December 93 - PRINT HINTS
LASERWRITER 8 FOR FUN AND PROFIT
In May of this year, Apple and Adobe Systems released version 8.0 of the LaserWriter driver -- the
biggest change to PostScript® printing on the Macintosh in eight years. This new driver was
rewritten from the ground up by engineers at Adobe, working closely with Apple engineers who
provided source code, guidance, and comprehensive testing. The resulting driver unleashes the power
of PostScript Level 2 printing as much as possible under the limitations of the pre-QuickDraw GX
Since the driver has been in general release for quite some time, we won't go through feature lists or
repeat things you've seen printed elsewhere. Instead we'll focus on how your application can
compatibly take advantage of the new driver's power. We'll also note some programming practices
that cause problems with LaserWriter 8 and that will continue to cause grief in the future with
WHERE TO FIND INFORMATION
The best news for programmers about this driver is that there's more information available for this
driver than for any printer driver before it. It follows the standard Printing Manager API
documented inInside MacintoshVolumes II and V, which you should stop reading immediately when
you can grab Inside Macintosh: Imaging With QuickDraw. The new book has vastly superior
organization and information about printing, including what's covered in the older Macintosh
Technical Notes, Q&As, and other sources of information Apple has refined through the years. Even
if you don't yet have the new book, everything in the older volumes and in the Technical Notes is
still valid, with few exceptions.
In addition, this issue's CD contains a 25-page document called "Developer Information," located in
the LaserWriter 8 folder, that talks about differences between the old and new drivers. Since this
driver was in open beta test from October 1992 through May 1993 as "PSWriter," the changes
shouldn't surprise too many people. The "Developer Information" document has been available since
October 1992 as well, so all kinds of great information have been at your fingertips for quite some
THE GROUND RULE
The new driver has several exciting new API calls to assist with PostScript printing and translation.
However, before getting into them, we must state The Ground Rule: While you're encouraged to use
new LaserWriter 8 features where appropriate, your application should not depend on them. Your handling of
printing or key services should not fail if the features aren't available.
Some users may not have upgraded to LaserWriter 8, and some may be running specialized versions
of the older driver and don't want to give it up. More important, however, is that the new API
features provided through PrGeneral arenot present in QuickDraw GX. In its initial release,
QuickDraw GX makes it easy for PostScript printer manufacturers to create their own drivers
supporting all their printer-specific features; under the old architecture this was about as easy as
removing your eyeballs from their sockets with your toes. This means there's a chance that a
customer will have softwarebeyondLaserWriter 8 that doesn't support the new calls documented on
the CD, so use them only if they're present.
For example, if you have an application that uses PostScript printer description (PPD) files to obtain
information about a target printer, you can use the new driver's PSPrimaryPPDOp selector to
PrGeneral to obtain an FSSpec referencing the PPD file the user chose for the current printer in the
Chooser. However, if the driver isn't available, the new PrGeneral calls return the error opNotImpl
(opcode not implemented) or resNotFound (the current driver doesn't support PrGeneral). In this
case, you should ask the user to locate the PPD file just as you did before LaserWriter 8 was
available. You shouldnot display an alert saying "You have the wrong printer driver chosen; go fix it."
Another example is in the powerful new functions that the driver provides for converting QuickDraw
pictures to encapsulated PostScript (EPS) format. If using these functions allows you to export EPS
data in a cross-platform document for higher fidelity on another system, that's great. If the driver
isn't available, though, you need to create your own EPS data or provide some alternate
representation of the data (perhaps a bitmap or a TIFF image).
Remember, these functions are there to use if they're available, but you can't require them. It's not
fair to remove features from your application based on the printer driver version. Try to use them if
you need to, but be prepared for when they're not present.
Sample code that helps explain the new features is also on the CD, in the same folder as the new
NEW THINGS YOU CAN DO
With that caveat on the table, let's discuss how some of the new features might affect your program.
There isn't room here to cover all the new APIs or their uses, so be sure to check out the
documentation and sample code on the CD for the comprehensive scoop.
PostScript printer description files. In addition to using PPD files in applications, some people
will need to create PPD files for custom in-house purposes, or because they're developing
PostScript-compatible hardware. There's a trick that's undocumented (and unguaranteed, so don't
write code that depends on this!) which lets the driver help you debug your PPD files: Normally,
when the driver parses a PPD file (during Chooser selection), it puts up a simple error dialog saying
"This PPD is invalid" if it finds a problem with the file. However, the driver has a resource of type
'PLRT' with ID 1 that contains a single byte, normally 0. If you change this byte to $01, the driver
will display an alert during PPD parsing saying exactly what it didn't like and on what line it didn't
like it. Since PPD files can get fairly complicated in short order, this feature can be extremely helpful.
This preference is stored in a PLRT resource only in versions 8.0 and 8.0.1 (shipping with Adobe
Acrobat). In later releases, it will be combined with some other useful preferences in a PRFS
resource. There's a resource editor TMPL template describing the bits in the PRFS resource. One of
these bits tells the driver to write all Printer Access Protocol (PAP) transactions to a PAPToDisk file
so that you can debug your printing code's output. This lets you see what the driver generates during
normal printing (not what it generates in the special case of creating a PostScript file) and is quite
handy. Have fun with the preferences, but remember not to ship code that relies on them -- don't
modify them from your code.
Dealing with EPS files. The older LaserWriter driver had been creating PostScript files as a
debugging aid for several years, and in version 7.0 this feature was finally added to the print job
dialog so that users could visibly control it. In 8.0, the file creation mechanism has been further
improved: it now provides user control over PostScript language level, font inclusion, and ASCII or
binary protocol, and can create EPS files on request. Since so many applications understand EPS
files, this feature gets a lot of exercise, and fosters some misunderstandings. The encapsulated
PostScript file format version 3.0 is discussed in Appendix H of Adobe'sPostScript Language Reference
Manual, Second Edition (the "red book"). The red book clearly states that an EPS file describes animage of a single page. That's why printing a range of pages to an EPS file gives you an image of
only the first page -- you can't have an image of more than one page in an EPS file.
The main problem users are having with EPS files created by the driver, however, is with the EPS
preview. This preview is an optional PICT resource of ID 256 which, if present, contains a
QuickDraw picture resembling what a PostScript interpreter would produce after executing the EPS
LaserWriter 8 does previews in three ways: it creates a picture that's one giant bitmap or pixel map
("standard preview"); it creates a picture containing all the drawing commands used to draw the page
("enhanced preview"); or it doesn't create a preview at all. The choice is the user's, or at least it'ssupposed to be. Some applications don't like the word "optional" very much and refuse to import EPS
files that don't contain the "optional" preview. Don't make the mistake of considering the preview to
Since the information for the preview picture comes from the drawing your application does into the
printing grafPort, there's trouble if your application doesn't draw things as the driver expects. For
example, some applications still examine the high byte of the wDev field in the print record and, if
they find the value 3, assume they're talking to a PostScript printer.
Such programs send all their data to be printed as custom PostScript code, not drawing anything into
the printing grafPort. This makes for an extremely boring preview image -- your code didn't draw
anything, so there's nothing in there to display.
If you create your own PostScript code,alwayssend dual QuickDraw and PostScript information
when printing or exporting pictures. Never create PostScript code without making as faithful a
QuickDraw representation as you can. Not only does this prevent EPS preview problems with
LaserWriter 8, it prevents problems under QuickDraw GX, where users can redirect print files after
you've finished your print loop but before they're imaged on a printer. If you sent only PostScript
code and the user redirects the print job to a StyleWriter II because the PostScript printer is busy,
the result will be a bunch of blank pages.
Some people have asked why EPS files created by the driver seem to be the size of a printed page
when the real image is only a small part of the page. That happens when your application doesn't
change the clipping rectangle for the image it's printing and when you send no QuickDraw code, but
only PostScript code. The driver watches all drawing you perform in the printing grafPort to
calculate the bounding rectangle for the EPS file; it has no way of knowing what that rectangle would
be for any PostScript code you send, so it relies on the clipping rectangle when your PostScript code
is sent through the printing grafPort. Use ClipRect to set the clipping rectangle of the printing
grafPort to match the height and width of your image. The driver will accumulate all your clipping
rectangles and make the bounding rectangle of the EPS file the smallest rectangle that encloses all of
them plus the bounding rectangles of all QuickDraw drawing you performed. If you send both
QuickDraw and PostScript code as recommended, you won't have this problem.
OLD THINGS THAT ARE DIFFERENT NOW
Some things are bound to change when you rewrite code from the ground up -- mostly
implementation details that were never guaranteed. That doesn't stop enterprising programmers
from finding such details and using them, though, and that's where a lot of compatibility problems
occur. Here are some things that have changed in the new driver that shouldn't have affected your
programs, but might have anyway.
Using private PostScript operators. Apple has advised programmers for a long time not to use
"Laser Prep" or "md" dictionary operators -- private PostScript operators used by the LaserWriter
driver to get its work done. Those operators were never documented or guaranteed to work, and as
the driver changed over the years so did many of the procedures, breaking applications that relied on
them. It's no big surprise that almost every one of those operators is either gone or changed in the
new driver. There's been some confusion in the past about just what Apple was trying to warn against, so I'm
pleased to take this opportunity to make it very clear:If it's not in the PostScript Language Reference
Manual, including appropriate supplements for your printer, don't use it.
Don't use any PostScript procedures you didn't define unless they're part of the language. If you find
a procedure defined in LaserWriter 8 that does something you want to do, don't call it! The
PostScript system in QuickDraw GX is entirely different from the one in LaserWriter 8; if you just
substitute one set of procedures that you shouldn't call for another, your application will break again
in the near future.
I would even avoid using printer-specific features, because with EPS files you're never sure what the
target printer will be. If you must use these features, wrap them in PostScript's "stop" mechanism so
that the job will complete even if the feature creates an error.
Precision Bitmap Alignment. In version 8.0, the Page Setup option "Precision Bitmap Alignment"
still says "(4% reduction)" at the end of the item in the Options dialog. That will change in versions
after 8.0 because the code will change.
In 8.0 and earlier, the Precision Bitmap Alignment option simply reduces the coordinate system to
96% of the former value, turning 300-dpi printers into 288-dpi printers. Since 288 dpi is an even
multiple of 72 dpi, the screen resolution, this prevents rounding errors in bitmaps where some bits
would be slightly larger than others. Unfortunately, this only solves the problem on 300-dpi printers.
On 400-dpi printers (such as are often found in Japan), it changes the resolution to 384 dpi, which
Sometime after 8.0, "Precision Bitmap Alignment" will start aligning to the nearest lower multiple of
72 dpi available on the target printer, calculated by the PostScript code when printing. On a 400-dpi
printer, that's 360 dpi for a 10% reduction. On a 600-dpi printer, it's 576 dpi and is again a 4%
reduction. The point is to get precisely aligned bitmaps, not to reduce by exactly 4%, and past 8.0
that's how it will work.
Font substitution. In the past, turning on fractional font widths with SetFractEnable(TRUE)
disabled font substitution. With LaserWriter 8, you always get font substitution when you ask for it.
In LaserWriter 7.1.1 through LaserWriter 7.2, turning off font substitution would sometimes give
you a TrueType version of a font if you had it -- even if the printer had a Type 1 version available
-- depending on whether you'd turned off line layout or enabled fractional font widths, and on what
day of the week it was. This inconsistent behavior is removed from LaserWriter 8: once again, Type
1 fonts are always picked over TrueType fonts if both are available to the printing system. This is
largely for compatibility with pre-TrueType systems.
Older customization resources. The older drivers supported mechanisms for adding device-
specific items to non-Apple printers, such as custom page sizes and code to enable sheet feeders.
These resources, if present, are ignored by LaserWriter 8 -- printer manufacturers can control
feeders, custom page sizes, and other device-specific features through PPD files. We later discovered
that some enterprising developers were using the 'feed' resource to control things other than sheet
feeders, since the mechanism gave them a chance to execute code on the Macintosh during the job
dialog. That wasn't what it was designed for, so no one made any effort to make sure that would still
work. That mechanism is now gone.
Color QuickDraw pixel patterns. Before LaserWriter 8, attempting to print with pixel patterns (as
opposed to older black-and-white patterns) generally produced stunning black blobs on your page.
With LaserWriter 8, printing with pixel patterns works just as you'd hope it would if the user
chooses either "Color/Grayscale" or "Calibrated Color/Grayscale" (making the printing grafPort a
cGrafPort) and if the printer supports PostScript Level 2 so the driver can use the Level 2 PostScript
pattern mechanism. On Level 1 devices, pixel patterns are implemented using screens (color screens
if available, halftone screens otherwise) and the patterns are clipped to their upper left eight-by-eight
grid, matching the dimensions of a regular QuickDraw pattern. Even though the implementationisn't perfect on Level 1 devices, something much closer to your desired pattern than a black blob now
Preferences file. The new driver keeps a preferences file in the Preferences folder (or in the System
Folder under System 6). It's in this file that the driver stores the parsed PPD data, plus the recorded
choices of which printers match which PPDs and some other driver-specific data that needs to stick
around. If you ever update drivers manually, delete the old preferences file. Its contentswillchange
from version to version. If you share one driver file among systems trying to isolate or reproduce a
problem and you want to have the best chance of seeing the problem again, be sure to keep the
preferences file with the driver as you bop between systems.
THE REST IS WAITING FOR YOU
If you have comments or bugs to report about the LaserWriter 8 driver, you can send them on
AppleLink to the read-only address LWDRIVER.BUG. You won't get a response or an
acknowledgment, but your feedback will get to the people responsible for making changes. Don't
forget to look at the information on the CD for the complete story!
SUMMARY OF NEW API FEATURES IN LASERWRITER 8
These are new selectors to PrGeneral. Full details and sample code are located on the CD. Remember, don't
even think about requiring these calls in your program.
- PSPrimaryPPDOp: Returns an FSSpec record locating the PPD file chosen for this printer, along with a
Boolean value indicating whether the file is the built-in "generic" PPD.
- getPSInfoOp:Informs you if the target printer supports PostScript Level 2 and binary communications. Also
tells you what kind of PostScript file the user chose to create, if any: EPS with no preview, EPS with
standard preview, EPS with enhanced preview, or PostScript job file format.
- PSIntentionsOp: Allows your code to tell the driver that you intend to use PostScript Level 2 or binary
communications features, so that the driver can generate appropriate DSC (document structuring
conventions) comments and return errors if the target printer doesn't support those features.
- PSpict2eps: Converts a QuickDraw picture into an EPS stream. You can specify most of the parameters in
the style and job dialogs, and you provide a callback routine that receives the EPS stream as it's created.
- PSFontInfo: Provides a PostScript stream to make a given outline font available on a PostScript interpreter,
including the TrueType scaler and TrueType conversions of fonts if necessary. You provide a callback
routine to receive the font information from the driver. Bitmap fonts are not supported.
- Inside Macintosh Volume II (Addison-Wesley, 1985), Chapter 5, and Volume V (Addison-Wesley, 1988),
- Inside Macintosh: Imaging With QuickDraw (Addison-Wesley, forthcoming).
- "Meet PrGeneral, the Trap That Makes the Most of the Printing Manager" by Pete ("Luke") Alexander,develop Issue 3.
- "Print Hints: Top 10 Printing Crimes" by Pete ("Luke") Alexander, develop Issue 10.
- "Print Hints: Top 10 Printing Misdemeanors" by Pete ("Luke") Alexander, develop Issue 12.
- Macintosh Technical Note "Picture Comments -- the Real Deal" (QuickDraw 10).
While we refer to the driver here as "LaserWriter 8," Adobe distributes the same driver as "PSPrinter." Adobe also
licenses the driver to printer manufacturers who license PostScript language software from Adobe, and those printermakers may call the driver by different names as well. Apple's initial release of the driver is named "LaserWriter 8.0," but
later releases (which may happen by the time this is published) will be named "LaserWriter 8." No matter what the driver
is called or how the icons appear, the internals are the same and all the information here applies. *
For more information on PrGeneral, see the article "Meet PrGeneral, the Trap That Makes the Most of the Printing
Manager" in develop Issue 3.*
Information on PostScript printer description files and other items related to PostScript language development
are available from the Adobe Systems Developers' Association, 1585 Charleston Road, P.O. Box 7900, Mountain View,
CA, 94039-7900, telephone (415)961-4111.*
Document structuring conventions are discussed in Appendix G of thePostScript Language Reference Manual,
second edition. *
MATT DEATHERAGE (AppleLink DEATHERAGE1) has been doing technical support for over five years. In addition to
serving as the technical lead for the LaserWriter 8 driver in Apple's Developer Technical Support group, he's worked on
several Apple printer projects when not focusing on fonts or typography or all the other fun imaging stuff there's never
enough time for. He remains true to his background by running the Apple II Programmers and Developers roundtable on
GEnie, but you can find him on-line in lots of other places, usually just where you're hoping he won't be. *
Thanks to Waymen Askey, Richard Blanchard, and Steve Winters for reviewing this column. *