Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 4 - Color QuickDraw / Color QuickDraw Reference

Color QuickDraw Routines / Creating and Disposing of Pixel Patterns

NewPixPat

Although you should generally create a pixel pattern in a 'ppat' resource and retrieve it with the GetPixPat function, you can use the NewPixPat function to create a new pixel pattern.

FUNCTION NewPixPat: PixPatHandle; 

DESCRIPTION

The NewPixPat function creates a new PixPat record (described on page 4-49) and returns a handle to it. This function calls the NewPixMap function to allocate the pattern's PixMap record (described on page 4-37) and initialize it to the same settings as the pixel map of the current GDevice record--that is, as stored in the gdPMap field of the global variable TheGDevice. This function also sets the pat1Data field of the new PixPat record to a 50 percent gray pattern. NewPixPat allocates new handles for the PixPat record's data, expanded data, expanded map, and color table but does not initialize them; instead, your application must initialize them.

Set the rowBytes, bounds, and pixelSize fields of the pattern's PixMap record to the dimensions of the desired pattern. The rowBytes value should be equal to

(width of bounds) pixelSize/8

The rowBytes value need not be even. The width and height of the bounds must be a power of 2. Each scan line of the pattern must be at least 1 byte in length--that is, ([width of bounds] pixelSize) must be at least 8.

Your application can explicitly specify the color corresponding to each pixel value with a color table. The color table for the pattern must be placed in the pmTable field in the pattern's PixMap record.

Including the PixPat record itself, NewPixPat allocates a total of five handles. The sizes of the handles to the PixPat and PixMap records are the sizes of their respective data structures. The other three handles are initially small in size. Once the pattern is drawn, the size of the expanded data is proportional to the size of the pattern data, but adjusted to the depth of the screen. The color table size is the size of the record plus 8 bytes times the number of colors in the table.

When you are finished using the pixel pattern, use the DisposePixPat procedure, which is described on page 4-82, to make the memory used by the pixel pattern available again.

SPECIAL CONSIDERATIONS

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