Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 4 - Color QuickDraw / Color QuickDraw Reference

Data Structures /

PixPat

Your application typically does not create PixPat records. Although you can create such records in your program code, it is usually easier to create pixel patterns using the pixel pattern resource, which is described on page 4-94.

A PixPat record is defined as follows:

TYPE PixPatHandle = ^PixPatPtr;
PixPatPtr         = ^PixPat;
PixPat            = 
RECORD
   patType:    Integer;       {pattern type}
   patMap:     PixMapHandle;  {pattern characteristics}
   patData:    Handle;        {pixel image defining pattern}
   patXData:   Handle;        {expanded pixel image}
   patXValid:  Integer;       {flags for expanded pattern data}
   patXMap:    Handle;        {handle to expanded pattern data}
   pat1Data:   Pattern;       {a bit pattern for a GrafPort }
                              { record}
END;

Field Description

patType

The pattern's type. The value 0 specifies a basic QuickDraw bit pattern, the value 1 specifies a full-color pixel pattern, and the value 2 specifies an RGB pattern. These pattern types are described in greater detail in the rest of this section.

patMap

A handle to a PixMap record (described on page 4-37) that describes the pattern's pixel image. The PixMap record can contain indexed or direct pixels.

patData

A handle to the pattern's pixel image.

patXData

A handle to an expanded pixel image used internally by Color QuickDraw.

patXValid

A flag that, when set to -1, invalidates the expanded data.

patXMap

Reserved for use by Color QuickDraw.

pat1Data

A bit pattern (described in the chapter "QuickDraw Drawing") to be used when this pattern is drawn into a GrafPort record (described in the chapter "Basic QuickDraw"). The NewPixPat function (described on page 4-79) sets this field to 50 percent gray.

When used for a color graphics port, the basic QuickDraw procedures PenPat and BackPat (described in the chapter "Basic QuickDraw") store pixel patterns in, respectively, the pnPixPat and bkPixPat fields of the CGrafPort record and set the patType field of the PixPat field to 0 to indicate that the PixPat record contains a bit pattern. Such patterns are limited to 8-by-8 pixel dimensions and, instead of being drawn in black and white, are always drawn using the colors specified in the CGrafPort record's rgbFgColor and rgbBkColor fields, respectively.

In a full-color pixel pattern, the patType field contains the value 1, and the pattern's dimensions, depth, resolution, set of colors, and other characteristics are defined by a PixMap record, referenced by the handle in the patMap field of the PixPat record. Full-color pixel patterns contain color tables that describe the colors they use. Generally such a color table contains one entry for each color used in the pattern. For instance, if your pattern has five colors, you would probably create a 4 bits per pixel pattern that uses pixel values 0-4, and a color table with five entries, numbered 0-4, that contain the RGB specifications for those pixel values.

However, if you don't specify a color table for a pixel value, Color QuickDraw assigns a color to that pixel value. The largest unassigned pixel value becomes the foreground color; the smallest unassigned pixel value is assigned the background color. Remaining unassigned pixel values are given colors that are evenly distributed between the foreground and background.

For instance, in the color table mentioned above, pixel values 5-15 are unused. Assume that the foreground color is black and the background color is white. Pixel value 15 is assigned the foreground color, black; pixel value 5 is assigned the background color, white; the nine pixel values between them are assigned evenly distributed shades of gray. If the PixMap record's color table is set to NIL, all pixel values are determined by blending the foreground and background colors.

Full-color pixel patterns are not limited to a fixed size: their height and width can be any power of 2, as specified by the height and width of the boundary rectangle for the PixMap record specified in the patMap field. A pattern 8 bits wide, which is the size of a bit pattern, has a row width of just 1 byte, contrary to the usual rule that the rowBytes field must be even. Read this pattern type into memory using the GetPixPat function (described on page 4-79), and set it using the PenPixPat or BackPixPat
procedure (described on page 4-58 and page 4-60, respectively).

The pixel map specified in the patMap field of the PixPat record defines the pattern's characteristics. The baseAddr field of the PixMap record for that pixel map is ignored. For a full-color pixel pattern, the actual pixel image defining the pattern is stored in the handle in the patData field of the PixPat record. The pattern's pixel depth need not match that of the pixel map into which it's transferred; the depth is adjusted automatically when the pattern is drawn. Color QuickDraw maintains a private copy of the pattern's pixel image, expanded to the current screen depth and aligned to the current graphics port, in the patXData field of the PixPat record.

In an RGB pixel pattern, the patType field contains the value 2. Using the MakeRGBPat procedure (described on page 4-81), your application can specify the exact color it wants to use. Color QuickDraw selects a pattern to approximate that color. In this way, your application can effectively increase the color resolution of the screen. RGB pixel patterns are particularly useful for dithering: mixing existing colors together to create the illusion of a third color that's unavailable on an indexed device. The MakeRGBPat procedure aids in this process by constructing a dithered pattern to approximate a given absolute color. An RGB pixel pattern can display 125 different patterns on a 4-bit screen, or 2197 different patterns on an 8-bit screen.

An RGB pixel pattern has an 8-by-8 pixel pattern that is 2 bits deep. For an RGB pixel pattern, the RGBColor record that you specify to the MakeRGBPat procedure defines the image; there is no image data.

Your application should never need to directly change the fields of a PixPat record. If you find it absolutely necessary for your application to so, immediately use the PixPatChanged procedure to notify Color QuickDraw that your application has changed the PixPat record. The PixPatChanged procedure is described on page 4-89.