The Interface Kit: BPicture

The Interface Kit Table of Contents | The Interface Kit Index

# BPicture

Derived from: none

Declared in: be/interface/Picture.h

Library: libbe.so

###### Summary

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 BPicture (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 `AppendPicture()` 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()`, and `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()`.

## Constructor and Destructor

### BPicture()

`BPicture(`void`) `
`BPicture(`const BPicture &picture`) `
`BPicture(` BMessage *archive`) `

Initializes the BPicture object by ensuring that it's empty, or by copying data from another picture or archive of a BPicture object.

### ~BPicture()

virtual `~BPicture() `

Destroys the Application Server's record of the BPicture object and deletes all its picture data.

## Member Functions

### Play()

virtual status_t *`Play(`void **callBackTable, int32 tableEntries, void *user`)`

Plays back a picture using a user's rendering functions. The functions are passed in callBackTable, an array of function pointers. tableEntries contains the number of functions in the table. The functions perform various tasks such as drawing lines and text. user is passed to each function, providing a hook for passing additional data to the call back functions. The functions, along with their positions in the call back table, are detailed below.

Index | Function prototype
--- | ---
0 | no operation
1 | MovePenBy(void *user, BPoint delta)
2 | StrokeLine(void *user, BPoint start, BPoint end)
3 | StrokeRect(void *user, BRect rect)
4 | FillRect(void *user, BRect rect)
5 | StrokeRoundRect(void *user, BRect rect, BPoint radii)
6 | FillRoundRect(void *user, BRect rect, BPoint radii)
7 | StrokeBezier(void *user, BPoint *control)
8 | FillBezier(void *user, BPoint *control)
9 | StrokeArc(void *user, BPoint center, BPoint radii, float startTheta, float arcTheta)
10 | FillArc(void *user, BPoint center, BPoint radii, float startTheta, float arcTheta)
11 | StrokeEllipse(void *user, BPoint center, BPoint radii)
12 | FillEllipse(void *user, BPoint center, BPoint radii)
13 | StrokePolygon(void *user, int32 numPoints, BPoint *points, bool isClosed)
14 | FillPolygon(void *user, int32 numPoints, BPoint *points, bool isClosed)
15 | Reserved
16 | Reserved
17 | DrawString(void *user, char *string, float deltax, float deltay)
18 | DrawPixels(void *user, BRect src, BRect dest, int32 width, int32 height, int32 bytesPerRow, int32 pixelFormat, int32 flags, void *data)
19 | Reserved
20 | SetClippingRects(void *user, BRect *rects, uint32 numRects)
21 | Reserved
22 | PushState(void *user)
23 | PopState(void *user)
24 | EnterStateChange(void *user)
25 | ExitStateChange(void *user)
26 | EnterFontState(void *user)
27 | ExitFontState(void *user)
28 | SetOrigin(void *user, BPoint pt)
29 | SetPenLocation(void *user, BPoint pt)
30 | SetDrawingMode(void *user, drawing_mode mode)
31 | SetLineMode(void *user, cap_mode capMode, join_mode joinMode, float miterLimit)
32 | SetPenSize(void *user, float size)
33 | SetForeColor(void *user, rgb_color color)
34 | SetBackColor(void *user, rgb_color color)
35 | SetStipplePattern(void *user, pattern p)
36 | SetScale(void *user, float scale)
37 | SetFontFamily(void *user, char *family)
38 | SetFontStyle(void *user, char *style)
39 | SetFontSpacing(void *user, int32 spacing)
40 | SetFontSize(void *user, float size)
41 | SetFontRotate(void *user, float rotation)
42 | SetFontEncoding(void *user, int32 encoding)
43 | SetFontFlags(void *user, int32 flags)
44 | SetFontShear(void *user, float shear)
45 | Reserved
46 | SetFontFace(void *user, int32 flags)

While many of these functions are similar to those found in BView, there are some important differences:

- The return value of the functions is ignored.

- The Fill... and Stroke... functions do not explicitly specify patterns. Instead, they should be drawn in the current pattern, as set by the SetStipplePattern() (callback #35). Note that there is no equivalent to SetStipplePattern() in BView.

- The deltax and deltay arguments passed to DrawString() are escapement delta values; the string should be drawn at the current pen position.

- MovePenBy() uses a BPoint to specify the amount to move the pen. The x component of the BPoint gives the x offset and the y component the y offset.

- Similarly, ...RoundRect() and ...Ellipse() use a BPoint to specify the two separate radius components. The x component gives the x radius and the y component the y radius.

- DrawPixels() is a BPicture-specific primitive for rendering bitmaps. It is a request to copy the src rectangle from the raw color information in data to the dest rectangle of the current rendering area. width, height, bytesPerRow, and pixelFormat provide all the information necessary to interpret data. flags is currently always zero and should be ignored. src and dest need not have the same dimensions; in these cases, the function should scale the bitmap appropriately.

- SetClippingRects() is a BPicture-specific primitive approximating `ConstrainClippingRegion()`. It instructs the renderer to replace the current clipping region with the union of the rectangles passed to SetClippingRects().

- Changes in the graphics state are sandwiched between calls to EnterStateChange() and ExitStateChange(). State change functions will only be called between these functions. No other call backs will be called between these functions. State change functions are all Set... functions in addition to EnterFontState() and ExitFontState().

- Similarly, changes to the font state are sandwiched between calls to EnterFontState() and ExitFontState(). Font state change functions will only be called between these functions. No other call backs will be called between these functions. Font state change functions are all SetFont... functions. Many of the font state functions are found in BFont rather than BView.

- SetFontRotate() sets the rotation of the font. Unlike the `BFont::SetRotation()` function, the angle here is specified in radians, rather than in degrees. You can convert the value into degrees by using the forumla:

degrees = (rotation*180.0)/3.14159265369);

## Archived Fields

The `Archive()` function adds the following fields to its BMessage argument:

Field | Type code | Meaning
--- | --- | ---
"_ver" | `B_INT32_TYPE` | Always 1.
"_endian" | `B_INT8_TYPE` | Endianness of the data. Always `B_HOST_IS_BENDIAN`.
"_data" | `B_RAW_TYPE` | The BPicture data.

The Interface Kit Table of Contents | The Interface Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..