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                                             J.Z.

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.*