Copyright (C) 1993, 1994 Aladdin Enterprises. All rights reserved. This file is part of Aladdin Ghostscript. Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND. No author or distributor accepts any responsibility for the consequences of using it, or for whether it serves any particular purpose or works at all, unless he or she says so in writing. Refer to the Aladdin Ghostscript Free Public License (the "License") for full details. Every copy of Aladdin Ghostscript must include a copy of the License, normally in a plain ASCII text file named PUBLIC. The License grants you the right to copy, modify and redistribute Aladdin Ghostscript, but only under certain conditions described in the License. Among other things, the License requires that the copyright notice and this notice be preserved on all copies. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This file, devarch.doc, contains notes about the architecture of device handling in Ghostscript. It is intended only for developers with a fairly deep understanding of Level 2 PostScript. For an overview of Ghostscript and a list of the documentation files, see README. ---------------------------------------------------------------- ****** MUCH OF THE MATERIAL IN THIS DOCUMENT IS UNRELIABLE. DON'T TRUST IT. ****** Background ========== PostScript language ------------------- Adobe's Level 1 PostScript specification ignored, except for a few now-obsolete operators, the possibility of a single PostScript system that had multiple hardware devices attached to it; Level 1 also did not deal, in a systematic way, with control of printing features such as page size and output finishing. In contrast, the available Level 2 specifications (the PostScript Language Reference Manual, Second Edition, and subsequent documentation obtained from the Adobe file server describing Adobe PostScript products through PostScript version 2013) include extensive facilities in this area. Adobe's documentation refers explicitly to three concepts of "device": - A physical device such as a file system, a communication port, or a printing engine. The IODevice resource enumerates these devices without providing any other information about them. Each IODevice may have a set of state variables specific to it; the setdevparams and currentdevparams operators control the state of individual IODevices. (In the rest of this document, we are not concerned with IODevices.) - A class of destination for rendering. The OutputDevice resource enumerates these, and gives some further information (available page sizes and resolutions). OutputDevices do not have state per se, although in Adobe's model, they typically correspond 1-for-1 with those IODevices that can serve as destinations for rendering. - An actual destination for rendering. This may be a special destination like the null device or a cache device, a display (for which the documentation specifies no further details), or an instance of an OutputDevice. OutputDevice instances are called "page devices". The only directly visible, program-controlled state of a page device is the contents of the current page. However, page devices also have a very large set of optional parameters that may be set when setpagedevice creates the instance, and read by currentpagedevice; some of these parameters may change from time to time as a result of external events or conditions. The parameters control both external hardware (e.g., duplex or collation) and internally implemented facilities such as portrait vs. landscape orientation. Ghostscript ----------- Ghostscript generalizes the Adobe model in several areas at the level of the PostScript program. - In addition to hard copy devices, Ghostscript can produce output on physical displays, window systems, raster files, or RAM; a typical Ghostscript configuration supports more than one of these. Ghostscript models this by providing new OutputDevices, and a new concept called an OutputDevice family for grouping them. - Ghostscript normally includes multiple drivers that can write to the same physical device (for example, multiple raster file format generators, or multiple printer drivers). Ghostscript models this by making each driver a different OutputDevice. - Ghostscript explicitly makes visible the objects that represent OutputDevice instances (page devices and their display, file, and RAM analogues) as new PostScript objects of type /devicetype. In the remainder of this document, we describe Ghostscript's handling of devices from four viewpoints: that of an ordinary PostScript program, that of the Ghostscript implementation at the PostScript level, that of the Ghostscript implementation at the C level, and that of the Ghostscript device driver. PostScript programs =================== OutputDevice resource --------------------- The OutputDevice resource is described in Adobe documentation as having been added in Adobe interpreter version 2011. Briefly, the resource names are the same as the allowed values of the /OutputDevice page device parameter, and the resource values are dictionaries giving properties of the output device. The defined properties as of version 2012 are HWResolution, ManualSize, and PageSize. Ghostscript provides one OutputDevice for each available driver. This includes file formats (e.g., /gifmono) and display or window systems (e.g., /x11) as well as printer types (e.g., /ljet3). It provides a special OutputDevice called /RAM whose instances simply accumulate a bitmap in RAM for later readout. In addition, if the available drivers include any printer, fax, or display driver, Ghostscript provides OutputDevice entries called /Printer, /Fax, /RasterFile, and /Display respectively that are aliases for the default driver in the respective family. (There is nothing special about these three names. Any driver can declare that it belongs to a particular family, and the driver of any given family that appears earliest in the build list becomes the default driver with that family name.) Finally, Ghostscript always provides an OutputDevice called /Default that is an alias for the default OutputDevice (the one used if setpagedevice is invoked with no current page device and no OutputDevice key in the parameter dictionary). Operators --------- Ghostscript provides the setpagedevice and currentpagedevice operators, as required by the Level 2 PostScript specifications. Ghostscript also provides a few other operators that implement increased functionality. .indexdevicename Returns the name of the int'th driver in the build list. The first driver is numbered 0. .selectdevice Creates and makes current a default instance of a given OutputDevice. - .currentdevice Returns the current device, which may be a page device or a special device. .getoutputparams ... Returns the parameters of a default instance of the given OutputDevice. Also returns the information for the OutputDevice resource dictionary. .getoutputparams ... Returns the parameters of a given device. Page device parameters ---------------------- Most of the page device parameters documented by Adobe (either in the New Red Book or in the post-Book notes) are specific to particular devices. Ghostscript leaves these up to the device driver to process, and only provides the Policies and PolicyReport mechanism to handle those that are unknown or out of range. Here are the parameters documented by Adobe that Ghostscript knows about specifically: BeginPage, EndPage, Install - per Red Book documentation. Policies - per Red Book documentation. The PageSize policy value of 7 (in later Adobe documentation) is not supported. ImagingBBox, HWResolution, Margins, PageSize - per Red Book documentation. Margins are given in device-specific units, per later Adobe documentation. OutputDevice - per later Adobe documentation. InputAttributes, OutputAttributes - per Red Book documentation. The feature whereby if InputAttributes is null, the interpreter consults the driver directly for media selection (per later documentation) is not implemented. Orientation - per Red Book documentation, also supported for RAM and display devices. We aren't sure yet how Orientation will affect raster file output devices. ProcessColorModel - per later Adobe documentation, but read-only for all but RAM devices. For RAM devices, only DeviceGray, DeviceRGB, and DeviceCMYK are supported. InsertSheet, OutputPage, SeparationColorNames, SeparationOrder - not currently supported. Collate and the concept of a "set" - not currently supported. Ghostscript also implements the following parameters that are not documented by Adobe: .HWBitsPerPixel - the number of bits per pixel, an integer between 1 and 32. This is read-only for all but RAM devices and a few file formats. GrayValues, RedValues, GreenValues, BlueValues, ColorValues - as defined by Adobe for the deviceinfo operator. These are read-only for all but RAM devices and a few file formats. .HWGrayMap, .HWRedMap, .HWGreenMap, .HWBlueMap, .HWColorMap - the maps of the realizable device colors. Each map is a string of M x xxxValues bytes; each entry is M bytes, where M = 1 for the first 4 maps and 1, 3, or 4 bytes according to the ProcessColorModel for HWColorMap. (I.e., the maps are like the lookup table for an Indexed color space.) If a map is missing, the realizable colors are 0, 1/N, ..., 1, where N is xxxValues-1. The Map parameters are read-only for all but RAM devices and a few file formats. Also, the strings returned are themselves always read-only; the only way to change a Map is to set the parameter. MaxRasterMemory - the maximum amount of RAM that can be allocated for raster memory. This is a constraint in addition to that imposed by the MaxRasterMemory system parameter. .PageCount - the number of times that the EndPage routine of this page device returned true. Normally, this is the same as the number of executions of showpage or copypage. .ShowpageCount - the number of times that showpage was executed with this page device; this is the value supplied to the BeginPage and EndPage procedures. .HWMargins - the widths of the unprintable areas at the left, bottom, right, and top edges of the page, expressed in 1/72" units. If ImagingBBox has not been specified, the default ImagingBBox is the PageSize inset by the .HWMargins. All other documented page device parameters, including Details dictionaries, are simply passed to the driver. Implementation - PostScript level ================================= Operators --------- .setdevice - Sets the current device without doing any of the things required by setpagedevice. Implementation - C level ======================== Driver interface ================ Appendix: Relationship to older Ghostscript versions ==================================================== Operators --------- Previous Ghostscript versions provided a set of device handling operators that were designed before the newer Adobe specifications were available. We now indicate how these map to newer facilities. .getdevice This low-level operator, renamed .indexdevice, still exists to allow enumerating the output devices. The standard way to enumerate OutputDevices is now (*) {...} /OutputDevice resourceforall. selectdevice This has been renamed .selectdevice, in keeping with Ghostscript practice of preceding all Ghostscript-specific operators with a dot. /outdevname selectdevice is essentially the same as << /OutputDevice /outdevname >> setpagedevice. currentdevice This has been renamed .currentdevice. setdevice We aren't sure what will happen to this. copydevice This is essentially equivalent to gsave .setdevice << >> setpagedevice .currentdevice grestore since setpagedevice always creates a new device. getdeviceprops Renamed .getoutputparams. devicename This can be implemented using .getoutputparams. deviceinitialmatrix This can be determined by selecting the device and then reading out the defaultmatrix. putdeviceprops This has been renamed .putoutputparams. Its status in the new scheme of things, like the status of setdevice, is unclear. makeimagedevice Replaced by setpagedevice with << /OutputDevice /RAM >>. The matrix, width, height, and palette arguments are replaced by parameters in the device dictionary. The default matrix is the identity matrix, the default width and height are 0, the default depth is 1, and the default palette is . copyscanlines We aren't sure whether to retain this or to replace it with an .imagefilter operator that provides a stream to read out the bits of a memory device. Page device parameters ---------------------- Previous Ghostscript versions had a concept of "device properties", which correspond to page device parameters in the current architecture. Here we list the correspondence between former Ghostscript device properties and current Ghostscript parameters. Prior Ghostscript Current Ghostscript ----------------- ------------------- Size and shape: InitialMatrix Margins, Orientation, Install Color: Colors [color]Values HWColorMap HW[color]Map Other: Name OutputDevice BufferSpace, MaxBitmap MaxRasterMemory Orientation, HWResolution, and Margins, together with the ability of the Install procedure to set the default CTM, are sufficient to specify all possible legal values of the initial transformation matrix. ****** Not sufficient to handle an inverted Y axis.