BRender Technical Reference Manual:3 Functions (Structured Reference):Image Support
Next|Prev|Up
Pixel Maps
BrPixelmapDirtyRectangleFill()
BrPixelmapDirtyRectangleCopy()
BrPixelmapDoubleBuffer()
Pick Functions

Image Support


Pixel Maps

See br_pixelmap272

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.

Using Pixel Maps

In general, you'll use a pixel map for the following:

Operations

The operations available on pixel maps include:

Rendering To Pixel Maps

BrPixelmapDirtyRectangleFill()42 and BrPixelmapDirtyRectangleCopy()42 are useful when using results from within a render bounds call back function (see br_renderbounds_cbfn307).

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


BrPixelmapDirtyRectangleFill()

Description:
Set an area of a pixel map that covers a specified rectangle to a given value.

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.

Declaration:
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)

Arguments:
br_pixelmap * dst

A pointer to the destination pixel map.

br_int_16 x,y

Co-ordinates of the rectangle's top left corner.

br_uint_16 w,h

Rectangle width and height (in pixels).

br_uint_32 colour

Value to set each pixel to.

Effects:
Sets an area of pixels in the destination pixel map to a value, such that each pixel in the specified rectangle is reset.

Remarks:
The actual area affected depends upon the platform and implementation, but this function is intended to provide the fastest way of resetting a particular rectangle. It is possible that this could be as large as the entire pixel map. Hopefully, most redundant, repeated calls would be ignored.

Example:
	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


BrPixelmapDirtyRectangleCopy()

Description:
Copy a rectangular window of data from one pixel map to the same position in another pixel map.

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.

Declaration:
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)

Arguments:
br_pixelmap * dst

A pointer to the destination pixel map.

const br_pixelmap * src

A pointer to the source pixel map.

br_int_16 x,y

Co-ordinates of the rectangle's top left corner.

br_uint_16 w,h

Rectangle width and height (in pixels).

Preconditions:
The source and destination pixel maps must have the same type and dimensions.

Effects:
Copies an area of pixels from the source to the destination pixel map, such that each pixel in the specified rectangle is copied.

Remarks:
The actual area copied depends upon the platform and implementation, but this function is intended to provide the fastest way of copying a particular rectangle. It is possible that this could be as large as the entire pixel map. Hopefully, most redundant, repeated calls would be ignored.

Example:
	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


Pixel Maps To Video

There are three ways of rendering to video:

  1. Render direct to a pixel map representing a video device

  2. Render to a memory based pixel map and copy it to a video pixel map each frame

  3. Render to a memory based pixel map and swap it with a video pixel map each frame

All three methods suffer from problems of tearing, the first also from visible image construction. That is, if modifications to video memory are not postponed until the start of the CRT fly-back.

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.


BrPixelmapDoubleBuffer()

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


Pick Functions

A common function required of a 3D API, by developers working on a 3D user interface, is one that will return the model at a particular pixel. This is typically used for picking functions, e.g. mouse selection operations by the user. For this purpose, BRender provides the function 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.


Generated with CERN WebMaker