Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 6 - Offscreen Graphics Worlds / Offscreen Graphics Worlds Reference

Routines / Managing an Offscreen Graphics World's Pixel Image

GetPixelsState

To save the current information about the memory allocated for an offscreen pixel image, you can use the GetPixelsState function.

FUNCTION GetPixelsState (pm: PixMapHandle): GWorldFlags;

pm

A handle to an offscreen pixel map.

DESCRIPTION

The GetPixelsState function returns information about the memory allocated for the base address for an offscreen pixel image. This information can be either of the following flags defined by the GWorldFlags data type:

TYPE GWorldFlags = 
SET OF (       {flags for GetPixelsState only are listed here}
   pixelsPurgeable,  {the base address for an offscreen pixel }
                     { image is purgeable}
   pixelsLocked,     {the offscreen pixel image is locked and }
                     { not purgeable}
);

If the pixelsPurgeable flag is not returned, then the base address for the offscreen pixel image is unpurgeable. If the pixelsLocked flag is not returned, then the base address for the offscreen pixel image is unlocked.

After using GetPixelsState to save this state information, your application can later use the SetPixelsState procedure, described next, to restore this state to the offscreen graphics world.

Specify a handle to a pixel map in the pm parameter. To get a handle to an offscreen pixel map, use the GetGWorldPixMap function, described on page 6-31.

SPECIAL CONSIDERATIONS

The GetPixelsState 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 GetPixelsState function are

Trap macro	Selector
_QDExtensions	$0004000D

SEE ALSO

After using GetPixelsState and before using SetPixelsState, your application can temporarily use the AllowPurgePixels procedure (described on page 6-34) to make the base address for an offscreen pixel image purgeable, the NoPurgePixels procedure (described on page 6-35) to make it unpurgeable, the LockPixels function (described on page 6-32) to prevent it from being moved, and the UnlockPixels procedure (described on page 6-33) to allow it to be moved.