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 ofdevice handling in Ghostscript.  It is intended only for developerswith a fairly deep understanding of Level 2 PostScript. For an overview of Ghostscript and a list of the documentation files, seeREADME. ---------------------------------------------------------------- ****** MUCH OF THE MATERIAL IN THIS DOCUMENT IS UNRELIABLE.  DON'TTRUST IT. ****** Background========== PostScript language------------------- Adobe's Level 1 PostScript specification ignored, except for a fewnow-obsolete operators, the possibility of a single PostScript system thathad multiple hardware devices attached to it; Level 1 also did not deal, ina systematic way, with control of printing features such as page size andoutput finishing.  In contrast, the available Level 2 specifications (thePostScript Language Reference Manual, Second Edition, and subsequentdocumentation obtained from the Adobe file server describing AdobePostScript products through PostScript version 2013) include extensivefacilities in this area. Adobe's documentation refers explicitly to three concepts of "device": 	- A physical device such as a file system, a communication port, ora printing engine.  The IODevice resource enumerates these devices withoutproviding any other information about them.  Each IODevice may have a setof state variables specific to it; the setdevparams and currentdevparamsoperators control the state of individual IODevices.  (In the rest of thisdocument, we are not concerned with IODevices.) 	- A class of destination for rendering.  The OutputDevice resourceenumerates these, and gives some further information (available page sizesand resolutions).  OutputDevices do not have state per se, although inAdobe's model, they typically correspond 1-for-1 with those IODevices thatcan serve as destinations for rendering. 	- An actual destination for rendering.  This may be a specialdestination like the null device or a cache device, a display (for whichthe documentation specifies no further details), or an instance of anOutputDevice.  OutputDevice instances are called "page devices".  The onlydirectly visible, program-controlled state of a page device is thecontents of the current page.  However, page devices also have a verylarge set of optional parameters that may be set when setpagedevicecreates the instance, and read by currentpagedevice; some of theseparameters may change from time to time as a result of external events orconditions.  The parameters control both external hardware (e.g., duplexor collation) and internally implemented facilities such as portrait vs.landscape orientation. Ghostscript----------- Ghostscript generalizes the Adobe model in several areas at the level ofthe PostScript program. 	- In addition to hard copy devices, Ghostscript can produce outputon physical displays, window systems, raster files, or RAM; a typicalGhostscript configuration supports more than one of these.  Ghostscriptmodels this by providing new OutputDevices, and a new concept called anOutputDevice family for grouping them. 	- Ghostscript normally includes multiple drivers that can write tothe same physical device (for example, multiple raster file formatgenerators, or multiple printer drivers).  Ghostscript models this bymaking each driver a different OutputDevice. 	- Ghostscript explicitly makes visible the objects that representOutputDevice instances (page devices and their display, file, and RAManalogues) as new PostScript objects of type /devicetype. In the remainder of this document, we describe Ghostscript's handling ofdevices from four viewpoints: that of an ordinary PostScript program, thatof the Ghostscript implementation at the PostScript level, that of theGhostscript implementation at the C level, and that of the Ghostscriptdevice driver. PostScript programs=================== OutputDevice resource--------------------- The OutputDevice resource is described in Adobe documentation as havingbeen added in Adobe interpreter version 2011.  Briefly, the resource namesare the same as the allowed values of the /OutputDevice page deviceparameter, and the resource values are dictionaries giving properties ofthe output device.  The defined properties as of version 2012 areHWResolution, ManualSize, and PageSize. Ghostscript provides one OutputDevice for each available driver.  Thisincludes file formats (e.g., /gifmono) and display or window systems(e.g., /x11) as well as printer types (e.g., /ljet3).  It provides aspecial OutputDevice called /RAM whose instances simply accumulate abitmap in RAM for later readout.  In addition, if the available driversinclude any printer, fax, or display driver, Ghostscript providesOutputDevice entries called /Printer, /Fax, /RasterFile, and /Displayrespectively that are aliases for the default driver in the respectivefamily.  (There is nothing special about these three names.  Any drivercan declare that it belongs to a particular family, and the driver of anygiven family that appears earliest in the build list becomes the defaultdriver with that family name.)  Finally, Ghostscript always provides anOutputDevice called /Default that is an alias for the default OutputDevice(the one used if setpagedevice is invoked with no current page device andno OutputDevice key in the parameter dictionary). Operators--------- Ghostscript provides the setpagedevice and currentpagedevice operators, asrequired by the Level 2 PostScript specifications.  Ghostscript alsoprovides a few other operators that implement increased functionality. <int> .indexdevicename <outdevname> 	Returns the name of the int'th driver in the build list.  The firstdriver is numbered 0. <outdevname> .selectdevice 	Creates and makes current a default instance of a givenOutputDevice. - .currentdevice <device> 	Returns the current device, which may be a page device or a specialdevice. <outdevname> .getoutputparams <mark> <name1> <value1> ... <nameN> <valueN> 	Returns the parameters of a default instance of the givenOutputDevice.  Also returns the information for the OutputDevice resourcedictionary. <device> .getoutputparams <mark> <name1> <value1> ... <nameN> <valueN> 	Returns the parameters of a given device. Page device parameters---------------------- Most of the page device parameters documented by Adobe (either in the NewRed Book or in the post-Book notes) are specific to particular devices.Ghostscript leaves these up to the device driver to process, and onlyprovides the Policies and PolicyReport mechanism to handle those that areunknown or out of range.  Here are the parameters documented by Adobe thatGhostscript 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 notdocumented 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 Detailsdictionaries, are simply passed to the driver. Implementation - PostScript level================================= Operators--------- <device> .setdevice - 	Sets the current device without doing any of the things requiredby setpagedevice. Implementation - C level======================== Driver interface================ Appendix: Relationship to older Ghostscript versions==================================================== Operators--------- Previous Ghostscript versions provided a set of device handling operatorsthat 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 toallow enumerating the output devices.  The standard way to enumerateOutputDevices is now (*) {...} /OutputDevice resourceforall. selectdevice	This has been renamed .selectdevice, in keeping with Ghostscriptpractice 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 grestoresince 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 outthe defaultmatrix. putdeviceprops	This has been renamed .putoutputparams.  Its status in the newscheme of things, like the status of setdevice, is unclear. makeimagedevice	Replaced by setpagedevice with << /OutputDevice /RAM >>.  Thematrix, width, height, and palette arguments are replaced by parameters inthe device dictionary.  The default matrix is the identity matrix, thedefault width and height are 0, the default depth is 1, and the defaultpalette is <ff 00>. 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 amemory device. Page device parameters---------------------- Previous Ghostscript versions had a concept of "device properties", whichcorrespond to page device parameters in the current architecture.  Here welist the correspondence between former Ghostscript device properties andcurrent 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 theInstall procedure to set the default CTM, are sufficient to specify allpossible legal values of the initial transformation matrix.  ****** Notsufficient to handle an inverted Y axis.