Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

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.

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)
NameValueData sizeData handleDescription
Text picture comments   
TextBegin1506TTxtPicRecBegin text function
TextEnd1510NILEnd text function
StringBegin1520NILBegin string delimitation
StringEnd1530NILEnd string delimitation
TextCenter1548TCenterRecOffset to center of rotation for text
LineLayoutOff1550NILTurn printer driver's line layout off
LineLayoutOn1560NILTurn printer driver's line layout on
ClientLineLayout15716TClientLLRecCustomize line layout error distribution
Graphics picture comments   
PolyBegin1600NILBegin special polygon
PolyEnd1610NILEnd special polygon
PolyIgnore1630NILIgnore following polygon data
PolySmooth1641TPolyVerbRecClose, fill, frame
PolyClose1650NILSmooth the curve between endpoints
RotateBegin2008TRotationRecBegin rotated port
RotateEnd2010NILEnd rotation
RotateCenter2028TCenterRecOffset to center of rotation
Line-drawing picture comments   
DashedLine180Size of a TDashedLineRecrecordTDashedLineRecDraw following lines as dashed
DashedStop1810NILEnd dashed lines
SetLineWidth1824TLineWidthHdlSet fractional line widths
PostScript picture comments   
PostScriptBegin1900NILSet driver state to PostScript
PostScriptEnd1910NILRestore QuickDraw state
PostScriptHandle192Length of PostScript dataHandlePostScript data referenced in handle
PostScriptFile193Length of PostScript dataHandleFilename referenced in handle
TextIsPostScript1940NILQuickDraw text is sent as PostScript
ResourcePS1958Resource type, resource ID, indexPostScript data in a resource file
PSBeginNoSave1960NILSet driver state to PostScript
Forms-printing picture comments   
FormsPrinting2100NILDon't clear print buffer after each page
EndFormsPrinting2110NILEnd forms printing after PrClosePage
ColorSync picture comments  
CMBeginProfile2200NILBegin ColorSync profile
CMEndProfile2210NILEnd ColorSync profile
CMEnableMatching2220NILBegin ColorSync color matching
CMDisableMatching2230NILEnd 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.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996