Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

QuickDraw and Picture Utilities Routines / Collecting Picture Information

RetrievePictInfo

Use the RetrievePictInfo function to return information about all the pictures, pixel maps, and bitmaps included in a survey.

FUNCTION RetrievePictInfo (thePictInfoID: PictInfoID; 
                          VAR thePictInfo: PictInfo; 
                          colorsRequested: Integer): OSErr;

thePictInfoID

The ID number--returned by the NewPictInfo function--that identifies the survey of pictures, pixel maps, and bitmaps. The NewPictInfo function is described on page 7-52.

thePictInfo

A pointer to the PictInfo record that holds information about the pictures or images in the survey. The PictInfo record is described on page 7-31.

colorsRequested

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

DESCRIPTION

In a PictInfo record that you point to in the parameter thePictInfo, the RetrievePictInfo function returns information about all of the pictures and images collected in the survey that you specify in the parameter thePictInfoID.

After using the NewPictInfo function to create a new survey, and then using RecordPictInfo to add pictures to your survey and RecordPixMapInfo to add pixel maps and bitmaps to your survey, you can call RetrievePictInfo.

When you are finished with the information in the PictInfo record, be sure to dispose of it. You can dispose of the Palette record by using the DisposePalette procedure. You can dispose of the ColorTable record by using the DisposeCTable procedure. You can dispose of other allocations with the DisposeHandle procedure. You should also use the DisposePictInfo function (described next) to dispose of the private data structures created by the NewPictInfo function.

SPECIAL CONSIDERATIONS

The RetrievePictInfo function may move or purge memory.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the RetrievePictInfo function are

Trap macro	Selector
_Pack15	$0505

RESULT CODES

pictInfoIDErr	-11001	Invalid picture information ID
colorsRequestedErr	-11004	Number out of range or greater than that passed to NewPictInfo

SEE ALSO

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.