Carbon


PixPat

Header: Quickdraw.h

struct PixPat {
    SInt16 patType; 
    PixMapHandle patMap; 
    Handle patData; 
    Handle patXData; 
    SInt16 patXValid; 
    Handle patXMap; 
    Pattern pat1Data;
};
typedef PixPat PixPatPtr;

Field descriptions

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.

patMap

A handle to a PixMap structure that describes the pattern’s pixel image. The PixMap structure 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 QuickDraw.

patXValid

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

patXMap

Reserved for use by QuickDraw.

pat1Data

A bit pattern to be used when this pattern is drawn into a GrafPort structure. The NewPixPat function sets this field to 50 percent gray.

Your application typically does not create PixPat structures. Although you can create such structures in your program code, it is usually easier to create pixel patterns using the pixel pattern resource, 'ppat'.

When used for a color graphics port, the basic QuickDraw functions PenPat and BackPat store pixel patterns in, respectively, the pnPixPat and bkPixPat fields of the CGrafPort structure and set the patType field of the PixPat field to 0 to indicate that the PixPat structure 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 structure’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 structure, referenced by the handle in the patMap field of the PixPat structure. 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, 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 structure’s color table is set to NULL, 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 structure 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, and set it using the PenPixPat or BackPixPat functions.

The pixel map specified in the patMap field of the PixPat structure defines the pattern’s characteristics. The baseAddr field of the PixMap structure 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 structure. 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. 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 structure.

In an RGB pixel pattern, the patType field contains the value 2. Using the MakeRGBPat function, your application can specify the exact color it wants to use. 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 function 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 structure that you specify to the MakeRGBPat function defines the image; there is no image data.

Your application should never need to directly change the fields of a PixPat structure. If you find it absolutely necessary for your application to so, immediately use the PixPatChanged function to notify QuickDraw that your application has changed the PixPat structure.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)