BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_light
Next|Prev|Up
The Structure
Members
Copy/Assign
Access & Maintenance
Referencing & Lifetime
Initialisation
Construction & Destruction
Supplementary
Import & Export
Platform Specific

br_light


The Structure

This structure is used to specify the properties of light actors. See Light Actors.

The typedef

(See light.h for precise declaration and ordering)

Behaviour

br_uint_8 type Light type

br_colour colour Light colour

Attenuation

br_scalar attenuation_c Light intensity

br_scalar attenuation_l Linear attenuation factor for point and spot lights

br_scalar attenuation_q Quadratic attenuation factor for point and spot lights

Spot Lighting

br_angle cone_inner The angle giving the cone of full-intensity light cast by a spot

br_angle cone_outer The angle giving the cone of illumination of a spot

Supplementary

char * identifier Light name

void * user User data (application dependent)

Related Functions

Scene Modelling

See BrLightEnable()
85, and BrLightDisable()86.

Members

Behaviour

br_uint_8 type

This member defines the type of the light. Note that different light types can affect rendering performance in different ways. Pre-lighting textures is the fastest means of lighting objects in a scene, ambient lighting comes next, then the three active lighting methods: direct, point and spot lights (in order of increasing processing requirements). The more lights in a scene*1, the more computation required.

The three active light types are described in the following table:

The type member also encodes a flag value BR_LIGHT_VIEW which can be combined with any of the three light types using the `inclusive-or' operation.When the flag is present, lighting calculations are performed in view space rather than model space. This is slower, but prevents odd anomalies if non-uniform scalings are used on models.

The bit mask value BR_LIGHT_TYPE can be used to extract the light type using the `and' operation.

br_colour colour

If the rendering engine supports it, a light may be of a specific colour. Typically supported when rendering in `true colour'.

Attenuation

The linear and quadratic attenuation factors determine the degree by which light intensity falls off with respect to distance and squared distance from the light source. If d is distance, and Ac, Al, Aq are the constant, linear and quadratic attenuation factors, then light intensity L is given by:

If a light actor is created with a default specification, the default values supplied for Ac, Al, Aq are 1.0, 0.0 and 0.0 respectively.

br_scalar attenuation_c

Constant attenuation component. Light intensity is inversely proportional to this value.

br_scalar attenuation_l

Linear attenuation factor. Light intensity is inversely proportional to distance factored by this value. It only applies to point and spot lights.

br_scalar attenuation_q

Quadratic attenuation factor. Light intensity is inversely proportional to distance factored by the square of this value. It only applies to point and spot lights.

Spot Lighting

Spot lights are defined in terms of an inner, fully lit cone of light and an outer, penumbral cone of light diminishing from fully lit to unlit. The intensity fall off between the inner and outer cones is linear.

The effect of having the outer cone angle smaller than the inner cone angle is undefined.

br_angle cone_inner

The inner cone of a spot light is defined by the angle between the cone's axis and its circumference. This represents the region within which surfaces will be fully lit (subject to attenuation).

br_angle cone_outer

The outer cone of a spot light is defined by the angle between the cone's axis and its circumference. This represents the region within which surfaces will be partially lit (subject to attenuation). The light level falls off linearly from the fully lit level at the inner cone to zero at the limit of the outer cone.

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 light may be freely copied.

Access & Maintenance

Lights can be modified at any time, though changes will not have any effect unless the light is enabled (see BrLightEnable()85). The members should always accord with the light type.

Referencing & Lifetime

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

Initialisation

Only members applicable to the light type need be initialised.

E.g. BrActorAllocate(BR_ACTOR_LIGHT,NULL) currently initialises a br_light145 structure as follows (after performing memset(,0,sizeof(br_light))):


br_light* light;
...
light->type=BR_LIGHT_DIRECT;
light->colour=BR_COLOUR_RGB(255,255,255);
light->attenuation_c=BR_SCALAR(1.0);

Construction & Destruction

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

Supplementary

Lights created by BrActorAllocate()89 are allocated from the BR_MEMORY_LIGHT ("LIGHT") resource class, and hence can benefit from the resource class supplementary functions.

Import & Export

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

Platform Specific

Some platforms directly support some types of light in hardware, though there is often a significant limit upon how many lights of each type are supported (also see BR_MAX_LIGHTS).


Generated with
CERN WebMaker