TweetFollow Us on Twitter

June 1994 - Graphical Truffles

Graphical Truffles

The Debugging Version of QuickDraw GX

Pete ("Luke") Alexander

By now, many of you have installed one of the beta versions of QuickDraw GX onto your Macintosh -- and possibly by the time you read this, QuickDraw GX Software Developer's Kit version 1.0 will be available from APDA. Maybe you've played with the various sample applications and are now ready to work on your first QuickDraw GX application. Perhaps you've even read my article in develop; Issue 15, "Getting Started With QuickDraw GX." In this column, I'll talk about something I referred to briefly in that article: the two versions of QuickDraw GX's combined graphics and layout portions, and how to take advantage of the debugging version during the development of your QuickDraw GX-based application. Along the way I'll update you on a few changes since I wrote the article.

The QuickDraw GX system extension comes in two flavors: a nondebugging and a debugging version. When you run the QuickDraw GX installer script, the nondebugging version is installed, including the complete QuickDraw GX system. The nondebugging version is lean and mean, so it's significantly faster than the debugging version; it performs quite a bit less error checking than the debugging version.

The debugging version of the extension provides extensive error checking and other debugging amenities. When developing a QuickDraw GX application, you should use this version to shake out the bugs. The debugging extension is in the DEBUG Init folder and is named "GXGraphics (debug)" in version 1.0 (it used to be named aSecretGraphics.debug); just drag it into your System Folder and reboot. As your system starts up you'll see the debugging extension's icon displayed before the QuickDraw GX icon.

An explanation of what's really going on here may help clarify things (and it has changed): There are actually three extensions within the QuickDraw GX extension -- one for graphics and layout, one for printing, and one for the Finder printing extension. The QuickDraw GX extension knows, if "GXGraphics (debug)" has already loaded, to use that extension instead of the nondebugging version of the graphics and layout extension. (Note that since the debugging extension must load before the nondebugging version, you should not change the debugging extension's name.)

Let's look at some differences between the two extensions, and specifically how to take advantage of the debugging version during the development of your QuickDraw GX application.

Notices, warnings, and errors. With the debugging version of the extension, you can get three types of information about drawing problems: notices, warnings, and errors. For a complete list of these, look at the graphics errors.h interface file. The many notices, warnings, and errors defined between #ifdef debugging and #endif in that file are available only with the debugging version. You'll need to #define debugging in your application to take advantage of them. (Make sure debugging is not defined when you build your final version.)

With the nondebugging version, notices aren't available at all, and the list of errors and warnings you need to respond to in your application consists only of those relatively few that lie outside #ifdef debugging and #endif in the graphics errors.h file. Your application must be set up to handle these errors and warnings, which in general indicate that the QuickDraw GX system could not honor your application's request. For example:


The debugging version checks for errors that you're likely to run into while developing your application, such as passing a negative pen size to GXSetShapePen or a curve to GXGetGlyphMetrics. The nondebugging version doesn't check for these types of errors; it assumes you've already shaken them out of the code.

Validation routines. The GXSetValidation and GXValidateShape routines are available only in the debugging version. These routines allow your application to tell whether it's passing valid parameters into a QuickDraw GX function, to validate the contents of all QuickDraw GX objects (such as a shape, style, and ink) before their use, and to validate the QuickDraw GX memory your application is using.

Speed optimizations. The nondebugging version has optimizations for speed built in -- not only fewer error checks but also inline functions. The debugging version doesn't optimize for speed. This shouldn't have any impact on your application development except that there's not a one-to-one correspondence between stack crawls using the debugging and nondebugging versions. A performance analysis of your QuickDraw GX application should only be donewithout the "GXGraphics (debug)" file in your Extensions folder.

GraphicsBug. The GraphicsBug debugging tool allows you to explore the contents of any QuickDraw GX object to make sure it contains the correct information. Another change from before is that GraphicsBug is available in both the debugging and nondebugging versions. This ability to spy on an object's contents is important to your application development because otherwise you could only access information in objects by making API calls, which would be very tedious during debugging.

There's a slight advantage when using GraphicsBug with the debugging version: heaps are listed by name rather than by hex address in the Heaps menu.

Memory. The debugging version's memory blocks in the QuickDraw GX heap are a bit bigger to help detect errors when your application writes over the end of a block: all the blocks end with the same signature, 'grfx'.

Special MacsBug messages. The debugging version generates MacsBug messages that are intended solely for the consumption of the Apple engineers in unusual circumstances. (One of my favorites is "Curious if this ever happens.") If we did our jobs right, you should never see one of these messages. In case you do, however, we're really interested in hearing what caused you to receive it; please let us know at AppleLink APPLE.BUGS.

You should design your application to take advantage of the extensive capabilities of the debugging extension, but turn those capabilities off when you create your final shipping application, to improve its performance. For example, calling GXValidateShape with the nondebugging extension installed will only result in a jump and return (that is, it will be a no-op). This is a wonderful method for testing the QuickDraw GX dispatcher, but it doesn't help the performance of your application.

In the final compile of your shipping application, you'll most likely want to remove all calls to validation routines, posting of notices, and extra warnings and errors available only in the debugging version. One approach would be to have various compilation flags associated with pairs of #ifdef and #endif to turn these features on and off.

For more information, see my article in Issue 15 if you haven't already -- or just dig into the QuickDraw GX documentation. Enjoy your journey into the QuickDraw GX world!


  • "Getting Started With QuickDraw GX" by Pete ("Luke") Alexander, develop  Issue 15.
  • "Print Hints: Looking Ahead to QuickDraw GX" by Pete ("Luke") Alexander, develop  Issue 13.

PETE ("LUKE") ALEXANDER has been providing developer support for QuickDraw GX ever since it was way up in the air. He's happy it's making its final approach, and he's hoping it lands smack dab in the middle of your software. As a glider pilot, Luke knows how important control is -- and with QuickDraw GX, you'll be able to maneuver your software into spaces you never thought possible. Since QuickDraw GX can help you do lots of great graphics stunts that you used to have to ask him about, Luke is about to soar off into the wild blue yonder and do some stunts of his own. Soon he'll be ready for the preflight check that will launch his sabbatical faster than QuickDraw GX handles two-byte text. For many weeks he'll be thinking about nothing but white sand beaches, white puffy clouds, and white-capped mountains. He'll lie on his back and watch the sway of the trees until they stop reminding him of the swashes of L's. So if you see him somewhere in Montana, Utah, Nevada, California, or Idaho, be sure to say hello -- but try not to use any words that have a G and an X in them. *

Thanks to Hugo Ayala, Cary Clark, and Herb Derby for reviewing this column. *


Community Search:
MacTech Search:

Software Updates via MacUpdate

The best games like Animal Crossing on m...
Animal Crossing amiibo Festival is out right now for the Wii U, reminding us of just how much fun that world can be. Or at least to go back and check in on our villages once in a while. [Read more] | Read more »
Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »
Facility 47 (Games)
Facility 47 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: You wake up alone and freezing in an icy cell. You try the cell door but it’s locked, it seems that you are stuck with no... | Read more »
The best Photoshop alternative on iPad
Instagram and Lightroom are great and all, but sometimes people need to get extra creative with their image editing.Like, Photoshop creative. If you're one of these people, take a look at our pick for the best mobile Photoshop experience on iPad... | Read more »
The Walking Dead: No Man’s Land guide -...
A new update for The Walking Dead: No Man’s Land was released last week, making it the perfect time for you to head back to your base and take out some walkers. Here’s the lowdown on what’s new to the game, and how to take advantage. [Read more] | Read more »
Goat Rider guide - Tips and tricks to st...
We've all been there. One second, we're riding high on a crazed goat, and the next, we've been tossed off it like someone who's no good at goat ridin'. [Read more] | Read more »
Real Boxing 2 CREED: How to become a gre...
Just in time for Rocky fans who can’t wait to see CREED, the latest movie, we have the official tie-in game,Real Boxing 2 CREED. It builds on the success of its predecessor and there’s lots to take in so we at 148apps thought we’d run you through... | Read more »
CoinOp Heroes 2 guide - How to build an...
CoinOp Heroes 2 justlaunched and, like all clickers, it's dangerously addictive stuff. You have to furiously tap your screen to defeat wave after wave of foes and earn an insane amount of cash to spend on character upgrades and an army of minions... | Read more »
Dr. Panda Firefighters (Education)
Dr. Panda Firefighters 1.0.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0.1 (iTunes) Description: FIGHT FIRES AND SAVE THE DAY!Work together with Dr. Panda and his firefighting team to rescue his trapped... | Read more »
Puddle + (Games)
Puddle + 1.0 Device: iOS iPhone Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Puddle is back in a new "+" edition featuring enhanced graphics, new videos and Apple TV support ! No IAP and No Ads. Dive into Puddle... | Read more »

Price Scanner via

Save $30-$40 on new Apple TVs after rebate
Adorama has new Apple TVs on sale for up to $40 off MSRP after mail-in rebate, good through December 15th. Shipping is free, and Adorama charges NY & NJ sales tax only: - 32GB Apple TV: $119.99... Read more
13-Inch Haswell MacBook Air At Two Years – Th...
The 13-inch mid-2013 “Haswell” MacBook Air I ordered in Apple’s November 2013 Black Friday sale was my first new Mac in four and a half years — the longest interval I’ve gone between system upgrades... Read more
Target Black Friday Early Access deals: $100...
Target is offering early access to their Black Friday deals on Apple products on their online store for today, the 25th, only. Choose free shipping or free local store pickup (if available): - Apple... Read more
BlackBerry Q3 Mobility Index Report Finds iOS...
BlackBerry has announced results of its thirteenth Good Mobility Index Report, showing that organizations are increasingly building custom secure apps. Among Good Powered by BlackBerry (formerly Good... Read more
Wednesday roundup of early Black Friday Mac s...
Save up to $500 on a new Mac with these early Black Friday deals from Apple resellers, currently the lowest prices available for these models: (1) B&H Photo has all new Macs on sale for up to $... Read more
iPod nano on sale for $119, $30 off MSRP
Walmart has the 16GB iPod nano (various colors) on sale for $119.20 on their online store for a limited time. That’s $30 off MSRP. Choose free shipping or free local store pickup (if available). Sale... Read more
Adorama Black Friday deals: Up to $400 off Ma...
Adorama has released their Black Friday deals for 2015. Save up to $400 on MacBook Pros, $200 on MacBooks and MacBook Airs, and $270 on iMacs. Use code RYBFDEAL during checkout to see these prices.... Read more
B&H Photo Deals: $200 off 12-inch 1.2GHz...
In addition to the B&H Photo Black Friday week sales we posted yesterday, B&H has lowered their price on two products to $200 off MSRP: - 12″ 1.2GHz Gray Retina MacBook: $1399 save $200 - 13... Read more
Best Buy Early Access: Today only, Up to $125...
Best Buy has iPad Air 2s on sale for up to $125 off MSRP and Apple Watch models on sale on their online store for up to $100 off MSRP with special codes through midnight CT tonight. Choose free... Read more
UPPERCASE DESIGNS Premium Ultra Thin Keyboard...
UPPERCASE Designs today announced its new Premium Ultra Thin Keyboard Protector and its Palm Rest Protector Set for the 12-inch MacBook. The accessories provide durable protection for the 12-inch... Read more

Jobs Board

Hardware Systems Integration Engineer - *App...
# Hardware Systems Integration Engineer - Apple Watch Job Number: 39380139 Santa Clara Valley, Califo ia, United States Posted: Apr. 23, 2015 Weekly Hours: **Job Read more
Sr. Technical/Project Manager, *Apple* Educ...
# Sr. Technical/Project Manager, Apple Education Job Number: 36588557 New York City, New York, United States Posted: Jul. 30, 2015 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Merchant Operations Manager: *Apple* Pay -...
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 than Read more
*Apple* Pay QA Manager - 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 than Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.