Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

QuickDraw and Picture Utilities Routines / Collecting Picture Information

GetPixMapInfo

Use the GetPixMapInfo function to gather color information about a single pixel map or bitmap.

FUNCTION GetPixMapInfo (thePixMapHandle: PixMapHandle; 
                        VAR thePictInfo: PictInfo; verb: Integer; 
                        colorsRequested: Integer; 
                        colorPickMethod: Integer; 
                        version: Integer): OSErr;

thePixMapHandle

A handle to a pixel map or bitmap.

thePictInfo

A pointer to a PictInfo record, which will hold information about a pixel map or bitmap. The PictInfo record is described on page 7-31.

verb

A value indicating whether you want color information returned in a ColorTable record, a Palette record, or both. You can also request that black and white not be included among the returned colors. You can use any or all of the following constants or the sum of the integers they represent:

            CONST
            returnColorTable  = 1;  {return a ColorTable record}
            returnPalette     = 2;  {return a Palette record}
            suppressBlackAndWhite
                              = 16; {don't include black and }
                                    { white with returned colors}

Because the Palette Manager adds black and white when creating a Palette record, you can specify the number of colors you want minus 2 in the colorsRequested parameter and specify the constant suppressBlackAndWhite in the verb parameter when gathering colors destined for a Palette record or a screen.

colorsRequested

From 1 to 256, the number of colors you want in the ColorTable or Palette record returned via the PictInfo record.

colorPickMethod

The method by which colors are selected for the ColorTable or Palette record returned via the PictInfo record. You can use one of the following constants or the integer it represents:

            CONST
            systemMethod   = 0;  {let Picture Utilities choose }
                                 { the method (currently they } 
                                 { always choose popularMethod)}
            popularMethod  = 1;  {return most frequently used }
                                 { colors}
            medianMethod   = 2;  {return a weighted distribution }
                                 { of colors}

You can also create your own color-picking method in a resource file of type 'cpmt' and pass its resource ID in the colorPickMethod parameter. The resource ID must be greater than 127.

version

Always set this parameter to 0.

DESCRIPTION

For the pixel map (or bitmap) whose handle you pass in the thePixMapHandle parameter, the GetPixMapInfo function returns color information in the PictInfo record that you point to in the parameter thePictInfo. Initially, all of the fields in a new PictInfo record are set to NIL. Relevant fields are set to appropriate values depending on the information you request using the GetPixMapInfo function.

Use the verb parameter to specify whether you want color information returned in a ColorTable record, a Palette record, or both, and use the colorPickMethod parameter to specify the method by which to select colors.

The Picture Utilities provide two color-picking methods: one (specified by the popularMethod constant) that gives you the most frequently used colors and one (specified by the medianMethod constant) that gives you the widest range of colors. If you specify the systemMethod constant, the Picture Utilities choose the method; currently they always choose popularMethod. You can also supply a color-picking method of your own.

When you are finished with the information in the PictInfo record, be sure to dispose of it. Use the Memory Manager procedure DisposeHandle to dispose of the PictInfo record. Dispose of the Palette record by using the DisposePalette procedure. Dispose of the ColorTable record by using the DisposeCTable procedure.

SPECIAL CONSIDERATIONS

The GetPixMapInfo function may move or purge memory.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the GetPixMapInfo function are

Trap macro	Selector
_Pack15	$0801

RESULT CODES

pictInfoVersionErr	-11000	Version number not 0
pictInfoVerbErr	-11002	Invalid verb combination specified
cantLoadPickMethodErr	-11003	Custom pick method not in resource chain
colorsRequestedErr	-11004	Number out of range or greater than that passed to NewPictInfo

SEE ALSO

See "Application-Defined Routines" beginning on page 7-60 for more information about creating your own color-picking method for the colorPickMethod parameter. The PictInfo record is described on page 7-31; the PixMapHandle data type and the ColorTable record are described in the chapter "Color QuickDraw" in this book; the Palette record is described in Advanced Color Imaging on the Mac OS.

The DisposePalette procedure is described in Advanced Color Imaging on the Mac OS. The DisposeCTable procedure is described in the chapter "Color QuickDraw" in this book. The DisposeHandle procedure is described in the chapter "Memory Manager" in Inside Macintosh: Memory.