Inside Macintosh: Imaging With QuickDraw /

Appendix B - Using Picture Comments for Printing

About Picture Comments

Within the drawing code sent to a printer driver after your application uses the PrOpenPage procedure, your application can specify picture comments by using the QuickDraw PicComment procedure. The PicComment procedure allows your application to pass data or commands directly to an output device.

PROCEDURE PicComment (kind: Integer; dataSize: Integer; 
                      dataHandle: Handle);

The kind parameter specifies the kind of picture comment, and the dataSize parameter specifies the size of the data referred to by the dataHandle parameter. (For some picture comments, the values passed in the dataSize and dataHandle parameters should be 0 and NIL, respectively.)

You typically use a picture comment to give your application and an output device additional control over the rendering of images. A number of picture comments have been given special definitions by various printer drivers. When a printer driver encounters one of these comments, it interprets the comment as an appropriate drawing operation. A PostScript printer driver, for example, may convert a picture comment into PostScript code.

By including picture comments in your code that draws into a printing graphics port, your application can rotate text and graphics, smooth polygons, draw hairlines, create dashed lines, and pass PostScript code directly to the printer driver. (For information about the PostScript language, see the PostScript Language Reference Manual, second edition, published by Addison-Wesley.)

Picture comments were initially designed to allow applications to share data in the form of QuickDraw pictures (as described in the chapter "Pictures" in this book). With the advent of the PostScript LaserWriter printer, the use of picture comments was extended to allow applications to more easily take advantage of various PostScript features unavailable with QuickDraw.

However, you do not need to create a QuickDraw picture to use picture comments for printing. When your application calls the Printing Manager procedure PrOpenPage, the printer driver collects your drawing operations after they are handled by the low-level drawing routines contained in the QDProcs record for the printing graphics port. As explained in the chapter "QuickDraw Drawing" in this book, the default low-level procedure specified by QuickDraw in the commentProc field of the QDProcs record is the StdComment procedure, which simply ignores picture comments. However, a printer driver can replace the StdComment procedure with its own routine for handling picture comments.

WARNING

As described in the chapter "Pictures" in this book, do not call the OpenCPicture or OpenPicture function between calls to PrOpenPage and PrClosePage.

When you use the PicComment procedure after calling PrOpenPage and before calling PrClosePage, the printer driver either ignores the picture comment passed to PicComment or collects the results of its drawing operations, depending on whether the printer driver has installed its own low-level drawing routine that handles the picture comment.

Although the PicComment procedure is available on all Macintosh computers, the availability of the drawing operations that you can implement with picture comments depends on the driver for the current printer. The inability to determine which picture comments are supported by the current printer driver means that if you use picture comments to perform drawing operations not supported by QuickDraw, you must also provide for printing on QuickDraw-only printers.

This requires your application to maintain separate code branches: for example, one that takes advantage of the picture comment handling of a PostScript printer driver, and another for a printer driver that supports only QuickDraw. Furthermore, you must hide the code that takes advantage of PostScript printer drivers from QuickDraw-based drivers, and you must hide from PostScript drivers the code that uses QuickDraw-based approximations of these drawing operations. Your application's printed output will necessarily differ depending on the driver for the current printer.

Table B-1 lists picture comments defined for various printer drivers produced by Apple and used by third-party producers of various other printer drivers. For each picture comment, this table shows the name of the picture comment that you specify in the kind parameter of the PicComment procedure, the value represented by the name, the value for the dataSize parameter, and the value for the dataHandle parameter. (Be sure to dispose of the memory you allocate for any handle you pass in the dataHandle parameter.) Keep in mind that it is impossible to determine which picture comments are supported by the driver of the current printer.

Table B-1 Names, values, and data sizes for picture comments (Continued)

Name	Value	Data size	Data handle	Description
Text picture comments
TextBegin	150	6	TTxtPicRec	Begin text function
TextEnd	151	0	NIL	End text function
StringBegin	152	0	NIL	Begin string delimitation
StringEnd	153	0	NIL	End string delimitation
TextCenter	154	8	TCenterRec	Offset to center of rotation for text
LineLayoutOff	155	0	NIL	Turn printer driver's line layout off
LineLayoutOn	156	0	NIL	Turn printer driver's line layout on
ClientLineLayout	157	16	TClientLLRec	Customize line layout error distribution
Graphics picture comments
PolyBegin	160	0	NIL	Begin special polygon
PolyEnd	161	0	NIL	End special polygon
PolyIgnore	163	0	NIL	Ignore following polygon data
PolySmooth	164	1	TPolyVerbRec	Close, fill, frame
PolyClose	165	0	NIL	Smooth the curve between endpoints
RotateBegin	200	8	TRotationRec	Begin rotated port
RotateEnd	201	0	NIL	End rotation
RotateCenter	202	8	TCenterRec	Offset to center of rotation
Line-drawing picture comments
DashedLine	180	Size of a TDashedLineRecrecord	TDashedLineRec	Draw following lines as dashed
DashedStop	181	0	NIL	End dashed lines
SetLineWidth	182	4	TLineWidthHdl	Set fractional line widths
PostScript picture comments
PostScriptBegin	190	0	NIL	Set driver state to PostScript
PostScriptEnd	191	0	NIL	Restore QuickDraw state
PostScriptHandle	192	Length of PostScript data	Handle	PostScript data referenced in handle
PostScriptFile	193	Length of PostScript data	Handle	Filename referenced in handle
TextIsPostScript	194	0	NIL	QuickDraw text is sent as PostScript
ResourcePS	195	8	Resource type, resource ID, index	PostScript data in a resource file
PSBeginNoSave	196	0	NIL	Set driver state to PostScript
Forms-printing picture comments
FormsPrinting	210	0	NIL	Don't clear print buffer after each page
EndFormsPrinting	211	0	NIL	End forms printing after PrClosePage
ColorSync picture comments
CMBeginProfile	220	0	NIL	Begin ColorSync profile
CMEndProfile	221	0	NIL	End ColorSync profile
CMEnableMatching	222	0	NIL	Begin ColorSync color matching
CMDisableMatching	223	0	NIL	End ColorSync color matching

All PostScript LaserWriter drivers support the picture comments listed in Table B-1.

Some third-party QuickDraw printer drivers support the TextBegin, TextCenter, and TextEnd picture comments.

The QuickDraw LaserWriter SC driver supports the LineLayoutOff, LineLayoutOn, and SetLineWidth picture comments.

The QuickDraw ImageWriter LQ driver and versions prior to 7.2 of the QuickDraw StyleWriter driver support the LineLayoutOff and LineLayoutOn picture comments.

The QuickDraw Personal LaserWriter LS driver and versions later than 7.2 of the QuickDraw StyleWriter driver support no picture comments at all.

The SetGrayLevel picture comment is now obsolete. The PostScriptFile, TextIsPostScript, FormsPrinting, EndFormsPrinting, ClientLineLayout, PSBeginNoSave, and ResourcePS picture comments have limited use and are no longer recommended.

See Advanced Color Imaging on the Mac OS for information about the picture comments used by the ColorSync Utilities.