Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

Application-Defined Routines

As described in "Collecting Picture Information" beginning on page 7-45, your application can use the GetPictInfo, GetPixMapInfo, and NewPictInfo functions to gather information about pictures, pixel maps, and bitmaps. Each of these functions can gather up to 256 colors in ColorTable and Palette records. In the colorPickMethod parameter to these functions, you specify how they should select which colors to gather. These Picture Utilities functions provide two color-picking methods: the first selects the most frequently used colors, and the second selects a weighted distribution of the existing colors.

You can also create your own color-picking method. You must compile it as a resource of type 'cpmt' and write its entry point in assembly language. To use this color-picking method ('cpmt') resource, pass its resource ID (which must be greater than 127) in the colorPickMethod parameter to these Picture Utilities functions. These functions call your color-picking method's entry point and pass one of four possible selectors in register D0. These functions pass their parameters on the stack. As shown in Table 7-1, each selector requires your color-picking method to call a different routine, which should return its results in register D0.

Table 7-1: Routine selectors for an application-defined color-picking method

D0 value	Routine to call
0	MyInitPickMethod
1	MyRecordColors
2	MyCalcColorTable
3	MyDisposeColorPickMethod

Your color-picking method ('cpmt') resource should include a routine that specifies its color bank (that is, the structure into which all the colors of a picture, pixel map, or bitmap are gathered) and allocates whatever data your color-picking method needs. This routine is explained next as a Pascal function declared as MyInitPickMethod.

Your MyInitPickMethod function can let the Picture Utilities generate a color bank consisting of a histogram (that is, frequency counts of each color) to a resolution of 5 bits per color. Or, your MyInitPickMethod function can specify that your application has its own custom color bank--for example, a histogram to a resolution of 8 bits per color.

If you create your own custom color bank, your 'cpmt' resource should include a routine that gathers and stores colors; this routine is described on page 7-63 as a Pascal function declared as MyRecordColors.

For the number of colors your application requests using the Picture Utilities, your 'cpmt' resource should include a routine that determines which colors to select from the color bank and then fills an array of ColorSpec records with those colors; this routine is described on page 7-64 as a Pascal function declared as MyCalcColorTable. The Picture Utilities function that your application initially called then returns these colors in a Palette record or ColorTable record, as specified by your application when it first called the Picture Utilities function.

Your 'cpmt' resource should include a routine that releases the memory allocated by your MyInitPickMethod routine. The routine that releases memory is described on page 7-66 as a Pascal function declared as MyDisposeColorPickMethod.

If your routines return an error, that error is passed back to the GetPictInfo, GetPixMapInfo, or NewPictInfo function, which in turn passes the error to your application as a function result.