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 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().