[gs-cvs] rev 8847 - trunk/gs/doc
ray at ghostscript.com
ray at ghostscript.com
Wed Jul 16 22:51:19 PDT 2008
Author: ray
Date: 2008-07-16 22:51:19 -0700 (Wed, 16 Jul 2008)
New Revision: 8847
Modified:
trunk/gs/doc/Language.htm
trunk/gs/doc/Use.htm
Log:
Update documentation to describe multi-threaded rendering (NumRenderingThreads)
and improve the documentation about the clist/banding parameters and the effect
on performance. Addresses issues raised in bug 689668.
Modified: trunk/gs/doc/Language.htm
===================================================================
--- trunk/gs/doc/Language.htm 2008-07-17 02:34:01 UTC (rev 8846)
+++ trunk/gs/doc/Language.htm 2008-07-17 05:51:19 UTC (rev 8847)
@@ -63,6 +63,7 @@
<li><a href="#Unstable_filters">Unstable filters</a>
</ul>
<li><a href="#Device_parameters">Device parameters</a>
+<li><a href="#Banding_parameters">Banding parameters</a>
<li><a href="#User_parameters">User parameters</a>
<li><a href="#Miscellaneous_additions">Miscellaneous additions</a>
<ul>
@@ -1907,17 +1908,46 @@
<p>
It should be noted that calling <tt>setpagedevice</tt> with one of the above keys may reset the effects of any <b><tt>pdfmark</tt></b> commands up to that point. In particular this is true of HWResolution, a behavior that differs from Adobe Distiller.
-<p>
-For printers these are also defined:
+<a name="Banding_parameters"></a>
+<p><b>
+For raster printers and image format (jpeg*, tiff*, png* ...) devices these
+page device parameters are also defined:</b>
+<dl>
+<dt><b><tt>MaxBitmap <integer></tt></b>
+<dd>Maximum space for a full page raster image (bitmap) in memory.
+<p>This value includes the space for padding raster lines and for an array of
+pointers for each raster line, thus the <b><tt>MaxBitmap</tt></b> value to allow
+a given PageSize of a specific number of bits per pixel to be rendered in a
+full page buffer may be somewhat larger than the bitmap size alone.
+</dl>
<dl>
<dt><b><tt>BufferSpace <integer></tt></b>
-<dd>Buffer space for band lists, if the bitmap is too big to fit in memory.
+<dd>Size of the buffer space for band lists, if the full page raster image
+(bitmap) is larger than <b><tt>MaxBitmap</tt></b> (see above.)
+
+<p>The buffer space is used to collect display list (clist) commands for the
+bands and then to consolidate those commands when writing the clist to the
+selected BAND_LIST_STORAGE device (memory or file) set when Ghostscript is compiled.
+<p>If <b><tt>MaxBitmap</tt></b> (above) forces banding mode, and if <b><tt>BufferSpace</tt></b>
+is large enough, the display list (clist) will consist of a single band.
+<p>The <b><tt>BufferSpace</tt></b> will determine the size of the 'consolidation'
+buffer (above) even if the <b><tt>MaxBitmap</tt></b> value is low enough to force
+banding/clist mode.
</dl>
<dl>
-<dt><b><tt>MaxBitmap <integer></tt></b>
-<dd>Maximum space for a full bitmap in memory.
+<dt><b><tt>NumRenderingThreads <integer></tt></b>
+<dd>When the display list (clist) banding mode is being used, bands can be rendered
+in separate threads. The default value, 0, causes the rendering of bands to be
+done in the same thread as the parser and device driver. <b><tt>NumRenderingThreads</tt></b>
+of 1 or higher results in bands rendering in the specified number of 'background'
+threads.
+<p>The number of threads should generally be set to the number of available
+processor cores for best throughput.
+<p>Note that each thread will allocate a band buffer (size determined by the
+<b><tt>BufferSpace</tt></b> or <b><tt>BandBufferSpace</tt></b> values) in addition to
+the band buffer in the 'main' thread.
</dl>
<dl>
@@ -1928,7 +1958,7 @@
for page-oriented output devices;
on Unix systems <b><tt>%pipe%</tt></b><em>command</em> writes to a pipe.
(<b><tt>|</tt></b><em>command</em> also writes to a pipe, but is now
-deprecated.)
+deprecated). Also see the <b><tt>-o</tt></b> parameter.
<p>
Attempts to set this parameter if <tt><b>.LockSafetyParams</b></tt> is true
will signal an <tt><b>invalidaccess</b></tt> error.
@@ -1947,23 +1977,24 @@
<p>
The following parameters are for use only by very specialized applications
-that separate band construction from band rasterization. Improper use may
-cause unpredictable errors. In particular, if you only want to allocate
+that separate band construction from band rasterization. <b>Improper use may
+cause unpredictable errors.</b> In particular, if you only want to allocate
more memory for banding, to increase band size and improve performance, use
-the <b><tt>BufferSpace</tt></b> parameter, not
-<b><tt>BandBufferSpace</tt></b>.
+the <b><tt>BufferSpace</tt></b> parameter, not <b><tt>BandBufferSpace</tt></b>.
<dl>
<dt><b><tt>BandHeight <integer></tt></b>
<dd>The height of bands when banding. 0 means use the largest band height
-that will fit within the BandBufferSpace (or BufferSpace, if
-BandBufferSpace is not specified).
+that will fit within the <b><tt>BandBufferSpace</tt></b> (or <b><tt>BufferSpace</tt></b>,
+if <b><tt>BandBufferSpace</tt></b> is not specified). If <b><tt>BandHeight</tt></b>
+is larger than the number of lines that will fit in the buffer, opening the device will fail.
</dl>
<dl>
<dt><b><tt>BandWidth <integer></tt></b>
<dd>The width of bands in the rasterizing pass, in pixels. 0 means use the
-actual page width.
+actual page width. A BandWidth value smaller than the width of the page
+will be ignored, and the actual page width will be used instead.
</dl>
<dl>
Modified: trunk/gs/doc/Use.htm
===================================================================
--- trunk/gs/doc/Use.htm 2008-07-17 02:34:01 UTC (rev 8846)
+++ trunk/gs/doc/Use.htm 2008-07-17 05:51:19 UTC (rev 8847)
@@ -2743,6 +2743,21 @@
speedup by telling Ghostscript to use more memory.
<ul>
+<li>
+For raster printers and image format (jpeg*, tiff*, png* ...) devices,
+performance can be 'tuned' by adjusting some of the parameters related
+to banding (clist) options (refer to: <a href="Language.htm#Banding_parameters">
+Banding Parameters</a>).
+<p>In general, page buffer mode is faster than banded/clist mode (a full page
+buffer is used when <b><tt>-dMaxBitmap=#</tt></b> is large enough for the entire
+raster image) since there is no need to write, then interpret the clist data.
+<p>On a multi-core system where multiple threads can be dispatched to
+individual processors/cores, banding mode may provide higher performance
+since <b><tt>-dNumRenderingThreads=#</tt></b> can be used to take advantage of
+more than one CPU core when rendering the clist. The number of threads should
+generally be set to the number of available processor cores for best throughput.
+<p>In general, larger <b><tt>-dBufferSpace=#</tt></b> values provide
+slightly higher performance since the per-band overhead is reduced.
<li>
If you are using X Windows, setting the <b><tt>-dMaxBitmap=</tt></b>
@@ -2750,13 +2765,16 @@
dramatically improve performance on files that have a lot of bitmap images.
<li>
-If you are using Chinese, Japanese, or other fonts with very large character
-sets, adding the following sequence of switches before the first file name
-may dramatically improve performance at the cost of an additional 2-3 Mb of
-memory: <b><tt>-c 3000000 setvmthreshold -f</tt></b>. This
-can also be useful in processing large documents when using a high-level
-output device (like pdfwrite) that maintains significant internal state.
-In fact, the <a href="Language.htm#.setpdfwrite"><tt>.setpdfwrite</tt></a>
+<p>
+With some PDF files, or if you are using Chinese, Japanese, or other fonts with
+very large character sets, adding the following sequence of switches before the
+first file name may dramatically improve performance at the cost of an additional
+memory. For example, to allow use of 30Mb of extra RAM use:
+<p>
+ <b><tt>-c 30000000 setvmthreshold -f</tt></b>.
+<p>This can also be useful in processing large documents when using a
+high-level output device (like pdfwrite) that maintains significant internal
+state. In fact, the <a href="Language.htm#.setpdfwrite"><tt>.setpdfwrite</tt></a>
operator used by the ps2pdf script and others sets a vmthreshold value of
3 MB to account for this.
More information about the gs-cvs
mailing list