BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_camera

The Structure
Members
Copy/Assign
Access & Maintenance
Referencing & Lifetime
Initialisation
Construction & Destruction
Supplementary
Import & Export

`br_camera`

The Structure

BRender's camera data structure. See Camera Actors.

The `typedef`

(See camera.h for precise declaration and ordering)

Behaviour

br_uint_8 type Camera type

Parameters

br_angle field_of_view Field of view

br_scalar hither_z Front of view volume

br_scalar yon_z Back of view volume

br_scalar aspect Aspect ratio (x/y)

br_scalar width Width of projection surface

br_scalar height Height of projection surface

Supplementary

char * identifier Camera name

void * user User data (application dependent)

Related Functions

Image Support

See also BrActorToScreenMatrix4()83, BrMatrix4Perspective()225.

Related Structures

Scene Modelling

See br_actor74.

Members

Behaviour

`br_uint_8 type`

Type of camera. Which can be one of the following:

Parameters

`br_angle field_of_view`

Field of view, i.e. the angle subtended at the camera between the top and bottom of the view volume (pyramid). Applies only to perspective cameras. The value should be greater than zero and less than 180xbc . Note than this is the full angle, i.e. not the half angle, between the view z axis and top (or bottom) of view volume.

`br_scalar hither_z`

Distance of front of view volume from camera along negative z axis, i.e. -hither_z in view co-ordinates. The value should be greater than zero.

`br_scalar yon_z`

Distance of back of view volume from camera along negative z axis, i.e. -yon_z in view co-ordinates. The value should be greater than hither_z.

`br_scalar aspect`

Scaling factor for width of viewing volume. For perspective cameras, xb1 1 in y view ordinates is mapped to the height of the output pixel map, and xb1 aspect in x view ordinates is mapped to the width of the output pixel map. For parallel cameras, the height of the view volume is mapped to the height of the output pixel map, whereas widthaspect is mapped to the width of the output pixel map.

`br_scalar width`

Width of view volume (rectangular prism) in world co-ordinates (before aspect is applied) - the actual width is widthaspect. Applies only to parallel cameras.

`br_scalar height`

Height of view volume (rectangular prism) in world co-ordinates. Applies only to parallel cameras.

Supplementary

`char * identifier`

Pointer to unique, zero terminated, character string (or Null if not required).

If identifier is set by BrActorLoad()95 or BrActorLoadMany()96 it will have been constructed using BrResStrDup()49.

`void * user`

This member may be used by the application for its own purposes. It is initialised to Null upon allocation (if allocated by BRender), and not accessed by BRender thereafter.

Copy/Assign

The camera should copied using structure assignment.

Access & Maintenance

Modification is not recommended during rendering, especially if applied to the viewing camera. The members should always accord with the camera type. The aspect may need to be updated in line with changing image dimensions.

Referencing & Lifetime

If not constructed by BrActorAllocate()89 it may be multiply referenced (given a sufficient lifetime). The camera structure should be maintained at least as long as it is referenced by any actor.

Initialisation

Only members applicable to the camera type need be initialised.

E.g. BrActorAllocate(BR_ACTOR_CAMERA,NULL) currently initialises a br_camera107 structure as follows (after performing memset(,0,sizeof(br_camera))):


br_camera* camera;
...
camera->type=BR_CAMERA_PERSPECTIVE;
camera->field_of_view=BR_ANGLE_DEG(45);
camera->hither_z=BR_SCALAR(0.1);
camera->yon_z=BR_SCALAR(10.0);
camera->aspect=BR_SCALAR(1.0);

Construction & Destruction

The camera structure can either be constructed/destroyed by the application, or by supplying Null to BrActorAllocate()89.

Supplementary

Cameras created by BrActorAllocate()89 are allocated from the BR_MEMORY_CAMERA ("CAMERA") resource class, and hence can benefit from the resource class supplementary functions.

Import & Export

Cameras are imported and exported with actors that specify them. See BrActorLoad()95 and BrActorSave()94.

Generated with CERN WebMaker