Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

Application-Defined Routines /

MyInitPickMethod

Your color-picking method ('cpmt') resource should include a routine that specifies its color bank and allocates whatever data your color-picking method needs. Here is how you would declare this routine if it were a Pascal function named MyInitPickMethod:

FUNCTION MyInitPickMethod (colorsRequested: Integer; 
                           VAR dataRef: LongInt; 
                           VAR colorBankType: Integer): OSErr;

colorsRequested

The number of colors requested by your application to be gathered for examination in a ColorTable or Palette record.

dataRef

A handle to any data needed by your color-picking method; that is, if your application allocates and uses additional data, it should return a handle to it in this parameter.

colorBankType

The type of color bank your color-picking method uses. Your MyInitPickMethod routine should return one of three valid color bank types, which it can represent with one of these constants:

            CONST
            colorBankIsCustom       = -1; {gathers colors into a }
                                          { custom color bank}
            colorBankIsExactAnd555  = 0;  {gathers exact colors }
                                          { if there are less }
                                          { than 256 unique }
                                          { colors in picture; }
                                          { otherwise gathers }
                                          { colors for picture }
                                          { in a 5-5-5 histogram}
            colorBankIs555          = 1;  {gathers colors into a }
                                          { 5-5-5 histogram}

Return the colorBankIs555 constant in this parameter if you want to let the Picture Utilities gather the colors for a picture or a pixel map into a 5-5-5 histogram. When you return the colorBankIs555 constant, the Picture Utilities call your MyCalcColorTable routine with a pointer to the color bank (that is, to the 5-5-5 histogram). Your MyCalcColorTable routine (described on page 7-64) selects whatever colors it needs from this color bank. Then the Picture Utilities function called by your application returns these colors in a Palette record, a ColorTable record, or both, as requested by your application.

Return the ColorBankIsExactAnd555 constant in this parameter to make the Picture Utilities return exact colors if there are less than 256 unique colors in the picture; otherwise, the Picture Utilities gather the colors for the picture in a 5-5-5 histogram, just as they do when you return the colorBankIs555 constant. If the picture or pixel map has fewer colors than your application requests when it calls a Picture Utilities function, the Picture Utilities function returns all of the colors contained in the color bank. If the picture or pixel map contains more colors than your application requests, the Picture Utilities call your MyCalcColorTable routine to select which colors to return.

Return the colorBankIsCustom constant in this parameter if you want to implement your own color bank for storing the colors in a picture or a pixel map. For example, because the 5-5-5 histogram that the Picture Utilities provide gathers colors to a resolution of 5 bits per color, your application may want to create a histogram with a resolution of 8 bits per color. When you return the colorBankIsCustom constant, the Picture Utilities call your MyRecordColors routine (explained in the next routine description) to create this color bank. The Picture Utilities also call your MyCalcColorTable routine to select colors from this color bank.

DESCRIPTION

Your MyInitPickMethod routine should allocate whatever data your color-picking method needs and store a handle to your data in the location pointed to by the dataRef parameter. In the colorBankType parameter, your MyInitPickMethod routine must also return the type of color bank your color-picking method uses for color storage. If your MyInitPickMethod routine generates any error, it should return the error as its function result.

The 5-5-5 histogram that the Picture Utilities provide if you return the ColorBankIs555 or ColorBankIsExactAnd555 constant in the colorBankType parameter is like a reversed cSpecArray record, which is an array of ColorSpec records. (The cSpecArray and ColorSpec records are described in the chapter "Color QuickDraw" in this book.) This 5-5-5 histogram is an array of 32,768 integers, where the index into the array is the color: 5 bits of red, followed by 5 bits of green, followed by 5 bits of blue. Each entry in the array is the number of colors in the picture that are approximated by the index color for that entry.

For example, suppose there were three instances of the following color in the pixel map:

Red	=	%1101 1010 1010 1110
Green	=	%0111 1010 1011 0001
Blue	=	%0101 1011 0110 1010

This color would be represented by index % 0 11011-01111-01011 (in hexadecimal, $6DEB), and the value in the histogram at this index would be 3, because there are three instances of this color.