Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Imaging With QuickDraw /
Chapter 7 - Pictures / Pictures Reference
QuickDraw and Picture Utilities Routines / Collecting Picture Information


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;
A handle to a picture.
A pointer to a PictInfo record, which will hold information about the picture. The PictInfo record is described on page 7-31.
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:
            returnColorTable  = 1;  {return a ColorTable record}
            returnPalette     = 2;  {return a Palette record}
            recordComments    = 4;  {return comment information}
            recordFontInfo    = 8;  {return font information}
                              = 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.
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.
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:
            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.
Always set this parameter to 0.
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.

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.

The trap macro and routine selector for the GetPictInfo function are
Trap macroSelector

pictInfoVersionErr-11000Version number not 0
pictInfoVerbErr-11002Invalid verb combination specified
cantLoadPickMethodErr-11003Custom pick method not in resource chain
colorsRequestedErr-11004Number out of range or greater than that passed to NewPictInfo
pictureDataErr-11005Invalid picture data
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.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996