diff options
Diffstat (limited to 'doc/Drivers.htm')
| -rw-r--r-- | doc/Drivers.htm | 491 |
1 files changed, 243 insertions, 248 deletions
diff --git a/doc/Drivers.htm b/doc/Drivers.htm index 577564ba..c596d5a2 100644 --- a/doc/Drivers.htm +++ b/doc/Drivers.htm @@ -1,123 +1,111 @@ <!doctype html> -<html> +<html lang="en"> <head> -<meta charset="UTF-8"> -<meta name="viewport" content="width=device-width, initial-scale=1.0"> -<link href="https://fonts.googleapis.com/css?family=Source+Sans+Pro" rel="stylesheet"> -<link rel="shortcut icon" type="image/png" href="../../images/favicon.png"> -<title>The Interface between Ghostscript and Device Drivers</title> - <!-- Originally: drivers.txt --> -<link href="style.css" rel="stylesheet" type="text/css"> -<link href="gs-style.css" rel="stylesheet" type="text/css"> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta name="viewport" content="user-scalable=yes, initial-scale=1, width=device-width"> + <link href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:200,200i,300,300i,400,400i,600,600i,700,700i,900,900i" rel="stylesheet"> + <link rel="shortcut icon" href="images/favicon.svg"> + <title>The Interface between Ghostscript and Device Drivers</title> + <link href="default.css" rel="stylesheet" type="text/css"> </head> <body> + <header><div class="title"><a href="index.html"><h1 aria-label="title">Ghostscript documentation</h1><h2 aria-label="version"></h2></a></div><a href="Search.htm" aria-label="Search" id="searchSite"><div class="search"></div></a></header> + <main> + <article> + <div class="outer"> - <div class="header"> - <div class="row"> - <div class="col-lt-6 logo"><a href="https://www.ghostscript.com/"><img src="images/ghostscript_logo.png" width="108" height="119" alt=""></a></div> - <div class="col-6"><div class="row"><div class="artifexlogo"><a href="https://artifex.com" target="_blank"><img src="images/Artifex_logo.png" width="194" height="40" alt=""></a></div> - <div class="col-12"><div class="button button1"><a href="https://artifex.com/contact-us/" title="Contact Us" target="_blank">Contact Us</a></div> - <div class="button button2 hidden-xs"><a href="https://www.ghostscript.com/download.html" title="Download">Download</a></div></div></div> - </div> - </div> - </div> - - <div class="banner"> - <div class="row"> - <div class="col-12">The Interface between Ghostscript and Device Drivers</div> - </div> - </div> - - <div class="main"> - <div class="row"> - <div id="sidebar"> - <div class="sidebar-item"></div> - <div class="col-2 leftnav"> - <ul> - <li><a href="https://www.ghostscript.com/">Home</a></li> - <li><a href="https://www.ghostscript.com/license.html">Licensing</a></li> - <li><a href="https://www.ghostscript.com/releases.html">Releases</a></li> - <li><a href="https://www.ghostscript.com/documentation.html" title="Documentation">Documentation</a></li> - <li><a href="https://www.ghostscript.com/download.html" title="Download">Download</a></li> - <li><a href="https://www.ghostscript.com/performance.html" title="Performance">Performance</a></li> - <li><a href="http://jbig2dec.com/" title="jbig2dec">jbig2dec</a></li> - <li><a href="http://git.ghostscript.com/?p=ghostpdl.git;a=summary">Source</a></li> - <li><a href="http://bugs.ghostscript.com/">Bugs</a></li> - <li><a href="https://www.ghostscript.com/faq.html" title="FAQ">FAQ</a></li> - </ul> - </div> - </div> - <div class="col-10 page"> - + <div class="inner"> <!--START EDITING HERE--> -<!-- [1.2 begin table of contents] ========================================= --> +<h1>The Interface between Ghostscript and Device Drivers</h1> -<h2>Table of contents</h2> +<h2><a name="toc"></a>Table of contents</h2> -<blockquote> -<li><a href="#Adding_drivers">Adding a driver</a></li> -<li><a href="#KISS">Keeping things simple</a></li> -<li><a href="#Structure">Driver structure</a></li> -<ul> - <li><a href="#Structure_definition">Structure definition</a></li> - <li><a href="#Sophisticated">For sophisticated developers only</a></li> -</ul> -<li><a href="#coordinates_and_types">Coordinates and types</a></li> -<ul> - <li><a href="#Coordinate_system">Coordinate system</a></li> - <li><a href="#Color_definition">Color definition</a></li> -<ul> - <li><a href="#sep_and_linear_fields">Separable and linear fields</a></li> - <li><a href="#Changing_color_info_data">Changing color_info data</a></li> -</ul> -<li><a href="#Types">Types</a></li> -</ul> -<li><a href="#Coding_conventions">Coding conventions</a></li> -<ul> - <li><a href="#Allocating_storage">Allocating storage</a></li> - <li><a href="#Driver_instance_allocation">Driver instance allocation</a></li> -</ul> -<li><a href="#Printer_drivers">Printer drivers</a></li> -<li><a href="#Printer_drivers_mt">Printer drivers (Multi-threaded)</a></li> -<li><a href="#Driver_procedures">Driver procedures</a></li> -<ul> - <li><a href="#Life_cycle">Life cycle</a></li> - <li><a href="#Open_close">Open, close, sync, copy</a></li> - <li><a href="#Color_mapping">Color and alpha mapping</a></li> - <li><a href="#Pixel_level_drawing">Pixel-level drawing</a></li> -<ul> - <li><a href="#Bitmap_imaging">Bitmap imaging</a></li> - <li><a href="#Pixmap_imaging">Pixmap imaging</a></li> - <li><a href="#Compositing">Compositing</a></li> - [<a href="#S_spec">S</a>, <a href="#T_spec">T</a>, <a href="#F_spec">f</a>, - <a href="#Compositing_notes">Notes</a>] -</ul> - <li><a href="#Polygon_level_drawing">Polygon-level drawing</a></li> - <li><a href="#Linear_color_drawing">Linear color drawing</a></li> - <li><a href="#High_level_drawing">High-level drawing</a></li> -<ul> - <li><a href="#Paths">Paths</a></li> - <li><a href="#Images">Images</a> [<a href="#Images_notes">Notes</a>]</li> - <li><a href="#Text">Text</a> [<a href="#Text_notes">Notes</a>]</li> - <li><a href="#Unicode">Unicode support for high level (vector) devices</a></li> -</ul> - <li><a href="#Reading_bits_back">Reading bits back</a></li> - <li><a href="#Parameters">Parameters</a></li> -<ul> - <li><a href="#Default_CRD_parameters">Default color rendering dictionary (CRD) parameters</a></li> -</ul> - <li><a href="#External_fonts">External fonts</a></li> - <li><a href="#Page_devices">Page devices</a></li> - <li><a href="#Miscellaneous">Miscellaneous</a></li> -</ul> -<li><a href="#Tray">Tray selection</a></li> -<ul> - <li><a href="#LeadingEdge">Tray rotation and the LeadingEdge parameter</a></li> - <li><a href="#LeadingPage">Interaction between LeadingEdge and PageSize</a></li> +<ul class="toc"> + <li><a href="#Adding_drivers">Adding a driver</a></li> + <li><a href="#KISS">Keeping things simple</a></li> + <li><a href="#Structure">Driver structure</a></li> + <li> + <ul> + <li><a href="#Structure_definition">Structure definition</a></li> + <li><a href="#Sophisticated">For sophisticated developers only</a></li> + </ul> + </li> + <li><a href="#coordinates_and_types">Coordinates and types</a></li> + <li> + <ul> + <li><a href="#Coordinate_system">Coordinate system</a></li> + <li><a href="#Color_definition">Color definition</a></li> + <li> + <ul> + <li><a href="#sep_and_linear_fields">Separable and linear fields</a></li> + <li><a href="#Changing_color_info_data">Changing color_info data</a></li> + </ul> + </li> + <li><a href="#Types">Types</a></li> + </ul> + </li> + <li><a href="#Coding_conventions">Coding conventions</a></li> + <li> + <ul> + <li><a href="#Allocating_storage">Allocating storage</a></li> + <li><a href="#Driver_instance_allocation">Driver instance allocation</a></li> + </ul> + </li> + <li><a href="#Printer_drivers">Printer drivers</a></li> + <li><a href="#Printer_drivers_mt">Printer drivers (Multi-threaded)</a></li> + <li><a href="#Driver_procedures">Driver procedures</a></li> + <li> + <ul> + <li><a href="#Life_cycle">Life cycle</a></li> + <li><a href="#Open_close">Open, close, sync, copy</a></li> + <li><a href="#Color_mapping">Color and alpha mapping</a></li> + <li><a href="#Pixel_level_drawing">Pixel-level drawing</a></li> + <li> + <ul> + <li><a href="#Bitmap_imaging">Bitmap imaging</a></li> + <li><a href="#Pixmap_imaging">Pixmap imaging</a></li> + <li><a href="#Compositing">Compositing</a></li> + <li> + <ul> + <li>[<a href="#S_spec">S</a>, <a href="#T_spec">T</a>, <a href="#F_spec">f</a>, + <a href="#Compositing_notes">Notes</a>]</li> + </ul> + </li> + </ul> + </li> + <li><a href="#Polygon_level_drawing">Polygon-level drawing</a></li> + <li><a href="#Linear_color_drawing">Linear color drawing</a></li> + <li><a href="#High_level_drawing">High-level drawing</a></li> + <li> + <ul> + <li><a href="#Paths">Paths</a></li> + <li><a href="#Images">Images</a> [<a href="#Images_notes">Notes</a>]</li> + <li><a href="#Text">Text</a> [<a href="#Text_notes">Notes</a>]</li> + <li><a href="#Unicode">Unicode support for high level (vector) devices</a></li> + </ul> + </li> + <li><a href="#Reading_bits_back">Reading bits back</a></li> + <li><a href="#Parameters">Parameters</a></li> + <li> + <ul> + <li><a href="#Default_CRD_parameters">Default color rendering dictionary (CRD) parameters</a></li> + </ul> + </li> + <li><a href="#External_fonts">External fonts</a></li> + <li><a href="#Page_devices">Page devices</a></li> + <li><a href="#Miscellaneous">Miscellaneous</a></li> + </ul> + </li> + <li><a href="#Tray">Tray selection</a></li> + <li> + <ul> + <li><a href="#LeadingEdge">Tray rotation and the LeadingEdge parameter</a></li> + <li><a href="#LeadingPage">Interaction between LeadingEdge and PageSize</a></li> + </ul> + </li> </ul> -</blockquote> <!-- [1.2 end table of contents] =========================================== --> @@ -148,7 +136,7 @@ need do is edit <code>contrib.mak</code> in two places.</p> <li>The list of devices, in the section headed "Catalog". Add <code>smurf</code> to the list.</li> -<li>The section headed "Device drivers".</li> +<li>The section headed "Device drivers". <p> Suppose the files containing the smurf driver are called @@ -202,6 +190,7 @@ or</p> <p> Note that the space before the :, and the explicit compilation rules for the .c files, are required for portability,</p> +</li> </ol> <hr> @@ -356,19 +345,20 @@ structure for ordinary drivers are:</p> <blockquote><table> <tr valign="top"> <td><code>const char *dname;</code></td> - <td> </td> + <td>The device name</td></tr> + <tr valign="top"> <td><code>bool is_open;</code></td> - <td> </td> + <td>True if device has been opened</td></tr> <tr valign="top"> <td><code>gx_device_color_info color_info;</code></td> - <td> </td> + <td>Color information</td></tr> <tr valign="top"> <td><code>int width;</code></td> - <td> </td> + <td>Width in pixels</td></tr> <tr valign="top"> <td><code>int height;</code></td> - <td> </td> + <td>Height in pixels</td></tr> </table></blockquote> @@ -400,6 +390,7 @@ structure, or to add procedures, you must change the following places:</p> (probably just adding <code>NULL</code> procedure entries if the new procedures don't produce output).</li> <li>These devices that must have complete (non-defaulted) procedure vectors:</li> +<li> <ul> <li>The null device in <a href="../base/gdevnfwd.c">gdevnfwd.c</a>.</li> <li>The command list "device" in <a href="../base/gxclist.c">gxclist.c</a>. @@ -407,6 +398,7 @@ structure, or to add procedures, you must change the following places:</p> <li>The "memory" devices in <a href="../base/gdevmem.h">gdevmem.h</a> and <code>gdevm*.c</code>.</li> </ul> +</li> <li>The clip list accumulation "device" in <a href="../base/gxacpath.c">gxacpath.c</a>.</li> <li>The clipping "devices" <a href="../base/gxclip.c">gxclip.c</a>, @@ -792,7 +784,7 @@ gets <code>gx_color_index</code> values from the device's procedures. If the <code>separable_and_linear</code> field in the device's <code>color_info</code> structure is not set to <code>GX_CINFO_SEP_LIN</code> then Ghostscript does not do -any computations with <code>gx_color_index</code> values.</dd> +any computations with <code>gx_color_index</code> values. <p> The special @@ -833,6 +825,9 @@ For Microsoft and the MSVC compiler, <code>GX_COLOR_INDEX_TYPE</code> will be set to <code>unsigned _int64</code> if <code>USE_LARGE_COLOR_INDEX</code> is set to 1 either on the make command line or by editing the definition in <a href="../psi/msvc32.mak">msvc32.mak</a> </p> + + </dd> + </dl> <dl> @@ -854,7 +849,7 @@ filling a region (rectangle). <code>gx_tile_bitmap</code> is an older, deprecated type lacking <code>shift</code> and <code>rep_shift</code>; <code>gx_strip_bitmap</code> has superseded it, and should be -used in new code. Here is a copy of the relevant part of the file:</dd> +used in new code. Here is a copy of the relevant part of the file: <blockquote> <pre> @@ -927,6 +922,9 @@ typedef struct gx_strip_bitmap_s { int num_planes; } gx_strip_bitmap;</pre> </blockquote> + +</dd> + </dl> <hr> @@ -1369,12 +1367,13 @@ always call <code>gs_opendevice</code> instead.</dd> (nominally 1/72 inch per unit) to device coordinates. The default procedure computes this from width, height, and [<code>xy</code>]<code>_pixels_per_inch</code> on the assumption that -the origin is in the upper left corner, that is</dd> +the origin is in the upper left corner, that is <blockquote> <code>xx</code> = <code>x_pixels_per_inch</code>/72, <code>xy</code> = 0,<br> <code>yx = 0, yy = -y_pixels_per_inch</code>/72,<br> <code>tx = 0, ty = height</code>. </blockquote> +</dd> </dl> <dl> @@ -1484,7 +1483,7 @@ the specified name is not a colorant for the device. A value of 0 to of the given name. A value of <code>GX_DEVICE_COLOR_MAX_COMPONENTS</code> indicates that the given name is a valid colorant name for the device but the colorant is not currently being used. This is used for implementing names -which are in SeparationColorNames but not in SeparationOrder.</dd> +which are in SeparationColorNames but not in SeparationOrder. <p> The default procedure returns results based upon process color model @@ -1492,6 +1491,7 @@ of DeviceGray, DeviceRGB, or DeviceCMYK selected by <code>color_info.num_components</code>. This procedure must be defined if another process color model is used by the device or spot colors are supported by the device.</p> +</dd> </dl> <dl> @@ -1501,7 +1501,7 @@ gx_device * dev, const gx_device ** tdev)</code> <b><em>[OPTIONAL]</em device to pass to them. These procedures are used to translate values in either Gray, RGB, or CMYK color spaces into device colorant values. A separate procedure is not required for the DeviceN and Separation color -spaces since these already represent device colorants.</dd> +spaces since these already represent device colorants. <p>In many cases, the device returned in <code>tdev</code> will be the same as <code>dev</code>, but the caller should not rely on this. For @@ -1520,6 +1520,7 @@ procedure must be defined if another process color model is used by the device or spot colors are to be supported. All these procedures take a <code>gx_device</code> pointer; these should be called with the value returned in <code>tdev</code> NOT the initial value of <code>dev</code>.</p> +</dd> </dl> <dl> @@ -1530,11 +1531,12 @@ value. The range of legal values of the arguments is 0 to <code>gx_max_color_value</code>. The default procedure packs bits into a <code>gx_color_index</code> value based upon the values in <code>color_info.depth</code> and -<code>color_info.num_components</code>.</dd> +<code>color_info.num_components</code>. <p> Note that the <code>encode_color</code> procedure must not return <code>gx_no_color_index</code> (all 1s).</p> +</dd> </dl> <dl> @@ -1586,11 +1588,12 @@ the point <em>(x,y)</em> is included in the rectangle, as are <b><em>not</em></b> <em>(x+w,y)</em>, <em>(x,y+h)</em>, or <em>(x+w,y+h)</em>. If <code>width</code> <= 0 or height <= 0, <code>fill_rectangle</code> should return 0 -without drawing anything.</dd> +without drawing anything. <p> Note that <code>fill_rectangle</code> is the only non-optional procedure in the driver interface.</p> +</dd> </dl> <h4><a name="Bitmap_imaging"></a>Bitmap imaging</h4> @@ -1621,13 +1624,14 @@ pixel is unaffected if the image bit is 0 or 1 respectively. If <code>id</code> is different from <code>gx_no_bitmap_id</code>, it identifies the bitmap contents unambiguously; a call with the same <code>id</code> will always have the same <code>data</code>, -<code>raster</code>, and data contents.</dd> +<code>raster</code>, and data contents. <p> This operation, with <code>color0</code> = <code>gx_no_color_index</code>, is the workhorse for text display in Ghostscript, so implementing it efficiently is very important.</p> +</dd> </dl> <dl> @@ -1645,7 +1649,7 @@ the device coordinate system. (Note that this is backwards from the PostScript definition of halftone phase.) <code>phase_x</code> and <code>phase_y</code> are guaranteed to be in the range <em>[0..</em><code>tile->width</code><em>)</em> and -<em>[0..</em><code>tile->height</code><em>)</em> respectively.</dd> +<em>[0..</em><code>tile->height</code><em>)</em> respectively. <p> If <code>color0</code> and <code>color1</code> are both @@ -1659,6 +1663,7 @@ implementing it efficiently for solid tiles (that is, where either <code>gx_no_color_index</code>, for colored halftones, or neither one is <code>gx_no_color_index</code>, for monochrome halftones) is very important.</p> +</dd> </dl> <h4><a name="Pixmap_imaging"></a>Pixmap imaging</h4> @@ -1752,41 +1757,44 @@ Given a 2d source block of pixels (supplied as scanline data), this function transforms that data, maps it through the supplied colour lookup function, clips it, and plots it into the device. -<p>In all calls to this function a negative return value indicates an error. +<p>In all calls to this function a negative return value indicates an error.</p> <p>Called first with the <code>transform_pixel_region_init</code> reason code, this prepares for subsequent calls to scale a region as described in the <code>data.u.init</code> structure. A pointer to any state required for this should be written into <code>data.state</code>, and the caller must -pass that in to subsequent calls. +pass that in to subsequent calls.</p> <p>Subsequently this will be called with <code>transform_pixel_region_data_needed</code>. The function will then check to see if the next scanline of data will be trivially clipped away. If so, then it will return zero to indicate that it is not needed. This can help the caller to avoid unnecessary processing. A positive return value -indicates that the line is required. +indicates that the line is required.</p> <p>For every line where the data is required, the function will be called with <code>transform_pixel_region_process_data</code>. The function will then read and process the line from <code>data.u.process_data</code>. The data in the buffer is packed 8 bit values, which will be fed into the supplied <code>cmapper</code> to set the device color as required. This is then written -into the device. +into the device.</p> <p>Once all the scanlines have been fed through calls to <code>transform_pixel_region_data_needed</code> and <code>transform_pixel_region_process_data</code>, a final call with <code>transform_pixel_region_end</code> -is made that frees the state. +is made that frees the state.</p> <p>The default implementation of this device function will generally break the pixel data down into calls to <code>fill_rectangle</code>, though in some cases (notably the portrait 8 bit per component output case), a faster route through <code>copy_color</code> -can be used. +can be used.</p> <p>Memory devices offer a version of this device function that can accelerate direct -plotting to the memory array. +plotting to the memory array.</p> <p>NOTE: Currently the clipping rectangle is not honoured for skewed (not portrait or landscape) transformations. This is allowed for in the callers. +</p> +</dd> + </dl> <h4><a name="Compositing"></a>Compositing</h4> @@ -1804,7 +1812,7 @@ gx_bitmap_id id, int x, int y, int width, int height, gx_color_index color, int depth)</code> <b><em>[OPTIONAL]</em></b></dt> <dd>This procedure is somewhat misnamed: it was added to the interface -before we really understood alpha channel and compositing.</dd> +before we really understood alpha channel and compositing. <p> Fill a given region with a given color modified by an individual alpha @@ -1820,6 +1828,7 @@ rule.</p> with an 8 bit depth. In addition they should accept either 2 or 4 if the corresponding <code>get_alpha_bits</code> procedure returns either of those values.</p> +</dd> </dl> <dl> @@ -1846,7 +1855,7 @@ it. Accordingly, the caller must watch the return values from this function to understand if a new device has been created to which future calls should be made. <p> -Devices will normally implement this in one of the following standard ways:</dd> +Devices will normally implement this in one of the following standard ways: <ul> <li>Devices that don't do any imaging and don't forward any imaging @@ -1907,6 +1916,7 @@ Closing a compositor frees all of its storage, including the compositor itself. However, since the <code>composite</code> call may return the same device, clients must check for this case, and only call the close procedure if a separate device was created.</p> +</dd> </dl> <h3><a name="Polygon_level_drawing"></a>Polygon-level drawing</h3> @@ -1967,7 +1977,9 @@ fixed fx0, fixed fy0, fixed fx1, fixed fy1, const gx_drawing_color *pdcolor, gs_logical_operation_t lop)</code> <b><em>[OPTIONAL]</em></b></dt> <dd>Draw a one-pixel-wide line from <em>(fx0,fy0)</em> to -<em>(fx1,fy1)</em>.</dd> +<em>(fx1,fy1)</em>.</dd></dl> + +<dl><dt></dt><dd> <h3><a name="Linear_color_drawing"></a>Linear color drawing</h3> @@ -1983,8 +1995,9 @@ or uses a non-separable or a non-linear color model.</p> const gs_fixed_point *p0, const gs_fixed_point *p1, const gs_fixed_point *p2, const frac31 *c0, const frac31 *c1, const frac31 *c2) -</code></dt> -<b><em>[OPTIONAL]</em></b> +</code> +<b><em>[OPTIONAL]</em></b></dt> + <dd>This function is the highest level one within the linear color function group. It fills a triangle with a linearly varying color. Arguments specify 3 points in the device space - vertices of a triangle, and their colors. @@ -2044,8 +2057,8 @@ in <code>gdevddrw.c</code> for sample code.</dd> const gs_fixed_point *p2, const gs_fixed_point *p3, const frac31 *c0, const frac31 *c1, const frac31 *c2, const frac31 *c2) -</code></dt> -<b><em>[OPTIONAL]</em></b> +</code><b><em>[OPTIONAL]</em></b></dt> + <dd>This function is a lower level one within the linear color function group. The default implementation of <code> fill_linear_color_triangle </code> calls this function 1-2 times per triangle. Besides that, @@ -2065,7 +2078,7 @@ All those important notes are applicable here.</dd> <dd> Sample code may be found in in <code>gxdtfill.h</code>; be aware it's rather complicated. A linear color function is generated from it as <code> gx_fill_trapezoid_ns_lc </code> -with the following template parameters :</dd> +with the following template parameters : <pre> #define LINEAR_COLOR 1 @@ -2080,7 +2093,7 @@ with the following template parameters :</dd> <p>See <code>check_gradient_overflow</code> (defined in in <code>gdevddrw.c</code>), as an example of an area that can't be painted in a single action due to 64-bits fixed overflows.</p> - +</dd> </dl> <dl> @@ -2153,32 +2166,32 @@ consult the source code, specifically:</p> <blockquote><table> <tr valign="top"> <th align="left">Header</th> - <th> </th> + <th align="left">Defines</th></tr> <tr valign="top"> <td><a href="../base/gxpaint.h">gxpaint.h</a></td> - <td> </td> + <td><code>gx_fill_params</code>, <code>gx_stroke_params</code></td></tr> <tr valign="top"> <td><a href="../base/gxfixed.h">gxfixed.h</a></td> - <td> </td> + <td><code>fixed</code>, <code>gs_fixed_point</code> (used by <code>gx_*_params</code>)</td></tr> <tr valign="top"> <td><a href="../base/gxgstate.h">gxgstate.h</a></td> - <td> </td> + <td><code>gs_imager_state</code> (used by <code>gx_*_params</code>)</td></tr> <tr valign="top"> <td><a href="../base/gxline.h">gxline.h</a></td> - <td> </td> + <td><code>gx_line_params</code> (used by <code>gs_imager_state</code>)</td></tr> <tr valign="top"> <td><a href="../base/gslparam.h">gslparam.h</a></td> - <td> </td> + <td>line cap/join values (used by <code>gx_line_params</code>)</td></tr> <tr valign="top"> <td><a href="../base/gxmatrix.h">gxmatrix.h</a></td> - <td> </td> + <td><code>gs_matrix_fixed</code> (used by <code>gs_imager_state</code>)</td></tr> <tr valign="top"> <td><a href="../base/gspath.h">gspath.h</a>, <a href="../base/gxpath.h">gxpath.h</a>, <a href="../base/gzpath.h">gzpath.h</a></td> - <td> </td> + <td><code>gx_path</code></td></tr> <tr valign="top"> <td><a href="../base/gxcpath.h">gxcpath.h</a>, <a href="../base/gzcpath.h">gzcpath.h</a></td> - <td> </td> + <td><code>gx_clip_path</code></td></tr> </table></blockquote> @@ -2236,36 +2249,36 @@ with the given color and logical operation. The clip path pointer may be command is as below.</dd> </dl> -<h5><a name="F_spec"></a>The function specification f</h5> +<h4><a name="F_spec"></a>The function specification f</h4> <p> "Command" indicates the raster operation and transparency as follows:</p> <blockquote><table> <tr valign="bottom"> - <th colspan ="3">Bits</th> + <th colspan ="2">Bits</th> </tr> <tr valign="top"> <td>7-0</td> - <td> </td> + <td>raster op</td></tr> <tr valign="top"> <td>8</td> - <td> </td> + <td>0 if source opaque, 1 if source transparent</td></tr> <tr valign="top"> <td>9</td> - <td> </td> + <td>0 if texture opaque, 1 if texture transparent</td></tr> <tr valign="top"> <td>10</td> - <td> </td> + <td>1 if pdf transparency is in use, 0 otherwise. This makes no difference to the rendering, but forces the raster operation to be considered non-idempotent by internal routines.</td></tr> <tr valign="top"> <td>11</td> - <td> </td> + <td>1 if the target of this operation is a specific plane, rather than all planes. The plane in question is given by bits 13 upwards. This is only used by the planar device.</td></tr> <tr valign="top"> <td>12-</td> - <td> </td> + <td>If bit 11 = 1, then bits 12 upwards give the plane number to operate on. Otherwise, should be set to 0.</td></tr> </table></blockquote> @@ -2282,67 +2295,67 @@ possible 2×2×2 input values as follows:</p> <blockquote><table> <tr valign="bottom"> <th>Bit</th> - <th> </th> + <th>Texture</th> - <th> </th> + <th>Source</th> - <th> </th> + <th>Destination</th></tr> <tr valign="top"> <td align="center">7</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">1</td></tr> <tr valign="top"> <td align="center">6</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">0</td></tr> <tr valign="top"> <td align="center">5</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">1</td></tr> <tr valign="top"> <td align="center">4</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">0</td></tr> <tr valign="top"> <td align="center">3</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">1</td></tr> <tr valign="top"> <td align="center">2</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">1</td> - <td> </td> + <td align="center">0</td></tr> <tr valign="top"> <td align="center">1</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">1</td></tr> <tr valign="top"> <td align="center">0</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">0</td> - <td> </td> + <td align="center">0</td></tr> </table></blockquote> @@ -2532,11 +2545,11 @@ gx_image_enum_common_t **pinfo)</code> <b><em>[OPTIONAL]</em></b></dt> <code>image_plane_data</code> function supplied in the returned image enumerator will follow, and then a call of <code>end_image</code>. The parameters of <code>begin_typed_image</code> -are as follows:</dd> +are as follows: <blockquote><table> -<tr valign="top"> <td><code>pis</code></td> - <td> </td> +<tr valign="top"><td><code>pis</code></td> + <td>pointer to an imager state. The only relevant elements of the imager state are the CTM (coordinate transformation matrix), the logical operation (<code>RasterOp</code> or @@ -2544,34 +2557,34 @@ are as follows:</dd> mask images, if <code>pmat</code> is not NULL and the color is pure, <code>pis</code> may be NULL.</td></tr> <tr valign="top"> <td><code>pmat</code></td> - <td> </td> + <td>pointer to a <code>gs_matrix</code> structure that defines the image transformation matrix. If <code>pis</code> is non-NULL, and <code>pmat</code> is NULL, then the <code>ctm</code> from <code>pis</code> should be used.</td></tr> <tr valign="top"> <td><code>pim</code></td> - <td> </td> + <td>pointer to the <code>gs_image_t</code> structure that defines the image parameters</td></tr> <tr valign="top"> <td><code>prect</code></td> - <td> </td> + <td>if not <code>NULL</code>, defines a subrectangle of the image; only the data for this subrectangle will be passed to <code>image_plane_data</code>, and only this subrectangle should be drawn</td></tr> <tr valign="top"> <td><code>pdcolor</code></td> - <td> </td> + <td>defines a drawing color, only needed for masks or if <code>CombineWithColor</code> is true</td></tr> <tr valign="top"> <td><code>pcpath</code></td> - <td> </td> + <td>if not <code>NULL</code>, defines an optional clipping path</td></tr> <tr valign="top"> <td><code>memory</code></td> - <td> </td> + <td>defines the allocator to be used for allocating bookkeeping information</td></tr> <tr valign="top"> <td><code>pinfo</code></td> - <td> </td> + <td>the implementation should return a pointer to its state structure here</td></tr> </table></blockquote> @@ -2593,6 +2606,7 @@ is called.</p> <code>begin_typed_image</code> returns 0 normally, or 1 if the image does not need any data. In the latter case, <code>begin_typed_image</code> does not allocate an enumeration structure.</p> +</dd> </dl> <p> @@ -2611,7 +2625,7 @@ gx_image_enum_common_t *info, const gx_image_plane_t *planes, int height)</code></dt> <dd>This call provides more of the image source data: specifically, <code>height</code> rows, with <code>Width</code> pixels supplied for -each row.</dd> +each row. <p> The data for each row are packed big-endian within each byte, as for @@ -2665,7 +2679,7 @@ arguments, does not require the data to be aligned in any way.</p> <p> Note that for some image types, different planes may have different numbers of bits per pixel, as defined in the <code>plane_depths</code> array.</p> - +</dd> </dl> <dl> @@ -2711,7 +2725,7 @@ gs_font *font, const gx_clip_path *pcpath, gs_text_enum_t **ppte)</code> <b><em>[OPTIONAL]</em></b></dt> -<p></p><dd> +<dd><p></p> Begin processing text, by creating a state structure and storing it in <code>*ppte</code>. The parameters of <code>text_begin</code> are as follows:</dd> @@ -2719,26 +2733,26 @@ follows:</dd> <blockquote><table> <tr valign="top"> <td><code>dev</code></td> - <td> </td> + <td>The usual pointer to the device.</td></tr> <tr valign="top"> <td><code>pis</code></td> - <td> </td> + <td>A pointer to an imager state. All elements may be relevant, depending on how the text is rendered. </td></tr> <tr valign="top"> <td><code>text</code></td> - <td> </td> + <td>A pointer to the structure that defines the text operation and parameters. See <a href="../base/gstext.h">gstext.h</a> for details.</td></tr> <tr valign="top"> <td><code>font</code></td> - <td> </td> + <td>Defines the font for drawing.</td></tr> <tr valign="top"> <td><code>pcpath</code></td> - <td> </td> + <td>If not <code>NULL</code>, defines an optional clipping path. Only relevant if the text operation includes <code>TEXT_DO_DRAW</code>.</td></tr> <tr valign="top"> <td><code>ppte</code></td> - <td> </td> + <td>The implementation should return a pointer to its state structure here.</td></tr> </table></blockquote> @@ -2787,9 +2801,9 @@ procedures, which in turn call the procedures in the text enumerator.</p> <dl> <dt><code>int gs_text_process(gs_text_enum_t *pte)</code></dt> -<p><dd>Continue processing text. This procedure may return 0 or a negative +<dd><p></p>Continue processing text. This procedure may return 0 or a negative error code as usual, or one of the following values (see -<a href="../base/gstext.h">gstext.h</a> for details).</dd></p> +<a href="../base/gstext.h">gstext.h</a> for details). <blockquote><table> <tr valign="top"> <td><code>TEXT_PROCESS_RENDER</code></td> @@ -2800,14 +2814,15 @@ error code as usual, or one of the following values (see <td>The client has asked to intervene between characters. This is used for <code>cshow</code> and <code>kshow</code>.</td></tr> </table></blockquote> +</dd> </dl> <dl> <dt><code>int gs_text_release(gs_gstate * pgs, gs_text_enum_t *pte, -client_name_t cname)</code></dt><p> <dd>Finish processing text and release +client_name_t cname)</code></dt><dd><p></p>Finish processing text and release all associated structures. Clients must call this procedure after <code>gs_text_process</code> returns 0 or an error, and may call it at -any time.</dd></p> +any time.</dd> </dl> <p> @@ -2853,22 +2868,22 @@ if the glyph can't be translated to Unicode.</p> <dt><code>int (*get_bits_rectangle)(gx_device *dev, const gs_int_rect *prect, gs_get_bits_params_t *params)</code> <b><em>[OPTIONAL]</em></b></dt> -<p><dd> +<dd> Read a rectangle of bits back from the device. The <code>params</code> -structure consists of:</dd></p> +structure consists of:<p></p> <table> <tr valign="top"> <td><code>options</code></td> - <td> </td> + <td>the allowable formats for returning the data</td></tr> <tr valign="top"> <td><code>data[32]</code></td> - <td> </td> + <td>pointers to the returned data</td></tr> <tr valign="top"> <td><code>x_offset</code></td> - <td> </td> + <td>the X offset of the first returned pixel in data</td></tr> <tr valign="top"> <td><code>raster</code></td> - <td> </td> + <td>the distance between scan lines in the returned data</td></tr> </table> @@ -2878,7 +2893,11 @@ willing to accept. (If the client has more flexibility, the implementation may be able to return the data more efficiently, by avoiding representation conversions.) The options are divided into groups.</p> -<blockquote><dl> +</dd> +</dl> + +<blockquote> +<dl> <dt><b><em>alignment</em></b></dt> <dd>Specifies whether the returned data must be aligned in the normal manner for bitmaps, or whether unaligned data are acceptable.</dd> @@ -2923,7 +2942,9 @@ the standard color space. (Native device pixels use <dd>Specifies whether alpha channel information should be returned as the first component, the last component, or not at all. Note that for devices that have no alpha capability, the returned alpha values will be all 1s. -</dd></dl></blockquote> +</dd></dl> + +</blockquote> <p> The client may set more than one option in each of the above groups; the @@ -3359,7 +3380,7 @@ non-rotated case.</li> <hr> <p> -<small>Copyright © 2000-2021 Artifex Software, Inc. All rights reserved.</small> +<small>Copyright © 2000-2022 Artifex Software, Inc. All rights reserved.</small> <p> This software is provided AS-IS with no warranty, either express or @@ -3372,41 +3393,15 @@ or contact Artifex Software, Inc., 1305 Grant Avenue - Suite 200, Novato, CA 94945, U.S.A., +1(415)492-9861, for further information. <p> -<small>Ghostscript version 9.55.0, 27 September 2021 +<small>Ghostscript version 9.56.0, 29 March 2022 <!-- [3.0 end visible trailer] ============================================= --> - <!--FINISH EDITING HERE--> - - </div> - </div> - </div> - - <div class="footer"> - <div class="row"> - <div class="col-7 footleft"> - <ul> - <li><a href="https://artifex.com/contact-us/" target="blank">CONTACT US</a></li> - <li><a href="https://artifex.com/about-us/" target="blank">ABOUT</a></li> - <li><a href="https://ghostscript.com/security.html">SECURITY</a></li> - </ul> - </div> - <div class="col-1 footcenter"> - <ul> - <li><a href="https://artifex.com/support/" target="blank">SUPPORT</a></li> - <li><a href="https://artifex.com/blog/artifex/" target="blank">BLOG</a></li> - <li><a href="https://artifex.com/privacy-policy/" target="blank">PRIVACY</a></li> - </ul> - </div> - <div class="col-ft-3 footright"><img src="images/Artifex_logo.png" width="194" height="40" alt=""/> <br> - © Copyright 2019-2021 Artifex Software, Inc. <br> - All rights reserved. - </div> - </div> - </div> - - <script src="http://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script> - <script src="index.js"></script> + </div><!-- close inner --> + </div><!-- close outer --> + </article> + </main> + <script src="site.js"></script> </body> </html> |