Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

QuickDraw and Picture Utilities Routines / Creating and Disposing of Pictures

OpenCPicture

To begin defining a picture in extended version 2 format, use the OpenCPicture function.

FUNCTION OpenCPicture (newHeader: OpenCPicParams): PicHandle;

newHeader

An OpenCPicParams record, which is defined as follows (see page 7-28 for a description of the OpenCPicParams data type):

            TYPE OpenCPicParams = 
            RECORD
               srcRect:    Rect;    {optimal bounding rectangle }
                                    { for displaying picture at }
                                    { resolution indicated in }
                                    { hRes, vRes fields}
               hRes:       Fixed;   {best horizontal resolution; }
                                    { $00480000 specifies 72 dpi}
               vRes:       Fixed;   {best vertical resolution; }
                                    { $00480000 specifies 72 dpi}
               version:    Integer; {set to -2}
               reserved1:  Integer; {reserved; set to 0}
               reserved2:  LongInt; {reserved; set to 0}
            END;

DESCRIPTION

The OpenCPicture function returns a handle to a new Picture record (described on page 7-26). Use the OpenCPicture function to begin defining a picture; OpenCPicture collects your subsequent drawing commands in this record. When defining a picture, you can use all other QuickDraw drawing routines described in this book, with the exception of CopyMask, CopyDeepMask, SeedFill, SeedCFill, CalcMask, and CalcCMask. (Nor can you use the PlotCIcon procedure, described in Inside Macintosh: More Macintosh Toolbox.)

You can also use the PicComment procedure (described on page 7-39) to include picture comments in your picture definition.

The OpenCPicture function creates pictures in the extended version 2 format. This format permits your application to specify resolutions when creating images.

Use the OpenCPicParams record you pass in the newHeader parameter to specify the horizontal and vertical resolution for the picture, and specify an optimal bounding rectangle for displaying the picture at this resolution. When you later call the DrawPicture procedure (described on page 7-43) to play back the saved picture, you supply a destination rectangle, and DrawPicture scales the picture so that it is completely aligned with the destination rectangle. To display a picture at a resolution other than that at which it was created, your application should compute an appropriate destination rectangle by scaling its width and height by the following factor:

scale factor = destination resolution / source resolution

For example, if a picture was created at 300 dpi and you want to display it at 75 dpi, then your application should compute the destination rectangle width and height as 1/4 of those of the picture's bounding rectangle.

The OpenCPicture function calls the HidePen procedure, so no drawing occurs on the screen while the picture is open (unless you call the ShowPen procedure just after OpenCPicture, or you called ShowPen previously without balancing it by a call to HidePen).

Use the handle returned by OpenCPicture when referring to the picture in subsequent routines, such as the DrawPicture procedure.

After defining the picture, close it by using the ClosePicture procedure, described on page 7-41. To draw the picture, use the DrawPicture procedure, described on page 7-43.

After creating the picture, your application can use the GetPictInfo function (described on page 7-46) to gather information about it. The PictInfo record (described on page 7-31) returned by GetPictInfo returns the picture's resolution and optimal bounding rectangle.

SPECIAL CONSIDERATIONS

When creating a picture, you should generally use the ClosePicture procedure to finish it before you open the Printing Manager with the PrOpen procedure. There are two main reasons for this. First, you should allow the printing driver to use as much memory as possible. Second, the Printing Manager creates its own type of graphics port--one that replaces the standard QuickDraw drawing operations stored in the grafProcs field of a CGrafPort or GrafPort record; to avoid unexpected results when creating a picture, you should draw into a graphics port created with QuickDraw instead of drawing into a printing port created by the Printing Manager.

After calling OpenCPicture, be sure to finish your picture definition by calling ClosePicture before you call OpenCPicture again. You cannot nest calls to OpenCPicture.

Always use the ClipRect procedure to specify a clipping region appropriate for your picture before you call OpenCPicture. If you do not use ClipRect to specify a clipping region, OpenCPicture uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you scale the picture when drawing it, the clipping region can become invalid when DrawPicture scales the clipping region--in which case, your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when you draw it. Setting a clipping region equal to the port rectangle of the current graphics port, as shown in Listing 7-1 on page 7-10, always sets a valid clipping region.

The OpenCPicture function may move or purge memory.

SEE ALSO

The PrOpen procedure is described in the chapter "Printing Manager" in this book. The ClipRect procedure is described in the chapter "Basic QuickDraw" in this book. The ShowPen and HidePen procedures are described in the chapter "QuickDraw Drawing" in this book.

Listing 7-1 on page 7-10 illustrates the use of the OpenCPicture function.