Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

Data Structures /

Picture

When you use the OpenCPicture or OpenPicture function (described on page 7-36 and page 7-38, respectively), QuickDraw begins collecting your subsequent drawing commands in a Picture record. (You use the ClosePicture procedure, described on page 7-41, to complete a picture definition.) When you use the GetPicture function (described on page 7-45) to retrieve a picture stored in a resource, GetPicture reads the resource into memory as a Picture record. ('PICT' resources are described on page 7-66.) By using the DrawPicture procedure (described on page 7-43), you can draw onscreen the picture defined by the commands stored in the Picture record.

A Picture record is defined as follows:

TYPE Picture =
RECORD
   picSize:    Integer; {for a version 1 picture: its size}
   picFrame:   Rect;    {bounding rectangle for the picture}
   {variable amount of picture data in the form of opcodes}
END;

Field Description

picSize

The size of the rest of this record for a version 1 picture. To maintain compatibility with the version 1 picture format, the picSize field was not changed for the version 2 picture or extended version 2 formats. The information in this field is useful only for version 1 pictures, which cannot exceed 32 KB in size. Because version 2 and extended version 2 pictures can be much larger than the 32 KB limit imposed by the 2-byte picSize field, you should use the Memory Manager function GetHandleSize to determine the size of a picture in memory, the File Manager function PBGetFInfo to determine the size of a picture in a 'PICT' file, and the Resource Manager function MaxSizeResource to determine the size of a 'PICT' resource. (See Inside Macintosh: Memory, Inside Macintosh: Files, and Inside Macintosh: More Macintosh Toolbox for more information about these functions.)

picFrame

The bounding rectangle for the picture defined in the rest of this record. The DrawPicture procedure uses this rectangle to scale the picture if you draw it into a destination rectangle of a different size.

Picture comments and compact drawing instructions in the form of picture opcodes compose the rest of this record.

A picture opcode is a number that the DrawPicture procedure uses to determine what object to draw or what mode to change for subsequent drawing. For debugging purposes, picture opcodes are listed in Appendix A at the back of this book. Your application generally should not read or write this picture data directly. Instead,
your application should use the OpenCPicture (or OpenPicture), ClosePicture, and DrawPicture routines to process these opcodes.

The Picture record can also contain picture comments. Created by applications using the PicComment procedure, picture comments contain data or commands for special processing by output devices, such as PostScript printers. The PicComment procedure is described on page 7-39, and picture comments are described in greater detail in Appendix B in this book.

You can use File Manager routines to save the picture in a file of type 'PICT', you can use Resource Manager routines to save the picture in a resource of type 'PICT', and you can use the Scrap Manager procedure PutScrap to store the picture in 'PICT' scrap format. See the chapter "File Manager" in Inside Macintosh: Files and the chapters "Resource Manager" and "Scrap Manager" in Inside Macintosh: More Macintosh Toolbox for more information about saving files, resources, and scrap data.