BPicture

A BPicture object represents a set of drawing instructions that are executed when the object is passed to BView’s DrawPicture() function. Because it contains drawing instructions rather than an actual image, a BPictureBPicture (unlike a BBitmap) is independent of the resolution of the display device.

Recording a Picture

To start recording into a BPicture, you pass a BPicture object to BView::BeginPicture(). All drawing instructions that are executed by the BView are recorded into the BPicture object. When you’re done recording, you call BView::EndPicture(), which passes back a pointer to the recorded object. For example:

BPicture *myPict;
someView->BeginPicture(new BPicture);
/* drawing code goes here*/
myPict = someView->EndPicture();

Only drawing that the BView does is recorded; drawing done by children and other views attached to the window is ignored, as is everything except drawing code.

Drawing instructions that are captured between BeginPicture() and EndPicture() are not renedered on-screen; ignored instructions may be rendered if they draw into the visible region of an on-screen window.

Any picture data in the BPicture passed to BeginPicture() is cleared; if you’d instead like to append to the BPicture, begin the picture recording with AppendPicture() instead. As with BeginPicture(), each AppendToPicture() must have a corresponding EndPicture().

The Picture Definition

The picture captures everything that affects the image that’s drawn. It takes a snapshot of the BView’s graphics state—the pen size, high and low colors, font size, and so on—when BeginPicture() is called. It then captures all subsequent modifications to those parameters, such as calls to MovePenTo(), SetLowColor(), an SetFontSize(). The recorded graphics state is used when the picture is drawn (through BView::DrawPicture()).

The picture records all primitive drawing instruction ( DrawBitmap(), StrokeEllipse(), FillRect(), etc.) and will even record calls to DrawPicture().

The picture makes its own copy of any data that’s passed during the recording session, including bitmaps passed to DrawBitmap() and picture data passed to DrawPicture().