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

LockPixels

To prevent the base address for an offscreen pixel image from being moved while you draw into or copy from its pixel map, use the LockPixels function.

FUNCTION LockPixels (pm: PixMapHandle): Boolean;

pm

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

DESCRIPTION

The LockPixels function prevents the base address for an offscreen pixel image from being moved. You must call LockPixels before drawing to or copying from an offscreen graphics world.

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, which is described next, the handle is recovered.

If the base address for an offscreen pixel image hasn't been purged by the Memory Manager or is not purgeable, LockPixels returns TRUE as its function result, and your application can draw into or copy from the offscreen pixel map. However, if the base address for an offscreen pixel image has been purged, LockPixels returns FALSE to indicate that you can perform no drawing to or copying from the pixel map. At that point, your application should either call the UpdateGWorld function (described on page 6-23) to reallocate the offscreen pixel image and then reconstruct it, or draw directly in a window instead of preparing the image in an offscreen graphics world.

As soon as you are finished drawing into and copying from the offscreen pixel image, you should call the UnlockPixels procedure.

SPECIAL CONSIDERATIONS

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

Trap macro	Selector
_QDExtensions	$00040001

SEE ALSO

Listing 6-1 on page 6-5 and Listing 6-2 on page 6-10 illustrate the use of this function. See Inside Macintosh: Memory for more information about memory management.