Related Info: Color QuickDraw Control Panel Gestalt Manager
Color Manager Palette Manager Graphics Devices

Color Quickdraw, Part II

Walking through the ColorMondrian code

By Dave Mark, MacTech Magazine Regular Contributing Author

Last month’s column introduced ColorMondrian, our first attempt at programming with Color QuickDraw. This month, we’ll walk through the ColorMondrian code and take a closer look at Color QuickDraw and Gestalt(), the Toolbox routine that knows everything there is to know about your Macintosh.

Before we get started, let’s take a quick look back at ColorMondrian. Figure 1 shows a sample ColorMondrian window. On a Macintosh with a single display, the window will appear centered below the menu bar. On a Macintosh with more than one display, the window will appear centered on the display with the deepest pixel settings (more on pixel depth in a minute). If that display contains the menu bar, the centering algorithm takes that into account.

Figure 1. ColorMondrian in action.

Another feature of ColorMondrian is the Devices menu. A hex address appears in the Devices menu for every monitor attached to your Macintosh. A check-mark appears next to the address representing the monitor with the deepest settings. Figure 2 shows my Devices menu.

Figure 2. My devices menu.

Some Color Quickdraw History

Early Macintosh models operated under a relatively simple graphics model. Color consisted of a choice of 8 colors (one of blackColor, whiteColor, redColor, greenColor, blueColor, cyanColor, magentaColor, and yellowColor). The color of the quickdraw pen was specified using the routines ForeColor() and BackColor(). This model was later named Classic QuickDraw.

On a Classic QuickDraw Mac, the display was built in to the Macintosh itself. A portion of RAM was dedicated to the pixels of the display. Since each pixel was either black or white, one bit was required for each pixel on the screen. Each row of pixels was represented by a sequence of bytes, each byte representing 8 consecutive pixels. The next row always started off with a new byte.

Remember the BitMapper program of a few month’s back? When it created a new BitMap, it had to calculate the proper value for the rowBytes field of the BitMap. Here’s the line of code that was used:

bPtr->rowBytes = (rPtr->right - rPtr->left + 7) / 8;

Alexei Lebedev (one of my CompuServe compatriots) rightly pointed out that this code contains an error. Here’s the correct code:

/* 1 */

bPtr->rowBytes = (rPtr->right - rPtr->left + 7) / 8;

i = bPtr->rowBytes / 2;

if ( (2 * i) != bPtr->rowBytes )
 bPtr->rowBytes ++;

Remember, we were trying to calculate the number of bytes needed to represent one row of pixels in the Rect pointed to by rPtr. The first calculation was pretty simple-minded. It forgot to take into account the fact that rowBytes must be even. An even simpler way to do this:

/* 2 */

bPtr->rowBytes = 
 (((rPtr->right - rPtr->left - 1) / 16) + 1) * 2;

This uses less code, accomplishes the same thing, but seems a little less readable to me. Ah, well, use whichever one you like...

As I was saying, a Classic QuickDraw Mac reserved part of main RAM to represent the pixels on the screen, approximately one bit per pixel (allowing for some possible wasted space at the end of each row). One bit-per-pixel is also known as a pixel-depth of 1. To represent the eight colors of Classic QuickDraw, you’d need a pixel-depth of 3 (to represent 8 possible values, you’d need 3 bits- 23 = 8)

When the Macintosh II was introduced, the first version of Color QuickDraw was also introduced. This version of Color QuickDraw allowed you to display up to 256 simultaneous colors, representing a pixel depth of 8. For the first time, a Mac was delivered that used a separate card for its video RAM, freeing up main RAM for application/System use! The Mac II also represented the first Mac with a separate monitor. The video card was attached to the mother board via the Mac’s new bus structure, named NuBus.

Later versions of Color QuickDraw allowed for higher pixel-depths. The version of Color QuickDraw that could handle a pixel-depth up to 32 became known as 32-Bit QuickDraw. When 32-Bit QuickDraw was first released, it required a separate extension to work, though this code was later added to the System and became a standard part of a Mac’s ROM.

Color QuickDraw represents each graphics device attached to your Mac (whether a display or an offscreen color device) using a gDevice data structure. Routines like GetNextDevice() and GetMainDevice() (you’ll see them in a bit, when we walk through the code) work with the list of gDevice’s maintained by Color QuickDraw and the Color Manager.

The RGB Model

Color QuickDraw represents colors using the RGB model. RGB stands for red, green, and blue, the three colors that combine to make up an RGB color. The RGB model is based on the RGBColor data structure:

struct RGBColor
{
 unsigned short red;
 unsigned short green;
 unsigned short blue;
};

Each component of an RGBColor can take on a value from 0 to 65535. If red, green, and blue are all 0, the RGBColor represents the color black. If all three are 65535, the RGBColor represents the color white. If red is 65535 and blue and green both 0, the color is red. You get the idea.

We’ll work with the RGB model throughout this program. Color QuickDraw does support two other color models (HSV, which is hue, saturation and brightness and CMY, which is cyan, magenta, yellow) and provides routines that convert colors between all three models.

Color Windows

To take advantage of the Color QuickDraw routines, you’ll want to replace your use of WindowRecords with CWindowRecords. CWindowRecords are similar to WindowRecords with a CGrafPort replacing the traditional GrafPort. Even with these changes, you can pass a pointer to a CWindowRecord to all the routines that usually take a WindowPtr. You’ll see how this works as we walk through the code.

Gestalt

Before we get to the code, there’s one more topic to cover. Gestalt() provides your application with information about the current state of your Mac’s hardware and software. Here’s the prototype for Gestalt():

OSErr Gestalt( OSType selector,long *response );

Gestalt() takes two parameters. The first, selector, allows you to tell Gestalt() what part of the hardware or software you are interested in. You can use Gestalt() to find out how much RAM is on the current Mac, what version of the operating system is installed, what processor this Mac is running, whether this machine supports Color QuickDraw, and much, much more.

Depending on the selector used, the second parameter, response, contains the requested information. You can tell the type of information returned by the last few characters of the selector. If the selector ends in Attr, the response is in the form of a 32-bit bitmap, where different bits stand for different features being available. A set of constants are available for each Attr selector you’ll use to see if the bits you are interested in are set.

If the selector ends in Count, the response is a number indicating an amount.

If the selector ends in Size, the response is a size, usually in bytes.

If the selector ends in Table, the response is the address of the first byte of a table.

If the selector ends in Type, the response is a value describing a particular type of feature. You’ll compare this value to a list of constants provided for each type.

If the selector ends in Version, the response is a version number. A version number with a decimal point (like 7.01) is usually represented as a two byte value with the left side of the decimal in the left byte and the right side of the decimal in the right byte.

Take the time to read about Gestalt(), either in Inside Macintosh or in THINK Reference. Take a look at each of the list of posssible selector codes in the “Using the Gestalt Manager” writeup.

In general, if you want to take advantage of a feature of the Macintosh that is not necessarily available on every Mac, you’ll want to call Gestalt() to make sure the feature is available. In case you were wondering, Gestalt() itself is not always available. The routine SysEnvirons() is a precursor to Gestalt(). THINK C (version 5.0 and later) provides special glue that converts your Gestalt() call to the appropriate SysEnvirons() call on a machine that doesn’t support Gestalt(). Therefore, you can always call Gestalt(). Be sure to check the error code returned by Gestalt(), just in case it has trouble processing your request.

The ColorMondrian Source Code

Let’s get started with last month’s source code. We started off with two important #includes. <stdio.h> was included to give us access to sprintf(). sprintf() was used to create the hex addresses in the Devices menu. <GestaltEqu.h> was included to give us access to Gestalt() and all its selector codes.

/* 3 */

#include <stdio.h>
#include <GestaltEqu.h>

These #defines will be explained as they appear in the code.

/* 4 */

#define kMBARResID 128
#define kErrorAlertID128
#define kAboutALRTid 129

#define kSleep   0L

#define kAutoStorage NULL
#define kVisible true
#define kWindowTitle "\pColorMondrian"
#define kMoveToFront (WindowPtr)-1
#define kNoGoAwayfalse
#define kNULLRefCon60L

#define mApple   128
#define iAbout   1

#define mFile    129
#define iQuit    1

#define mDevice  131

#define kWindowMargin5

#define kRandomUpperLimit 32768

#define kEmptyString "\p"
#define kNULLFilterProc   NULL

The global gDone is set to false initially, then set to true when Quit is selected from the File menu.

/* 5 */

/*************/
/*  Globals  */
/*************/

Boolean gDone;

As always, here are the function prototypes.

/* 6 */

/***************/
/*  Functions  */
/***************/

void    ToolboxInit( void );
void    MenuBarInit( void );
void    CreateWindow( GDHandle device );
void    EventLoop( void );
void    DoEvent( EventRecord *eventPtr );
void    HandleMouseDown( EventRecord *eventPtr );
void    HandleMenuChoice( long menuChoice );
void    HandleAppleChoice( short item );
void    HandleFileChoice( short item );
void    HandleDeviceChoice( short item );
Boolean HasColorQD( void );
GDHandleGetDeepestDevice( void );
short   GetDeviceDepth( GDHandle device );
void    DrawRandomRect( void );
void    RandomColor( RGBColor *colorPtr );
void    RandomRect( Rect *rectPtr );
short Randomize( short range );
void    DoError( Str255 errorString );

main() starts by initializing the Toolbox. Next, the routine HasColorQD() is called to see if Color QuickDraw is installed on this Macintosh. As you’ve probably guessed, HasColorQD() uses Gestalt() to answer this question. If Color QuickDraw is not available, an error message is displayed.

/* 7 */

/****************** main ***************************/

void main( void )
{
 ToolboxInit();
 
 if ( ! HasColorQD() )
 DoError(
 "\pThis machine doesn't support Color QuickDraw!" );

If Color QuickDraw is not installed, we should exit the program, probably by calling ExitToShell() immediately after DoError(). You might also exit the program from inside DoError().

A more sophisticated approach is to create a global Boolean named hasColorQuickDraw or somesuch that you set at the beginning of your program, and that you can check throughout your program. In many cases, you’ll want your program to work, whether Color QuickDraw is available or not. Using a global makes this information available throughout your program.

This approach is fine if the requested feature is something that won’t change as your program executes. For example, if Color QuickDraw is not installed, it won’t suddenly be installed halfway through your program’s execution.

On the other hand, there are some features of your environment that might change as your program runs. For example, the user might change the color depth of their monitor(s) as the program runs. If this is important to you, you can still represent this information via a global, but you’d better update the global frequently.

Next, the menu bar is set up and the ColorMondrian window is created. The routine GetDeepestDevice() returns a handle to the GDevice with the greatest pixel-depth. This handle is passed to CreateWindow().

/* 8 */

 MenuBarInit();
 
 CreateWindow( GetDeepestDevice() );

Once the window is created, we start the color shape generation loop.

 EventLoop();
}

Nothing new here.

/* 9 */

/****************** ToolboxInit *********************/

void ToolboxInit( void )
{
 InitGraf( &thePort );
 InitFonts();
 InitWindows();
 InitMenus();
 TEInit();
 InitDialogs( nil );
 InitCursor();
}

MenuBarInit() starts off by loading the MBAR resource and adding the DRVRs to the • menu.

/* 10 */

/****************** MenuBarInit ***********************/

void MenuBarInit( void )
{
 Handle menuBar;
 MenuHandle menu;
 GDHandle device, deepestDevice;
 Str255 itemStr;
 short  curDeviceNumber = 1;
 
 menuBar = GetNewMBar( kMBARResID );
 SetMenuBar( menuBar );

 menu = GetMHandle( mApple );
 AddResMenu( menu, 'DRVR' );

Next, we set up the Devices menu. We retrieve the MenuHandle so we can add items to it with AppendMenu(). Then, we retrieve a handle to the device with the deepest pixel-depth.

/* 11 */

 menu = GetMHandle( mDevice );
 
 deepestDevice = GetDeepestDevice();

Next, GetDeviceList() gets called. GetDeviceList() returns a handle to the first device in the list of devices. We’ll pass this device to GetNextDevice() to retrieve the next device in the list. When the device we pass to GetNextDevice() is the last device in the list, GetNextDevice() returns NULL.

/* 12 */

 device = GetDeviceList();

For each device in the list, we’ll create a 10 character pascal string which will contain the address, in hex, stored in the handle. We’ll use sprintf() to place the address, in the desired format, in itemStr. Finally, the item is added to the menu via AppendMenu().

/* 13 */

 while ( device != NULL )
 {
 itemStr[0] = 10;
 sprintf( (char *)(&(itemStr[1])), 
 "0x%08lX", (unsigned long)device );
 AppendMenu( menu, itemStr );

If the device just added was the deepest device, we’ll add a check mark to the item.

/* 14 */

 if ( device == deepestDevice )
 CheckItem( menu, curDeviceNumber, true );

Finally, we’ll call GetNextDevice() and bump the value in curDeviceNumber.

/* 15 */

 device = GetNextDevice( device );
 curDeviceNumber++;
 }

Once we drop out of the device loop, we draw the menu bar.

/* 16*/

 DrawMenuBar();
}

CreateWindow() creates a window on the specified device.

/* 17 */

/****************** CreateWindow ***********************/

void CreateWindow( GDHandle device )
{
 WindowPtrwindow;
 Rect   wBounds;

The handle stored in device must be dereferenced twice to get to the GDevice struct. The gdRect field is a Rect containing the devices bounding rectangle.

/* 18 */

 wBounds = (**device).gdRect;

GetMainDevice() returns a handle to the device containing the menu bar. If this device is the main device, we need to take the height of the menu bar into account when calculating the window’s Rect. GetMBarHeight() returns the height of the menu bar in pixels.

/* 19 */ 

 if ( device == GetMainDevice() )
 wBounds.top += GetMBarHeight();

We use InsetRect() to make the window a little smaller, purely for aesthetics.

/* 20 */

 InsetRect( &wBounds, kWindowMargin, kWindowMargin );

Now we call NewCWindow() to create a new CWindowRecord, as opposed to a WindowRecord created by NewWindow().

/* 21 */

 window = NewCWindow( kAutoStorage,
 &wBounds,
 kWindowTitle,
 kVisible,
 altDBoxProc,
 kMoveToFront,
 kNoGoAway,
 kNULLRefCon );

If the window couldn’t be created, we display an error message. Again, I should add a call to ExitToShell() at the end of DoError(), since there’s not a lot we can do without a window to draw in.

/* 22 */

 if ( window == nil )
 {
 DoError( "\pCouldn't create window!" );
 }
 else
 {
 ShowWindow( window );
 SetPort( window );
 }
}

EventLoop() is the same as it ever was, though we’ve added a call to DrawRandomRect() to draw a ColorMondrian shape.

You might want to add some code here to recheck the pixel depth of all monitors and update the check mark in the Devices menu if necessary. In fact, if the relative depth’s of the monitors change (let’s say the user changes the depth of a monitor using the Monitors control panel), you might want to move the window to the monitor that just became deepest.

/* 23 */

/*********************** EventLoop *********/

void EventLoop( void )
{
 EventRecordevent;
 
 GetDateTime( (unsigned long *)(&randSeed) );
 
 gDone = false;
 while ( gDone == false )
 {
 if ( WaitNextEvent( everyEvent, &event, kSleep, nil ) )
 DoEvent( &event );
 
 DrawRandomRect();
 }
}

Nothing new here.

/* 24 */

/************************ DoEvent **********/

void DoEvent( EventRecord *eventPtr )
{
 char theChar;
 
 switch ( eventPtr->what )
 {
 case mouseDown: 
 HandleMouseDown( eventPtr );
 break;
 case keyDown:
 case autoKey:
 theChar = eventPtr->message & charCodeMask;
 if ( (eventPtr->modifiers & cmdKey) != 0 ) 
 HandleMenuChoice( MenuKey( theChar ) );
 break;
 }
}

Nothing new here.

/* 25 */

/*********************** HandleMouseDown ***************/

void HandleMouseDown( EventRecord *eventPtr )
{
 WindowPtrwindow;
 short  thePart;
 long   menuChoice;
 
 thePart = FindWindow( eventPtr->where, &window );
 
 switch ( thePart )
 {
 case inMenuBar:
 menuChoice = MenuSelect( eventPtr->where );
 HandleMenuChoice( menuChoice );
 break;
 case inSysWindow : 
 SystemClick( eventPtr, window );
 break;
 }
}

Nope. Same as always.

/* 26 */

/****************** HandleMenuChoice ***********************/

void HandleMenuChoice( long menuChoice )
{
 short  menu;
 short  item;
 
 if ( menuChoice != 0 )
 {
 menu = HiWord( menuChoice );
 item = LoWord( menuChoice );
 
 switch ( menu )
 {
 case mApple:
 HandleAppleChoice( item );
 break;
 case mFile:
 HandleFileChoice( item );
 break;
 case mDevice:
 HandleDeviceChoice( item );
 break;
 }
 HiliteMenu( 0 );
 }
}

In HandleAppleChoice() we added an about alert.

/* 27 */

/****************** HandleAppleChoice ***********************/

void HandleAppleChoice( short item )
{
 MenuHandle appleMenu;
 Str255 accName;
 short  accNumber;
 
 switch ( item )
 {
 case iAbout:
 NoteAlert( kAboutALRTid, kNULLFilterProc );
 break;
 default:
 appleMenu = GetMHandle( mApple );
 GetItem( appleMenu, item, accName );
 accNumber = OpenDeskAcc( accName );
 break;
 }
}

Handle the File menu’s Quit item.

/* 28 */

/****************** HandleFileChoice ***********************/

void HandleFileChoice( short item )
{
 switch ( item )
 {
 case iQuit :
 gDone = true;
 break;
 }
}

This routine doesn’t do anything, but you might want to add some code here as indicated by the comment. The toughest part here is finding a system with more than one monitor to work with...

/* 29 */

/****************** HandleDeviceChoice ********************/

void HandleDeviceChoice( short item )
{
/* Try this:
 Modify the program so that when a device is selected
 from the Device menu, the current window gets closed and a
 new window is opened on the selected device. Be careful when
 you translate the menu item back into an address. Debug your
 program thoroughly before you try to use the address as an
 address. You don't want to accidentally reformat your hard 
 drive, right?
 
 Also, don't forget to update the check mark!
*/
}

Here’s our call to Gestalt() to tell whether Color QuickDraw is installed. The gestaltQuickDrawVersion selector retrieves a two byte value describing the version of QuickDraw installed on this machine. If the first byte is 1, 8-bit Color QuickDraw is installed. If the first byte is 2, 32-bit Color QuickDraw is installed. Either one of these is fine for our purposes.

/* 30 */

/****************** HasColorQD *****************/

Boolean HasColorQD( void )
{
 unsigned char   version[ 4 ];
 OSErr  err;
 
 err = Gestalt( gestaltQuickDrawVersion, (long *)version );

I should have called DoError() here. Either way, this doesn’t really represent a proper error-handling strategy. I’d love to see an article on error handling in a future issue of MacTech. Any takers?

/* 31 */

 if ( err != noErr )
 {
 SysBeep( 10 );  /*  Error calling Gestalt!!!  */
 ExitToShell();
 }

If the 3rd byte (this is a 4-byte value - the 3rd and 4th bytes contain the 2 version bytes) is 1 or more, Color QuickDraw is installed.

/* 32 */

 if ( version[ 2 ] > 0 )
 return( true );
 else
 return( false );
}

GetDeepestDevice() steps through the device list, calling GetDeviceDepth() to determine the device with the deepest pixel setting.

/* 33 */

/****************** GetDeepestDevice *****************/

GDHandle GetDeepestDevice( void )
{
 GDHandle curDevice, maxDevice = NULL;
 short  curDepth, maxDepth = 0;
 
 curDevice = GetDeviceList();
 
 while ( curDevice != NULL )
 {
 curDepth = GetDeviceDepth( curDevice );
 
 if ( curDepth > maxDepth )
 {
 maxDepth = curDepth;
 maxDevice = curDevice;
 }

 curDevice = GetNextDevice( curDevice );
 }
 
 return( maxDevice );
}

GetDeviceDepth() starts by retrieving a handle to the device’s PixMap from the GDevice struct. A PixMap is a color version of a BitMap. Check out the PixMap struct in Inside Macintosh.

/* 34 */

/****************** GetDeviceDepth *****************/

short GetDeviceDepth( GDHandle device )
{
 PixMapHandle  screenPixMapH;
 
 screenPixMapH = (**device).gdPMap;

The pixelSize field tells you the depth of this PixMap.

 return( (**screenPixMapH).pixelSize );
}

DrawRandomRect() creates a random rectangle in the current window, generates a random color, makes that color the current foreground color, then draws an oval in that color.

/* 35 */

/****************** DrawRandomRect *****************/

void DrawRandomRect( void )
{
 Rect   randomRect;
 RGBColor color;
 
 RandomRect( &randomRect );
 RandomColor( &color );
 RGBForeColor( &color );
 PaintOval( &randomRect );
}

RandomColor() randomly generates an RGBColor by randomly generating values for red, green, and blue that range from 0 to 65534. Remember, Random() generates values ranging from -32767 to 32767.

/* 36 */

/****************** RandomColor *********************/

void RandomColor( RGBColor *colorPtr )
{
 colorPtr->red = Random() + 32767;
 colorPtr->blue = Random() + 32767;
 colorPtr->green = Random() + 32767;
}

RandomRect() generates a random Rect in the frontmost window.

/* 37 */

/****************** RandomRect *********************/

void RandomRect( Rect *rectPtr )
{
 WindowPtrwindow;

 window = FrontWindow();
 
 rectPtr->left = Randomize( window->portRect.right
 - window->portRect.left );
 rectPtr->right = Randomize( window->portRect.right
 - window->portRect.left );
 rectPtr->top = Randomize( window->portRect.bottom
 - window->portRect.top );
 rectPtr->bottom = Randomize( window->portRect.bottom
 - window->portRect.top );
}

Randomize() generates a number from 0 to the specified upper limit.

/* 38 */

/****************** Randomize **********************/

short Randomize( short range )
{
 long   randomNumber;
 
 randomNumber = Random();
 
 if ( randomNumber < 0 )
 randomNumber *= -1;
 
 return( (randomNumber * range) / kRandomUpperLimit );
}


/***************** DoError ********************/

void DoError( Str255 errorString )
{
 ParamText( errorString, kEmptyString, 
 kEmptyString, kEmptyString );
 
 StopAlert( kErrorAlertID, kNULLFilterProc );
}

Till Next Month...

There’s a lot to learn about Color QuickDraw. Hopefully, this column gave you a good foothold. You will definitely want to read about the Color Manager, PixMaps, and the Palette Manager in Inside Macintosh. In the meantime, I’m going to try to update BitMapper to handle color. Look for PixMapper sometime soon...