All DatabasesInside Mac - Basic Toolbox
OpenPicture
OpenPicture Begin recording a picture definition (two versions)
#include <Quickdraw.h> Color Quickdraw
PicHandle OpenPicture( picRect );
Rect *picRect ; rectangle defining frame of picture
There are two versions of OpenPicture. Explanations of both versions
follow, first the old (the one that uses version 1 pictures) and then the new
one (that uses version 2 pictures).
Version 1 Pictures
OpenPicture allocates and initializes a Picture structure, setting its frame
size and position to a specified rectangle. It hides the pen. Subsequent drawing
operations are recorded into the picture structure until picture recording is
stopped via ClosePicture.
picRect is the address of an 8-byte Rect structure, expressed in
coordinates local to the current GrafPort. Portions of figures drawn
outside of this frame are recorded in the picture, but are not
displayed via DrawPicture.
Returns: a PicHandle; a handle leading to a variable-length Picture
structure that is allocated and initialized by this call. The picSize
field is set to 10 and the picFrame field is set equal to picRect .
Notes: Be sure to set the GrafPort's clipRgn to a smaller size than its default
setting (see SetClip and ClipRect). One way to shrink the clipRgn is to
call this function before you record your picture:
ClipRect( &thePort->portRect );
Unlike OpenRgn , this call allocates the handle and data structure for you.
However, many other features are similar:
• The pen is hidden (unless a previous call to ShowPen has not been
balanced) and you can use ShowPen after opening the picture if you want
to see the pen while drawing.
• Subsequent drawing operations are recorded into the picture, and may be
played-back ( optionally scaled) via DrawPicture.
• Don't open another picture when one is already open.
• To temporarily interrupt picture definition, you can switch to a different
GrafPort (see SetPort), or you can save the current value of picSave,
and set it to NIL. Restore the saved value to resume picture recording.
Pictures are saved in a compact internal format, starting at offset 10
within the variable-length Picture structure. With the 64K ROMs,
pictures are limited to 32K and the length can be found in the picSize field.
Later ROMs overcome this limitation; you can use GetHandleSize to find
the size of a picture-a long int, up to 4 giga bytes. The picSize field contains
the lower 16-bits of the actual size.
If you run out of memory while defining a picture, the picFrame field gets
set to the empty rectangle (use EmptyRect to test for this).
Virtually all operations that change the screen image (and do so within the
area enclosed by picRect ) are recorded into the picture (exceptions include
CopyMask and ScrollRect, whose output is not saved in the picture
definition). For instance, a typical way to create a bit-image for transfer
to the desk scrap is to use CopyBits after opening a picture, as in the
example, below.
Picture "comments" can be used to store additional information about the
picture into its definition, such as the order in which picture elements are
drawn or special instructions for the printer. See PicComment and
StdComment.
If you need to store a PICT over 32K, you may not be able to store it in a
'PICT' resource. To see how to work around this, see Large PICTs.
Example
#include <Quickdraw.h>
Rect picRect;
PicHandle thePic;
ClipRect( &thePort->portRect ); // Important: shrink clipRgn
SetRect( &picRect, 0,0,100,100 );
thePic = OpenPicture( &picRect ); // start recording
CopyBits( &thePort->portBits, &thePort->portBits,
&picRect, &picRect, srcCopy, 0L );
ClosePicture(); Í// stop recording
// Now you can copy the picture to the scrap, scale and
// draw it elsewhere on the screen, etc.
Version 2 Pictures
OpenPicture for Color QuickDraw is different from the old routine of the
same name only in that it automatically opens a version 2 picture if the
current port is a CGrafPort. Otherwise, it allocates and initializes a Picture
structure, setting its frame size and position to a specified rectangle. It hides
the pen. Subsequent drawing operations are recorded into the picture
structure until picture recording is stopped via ClosePicture.
picRect is the address of an 8-byte Rect structure, expressed in
coordinates local to the current CGrafPort. Portions of figures drawn
outside of this frame are recorded in the picture, but are not
displayed via DrawPicture.
Returns: a PicHandle; a handle leading to a variable-length Picture
structure which is allocated and initialized by this call. The picSize
field is set to 10 and the picFrame field is set equal to picRect.
Notes: Be sure to set the cGrafPort's clipRgn to a smaller size than its default
setting (see SetClip and ClipRect).
Unlike OpenRgn, this call DOES allocate the handle and data structure for
you. However, many other features are similar:
• The pen is hidden (unless a previous call to ShowPen has not been
balanced) and you can use ShowPen after opening the picture if you want
to see the pen while drawing.
• Subsequent drawing operations are recorded into the picture, and may be
played back ( optionally scaled) via DrawPicture.
• Don't open another picture when one is already open.
• To temporarily interrupt picture definition, you can switch to a different
CGrafPort, or you can save the current value of picSave, and set it to NIL.
Restore the saved value to resume picture recording.
Pictures are saved in a compact internal format, starting at offset 10
within the variable-length Picture structure. With the 64K ROMs,
pictures are limited to 32K and the length can be found in the picSize field.
Later ROMs overcome this limitation; you can use GetHandleSize to find
the size of a picture -- a long short, up to 4 giga bytes. The picSize field
contains the lower 16-bits of the actual size.
If you run out of memory while defining a picture, the picFrame field is
set to the empty rectangle (use EmptyRect to test for this).
Virtually all operations which change the screen image (and do so within
the area enclosed by picRect) are recorded into the picture (exceptions
include CopyMask and ScrollRect, whose output is not saved in the
picture definition). For instance, a typical way to create a bit-image for
transfer to the desk scrap is to use CopyBits after opening a picture, as in
the example, below.
Picture "comments" can be used to store additional information about the
picture into its definition, such as the order in which picture elements are
drawn or special instructions for the printer. See PicComment and
StdComment.
Referenced by (67):