Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 6 - Offscreen Graphics Worlds / Offscreen Graphics Worlds Reference

Routines / Creating, Altering, and Disposing of Offscreen Graphics Worlds

UpdateGWorld

To change the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world, use the UpdateGWorld function. You should call UpdateGWorld after every update event and whenever your windows move or change size.

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

offscreenGWorld

On input, a pointer to an existing offscreen graphics world; upon completion, the pointer to the updated offscreen graphics world.

pixelDepth

The pixel depth of the offscreen world; possible depths are 1, 2, 4, 8, 16, and 32 bits per pixel. If you specify 0 in this parameter, UpdateGWorld rescans the device list and uses the depth of the screen with the greatest pixel depth among all screens whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you specify 0 in this parameter, UpdateGWorld also copies the GDevice record from this device to create an offscreen GDevice record. The UpdateGWorld function ignores the value you supply for this parameter if you specify a GDevice record in the aGDevice parameter.

boundsRect

The boundary rectangle and port rectangle for the offscreen pixel map. This also becomes the boundary rectangle for the GDevice record, if NewGWorld creates one. If you specify 0 in the pixelDepth parameter, NewGWorld interprets the boundaries in global coordinates, with which it determines which screens intersect the rectangle. (NewGWorld then uses the pixel depth, color table, and GDevice record from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle.) Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.

cTable

A handle to a ColorTable record. If you pass NIL in this parameter, UpdateGWorld uses the default color table for the pixel depth that you specify in the pixelDepth parameter; if you set the pixelDepth parameter to 0, UpdateGWorld copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. The UpdateGWorld function ignores the value you supply for this parameter if you specify a GDevice record in the aGDevice parameter.

aGDevice

As an option, a handle to a GDevice record whose pixel depth and color table you want to use for the offscreen graphics world. To use the pixel depth and color table that you specify in the pixelDepth and cTable parameters, set this parameter to NIL.

flags

Options available to your application. You can set a combination of the flags keepLocal, clipPix, stretchPix, and ditherPix. If you don't wish to use any of these flags, pass the empty set ([ ]) in this parameter for Pascal code or pass 0 here for C code. However, you should pass either clipPix or stretchPix to ensure that the pixel map is updated to reflect the new color table. The available flags are described here:

           TYPE GWorldFlags = 
           SET OF (       {flags for UpdateGWorld are listed here}
            keepLocal,    {keep data structures in main memory}
            clipPix,      {update and clip pixel image to new }
                          { boundary rectangle}
            stretchPix,   {update and stretch or shrink pixel }
                          { image to the new boundary rectangle}
            ditherPix,    {include with clipPix or stretchPix }
                          { flag to dither the pixel image}
           );

DESCRIPTION

The UpdateGWorld function changes an offscreen graphics world to the specified pixel depth, rectangle, color table, and options that you supply in the pixelDepth, boundsRect, cTable, and flags parameters, respectively. In the offscreenGWorld parameter, pass the pointer returned to your application by the NewGWorld function when you created the offscreen graphics world.

If the LockPixels function (described on page 6-32) reports that the Memory Manager has purged the base address for the offscreen pixel image, you can use UpdateGWorld to reallocate its memory. Your application should then reconstruct the pixel image or draw directly in a window instead of preparing the image in an offscreen graphics world.

In the flags parameter, you can specify the keepLocal flag, which keeps the offscreen pixel image in Macintosh main memory or returns the image to main memory if it had been previously cached. If you use UpdateGWorld without passing it the keepLocal flag, you allow the offscreen pixel image to be cached on a graphics accelerator card if one is present.

As its function result, UpdateGWorld returns the gwFlagErr flag if UpdateGWorld was unsuccessful; in this case, the offscreen graphics world is left unchanged. You can use the QDError function, described in the chapter "Color QuickDraw," to help you determine why UpdateGWorld failed.

If UpdateGWorld is successful, it returns a combination of the following flags, which are defined by the GWorldFlags data type:

Flag	Meaning
mapPix	Color QuickDraw remapped the colors to a new color table.
newDepth	Color QuickDraw translated the pixel values in the offscreen pixel image to those for a different pixel depth.
alignPix	QuickDraw realigned the offscreen image to the window.
newRowBytes	QuickDraw changed the value of the rowBytes field in the PixMap record for the offscreen graphics world.
reallocPix	QuickDraw had to reallocate memory for the offscreen pixel image; your application should then reconstruct the pixel image, or draw directly in a window instead of preparing the image in an offscreen graphics world.
clipPix	QuickDraw clipped the pixel image.
stretchPix	QuickDraw stretched or shrank the offscreen image.
ditherPix	Color QuickDraw dithered the offscreen pixel image.

The UpdateGWorld function uses the following algorithm when updating the offscreen pixel image:

1. If the color table that you specify in the cTable parameter is different from the previous color table, or if the color table associated with the GDevice record that you specify in the aGDevice parameter is different, Color QuickDraw maps the pixel values in the offscreen pixel map to the new color table.
2. If the value you specify in the pixelDepth parameter differs from the previous pixel depth, Color QuickDraw translates the pixel values in the offscreen pixel image to those for the new pixel depth.
3. If the rectangle you specify in the boundsRect parameter differs from, but has the same size as, the previous boundary rectangle, QuickDraw realigns the pixel image to the screen for optimum performance for the CopyBits procedure.
4. If the rectangle you specify in the boundsRect parameter is smaller than the previous boundary rectangle and you specify the clipPix flag, the pixel image is clipped along the bottom and right edges.
5. If the rectangle you specify in the boundsRect parameter is bigger than the previous boundary rectangle and you specify the clipPix flag, the bottom and right edges of the pixel image are undefined.
6. If the rectangle you specify in the boundsRect parameter is smaller than the previous boundary rectangle and you specify the stretchPix flag, the pixel image is reduced to the new size.
7. If the rectangle you specify in the boundsRect parameter is bigger than the previous boundary rectangle and you specify the stretchPix flag, the pixel image is stretched to the new size.
8. If the Memory Manager purged the base address for the offscreen pixel image, UpdateGWorld reallocates the memory, but the pixel image is lost. You must reconstruct it.

SPECIAL CONSIDERATIONS

The UpdateGWorld function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the UpdateGWorld function are

Trap macro	Selector
_QDExtensions	$00160003