1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<title>The interface between Ghostscript and device drivers</title> 5<!-- $Id: Drivers.htm,v 1.58 2005/10/20 19:46:23 ray Exp $ --> 6<!-- Originally: drivers.txt --> 7<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 8</head> 9 10<body> 11<!-- [1.0 begin visible header] ============================================ --> 12 13<!-- [1.1 begin headline] ================================================== --> 14 15<h1>The interface between Ghostscript and device drivers</h1> 16 17<!-- [1.1 end headline] ==================================================== --> 18 19<!-- [1.2 begin table of contents] ========================================= --> 20 21<h2>Table of contents</h2> 22 23<blockquote><ul> 24<li><a href="#Adding_drivers">Adding a driver</a> 25<li><a href="#KISS">Keeping things simple</a> 26<li><a href="#Structure">Driver structure</a> 27<ul> 28<li><a href="#Structure_definition">Structure definition</a> 29<li><a href="#Sophisticated">For sophisticated developers only</a> 30</ul> 31<li><a href="#coordinates_and_types">Coordinates and types</a> 32<ul> 33<li><a href="#Coordinate_system">Coordinate system</a> 34<li><a href="#Color_definition">Color definition</a> 35<ul> 36<li><a href="#sep_and_linear_fields">Separable and linear fields</a> 37<li><a href="#Changing_color_info_data">Changing color_info data</a> 38</ul> 39<li><a href="#Types">Types</a> 40</ul> 41<li><a href="#Coding_conventions">Coding conventions</a> 42<ul> 43<li><a href="#Allocating_storage">Allocating storage</a> 44<li><a href="#Driver_instance_allocation">Driver instance allocation</a> 45</ul> 46<li><a href="#Printer_drivers">Printer drivers</a> 47<li><a href="#Driver_procedures">Driver procedures</a> 48<ul> 49<li><a href="#Life_cycle">Life cycle</a> 50<li><a href="#Open_close">Open, close, sync, copy</a> 51<li><a href="#Color_mapping">Color and alpha mapping</a> 52<li><a href="#Pixel_level_drawing">Pixel-level drawing</a> 53<ul> 54<li><a href="#Bitmap_imaging">Bitmap imaging</a> 55<li><a href="#Pixmap_imaging">Pixmap imaging</a> 56<li><a href="#Compositing">Compositing</a> 57 [<a href="#S_spec">S</a>, <a href="#T_spec">T</a>, <a href="#F_spec">f</a>, 58 <a href="#Compositing_notes">Notes</a>] 59</ul> 60<li><a href="#Polygon_level_drawing">Polygon-level drawing</a> 61<li><a href="#Linear_color_drawing">Linear color drawing</a> 62<li><a href="#High_level_drawing">High-level drawing</a> 63<ul> 64<li><a href="#Paths">Paths</a> 65<li><a href="#Images">Images</a> [<a href="#Images_notes">Notes</a>] 66<li><a href="#Text">Text</a> [<a href="#Text_notes">Notes</a>] 67<li><a href="#Unicode">Unicode support for high level devices</a> 68</ul> 69<li><a href="#Reading_bits_back">Reading bits back</a> 70<li><a href="#Parameters">Parameters</a> 71<ul> 72<li><a href="#Default_CRD_parameters">Default color rendering dictionary (CRD) parameters</a> 73</ul> 74<li><a href="#External_fonts">External fonts</a> 75<li><a href="#Page_devices">Page devices</a> 76<li><a href="#Miscellaneous">Miscellaneous</a> 77</ul> 78</ul></blockquote> 79 80<!-- [1.2 end table of contents] =========================================== --> 81 82<!-- [1.3 begin hint] ====================================================== --> 83 84<p>For other information, see the <a href="Readme.htm">Ghostscript 85overview</a> and the documentation on <a href="Make.htm">how to build 86Ghostscript</a>. 87 88<!-- [1.3 end hint] ======================================================== --> 89 90<hr> 91 92<!-- [1.0 end visible header] ============================================== --> 93 94<!-- [2.0 begin contents] ================================================== --> 95 96<h2><a name="Adding_drivers"></a>Adding a driver</h2> 97 98<p> 99To add a driver to Ghostscript, first pick a name for your device, say 100"<b><tt>smurf</tt></b>". (Device names must be 1 to 8 characters, begin 101with a letter, and consist only of letters, digits, and underscores. Case 102is significant: all current device names are lower case.) Then all you 103need do is edit <b><tt>contrib.mak</tt></b> in two places. 104 105<ol> 106<li>The list of devices, in the section headed "Catalog". Add 107<b><tt>smurf</tt></b> to the list. 108 109<li>The section headed "Device drivers". 110 111<p> 112Suppose the files containing the smurf driver are called 113"<b><tt>joe</tt></b>" and "<b><tt>fred</tt></b>". Then you should add the 114following lines: 115 116<blockquote> 117<pre># ------ The SMURF device ------ # 118 119smurf_=$(GLOBJ)joe.$(OBJ) $(GLOBJ)fred.$(OBJ) 120$(DD)smurf.dev: $(smurf_) 121 $(SETDEV) $(DD)smurf $(smurf_) 122 123$(GLOBJ)joe.$(OBJ) : $(GLSRC)joe.c 124 $(GLCC) $(GLO_)joe.$(OBJ) $(C_) $(GLSRC)joe.c 125 126$(GLOBJ)fred.$(OBJ) : $(GLSRC)fred.c 127 $(GLCC) $(GLO_)fred.$(OBJ) $(C_) $(GLSRC)fred.c</pre> 128</blockquote> 129 130<p> 131and whatever <b><tt>joe.c</tt></b> and <b><tt>fred.c</tt></b> depend on. 132If the smurf driver also needs special libraries, for instance a library 133named "<b><tt>gorf</tt></b>", then the entry should look like this: 134 135<blockquote> 136<pre>$(DD)smurf.dev : $(smurf_) 137 $(SETDEV) $(DD)smurf $(smurf_) 138 $(ADDMOD) $(DD)smurf -lib gorf</pre> 139</blockquote> 140 141<p> 142If, as will usually be the case, your driver is a printer driver (as 143<a href="#Printer_drivers">discussed below</a>), the device entry should 144look like this: 145 146<blockquote> 147<pre>$(DD)smurf.dev : $(smurf_) $(GLD)page.dev 148 $(SETPDEV) $(DD)smurf $(smurf_)</pre> 149</blockquote> 150 151<p> 152or 153 154<blockquote> 155<pre>$(DD)smurf.dev : $(smurf_) $(GLD)page.dev 156 $(SETPDEV) $(DD)smurf $(smurf_) 157 $(ADDMOD) $(DD)smurf -lib gorf</pre> 158</blockquote> 159 160<p> 161Note that the space before the :, and the explicit compilation rules for the 162.c files, are required for portability, 163</ol> 164 165<hr> 166 167<h2><a name="KISS"></a>Keeping things simple</h2> 168 169<p> 170If you want to add a simple device (specifically, a monochrome printer), you 171probably don't need to read the rest of this document; just use the code in 172an existing driver as a guide. The Epson and Canon BubbleJet drivers <a 173href="../src/gdevepsn.c">gdevepsn.c</a> and <a 174href="../src/gdevbj10.c">gdevbj10.c</a> are good models for dot-matrix 175printers, which require presenting the data for many scan lines at once; the 176DeskJet/LaserJet drivers in <a href="../src/gdevdjet.c">gdevdjet.c</a> are 177good models for laser printers, which take a single scan line at a time but 178support data compression. For color printers, there are unfortunately no 179good models: the two major color inkjet printer drivers, <a 180href="../src/gdevcdj.c">gdevcdj.c</a> and <a 181href="../src/gdevstc.c">gdevstc.c</a>, are far too complex to read. 182 183<p> 184On the other hand, if you're writing a driver for some more esoteric 185device, you probably do need at least some of the information in the rest 186of this document. It might be a good idea for you to read it in 187conjunction with one of the existing drivers. 188 189<p> 190Duplication of code, and sheer volume of code, is a serious maintenance and 191distribution problem for Ghostscript. If your device is similar to an 192existing one, try to implement your driver by adding some parameterization 193to an existing driver rather than by copying code to create an entirely new 194source module. <a href="../src/gdevepsn.c">gdevepsn.c</a> and <a 195href="../src/gdevdjet.c">gdevdjet.c</a> are good examples of this approach. 196 197<hr> 198 199<h2><a name="Structure"></a>Driver structure</h2> 200 201<p> 202A device is represented by a structure divided into three parts: 203 204<ul> 205<li>procedures that are (normally) shared by all instances of each device; 206 207<li>parameters that are present in all devices but may be different for 208each device or instance; and 209 210<li>device-specific parameters that may be different for each instance. 211</ul> 212 213<p> 214Normally the procedure structure is defined and initialized at compile 215time. A prototype of the parameter structure (including both generic and 216device-specific parameters) is defined and initialized at compile time, but 217is copied and filled in when an instance of the device is created. Both of 218these structures should be declared as <b><tt>const</tt></b>, but for backward 219compatibility reasons the latter is not. 220 221<p> 222The <b><tt>gx_device_common</tt></b> macro defines the common structure 223elements, with the intent that devices define and export a structure along 224the following lines. Do not fill in the individual generic parameter values 225in the usual way for C structures: use the macros defined for this purpose 226in <a href="../src/gxdevice.h">gxdevice.h</a> or, if applicable, <a 227href="../src/gdevprn.h">gdevprn.h</a>. 228 229<blockquote> 230<pre>typedef struct smurf_device_s { 231 gx_device_common; 232 <b><em>... device-specific parameters ...</em></b> 233} smurf_device; 234smurf_device gs_smurf_device = { 235 <b><em>... macro for generic parameter values ...,</em></b> 236 { <b><em>... procedures ...</em></b> }, /* std_procs */ 237 <b><em>... device-specific parameter values if any ...</em></b> 238};</pre> 239</blockquote> 240<p> 241The device structure instance <b>must</b> have the name 242<b><tt>gs_smurf_device</tt></b>, where <b><tt>smurf</tt></b> is the device 243name used in <b><tt>contrib.mak</tt></b>. <b><tt>gx_device_common</tt></b> 244is a macro consisting only of the element definitions. 245<p> 246All the device procedures are called with the device as the first argument. 247Since each device type is actually a different structure type, the device 248procedures must be declared as taking a <b><tt>gx_device *</tt></b> as 249their first argument, and must cast it to 250<b><tt>smurf_device *</tt></b> internally. For example, in the code 251for the "memory" device, the first argument to all routines is called 252<b><tt>dev</tt></b>, but the routines actually use <b><tt>mdev</tt></b> to 253refer to elements of the full structure, using the following standard 254initialization statement at the beginning of each procedure: 255 256<blockquote> 257<pre>gx_memory_device *const mdev = (gx_device_memory *)dev;</pre> 258</blockquote> 259 260<p> 261(This is a cheap version of "object-oriented" programming: in C++, for 262example, the cast would be unnecessary, and in fact the procedure table 263would be constructed by the compiler.) 264 265<h3><a name="Structure_definition"></a>Structure definition</h3> 266 267<p> 268You should consult the definition of struct <b><tt>gx_device_s</tt></b> in 269<a href="../src/gxdevice.h">gxdevice.h</a> for the complete details of the 270generic device structure. Some of the most important members of this 271structure for ordinary drivers are: 272 273<blockquote><table cellpadding=0 cellspacing=0> 274<tr valign=top> <td><b><tt>const char *dname;</tt></b> 275 <td> 276 <td>The device name 277<tr valign=top> <td><b><tt>bool is_open;</tt></b> 278 <td> 279 <td>True if device has been opened 280<tr valign=top> <td><b><tt>gx_device_color_info color_info;</tt></b> 281 <td> 282 <td>Color information 283<tr valign=top> <td><b><tt>int width;</tt></b> 284 <td> 285 <td>Width in pixels 286<tr valign=top> <td><b><tt>int height;</tt></b> 287 <td> 288 <td>Height in pixels 289</table></blockquote> 290 291<p> 292The name in the structure (<b><tt>dname</tt></b>) should be the same as the 293name in <a href="../src/contrib.mak">contrib.mak</a>. 294 295<h3><a name="Sophisticated"></a>For sophisticated developers only</h3> 296 297<p> 298If for any reason you need to change the definition of the basic device 299structure, or to add procedures, you must change the following places: 300 301<blockquote><ul> 302<li>This document and the <a href="News.htm">news document</a> (if you want 303 to keep the documentation up to date). 304<li>The definition of <b><tt>gx_device_common</tt></b> and the procedures 305 in <a href="../src/gxdevcli.h">gxdevcli.h</a>. 306<li>Possibly, the default forwarding procedures declared in 307 <a href="../src/gxdevice.h">gxdevice.h</a> and implemented in 308 <a href="../src/gdevnfwd.c">gdevnfwd.c</a>. 309<li>The device procedure record completion routines in 310 <a href="../src/gdevdflt.c">gdevdflt.c</a>. 311<li>Possibly, the default device implementation in 312 <a href="../src/gdevdflt.c">gdevdflt.c</a>, 313 <a href="../src/gdevddrw.c">gdevddrw.c</a>, and 314 <a href="../src/gxcmap.c">gxcmap.c</a>. 315<li>The bounding box device in <a href="../src/gdevbbox.c">gdevbbox.c</a> 316 (probably just adding <b><tt>NULL</tt></b> procedure entries if the 317 new procedures don't produce output). 318<li>These devices that must have complete (non-defaulted) procedure vectors: 319<ul> 320<li>The null device in <a href="../src/gdevnfwd.c">gdevnfwd.c</a>. 321<li>The command list "device" in <a href="../src/gxclist.c">gxclist.c</a>. 322 This is not an actual device; it only defines procedures. 323<li>The "memory" devices in <a href="../src/gdevmem.h">gdevmem.h</a> and 324 <b><tt>gdevm*.c</tt></b>. 325</ul> 326<li>The clip list accumulation "device" in 327 <a href="../src/gxacpath.c">gxacpath.c</a>. 328<li>The clipping "devices" <a href="../src/gxclip.c">gxclip.c</a>, 329 <a href="../src/gxclip2.c">gxclip2.c</a>, 330 and <a href="../src/gxclipm.c">gxclipm.c</a>. 331<li>The pattern accumulation "device" in 332 <a href="../src/gxpcmap.c">gxpcmap.c</a>. 333<li>The hit detection "device" in <a href="../src/gdevhit.c">gdevhit.c</a>. 334<li>The generic printer device macros in 335 <a href="../src/gdevprn.h">gdevprn.h</a>. 336<li>The generic printer device code in 337 <a href="../src/gdevprn.c">gdevprn.c</a>. 338<li>The RasterOp source device in 339 <a href="../src/gdevrops.c">gdevrops.c</a>. 340</ul></blockquote> 341 342<p> 343You may also have to change the code for 344<b><tt>gx_default_get_params</tt></b> or 345<b><tt>gx_default_put_params</tt></b> in <a 346href="../src/gsdparam.c">gsdparam.c</a>. 347 348<p> 349You should not have to change any of the real devices in the standard 350Ghostscript distribution (listed in <a href="../src/devs.mak">devs.mak</a> 351and <a href="../src/contrib.mak">contrib.mak</a>) or any of your own 352devices, because all of them are supposed to use the macros in <a 353href="../src/gxdevice.h">gxdevice.h</a> or <a 354href="../src/gdevprn.h">gdevprn.h</a> to define and initialize their state. 355 356<hr> 357 358<h2><a name="coordinates_and_types"></a>Coordinates and types</h2> 359 360<h3><a name="Coordinate_system"></a>Coordinate system</h3> 361 362<p> 363Since each driver specifies the initial transformation from user 364coordinates to device coordinates, the driver can use any coordinate system 365it wants, as long as a device coordinate will fit in an 366<b><tt>int</tt></b>. (This is only an issue on DOS systems, where ints are 367only 16 bits. User coordinates are represented as floats.) Most current 368drivers use a coordinate system with (0,0) in the upper left corner, with 369<b><em>X</em></b> increasing to the right and <b><em>Y</em></b> increasing 370toward the bottom. However, there is supposed to be nothing in the rest of 371Ghostscript that assumes this, and indeed some drivers use a coordinate 372system with (0,0) in the lower left corner. 373 374<p> 375Drivers must check (and, if necessary, clip) the coordinate parameters given 376to them: they should not assume the coordinates will be in bounds. The 377<b><tt>fit_fill</tt></b> and <b><tt>fit_copy</tt></b> macros in <a 378href="../src/gxdevice.h">gxdevice.h</a> are very helpful in doing this. 379 380<h3><a name="Color_definition"></a>Color definition</h3> 381 382<p> 383Between the Ghostscript graphics library and the device, colors are 384represented in three forms. Color components in a color space (Gray, RGB, 385DeviceN, etc.) represented as <b><tt>frac</tt></b> values. Device colorants 386are represented as <b><tt>gx_color_value</tt></b> values. For many 387procedures, colors are represented in a type called 388<b><tt>gx_color_index</tt></b>. 389All three types are described in more detail in <a href="#Types">Types</a> 390 391<p> 392The <b><tt>color_info</tt></b> member of the device structure defines the 393color and gray-scale capabilities of the device. Its type is defined as 394follows: 395 396<blockquote> 397<pre> 398/* 399 * The enlarged color model information structure: Some of the 400 * information that was implicit in the component number in 401 * the earlier conventions (component names, polarity, mapping 402 * functions) are now explicitly provided. 403 * 404 * Also included is some information regarding the encoding of 405 * color information into gx_color_index. Some of this information 406 * was previously gathered indirectly from the mapping 407 * functions in the existing code, specifically to speed up the 408 * halftoned color rendering operator (see 409 * gx_dc_ht_colored_fill_rectangle in gxcht.c). The information 410 * is now provided explicitly because such optimizations are 411 * more critical when the number of color components is large. 412 * 413 * Note: no pointers have been added to this structure, so there 414 * is no requirement for a structure descriptor. 415 */ 416typedef struct gx_device_color_info_s { 417 418 /* 419 * max_components is the maximum number of components for all 420 * color models supported by this device. This does not include 421 * any alpha components. 422 */ 423 int max_components; 424 425 /* 426 * The number of color components. This does not include any 427 * alpha-channel information, which may be integrated into 428 * the gx_color_index but is otherwise passed as a separate 429 * component. 430 */ 431 int num_components; 432 433 /* 434 * Polarity of the components of the color space, either 435 * additive or subtractive. This is used to interpret transfer 436 * functions and halftone threshold arrays. Possible values 437 * are GX_CM_POLARITY_ADDITIVE or GX_CM_POLARITY_SUBTRACTIVE 438 */ 439 gx_color_polarity_t polarity; 440 441 /* 442 * The number of bits of gx_color_index actually used. 443 * This must be <= sizeof(gx_color_index), which is usually 64. 444 */ 445 byte depth; 446 447 /* 448 * Index of the gray color component, if any. The max_gray and 449 * dither_gray values apply to this component only; all other 450 * components use the max_color and dither_color values. 451 * 452 * This will be GX_CINFO_COMP_NO_INDEX if there is no gray 453 * component. 454 */ 455 byte gray_index; 456 457 /* 458 * max_gray and max_color are the number of distinct native 459 * intensity levels, less 1, for the gray and all other color 460 * components, respectively. For nearly all current devices 461 * that support both gray and non-gray components, the two 462 * parameters have the same value. 463 * 464 * dither_grays and dither_colors are the number of intensity 465 * levels between which halftoning can occur, for the gray and 466 * all other color components, respectively. This is 467 * essentially redundant information: in all reasonable cases, 468 * dither_grays = max_gray + 1 and dither_colors = max_color + 1. 469 * These parameters are, however, extensively used in the 470 * current code, and thus have been retained. 471 * 472 * Note that the non-gray values may now be relevant even if 473 * num_components == 1. This simplifies the handling of devices 474 * with configurable color models which may be set for a single 475 * non-gray color model. 476 */ 477 gx_color_value max_gray; /* # of distinct color levels -1 */ 478 gx_color_value max_color; 479 480 gx_color_value dither_grays; 481 gx_color_value dither_colors; 482 483 /* 484 * Information to control super-sampling of objects to support 485 * anti-aliasing. 486 */ 487 gx_device_anti_alias_info anti_alias; 488 489 /* 490 * Flag to indicate if gx_color_index for this device may be divided 491 * into individual fields for each component. This is almost always 492 * the case for printers, and is the case for most modern displays 493 * as well. When this is the case, halftoning may be performed 494 * separately for each component, which greatly simplifies processing 495 * when the number of color components is large. 496 * 497 * If the gx_color_index is separable in this manner, the comp_shift 498 * array provides the location of the low-order bit for each 499 * component. This may be filled in by the client, but need not be. 500 * If it is not provided, it will be calculated based on the values 501 * in the max_gray and max_color fields as follows: 502 * 503 * comp_shift[num_components - 1] = 0, 504 * comp_shift[i] = comp_shift[i + 1] 505 * + ( i == gray_index ? ceil(log2(max_gray + 1)) 506 * : ceil(log2(max_color + 1)) ) 507 * 508 * The comp_mask and comp_bits fields should be left empty by the client. 509 * They will be filled in during initialization using the following 510 * mechanism: 511 * 512 * comp_bits[i] = ( i == gray_index ? ceil(log2(max_gray + 1)) 513 * : ceil(log2(max_color + 1)) ) 514 * 515 * comp_mask[i] = (((gx_color_index)1 << comp_bits[i]) - 1) 516 * << comp_shift[i] 517 * 518 * (For current devices, it is almost always the case that 519 * max_gray == max_color, if the color model contains both gray and 520 * non-gray components.) 521 * 522 * If separable_and_linear is not set, the data in the other fields 523 * is unpredictable and should be ignored. 524 */ 525 gx_color_enc_sep_lin_t separable_and_linear; 526 byte comp_shift[GX_DEVICE_COLOR_MAX_COMPONENTS]; 527 byte comp_bits[GX_DEVICE_COLOR_MAX_COMPONENTS]; 528 gx_color_index comp_mask[GX_DEVICE_COLOR_MAX_COMPONENTS]; 529 /* 530 * Pointer to name for the process color model. 531 */ 532 const char * cm_name; 533 534} gx_device_color_info; 535</pre> 536</blockquote> 537 538<p> 539Note: See <a href="#Changing_color_info_data">Changing color_info data</a> before changing 540any information in the <b><tt>color_info structure</tt></b> for a device. 541 542<p> 543It is recommended that the values for this structure be defined using one 544of the standard macros provided for this purpose. This allows for future 545changes to be made to the structure without changes being required in the 546actual device code. 547 548<p> 549The following macros (in <a href="../src/gxdevcli.h">gxdevcli.h</a>) provide 550convenient shorthands for initializing this structure for ordinary 551black-and-white or color devices: 552 553<blockquote> 554<b><tt>#define dci_black_and_white</tt></b> ...<br> 555<b><tt>#define dci_color(depth,maxv,dither)</tt></b> ... 556</blockquote> 557 558<p> 559The <b><tt>#define dci_black_and_white</tt></b> macro defines a 560single bit monochrome device (For example: a typical monochrome printer device.) 561 562<p> 563The <b><tt>#define dci_color(depth,maxv,dither)</tt></b> macro can be used 564to define a 24 bit RGB device or a 4 or 32 bit CMYK device. 565 566<p> 567The <b><tt>#define dci_extended_alpha_values</tt></b> macro (in 568<a href="../src/gxdevcli.h">gxdevcli.h</a>) 569specifies most of the current fields in the structure. However this macro allows 570only the default setting for the comp_shift, comp_bits, and comp_mask fields 571to be set. Any device which requires a non-default setting for these fields 572has to correctly these fields during the device open procedure. 573See 574<a href="#sep_and_linear_fields">Separable and linear fields></a> and 575<a href="#Changing_color_info_data">Changing color_info data</a>. 576 577<p> 578The idea is that a device has a certain number of gray levels 579(<b><tt>max_gray</tt></b>+1) and a certain number of colors 580(<b><tt>max_rgb</tt></b>+1) that it can produce directly. When Ghostscript 581wants to render a given color space color value as a device color, it first tests 582whether the color is a gray level and if so: 583 584<blockquote> 585If <b><tt>max_gray</tt></b> is large (>= 31), Ghostscript asks the 586device to approximate the gray level directly. If the device returns a 587valid <b><tt>gx_color_index</tt></b>, Ghostscript uses it. Otherwise, 588Ghostscript assumes that the device can represent 589<b><tt>dither_gray</tt></b> distinct gray levels, equally spaced along the 590diagonal of the color cube, and uses the two nearest ones to the desired 591color for halftoning. 592</blockquote> 593 594<p> 595If the color is not a gray level: 596 597<blockquote> 598If <b><tt>max_rgb</tt></b> is large (>= 31), Ghostscript asks the device 599to approximate the color directly. If the device returns a valid 600<b><tt>gx_color_index</tt></b>, Ghostscript uses it. Otherwise, 601Ghostscript assumes that the device can represent 602 603<blockquote> 604<b><tt>dither_rgb</tt></b> × <b><tt>dither_rgb</tt></b> × <b><tt>dither_rgb</tt></b> 605</blockquote> 606 607<p> 608distinct colors, equally spaced throughout the color cube, and uses two of 609the nearest ones to the desired color for halftoning. 610</blockquote> 611 612<h4><a name="sep_and_linear_fields"></a>Separable and linear fields</h4> 613<p> 614The three fields <b><tt>comp_shift</tt></b>, <b><tt>comp_bits</tt></b>, and 615<b><tt>comp_mask</tt></b> are only used if the <b><tt>separable_and_linear</tt></b> 616field is set to <b><tt>GX_CINFO_SEP_LIN</tt></b>. In this situation a <b><tt>gx_color_index</tt></b> 617value must represent a combination created by or'ing bits for each of the devices's 618output colorants. The <b><tt>comp_shift</tt></b> array defines the location 619(shift count) of each colorants bits in the output gx_color_index value. The 620<b><tt>comp_bits</tt></b> array defines the number of bits for each colorant. 621The <b><tt>comp_mask</tt></b> array contains a mask which can be used to isolate 622the bits for each colorant. These fields must be set if the device supports 623more than four colorants. 624 625<h4><a name="Changing_color_info_data"></a>Changing color_info data</h4> 626 627<p> For most devices, the information in the device's <tt><b>color_info</b></tt> 628structure is defined by the various device definition macros and the data remains 629constant during the entire existence of the device. In general the Ghostscript 630graphics assumes that the information is constant. However some devices want 631to modify the data in this structure. 632 633<p> 634The device's <b><tt>put_params</tt></b> procedure may change 635<b><tt>color_info</tt></b> field values. 636After the data has been modified then the 637device should be closed (via a call to <tt><b>gs_closedevice</b></tt>). Closing 638the device will erase the current page so these changes should only be made 639before anything has been drawn on a page. 640 641<p> The device's <tt><b>open_device</b></tt> procedure may change 642<b><tt>color_info</tt></b> field values. These changes should be done before 643calling any other procedures are called. 644 645<p> 646The Ghostscript graphics library 647uses some of the data in <b><tt>color_info</tt></b> to set the default 648procedures for the 649<b><tt>get_color_mapping_procs</tt></b>, 650<b><tt>get_color_comp_index</tt></b>, 651<b><tt>encode_color</tt></b>, and 652<b><tt>decode_color</tt></b> procedures. 653These default procedures are set when the 654device is originally created. If any changes are made to the 655<b><tt>color_info</tt></b> fields then the device's <b><tt>open_device</tt></b> 656procedure 657has responsibility for insuring that the correct procedures are contained 658in the device structure. (For an example, see the display device open procedure 659<b><tt>display_open</tt></b> and its subroutine <b><tt>display_set_color_format 660</tt></b> (in <a href="../src/gdevdisp.c">gdevdisp</a>). 661 662 663<h3><a name="Types"></a>Types</h3> 664 665<p> 666Here is a brief explanation of the various types that appear as parameters 667or results of the drivers. 668 669<dl> 670<dt><b><tt>frac</tt></b> (defined in <a href="../src/gxfrac.h">gxfrac.h</a>) 671<dd>This is the type used to represent color values for the input to the 672color model mapping procedures. It is currently defined as a short. It has a 673range of <b><tt>frac_0</tt></b> to <b><tt>frac_1</tt></b>. 674</dl> 675 676<dl> 677<dt><b><tt>gx_color_value</tt></b> (defined in 678<a href="../src/gxdevice.h">gxdevice.h</a>) 679<dd>This is the type used to represent RGB or CMYK color values. It is 680currently equivalent to unsigned short. However, Ghostscript may use less 681than the full range of the type to represent color values: 682<b><tt>gx_color_value_bits</tt></b> is the number of bits actually used, 683and <b><tt>gx_max_color_value</tt></b> is the maximum value, equal to 684(2^<small><sup><b><tt>gx_max_color_value_bits</tt></b></sup></small>)-1. 685</dl> 686 687<dl> 688<dt><b><tt>gx_device</tt></b> (defined in 689<a href="../src/gxdevice.h">gxdevice.h</a>) 690<dd>This is the device structure, as explained above. 691</dl> 692 693<dl> 694<dt><b><tt>gs_matrix</tt></b> (defined in 695<a href="../src/gsmatrix.h">gsmatrix.h</a>) 696<dd>This is a 2-D homogeneous coordinate transformation matrix, used by 697many Ghostscript operators. 698</dl> 699 700<dl> 701<dt><b><tt>gx_color_index</tt></b> (defined in 702<a href="../src/gxcindex.h">gxcindex.h</a>) 703<dd>This is meant to be whatever the driver uses to represent a device 704color. For example, it might be an index in a color map, or it might be R, 705G, and B values packed into a single integer. The Ghostscript graphics library 706gets <b><tt>gx_color_index</tt></b> values from the device's 707<b><tt>encode_color</tt></b> and hands them back as arguments to several other 708procedures. If the <b><tt>separable_and_linear</tt></b> field in the device's 709<b><tt>color_info</tt></b> structure is not set to 710<b><tt>GX_CINFO_SEP_LIN</tt></b> then Ghostscript does not do 711any computations with <b><tt>gx_color_index</tt></b> values. 712 713<p> 714The special 715value <b><tt>gx_no_color_index</tt></b> (defined as 716<b><tt>(~(gx_color_index)(0))</tt></b> ) means "transparent" for some of 717the procedures. 718 719<p> 720The size of <b><tt>gx_color_index</tt></b> can be either 32 or 64 bits. The 721choice depends upon the architecture of the CPU and the compiler. The default 722type definition is simply: 723 724<blockquote><b><tt> 725typedef unsigned long gx_color_index; 726</tt></b></blockquote> 727 728However if <b><tt>GX_COLOR_INDEX_TYPE</tt></b> is defined, then it is used 729as the type for <b><tt>gx_color_index</tt></b>. 730 731<blockquote><b><tt> 732typedef GX_COLOR_INDEX_TYPE gx_color_index; 733</tt></b></blockquote> 734 735The smaller size (32 bits) may produce more efficient or faster executing 736code. The larger size (64 bits) is needed for representing either more 737bits per component or more components. An example of the later case is 738a device that supports 8 bit contone colorants using a DeviceCMYK process 739color model with its four colorants and also supports additional spot 740colorants. 741 742<p> 743Currently autoconf attempts to find a 64 bit type definition for the 744compiler being used, and if a 64 bit type is found then 745<b><tt>GX_COLOR_INDEX_TYPE</tt></b> is set to the type. 746 747<p> 748For Microsoft and the MSVC compiler, <b><tt>GX_COLOR_INDEX_TYPE</tt></b> will 749be set to <b><tt>unsigned _int64</tt></b> if <b><tt>USE_LARGE_COLOR_INDEX</tt></b> 750is set to 1 either on the make command line or by editing the definition 751 in <a href="../src/msvc32.mak">msvc32.mak</a> 752</dl> 753 754<dl> 755<dt><b><tt>gs_param_list</tt></b> (defined in <a 756href="../src/gsparam.h">gsparam.h</a>) 757 <dd>This is a parameter list, which is used to read and set attributes in a 758device. See the comments in <a href="../src/gsparam.h">gsparam.h</a>, and 759the <a href="#Parameters">description of the <b><tt>get_params</tt></b> and 760<b><tt>put_params</tt></b> procedures</a> below, for more detail. 761</dl> 762 763<dl> 764<dt><b><tt>gx_tile_bitmap</tt></b> (defined in 765<a href="../src/gxbitmap.h">gxbitmap.h</a>) 766<br><b><tt>gx_strip_bitmap</tt></b> (defined in 767<a href="../src/gxbitmap.h">gxbitmap.h</a>) 768<dd>These structure types represent bitmaps to be used as a tile for 769filling a region (rectangle). <b><tt>gx_tile_bitmap</tt></b> is an older 770type lacking <b><tt>shift</tt></b> and <b><tt>rep_shift</tt></b>; 771<b><tt>gx_strip_bitmap</tt></b> has superseded it, and it should not be 772used in new code. Here is a copy of the relevant part of the file: 773 774<blockquote> 775<pre> 776/* 777 * Structure for describing stored bitmaps. 778 * Bitmaps are stored bit-big-endian (i.e., the 2^7 bit of the first 779 * byte corresponds to x=0), as a sequence of bytes (i.e., you can't 780 * do word-oriented operations on them if you're on a little-endian 781 * platform like the Intel 80x86 or VAX). Each scan line must start on 782 * a (32-bit) word boundary, and hence is padded to a word boundary, 783 * although this should rarely be of concern, since the raster and width 784 * are specified individually. The first scan line corresponds to y=0 785 * in whatever coordinate system is relevant. 786 * 787 * For bitmaps used as halftone tiles, we may replicate the tile in 788 * X and/or Y, but it is still valuable to know the true tile dimensions 789 * (i.e., the dimensions prior to replication). Requirements: 790 * width % rep_width = 0 791 * height % rep_height = 0 792 * 793 * For halftones at arbitrary angles, we provide for storing the halftone 794 * data as a strip that must be shifted in X for different values of Y. 795 * For an ordinary (non-shifted) halftone that has a repetition width of 796 * W and a repetition height of H, the pixel at coordinate (X,Y) 797 * corresponds to halftone pixel (X mod W, Y mod H), ignoring phase; 798 * for a shifted halftone with shift S, the pixel at (X,Y) corresponds 799 * to halftone pixel ((X + S * floor(Y/H)) mod W, Y mod H). Requirements: 800 * strip_shift < rep_width 801 * strip_height % rep_height = 0 802 * shift = (strip_shift * (size.y / strip_height)) % rep_width 803 */ 804typedef struct gx_strip_bitmap_s { 805 byte *data; 806 int raster; /* bytes per scan line */ 807 gs_int_point size; /* width, height */ 808 gx_bitmap_id id; 809 ushort rep_width, rep_height; /* true size of tile */ 810 ushort strip_height; 811 ushort strip_shift; 812 ushort shift; 813} gx_strip_bitmap;</pre> 814</blockquote> 815</dl> 816 817<hr> 818 819<h2><a name="Coding_conventions"></a>Coding conventions</h2> 820 821<p> 822All the driver procedures defined below that return <b><tt>int</tt></b> 823results return 0 on success, or an appropriate negative error code in the 824case of error conditions. The error codes are defined in <a 825href="../src/gserrors.h">gserrors.h</a>; they correspond directly to the 826errors defined in the PostScript language reference manuals. The most 827common ones for drivers are: 828 829<blockquote><dl> 830<dt><b><tt>gs_error_invalidfileaccess</tt></b> 831<dd>An attempt to open a file failed. 832 833<dt><b><tt>gs_error_ioerror</tt></b> 834<dd>An error occurred in reading or writing a file. 835 836<dt><b><tt>gs_error_limitcheck</tt></b> 837 <dd>An otherwise valid parameter value was too large for the 838implementation. 839 840<dt><b><tt>gs_error_rangecheck</tt></b> 841<dd>A parameter was outside the valid range. 842 843<dt><b><tt>gs_error_VMerror</tt></b> 844<dd>An attempt to allocate memory failed. (If this happens, the procedure 845should release all memory it allocated before it returns.) 846</dl></blockquote> 847 848<p> 849If a driver does return an error, rather than a simple return statement it 850should use the <b><tt>return_error</tt></b> macro defined in <a 851href="../src/gx.h">gx.h</a>, which is automatically included by <a 852href="../src/gdevprn.h">gdevprn.h</a> but not by <a 853href="../src/gserrors.h">gserrors.h</a>. For example 854 855<blockquote> 856<b><tt> return_error(gs_error_VMerror); 857</tt></b></blockquote> 858 859<h3><a name="Allocating_storage"></a>Allocating storage</h3> 860 861<p> 862While most drivers (especially printer drivers) follow a very similar 863template, there is one important coding convention that is not obvious from 864reading the code for existing drivers: driver procedures must not use 865<b><tt>malloc</tt></b> to allocate any storage that stays around after the 866procedure returns. Instead, they must use <b><tt>gs_malloc</tt></b> and 867<b><tt>gs_free</tt></b>, which have slightly different calling conventions. 868(The prototypes for these are in <a href="../src/gsmemory.h">gsmemory.h</a>, 869which is included in <a href="../src/gx.h">gx.h</a>, which is included in <a 870href="../src/gdevprn.h">gdevprn.h</a>.) This is necessary so that 871Ghostscript can clean up all allocated memory before exiting, which is 872essential in environments that provide only single-address-space 873multi-tasking (some versions of Microsoft Windows). 874 875<blockquote> 876<pre>char *gs_malloc(uint num_elements, uint element_size, 877 const char *client_name);</pre> 878</blockquote> 879 880<p> 881Like <b><tt>calloc</tt></b>, but unlike <b><tt>malloc</tt></b>, 882<b><tt>gs_malloc</tt></b> takes an element count and an element size. For 883structures, <b><tt>num_elements</tt></b> is 1 andi 884<b><tt>element_size</tt></b> is <b><tt>sizeof</tt></b> the structure; for 885byte arrays, <b><tt>num_elements</tt></b> is the number of bytes and 886<b><tt>element_size</tt></b> is 1. Unlike <b><tt>calloc</tt></b>, 887<b><tt>gs_malloc</tt></b> does <b>not</b> clear the block of storage. 888 889<p> 890The <b><tt>client_name</tt></b> is used for tracing and debugging. It must 891be a real string, not <b><tt>NULL</tt></b>. Normally it is the name of the 892procedure in which the call occurs. 893 894<blockquote> 895<pre>void gs_free(char *data, uint num_elements, uint element_size, 896 const char *client_name);</pre> 897</blockquote> 898 899<p> 900Unlike <b><tt>free</tt></b>, <b><tt>gs_free</tt></b> demands that 901<b><tt>num_elements</tt></b> and element_size be supplied. It also 902requires a client name, like <b><tt>gs_malloc</tt></b>. 903 904<h3><a name="Driver_instance_allocation"></a>Driver instance allocation</h3> 905 906<p>i 907All driver instances allocated by Ghostscript's standard allocator must 908point to a "structure descriptor" that tells the garbage collector how to 909trace pointers in the structure. For drivers registered in the normal way 910(using the makefile approach described above), no special care is needed as 911long as instances are created only by calling the 912<b><tt>gs_copydevice</tt></b> procedure defined in <a 913href="../src/gsdevice.h">gsdevice.h</a>. If you have a need to define 914devices that are not registered in this way, you must fill in the stype 915member in any dynamically allocated instances with a pointer to the same 916structure descriptor used to allocate the instance. For more information 917about structure descriptors, see <a href="../src/gsmemory.h">gsmemory.h</a> 918and <a href="../src/gsstruct.h">gsstruct.h</a>. 919 920<hr> 921 922<h2><a name="Printer_drivers"></a>Printer drivers</h2> 923 924<p> 925Printer drivers (which include drivers that write some kind of raster file) 926are especially simple to implement. 927The printer driver must implement a <b><tt>print_page</tt></b> or 928<b><tt>print_page_copies</tt></b> procedure. There are macros in <a 929href="../src/gdevprn.h">gdevprn.h</a> that generate the device structure for 930such devices, of which the simplest is <b><tt>prn_device</tt></b>; for an 931example, see <a href="../src/gdevbj10.c">gdevbj10.c</a>. If you are writing 932a printer driver, we suggest you start by reading <a 933href="../src/gdevprn.h">gdevprn.h</a> and the <a 934href="#Color_mapping">subsection on "Color mapping"</a> below; you may be 935able to ignore all the rest of the driver procedures. 936 937<p> 938The <b><tt>print_page</tt></b> procedures are defined as follows: 939 940<blockquote> 941<pre>int (*print_page)(gx_device_printer *, FILE *) 942int (*print_page_copies)(gx_device_printer *, FILE *, int)</pre> 943</blockquote> 944 945<p> 946This procedure must read out the rendered image from the device and write 947whatever is appropriate to the file. To read back one or more scan lines 948of the image, the <b><tt>print_page</tt></b> procedure must call one of the 949following procedures: 950 951<blockquote> 952<pre>int gdev_prn_copy_scan_lines(gx_device_printer *pdev, int y, byte *str, 953 uint size)</pre> 954</blockquote> 955 956<p> 957For this procedure, <b><tt>str</tt></b> is where the data should be copied to, and <b><tt>size</tt></b> is 958the size of the buffer starting at <b><tt>str</tt></b>. This procedure returns the number 959of scan lines copied, or <0 for an error. <b><tt>str</tt></b> need not be aligned. 960 961<blockquote> 962<pre>int gdev_prn_get_bits(gx_device_printer *pdev, int y, byte *str, 963 byte **actual_data)</pre> 964</blockquote> 965 966<p> 967This procedure reads out exactly one scan line. If the scan line is 968available in the correct format already, <b><tt>*actual_data</tt></b> is 969set to point to it; otherwise, the scan line is copied to the buffer 970starting at <b><tt>str</tt></b>, and <b><tt>*actual_data</tt></b> is set to 971<b><tt>str</tt></b>. This saves a copying step most of the time. 972<b><tt>str</tt></b> need not be aligned; however, if 973<b><tt>*actual_data</tt></b> is set to point to an existing scan line, it 974will be aligned. (See the description of the <b><tt>get_bits</tt></b> 975procedure below for more details.) 976 977<p> 978In either case, each row of the image is stored in the form described in 979the comment under <b><tt>gx_tile_bitmap</tt></b> above; each pixel takes 980the number of bits specified as <b><tt>color_info.depth</tt></b> in the 981device structure, and holds values returned by the device's 982<b><tt>encode_color</tt></b> procedure. 983 984<p> 985The <b><tt>print_page</tt></b> procedure can determine the number of bytes 986required to hold a scan line by calling: 987 988<blockquote> 989<pre>uint gdev_prn_raster(gx_device_printer *)</pre> 990</blockquote> 991 992<p> 993For a very simple concrete example, we suggest reading the code in 994<b><tt>bit_print_page</tt></b> in <a href="../src/gdevbit.c">gdevbit.c</a>. 995 996<p> 997If the device provides <b><tt>print_page</tt></b>, Ghostscript will call 998<b><tt>print_page</tt></b> the requisite number of times to print the 999desired number of copies; if the device provides 1000<b><tt>print_page_copies</tt></b>, Ghostscript will call 1001<b><tt>print_page_copies</tt></b> once per page, passing it the desired 1002number of copies. 1003 1004<hr> 1005 1006<h2><a name="Driver_procedures"></a>Driver procedures</h2> 1007 1008<p> 1009Most of the procedures that a driver may implement are optional. If a 1010device doesn't supply an optional procedure <b><tt>WXYZ</tt></b>, the entry 1011in the procedure structure may be either <b><tt>gx_default_WXYZ</tt></b>, 1012for instance <b><tt>gx_default_tile_rectangle</tt></b>, or 1013<b><tt>NULL</tt></b> or 0. (The device procedure must also call the 1014<b><tt>gx_default_</tt></b> procedure if it doesn't implement the function 1015for particular values of the arguments.) Since C compilers supply 0 as the 1016value for omitted structure elements, this convention means that statically 1017initialized procedure structures continue to work even if new (optional) 1018members are added. 1019 1020<h3><a name="Life_cycle"></a>Life cycle</h3> 1021 1022<p> 1023A device instance begins life in a closed state. In this state, no output 1024operations will occur. Only the following procedures may be called: 1025 1026<blockquote><b><tt> 1027open_device<br> 1028finish_copydevice<br> 1029get_initial_matrix<br> 1030get_params<br> 1031put_params<br> 1032get_hardware_params 1033</tt></b></blockquote> 1034 1035<p> 1036When <b><tt>setdevice</tt></b> installs a device instance in the graphics 1037state, it checks whether the instance is closed or open. If the instance 1038is closed, <b><tt>setdevice</tt></b> calls the open routine, and then sets 1039the state to open. 1040 1041<p> 1042There is no user-accessible operation to close a device instance. This is 1043not an oversight -- it is required in order to enforce the following 1044invariant: 1045 1046<blockquote> 1047If a device instance is the current device in <em>any</em> graphics state, 1048it must be open (have <b><tt>is_open</tt></b> set to true). 1049</blockquote> 1050 1051<p> 1052Device instances are only closed when they are about to 1053be freed, which occurs in three situations: 1054 1055<ul> 1056<li>When a <b><tt>restore</tt></b> occurs, if the instance was created since 1057the corresponding <b><tt>save</tt></b> and is in a VM being restored. I.e., 1058if the instance was created in local VM since a <b><tt>save</tt></b>, it 1059will always be closed and freed by the corresponding 1060<b><tt>restore</tt></b>; if it was created in global VM, it will only be 1061closed by the outermost <b><tt>restore</tt></b>, regardless of the save 1062level at the time the instance was created. 1063 1064<li>By the garbage collector, if the instance is no longer accessible. 1065 1066<li>When Ghostscript exits (terminates). 1067</ul> 1068 1069<h3><a name="Open_close"></a>Open, close, sync, copy</h3> 1070 1071<dl> 1072<dt><b><tt>int (*open_device)(gx_device *)</tt></b> <b><em>[OPTIONAL]</em></b> 1073<dd>Open the device: do any initialization associated with making the device 1074instance valid. This must be done before any output to the device. The 1075default implementation does nothing. <b>NOTE</b>: Clients should never call 1076a device's <b><tt>open_device</tt></b> procedure directly: they should 1077always call <b><tt>gs_opendevice</tt></b> instead. 1078</dl> 1079 1080<dl> 1081<dt><b><tt>int (*finish_copydevice)(gx_device *dev, const gx_device 1082*from_dev)</tt></b> <b><em>[OPTIONAL]</em></b> <dd>Perform any cleanup 1083required after <b><tt>copydevice</tt></b> has created a new device instance 1084by copying <b><tt>from_dev</tt></b>. If the copy operation should not be 1085allowed, this procedure should return an error; the copy will be freed. The 1086default implementation allows copying the device prototype, but does not 1087allow copying device instances, because instances may contain internal 1088pointers that should not be shared between copies, and there is no way to 1089determine this from outside the device. <b>NOTE</b>: Clients should never 1090call a device's <b><tt>finish_copydevice</tt></b> procedure: this procedure 1091is only intended for use by <b><tt>gs_copydevice[2]</tt></b>. 1092</dl> 1093 1094<dl> 1095<dt><b><tt>void (*get_initial_matrix)(gx_device *, gs_matrix *)</tt></b> <b><em>[OPTIONAL]</em></b> 1096<dd>Construct the initial transformation matrix mapping user coordinates 1097(nominally 1/72 inch per unit) to device coordinates. The default 1098procedure computes this from width, height, and 1099[<b><tt>xy</tt></b>]<b><tt>_pixels_per_inch</tt></b> on the assumption that 1100the origin is in the upper left corner, that is 1101<blockquote> 1102<b><tt>xx</tt></b> = <b><tt>x_pixels_per_inch</tt></b>/72, <b><tt>xy</tt></b> = 0,<br> 1103<b><tt>yx = 0, yy = -y_pixels_per_inch</tt></b>/72,<br> 1104<b><tt>tx = 0, ty = height</tt></b>. 1105</blockquote> 1106</dl> 1107 1108<dl> 1109<dt><b><tt>int (*sync_output)(gx_device *)</tt></b> <b><em>[OPTIONAL]</em></b> 1110<dd>Synchronize the device. If any output to the device has been 1111buffered, send or write it now. Note that this may be called several times 1112in the process of constructing a page, so printer drivers should <b>not</b> 1113implement this by printing the page. The default implementation does 1114nothing. 1115</dl> 1116 1117<dl> 1118<dt><b><tt>int (*output_page)(gx_device *, int num_copies, int flush)</tt></b> <b><em>[OPTIONAL]</em></b> 1119<dd>Output a fully composed page to the device. The 1120<b><tt>num_copies</tt></b> argument is the number of copies that should be 1121produced for a hardcopy device. (This may be ignored if the driver has 1122some other way to specify the number of copies.) The <b><tt>flush</tt></b> 1123argument is true for <b><tt>showpage</tt></b>, false for 1124<b><tt>copypage</tt></b>. The default definition just calls 1125<b><tt>sync_output</tt></b>. Printer drivers should implement this by 1126printing and ejecting the page. 1127</dl> 1128 1129<dl> 1130<dt><b><tt>int (*close_device)(gx_device *)</tt></b> <b><em>[OPTIONAL]</em></b> 1131<dd>Close the device: release any associated resources. After this, output 1132to the device is no longer allowed. The default implementation does 1133nothing. <b>NOTE</b>: Clients should never call a device's 1134<b><tt>close_device</tt></b> procedure directly: they should always call 1135<b><tt>gs_closedevice</tt></b> instead. 1136</dl> 1137<h3><a name="Color_mapping"></a>Color and alpha mapping</h3> 1138 1139<p> 1140Note that code in the Ghostscript library may cache the results of calling 1141one or more of the color mapping procedures. If the result returned by any 1142of these procedures would change (other than as a result of a change made by 1143the driver's <b><tt>put_params</tt></b> procedure), the driver must call 1144<b><tt>gx_device_decache_colors(dev)</tt></b>. 1145 1146<p> 1147The <b><tt>map_rgb_color</tt></b>, <b><tt>map_color_rgb</tt></b>, and 1148<b><tt>map_cmyk_color</tt></b> are obsolete. They have been left 1149in the device procedure list for backward compatibility. See the 1150<b><tt>encode_color</tt></b> and <b><tt>decode_color</tt></b> procedures 1151below. To insure that older device drivers are changed to use the new 1152<b><tt>encode_color</tt></b> and <b><tt>decode_color</tt></b> 1153procedures, 1154the parameters for the older procedures have been changed to 1155match the new procedures. To minimize changes in devices that have 1156already been written, the map_rgb_color and map_cmyk_color routines 1157are used as the default value for the encode_color routine. The 1158map_cmyk_color routine is used if the number of components is four. 1159The map_rgb_color routine is used if the number of components is one 1160or three. This works okay for RGB and CMYK process color model devices. 1161However this does not work properly for gray devices. The encode_color 1162routine for a gray device is only passed one component. Thus the 1163map_rgb_color routine must be modified to only use a single input (instead 1164of three). (See the encode_color and decode_color routines below.) 1165 1166 1167<p> 1168Colors can be specified to the Ghostscript graphics library in a variety 1169of forms. For example, there are a wide variety of color spaces that can 1170be used such as Gray, RGB, CMYK, DeviceN, Separation, Indexed, CIEbasedABC, 1171etc. The graphics library converts the various input color space 1172values into four base color spaces: Gray, RGB, CMYK, and DeviceN. The 1173DeviceN color space allows for specifying values for individual device 1174colorants or spot colors. 1175 1176<p> 1177Colors are converted by the device in a two step process. The first step 1178is to convert a color in one of the base color spaces (Gray, RGB, CMYK, 1179or DeviceN) into values for each device colorant. This transformation is 1180done via a set of procedures provided by the device. These procedures are 1181provided by the <b><tt>get_color_mapping_procs</tt></b> device procedure. 1182 1183<p> 1184Between the first and second steps, the graphics library applies transfer 1185functions to the device colorants. Where needed, the output of the results 1186after the transfer functions is used by the graphics library for halftoning. 1187 1188<p> 1189In the second step, the device procedure <b><tt>encode_color</tt></b> is 1190used to convert the transfer function results into a 1191<b><tt>gx_color_index</tt></b> value. 1192The <b><tt>gx_color_index</tt></b> values are passed to specify colors 1193to various routines. 1194The choice of the encoding for a <b><tt>gx_color_index</tt></b> is 1195up to the device. Common choices are indexes into a color palette or 1196several integers packed together into a single value. The manner of this 1197encoding is usually opaque to the graphics library. The only exception to this 1198statement occurs when halftoning 5 or more colorants. In this case the 1199graphics library assumes that if a colorant values is zero then the 1200bits associated with the colorant in the <b><tt>gx_color_index</tt></b> 1201value are zero. 1202 1203<dl> 1204<dt><b><tt>int get_color_comp_index(const gx_device * dev, const char * pname, 1205int name_size, int src_index)</tt></b> <b><em>[OPTIONAL]</em></b> 1206<dd>This procedure returns the device colorant number of the given name. 1207The possible return values are -1, 0 to 1208<b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS - 1</tt></b>, or 1209<b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS</tt></b>. A value of -1 indicates that 1210the specified name is not a colorant for the device. A value of 0 to 1211<b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS - 1</tt></b> indicates the colorant number 1212of the given name. A value of <b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS</tt></b> 1213indicates that the given name is a valid colorant name for the device but the 1214colorant is not currently being used. This is used for implementing names 1215which are in SeparationColorNames but not in SeparationOrder. 1216 1217<p> 1218The default procedure returns results based upon process color model 1219of DeviceGray, DeviceRGB, or DeviceCMYK selected by 1220<b><tt>color_info.num_components</tt></b>. This procedure must be 1221defined if another process color model is used by the device or spot colors are 1222supported by the device. 1223</dd> 1224</dl> 1225 1226<dl> 1227<dt><b><tt>const gx_cm_color_map_procs * get_color_mapping_procs(const 1228gx_device * dev)</tt></b> <b><em>[OPTIONAL]</em></b> 1229<dd>This procedure returns a list of three procedures. These procedures 1230are used to translate values in either Gray, RGB, or CMYK color spaces 1231into device colorant values. A separate procedure is not required for the 1232DeviceN and Separation color spaces since these already represent 1233device colorants. 1234 1235<p> 1236The default procedure returns a list of procedures based upon 1237<b><tt>color_info.num_components</tt></b>. These procedures are appropriate 1238for DeviceGray, DeviceRGB, or DeviceCMYK process color model devices. A 1239procedure must be defined if another process color model is used by the 1240device or spot colors are to be supported. 1241</dd> 1242</dl> 1243 1244<dl> 1245<dt><b><tt>gx_color_index (*encode_color)(gx_device * dev, 1246gx_color_value * cv)</tt></b> <b><em>[OPTIONAL]</em></b> 1247<dd>Map a set of device color values into a <b><tt>gx_color_index</tt></b> 1248value. The range of legal values of the 1249arguments is 0 to <b><tt>gx_max_color_value</tt></b>. The default procedure 1250packs bits into a <b><tt>gx_color_index</tt></b> value based upon the 1251values in <b><tt>color_info.depth</tt></b> and 1252<b><tt>color_info.num_components</tt></b>. 1253 1254<p> 1255Note that the <b><tt>encode_color</tt></b> procedure 1256must not return <b><tt>gx_no_color_index</tt></b> (all 1s). 1257</dl> 1258 1259<dl> 1260<dt><b><tt>int (*decode_color)(gx_device *, gx_color_index color, 1261gx_color_value * CV)</tt></b> <b><em>[OPTIONAL]</em></b> 1262<dd>This is the inverse of the <b><tt>encode_color</tt></b> procedure. 1263Map a <b><tt>gx_color_index</tt></b> value to color values. The default 1264procedure unpacks bits from the <b><tt>gx_color_index</tt></b> value based upon 1265the values in <b><tt>color_info.depth</tt></b> and 1266<b><tt>color_info.num_components</tt></b>. 1267</dl> 1268 1269<dl> 1270<dt><b><tt>gx_color_index (*map_rgb_alpha_color)(gx_device *, 1271gx_color_value red, gx_color_value green, 1272gx_color_value blue, gx_color_value alpha)</tt></b> <b><em>[OPTIONAL]</em></b> 1273<dd>Map a RGB color and an opacity value to a device color. The range of 1274legal values of the RGB and alpha arguments is 0 to 1275<b><tt>gx_max_color_value</tt></b>; <b><tt>alpha</tt></b> = 0 means 1276transparent, <b><tt>alpha</tt></b> = <b><tt>gx_max_color_value</tt></b> 1277means fully opaque. The default is to use the 1278<b><tt>encode_color</tt></b> procedure and ignore alpha. 1279 1280<p> 1281Note that if a driver implements <b><tt>map_rgb_alpha_color</tt></b>, it 1282must also implement <b><tt>encode_color</tt></b>, and must implement them 1283in such a way that 1284<b><tt>map_rgb_alpha_color(dev, r, g, b, gx_max_color_value)</tt></b> 1285returns the same value as 1286<b><tt>encode_color(dev, CV)</tt></b>. 1287</dl> 1288 1289<dl> 1290<dt><b><tt>int (*map_color_rgb_alpha)(gx_device *, 1291gx_color_index color, gx_color_value rgba[4])</tt></b> 1292<b><em>[OPTIONAL]</em></b> 1293<dd>Map a device color code to RGB and alpha values. The default 1294implementation calls <b><tt>map_color_rgb</tt></b> and fills in 1295<b><tt>gx_max_color_value</tt></b> for alpha. 1296 1297<p> 1298Note that if a driver implements <b><tt>map_color_rgb_alpha</tt></b>, it 1299must also implement <b><tt>decode_color</tt></b>, and must implement them 1300in such a way that the first 3 values returned by 1301<b><tt>map_color_rgb_alpha</tt></b> are the same as the values returned by 1302<b><tt>decode_color</tt></b>. 1303 1304<p> 1305Note that only RGB devices currently support variable opacity; alpha is ignored 1306on other devices. The PDF 1.4 transparency features are supported on all devices. 1307</dl> 1308 1309<dl> 1310<dt><b><tt>typedef enum { go_text, 1311go_graphics } graphic_object_type; int 1312(*get_alpha_bits)(gx_device *dev, 1313graphic_object_type type)</tt></b> <b><em>[OPTIONAL] [OBSOLETE]</em></b> 1314<dd>This procedure is no longer used: it is replaced by the 1315color_info.anti_alias member of the driver structure. However, it still 1316appears in the driver procedure vector for backward compatibility. It 1317should never be called, and drivers should not implement it. 1318</dl> 1319 1320<dl> 1321<dt><b><tt>void (*update_spot_equivalent_colors)(gx_device *, 1322const gs_state *)</tt></b> 1323<b><em>[OPTIONAL]</em></b> 1324<dd>This routine provides a method for the device to gather an equivalent 1325color for spot colorants. This routine is called when a Separation or DeviceN 1326color space is installed. See comments at the start of 1327<a href="../src/gsequivc.c">gsequivc.c</a>. Note: This procedure is only needed 1328for devices that support spot colorants and also need to have an equivalent 1329color for simulating the appearance of the spot colorants. 1330</dl> 1331 1332<h3><a name="Pixel_level_drawing"></a>Pixel-level drawing</h3> 1333 1334<p> 1335This group of drawing operations specifies data at the pixel level. All 1336drawing operations use device coordinates and device color values. 1337 1338<dl> 1339<dt><b><tt>int (*fill_rectangle)(gx_device *, int x, 1340int y, int width, int height, 1341gx_color_index color)</tt></b> 1342<dd>Fill a rectangle with a color. The set of pixels filled is {(px,py) | 1343x <= px < x + width and y <= py < y + height}. In other words, 1344the point <em>(x,y)</em> is included in the rectangle, as are 1345<em>(x+w-1,y)</em>, <em>(x,y+h-1)</em>, and <em>(x+w-1,y+h-1)</em>, but 1346<b><em>not</em></b> <em>(x+w,y)</em>, <em>(x,y+h)</em>, or 1347<em>(x+w,y+h)</em>. If <b><tt>width</tt></b> <= 0 or 1348height <= 0, <b><tt>fill_rectangle</tt></b> should return 0 1349without drawing anything. 1350 1351<p> 1352Note that <b><tt>fill_rectangle</tt></b> is the only non-optional procedure 1353in the driver interface. 1354</dl> 1355 1356<h4><a name="Bitmap_imaging"></a>Bitmap imaging</h4> 1357 1358<p> 1359Bitmap (or pixmap) images are stored in memory in a nearly standard way. 1360The first byte corresponds to <em>(0,0)</em> in the image coordinate 1361system: bits (or polybit color values) are packed into it left to right. 1362There may be padding at the end of each scan line: the distance from one 1363scan line to the next is always passed as an explicit argument. 1364 1365<dl> 1366<dt><b><tt>int (*copy_mono)(gx_device *, 1367const unsigned char *data, int data_x, int raster, 1368gx_bitmap_id id, int x, int y, int width, 1369int height, gx_color_index color0, 1370gx_color_index color1)</tt></b> <b><em>[OPTIONAL]</em></b> 1371<dd>Copy a monochrome image (similar to the PostScript image operator). 1372Each scan line is raster bytes wide. Copying begins at 1373(<b><tt>data_x</tt></b>,0) and transfers a rectangle of the given width and 1374height to the device at device coordinate <em>(x,y)</em>. (If the transfer 1375should start at some non-zero y value in the data, the caller can adjust 1376the data address by the appropriate multiple of the raster.) The copying 1377operation writes device color <b><tt>color0</tt></b> at each 0-bit, and 1378<b><tt>color1</tt></b> at each 1-bit: if <b><tt>color0</tt></b> or 1379<b><tt>color1</tt></b> is <b><tt>gx_no_color_index</tt></b>, the device 1380pixel is unaffected if the image bit is 0 or 1 respectively. If 1381<b><tt>id</tt></b> is different from <b><tt>gx_no_bitmap_id</tt></b>, it 1382identifies the bitmap contents unambiguously; a call with the same 1383<b><tt>id</tt></b> will always have the same <b><tt>data</tt></b>, 1384<b><tt>raster</tt></b>, and data contents. 1385 1386<p> 1387This operation, with 1388<b><tt>color0</tt></b> = <b><tt>gx_no_color_index</tt></b>, is 1389the workhorse for text display in Ghostscript, so implementing it 1390efficiently is very important. 1391</dl> 1392 1393<dl> 1394<dt><b><tt>int (*tile_rectangle)(gx_device *, 1395const gx_tile_bitmap *tile, int x, int y, 1396int width, int height, gx_color_index color0, 1397gx_color_index color1, int phase_x, int phase_y)</tt></b> 1398<b><em>[OPTIONAL] [OBSOLETE]</em></b> 1399<dd>This procedure is still supported, but has been superseded by 1400<b><tt>strip_tile_rectangle</tt></b>. New drivers should implement 1401<b><tt>strip_tile_rectangle</tt></b>; if they cannot cope with non-zero 1402shift values, they should test for this explicitly and call the default 1403implementation (<b><tt>gx_default_strip_tile_rectangle</tt></b>) if 1404shift != 0. Clients should call 1405<b><tt>strip_tile_rectangle</tt></b>, not <b><tt>tile_rectangle</tt></b>. 1406</dl> 1407 1408<dl> 1409<dt><b><tt>int (*strip_tile_rectangle)(gx_device *, 1410const gx_strip_bitmap *tile, int x, int y, 1411int width, int height, gx_color_index color0, 1412gx_color_index color1, int phase_x, int phase_y)</tt></b> 1413<b><em>[OPTIONAL]</em></b> 1414<dd>Tile a rectangle. Tiling consists of doing multiple 1415<b><tt>copy_mono</tt></b> operations to fill the rectangle with copies of 1416the tile. The tiles are aligned with the device coordinate system, to 1417avoid "seams". Specifically, the (<b><tt>phase_x</tt></b>, 1418<b><tt>phase_y</tt></b>) point of the tile is aligned with the origin of 1419the device coordinate system. (Note that this is backwards from the 1420PostScript definition of halftone phase.) <b><tt>phase_x</tt></b> and 1421<b><tt>phase_y</tt></b> are guaranteed to be in the range 1422<em>[0..</em><b><tt>tile->width</tt></b><em>)</em> and 1423<em>[0..</em><b><tt>tile->height</tt></b><em>)</em> respectively. 1424 1425<p> 1426If <b><tt>color0</tt></b> and <b><tt>color1</tt></b> are both 1427<b><tt>gx_no_color_index</tt></b>, then the tile is a color pixmap, not a 1428bitmap: see the next section. 1429 1430<p> 1431This operation is the workhorse for halftone filling in Ghostscript, so 1432implementing it efficiently for solid tiles (that is, where either 1433<b><tt>color0</tt></b> and <b><tt>color1</tt></b> are both 1434<b><tt>gx_no_color_index</tt></b>, for colored halftones, or neither one is 1435<b><tt>gx_no_color_index</tt></b>, for monochrome halftones) is very 1436important. 1437</dl> 1438 1439<h4><a name="Pixmap_imaging"></a>Pixmap imaging</h4> 1440 1441<p> 1442Pixmaps are just like bitmaps, except that each pixel occupies more than 1443one bit. All the bits for each pixel are grouped together (this is 1444sometimes called "chunky" or "Z" format). For <b><tt>copy_color</tt></b>, 1445the number of bits per pixel is given by the 1446<b><tt>color_info.depth</tt></b> parameter in the device structure: the 1447legal values are 1, 2, 4, 8, 16, 24, 32, 40, 48, 56, or 64. The pixel 1448values are device color codes (that is, whatever it is that 1449<b><tt>encode_color</tt></b> returns). 1450 1451<dl> 1452<dt><b><tt>int (*copy_color)(gx_device *, 1453const unsigned char *data, int data_x, int raster, 1454gx_bitmap_id id, int x, int y, int width, 1455int height)</tt></b> <b><em>[OPTIONAL]</em></b> 1456<dd>Copy a color image with multiple bits per pixel. The raster is in 1457bytes, but <b><tt>x</tt></b> and <b><tt>width</tt></b> are in pixels, not 1458bits. If <b><tt>id</tt></b> is different from 1459<b><tt>gx_no_bitmap_id</tt></b>, it identifies the bitmap contents 1460unambiguously; a call with the same <b><tt>id</tt></b> will always have the 1461same <b><tt>data</tt></b>, <b><tt>raster</tt></b>, and data contents. 1462 1463<p> 1464We do not provide a separate procedure for tiling with a pixmap; instead, 1465<b><tt>tile_rectangle</tt></b> can also take colored tiles. This is 1466indicated by the <b><tt>color0</tt></b> and <b><tt>color1</tt></b> 1467arguments' both being <b><tt>gx_no_color_index</tt></b>. In this case, as 1468for <b><tt>copy_color</tt></b>, the <b><tt>raster</tt></b> and 1469<b><tt>height</tt></b> in the "bitmap" are interpreted as for real bitmaps, 1470but the <b><tt>x</tt></b> and <b><tt>width</tt></b> are in pixels, not 1471bits. 1472</dl> 1473 1474<h4><a name="Compositing"></a>Compositing</h4> 1475 1476<p> 1477In addition to direct writing of opaque pixels, devices must also support 1478compositing. Currently two kinds of compositing are defined 1479(<b><tt>RasterOp</tt></b> and alpha-based), but more may be added in the 1480future. 1481 1482<blockquote> 1483<b><em>THIS AREA OF THE INTERFACE IS SOMEWHAT UNSTABLE: USE AT YOUR OWN 1484RISK.</em></b> 1485</blockquote> 1486 1487<dl> 1488<dt><b><tt>int (*copy_alpha)(gx_device *dev, 1489const unsigned char *data, int data_x, int raster, 1490gx_bitmap_id id, int x, int y, int width, 1491int height, gx_color_index color, int depth)</tt></b> 1492<b><em>[OPTIONAL]</em></b> 1493<dd>This procedure is somewhat misnamed: it was added to the interface 1494before we really understood alpha channel and compositing. 1495 1496<p> 1497Fill a given region with a given color modified by an individual alpha 1498value for each pixel. For each pixel, this is equivalent to 1499alpha-compositing with a source pixel whose alpha value is obtained from 1500the pixmap (<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, and 1501<b><tt>raster</tt></b>) and whose color is the given color (which has 1502<b><em>not</em></b> been premultiplied by the alpha value), using the Sover 1503rule. <b><tt>depth</tt></b>, the number of bits per alpha value, is either 15042 or 4, and in any case is always a value returned by a previous call on 1505the <b><tt>get_alpha_bits</tt></b> procedure. Note that if 1506<b><tt>get_alpha_bits</tt></b> always returns 1, this procedure will never 1507be called. 1508</dl> 1509 1510<dl> 1511<dt><b><tt>int (*create_compositor)(dev_t *dev, 1512gx_device_t **pcdev, const gs_composite_t *pcte, 1513const gs_imager_state *pis, gs_memory_t *memory)</tt></b> 1514<b><em>[OPTIONAL]</em></b> 1515<dd>Create a new device (called a "compositing device" or "compositor") 1516that will composite data written to it with the device's existing data, 1517according to the compositing function defined by <b><tt>*pcte</tt></b>. 1518Devices will normally implement this in one of the following standard ways: 1519 1520<ul> 1521<li>Devices that don't do any imaging and don't forward any imaging 1522operations (for example, the null device, the hit detection device, and the 1523clipping list accumulation device) simply return themselves, which 1524effectively ignores the compositing function. 1525 1526<li>"Leaf" devices that do imaging and have no special optimizations for 1527compositing (for example, some memory devices) ask the 1528<b><tt>gs_composite_t</tt></b> to create a default compositor. 1529 1530<li>Leaf devices that can implement some kinds of compositing operation 1531efficiently (for example, monobit memory devices and RasterOp) inspect the 1532type and values of <b><tt>*pcte</tt></b> to determine whether it specifies 1533such an operation: if so, they create a specialized compositor, and if not, 1534they ask the <b><tt>gs_composite_t</tt></b> to create a default compositor. 1535</ul> 1536 1537<p> 1538Other kinds of forwarding devices, which don't fall into any of these 1539categories, require special treatment. In principle, what they do is ask 1540their target to create a compositor, and then create and return a copy of 1541themselves with the target's new compositor as the target of the copy. 1542There is a possible default implementation of this approach: if the 1543original device was <b>D</b> with target <b>T</b>, and <b>T</b> creates a 1544compositor <b>C</b>, then the default implementation creates a device 1545<b>F</b> that for each operation temporarily changes <b>D</b>'s target to 1546<b>C</b>, forwards the operation to <b>D</b>, and then changes <b>D</b>'s 1547target back to <b>T</b>. However, the Ghostscript library currently only 1548creates a compositor with an imaging forwarding device as target in a few 1549specialized situations (banding, and bounding box computation), and these 1550are handled as special cases. 1551 1552<p> 1553Note that the compositor may have a different color space, color 1554representation, or bit depth from the device to which it is compositing. 1555For example, alpha-compositing devices use standard-format chunky color 1556even if the underlying device doesn't. 1557 1558<p> 1559Closing a compositor frees all of its storage, including the compositor 1560itself. However, since the <b><tt>create_compositor</tt></b> call may 1561return the same device, clients must check for this case, and only call the 1562close procedure if a separate device was created. 1563</dl> 1564 1565<p> 1566<font size="+1"> 1567<b><em>[strip_]copy_rop WILL BE SUPERSEDED BY COMPOSITORS</em></b> 1568</font> 1569 1570<dl> 1571<dt><b><tt>int (*copy_rop)(gx_device *dev, 1572const byte *sdata, int sourcex, uint sraster, 1573gx_bitmap_id id, const gx_color_index *scolors, 1574const gx_tile_bitmap *texture, 1575const gx_color_index *tcolors, int x, int y, 1576int width, int height, int phase_x, int phase_y, 1577int command)</tt></b> <b><em>[OPTIONAL]</em></b> 1578<dd>This procedure is still supported, but has been superseded by 1579<b><tt>strip_copy_rop</tt></b>. New drivers should implement 1580<b><tt>strip_copy_rop</tt></b>; if they cannot cope with non-zero shift 1581values in the texture, they should test for this explicitly and call the 1582default implementation (<b><tt>gx_default_strip_copy_rop</tt></b>) if 1583shift != 0. Clients should call <b><tt>strip_copy_rop</tt></b>, 1584not <b><tt>copy_rop</tt></b>. 1585</dl> 1586 1587<dl> 1588<dt><b><tt>int (*strip_copy_rop)(gx_device *dev, 1589const byte *sdata, int sourcex, uint sraster, 1590gx_bitmap_id id, const gx_color_index *scolors, 1591const gx_strip_bitmap *texture, 1592const gx_color_index *tcolors, int x, int y, 1593int width, int height, int phase_x, int phase_y, 1594int command)</tt></b> <b><em>[OPTIONAL]</em></b> 1595<dd>Combine an optional source image <b>S</b> (as for 1596<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b>) and an optional 1597texture <b>T</b> (a tile, as for <b><tt>tile_rectangle</tt></b>) with the 1598existing bitmap or pixmap <b>D</b> held by the driver, pixel by pixel, 1599using any 3-input Boolean operation as modified by "transparency" flags: 1600schematically, set <b>D = f(D,S,T)</b>, computing <b>f</b> in RGB 1601space rather than using actual device pixel values. <b>S</b> and <b>T</b> 1602may each (independently) be a solid color, a bitmap with "foreground" and 1603"background" colors, or a pixmap. This is a complex (and currently rather 1604slow) operation. The arguments are as follows: 1605 1606<blockquote><table cellpadding=0 cellspacing=0> 1607<tr valign=top> <td><b><tt>dev</tt></b> 1608 <td> 1609 <td>the device, as for all driver procedures 1610<tr valign=top> <td><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>, <b><tt>sraster</tt></b>, <b><tt>id</tt></b>, <b><tt>scolors</tt></b> 1611 <td> 1612 <td>specify <b>S</b>, <a href="#S_spec">see below</a> 1613<tr valign=top> <td><b><tt>texture</tt></b>, <b><tt>tcolors</tt></b> 1614 <td> 1615 <td>specify <b>T</b>, <a href="#T_spec">see below</a> 1616<tr valign=top> <td><b><tt>x</tt></b>, <b><tt>y</tt></b>, <b><tt>width</tt></b>, <b><tt>height</tt></b> 1617 <td> 1618 <td>as for the other copy and fill procedures 1619<tr valign=top> <td><b><tt>phase_x</tt></b>, <b><tt>phase_y</tt></b> 1620 <td> 1621 <td>part of <b>T</b> specification, <a href="#T_spec">see below</a> 1622<tr valign=top> <td><b><tt>command</tt></b> 1623 <td> 1624 <td><a href="#F_spec">see below</a> 1625</table></blockquote> 1626</dl> 1627 1628<h5><a name="S_spec"></a>The source specification S</h5> 1629 1630<p> 1631As noted above, the source <b>S</b> may be a solid color, a bitmap, or a 1632pixmap. If <b>S</b> is a solid color: 1633 1634<ul> 1635<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>, 1636<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> are irrelevant. 1637 1638<li><b><tt>scolors</tt></b> points to two <b><tt>gx_color_index</tt></b> 1639values; <b><tt>scolors[0]</tt></b> = <b><tt>scolors[1]</tt></b> = the 1640color. 1641</ul> 1642 1643<p> 1644If <b>S</b> is a bitmap: 1645 1646<ul> 1647<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>, 1648<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> arguments are as for 1649<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b> 1650(<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, <b><tt>raster</tt></b>, 1651<b><tt>id</tt></b>), and specify a source bitmap. 1652 1653<li><b><tt>scolors</tt></b> points to two <b><tt>gx_color_index</tt></b> 1654values; <b><tt>scolors[0]</tt></b> is the background color (the color 1655corresponding to 0-bits in the bitmap), <b><tt>scolors[1]</tt></b> is the 1656foreground color (the color corresponding to 1-bits in the bitmap). 1657</ul> 1658 1659<p> 1660If <b>S</b> is a pixmap: 1661 1662<ul> 1663<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>, 1664<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> arguments are as for 1665<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b> 1666(<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, <b><tt>raster</tt></b>, 1667<b><tt>id</tt></b>), and specify a source pixmap whose depth is the same as 1668the depth of the destination. 1669 1670<li><b><tt>scolors</tt></b> is <b><tt>NULL</tt></b>. 1671</ul> 1672 1673<p> 1674Note that if the source is a bitmap with background=0 and foreground=1, and 1675the destination is 1 bit deep, then the source can be treated as a pixmap 1676(scolors=<b><tt>NULL</tt></b>). 1677 1678<h5><a name="T_spec"></a>The texture specification T</h5> 1679 1680<p> 1681Similar to the source, the texture <b>T</b> may be a solid color, a bitmap, 1682or a pixmap. If <b>T</b> is a solid color: 1683 1684<ul> 1685<li>The texture pointer is irrelevant. 1686 1687<li><b><tt>tcolors</tt></b> points to two <b><tt>gx_color_index</tt></b> 1688values; <b><tt>tcolors[0]</tt></b> = <b><tt>tcolors[1]</tt></b> = the 1689color. 1690</ul> 1691 1692<p> 1693If <b>T</b> is a bitmap: 1694 1695<ul> 1696<li>The texture argument points to a <b><tt>gx_tile_bitmap</tt></b>, as for 1697the <b><tt>tile_rectangle</tt></b> procedure. Similarly, 1698<b><tt>phase_x</tt></b> and <b><tt>phase_y</tt></b> specify the offset of 1699the texture relative to the device coordinate system origin, again as for 1700<b><tt>tile_rectangle</tt></b>. The tile is a bitmap (1 bit per pixel). 1701 1702<li><b><tt>tcolors</tt></b> points to two <b><tt>gx_color_index</tt></b> 1703values; <b><tt>tcolors[0]</tt></b> is the background color (the color 1704corresponding to 0-bits in the bitmap), <b><tt>tcolors[1]</tt></b> is the 1705foreground color (the color corresponding to 1-bits in the bitmap). 1706</ul> 1707 1708<p> 1709If <b>T</b> is a pixmap: 1710 1711<ul> 1712<li>The texture argument points to a <b><tt>gx_tile_bitmap</tt></b> whose 1713depth is the same as the depth of the destination. 1714 1715<li>tcolors is <b><tt>NULL</tt></b>. 1716</ul> 1717 1718<p> 1719Again, if the texture is a bitmap with background=0 and foreground=1, and 1720the destination depth is 1, the texture bitmap can be treated as a pixmap 1721(tcolors=<b><tt>NULL</tt></b>). 1722 1723<p> 1724Note that while a source bitmap or pixmap has the same width and height as 1725the destination, a texture bitmap or pixmap has its own width and height 1726specified in the <b><tt>gx_tile_bitmap</tt></b> structure, and is 1727replicated or clipped as needed. 1728 1729<h5><a name="F_spec"></a>The function specification f</h5> 1730 1731<p> 1732"Command" indicates the raster operation and transparency as follows: 1733 1734<blockquote><table cellpadding=0 cellspacing=0> 1735<tr valign=bottom> 1736 <th>Bits 1737 <td> 1738 <td> 1739<tr valign=top> <td>7-0 1740 <td> 1741 <td>raster op 1742<tr valign=top> <td>8 1743 <td> 1744 <td>0 if source opaque, 1 if source transparent 1745<tr valign=top> <td>9 1746 <td> 1747 <td>0 if texture opaque, 1 if texture transparent 1748<tr valign=top> <td>?-10 1749 <td> 1750 <td>unused, must be 0 1751</table></blockquote> 1752 1753<p> 1754The raster operation follows the Microsoft and H-P specification. It is an 17558-element truth table that specifies the output value for each of the 1756possible 2×2×2 input values as follows: 1757 1758<blockquote><table cellpadding=0 cellspacing=0> 1759<tr valign=bottom> 1760 <th>Bit 1761 <td> 1762 <th>Texture 1763 <td> 1764 <th>Source 1765 <td> 1766 <th>Destination 1767<tr> <td colspan=7><hr> 1768<tr valign=top> <td align=center>7 1769 <td> 1770 <td align=center>1 1771 <td> 1772 <td align=center>1 1773 <td> 1774 <td align=center>1 1775<tr valign=top> <td align=center>6 1776 <td> 1777 <td align=center>1 1778 <td> 1779 <td align=center>1 1780 <td> 1781 <td align=center>0 1782<tr valign=top> <td align=center>5 1783 <td> 1784 <td align=center>1 1785 <td> 1786 <td align=center>0 1787 <td> 1788 <td align=center>1 1789<tr valign=top> <td align=center>4 1790 <td> 1791 <td align=center>1 1792 <td> 1793 <td align=center>0 1794 <td> 1795 <td align=center>0 1796<tr valign=top> <td align=center>3 1797 <td> 1798 <td align=center>0 1799 <td> 1800 <td align=center>1 1801 <td> 1802 <td align=center>1 1803<tr valign=top> <td align=center>2 1804 <td> 1805 <td align=center>0 1806 <td> 1807 <td align=center>1 1808 <td> 1809 <td align=center>0 1810<tr valign=top> <td align=center>1 1811 <td> 1812 <td align=center>0 1813 <td> 1814 <td align=center>0 1815 <td> 1816 <td align=center>1 1817<tr valign=top> <td align=center>0 1818 <td> 1819 <td align=center>0 1820 <td> 1821 <td align=center>0 1822 <td> 1823 <td align=center>0 1824</table></blockquote> 1825 1826<p> 1827Transparency affects the output in the following way. A source or texture 1828pixel is considered transparent if its value is all 1s (for instance, 1 for 1829bitmaps, <tt>0xffffff</tt> for 24-bit RGB pixmaps) <b><em>and</em></b> the 1830corresponding transparency bit is set in the command. For each pixel, the 1831result of the Boolean operation is written into the destination iff neither 1832the source nor the texture pixel is transparent. (Note that the HP 1833RasterOp specification, on which this is based, specifies that if the 1834source and texture are both all 1s and the command specifies transparent 1835source and opaque texture, the result <b><em>should</em></b> be written in 1836the output. We think this is an error in the documentation.) 1837 1838<h5><a name="Compositing_notes"></a>Notes</h5> 1839 1840<p> 1841<b><tt>copy_rop</tt></b> is defined to operate on pixels in RGB space, 1842again following the HP and Microsoft specification. For devices that 1843don't use RGB (or gray-scale with black = 0, white = all 1s) as their 1844native color representation, the implementation of <b><tt>copy_rop</tt></b> 1845must convert to RGB or gray space, do the operation, and convert back (or 1846do the equivalent of this). Here are the <b><tt>copy_rop</tt></b> 1847equivalents of the most important previous imaging calls. We assume the 1848declaration: 1849 1850<blockquote><b><tt> 1851static const gx_color_index white2[2] = { 1, 1 }; 1852</tt></b></blockquote> 1853 1854<p> 1855Note that <b><tt>rop3_S</tt></b> may be replaced by any other Boolean operation. 1856For monobit devices, we assume that black = 1. 1857 1858<blockquote> 1859<pre>/* For all devices: */ 1860(*fill_rectangle)(dev, x, y, w, h, color) ==> 1861 1862 { gx_color_index colors[2]; 1863 colors[0] = colors[1] = color; 1864 (*dev_proc(dev, copy_rop))(dev, NULL, 0, 0, gx_no_bitmap_id, colors, 1865 NULL, colors /*irrelevant*/, 1866 x, y, w, h, 0, 0, rop3_S); 1867 } 1868 1869/* For black-and-white devices only: */ 1870(*copy_mono)(dev, base, sourcex, sraster, id, 1871 x, y, w, h, (gx_color_index)0, (gx_color_index)1) ==> 1872 1873 (*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, NULL, 1874 NULL, white2 /*irrelevant*/, 1875 x, y, w, h, 0, 0, rop3_S); 1876 1877/* For color devices, where neither color0 nor color1 is gx_no_color_index: */ 1878(*copy_mono)(dev, base, sourcex, sraster, id, 1879 x, y, w, h, color0, color1) ==> 1880 1881 { gx_color_index colors[2]; 1882 colors[0] = color0, colors[1] = color1; 1883 (*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, colors, 1884 NULL, white2 /*irrelevant*/, 1885 x, y, w, h, 0, 0, rop3_S); 1886 } 1887 1888/* For black-and-white devices only: */ 1889(*copy_mono)(dev, base, sourcex, sraster, id, 1890 x, y, w, h, gx_no_color_index, (gx_color_index)1) ==> 1891 1892 (*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, NULL, 1893 NULL, white2 /*irrelevant*/, 1894 x, y, w, h, 0, 0, 1895 rop3_S | lop_S_transparent); 1896 1897/* For all devices: */ 1898(*copy_color)(dev, base, sourcex, sraster, id, 1899 x, y, w, h) ==> [same as first copy_mono above] 1900 1901/* For black-and-white devices only: */ 1902(*tile_rectangle)(dev, tile, x, y, w, h, 1903 (gx_color_index)0, (gx_color_index)1, px, py) ==> 1904 1905 (*dev_proc(dev, copy_rop))(dev, NULL, 0, 0, gx_no_bitmap_id, 1906 white2 /*irrelevant*/, 1907 tile, NULL, 1908 x, y, w, h, px, py, rop3_T) 1909</pre></blockquote> 1910 1911<h3><a name="Polygon_level_drawing"></a>Polygon-level drawing</h3> 1912 1913<p> 1914In addition to the pixel-level drawing operations that take integer device 1915coordinates and pure device colors, the driver interface includes 1916higher-level operations that draw polygons using fixed-point coordinates, 1917possibly halftoned colors, and possibly a non-default logical operation. 1918 1919<p> 1920The <b><tt>fill_</tt></b>* drawing operations all use the center-of-pixel 1921rule: a pixel is colored iff its center falls within the polygonal region 1922being filled. If a pixel center <em>(X+0.5,Y+0.5)</em> falls exactly on 1923the boundary, the pixel is filled iff the boundary is horizontal and the 1924filled region is above it, or the boundary is not horizontal and the filled 1925region is to the right of it. 1926 1927<dl> 1928<dt><b><tt>int (*fill_trapezoid)(gx_device *dev, const 1929gs_fixed_edge *left, const gs_fixed_edge *right, 1930fixed ybot, fixed ytop, bool swap_axes, 1931const gx_drawing_color *pdcolor, 1932gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b> 1933<dd>Fill a trapezoid. The bottom and top edges are parallel to the x 1934axis, and are defined by <b><tt>ybot</tt></b> and <b><tt>ytop</tt></b>, 1935respectively. The left and right edges are defined by <b><tt>left</tt></b> 1936and <b><tt>right</tt></b>. Both of these represent lines (<b><tt>gs_fixed_edge</tt></b> 1937is defined in <a href="../src/gxdevcli.h">gxdevcli.h</a> and consists 1938of <b><tt>gs_fixed_point</tt></b> <b><tt>start</tt></b> and <b><tt>end</tt></b> points). 1939The y coordinates of these lines need not have any specific relation to 1940<b><tt>ybot</tt></b> and <b><tt>ytop</tt></b>. The routine is defined this way so 1941that the filling algorithm can subdivide edges and still guarantee 1942that the exact same pixels will be filled. If 1943<b><tt>swap_axes</tt></b> is set, the meanings of X and Y are 1944interchanged. 1945</dl> 1946<dt><b><tt>int (*fill_parallelogram)(gx_device *dev, 1947fixed px, fixed py, fixed ax, fixed ay, fixed bx, 1948fixed by, const gx_drawing_color *pdcolor, 1949gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b> 1950<dd>Fill a parallelogram whose corners are <em>(px,py)</em>, 1951<em>(px+ax,py+ay)</em>, <em>(px+bx,py+by)</em>, and 1952<em>(px+ax+bx,py+ay+by)</em>. There are no constraints on the values of 1953any of the parameters, so the parallelogram may have any orientation 1954relative to the coordinate axes. 1955 1956 1957<dl> 1958<dt><b><tt>int (*fill_triangle)(gx_device *dev, fixed px, 1959fixed py, fixed ax, fixed ay, fixed bx, fixed by, 1960const gx_drawing_color *pdcolor, 1961gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b> 1962<dd>Fill a triangle whose corners are <em>(px,py)</em>, 1963<em>(px+ax,py+ay)</em>, and <em>(px+bx,py+by)</em>. 1964</dl> 1965 1966<dl> 1967<dt><b><tt>int (*draw_thin_line)(gx_device *dev, 1968fixed fx0, fixed fy0, fixed fx1, fixed fy1, 1969const gx_drawing_color *pdcolor, 1970gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b> 1971<dd>Draw a one-pixel-wide line from <em>(fx0,fy0)</em> to 1972<em>(fx1,fy1)</em>. 1973</dl> 1974 1975<dl> 1976<dt><b><tt>int (*draw_line)(gx_device *dev, int x0, int y0, 1977int x1, int y1, gx_color_index color)</tt></b> 1978<b><em>[OPTIONAL] [OBSOLETE]</em></b> 1979<dd>This procedure is no longer used: it is replaced by the draw_thin_line 1980procedure. However, still appears in the driver procedure vector for 1981backward compatibility. It should never be called, and drivers should not 1982implement it. 1983</dl> 1984 1985<h3><a name="Linear_color_drawing"></a>Linear color drawing</h3> 1986 1987<p> 1988Linear color functions allow fast high quality rendering of 1989shadings on continuous tone devices. They implement filling simple areas 1990with a lineary varying color. These functions are not called if the device applies halftones, 1991or uses a non-separable or a non-linear color model. 1992 1993<dl> 1994<dt><b><tt> int (*fill_linear_color_triangle) 1995 (dev_t *dev, const gs_fill_attributes *fa, 1996 const gs_fixed_point *p0, const gs_fixed_point *p1, 1997 const gs_fixed_point *p2, 1998 const frac31 *c0, const frac31 *c1, const frac31 *c2) 1999</tt></b> 2000<b><em>[OPTIONAL]</em></b> 2001<dd>This function is the highest level one within the linear color function group. 2002It fills a triangle with a linearly varying color. 2003Arguments specify 3 points in the device space - vertices of a triangle, and their colors. 2004The colors are represented as vectors of positive fractional numbers, each of which 2005represents a color component value in the interval <b><tt>[0,1]</tt></b>. 2006The number of components in a vector in the number of color 2007components in the device (process) color model. 2008<dd> 2009The implementation fills entire triangle. 2010The filling rule is same as for <a href="#Polygon_level_drawing">Polygon-level drawing</a>. 2011A color for each pixel within the triangle to be computed as a linear interpolation 2012of vertex colors. 2013<dd> 2014The implementation may reject the request if the area or the color appears too complex 2015for filling in a single action. For doing that the implementation returns 0 and must not 2016paint any pixel. In this case the graphics library will perform a subdivision of the area 2017into smaller triangles and call the function again with smaller areas. 2018<dd> 2019<b><em>Important note :</em></b> Do not try to decompose the area within 2020the implementation of <b><tt> fill_linear_color_triangle </tt></b>, because 2021it can break the plane coverage contiguity and cause a dropout. 2022Instead that request graphics library to perform the decomposition. 2023The graphics libary is smart enough to do that properly. 2024<dd> 2025<b><em>Important note :</em></b> 2026The implementation must handle a special case, when only 2 colors are specified. 2027It happens if <b><tt>p3</tt></b> one is <b><tt>NULL</tt></b>. 2028This means that the color does not depend on the X coordinate, 2029i.e. it forms a linear gradient along the Y axis. 2030The implementation must not reject (return 0) such cases. 2031<dd> 2032<b><em>Important note :</em></b>The device color component 2033value 1 may be represented with several hexadecimal values : 2034<b><tt>0x7FFF0000</tt></b>, <b><tt>0x7FFFF000</tt></b>, <b><tt>0x7FFFFF00</tt></b>, etc., 2035because the precision here exceeds the color precision of the device. 2036To convert a <b><tt>frac31</tt></b> value into a device color component value, 2037fist drop (ignore) the sign bit, then drop least significant bits - 2038so many ones as you need to fit the device color precision. 2039<dd> 2040<b><em>Important note :</em></b> The <b><tt>fa</tt></b> argument may contain 2041the <b><tt>swap_axes</tt></b> bit set. In this case the implementation must swap (transpoze) 2042<b><tt>X</tt></b> and <b><tt>Y</tt></b> axes. 2043<dd> 2044<b><em>Important note :</em></b> The implementation must not paint outside the 2045clipping rectangle specified in the <b><tt>fa</tt></b> argument. 2046If <b><tt>fa->swap_axes</tt></b> is true, the clipping rectangle is transposed. 2047<dd> 2048See <b><tt> gx_default_fill_linear_color_triangle </tt></b> 2049in <b><tt>gdevddrw.c</tt></b> as a sample code. 2050</dl> 2051 2052 2053<dl> 2054<dt><b><tt> int (*fill_linear_color_trapezoid) 2055 (dev_t *dev, const gs_fill_attributes *fa, 2056 const gs_fixed_point *p0, const gs_fixed_point *p1, 2057 const gs_fixed_point *p2, const gs_fixed_point *p3, 2058 const frac31 *c0, const frac31 *c1, 2059 const frac31 *c2, const frac31 *c2) 2060</tt></b> 2061<b><em>[OPTIONAL]</em></b> 2062<dd>This function is a lower level one within the linear color function group. 2063The default implementation of <b><tt> fill_linear_color_triangle </tt></b> 2064calls this function 1-2 times per triangle. Besides that, 2065this function may be called by the graphics library for other special cases, 2066when a decomposition into triangles appears undiserable. 2067<dd> 2068Rather the prototype can specify a bilinear color, 2069we assume that the implementation handles linear colors only. 2070This means that the implementation can ignore any of <b><tt> c0, c1, c2, c3 </tt></b>. 2071The graphics library takes a special care of the color linearity 2072when calling this function. The reason for passing all 4 color arguments 2073is to avoid color precision problems. 2074<dd> 2075Similarly to <b><tt> fill_linear_color_triangle </tt></b>, 2076this function may be called with only 2 colors, and may reject too comple areas. 2077All those important notes are applicable here. 2078<dd> 2079A sample code may be found in in <b><tt>gxdtfill.h</tt></b>, rather it's a kind of complicated. 2080A linear color function is generated from it as <b><tt> gx_fill_trapezoid_ns_lc </tt></b> 2081with the following template parametres : 2082 2083<pre> 2084#define LINEAR_COLOR 1 2085#define EDGE_TYPE gs_linear_color_edge 2086#define FILL_ATTRS const gs_fill_attributes * 2087#define CONTIGUOUS_FILL 0 2088#define SWAP_AXES 0 2089#define FILL_DIRECT 1 2090</pre> 2091See the helplers <b><tt>init_gradient</tt></b>, 2092<b><tt>step_gradient</tt></b> (defined in in <b><tt>gdevddrw.c</tt></b>), how to manage colors. 2093See <b><tt>check_gradient_overflow</tt></b> 2094(defined in in <b><tt>gdevddrw.c</tt></b>), as an example of an area 2095that can't be painted in a single action due to 64-bits fixed overflows. 2096 2097</dl> 2098 2099<dl> 2100<dt><b><tt> int (*fill_linear_color_scanline) 2101 (dev_t *dev, const gs_fill_attributes *fa, 2102 int i, int j, int w, 2103 const frac31 *c0, 2104 const int32_t *c0_f, 2105 const int32_t *cg_num, 2106 int32_t cg_den) 2107</tt></b> 2108<b><em>[OPTIONAL]</em></b> 2109<dd>This function is the lowest level one within the linear color function group. 2110It implements filling a scanline with a linearly varying color. 2111The default implementation for <b><tt> fill_linear_color_trapezoid </tt></b> 2112calls this function, and there are no other calls to it from the graphics libary. 2113Thus if the device implements <b><tt> fill_linear_color_triangle </tt></b> and 2114<b><tt> fill_linear_color_trapezoid </tt></b> by own means, 2115this function may be left unimplemented. 2116<dd> 2117<b><tt>i</tt></b> and <b><tt>j</tt></b> specify device coordinates (indices) 2118of the starting pixel of the scanline, <b><tt>w</tt></b> specifies the 2119width of the scanline, i.e. the number of pixels to be painted to the right from 2120the starting pixel, including the starting pixel. 2121<dd> 2122<b><tt>c0</tt></b> specifies the color for the starting pixel 2123as a vector of fraction values, each of which represents 2124a color value in the interval <b><tt>[0,1]</tt></b>. 2125<dd> 2126<b><tt>c0_f</tt></b> specify a fraction part of the color for the starting pixel. 2127See the formula below about using it. 2128<dd> 2129<b><tt>cg_num</tt></b> specify a numerator for the color gradient - 2130a vector of values in <b><tt>[-1,1]</tt></b>, each of which correspond to a color component. 2131<dd> 2132<b><tt>cg_den</tt></b> specify the denominator for the color gradient - 2133a value in <b><tt>[-1,1]</tt></b>. 2134<dd><p> 2135The color for the pixel <b><tt>[i + k, j]</tt></b> to be computed like this : 2136<pre><b><tt> 2137 (double)(c0[n] + (c0_f[n] + cg_num[n] * k) / cg_den) / (1 ^ 31 - 1) 2138</tt></b></pre> 2139<dd>where <b><tt>0 <= k <= w </tt></b>, and <b><tt>n</tt></b> is a device color component index. 2140 2141<dd> 2142<b><em>Important note :</em></b> The <b><tt>fa</tt></b> argument may contain 2143the <b><tt>swap_axes</tt></b> bit set. In this case the implementation must swap (transpose) 2144<b><tt>X</tt></b> and <b><tt>Y</tt></b> axes. 2145<dd> 2146<b><em>Important note :</em></b> The implementation must not paint outside the 2147clipping rectangle specified in the <b><tt>fa</tt></b> argument. 2148If <b><tt>fa->swap_axes</tt></b> is true, the clipping rectangle is transposed. 2149<dd> 2150See <b><tt> gx_default_fill_linear_color_scanline</tt></b> 2151in <b><tt>gdevdsha.c</tt></b> as a sample code. 2152</dl> 2153 2154 2155<h3><a name="High_level_drawing"></a>High-level drawing</h3> 2156 2157<p> 2158In addition to the lower-level drawing operations described above, the 2159driver interface provides a set of high-level operations. Normally these 2160will have their default implementation, which converts the high-level 2161operation to the low-level ones just described; however, drivers that 2162generate high-level output formats such as CGM, or communicate with devices 2163that have firmware for higher-level operations such as polygon fills, may 2164implement these high-level operations directly. For more details, please 2165consult the source code, specifically: 2166 2167<blockquote><table cellpadding=0 cellspacing=0> 2168<tr valign=top> <th align=left>Header 2169 <td> 2170 <th align=left>Defines 2171<tr valign=top> <td><a href="../src/gxpaint.h">gxpaint.h</a> 2172 <td> 2173 <td><b><tt>gx_fill_params</tt></b>, <b><tt>gx_stroke_params</tt></b> 2174<tr valign=top> <td><a href="../src/gxfixed.h">gxfixed.h</a> 2175 <td> 2176 <td><b><tt>fixed</tt></b>, <b><tt>gs_fixed_point</tt></b> (used by 2177 <b><tt>gx_*_params</tt></b>) 2178<tr valign=top> <td><a href="../src/gxistate.h">gxistate.h</a> 2179 <td> 2180 <td><b><tt>gs_imager_state</tt></b> (used by <b><tt>gx_*_params</tt></b>) 2181<tr valign=top> <td><a href="../src/gxline.h">gxline.h</a> 2182 <td> 2183 <td><b><tt>gx_line_params</tt></b> (used by <b><tt>gs_imager_state</tt></b>) 2184<tr valign=top> <td><a href="../src/gslparam.h">gslparam.h</a> 2185 <td> 2186 <td>line cap/join values (used by <b><tt>gx_line_params</tt></b>) 2187<tr valign=top> <td><a href="../src/gxmatrix.h">gxmatrix.h</a> 2188 <td> 2189 <td><b><tt>gs_matrix_fixed</tt></b> (used by <b><tt>gs_imager_state</tt></b>) 2190<tr valign=top> <td><a href="../src/gspath.h">gspath.h</a>, <a href="../src/gxpath.h">gxpath.h</a>, <a href="../src/gzpath.h">gzpath.h</a> 2191 <td> 2192 <td><b><tt>gx_path</tt></b> 2193<tr valign=top> <td><a href="../src/gxcpath.h">gxcpath.h</a>, <a href="../src/gzcpath.h">gzcpath.h</a> 2194 <td> 2195 <td><b><tt>gx_clip_path</tt></b> 2196</table></blockquote> 2197 2198<p> 2199For a minimal example of how to implement the high-level drawing operations, 2200see <a href="../src/gdevtrac.c">gdevtrac.c</a>. 2201 2202<h4><a name="Paths"></a>Paths</h4> 2203 2204<dl> 2205<dt><b><tt>int (*fill_path)(gx_device *dev, 2206const gs_imager_state *pis, gx_path *ppath, 2207const gx_fill_params *params, 2208const gx_drawing_color *pdcolor, 2209const gx_clip_path *pcpath)</tt></b> <b><em>[OPTIONAL]</em></b> 2210<dd>Fill the given path, clipped by the given clip path, according to the 2211given parameters, with the given color. The clip path pointer may be 2212<b><tt>NULL</tt></b>, meaning do not clip. 2213<dd> 2214The implementation must paint the path with the specified device color, 2215which may be either a pure color, or a pattern. If the device can't 2216handle non-pure colors, it should check the color type and 2217call the default implementation gx_default_fill_path for cases, 2218which the device can't handle. The default implementation will perform 2219a subdivision of the area to be painted, and will 2220call other device virtual functions (such as fill_linear_color_triangle) 2221with simpler areas. 2222 2223</dl> 2224 2225<dl> 2226<dt><b><tt>int (*stroke_path)(gx_device *dev, 2227const gs_imager_state *pis, gx_path *ppath, 2228const gx_stroke_params *params, 2229const gx_drawing_color *pdcolor, 2230const gx_clip_path *pcpath)</tt></b> <b><em>[OPTIONAL]</em></b> 2231<dd>Stroke the given path, clipped by the given clip path, according to the 2232given parameters, with the given color. The clip path pointer may be 2233<b><tt>NULL</tt></b>, meaning not to clip. 2234</dl> 2235 2236<dl> 2237<dt><b><tt>int (*fill_mask)(gx_device *dev, 2238const byte *data, int data_x, int raster, 2239gx_bitmap_id id, int x, int y, int width, 2240int height, const gx_drawing_color *pdcolor, int depth, 2241int command, const gx_clip_path *pcpath)</tt></b> 2242<b><em>[OPTIONAL]</em></b> 2243<dd>Color the 1-bits in the given mask (or according to the alpha values, 2244if <b><tt>depth</tt></b> > 1), clipped by the given clip path, 2245with the given color and logical operation. The clip path pointer may be 2246<b><tt>NULL</tt></b>, meaning do not clip. The parameters 2247<b><tt>data</tt></b>, ..., <b><tt>height</tt></b> are as for 2248<b><tt>copy_mono</tt></b>; depth is as for <b><tt>copy_alpha</tt></b>; 2249command is as for <b><tt>copy_rop</tt></b>. 2250</dl> 2251 2252<h4><a name="Images"></a>Images</h4> 2253 2254<p> 2255Similar to the high-level interface for fill and stroke graphics, a high-level 2256interface exists for bitmap images. The procedures in this part of the 2257interface are optional. 2258 2259<p> 2260Bitmap images come in a variety of types, corresponding closely (but not 2261precisely) to the PostScript ImageTypes. The generic or common part of all 2262bitmap images is defined by: 2263 2264<blockquote> 2265<pre>typedef struct { 2266 const gx_image_type_t *type; 2267 gs_matrix ImageMatrix; 2268} gs_image_common_t;</pre> 2269</blockquote> 2270 2271<p> 2272Bitmap images that supply data (all image types except 2273<b><tt>image_type_from_device</tt></b> (2)) are defined by: 2274 2275<blockquote> 2276<pre>#define gs_image_max_components 5 2277typedef struct { 2278 << gs_image_common_t >> 2279 int Width; 2280 int Height; 2281 int BitsPerComponent; 2282 float Decode[gs_image_max_components * 2]; 2283 bool Interpolate; 2284} gs_data_image_t;</pre> 2285</blockquote> 2286 2287<p> 2288Images that supply pixel (as opposed to mask) data are defined by: 2289 2290<blockquote> 2291<pre>typedef enum { 2292 /* Single plane, chunky pixels. */ 2293 gs_image_format_chunky = 0, 2294 /* num_components planes, chunky components. */ 2295 gs_image_format_component_planar = 1, 2296 /* BitsPerComponent * num_components planes, 1 bit per plane */ 2297 gs_image_format_bit_planar = 2 2298} gs_image_format_t; 2299typedef struct { 2300 << gs_data_image_t >> 2301 const gs_color_space *ColorSpace; 2302 bool CombineWithColor; 2303} gs_pixel_image_t;</pre> 2304</blockquote> 2305 2306<p> 2307Ordinary PostScript Level 1 or Level 2 (<b><tt>ImageType</tt></b> 1) images 2308are defined by: 2309 2310<blockquote> 2311<pre>typedef enum { 2312 /* No alpha. */ 2313 gs_image_alpha_none = 0, 2314 /* Alpha precedes color components. */ 2315 gs_image_alpha_first, 2316 /* Alpha follows color components. */ 2317 gs_image_alpha_last 2318} gs_image_alpha_t; 2319typedef struct { 2320 << gs_pixel_image_t >> 2321 bool ImageMask; 2322 bool adjust; 2323 gs_image_alpha_t Alpha; 2324} gs_image1_t; 2325typedef gs_image1_t gs_image_t;</pre> 2326</blockquote> 2327 2328<p> 2329Of course, standard PostScript images don't have an alpha component. For 2330more details, consult the source code in <a 2331href="../src/gsiparam.h">gsiparam.h</a> and <b><tt>gsiparm*.h</tt></b>, 2332which define parameters for an image. 2333 2334<p> 2335The <b><tt>begin[_typed_]image</tt></b> driver procedures create image 2336enumeration structures. The common part of these structures consists of: 2337 2338<blockquote> 2339<pre>typedef struct gx_image_enum_common_s { 2340 const gx_image_type_t *image_type; 2341 const gx_image_enum_procs_t *procs; 2342 gx_device *dev; 2343 gs_id id; 2344 int num_planes; 2345 int plane_depths[gs_image_max_planes]; /* [num_planes] */ 2346 int plane_widths[gs_image_max_planes] /* [num_planes] */ 2347} gx_image_enum_common_t;</pre> 2348</blockquote> 2349 2350<p> 2351where <b><tt>procs</tt></b> consists of: 2352 2353<blockquote> 2354<pre>typedef struct gx_image_enum_procs_s { 2355 2356 /* 2357 * Pass the next batch of data for processing. 2358 */ 2359#define image_enum_proc_plane_data(proc)\ 2360 int proc(gx_device *dev,\ 2361 gx_image_enum_common_t *info, const gx_image_plane_t *planes,\ 2362 int height) 2363 2364 image_enum_proc_plane_data((*plane_data)); 2365 2366 /* 2367 * End processing an image, freeing the enumerator. 2368 */ 2369#define image_enum_proc_end_image(proc)\ 2370 int proc(gx_device *dev,\ 2371 gx_image_enum_common_t *info, bool draw_last) 2372 2373 image_enum_proc_end_image((*end_image)); 2374 2375 /* 2376 * Flush any intermediate buffers to the target device. 2377 * We need this for situations where two images interact 2378 * (currently, only the mask and the data of ImageType 3). 2379 * This procedure is optional (may be 0). 2380 */ 2381#define image_enum_proc_flush(proc)\ 2382 int proc(gx_image_enum_common_t *info) 2383 2384 image_enum_proc_flush((*flush)); 2385 2386} gx_image_enum_procs_t;</pre> 2387</blockquote> 2388 2389<p> In other words, <b><tt>begin[_typed]_image</tt></b> sets up an 2390enumeration structure that contains the procedures that will process the 2391image data, together with all variables needed to maintain the state of the 2392process. Since this is somewhat tricky to get right, if you plan to create 2393one of your own you should probably read an existing implementation of 2394<b><tt>begin[_typed]_image</tt></b>, such as the one in <a 2395href="../src/gdevbbox.c">gdevbbox.c</a> or <a 2396href="../src/gdevps.c">gdevps.c</a>. 2397 2398<p> 2399The data passed at each call of <b><tt>image_plane_data</tt></b> consists of 2400one or more planes, as appropriate for the type of image. 2401<b><tt>begin[_typed]_image</tt></b> must initialize the 2402<b><tt>plane_depths</tt></b> array in the enumeration structure with the 2403depths (bits per element) of the planes. The array of 2404<b><tt>gx_image_plane_t</tt></b> structures passed to each call of 2405<b><tt>image_plane_data</tt></b> then defines where the data are stored, as 2406follows: 2407 2408<blockquote> 2409<pre>typedef struct gx_image_plane_s { 2410 const byte *data; 2411 int data_x; 2412 uint raster; 2413} gx_image_plane_t;</pre> 2414</blockquote> 2415 2416<dl> 2417<dt><b><tt>int (*begin_image)(gx_device *dev, 2418const gs_imager_state *pis, const gs_image_t *pim, 2419gs_image_format_t format, gs_int_rect *prect, 2420const gx_drawing_color *pdcolor, 2421const gx_clip_path *pcpath, gs_memory_t *memory, 2422gx_image_enum_common_t **pinfo)</tt></b> <b><em>[OPTIONAL]</em></b> 2423<dd>Begin the transmission of an image. Zero or more calls of 2424<b><tt>image_plane_data</tt></b> will follow, and then a call of 2425<b><tt>end_image</tt></b>. The parameters of <b><tt>begin_image</tt></b> 2426are as follows: 2427 2428<blockquote><table cellpadding=0 cellspacing=0> 2429<tr valign=top> <td><b><tt>pis</tt></b> 2430 <td> 2431 <td>pointer to an imager state. The only relevant elements of the 2432 imager state are the CTM (coordinate transformation matrix), 2433 the logical operation (<b><tt>RasterOp</tt></b> or 2434 transparency), and the color rendering information. 2435<tr valign=top> <td><b><tt>pim</tt></b> 2436 <td> 2437 <td>pointer to the <b><tt>gs_image_t</tt></b> structure that 2438 defines the image parameters 2439<tr valign=top> <td><b><tt>format</tt></b> 2440 <td> 2441 <td>defines how pixels are represented for 2442 <b><tt>image_plane_data</tt></b>. See the description of 2443 <b><tt>image_plane_data</tt></b> below 2444<tr valign=top> <td><b><tt>prect</tt></b> 2445 <td> 2446 <td>if not <b><tt>NULL</tt></b>, defines a subrectangle of the 2447 image; only the data for this subrectangle will be passed to 2448 <b><tt>image_plane_data</tt></b>, and only this subrectangle should 2449 be drawn 2450<tr valign=top> <td><b><tt>pdcolor</tt></b> 2451 <td> 2452 <td>defines a drawing color, only needed for masks or if 2453 <b><tt>CombineWithColor</tt></b> is true 2454<tr valign=top> <td><b><tt>pcpath</tt></b> 2455 <td> 2456 <td>if not <b><tt>NULL</tt></b>, defines an optional clipping path 2457<tr valign=top> <td><b><tt>memory</tt></b> 2458 <td> 2459 <td>defines the allocator to be used for allocating bookkeeping 2460 information 2461<tr valign=top> <td><b><tt>pinfo</tt></b> 2462 <td> 2463 <td>the implementation should return a pointer to its state 2464 structure here 2465</table></blockquote> 2466 2467<p> 2468<b><tt>begin_image</tt></b> is expected to allocate a structure for its 2469bookkeeping needs, using the allocator defined by the memory parameter, and 2470return it in <b><tt>*pinfo</tt></b>. <b><tt>begin_image</tt></b> should not assume that 2471the structures in <b><tt>*pim</tt></b>, <b><tt>*prect</tt></b>, or 2472<b><tt>*pdcolor</tt></b> will survive the call on 2473<b><tt>begin_image</tt></b> (except for the color space in 2474<b><tt>*pim->ColorSpace</tt></b>): it should copy any necessary parts of 2475them into its own bookkeeping structure. It may, however, assume that 2476<b><tt>*pis</tt></b>, <b><tt>*pcpath</tt></b>, and of course 2477<b><tt>*memory</tt></b> will live at least until <b><tt>end_image</tt></b> 2478is called. 2479 2480<p> 2481<b><tt>begin_image</tt></b> returns 0 normally, or 1 if the image does not 2482need any data. In the latter case, <b><tt>begin_image</tt></b> does not 2483allocate an enumeration structure. 2484</dl> 2485 2486<dl> 2487<dt><b><tt>int (*begin_typed_image)(gx_device *dev, 2488const gs_imager_state *pis, const gs_matrix *pmat, 2489const gs_image_common_t *pim, gs_int_rect *prect, 2490const gx_drawing_color *pdcolor, 2491const gx_clip_path *pcpath, gs_memory_t *memory, 2492gx_image_enum_common_t **pinfo)</tt></b> <b><em>[OPTIONAL]</em></b> 2493<dd>This has the same function as <b><tt>begin_image</tt></b>, except 2494<ul> 2495<li>The image may be of any <b><tt>ImageType</tt></b>, not only 2496<b><tt>image_type_simple</tt></b> (1); 2497 2498<li>The image format is included in the image structure, not supplied as a 2499separate argument; 2500 2501<li>The optional <b><tt>pmat</tt></b> argument provides a matrix that 2502substitutes for the one in the imager state; 2503 2504<li>For mask images, if <b><tt>pmat</tt></b> is not <b><tt>NULL</tt></b> 2505and the color is pure, <b><tt>pis</tt></b> may be <b><tt>NULL</tt></b>. 2506</ul> 2507</dl> 2508 2509<p> 2510The actual transmission of data uses the procedures in the enumeration 2511structure, not driver procedures, since the handling of the data usually 2512depends on the image type and parameters rather than the device. These 2513procedures are specified as follows. 2514 2515<dl> 2516<dt><b><tt>int (*image_plane_data)(gx_device *dev, 2517gx_image_enum_common_t *info, 2518const gx_image_plane_t *planes, int height)</tt></b> 2519<dd>This call provides more of the image source data: specifically, 2520<b><tt>height</tt></b> rows, with <b><tt>Width</tt></b> pixels supplied for 2521each row. 2522 2523<p> 2524The data for each row are packed big-endian within each byte, as for 2525<b><tt>copy_color</tt></b>. The <b><tt>data_x</tt></b> (starting X position 2526within the row) and <b><tt>raster</tt></b> (number of bytes per row) are 2527specified separately for each plane, and may include some padding at the 2528beginning or end of each row. Note that for non-mask images, the input data 2529may be in any color space and may have any number of bits per component (1, 25302, 4, 8, 12); currently mask images always have 1 bit per component, but in 2531the future, they might allow multiple bits of alpha. Note also that each 2532call of <b><tt>image_plane_data</tt></b> passes complete pixels: for example, for 2533a chunky image with 24 bits per pixel, each call of 2534<b><tt>image_plane_data</tt></b> passes 3N bytes of data (specifically, 25353 × Width × height). 2536 2537<p> 2538The interpretation of planes depends on the <b><tt>format</tt></b> member of 2539the <b><tt>gs_image[_common]_t</tt></b> structure: 2540 2541<ul> 2542<li>If the format is <b><tt>gs_image_format_chunky</tt></b>, 2543<b><tt>planes[0].data</tt></b> points to data in "chunky" format, in which 2544the components follow each other (for instance, RGBRGBRGB....) 2545 2546<li>If the format is <b><tt>gs_image_format_component_planar</tt></b>, 2547<b><tt>planes[0 .. N-1].data</tt></b> point to data for the 2548<b><em>N</em></b> components (for example, <b><em>N</em></b>=3 for RGB 2549data); each plane contains samples for a single component, for instance, 2550RR..., GG..., BB.... Note that the planes are divided by component, not by 2551bit: for example, for 24-bit RGB data, <b><em>N</em></b>=3, with 8-bit 2552values in each plane of data. 2553 2554<li>If the format is <b><tt>gs_image_format_bit_planar</tt></b>, 2555<b><tt>planes[0 .. N*B-1].data</tt></b> point to data for the 2556<b><em>N</em></b> components of <b><em>B</em></b> bits each (for example, 2557<b><em>N</em></b>=3 and <b><em>B</em></b>=4 for RGB data with 4 bits per 2558component); each plane contains samples for a single bit, for instance, R0 2559R1 R2 R3 G0 G1 G2 G3 B0 B1 B2 B3. Note that the most significant bit of 2560each plane comes first. 2561</ul> 2562 2563<p> 2564If, as a result of this call, <b><tt>image_plane_data</tt></b> has been called with all 2565the data for the (sub-)image, it returns 1; otherwise, it returns 0 or an 2566error code as usual. 2567 2568<p> 2569<b><tt>image_plane_data</tt></b>, unlike most other procedures that take bitmaps as 2570arguments, does not require the data to be aligned in any way. 2571 2572<p> 2573Note that for some image types, different planes may have different 2574numbers of bits per pixel, as defined in the <b><tt>plane_depths</tt></b> array. 2575</dl> 2576 2577<dl> 2578<dt><b><tt>int (*end_image)(gx_device *dev, void *info, 2579bool draw_last)</tt></b> 2580<dd>Finish processing an image, either because all data have been supplied 2581or because the caller has decided to abandon this image. 2582<b><tt>end_image</tt></b> may be called at any time after 2583<b><tt>begin_image</tt></b>. It should free the info structure and any 2584subsidiary structures. If <b><tt>draw_last</tt></b> is true, it should 2585finish drawing any buffered lines of the image. 2586</dl> 2587 2588<h5><a name="Images_notes"></a>Notes</h5> 2589 2590<p> 2591While there will almost never be more than one image enumeration in 2592progress -- that is, after a <b><tt>begin_image</tt></b>, 2593<b><tt>end_image</tt></b> will almost always be called before the next 2594<b><tt>begin_image</tt></b> -- driver code should not rely on this 2595property; in particular, it should store all information regarding the 2596image in the info structure, not in the driver structure. 2597 2598<p> 2599Note that if <b><tt>begin_[typed_]image</tt></b> saves its parameters in 2600the info structure, it can decide on each call whether to use its own 2601algorithms or to use the default implementation. (It may need to call 2602<b><tt>gx_default_begin</tt></b>/<b><tt>end_image</tt></b> partway 2603through.) [A later revision of this document may include an example here.] 2604 2605<h4><a name="Text"></a>Text</h4> 2606 2607<p> 2608The third high-level interface handles text. As for images, the interface 2609is based on creating an enumerator which then may execute the operation in 2610multiple steps. As for the other high-level interfaces, the procedures are 2611optional. 2612 2613<dl> 2614<dt><b><tt>int (*text_begin)(gx_device *dev, 2615gs_imager_state *pis, const gs_text_params_t *text, 2616gs_font *font, gx_path *path, 2617const gx_device_color *pdcolor, 2618const gx_clip_path *pcpath, gs_memory_t *memory, 2619gs_text_enum_t **ppte)</tt></b> <b><em>[OPTIONAL]</em></b> 2620 2621<dd> 2622Begin processing text, by creating a state structure and storing it in 2623<b><tt>*ppte</tt></b>. The parameters of <b><tt>text_begin</tt></b> are as 2624follows: 2625</dl> 2626 2627<blockquote><table cellpadding=0 cellspacing=0> 2628<tr valign=top> <td><b><tt>dev</tt></b> 2629 <td> 2630 <td>The usual pointer to the device. 2631<tr valign=top> <td><b><tt>pis</tt></b> 2632 <td> 2633 <td>A pointer to an imager state. All elements may be relevant, 2634 depending on how the text is rendered. 2635<tr valign=top> <td><b><tt>text</tt></b> 2636 <td> 2637 <td>A pointer to the structure that defines the text operation 2638 and parameters. See <a href="../src/gstext.h">gstext.h</a> for details. 2639<tr valign=top> <td><b><tt>font</tt></b> 2640 <td> 2641 <td>Defines the font for drawing. 2642<tr valign=top> <td><b><tt>path</tt></b> 2643 <td> 2644 <td>Defines the path where the character outline will be appended 2645 (if the text operation includes <b><tt>TEXT_DO_...PATH</tt></b>), 2646 and whose current point indicates where drawing should occur 2647 and will be updated by the string width (unless the text 2648 operation includes <b><tt>TEXT_DO_NONE</tt></b>). 2649<tr valign=top> <td><b><tt>pdcolor</tt></b> 2650 <td> 2651 <td>Defines the drawing color for the text. Only relevant if 2652 the text operation includes <b><tt>TEXT_DO_DRAW</tt></b>. 2653<tr valign=top> <td><b><tt>pcpath</tt></b> 2654 <td> 2655 <td>If not <b><tt>NULL</tt></b>, defines an optional clipping path. 2656 Only relevant if the text operation includes 2657 <b><tt>TEXT_DO_DRAW</tt></b>. 2658<tr valign=top> <td><b><tt>memory</tt></b> 2659 <td> 2660 <td>Defines the allocator to be used for allocating bookkeeping 2661 information. 2662<tr valign=top> <td><b><tt>ppte</tt></b> 2663 <td> 2664 <td>The implementation should return a pointer to its state 2665 structure here. 2666</table></blockquote> 2667 2668<p> 2669<b><tt>text_begin</tt></b> must allocate a structure for its bookkeeping 2670needs, using the allocator defined by the <b><tt>memory</tt></b> parameter, 2671and return it in <b><tt>*ppte</tt></b>. <b><tt>text_begin</tt></b> may 2672assume that the structures passed as parameters will survive until text 2673processing is complete. 2674 2675<p> 2676Clients should not call the driver <b><tt>text_begin</tt></b> procedure 2677directly. Instead, they should call <b><tt>gx_device_text_begin</tt></b>, 2678which takes the same parameters and also initializes certain common elements 2679of the text enumeration structure, or <b><tt>gs_text_begin</tt></b>, which 2680takes many of the parameters from a graphics state structure. For details, 2681see <a href="../src/gstext.h">gstext.h</a>. 2682 2683<p> 2684The actual processing of text uses the procedures in the enumeration 2685structure, not driver procedures, since the handling of the text may depend 2686on the font and parameters rather than the device. Text processing may also 2687require the client to take action between characters, either because the 2688client requested it (<b><tt>TEXT_INTERVENE</tt></b> in the operation) or 2689because rendering a character requires suspending text processing to call an 2690external package such as the PostScript interpreter. (It is a deliberate 2691design decision to handle this by returning to the client, rather than 2692calling out of the text renderer, in order to avoid potentially unknown 2693stack requirements.) Specifically, the client must call the following 2694procedures, which in turn call the procedures in the text enumerator. 2695 2696<dl> 2697<dt><b><tt>int gs_text_process(gs_text_enum_t *pte)</tt></b> 2698<dd>Continue processing text. This procedure may return 0 or a negative 2699error code as usual, or one of the following values (see 2700<a href="../src/gstext.h">gstext.h</a> for details). 2701 2702<blockquote><table cellpadding=0 cellspacing=0> 2703<tr valign=top> <td><b><tt>TEXT_PROCESS_RENDER</tt></b> 2704 <td>The client must cause the current character to be rendered. 2705 This currently only is used for PostScript Type 0-4 fonts 2706 and their CID-keyed relatives. 2707<tr valign=top> <td><b><tt>TEXT_PROCESS_INTERVENE</tt></b> 2708 <td>The client has asked to intervene between characters. 2709 This is used for <b><tt>cshow</tt></b> and <b><tt>kshow</tt></b>. 2710</table></blockquote> 2711</dl> 2712 2713<dl> 2714<dt><b><tt>int gs_text_release(gs_text_enum_t *pte, 2715client_name_t cname)</tt></b> <dd>Finish processing text and release 2716all associated structures. Clients must call this procedure after 2717<b><tt>gs_text_process</tt></b> returns 0 or an error, and may call it at 2718any time. 2719</dl> 2720 2721<p> 2722There are numerous other procedures that clients may call during text 2723processing. See <a href="../src/gstext.h">gstext.h</a> for details. 2724 2725<h5><a name="Text_notes"></a>Notes</h5> 2726 2727<p> 2728Note that unlike many other optional procedures, the default implementation 2729of <b><tt>text_begin</tt></b> cannot simply return: like the default 2730implementation of <b><tt>begin[_typed]_image</tt></b>, it must create and 2731return an enumerator. Furthermore, the implementation of the 2732<b><tt>process</tt></b> procedure (in the enumerator structure, called by 2733<b><tt>gs_text_process</tt></b>) cannot simply return without doing 2734anything, even if it doesn't want to draw anything on the output. See the 2735comments in <a href="../src/gxtext.h">gxtext.h</a> for details. 2736 2737<h4><a name="Unicode"></a>Unicode support for high level devices</h4> 2738 2739<p> 2740<p>Implementing a new high level device, one may need to translate <b><tt>Postscript</tt></b> 2741character codes into <b><tt>Unicode</tt></b>. This can be done pretty simply. 2742 2743<p>For translating a <b><tt>Postscript</tt></b> text you need to inplement the device 2744virtual function <b><tt>text_begin</tt></b>. It should create a new instance of 2745<b><tt>gs_text_enum_t</tt></b> in the heap (let its pointer be <b><tt>pte</tt></b>), 2746and assign a special function to <b><tt>gs_text_enum_t::procs.process</tt></b>. 2747The function will receive <b><tt>pte</tt></b>. It should take the top level font from 2748<b><tt>pte->orig_font</tt></b>, 2749and iterate with <b><tt>font->procs.next_char_glyph(pte, ..., &glyph)</tt></b>. 2750The last argument receives a <b><tt>gs_glyph</tt></b> value, which encodes a 2751<b><tt>Postscript</tt></b> character name or CID (and also stores it into 2752<b><tt>pte->returned.current_glyph</tt></b>). 2753Then obtain the current subfont with <b><tt>gs_text_current_font(pte)</tt></b> 2754(it can differ from the font) 2755and call <b><tt>subfont->procs.decode_glyph(subfont, glyph)</tt></b>. 2756The return value will be an <b><tt>Unicode</tt></b> code, or <b><tt>GS_NO_CHAR</tt></b> 2757if the glyph can't be translated to Unicode. 2758 2759<h3><a name="Reading_bits_back"></a>Reading bits back</h3> 2760 2761<dl> 2762<dt><b><tt>int (*get_bits_rectangle)(gx_device *dev, 2763const gs_int_rect *prect, gs_get_bits_params_t *params, 2764gs_int_rect **unread)</tt></b> <b><em>[OPTIONAL]</em></b> 2765 2766<dd> 2767Read a rectangle of bits back from the device. The <b><tt>params</tt></b> 2768structure consists of: 2769 2770<table cellpadding=0 cellspacing=0> 2771<tr valign=top> <td><b><tt>options</tt></b> 2772 <td> 2773 <td>the allowable formats for returning the data 2774<tr valign=top> <td><b><tt>data[32]</tt></b> 2775 <td> 2776 <td>pointers to the returned data 2777<tr valign=top> <td><b><tt>x_offset</tt></b> 2778 <td> 2779 <td>the X offset of the first returned pixel in data 2780<tr valign=top> <td><b><tt>raster</tt></b> 2781 <td> 2782 <td>the distance between scan lines in the returned data 2783</table> 2784 2785<p> 2786<b><tt>options</tt></b> is a bit mask specifying what formats the client is 2787willing to accept. (If the client has more flexibility, the implementation 2788may be able to return the data more efficiently, by avoiding representation 2789conversions.) The options are divided into groups. 2790 2791<blockquote><dl> 2792<dt><b><em>alignment</em></b> 2793<dd>Specifies whether the returned data must be aligned in the normal 2794manner for bitmaps, or whether unaligned data are acceptable. 2795 2796<dt><b><em>pointer or copy</em></b> 2797<dd>Specifies whether the data may be copied into storage provided by the 2798client and/or returned as pointers to existing storage. (Note that if 2799copying is not allowed, it is much more likely that the implementation will 2800return an error, since this requires that the client accept the data in the 2801implementation's internal format.) 2802 2803<dt><b><em>X offset</em></b> 2804<dd>Specifies whether the returned data must have a specific X offset 2805(usually zero, but possibly other values to avoid skew at some later stage 2806of processing) or whether it may have any X offset (which may avoid skew in 2807the <b><tt>get_bits_rectangle</tt></b> operation itself). 2808 2809<dt><b><em>raster</em></b> 2810<dd>Specifies whether the raster (distance between returned scan lines) 2811must have its standard value, must have some other specific value, or may 2812have any value. The standard value for the raster is the device width 2813padded out to the alignment modulus when using pointers, or the minimum 2814raster to accommodate the X offset + width when copying (padded out to the 2815alignment modulus if standard alignment is required). 2816 2817<dt><b><em>format</em></b> 2818<dd>Specifies whether the data are returned in chunky (all components of a 2819single pixel together), component-planar (each component has its own scan 2820lines), or bit-planar (each bit has its own scan lines) format. 2821 2822<dt><b><em>color space</em></b> 2823<dd>Specifies whether the data are returned as native device pixels, or in 2824a standard color space. Currently the only supported standard space is 2825RGB. 2826 2827<dt><b><em>standard component depth</em></b> 2828<dd>Specifies the number of bits per component if the data are returned in 2829the standard color space. (Native device pixels use 2830<b><tt>dev</tt></b>-><b><tt>color_info.depth</tt></b> bits per pixel.) 2831 2832<dt><b><em>alpha</em></b> 2833<dd>Specifies whether alpha channel information should be returned as the 2834first component, the last component, or not at all. Note that for devices 2835that have no alpha capability, the returned alpha values will be all 1s. 2836</dl></blockquote> 2837 2838<p> 2839The client may set more than one option in each of the above groups; the 2840implementation will choose one of the selected options in each group to 2841determine the actual form of the returned data, and will update 2842<b><tt>params[].options</tt></b> to indicate the form. The returned 2843<b><tt>params[].options</tt></b> will normally have only one option set per 2844group. 2845 2846<p> 2847For further details on <b><tt>params</tt></b>, see <a 2848href="../src/gxgetbit.h">gxgetbit.h</a>. For further details on 2849<b><tt>options</tt></b>, see <a href="../src/gxbitfmt.h">gxbitfmt.h</a>. 2850 2851<p> 2852Define w = <b><tt>prect</tt></b>->q.x - <b><tt>prect</tt></b>->p.x, h 2853= <b><tt>prect</tt></b>->q.y - <b><tt>prect</tt></b>->p.y. If the 2854bits cannot be read back (for example, from a printer), return 2855<b><tt>gs_error_unknownerror</tt></b>; if raster bytes is not enough space 2856to hold <b><tt>offset_x</tt></b> + w pixels, or if the source rectangle 2857goes outside the device dimensions (p.x < 0 || p.y < 0 || q.x > 2858<b><tt>dev</tt></b>->width || q.y > <b><tt>dev</tt></b>->height), 2859return <b><tt>gs_error_rangecheck</tt></b>; if any regions could not be 2860read, return <b><tt>gs_error_ioerror</tt></b> if unpainted is 2861<b><tt>NULL</tt></b>, otherwise the number of rectangles (see below); 2862otherwise return 0. 2863 2864<p> 2865The caller supplies a buffer of <b><tt>raster</tt></b> × h 2866bytes starting at <b><tt>data[0]</tt></b> for the returned data in chunky 2867format, or <b><em>N</em></b> buffers of 2868<b><tt>raster</tt></b> × h bytes starting at 2869<b><tt>data[0]</tt></b> through 2870<b><tt>data[</tt></b><b><em>N-1</em></b><b><tt>]</tt></b> in planar format 2871where <b><em>N</em></b> is the number of components or bits. The contents 2872of the bits beyond the last valid bit in each scan line (as defined by w) 2873are unpredictable. data need not be aligned in any way. If 2874<b><tt>x_offset</tt></b> is non-zero, the bits before the first valid bit 2875in each scan line are undefined. If the implementation returns pointers to 2876the data, it stores them into <b><tt>data[0]</tt></b> or 2877<b><tt>data[</tt></b><b><em>0..N-1</em></b><b><tt>]</tt></b>. 2878 2879<p> 2880If not all the source data are available (for example, because the source 2881was a partially obscured window and backing store was not available or not 2882used), or if the rectangle does not fall completely within the device's 2883coordinate system, any unread bits are undefined, and the value returned 2884depends on whether unread is <b><tt>NULL</tt></b>. If unread is 2885<b><tt>NULL</tt></b>, return <b><tt>gs_error_ioerror</tt></b>; in this case, 2886some bits may or may not have been read. If unread is not 2887<b><tt>NULL</tt></b>, allocate (using <b><tt>dev</tt></b>->memory) and 2888fill in a list of rectangles that could not be read, store the pointer to 2889the list in <b><tt>*unread</tt></b>, and return the number of rectangles; in 2890this case, all bits not listed in the rectangle list have been read back 2891properly. The list is not sorted in any particular order, but the 2892rectangles do not overlap. Note that the rectangle list may cover a 2893superset of the region actually obscured: for example, a lazy implementation 2894could return a single rectangle that was the bounding box of the region. 2895</dl> 2896 2897<dl> 2898<dt><b><tt>int (*get_bits)(gx_device *dev, int y, 2899byte *data, byte **actual_data)</tt></b> 2900<b><em>[OPTIONAL]</em></b> 2901<dd>Read scan line <b><tt>y</tt></b> of bits back from the device into the 2902area starting at data. This call is functionally equivalent to 2903 2904<blockquote> 2905<pre>(*get_bits_rectangle) 2906 (dev, {0, y, dev->width, y+1}, 2907 {(GB_ALIGN_ANY | (GB_RETURN_COPY | GB_RETURN_POINTER) | GB_OFFSET_0 | 2908 GB_RASTER_STANDARD | GB_FORMAT_CHUNKY | GB_COLORS_NATIVE | 2909 GB_ALPHA_NONE), 2910 {data}})</pre></blockquote> 2911 2912<p> 2913with the returned value of 2914<b><tt>params</tt></b>-><b><tt>data[0]</tt></b> stored in 2915<b><tt>*actual_data</tt></b>, and will in fact be implemented this way if 2916the device defines a <b><tt>get_bits_rectangle</tt></b> procedure and does 2917not define one for <b><tt>get_bits</tt></b>. (If 2918<b><tt>actual_data</tt></b> is <b><tt>NULL</tt></b>, 2919<b><tt>GB_RETURN_POINTER</tt></b> is omitted from the options.) 2920</dl> 2921 2922<h3><a name="Parameters"></a>Parameters</h3> 2923 2924<p> 2925Devices may have an open-ended set of parameters, which are simply pairs 2926consisting of a name and a value. The value may be of various types: 2927integer (int or long), boolean, float, string, name, <b><tt>NULL</tt></b>, 2928array of integer, array of float, or arrays or dictionaries of mixed types. 2929For example, the <b><tt>Name</tt></b> of a device is a string; the 2930<b><tt>Margins</tt></b> of a device is an array of two floats. See 2931<a href="../src/gsparam.h">gsparam.h</a> for more details. 2932 2933<p> 2934If a device has parameters other than the ones applicable to all devices 2935(or, in the case of printer devices, all printer devices), it must provide 2936<b><tt>get_params</tt></b> and <b><tt>put_params</tt></b> procedures. If 2937your device has parameters beyond those of a straightforward display or 2938printer, we strongly advise using the <b><tt>_get_params</tt></b> and 2939<b><tt>_put_params</tt></b> procedures in an existing device (for example, 2940<a href="../src/gdevcdj.c">gdevcdj.c</a> or <a 2941href="../src/gdevbit.c">gdevbit.c</a>) as a model for your own code. 2942 2943<dl> 2944<dt><b><tt>int (*get_params)(gx_device *dev, 2945gs_param_list *plist)</tt></b> <b><em>[OPTIONAL]</em></b> 2946<dd>Read the parameters of the device into the parameter list at 2947<b><tt>plist</tt></b>, using the <b><tt>param_write_*</tt></b> 2948macros or procedures defined in <a href="../src/gsparam.h">gsparam.h</a>. 2949</dl> 2950 2951<dl> 2952<dt><b><tt>int (*get_hardware_params)(gx_device *dev, 2953gs_param_list *plist)</tt></b> <b><em>[OPTIONAL]</em></b> 2954<dd>Read the hardware-related parameters of the device into the parameter 2955list at plist. These are any parameters whose values are under control of 2956external forces rather than the program -- for example, front panel 2957switches, paper jam or tray empty sensors, etc. If a parameter involves 2958significant delay or hardware action, the driver should only determine the 2959value of the parameter if it is "requested" by the 2960<b><tt>gs_param_list</tt></b> [<b><tt>param_requested</tt></b>(plist, 2961<b><tt>key_name</tt></b>)]. This function may cause the asynchronous 2962rendering pipeline (if enabled) to be drained, so it should be used 2963sparingly. 2964</dl> 2965 2966<dl> 2967<dt><b><tt>int (*put_params)(gx_device *dev, 2968gs_param_list *plist)</tt></b> <b><em>[OPTIONAL]</em></b> 2969<dd>Set the parameters of the device from the parameter list at 2970<b><tt>plist</tt></b>, using the <b><tt>param_read_</tt></b>* 2971macros/procedures defined in <a href="../src/gsparam.h">gsparam.h</a>. All 2972<b><tt>put_params</tt></b> procedures must use a "two-phase commit" 2973algorithm; see <a href="../src/gsparam.h">gsparam.h</a> for details. 2974</dl> 2975 2976<h4><a name="Default_CRD_parameters"></a>Default color rendering 2977dictionary (CRD) parameters</h4> 2978 2979<p> 2980Drivers that want to provide one or more default CIE color rendering 2981dictionaries (CRDs) can do so through <b><tt>get_params</tt></b>. To do 2982this, they create the CRD in the usual way (normally using the 2983<b><tt>gs_cie_render1_build</tt></b> and <b><tt>_initialize</tt></b> 2984procedures defined in <a href="../src/gscrd.h">gscrd.h</a>), and then write 2985it as a parameter using <b><tt>param_write_cie_render1</tt></b> defined in 2986<a href="../src/gscrdp.h">gscrdp.h</a>. However, the TransformPQR procedure 2987requires special handling. If the CRD uses a TransformPQR procedure 2988different from the default (identity), the driver must do the following: 2989 2990<ul> 2991<li>The TransformPQR element of the CRD must include a 2992<b><tt>proc_name</tt></b>, and optionally <b><tt>proc_data</tt></b>. The 2993<b><tt>proc_name</tt></b> is an arbitrary name chosen by the driver to 2994designate the particular TransformPQR function. It must not be the same as 2995any device parameter name; we strongly suggest it include the device name, 2996for instance, "<b><tt>bitTPQRDefault</tt></b>". 2997 2998<li>For each such named TransformPQR procedure, the driver's 2999<b><tt>get_param</tt></b> procedure must provide a parameter of the same 3000name. The parameter value must be a string whose bytes are the actual 3001procedure address. 3002</ul> 3003 3004<p> 3005For a complete example, see the <b><tt>bit_get_params</tt></b> procedure in 3006<a href="../src/gdevbit.c">gdevbit.c</a>. Note that it is essential that 3007the driver return the CRD or the procedure address only if specifically 3008requested (<b><tt>param_requested(...)</tt></b> > 0); otherwise, errors 3009will occur. 3010 3011<h3><a name="External_fonts"></a>External fonts</h3> 3012 3013<p> 3014Drivers may include the ability to display text. More precisely, they may 3015supply a set of procedures that in turn implement some font and text 3016handling capabilities, described in <a href="Xfonts.htm">a separate 3017document</a>. The link between the two is the driver procedure that 3018supplies the font and text procedures: 3019 3020<dl> 3021<dt><b><tt>xfont_procs *(*get_xfont_procs)(gx_device *dev)</tt></b> <b><em>[OPTIONAL]</em></b> 3022<dd>Return a structure of procedures for handling external fonts and text 3023display. A <b><tt>NULL</tt></b> value means that this driver doesn't 3024provide this capability. 3025</dl> 3026 3027<p> 3028For technical reasons, a second procedure is also needed: 3029 3030<dl> 3031<dt><b><tt>gx_device *(*get_xfont_device)(gx_device *dev)</tt></b> <b><em>[OPTIONAL]</em></b> 3032<dd>Return the device that implements <b><tt>get_xfont_procs</tt></b> in a 3033non-default way for this device, if any. Except for certain special 3034internal devices, this is always the device argument. 3035</dl> 3036 3037<h3><a name="Page_devices"></a>Page devices</h3> 3038 3039<dl> 3040<dt><b><tt>gx_device *(*get_page_device)(gx_device *dev)</tt></b> 3041<b><em>[OPTIONAL]</em></b> 3042<dd>According to the Adobe specifications, some devices are "page devices" 3043and some are not. This procedure returns <b><tt>NULL</tt></b> if the 3044device is not a page device, or the device itself if it is a page device. 3045In the case of forwarding devices, <b><tt>get_page_device</tt></b> returns 3046the underlying page device (or <b><tt>NULL</tt></b> if the underlying 3047device is not a page device). 3048</dl> 3049 3050<h3><a name="Miscellaneous"></a>Miscellaneous</h3> 3051 3052<dl> 3053<dt><b><tt>int (*get_band)(gx_device *dev, int y, 3054int *band_start)</tt></b> <b><em>[OPTIONAL]</em></b> 3055<dd>If the device is a band device, this procedure stores in 3056<b><tt>*band_start</tt></b> the scan line (device Y coordinate) of the band 3057that includes the given Y coordinate, and returns the number of scan lines 3058in the band. If the device is not a band device, this procedure returns 0. 3059The latter is the default implementation. 3060</dl> 3061 3062<dl> 3063<dt><b><tt>void (*get_clipping_box)(gx_device *dev, 3064gs_fixed_rect *pbox))</tt></b> <b><em>[OPTIONAL]</em></b> 3065<dd>Stores in <b><tt>*pbox</tt></b> a rectangle that defines the device's 3066clipping region. For all but a few specialized devices, this is 3067<em>((0,0),(width,height))</em>. 3068</dl> 3069 3070<!-- [2.0 end contents] ==================================================== --> 3071 3072<!-- [3.0 begin visible trailer] =========================================== --> 3073<hr> 3074 3075<p> 3076<small>Copyright © 1996, 2000 Aladdin Enterprises. 3077All rights reserved.</small> 3078 3079<p> 3080This software is provided AS-IS with no warranty, either express or 3081implied. 3082 3083This software is distributed under license and may not be copied, 3084modified or distributed except as expressly authorized under the terms 3085of the license contained in the file LICENSE in this distribution. 3086 3087For more information about licensing, please refer to 3088http://www.ghostscript.com/licensing/. For information on 3089commercial licensing, go to http://www.artifex.com/licensing/ or 3090contact Artifex Software, Inc., 101 Lucas Valley Road #110, 3091San Rafael, CA 94903, U.S.A., +1(415)492-9861. 3092 3093<p> 3094<small>Ghostscript version 8.53, 20 October 2005 3095 3096<!-- [3.0 end visible trailer] ============================================= --> 3097 3098</small></body> 3099</html> 3100