Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

QuickDraw and Picture Utilities Routines / Collecting Picture Information

GetPictInfo

Use the GetPictInfo function to gather information about a single picture.

FUNCTION GetPictInfo (thePictHandle: PicHandle; 
                      VAR thePictInfo: PictInfo; verb: Integer; 
                      colorsRequested: Integer; 
                      colorPickMethod: Integer; 
                      version: Integer): OSErr;

thePictHandle

A handle to a picture.

thePictInfo

A pointer to a PictInfo record, which will hold information about the picture. The PictInfo record is described on page 7-31.

verb

A value indicating what type of information you want GetPictInfo to return in the PictInfo record. 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}
            recordComments    = 4;  {return comment information}
            recordFontInfo    = 8;  {return font information}
            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 suppressBlackAndWhite constant 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. If you are not requesting colors (that is, if you pass the recordComments or recordFontInfo constant in the verb parameter), this function does not return colors, in which case you may instead pass 0 here.

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

In the PictInfo record to which the parameter thePictInfo points, the GetPictInfo function returns information about the picture you specify in the thePictHandle parameter. 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 GetPictInfo function.

Use the verb parameter to specify whether you want color information (in a ColorTable record, a Palette record, or both), whether you want picture comment information, and whether you want font information. If you want color information, be sure to 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. Each has advantages in different situations. For example, suppose the picture of a forest image contains 400 colors, of which 300 are greens, 80 are browns, and the rest are a scattering of golden sunlight effects. If you ask for the 250 most used colors, you will probably receive all greens. If you ask for a range of 250 colors, you will receive an assortment stretching from the greens and golds to the browns, including colors in between that might not actually appear in the image. 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.

If your application uses more than one color-picking method, it should present the user with a choice of which method to use.

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, CommentSpec, and FontSpec records. Dispose of the Palette record by using the DisposePalette procedure. Dispose of the ColorTable record by using the DisposeCTable procedure.

SPECIAL CONSIDERATIONS

When you ask for color information, GetPictInfo takes into account only the version 2 and extended version 2 picture opcodes RGBFgCol, RGBBkCol, BkPixPat, PnPixPat, FillPixPat, and HiliteColor (as well as pixel map or bitmap data). Each occurrence of these opcodes is treated as 1 pixel, regardless of the number and sizes of the objects drawn with that color. If you need an accurate set of colors from a complex picture, create an image of the picture in an offscreen pixel map, and then call the GetPixMapInfo function (described on page 7-49) to obtain color information about that pixel map.

The GetPictInfo function returns a bit depth of 1 on QuickTime-compressed 'PICT' files. However, when QuickTime is installed, QuickTime decompresses and displays the image correctly.

The GetPictInfo function may move or purge memory.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the GetPictInfo function are

Trap macro	Selector
_Pack15	$0800

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
pictureDataErr	-11005	Invalid picture data

SEE ALSO

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

The DisposePalette procedure is described in the chapter "Palette Manager" 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.

Listing 7-12 on page 7-24 illustrates the use of the GetPictInfo function.