Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 4 - Color QuickDraw / Color QuickDraw Reference

Data Structures /

PixMap

A pixel map, which is defined by a data structure of type PixMap, contains information about the dimensions and contents of a pixel image, as well as information on the image's storage format, depth, resolution, and color usage.

TYPE  PixMap = 
RECORD
   baseAddr:      Ptr;        {pixel image}
   rowBytes:      Integer;    {flags, and row width}
   bounds:        Rect;       {boundary rectangle}
   pmVersion:     Integer;    {PixMap record version number}
   packType:      Integer;    {packing format}
   packSize:      LongInt;    {size of data in packed state}
   hRes:          Fixed;      {horizontal resolution}
   vRes:          Fixed;      {vertical resolution}
   pixelType:     Integer;    {format of pixel image}
   pixelSize:     Integer;    {physical bits per pixel}
   cmpCount:      Integer;    {logical components per pixel}
   cmpSize:       Integer;    {logical bits per component}
   planeBytes:    LongInt;    {offset to next plane}
   pmTable:       CTabHandle; {handle to the ColorTable record }
                              { for this image}
   pmReserved:    LongInt;    {reserved for future expansion}
END; 

Field Description

baseAddr

For an onscreen pixel image, a pointer to the first byte of the image. For optimal performance, this should be a multiple of 4. The pixel image that appears on a screen is normally stored on a graphics card rather than in main memory.

WARNING

The baseAddr field of the PixMap record for an offscreen graphics world contains a handle instead of a pointer. You must use the GetPixBaseAddr function (described in the chapter "Offscreen Graphics Worlds" in this book) to obtain a pointer to the PixMap record for an offscreen graphics world. Your application should never directly access the baseAddr field of the PixMap record for an offscreen graphics world; instead, your application should always use GetPixBaseAddr.

rowBytes

The offset in bytes from one row of the image to the next. The value must be even, less than $4000, and for best performance it should be a multiple of 4. The high 2 bits of rowBytes are used as flags. If bit 15 = 1, the data structure pointed to is a PixMap record; otherwise it is a BitMap record.

bounds

The boundary rectangle, which links the local coordinate system of a graphics port to QuickDraw's global coordinate system and defines the area of the bit image into which QuickDraw can draw. By default, the boundary rectangle is the entire main screen. Do not use the value of this field to determine the size of the screen; instead use the value of the gdRect field of the GDevice record for the screen, as described in the chapter "Graphics Devices" in this book.

pmVersion

The version number of Color QuickDraw that created this PixMap record. The value of pmVersion is normally 0. If pmVersion is 4, Color QuickDraw treats the PixMap record's baseAddr field as 32-bit clean. (All other flags are private.) Most applications never need to set this field.

packType

The packing algorithm used to compress image data. Color QuickDraw currently supports a packType of 0, which means no packing, and values of 1 to 4 for packing direct pixels.

packSize

The size of the packed image in bytes. When the packType field contains the value 0, this field is always set to 0.

hRes

The horizontal resolution of the pixel image in pixels per inch. This value is of type Fixed; by default, the value here is $00480000 (for 72 pixels per inch).

vRes

The vertical resolution of the pixel image in pixels per inch. This value is of type Fixed; by default, the value here is $00480000 (for 72 pixels per inch).

pixelType

The storage format for a pixel image. Indexed pixels are indicated by a value of 0. Direct pixels are specified by a value of RGBDirect, or 16. In the PixMap record of the GDevice record (described in the chapter "Graphics Devices") for a direct device, this field is set to the constant RGBDirect when the screen depth is set.

pixelSize

Pixel depth; that is, the number of bits used to represent a pixel. Indexed pixels can have sizes of 1, 2, 4, and 8 bits; direct pixel sizes are 16 and 32 bits.

cmpCount

The number of components used to represent a color for a pixel. With indexed pixels, each pixel is a single value representing an index in a color table, and therefore this field contains the value 1--the index is the single component. With direct pixels, each pixel contains three components--one integer each for the intensities of red, green, and blue--so this field contains the value 3.

cmpSize

The size in bits of each component for a pixel. Color QuickDraw expects that the sizes of all components are the same, and that the value of the cmpCount field multiplied by the value of the cmpSize field is less than or equal to the value in the pixelSize field.

For an indexed pixel value, which has only one component, the value of the cmpSize field is the same as the value of the pixelSize field--that is, 1, 2, 4, or 8.

For direct pixels there are two additional possibilities:

A 16-bit pixel, which has three components, has a cmpSize value
of 5. This leaves an unused high-order bit, which Color QuickDraw sets to 0.

A 32-bit pixel, which has three components (red, green, and blue), has a cmpSize value of 8. This leaves an unused high-order byte, which Color QuickDraw sets to 0.

If presented with a 32-bit image--for example, in the CopyBits procedure--Color QuickDraw passes whatever bits are there, and it does not set the high byte to 0. Generally, therefore, your application should clear the memory for the image to 0 before creating a 16-bit or 32-bit image. The Memory Manager functions NewHandleClear and NewPtrClear, described in Inside Macintosh: Memory, assist you in allocating prezeroed memory.

planeBytes

The offset in bytes from one drawing plane to the next. This field is set to 0.

pmTable

A handle to a ColorTable record (described on page 4-47) for the colors in this pixel map.

pmReserved

Reserved for future expansion. This field must be set to 0 for future compatibility.

Note that the pixel map for a window's color graphics port always consists of the pixel depth, color table, and boundary rectangle of the main screen, even if the window is created on or moved to an entirely different screen.