BRAVING OFFSCREEN WORLDS

GUILLERMO ORTIZ

No one disputes the benefits of using offscreen environments to prepare and keep the contents of windows. The only problem is that creating such environments--from a simple pixMap to a more complicated GDevice--can be rather difficult. 32-Bit QuickDraw includes a set of calls that allows an application to create offscreen worlds easily and effectively. This article describes those calls and provides details on how to use them.

Until now, creating and maintaining offscreen devices or ports has been complicated and confusing at best. As part of 32-Bit QuickDraw, Apple's engineering team has included a set of calls that makes creating and maintaining offscreen devices and ports a real breeze. Using the offscreen graphics environment, QuickDraw can maintain the data alignment necessary to improve the performance of CopyBits when you use it to display onscreen the contents of the offscreen buffer.

Also, applications using the offscreen world support from QuickDraw are more likely to benefit from future enhancements to QuickDraw than programs doing their own offscreen management. This can save you a lot of time down the road.

The offscreen world offers a few more benefits:

• The system takes care of all the messy details involved in creating the offscreen GDevice. You don't need to bother asking "What flags should I set?" or "What is the refNum for an offscreen device?"
• You can tailor the offscreen port according to your specifications rather than being restricted to screenBits.bounds. Because the visRgn comes set to the right dimensions, you won't need to change anything.
• The pixMap associated with the offscreen world comes back from the call complete and ready to use. You won't have to lose sleep wondering if you set the correct value for rowBytes or if your baseAddress pointer has less memory than it should because the compiler didn't do the multiplication using Longs.

Think of the GWorld structure as an extension to the CGrafPort structure, containing the port information along with the device data and some extra state information. In most cases, a GWorldPtr can be used interchangeably with a CGrafPtr, which makes converting applications quite easy. At this point, however, Apple is keeping the structure of an offscreen graphics world private to allow for further expansion.

For instance, in the following section of Developer Technical Support's sample program FracApp, the new calls were implemented without changing the document's data structure at all. This example illustrates the difference the new set of calls can make when creating offscreen environments.

A LOOK AT THE NEW CALLS

Let's use a section of the sample program FracApp to illustrate the difference this new set of calls can make when creating offscreen environments. The procedure TFracAppDocument.BuildOffWorld creates a new device and its accompanying structures for each document. Here is the original code, with comments shortened, followed by the equivalent code using the new calls:

PROCEDURE  TFracAppDocument.BuildOffWorld (sizeOfDoc: Rect);
VAR oldPerm:    Boolean;
        dummy:  Boolean;
        docW, docH: LongInt;
        fi:     FailInfo;
        currDevice: GDHandle;
        currPort:   GrafPtr;
        Erry:   OSErr;
    
    PROCEDURE DeathBuildOff (error: OSErr; message: LONGINT);
    {Error handler}

    BEGIN
        oldPerm := PermAllocation (oldPerm);    
        { Set memory back to previous. }
        
        SetGDevice (currDevice);    
        { Set device back to main, just in case. }
        SetPort (currPort);
    END;

BEGIN
    currDevice := GetGDevice;   { save current for error handling. }
    GetPort(currPort);
    
    oldPerm := PermAllocation (TRUE);

    CatchFailures(fi, DeathBuildOff);   { any failures, must be }
                                        { cleaned up. }

    { Let's set up the size of the rectangle we are using for the }
    { document. }
    docW := sizeOfDoc.right - sizeOfDoc.left;
    docH := sizeOfDoc.bottom - sizeOfDoc.top;


    { Now try to set up the offscreen bitMap (color). }
    fBigBuff := NewPtr (docW * docH);
    FailMemError;       { couldn't get it we die. }


    { OK, now we get wacko.  We need to create our own gDevice, }
            
    fDrawingDevice := NewGDevice (0, -1);  { -1 means unphysical }
                                           { device.  }
    FailNIL (fDrawingDevice);       { If we failed, error out. }
    
    { Now init all the fields in the gDevice Record, since it comes }
    { uninitialized. }
    HLock ( Handle(fDrawingDevice) );
    WITH  fDrawingDevice^^  DO  BEGIN
        gdId := 0;  { no ID for search & complement procs }
        gdType := clutType;     { color table type fer sure. }
        
        DisposCTable (gdPMap^^.pmTable);  { kill the stub that is }
                                          { there. }
        gdPMap^^.pmTable := gOurColors;   { make a copy of our }
                                          { global color table. }
        Erry := HandToHand (Handle(gdPMap^^.pmTable));
        FailOSErr (Erry);   { if not possible, blow out. }
        
        { build a new iTable for this device }
        MakeITable (gdPMap^^.pmTable, gdITable, 3);
        FailOSErr (QDError);{ no memory, we can leave here. }
        
        gdResPref := 3;{ preferred resolution in table. }
        gdSearchProc := NIL; { no search proc. }
        gdCompProc := NIL;  { no complement proc. }
        { Set the gdFlags }
        gdFlags := 2**0 + 2**10 + 2**14 + 2**15;  { set each bit we }
                                                  { need. }
        
        { Now set up the fields in the offscreen PixMap }
        gdPMap^^.baseAddr := fBigBuff;  { The base address is our }
                                        { buffer. }
        gdPMap^^.bounds := sizeOfDoc;   { bounding rectangle to our }
                                        { device. }

        gdPMap^^.rowBytes := docW + $8000;
        gdPMap^^.pixelSize := 8;
        gdPMap^^.cmpCount := 1;
        gdPMap^^.cmpSize := 8;
        
        gdRect := sizeOfDoc;  { the bounding rectangle for gDevice, }
                              { too. }
    END;        { With fDrawingDevice }
        
    HUnLock ( Handle(fDrawingDevice) );

    { Yow, that was rough.}
    SetGDevice (fDrawingDevice);
    

    fDrawingPort := CGrafPtr( NewPtr (SizeOf (CGrafPort)) );
                                               { addr CPort record. }
    FailNil (fDrawingPort); { didn't get it, means we die. }
    
    { Now the world is created }
    dummy := PermAllocation (FALSE);

    OpenCPort (fDrawingPort);   { make a new port offscreen. }
    FailNoReserve;      { Make reserve, die if we can't }
        
    { QuickDraw is most obnoxious about making a port that is bigger
    than the screen, so we need to modify the visRgn to make it as
    big as our full page document }
    RectRgn(fDrawingPort^.visRgn, sizeOfDoc);

    fDrawingPort^.portRect := sizeOfDoc;

    { OK, we have a nice new color port that is offscreen. }
    Success (fi);

    oldPerm := PermAllocation (oldPerm);

    { Now we have the offscreen PixMap, we need to initialize it to
    white. }
    SetPort (GrafPtr(fDrawingPort));
    EraseRect (sizeOfDoc);      { clear the bits. }

    SetGDevice (currDevice);
    SetPort (currPort);
END;    { BuildOffWorld }

Now let's see what the equivalent code looks like when we use the calls provided by 32-Bit QuickDraw and its offscreen support:

PROCEDURE TFracAppDocument.BuildOffWorld(sizeOfDoc:RECT); 
VAR oldPerm :Boolean;
        fi  :FailInfo;
        currDev :GDHandle;
        currPort    :CGrafPtr;
        erry    :QDErr;
        
    PROCEDURE DeathBuildOff (error: OSErr; message:LONGINT);
    
    BEGIN
        oldPerm := PermAllocation(oldPerm);
        SetGWorld (currPort,  currDev); 
    END;
    
BEGIN  (*myBuildOffWorld*)
    GetGWorld(currPort,  currDev);
    CatchFailures(fi, DeathDocument);
    Erry := NewGWorld(fDrawingPort, 8, sizeOfDoc, gOurColors, NIL,
        GWorldFlags(0));
    FailOSErr(Erry);
    
    SetGWorld (fDrawingPort,  NIL); 
    
    IF ( NOT LockPixels(fDrawingPort^.portPixMap) ) THEN
    FailOSErr(QDError);
    
        EraseRect(FDrawingPort^.portRect);
    
    UnlockPixels (fDrawingPort^.portPixMap); 
    
    SetGWorld (currPort,  currDev); 
END {myBuildOffWorld};

CALLS YOU CAN'T DO WITHOUT

The new routines simplify the code and help prevent the typical errors you make having to initialize all those special fields. It only makes sense to make your work easier if you can. Here are the calls in the order they appear in the sample code:

PROCEDURE GetGWorld(VAR port:CGrafPtr; VAR gdh:GDHandle)

This call takes the place of two standard calls, GetPort and GetGDevice. It saves the current settings for later restoration and works for offscreen worlds as well as old-style ports.

• port is set to the current port, which can be a GrafPtr, a CGrafPtr, or a GWorldPtr.
• gdh returns the current device.

FUNCTION NewGWorld(VAR offscreenWorld: GWorldPtr; pixelDepth:
        INTEGER; boundsRect: Rect; cTable:CTabHandle;
        aGDevice: GDHandle; flags: GWorldFlags): QDErr;

This is the call that does the work. If the function returns noErr, then offscreenWorld contains a pointer to the newly created offscreen environment. If the function does not return noErr, then something didn't work. Most likely the Memory Manager couldn't allocate enough memory for all the structures. In that case, your program has to decide what to do next, such as draw to the window's port, sacrificing speed, features, or both.

Possible error returns other than noErr are cDepthErr (no such depth is possible), paramErr (illegal parameter), plus any Memory Manager or QuickDraw errors.

• pixelDepth must be 1, 2, 4, 8, 16, or 32 bits per pixel. With one exception, other values will make the call return cDepthErr. pixelDepth can be 0, as described later in this article.
• boundsRect is used to calculate the offscreen pixMap's size and coordinate system. It is also used to set portRect, pixMap bounds, gdRect, and the port's visRgn.
• When it is provided, cTable is copied and the copy is used for the offscreen pixMap. If cTable is nil, then the system uses the default table for the desired depth.
• When aGDevice is not nil and the noNewDevice flag is set, no new offscreen device is created. This is the case when you want to create an offscreen port but do not need the offscreen device. In our example, aGDevice is always nil because we want to keep a separate environment for each document being drawn, which requires a unique color table and inverse table, implying the need for individual devices.

  This is useful when, for example, an application has several offscreen worlds with similar characteristics, such as depth or color table. It is possible to allocate only one GWorld with an offscreen device and to use that offscreen device as a GDevice for all the other GWorlds. Be sure to avoid using one of the screen devices as a GDevice. If the user changes the characteristics of a screen device via the Control Panel, your offscreen world will become invalid.

  Note that aGDevice is used to create the offscreen graphics world only when noNewDevice is set and its pixelDepth is not 0. In any other instance, aGDevice should be set to nil.

  If pixelDepth is 0, boundsRect is used to find the deepest device that intersects the rectangle. Taken in global screen coordinates, the depth, color table, and inverse table of this device are used to set up the offscreen environment.

• The flags parameter gives some control to the application for the creation of the new offscreen graphics environment. Currently the possible values are a combination of pixPurge and noNewDevice.

  If pixPurge is set, the offscreen buffer is created as a purgeable block. The effects of noNewDevice are the same, as discussed earlier.

FUNCTION GetGWorldDevice(offscreenWorld: GWorldPtr):GDHandle;

This call returns the GDevice associated with offscreenWorld, normally the offscreen device created with NewGWorld. If noNewDevice was used, however, the device returned will be the device passed to NewGWorld or UpdateGWorld.

PROCEDURE SetGWorld (port: CGrafPtr; gdh: GDHandle);

This call replaces SetPort and SetGDevice. If port is a GrafPtr or a CGrafPtr, then the current port is set to port and the current device is set to gdh. If port is a GWorldPtr, then the current port is set to port and the current device is set to the device attached to the offscreen graphics world.

As a rule of thumb, when you use the offscreen support provided with 32-Bit QuickDraw, you should use GetGWorld instead of GetPort and GetGDevice, and SetGWorld instead of SetPort and SetGDevice. Both calls are safe to use within the old-style environment and ensure proper behavior in the new.

If pixelDepth is 1,2,4,8,16, or 32 optimize for offscreen data depth boundsRect is a rectangle in local coordinates if cTable is nil NewGWorld uses default color table for given pixelDepth else NewGWorld attaches a copy of your cTable to your new GWorld if NoNewDevice flag is passed (see flags) aGDevice is used to create your new GWorld (aGDevice should not be a screen device) else aGDevice is ignored J.Z.

WHERE IS THE CATCH?

When using the offscreen world environment, you have to make sure that the pixMap is actually available and locked when you draw to or from an offscreen graphics world. This is why you must bracket any drawing action with LockPixels and UnlockPixels.

In our example, to anchor the offscreen pixMap, we need to call LockPixels just before calling EraseRect. When we are done, a call to UnlockPixels releases the buffer. These two calls are the only extra work offscreen support in 32-Bit QuickDraw demands.

FUNCTION LockPixels (pm: PixMapHandle):Boolean; 

Call this function prior to any drawing operation to or from the offscreen environment. A false value returned means the offscreen pixMap has been purged. A LockPixels result of false tells the application to either recreate the offscreen pixMap, using UpdateGWorld in the process, or draw directly to the target window.

PROCEDURE UnlockPixels (pm: PixMapHandle); 

When you finish drawing, you should call UnlockPixels. Just remember that all that is locked should be unlocked. Otherwise, strange things may happen. one more call you'll need

FUNCTION UpdateGWorld (VAR offscreenGWorld: GWorldPtr; pixelDepth:
    INTEGER; boundsRect: Rect; cTable: CTabHandle;
    aGDevice: GDHandle; flags: GWorldFlags): GWorldFlags;

This call reconstructs the offscreen environment according to the new boundsRect, cTable, and pixelDepth. These parameters work in large part the same way they do in NewGWorld.

When pixelDepth is 0, the device list is parsed again to find the deepest device intersecting boundsRect taken in global coordinates. If aGDevice is not nil, then pixelDepth and cTable are ignored and the fields from aGDevice are used offscreen. If the offscreen buffer has been purged, UpdateGWorld allocates a new one.

When necessary, the application can simply call UpdateGWorld to change the offscreen environment without having to recreate the offscreen image from scratch. This is the case, for example, when the user selects a different depth or the color table is modified somehow.

Keeping the offscreen world parallel to the conditions used to display the images to the user guarantees that when CopyBits is called to update a window, the operation will be performed at the highest speed. The controlling parameter flags can take the following values:

• [] I know what I am doing--don't update the pixels for me.
• [clipPix] If boundsRect is smaller than the current boundsRect, the bottom and right edges pixels are clipped out. If boundsRect is larger, the bottom and right edges are filled with the background color.
• [stretchPix] If boundsRect is smaller, the image is reduced to the new size. If the rectangle is larger, the offscreen image is enlarged to fit the new area.
• [clipPix, ditherPix] and [stretchPix, ditherPix] These provide error diffusion when necessary in addition to clipping or stretching.

Now if boundsRect is new but the same size, UpdateGWorld realigns the pixMap for best performance. With a new pixelDepth, the pixels are scaled to the new depth. If cTable is new as well, the pixels are mapped to the new colors.

Even for our engineers, some miracles are just too difficult. If the pixMap has been purged, it is reallocated, but the old contents are lost.

When UpdateGWorld returns, check its result, which will be of the GWorldflags variety. If gwFlagErr is set, that means the call was unsuccessful. The offscreen world has not changed, and some correcting action is required. The errors might be cDepthErr (no such depth is possible), paramErr (illegal parameters), and any Memory Manager or QuickDraw errors.

If the call was successful, the rest of the flags can be interpreted as follows:

mapPix	Color mapping was necessary.
newDepth	Depth is new.
alignPix	Pixels were realigned for best results.
newRowBytes	RowBytes changed.
reallocPix	pixMap was reallocated.
clipPix	Clipping was used.
stretchPix	Stretching was used.
ditherPix	Dithering was used.

SOME BONUS CALLS

PROCEDURE DisposeGWorld (offscreenGWorld: GWorldPtr);

Make this call only when you are one hundred percent sure you don't need offscreenGWorld any more, and you want to release the memory it uses.

PROCEDURE AllowPurgePixels (pm: PixMapHandle);

This call makes the given pixMap purgeable.

PROCEDURE NoPurgePixels (pm: PixMapHandle);

This one makes the pixMap nonpurgeable.

FUNCTION GetPixelsState (pm: PixMapHandle): GWorldflags;

Make this call to find out the condition of the flags pixelsPurgeable and pixelsLocked. When you want to make temporary changes, you can use this call in conjunction with SetPixelsState to save and later restore the state of the flags.

PROCEDURE SetPixelsState (pm: PixMapHandle; state: GWorldFlags);

This call sets the state of the pixelsPurgeable and pixelsLocked flags.

FUNCTION GetPixBaseAddr (pm: PixMapHandle): Ptr;

Since the offscreen world is yours, you will probably feel the urge to mess with it directly. GetPixBaseAddr is the call you need. It returns the 32-bit address of the start of the offscreen buffer associated with the given pixMap. The address is valid until any call that moves memory around is made. If you make such a call, you must call GetPixBaseAddr again. If the offscreen pixMap has been purged, the call returns nil.

FUNCTION NewScreenBuffer (globalRect: Rect; purgeable: BOOLEAN;
        VAR gdh: GDHandle; VAR offscreenPixMap: PixMapHandle): QDErr;

This call creates a pixMap using the color table and depth of the deepest device intersected by globalRect. It is useful when the offscreen buffer is used to keep a copy of a portion of a window. Normally, applications don't need to make this call.

If the call is successful, gdh is a handle to the deepest device and offscreen pixMap points to the new pixMap. Note that if the screen device returned in gdh is changed by the user in monitors, the offscreen pixMap becomes invalid.

Errors are noErr (everything is okay), cNoMemErr (couldn't get all the memory needed), paramErr (illegal parameters), and any Memory Manager or QD errors.

PROCEDURE DisposeScreenBuffer (offscreenPixMap: PixMapHandle);

You made it, so call this procedure to dispose of it.

CALLS TO AVOID DISASTER

Even though all the books, Technical Notes, and documents that describe how to program the Macintosh talk about the things you shouldn't do and the data fields you are not supposed to mess with, not everyone can resist temptation. That's why 32-Bit QuickDraw includes a set of calls that allows you to tell the system you have modified some forbidden structure, and it should try to accommodate to your designs. The calls are:

PROCEDURE CTabChanged (ctab: CTabHandle);

This call says "Yes, I know I shouldn't mess with a color table directly, but I did it and I want to come clean." Use SetEntries, or even better let the Palette Manager maintain the color table for you.

PROCEDURE PixPatChanged (ppat: PixPatHandle);

Use this call to say "I admit I modified the fields of a PixPat directly. Please fix the resulting mess for me." When the modifications include changing the contents of the color table pointed to by PixPat.patMap^^.pmTable, you should also call CTabChanged. PenPixPat and BackPixPat are a better way to install new patterns.

PROCEDURE PortChanged (port: GrafPtr);

You should not modify any of the port structures directly. But if you cannot control yourself, use this call to let QuickDraw know what you've done. If you modify either the pixPat or the color table associated with the port, you need to call PixPatChanged and CTabChanged.

PROCEDURE GDeviceChanged (gdh: GDHandle);

The best practice is to stay away from the fields of any GDevice. But if you do change something, make this call so the system can rectify any problems. If you change the data of the color table in the device's pixMap, you must also call CTabChanged.

NEWGWORLD

NewGWorld(offscreenGWorld, pixelDepth, boundsRect, cTable, aGDevice, flags);

On entry offscreenGWorld should point to nothing
On exit offscreenGWorld is your new GWorld	the pointer may not be the same

Flags can be one of ...
	0	pixels not purgeable, create a new device
	pixPurge	pixels are purgeable, check LockPixel's return value
	NoNewDevice	pixelDepth and cTable are from aGDevice
	pixPurge and NoNewDevice
if pixelDepth is 0	optimize for CopyBits Speed
	boundsRect holds a global rectangle	corresponding to a window
	cTable is ignored	uses cTable from boundsRect's deepest screen
	aGDevice is ignored
If pixelDepth is 1,2,4,8,16, or 32	optimize for offscreen data depth

	boundsRect is a rectangle in local coordinates
	if cTable is nil
		NewGWorld uses default color table for given pixelDepth
	else
		NewGWorld attaches a copy of your cTable to your new GWorld
	if NoNewDevice flag is passed (see flags)
		aGDevice is used to create your new GWorld (aGDevice should not be a screen device)
	else
		aGDevice is ignored

UPDATEGWORLD

UpdateGWorld(offscreenGWorld, pixelDepth, boundsRect,cTable, aGDevice, flags);

On entry offscreenGWorld is your old GWorld
On exit offscreenGWorld is your new GWorld	the pointer may or may not be the same

Flags can be one of ...
	0	pixels not updated
	clipPix	preserves pixels it can, puts background in new areas
	stretchPix	stretches pixels to fit from old to new pixmap
	clipPix and ditherPix	plus the pixels are dithered if necessary
	stretchPix and ditherPix

If aGDevice is not nil then the pixelDepth and cTable you supply are overridden by the pixelDepth and cTable of aGDevice.

If pixelDepth is 0
	boundsRect is a global rectangle
typically corresponds to the associated window
	cTable is ignored
uses cTable from boundsRect's deepest screen device
	aGDevice is nil	watch out for side effects if not nil!

If pixelDepth is 1,2,4,8,16, or 32
	boundsRect is a rectangle in local coordinates	if different from old boundsRect then pixmap, etc are updated appropriately

	if cTable is nil
		uses default color table for given pixelDepth and updates pixmap if different
	else
		new color table used to update your pixmap
	aGDevice is nil or the device to determine your cTable and pixel depth J.Z.

Guillermo Ortiz graduated from college with a BSEE, but this event took place so long ago and so far away that he gave up trying to remember when and where. He is truly the Apple veteran among the bunch of authors in this issue, having successfully emerged as a pretty nice guy from six years at Apple--four as an Apple II Pascal "expert" and two working on Color QuickDraw, the Palette Manager, and the like. He attributes surviving the 32-bit QuickDraw project to being in good shape from running and playing tennis with good friends. His curriculum vitae is entitled, "My Life As An Elvis Impersonator." Although he profusely denies ever having written that line, there's a trail of sequins leading to his office. 'Fess up, Guillermo. *

All Apple developers (Associates and Partners) received FracApp with their monthly mailings. It is also available on develop, the CD, and through APDA on the DTS sample code disks.*