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

AllowPurgePixels

You can use the AllowPurgePixels procedure to make the base address for an offscreen pixel image purgeable.

PROCEDURE AllowPurgePixels (pm: PixMapHandle);

pm

A handle to an offscreen pixel map.

DESCRIPTION

The AllowPurgePixels procedure marks the base address for an offscreen pixel image as purgeable; this allows the Memory Manager to free the memory it occupies if available memory space becomes low. By default, NewGWorld creates an unpurgeable base address for an offscreen pixel image.

To get a handle to an offscreen pixel map, first use the GetGWorldPixMap function, described on page 6-31. Then supply this handle for the pm parameter of AllowPurgePixels.

Your application should call the LockPixels function (described on page 6-32) before drawing into or copying from an offscreen pixel map. If the Memory Manager has purged the base address for its pixel image, LockPixels returns FALSE. In that case either your application should use the UpdateGWorld function (described on page 6-23) to begin reconstructing the offscreen pixel image, or it should draw directly to an onscreen graphics port.

Only unlocked memory blocks can be made purgeable. If you use LockPixels, you must use the UnlockPixels procedure (explained in the preceding section) before calling AllowPurgePixels.

SPECIAL CONSIDERATIONS

The AllowPurgePixels 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 AllowPurgePixels procedure are

Trap macro	Selector
_QDExtensions	$0004000B

SEE ALSO

See Inside Macintosh: Memory for more information about memory management.