br_pixelmap
272
In BRender, all two dimensional images are described in terms of pixel maps. A pixel map may represent any device that can be described in terms of width and height, and can support primitive graphical operations such as plot a point, line or triangle, e.g. video memory, a printer, or an area of memory. As far as BRender is concerned there is very little difference between them, it'll quite happily produce an image on a dot matrix printer as on an accelerated graphics card. Of course, the performance may be quite different depending on what device the pixel map refers to. On some platforms there may be graphic acceleration hardware which may only be usable on video memory, which may be inaccessible to BRender, thus rendering to a screen pixel map may be a few times faster than rendering to a pixel map based in main memory. Sometimes it's the other way around.
BrPixelmapDirtyRectangleFill()
42
and BrPixelmapDirtyRectangleCopy()
42
are useful when using results from within a render bounds call back function (see br_renderbounds_cbfn
307
).
In some cases a scene rendering may only affect a few small areas of the destination pixel map. It can provide some performance improvement if only these areas are cleared each frame, rather than clearing the entire pixel map. The procedure is to utilise the br_renderbounds_cbfn
307 call-back, setting it before rendering (using
BrZbRenderBoundsCallbackSet()
38), collect a list (or overall bounding rectangle) of bounds supplied, and use this to clear the destination pixel map just before the next rendering. Each rectangle can be cleared or reset using
BrPixelmapDirtyRectangleFill()
42
or BrPixelmapDirtyRectangleCopy()
42. These functions are used because they can be faster, though they may utilise a larger rectangle than that specified (for more efficient word aligned operation).
This function is intended to be used in conjunction with a rendering call-back to reset those regions of a pixel map that have been rendered to.
A pointer to the destination pixel map.
Co-ordinates of the rectangle's top left corner.
Rectangle width and height (in pixels).
Value to set each pixel to.
Description:
Set an area of a pixel map that covers a specified rectangle to a given value.BrPixelmapDirtyRectangleFill()
void BrPixelmapDirtyRectangleFill(br_pixelmap* dst,br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h,br_uint_32 colour)
br_pixelmap * dst
br_int_16 x,y
br_uint_16 w,h
br_uint_32 colour
br_uint_32 zfar=0xffffffff;
br_int_16 drx, dry;
br_uint_16 drw, drh;
br_pixelmap* zbuffer;
...
BrPixelmapDirtyRectangleFill(zbuffer,drx,dry,drw,drh,zfar);
See Also:
BrZbRenderBoundsCallbackSet()
38
This function is intended to be used in conjunction with a rendering call-back to copy those regions of a pixel map that have been rendered to.
A pointer to the destination pixel map.
A pointer to the source pixel map.
Co-ordinates of the rectangle's top left corner.
Rectangle width and height (in pixels).
Description:
Copy a rectangular window of data from one pixel map to the same position in another pixel map.BrPixelmapDirtyRectangleCopy()
void BrPixelmapDirtyRectangleCopy(br_pixelmap* dst,const br_pixelmap* src, br_int_16 x, br_int_16 y,br_uint_16 w, br_uint_16 h)
br_pixelmap * dst
const br_pixelmap * src
br_int_16 x,y
br_uint_16 w,h
br_int_16 drx, dry;
br_uint_16 drw, drh;
br_pixelmap* offscreen;
br_pixelmap* backdrop;
...
BrPixelmapDirtyRectangleCopy(offscreen, backdrop,drx,dry,drw,drh);
See Also:
BrZbRenderBoundsCallbackSet()
38
Fortunately, BRender provides a function BrPixelmapDoubleBuffer()
44 which should be used to avoid the possible problems as described above. This will perform, transparently, either of the last two methods. If the video device supports page swapping then it will utilise that feature, otherwise it will copy a pixel map to video memory. However, it will automatically do this at the start of the CRT fly-back, wherever possible.
Description:
If the destination pixel map relates to a device, for example a graphics hardware screen, then the source `off-screen' pixel map is copied to the destination pixel map at a suitable moment. If the source is an off screen pixel map (created using BrPixelmapDoubleBuffer()
BrPixelmapMatch(
...,
BR_PMMATCH_OFFSCREEN
)
286) then it is swapped with the destination pixel map instead.
Otherwise, the function is equivalent to BrPixelmapCopy()
280
and the source pixel map is copied to the destination pixel map.
Declaration:
void BrPixelmapDoubleBuffer(br_pixelmap* dst, br_pixelmap* src)
Arguments:
br_pixelmap * dst
A pointer to the destination pixel map.
br_pixelmap * src
A pointer to the source pixel map.
Effects: If the destination is a device that supports a `wait for vertical retrace' function, a copy or swap will be performed pending that event.
If the destination is a device that supports double buffering and the source pixel map is an off-screen secondary buffer, the destination and source will be switched to use each other's buffers.
Remarks: Returns immediately, but will cause further rendering or calls of this function to block until the copy or swap has been completed.
BrScenePick2D()
84
which will invoke a specified call-back function for each model actor whose bounds contain the pixel. It is up to the application to determine greater precision, such as which model, faces or texture co-ordinates appear at the pixel.
There is also a 3D version of the pick function, called BrScenePick3D()
82. This will perform a similar operation, but operates on a bounding box rather than a screen pixel. However, if the image is depth buffered, the depth information for a pixel could be used in conjunction with
BrActorToScreenMatrix4()
83
to produce a bounding box, more closely corresponding to the pixel resulting from a model's face.