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.

RECOMMENDED READING

• Inside Macintosh Volume II (Addison-Wesley, 1985), Chapter 5, and Volume V (Addison-Wesley, 1988), Chapter 22.
• 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. *