Legacy Document

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

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

PictInfo
When you use the GetPictInfo function (described on page 7-46) to collect information about a picture, or when you use the GetPixMapInfo function (described on page 7-49) to collect color information about a pixel map or bitmap, the function returns the information in a PictInfo record. When you gather this information for multiple pictures, pixel maps, or bitmaps, the RetrievePictInfo function (described on page 7-57) also returns a PictInfo record containing this information.
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 Picture Utilities functions as described in this chapter.
The PictInfo record is defined as follows:
TYPE PictInfo = 
RECORD
   version:          Integer;          {Picture Utilities version number}
   uniqueColors:     LongInt;          {total colors in survey}
   thePalette:       PaletteHandle;    {handle to a Palette record--NIL for }
                                       { a bitmap in a basic graphics port}
   theColorTable:    CTabHandle;       {handle to a ColorTable record--NIL }
                                       { for a bitmap in a basic graphics }
                                       { port}
   hRes:             Fixed;            {best horizontal resolution (dpi)}
   vRes:             Fixed;            {best vertical resolution (dpi)}
   depth:            Integer;          {greatest pixel depth}
   sourceRect:       Rect;             {optimal bounding rectangle for }
                                       { picture for display at resolution }
                                       { specified in hRes and vRes fields}
   textCount:        LongInt;          {number of text strings in picture(s)}
   lineCount:        LongInt;          {number of lines in picture(s)}
   rectCount:        LongInt;          {number of rectangles in picture(s)}
   rRectCount:       LongInt;          {number of rounded rectangles in }
                                       { picture(s)}
   ovalCount:        LongInt;          {number of ovals in picture(s)}
   arcCount:         LongInt;          {number of arcs and wedges in }
                                       { picture(s)}
   polyCount:        LongInt;          {number of polygons in picture(s)}
   regionCount:      LongInt;          {number of regions in picture(s)}
   bitMapCount:      LongInt;          {number of bitmaps}
   pixMapCount:      LongInt;          {number of pixel maps}
   commentCount:     LongInt;          {number of comments in picture(s)}
   uniqueComments:   LongInt;          {number of different comments }
                                       { (by ID) in picture(s)}
   commentHandle:    CommentSpecHandle;{handle to an array of CommentSpec }
                                       { records for picture(s)}
   uniqueFonts:      LongInt;          {number of fonts in picture(s)}
   fontHandle:       FontSpecHandle;   {handle to an array of FontSpec }
                                       { records for picture(s)}
   fontNamesHandle:  Handle;           {handle to list of font names for }
                                       { picture(s)}
   reserved1:        LongInt;
   reserved2:        LongInt;
END; 
Field Description

version
The version number of the Picture Utilities, currently set to 0.
uniqueColors
The number of colors in the picture specified to the GetPictInfo function, or the number of colors in the pixel map or bitmap specified to the GetPixMapInfo function, or the total number of colors for all the pictures, pixel maps, and bitmaps returned by the RetrievePictInfo function. The number of colors returned in this field is limited by the accuracy of the Picture Utilities' color bank for color storage. See "Application-Defined Routines" beginning on page 7-60 for information about the Picture Utility's color bank and about how you can create your own for selecting colors.
thePalette
A handle to the resulting Palette record if you specified to the GetPictInfo, GetPixMapInfo, or NewPictInfo function that colors be returned in a Palette record. That Palette record contains either the number of colors you specified to the function or--if there aren't that many colors in the pictures, pixel maps, or bitmaps--the number of colors found. Depending on the constant you pass in the verb parameter to the function, the Palette record contains either the most used or the widest range of colors in the pictures, pixel maps, and bitmaps. On Macintosh computers running basic QuickDraw only, this field is always returned as NIL. See the chapter "Palette Manager" in Advanced Color Imaging on the Mac OS for more information about Palette records.
theColorTable
A handle to the resulting ColorTable record if you specified to the GetPictInfo, GetPixMapInfo, or NewPictInfo function that colors be returned in a ColorTable record. If the pictures, pixel maps, or bitmaps contain fewer colors found than you specified to the function, the unused entries in the ColorTable record are filled with black. Depending on the constant you pass in the verb parameter to the function, the ColorTable record contains either the most used or the widest range of colors in the pictures, pixel maps, and bitmaps. The chapter "Color QuickDraw" in this book describes ColorTable records. On Macintosh computers running basic QuickDraw only, this field is always returned as NIL.

If a picture has more than 256 colors or has pixel depths of 32 bits, then Color QuickDraw translates the colors in the ColorTable record to 16-bit depths. In such a case, the returned colors might have a slight loss of resolution, and the uniqueColors field reflects the number of colors distinguishable at that pixel depth.
hRes
The horizontal resolution of the current picture, pixel map, or bitmap retrieved by the GetPictInfo or GetPixMapInfo function; the greatest horizontal resolution from all pictures, pixel maps, and bitmaps retrieved by the RetrievePictInfo function.
vRes
The vertical resolution of the current picture, pixel map, or bitmap retrieved by the GetPictInfo or GetPixMapInfo function; the greatest vertical resolution of all pictures, pixel maps, and bitmaps retrieved by the RetrievePictInfo function. Note that although the values of the hRes and vRes fields are usually the same, they don't have to be.
depth
The pixel depth of the picture specified to the GetPictInfo function or the pixel map specified to the GetPixMapInfo function. When you use the RetrievePictInfo function, this field contains the deepest pixel depth of all pictures or pixel maps retrieved by the function.
sourceRect
The optimal bounding rectangle for displaying the picture at the resolution indicated by the hRes and vRes fields. The upper-left corner of the rectangle is always (0,0). Pictures created with the OpenCPicture function have the hRes, vRes, and sourceRect fields built into their Picture records. For pictures created by OpenPicture, the hRes and vRes fields are set to 72 dpi, and the source rectangle is calculated using the picFrame field of the Picture record for the picture.
textCount
The number of text strings in the picture specified to the GetPictInfo function, or the total number of text objects in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps specified to GetPixMapInfo or RetrievePictInfo, this field is set to 0.
lineCount
The number of lines in the picture specified to the GetPictInfo function, or the total number of lines in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps, this field is set to 0.
rectCount
The number of rectangles in the picture specified to the GetPictInfo function, or the total number of rectangles in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps, this field is set to 0.
rRectCount
The number of rounded rectangles in the picture specified to the GetPictInfo function, or the total number of rounded rectangles in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps, this field is set to 0.
ovalCount
The number of ovals in the picture specified to the GetPictInfo function, or the total number of ovals in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps, this field is set to 0.
arcCount
The number of arcs and wedges in the picture specified to the GetPictInfo function, or the total number of arcs and wedges in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps, this field is set to 0.
polyCount
The number of polygons in the picture specified to the GetPictInfo function, or the total number of polygons in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps, this field is set to 0.
regionCount
The number of regions in the picture specified to the GetPictInfo function, or the total number of regions in all the pictures retrieved by the RetrievePictInfo function. For pixel maps and bitmaps, this field is set to 0.
bitMapCount
The total number of bitmaps in the survey.
pixMapCount
The total number of pixel maps in the survey.
commentCount
The number of comments in the picture specified to the GetPictInfo function, or the total number of comments in all the pictures retrieved by the RetrievePictInfo function. This field is valid only if you specified to the GetPictInfo or NewPictInfo function that comments be returned in a CommentSpec record, described on page 7-29. For pixel maps and bitmaps, this field is set to 0.
uniqueComments
The number of picture comments that have different IDs in the picture specified to the GetPictInfo function, or the total number of picture comments with different IDs in all the pictures retrieved by the RetrievePictInfo function. (The values for many common IDs are listed in Appendix B, "Using Picture Comments for Printing," in this book.) This field is valid only if you specify that comments be returned in a CommentSpec record. For pixel maps and bitmaps, this field is set to 0.
commentHandle
A handle to an array of CommentSpec records, described on page 7-29. For pixel maps and bitmaps, this field is set to NIL.
uniqueFonts
The number of different fonts in the picture specified to the GetPictInfo function, or the total number of different fonts in all the pictures retrieved by the RetrievePictInfo function. For bitmap fonts, a font is a complete set of glyphs in one size, typeface, and style--for example, 12-point Geneva italic. For outline fonts, a font is a complete set of glyphs in one typeface and style--for example, Geneva italic.

This field is valid only if you specify that fonts be returned in a FontSpec record, which is described on page 7-29. For pixel maps and bitmaps, this field is set to 0.
fontHandle
A handle to a list of FontSpec records, described on page 7-29. For pixel maps and bitmaps, this field is set to NIL.
fontNamesHandle

A handle to the names of the fonts in the picture retrieved by the GetPictInfo function or the pictures retrieved by the RetrievePictInfo function. The offset to a particular name is stored in the nameOffset field of the FontSpec record for that font. A font name is a name, such as Geneva, given to one font family to distinguish it from other font families.
When you are finished with this information, be sure to dispose of it. You can dispose of Palette records by using the DisposePalette procedure (which is described in the chapter "Palette Manager" in Advanced Color Imaging on the Mac OS). You can dispose of ColorTable records by using the DisposeCTable procedure (described in the chapter "Color QuickDraw" in this book). You can dispose of other allocations with the DisposeHandle procedure (described in Inside Macintosh: Memory).