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

SetPixelsState

To restore an offscreen pixel image to the state that you saved with the GetPixelsState function (explained in the preceding section), you can use the SetPixelsState procedure.

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

pm

A handle to an offscreen pixel map.

state

Flags, which you usually save with the GetPixelsState function, defined by the GWorldFlags data type:

           TYPE GWorldFlags = 
           SET OF ( {flags for SetPixelsState are listed here}
             pixelsPurgeable,  {make the base address for an }
                               { offscreen pixel image purgeable}
             pixelsLocked      {prevent the base address for an }
                               { offscreen pixel image from }
                               { being moved}
           );

DESCRIPTION

The SetPixelsState procedure changes the state of the memory allocated for an offscreen pixel image to the state indicated by the flags specified in the state parameter, which you typically save using the GetPixelsState function.

Because only an unlocked memory block can be purged, SetPixelsState calls the UnlockPixels and AllowPurgePixels procedures (described on page 6-33 and page 6-34, respectively) if the state parameter specifies the pixelsPurgeable flag. If the state parameter does not specify the pixelsPurgeable flag, SetPixelsState makes the base address for the offscreen pixel image unpurgeable.

If the state parameter does not specify the pixelsLocked flag, SetPixelsState allows the base address for the offscreen pixel image to be moved.

SPECIAL CONSIDERATIONS

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

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the SetPixelsState procedure are

Trap macro	Selector
_QDExtensions	$0008000E

SEE ALSO

After using GetPixelsState and before using SetPixelsState, your application can temporarily alter the offscreen graphics world by using the AllowPurgePixels procedure (described on page 6-34) to temporarily mark the memory block for its offscreen pixel map as 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 unlock it.