--- /i/Contribs/gdal/gdal_utilities.dox 2017-09-29 08:35:26.000000000 -0600
+++ /i/Contribs/gdal/gdal_utilities_rasterize.dox 2017-09-29 09:05:14.000000000 -0600
@@ -1054,13 +1054,18 @@
Note that on the fly reprojection of vector data to the coordinate system of the
raster data is only supported since GDAL 2.1.0.
-Since GDAL 1.8.0, the target GDAL file can be created by gdal_rasterize. Either
-the -tr or -ts option must be used in that case.
+Prior to GDAL 1.8.0, gdal_rasterize could only modify existing raster images.
+Since 1.8.0, it will create a new target raster image when any of the -of,
+-a_nodata, -init, -a_srs, -co, -te, -tr, -tap, -ts, or -ot options are used.
+The resolution or size must be specified using the -tr or -ts option for all new
+rasters. The target raster will be overwritten if it already exists and any of
+these creation-related options are used.
- -b band:
-
The band(s) to burn values into. Multiple -b arguments may be used to burn
-into a list of bands. The default is to burn into band 1.
+into a list of bands. The default is to burn into band 1. Not used when
+creating a new raster.
- -i:
-
Invert rasterization. Burn the fixed burn value, or the burn value associated
@@ -1165,8 +1170,10 @@
Any OGR supported readable datasource.
- dst_filename:
-
-The GDAL supported output file. Must support update mode access.
-Before GDAL 1.8.0, gdal_rasterize could not create new output files.
+The GDAL supported output file. Must support update mode access. As of GDAL
+1.8.0, this file will be created (or overwritten if it already exists) if the
+-of, -a_nodata, -init, -a_srs, -co, -te, -tr, -tap, -ts, or -ot options are
+used.
@@ -1190,6 +1197,14 @@
gdal_rasterize -a ROOF_H -where 'class="A"' -l footprints footprints.shp city_dem.tif
\endverbatim
+The following would burn all polygons from footprint.shp into a new 1000x1000
+rgb TIFF as the color red. Note that -b is not used; the order of the -burn
+options determines the bands of the output raster.
+
+\verbatim
+gdal_rasterize -burn 255 -burn 0 -burn 0 -ot Byte -ts 1000 1000 -l footprints footprints.shp mask.tif
+\endverbatim
+
\if man
\section gdal_rasterize_author AUTHORS
Frank Warmerdam