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

UnlockPixels

When you are finished drawing into and copying from an offscreen graphics world, use the UnlockPixels procedure.

PROCEDURE UnlockPixels (pm: PixMapHandle);

pm

A handle to an offscreen pixel map. Pass the same handle that you passed previously to the LockPixels function.

DESCRIPTION

The UnlockPixels procedure allows the Memory Manager to move the base address for the offscreen pixel map that you specify in the pm parameter. To ensure the integrity of the data in a pixel image, call LockPixels (explained in the preceding section) before drawing into or copying from a pixel map; then, to prevent heap fragmentation, call UnlockPixels as soon as your application finishes drawing to and copying from the offscreen pixel map.

The baseAddr field of the PixMap record for an offscreen graphics world contains a handle instead of a pointer (which is what the baseAddr field for an onscreen pixel map contains). The LockPixels function dereferences the PixMap handle into a pointer. When you use the UnlockPixels procedure, the handle is recovered.

You don't need to call UnlockPixels if LockPixels returns FALSE, because LockPixels doesn't lock the memory for a pixel image if that memory has been purged. However, calling UnlockPixels on purged memory does no harm.

SPECIAL CONSIDERATIONS

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

Trap macro	Selector
_QDExtensions	$00040002