Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 3 - QuickDraw Drawing / QuickDraw Drawing Reference

Routines / Creating and Managing Regions

OpenRgn

To begin defining a region, use the OpenRgn procedure.

PROCEDURE OpenRgn;

DESCRIPTION

The OpenRgn procedure allocates temporary memory to start saving lines and framed shapes for processing as a region definition. Call OpenRgn only after initializing a region with the NewRgn function.

The NewRgn function stores the definition for a region in a Region record.

While a region is open, all calls to Line, LineTo, and the procedures that draw framed shapes (except arcs) affect the outline of the region. Only the line endpoints and shape boundaries affect the region definition--the pattern mode, pattern, and size do not affect it.

When you are finished defining the region, call the CloseRgn procedure.

The OpenRgn procedure calls HidePen, so no drawing occurs on the screen while the region is open (unless you call ShowPen just after OpenRgn, or you called ShowPen previously without balancing it by a call to HidePen). Since the pen hangs below and
to the right of the pen location, drawing lines with even the smallest pen changes pixels that lie outside the region you define.

The outline of a region is mathematically defined and infinitely thin, and it separates the bit or pixel image into two groups of pixels: those within the region and those outside it.

A region should consist of one or more closed loops. Each framed shape itself constitutes a loop. Any lines drawn with the Line or LineTo procedure should connect with each other or with a framed shape. Even if the onscreen presentation of a region is clipped, the definition of a region is not; you can define a region anywhere on the coordinate plane with complete disregard for the location of various graphics port entities on that plane.

When a region is open, the current graphics port's rgnSave field contains a handle to information related to the region definition. If you want to temporarily disable the collection of lines and shapes, you can save the current value of this field, set the field to NIL, and later restore the saved value to resume the region definition. Also, calling SetPort while a region is being formed discontinues formation of the region until another call to SetPort resets the region's original graphics port.

SPECIAL CONSIDERATIONS

Regions are limited to 32 KB in size in basic QuickDraw and 64 KB in Color QuickDraw. You can determine the current size of an existing region by calling the Memory Manager function GetHandleSize (described in Inside Macintosh: Memory). When you record drawing operations in an open region, the resulting region description may overflow the 32 KB or 64 KB limit. Should this happen in Color QuickDraw, the QDError function (described in the chapter "Color QuickDraw" in this book) returns the result code regionTooBigError.

Do not call OpenRgn while another region or a polygon is already open. When you are finished constructing the region, use the CloseRgn procedure, which is described next.

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

SEE ALSO

Listing 3-8 on page 3-24 illustrates how to use this procedure. The Region record is described in the chapter "Basic QuickDraw."