TweetFollow Us on Twitter

GXGraphic Extension

Volume Number: 13 (1997)
Issue Number: 10
Column Tag: develop

Using the GXGraphics Extension

by Ingrid Kelly and Robin Mikawa, Apple Developer Technical Support

Using The GXGraphics Extension

Starting with Mac OS 8.0, the QuickDraw GX environment no longer supports the GX Printing Manager API. Although this decision will require significant changes to existing system software and applications, it will allow us to transition to a unified printing architecture that will improve the compatibility of QuickDraw GX software in the classic QuickDraw environment. Mac OS 8.0 includes the GXGraphics 1.1.6 extension, which provides the advanced Graphics and Typography capabilities of QuickDraw GX, a QuickDraw GX codec in the QuickTime 2.5 extension, and a fully integrated version of the Collection Manager. This article includes:

  • The changes needed for an application (GX aware, GX savvy, and GX dependent) to support GX Printing on Mac OS 8.0.
  • Where to get the current version of the GXGraphics extension (1.1.3) and a description of any differences with GXGraphics 1.1.6 included with Mac OS 8.0.
  • Any known incompatibilities or limitations of the GXGraphics extension, as well as known solutions to these problems. This Article is intended to help developers who wish to transition their GX products to support QuickDraw GX on Mac OS 8.0.

Note: Throughout this Article, the term, "classic printing architecture," refers to the Macintosh Printing Manager described in Chapter 9 of Inside Macintosh: Imaging With QuickDraw. "QuickDraw GX" refers to the full GX environment (i.e., Graphics, Typography, and Printing) and "GXGraphics" refers to the partial GX implementation provided by the GXGraphics extension (i.e., Graphics and Typography).

Features Not Supported in Mac OS 8.0

Following is a list of key features that are currently available in QuickDraw GX 1.1.3/1.1.5 that will no longer be available to developers under the GXGraphics 1.1.6 strategy:

  • GX Printer Driver APIs: GX Printer drivers will no longer be supported. All developers need to have a classic printer driver for their device.
  • GX Printing Extensions: GX Extensions will no longer be supported. Some developers may be able to roll their GX extension functionality into their application or driver.
  • Custom page formatting (the ability to arbitrarily specify page formatting within a single document): This feature will no longer be available. This feature could be implemented using the extended print record architecture added with LaserWriter version 8.4. See develop Journal Issue 27: 'The All-New LaserWriter Driver Version 8.4' for more information on the extended print record.
  • Portable Digital Document authoring: Developers will no longer be able to author PDDs via the GX Printing APIs. Also, SimpleText will not display PDDs under QuickDraw GX 1.1.6. You should convert PDD files to a different format, such as Adobe Acrobat PDF files, before attempting to use them with Mac OS 8 or QuickDraw GX 1.1.6
  • Vector Print Driver API: Under the new GX model, there will no longer be a custom API for vector printer driver developers. Vector printer drivers will have to be written with the classic printing architecture.

Overview of the GXGraphics Extension

The GXGraphics extension is a system extension that adds powerful graphics and typographic capabilities to your user's Macintosh without requiring the full QuickDraw GX package to be installed on your user's machine. The extension that we are currently licensing and distributing, GXGraphics 1.1.3, covers all QuickDraw GX graphics and typography functionality up to and including QuickDraw GX version 1.1.3.

GXGraphics 1.1.3

The GXGraphics 1.1.3 extension contains GX graphics and typography, but does not contain GX Printing. There are stubs for the GX Printing calls in QuickDrawGXLib/GXGraphics 1.1.3 but they do not work. This extension has been released and tested on 7.5.1 through 7.6. See Table 1 for more specific details.

GXGraphics 1.1.6

The GXGraphics 1.1.6 release contains GX graphics and typography, but will no longer have the printing stubs available. This extension has been tested and released for Mac OS 8.0. See Table 1 for more specific details.

NameVersionComponent Gestalt Selector
QuickDraw GX1.1.3, 1.1.5QuickDraw GX* qdgx (obsolete)
GX Printing* pmgr
GX Graphics* grfx
Collections Mgr* cltn
GXGraphics1.1.3GX Printing**
GXGraphics* grfx
Collections Mgr**
GXGraphics1.1.6GXGraphics* grfx

* APIs are exported and available
** APIs are exported but not available; you should use the gestalt selector on application launch to verify whether or not the functions are implemented.

Table 1. Differences in the QuickDraw GX Releases.

Note: With Mac OS 8.0, the Collections Manager APIs have been rolled out of QuickDraw GX and into the system.

Application Changes

Since the GX printing architecture will no longer be supported for Mac OS, any software that does not already have a solution using classic QuickDraw printing will need to be updated. For the majority of applications, the recommended solution for Mac OS 8.0 is to use the QuickTime compression/decompression mechanism for imaging QuickDraw GX data. The basic technique is to encapsulate the QuickDraw GX image in a compressed data format using the object flattening functions from QuickDraw GX. Once the compressed image data is created, it may be passed to the QuickDraw GX codec and drawn using the QuickTime image compression functions or embedded within a QuickDraw picture and drawn using the DrawPicture function. In either case, the compressed data is passed to the the low-level QuickDraw drawing routines through the StdPix bottleneck routine. StdPix decompresses the data using the QuickDraw GX codec and passes the decompressed data to the bitsProc bottleneck routine when rendering the image.

LaserWriter drivers starting with version 8.3 recognize compressed data that may be drawn using QuickTime, like QuickDraw GX flattened objects. For Mac OS 8.0, the LaserWriter driver has been modified to render the QuickDraw GX data at the device resolution of the printer. When despooling, the printer driver changes the resolution of the offscreen drawing port and uses the QuicDraw GX codec to rasterize the compressed data. The QuickDraw printer drivers from Apple render the compressed data during spooling and use the resolution of the active graphics port. Application developers may wish to use the device resolution commands of the PrGeneral routine to improve the quality of their printed images as described in "Meet PrGeneral, the Trap That Makes the Most of the Printing Manager," in develop 3.

General Changes For All Applications

The sample code for this Article includes updated versions of three QuickDraw GX user libraries, CodecLibrary, PrintingLibrary, and StorageLibrary, that may be used to simplify the conversion of your software. The TwoFace sample application supports the basic job, format, dialog, and spooling functions of the QuickDraw GX Printing Manager. It uses an abstraction layer provided by the PrintingLibrary to handle printing through the QuickDraw GX and classic QuickDraw printing architectures, depending on which environment is available when the application is launched. All the changes described in this section are handled automatically by the user libraries if you simply convert any references to the QuickDraw GX Printing Manager, including the gxJob and gxFormat data types, to the equivalent functions and data types of the PrintingLibrary.

1) Check the correct gestalt selector. Use the individual grfx and pmgr gestalt selectors rather than the obsolete qdgx gestalt selector.

Boolean gPrintingArchitecture = false;
long theFeature;

if ( Gestalt(gestaltGraphicsVersion, &theFeature) != noErr )
		return;

if ( Gestalt(gestaltGXPrintingMgrVersion, &theFeature)!= noErr )
	gPrintingArchitecture = kQDPrArch;
else
	gPrintingArchitecture = kGXPrArch;

2) For 68000 applications that use A-trap addresses to determine which parts of the GX environment are installed, use the individual gestalt selectors instead. This technique is not recommended but has been used by some applications in the past. If this is the case for your application, verify that you are checking the correct A-trap addresses:

Trap Address Technology
ABFEGX Printing
A832GX Graphics
ABF6Collections Manager

3) During initialization of a PowerPC application, check if the QuickDraw GX Printing library is installed. If the application is "weak" linked to the library, the Process Manager will launch it even if the library is missing, although the Code Fragment Manager will not resolve the addresses of the functions in the library. If the application calls any of these functions, it will crash. Your application should check if any of the Printing Manager functions cannot be resolved and exit gracefully if the library is missing. Note that the check could be performed against any function you call in the library. GXInitPrinting is often the first function that is called from the Printing Manager, so it is convenient.

if ( (UInt32)GXInitPrinting == UnresolvedCFragSymbolAddress )
	gPrintingArchitecture = kQDPrArch;

4) During printing, create a single picture shape for the contents of each page in the document. The PrintingLibrary includes a sample viewport filter function that handles this task from within the printing loop.

5) Use GXFlattenShape to create the compressed data for the QuickDraw GX codec. GXFlattenShape is described in detail in Inside Macintosh: QuickDraw GX Objects 2-88 to 2-89.

6) Use DecompressImage as described in "Printing Images Faster With Data Compression", in develop 24 (December 1995) to create the QuickDraw picture with the embedded QuickDraw GX data. When the application calls the standard DrawPicture function to display the image containing the compressed QuickDraw GX data, the StdPix function decompresses the image by invoking the Image Compression Manager. The CodecLibrary implements a function, GXCdShapeToPicture, that encodes the QuickDraw GX data as QuickTime compressed data and creates a PicHandle; an application may use this routine to create a QuickDraw picture prior to entering the printing loop or to convert a QuickDraw GX document to the QuickDraw PICT file format. DecompressImage is described in detail in Inside Macintosh: QuickTime, pages 3-78 to 3-79.

7) An alternative to Step 6 is to pass the flattened QuickDraw GX data directly to the custom StdPix bottleneck installed by the printer driver during printing. The CodecLibrary implements a function, GXCdDrawShape, that converts the QuickDraw GX data to a QuickTime encoded PixMap data structure, which it passes to the QuickDraw GX codec from within the printing loop. StdPix is described in detail in Inside Macintosh: QuickTime, pages 3-138 to 3-139.

Specific Changes Required Based on Level of Support

Here is an outline of the changes GX applications will need to make. They are outlined according to the level of GX support.

GX Unaware (no knowledge of GX)

  • No changes are needed

GX Aware (implements core GX Printing features)

  • Classic Printing code should be added using the new printing user library. (Step 1-7)

GX Savvy (implements support for Graphics, Typography and Printing)

  • Classic Printing code should be added using the new printing user library. (Step 1-7)

GX Dependent (requires GX to be installed to function)

  • Classic Printing code should be added using the new printing user library. (Step 1-7)

Additional Changes

Custom Page formatting

  • Currently, applications that wish to implement custom page formatting will have to spool multiple jobs per document. One job for each change in the page formatting.

It is important to note, that even today -- on System 7.5.x -- it is possible for an application using GXGraphics 1.1.x to print using the classic printing mechanism described above.

GX Printing Extension Changes

Printing extensions have been used for a wide variety of things in the history of GXPrinting. However, despite their potential for optimizing printing from certain kinds of applications, they have never been developed or used to their full potential by many developers. Unfortunately, under the new GX model , GX extensions are no longer available. Some of the functionality that developers have used GX extensions for can be rolled into classic applications or drivers, but that will have to be determined by the developer on a case-by-case basis.

GX Printer Driver Changes

Under the new GX model, GX printer drivers will no longer be supported. There is no transition plan for these drivers.

Classic Printer Driver Changes

  • In the world of GXGraphics 1.1.6 it will be desirable to print GX objects to classic printer drivers.

Raster

  • For raster printer drivers, the output from an updated GX application should match the high quality output today from GX drivers.

PostScript

For PostScript printer drivers however, there will be some changes required to add support for printing high-quality GX objects. We are currently working on determining what the best delivery mechanism for these changes will be (a library, an new API, atc.). As soon as we have a better idea of how to do this, we will update this Article to reflect the necessary changes.

PDD Changes

Under the new GX architecture, there is no way to author PDD documents. Also, SimpleText will not display PDD's under QuickDraw GX 1.1.6. You should convert PDD files to a different format, such as Adobe Acrobat PDF files, before attempting to use them with Mac OS 8 or QuickDraw GX 1.1.6.

Incompatibilities and Limitations

This section describes the known incompatibilities and limitations, and their solutions for the GXGraphics 1.1.6 extension:

  • Current versions of printer drivers may generate large spool files and take a long time to print when printing documents containing QuickDraw GX data. In addition, QuickDraw GX data printed to the Apple Color LaserWriter may be printed at less than full printer resolution. These problems will be addressed in future versions of printer drivers from Apple and other vendors.
  • With ATM 4.0.2, some PDF documents that use ATM substitution fonts may not print correctly using the LaserWriter 8 driver. This problem will be fixed in a future version of LaserWriter 8 which will be available in late summer 1997.
  • ATM 3.8.3 and 4.0 do not currently recognize that QuickDraw GX is installed when the GXGraphics extension is in your user's system. This causes problems with Type-1 enabled fonts. This problem has been fixed with the 4.0.2 release of ATM by Adobe Systems. Check with Adobe for a newer version of ATM Deluxe.
  • Some older QuickDraw pictures with embedded QuickDraw GX data may print with random noise in the background of the picture. This problem will be fixed in a future version of QuickTime.
  • Some QuickDraw GX data may print incorrectly in low memory conditions. You may notice that parts of the image repeat rather than the entire image printing correctly. This problem is in the QuickDraw GX QuickTime Codec and will be fixed in a future version of QuickTime.

Where To Get GXGraphics 1.1.6 And How To License It

The GXGraphics 1.1.6 extension

  • GXGraphics 1.1.6 is only available as part of the Mac OS 8.0 package. It is equivalent to the GXGraphics 1.1.3 release with a new installer and PPC library changes.

Software Licensing

  • For developers who wish to ship the GXGraphics extension with their product, you must contact Software Licensing at sw.license@apple.com or call them at 512-919-2645. Reference the QuickDraw GX software license to make sure you get the appropriate licensing agreement.

Conclusion

By simply following the above steps, you should easily be able to convert your GX applications into a viewable applications that your users will be able to use without having the complete GX extension installed.

Further References

  • Inside Macintosh: Imaging With QuickDraw
  • Inside Macintosh: QuickDraw GX Graphics
  • Inside Macintosh: QuickDraw GX Objects
  • Inside Macintosh: QuickTime
  • "The All-New LaserWriter Driver Version 8.4", in develop 27 by Dave Polaschek.
  • "Printing Images Faster With Data Compression", in develop 24 by David Gelphman.
  • "Meet PrGeneral, the Trap That Makes the Most of the Printing Manager", in develop issue 3 by Pete Alexander.
  • "A Print Loop That Cares--The Sequel", Technote 1092 by Ingrid Kelly.
  • "Adding Items to the Printing Manager's Dialogs", Technote 1080 by Ingrid Kelly and Dave Polaschek.

Acknowledgments

Thanks to Paul Danbold, David Goldsmith, David Hayward, Dan Lipton, and Dave Opstad.


Ingrid Kelly works in Apple's Developer Technical Support group answering questions about graphics, color and printing on the Mac OS. In a previous life, she worked at NASA in the Human Factors Research branch studying aircraft pilots, but she finds that studying people at Apple is much more interesting!

Robin Mikawa has recently returned to her first love as a graphics engineer on the QuickDraw GX project. A three-year stint on the WordScript engineering team has instilled her a love for typographical truffles, multilingual system software, and noodle-based dishes from all parts of the world.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

DiskCatalogMaker 7.1.3 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Amadeus Pro 2.4 - Multitrack sound recor...
Amadeus Pro lets you use your Mac for any audio-related task, such as live audio recording, digitizing tapes and records, converting between a variety of sound formats, etc. Thanks to its outstanding... Read more
Little Snitch 4.0.1 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Sparkle Pro 2.2.1 - $79.99
Sparkle Pro will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more
iWatermark Pro 2.0.0fc4 - Easily add wat...
iWatermark Pro is the essential watermarking app for professional, business, and personal use. Easily secure and protect your photos with text, a graphic, a signature, or a QR watermark. Once added... Read more
Together 3.8.7 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Together Features Smart storage. With simple drag-and-... Read more
DiskCatalogMaker 7.1.3 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Together 3.8.7 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Together Features Smart storage. With simple drag-and-... Read more
Little Snitch 4.0.1 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Sparkle Pro 2.2.1 - $79.99
Sparkle Pro will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more

Latest Forum Discussions

See All

Mix and match magical brews in Miracle M...
Miracle Merchant, the charming fantasy card game by Tiny Touch Tales, is arriving next week. The development team, which also brought you Card Crawl and Card Thief, announced the game's launch with a pleasant little trailer that showcases the game'... | Read more »
Last Day on Earth: Zombie Survival guide...
Last Day on Earth: Zombie Survival is the latest big hit in the survival game craze. The gist of the game is pretty cut and dry -- try your best to survive in a world overrun by flesh-eating zombies. But Last Day on Earth justifies the hype... | Read more »
Eden: Renaissance (Games)
Eden: Renaissance 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Eden: Renaissance is a thrilling turn-based puzzle adventure set in a luxurious world, offering a deep and moving... | Read more »
Glyph Quest Chronicles guide - how to ma...
Glyph Quest returns with a new free-to-play game, Glyph Quest Chronicles. Chronicles offers up more of the light-hearted, good humored fantasy fun that previous games featured, but with a few more refined tricks up its sleeve. It's a clever mix of... | Read more »
Catch yourself a Lugia and Articuno in P...
Pokémon Go Fest may have been a bit of a disaster, with Niantic offering fans full refunds and $100 worth of in-game curency to apologize for the failed event, but that hasn't ruined trainers' chances of catching new legendary Pokémon. Lugia nad... | Read more »
The best deals on the App Store this wee...
There are quite a few truly superb games on sale on the App Store this week. If you haven't played some of these, many of which are true classics, now's the time to jump on the bandwagon. Here are the deals you need to know about. [Read more] | Read more »
Realpolitiks Mobile (Games)
Realpolitiks Mobile 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: PLEASE NOTE: The game might not work properly on discontinued 1GB of RAM devices (iPhone 5s, iPhone 6, iPhone 6 Plus, iPad... | Read more »
Layton’s Mystery Journey (Games)
Layton’s Mystery Journey 1.0.0 Device: iOS Universal Category: Games Price: $15.99, Version: 1.0.0 (iTunes) Description: THE MUCH-LOVED LAYTON SERIES IS BACK WITH A 10TH ANNIVERSARY INSTALLMENT! Developed by LEVEL-5, LAYTON’S... | Read more »
Full Throttle Remastered (Games)
Full Throttle Remastered 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Originally released by LucasArts in 1995, Full Throttle is a classic graphic adventure game from industry legend Tim... | Read more »
Stunning shooter Morphite gets a new tra...
Morphite is officially landing on iOS in September. The game looks like the space shooter we've been needing on mobile, and we're going to see if it fits the bill quite shortly. The game's a collaborative effort between Blowfish Studios, We're Five... | Read more »

Price Scanner via MacPrices.net

PHOOZY World’s First Thermal Capsules to Summ...
Summer days spent soaking up the sun can be tough on smartphones, causing higher battery consumption and overheating. To solve this problem, eXclaim IP, LLC has introduced the PHOOZY Thermal Capsule... Read more
2018 Honda Ridgeline with Android Auto and Ap...
The 2018 Honda Ridgeline is arriving in dealerships nationwide with a Manufacturer’s Suggested Retail Price (MSRP1) starting at $29,630. The 2017 Honda Ridgeline was named North American Truck of the... Read more
comScore Ranks Top 15 U.S. Smartphone Apps fo...
comScore, Inc. recently released data from comScore Mobile Metrix, reporting the top smartphone apps in the U.S. by audience reach for June 2017. * “Apple Music,” as it appears in comScore’s monthly... Read more
13-inch 3.1GHz MacBook Pros on sale for $100...
B&H Photo has the new 2017 13″ 3.1GHz Space Gray MacBook Pros in stock today and on sale for $100 off MSRP including free shipping. B&H charges sales tax in NY and NJ only: – 13″ 3.1GHz/256GB... Read more
Apple refurbished Mac minis available startin...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: – 1.4GHz Mac mini: $419 $80 off MSRP – 2.6GHz Mac... Read more
Apple’s 2017 Back to School Promotion: Free B...
Purchase a new Mac using Apple’s Education discount, and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free. As part... Read more
Clearance 2016 13-inch MacBook Pros available...
B&H Photo has clearance 2016 13″ MacBook Pros in stock today for up to $220 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 13″ 2.9GHz/512GB Touch Bar... Read more
Apple Move Away from White Label Event Apps C...
DoubleDutch, Inc., a global provider of Live Engagement Marketing (LEM) solutions, has made a statement in the light of a game-changing announcement from Apple at this year’s WWDC conference.... Read more
70 Year Old Artist Creates Art Tools for the...
New Hampshire-based developer Pirate’s Moon has announced MyArtTools 1.1.3, the update to their precision drawing app, designed by artist Richard Hoeper exclusively for use with the 12.9-inch iPad... Read more
Sale! New 2017 13-inch 2.3GHz MacBook Pros fo...
Amazon has new 2017 13″ 2.3GHz/128GB MacBook Pros on sale today for $150 off MSRP including free shipping. Their prices are the lowest available for these models from any reseller: – 13″ 2.3GHz/128GB... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Poole -...
Job Summary The people here at Apple don't just create products - they create the kind of wonder that's revolutionised entire industries. It's the diversity of those Read more
SW Engineer *Apple* TV - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Product Manager - *Apple* Pay on the *Appl...
Job Summary Apple is looking for a talented product manager to drive the expansion of Apple Pay on the Apple Online Store. This position includes a unique Read more
*Apple* Retail - Multiple Positions - Apple...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.