Next Page >

Hide TOC

Legacy Document

Important: The Picture Utilities are deprecated as of Mac OS X v10.4. The replacement API for all QuickDraw technologies is Quartz 2D (Core Graphics). See Quartz Programming Guide for QuickDraw Developers for strategies to replace QuickDraw code with Quartz 2D..

Picture Utilities Reference (Not Recommended)

Framework	ApplicationServices/ApplicationServices.h
Declared in	PictUtils.h

Overview

Because Quartz 2D uses an entirely different approach to graphics than used by QuickDraw, there is no one-to-one correlation between QuickDraw and Quartz 2D functions. However, because Quartz offers many new features and improved performance compared to QuickDraw, it is worthwhile making the effort to convert your graphics code to Quartz.

QuickDraw pictures are sequences of saved drawing commands. Pictures provide a common medium for the sharing of image data.

The Picture Utilities allow your application to gather information about a picture, such as color, fonts, picture comments, and resolution. You can also use the Picture Utilities to gather information about the colors in pixel maps.

Functions by Task

Collecting Picture Information

Using Universal Procedure Pointers

Callbacks

CalcColorTableProcPtr

Defines a pointer to a color table calculation callback. Your color calculation callback selects as many colors as are requested by your application from the color bank for a picture or pixel map and then fills these colors into an array of ColorSpec structures.

typedef OSErr (*CalcColorTableProcPtr)
(
   UInt32 dataRef,
   SInt16 colorsRequested,
   void * colorBankPtr,
   CSpecArray resultPtr
);

If you name your function MyCalcColorTableProc, you would declare it like this:

OSErr CalcColorTableProcPtr (
   UInt32 dataRef,
   SInt16 colorsRequested,
   void * colorBankPtr,
   CSpecArray resultPtr
);

Parameters

dataRef

A handle to any data your method needs. Your application initially creates this handle using the InitPickMethodProcPtr function.

colorsRequested

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

colorBankPtr

If your MyInitPickMethodCallback function returned either the colorBankIsExactAnd555 or colorBankIs555 constant, then this parameter contains a pointer to the 5-5-5 histogram that describes all of the colors in the picture, pixel map, or bitmap being examined. (The format of the 5-5-5 histogram is explained in the function description for the InitPickMethodProcPtr function.) Your MyCalcColorTableCallback function should examine these colors and then, using its own criterion for selecting the colors, fill in an array of ColorSpec structures with the number of colors specified in the colorsRequested parameter.

If your MyInitPickMethodCallback function returned the colorBankIsCustom constant, then the value passed in this parameter is invalid. In this case, your MyCalcColorTableCallback function should use the custom color bank that your application created (using the RecordColorsProcPtr function) for filling in an array of ColorSpec structures with the number of colors specified in the colorsRequested parameter.

Your MyCalcColorTableCallback function should return a pointer to this array of ColorSpec structures in the next parameter.

resultPtr

A pointer to the array of ColorSpec structures to be filled with the number of colors specified in the colorsRequested parameter. The Picture Utilities function that your application initially called places these colors in a Palette structure or ColorTable structure, as specified by your application.

Return Value

A result code. See “Picture Utilities Result Codes.” If MyCalcColorTableCallback generates an error, it should return the error as its function result. This error is passed back to the GetPictInfo, GetPixMapInfo, or NewPictInfo function, which in turn passes the error to your application as a function result.

Discussion

Selecting from the color bank created for the picture, bitmap, or pixel map being examined, MyCalcColorTableCallback fills an array of ColorSpec structures with the number of colors requested in the colorsRequested parameter and returns this array in the resultPtr parameter.

If more colors are requested than the picture contains, MyCalcColorTable fills the remaining entries with black (0000 0000 0000).

The colorBankPtr parameter is of type Ptr because the data stored in the color bank is of the type specified by your InitPickMethodProcPtr function. Thus, if you specified colorBankIs555 in the colorBankType parameter, the color bank would be an array of integers. However, if the Picture Utilities support other data types in the future, the colorBankPtr parameter could point to completely different data types.

Always coerce the value passed in the colorBankPtr parameter to a pointer to an integer. In the future you may need to coerce this value to a pointer of the type you specify in your MyInitPickMethodCallback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

DisposeColorPickMethodProcPtr

Defines a pointer to a method disposal callback function. Your method disposal function releases the memory for the 'cpmt' resource allocated by your MyInitPickMethodCallback function.

typedef OSErr (*DisposeColorPickMethodProcPtr)
(
   UInt32 dataRef
);

If you name your function MyDisposeColorPickMethodProc, you would declare it like this:

OSErr DisposeColorPickMethodProcPtr (
   UInt32 dataRef
);

Parameters

dataRef: A handle to any data your method needs. Your application initially creates this handle using the InitPickMethodProcPtr function.

Return Value

A result code. See “Picture Utilities Result Codes.” If your MyDisposeColorPickMethodCallback function generates an error, it should return the error as its function result. This error is passed back to the GetPictInfo, GetPixMapInfo, or NewPictInfo function, which in turn passes the error to your application as a function result.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

InitPickMethodProcPtr

Defines a pointer to a method initialization callback function. Your method initialization function specifies the color back and allocates whatever data your color-picking method needs.

typedef OSErr (*InitPickMethodProcPtr)
(
   SInt16 colorsRequested,
   UInt32 * dataRef,
   SInt16 * colorBankType
);

If you name your function MyInitPickMethodProc, you would declare it like this:

OSErr InitPickMethodProcPtr (
   SInt16 colorsRequested,
   UInt32 * dataRef,
   SInt16 * colorBankType
);

Parameters

colorsRequested

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

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 MyInitPickMethodCallback function should return one of three valid color bank types.

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 MyCalcColorTableCallback function with a pointer to the color bank (that is, to the 5-5-5 histogram). Your MyCalcColorTableCallback function selects whatever colors it needs from this color bank. Then the Picture Utilities function called by your application returns these colors in a Palette structure, a ColorTable structure, 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 MyCalcColorTableCallback function 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 MyRecordColorsCallback function to create this color bank. The Picture Utilities also call your MyCalcColorTableCallback function to select colors from this color bank.

Return Value

A result code. See “Picture Utilities Result Codes.” If MyInitPickMethodCallback generates any error, it should return the error as its function result. This error is passed back to the GetPictInfo, GetPixMapInfo, or NewPictInfo function, which in turn passes the error to your application as a function result.

Discussion

Your color-picking method ( 'cpmt') resource should include a function that specifies its color bank (that is, the structure into which all the colors of a picture, pixel map, or bitmap are gathered) and allocates whatever data your color-picking method needs. Your MyInitPickMethodCallback can let the Picture Utilities generate a color bank consisting of a histogram (that is, frequency counts of each color) to a resolution of 5 bits per color. Or, your MyInitPickMethodCallback function can specify that your application has its own custom color bank—for example, a histogram to a resolution of 8 bits per color.

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 structure, which is an array of ColorSpec structures. 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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

RecordColorsProcPtr

Defines a pointer to a color recording callback function. Your color recording function creates a color bank.

typedef OSErr (*RecordColorsProcPtr)
(
   UInt32 dataRef,
   RGBColor * colorsArray,
   SInt32 colorCount,
   SInt32 * uniqueColors
);

If you name your function MyRecordColorsProc, you would declare it like this:

OSErr RecordColorsProcPtr (
   UInt32 dataRef,
   RGBColor * colorsArray,
   SInt32 colorCount,
   SInt32 * uniqueColors
);

Parameters

dataRef: A handle to any data your function needs. Your application initially creates this handle using the InitPickMethodProcPtr function.
colorsArray: An array of RGBColor structures. Your MyRecordColorsCallback function stores the color information for this array of RGBColor structures in a data structure of type RGBColorArray.
colorCount: The number of colors in the array specified in the colorsArray parameter.
uniqueColors: Upon input, the number of unique colors already added to the array in the colorsArray parameter. (The Picture Utilities functions call your MyRecordColors function once for every color in the picture, pixel map, or bitmap.) Your MyRecordColorsCallback function must calculate the number of unique colors (to the resolution of the color bank) that are added by this call. Your MyRecordColorsCallback function should add this amount to the value passed upon input in this parameter and then return the sum in this parameter.

Return Value

A result code. See “Picture Utilities Result Codes.” If your MyRecordColorsCallback function generates any error, it should return the error as its function result. This error is passed back to the GetPictInfo, GetPixMapInfo, or NewPictInfo function, which in turn passes the error to your application as a function result.

Discussion

MyRecordColorsCallback stores each color encountered in a picture or pixel into its own color bank. The Picture Utilities call MyRecordColorsCallback only if your MyInitPickMethodCallback function returns the constant colorBankIsCustom in the colorBankType parameter. When you return the colorBankIsCustom constant in the colorBankType parameter to your MyInitPickMethodCallback function, your color-picking method ( 'cpmt') resource must include a function that creates this color bank; for example, your application may want to create a histogram with a resolution of 8 bits per color.

The Picture Utilities functions call MyRecordColorsCallback for all the colors in the picture, pixel map, or bitmap.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

Data Types

CalcColorTableUPP

Defines a universal procedure pointer (UPP) to a color table calculation callback.

typedef CalcColorTableProcPtr CalcColorTableUPP;

Discussion

For more information, see the description of the callback function CalcColorTableProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

CommentSpec

Contains information about the comments in a picture.

struct CommentSpec {
   short count;
   short ID;
};
typedef struct CommentSpec CommentSpec;
typedef CommentSpec * CommentSpecPtr;
typedef CommentSpecPtr * CommentSpecHandle;

Fields

count: The number of times this kind of picture comment occurs in the picture specified to the GetPictInfo function or in all the pictures examined with the NewPictInfo function.
ID: The value set in the kind parameter when the picture comment was created using the function PicComment. For a description of this function, see Inside Mac OS X: Quickdraw Reference.

Discussion

If you specify the structureComments constant in the verb parameter to the GetPictInfo function or the NewPictInfo function, you receive a PictInfo structure that includes in its commentHandle field a handle to an array of CommentSpec structures. The uniqueComments field of the PictInfo structure indicates the number of CommentSpec structures in this array.

When you are finished using the information returned in a CommentSpec structure, use the DisposeHandle function to dispose of the memory allocated to it.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

DisposeColorPickMethodUPP

Defines a universal procedure pointer (UPP) to a method disposal callback.

typedef DisposeColorPickMethodProcPtr DisposeColorPickMethodUPP;

Discussion

For more information, see the description of the callback function DisposeColorPickMethodProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

FontSpec

Contains information about the fonts in a picture.

struct FontSpec {
   short pictFontID;
   short sysFontID;
   long size[4];
   short style;
   long nameOffset;
};
typedef struct FontSpec FontSpec;
typedef FontSpec * FontSpecPtr;
typedef FontSpecPtr * FontSpecHandle;

Fields

pictFontID: The ID number of the font as it is stored in the picture.
sysFontID: The number that identifies the resource file (of type 'FOND') that specifies the font family. Every font family, has a unique font family ID, in a range of values that determines the script system to which the font family belongs.
size: The point sizes of the fonts in the picture. The field contains 128 bits, in which a bit is set for each point size encountered, from 1 to 127 points. Bit 0 is set if a size larger than 127 is found.
style: The styles for this font family at any of its sizes. The values in this field can also be represented with the Style data type.
nameOffset: The offset into the list of font names (indicated by the fontNamesHandle field of the PictInfo structure) at which the name for this font family is stored. A font name is given to a font family to distinguish it from other font families.

Discussion

If you specify the recordFontInfo constant in the verb parameter to the GetPictInfo function or the NewPictInfo function, your application receives a PictInfo structure that includes in its fontHandle field a handle to an array of FontSpec structures. The uniqueFonts field of the PictInfo structure indicates the number of FontSpec structures in this array. (For bitmap fonts, a font is a complete set of glyphs in one size, typeface, and style. For outline fonts, a font is a complete set of glyphs in one typeface and style.)

When you are finished using the information returned in a FontSpec structure, you should use the Memory Manager function DisposeHandle to dispose of the memory allocated to it.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

InitPickMethodUPP

Defines a universal procedure pointer (UPP) to a method initialization callback.

typedef InitPickMethodProcPtr InitPickMethodUPP;

Discussion

For more information, see the description of the callback function InitPickMethodProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

PictInfo

Contains information about a picture.

struct PictInfo {
   short version;
   long uniqueColors;
   PaletteHandle thePalette;
   CTabHandle theColorTable;
   Fixed hRes;
   Fixed vRes;
   short depth;
   Rect sourceRect;
   long textCount;
   long lineCount;
   long rectCount;
   long rRectCount;
   long ovalCount;
   long arcCount;
   long polyCount;
   long regionCount;
   long bitMapCount;
   long pixMapCount;
   long commentCount;
   long uniqueComments;
   CommentSpecHandle commentHandle;
   long uniqueFonts;
   FontSpecHandle fontHandle;
   Handle fontNamesHandle;
   long reserved1;
   long reserved2;
};
typedef struct PictInfo PictInfo;
typedef PictInfo * PictInfoPtr;

Fields

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 InitPickMethodProcPtr, RecordColorsProcPtr, CalcColorTableProcPtr, and DisposeColorPickMethodProcPtr 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 structure if you specified to the GetPictInfo, GetPixMapInfo, or NewPictInfo function that colors be returned in a Palette structure. That Palette structure contains either the number of colors you specified to the function or—if there are not 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 structure 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 NULL.

theColorTable

A handle to the resulting ColorTable structure if you specified to the GetPictInfo, GetPixMapInfo, or NewPictInfo function that colors be returned in a ColorTable structure. If the pictures, pixel maps, or bitmaps contain fewer colors found than you specified to the function, the unused entries in the ColorTable structure are filled with black. Depending on the constant you pass in the verb parameter to the function, the ColorTable structure 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 NULL.

If a picture has more than 256 colors or has pixel depths of 32 bits, then Color QuickDraw translates the colors in the ColorTable structure 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 or 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 or the greatest vertical resolution of all pictures, pixel maps, and bitmaps retrieved by the RetrievePictInfo function. Although the values of the hRes and vRes fields are usually the same, they do not 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 structures. 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 structure 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 structure. 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. This field is valid only if you specify that comments be returned in a CommentSpec structure. For pixel maps and bitmaps, this field is set to 0.

commentHandle

A handle to an array of CommentSpec structures. For pixel maps and bitmaps, this field is set to NULL. See CommentSpec.

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 outline fonts, a font is a complete set of glyphs in one 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 structure. For pixel maps and bitmaps, this field is set to 0.

fontHandle

A handle to a list of FontSpec structures. For pixel maps and bitmaps, this field is set to NULL.

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 structure for that font. A font name is a name given to one font family to distinguish it from other font families.

reserved1

reserved2

Discussion

When you use the GetPictInfo function to collect information about a picture, or when you use the GetPixMapInfo function to collect color information about a pixel map or bitmap, the function returns the information in a PictInfo structure. When you gather this information for multiple pictures, pixel maps, or bitmaps, the RetrievePictInfo function also returns a PictInfo structure containing this information.

Initially, all of the fields in a new PictInfo structure are set to NULL. Relevant fields are set to appropriate values depending on the information you request using the Picture Utilities functions.

When you are finished with this information, be sure to dispose of it. You can dispose of Palette structures by using the Palette Manager function, DisposePalette. Dispose of ColorTable structures by using the QuickDraw function, DisposeCTable. Dispose of other allocations with the Memory Manager function, DisposeHandle.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

PictInfoID

Defines an identifier for a collection of pictures, pixel maps, or bitmaps in an application.

typedef long PictInfoID;

Discussion

Picture Utilities returns a PictInfoID value when you call the function NewPictInfo. It serves as a unique identifier for a collection of pictures, pixel maps, or bitmaps defined in your application. You use this ID when calling other Picture Utilities functions to manage and survey your collection.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

RecordColorsUPP

Defines a universal procedure pointer (UPP) to a color recording callback.

typedef RecordColorsProcPtr RecordColorsUPP;

Discussion

For more information, see the description of the callback function RecordColorsProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

PictUtils.h

Constants

Color Bank Type

Specifies the type of color bank used in a color-picking method.

enum {
   ColorBankIsCustom = -1,
   ColorBankIsExactAnd555 = 0,
   ColorBankIs555 = 1
};

Constants

ColorBankIsCustom

Gathers colors into a custom color bank. Picture Utilities gathers 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 RecordColorsProcPtr function with a pointer to the color bank (that is, to the 5-5-5 histogram). Your CalcColorTableProcPtr function selects whatever colors it needs from this color bank. Then the Picture Utilities function called by your application returns these colors in a Palette structure, a ColorTable structure, or both, as requested by your application.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

ColorBankIsExactAnd555

Gathers exact colors if there are less than 256 unique colors in picture; otherwise gathers colors for picture in a 5-5-5 histogram. 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 CalcColorTableProcPtr function to select which colors to return.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

ColorBankIs555

Gathers colors into a 5-5-5 histogram. Specify colorBankIsCustom constant 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 RecordColorsProcPtr function to create this color bank. The Picture Utilities also call your CalcColorTableProcPtr function to select colors from this color bank.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

Discussion

Your InitPickMethodProcPtr function returns these constants in the colorBankType parameter to indicate the type of color bank used in your color-picking method.

Color Selection Method

Indicates the color selection method used in a PictInfo record.

enum {
   systemMethod = 0,
   popularMethod = 1,
   medianMethod = 2
};

Constants

systemMethod

Lets Picture Utilities choose the method. Currently they always choose popularMethod.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

popularMethod

Returns the most frequently used colors.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

medianMethod

Returns a weighted distribution of colors.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

Discussion

These constants are used to indicate the method by which colors are selected for the ColorTable or Palette structure returned via the PictInfo structure, by the functions NewPictInfo , GetPixMapInfo , or GetPictInfo.

Color Information Type

Indicates the type of color information returned in a PictInfo record.

enum {
   returnColorTable = 0x0001,
   returnPalette = 0x0002,
   recordComments = 0x0004,
   recordFontInfo = 0x0008,
   suppressBlackAndWhite = 0x0010
};

Constants

returnColorTable

Specify to return a Color Table.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

returnPalette

Specify to return a Palette structure.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

recordComments

Specify to return comment information.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

recordFontInfo

Specify to return font information.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

suppressBlackAndWhite

Don't include black and white with returned colors.

Available in Mac OS X v10.0 and later.

Declared in PictUtils.h.

Discussion

These constants are used in the verb parameter of the GetPictInfo , GetPixMapInfo ,and NewPictInfo functions to indicate the type of information those functions should return. You can use any or all of these constants or the sum of the integers they represent.

Result Codes

The table below lists the most common result codes returned by Picture Utilities.

Result Code	Value	Description
`pictInfoVersionErr`	-11000	Wrong version of the PictInfo structure. Available in Mac OS X v10.0 and later.
`pictInfoIDErr`	-11001	The internal consistancy check for the PictInfoID is wrong. Available in Mac OS X v10.0 and later.
`pictInfoVerbErr`	-11002	The PictInfo verb is not valid. Available in Mac OS X v10.0 and later.
`cantLoadPickMethodErr`	-11003	Unable to load the custom pick method resource. Available in Mac OS X v10.0 and later.
`colorsRequestedErr`	-11004	The number of colors requested is illegal. Available in Mac OS X v10.0 and later.
`pictureDataErr`	-11005	The picture data is not valid. Available in Mac OS X v10.0 and later.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.