PRINT HINTS

LASERWRITER 8 FOR FUN AND PROFIT

MATT DEATHERAGE

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 printing
architecture.

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 QuickDraw GX.

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 time.

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 driver.

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 code.

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 be required.

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 doesn't help.

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 appears.

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.

PRINT HINTS

LASERWRITER 8 FOR FUN AND PROFIT

MATT DEATHERAGE

SUMMARY OF NEW API FEATURES IN LASERWRITER 8

RECOMMENDED READING