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

br_face

The Structure

The face data structure, describing a single triangular face.

The typedef

(See model.h for precise declaration and ordering)

br_uint_16 vertices[3] Vertices around face

br_material * material Face material

br_uint_16 smoothing Controls smoothing between shared edges

br_uint_8 flags Face flags

Related Structures

See br_model228 for the structure in which vertices are used.

Members

br_uint_16 vertices[3]

An array of vertex indices specifying the vertices of this face. This defines a polygon of the model's the surface. The order in which vertices are listed is important. The primary, visible side of a face from the viewpoint has its vertices listed in anticlockwise order.

See br_model228 and br_vertex367.

br_material material

Pointer to the material structure associated with this face. Note that if this is Null and the face is part of a model actor's model, then the model actor's material (as specified or inherited) will be used.

br_uint_16 smoothing

A 16 bit field in which each bit represents a smoothing group. If, when smooth-shading a surface, two adjacent faces share a smoothing group, the edge between them will be smooth.

br_uint_8 flags

Face flags, indicating whether the edges of the face abut co-planar faces, and thus do not need to be drawn in the wire-frame render style BR_RSTYLE_EDGES. The following table describes each flag.



Copy/Assign

Face structures should not be copied by assignment - copy member-wise instead. Note that faces so copied, will still need the models that refer to them to be updated before they are involved in rendering.

Access & Maintenance

Members may be freely accessed. The structure should remain valid while it is referenced by any model. Some private members are modified if BrModelUpdate()237 is applied to the model that references the face. Any changes to members will not affect models that use the face until BrModelUpdate()237 is called. BrModelUpdate()237 must be called before rendering if any changes have been made to faces of models that are in the registry.

Referencing & Lifetime

Be careful of referencing faces especially ones allocated by BrModelAllocate()239, they are liable to be moved around during BrModelUpdate()237, say. Faces are generally only allocated as arrays completely describing a model. Always access using indexing from the model's faces member.

The structure should remain valid while it is referenced by any model. If constructed by BrModelAllocate()239 it will be destroyed when the model it was constructed with is destroyed (or upon BrModelUpdate()237 if BR_MODF_KEEP_ORIGINAL had not been set beforehand).

Initialisation

If not constructed by BrModelAllocate()239, ensure the structure is first zeroed, e.g using memset(...,0,sizeof(br_face)). Set the members appropriately. Models that refer to such faces must have the flag BR_MODF_KEEP_ORIGINAL set. Models referring to initialised faces must be updated before they are involved in rendering.

Construction & Destruction

If this structure is constructed by BrModelAllocate()239 (or indirectly by BrModelLoad()243) it will be destroyed with the model (or upon BrModelUpdate()237 if BR_MODF_KEEP_ORIGINAL had not been set beforehand). It may be constructed (and appropriately destroyed) any other way (as long as BR_MODF_KEEP_ORIGINAL is set in the model).

Supplementary

When constructed by BrModelAllocate()239 faces are allocated from the "FACES" memory class. It is probably better to organise any enumeration around models (see br_model228).

Import & Export

Faces can be imported and exported with models.

Generated with CERN WebMaker