BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_order_table
Next|Prev|Up
The Structure
Members
Operations
BrZsOrderTablePrimitiveInsert()
BrZsOrderTablePrimaryEnable()
BrZsOrderTablePrimaryDisable()
Copy/Assign
Access & Maintenance
BrZsOrderTableClear()
Referencing & Lifetime
Initialisation
Construction & Destruction
BrZsOrderTableAllocate()
BrZsOrderTableFree()

br_order_table


The Structure

This is an order table used by the Z-Sort renderer. It contains a table of pointers to linked lists of rendering primitives. The Z depth range of the order table is divided into a number of equal intervals (buckets). Each primitive generated by the Z-Sort renderer is inserted into the appropriate list so that it is eventually rendered in order of depth. It is the application developer's task to determine a scheme so that the scene is crudely segmented into layers of background through to foreground (with an order table for each layer), and any mutually depth critical faces are sorted in order. It does not matter in which order non-overlapping faces are drawn with respect to each other, so the trick is to sort only overlapping faces that need sorting, i.e. concave models, or interpenetrating models.

There is a facility of nominating a primary order table such that all other secondary order tables are rendered in between its buckets. This provides a quick and easy way of progressing to the next step, after having a single order table, i.e. a primary order table for static features and individual order tables for models.

Order tables are assigned to actors, either by default, inheritance or explicitly (see BrZsActorOrderTableSet()87).

The typedef

(See order.h for precise declaration and ordering)

Parameters

br_scalar min_z Minimum z depth of range

br_scalar max_z Maximum z depth of range

br_scalar sort_z Depth at which order table should be sorted

br_uint_16 size Number of buckets

br_uint_16 type Sort type

br_uint_32 flags Various flags

Internal

br_primitive ** table Order table array (of primitive linked-lists)

br_order_table * next Next order table

br_uint_16 visits Number of times order table has been referenced so far

Related Functions

Scene Modelling

BrZsActorOrderTableSet()87, BrZsActorOrderTableGet()88.

Scene Rendering

BrZsPrimitiveCallbackSet()39, BrZsPrimitiveBucketSelect()309.

Related Structures

Scene Rendering

br_primitive305, br_primitive_cbfn307.

Members

Parameters

br_scalar min_z, max_z

Range of z depths over which to sort. Any z depths of vertices outside this range will be clamped to the limits. Note that the z depth values are a result of a linear mapping from camera co-ordinate space, of the range [hither_z, yon_z] to the range [-hither_z, +yon_z]. These members are usually set by using the BR_ORDER_TABLE_NEW_BOUNDS or BR_ORDER_TABLE_INIT_BOUNDS flags, but can be set explicitly using the BrZsScreenZToDepth()32 functions. Note that BrOriginToScreenXYZO()252, BrPointToScreenXYZO()252 and BrPointToScreenXYZOMany()253 return projected screen z ordinates, not depths.

The z range (max_z-min_z) must be greater than 0.001, otherwise it will be forced to this range.

br_scalar sort_z

This member defines the value of z used to determine the position at which this order table is in the list of order tables. This value is typically set to min_z, and may be set explicitly or automatically at the same time as min_z and max_z. There are flags available which can be used to specify how sort_z is calculated.

Note that this member is not relevant to primary order tables.

br_uint_16 size

This member defines the number of intervals (buckets) that the z range is divided into. It also defines the number of pointers pointed to by table.

An order table used for a single opaque convex model need only have one bucket, whereas a complex model actor with several child models (within the z range of the parent) might need several intervals.

br_uint_16 type

How primitives are inserted into an order table, obviously depends upon their depth, but for primitives with more than one z value, such as lines, triangles and quads, how to arrive at a single z value is not a clear cut decision. Because it depends so much upon the scene and the application, it is left to the application to specify the way the sorting z should be obtained. The following table describes each type which can be specified in this member.

br_uint_32 flags

At some point the z range of each order table must be set appropriately. The z range is not only used to determine into which buckets each primitive should be placed, but also in which order the order tables should be rendered. If the application knows in advance what this range can be then the z range can be set before rendering begins (see BrZsScreenZToDepth()32), otherwise various flags can be used to get the z range to be calculated automatically. Note that an order table is used in descendant order, that is, actors nearer the root of the hierarchy will see the order table first. Once the hierarchy has been traversed, the order tables will be sorted according to the value of sort_z, which can be set according to the values of min_z and max_z. The order tables will be rendered furthest first (see also BrZsOrderTablePrimaryEnable()264).

The flags are described in the following table.

The first three flags are mutually exclusive, as are the last three. Any one of the first three may be combined with the fourth, and any one of the last three.

Bounds can be computed from the following actors: BR_ACTOR_MODEL, BR_ACTOR_BOUNDS and BR_ACTOR_BOUNDS_CORRECT.

Note that when an order table's bounds are calculated, they are always calculated from the full bounds of the model (or bounds data structure). Therefore, it is possible, where bounds intersect the boundaries of the viewing volume, for one of the order table bounds to lie outside the view space. All buckets are still rendered, but the buckets outside the view space will be empty (unless a custom primitive call-back has utilised them).

Internal

br_primitive ** table

A pointer to a list of heads of linked lists of primitives. Each linked list is effectively each bucket of the bucket sort (per order table). This member is for internal use only. Each pointer will be Null if the bucket is empty. Note that primitives are allocated from the primitive heap supplied at the start of rendering

br_order_table * next

Pointer to the next order table (next lowest min_z). Null at end of list. Each rendering, this list is constructed (before drawing), and then deconstructed (after drawing). This member should only be non-Null during rendering, i.e. within a rendering call-back function such as CBFnModelCustom()
247. This member is for internal use only.

br_uint_16 visits

This member is used to determine when to clear and initialise the order table's z range (if required). This member is set to zero upon allocation and after rendering, and incremented each time it is referenced by an actor traversed during rendering. When zero, the order table is cleared (and if BR_ORDER_TABLE_INIT_BOUNDS is set, its z range calculated) when it is next referenced by an actor traversed during rendering. This member is for internal use only.

Operations


BrZsOrderTablePrimitiveInsert()

Description:
Insert a rendering primitive into an order table.

Declaration:
void BrZsOrderTablePrimitiveInsert(br_order_table* order_table, br_primitive* primitive, br_uint_16 bucket)

Arguments:
br_order_table * order_table

Non-Null pointer to order table in which to insert primitive (supplied as argument to CBFnPrimitive()307).

br_primitive * primitive

Non-Null pointer to primitive to insert (supplied as argument to CBFnPrimitive()307).

br_uint_16 bucket

Bucket of order table in which to insert primitive (between 0 and order_table->size-1). See BrZsPrimitiveBucketSelect()309.

Preconditions:
Between BrZsSceneRenderBegin()35 & BrZsSceneRenderEnd()37. Within a primitive call-back function.

Effects:
The primitive is inserted into the order table in the specified bucket.

Remarks:
This function is only provided to customise the ordering of primitives in a particular order table. It is not intended to permit automatic generation of primitives.

Note that order tables are marked for clearing after rendering and allocation. Upon entry to a primitive call-back, the order table will have been cleared, and may already contain primitives. The state of other order tables is undefined.

See Also:
BrZsModelRender()249.


BrZsOrderTablePrimaryEnable()

Description:
Enable the use of a primary order table, between whose buckets all other order tables are then rendered. By default, no primary order table is enabled.

Declaration:
void BrZsOrderTablePrimaryEnable(br_order_table* order_table)

Arguments:
br_order_table * order_table

A pointer to the order table to be used as the primary order table. If Null is supplied, the default order table will be used.

Preconditions:
Between BrZsBegin()
28 & BrZsEnd()40.

Effects:
The Z sort renderer will use the specified order table as a primary order table, making other order tables secondary. All secondary order tables are rendered sequentially, as appropriate, between the rendering of the buckets of the primary order table. Secondary order tables whose sort_z lies further away than max_z are rendered first (in order of their sort_z). Then the furthest bucket of the primary order table is rendered, followed by the secondary order tables whose sort_z lies within that bucket (in order of their sort_z). This continues for each bucket of the primary order table. Finally, the secondary order tables whose sort_z is in front of the nearest bucket of the primary order table are rendered (in order of their sort_z).

Remarks:
Note that the primary order table facility only provides a relatively coarse way of merging the ordering of primitives (or buckets) in secondary order tables with those in the primary order table. Nevertheless, with a bit of care, it often gives satisfactory results for a wide range of scenes, with relatively straightforward allocation of order tables.

See Also:
BrZsOrderTablePrimaryDisable()
265.


BrZsOrderTablePrimaryDisable()

Description:
Disable the use of a primary order table. Note that the primary order table is disabled by default.

Declaration:
void BrZsOrderTablePrimaryDisable()

Preconditions:
Between BrZsBegin()
28 & BrZsEnd()40.

Effects:
Order tables are rendered sequentially in order of their sort_z.

Remarks:
The simpler Z sort algorithm that this function engages, generally requires a deal of care and effort to ensure correct rendering order, especially in complex scenes. The results generally produce a more reliable ordering than with a primary order table, as so much more care is needed.

See Also:
BrZsOrderTablePrimaryEnable()264.


Copy/Assign

Structure assignment is not recommended. Copy members as appropriate.

Access & Maintenance

Members should only be modified with care during rendering. Do not modify primitives via table, or the linked list of order tables via next. Order tables are automatically cleared at the start of each rendering, but can be cleared thereafter (if required) using BrZsOrderTableClear()265.


BrZsOrderTableClear()

Description:
Clear an order table, re-initialising its table of pointers to primitives.

Declaration:
void BrZsClearOrderTable(br_order_table* order_table)

Arguments:
br_order_table * order_table

A non-Null pointer to the order table to be cleared.

Preconditions:
Between BrZsBegin()
28 & BrZsEnd()40.

Effects:
The series of void pointers pointed to by table are reset to Null. Some private flags may be modified.

Remarks:
Note that order tables are marked for clearing after rendering and allocation. Upon entry to a primitive call-back, the order table will have been cleared, and may already contain primitives. Given automatic clearing, the use of this function is not generally required.

See Also:
BrZsActorOrderTableGet()88.


Referencing & Lifetime

Order tables can be referred to any number of times by an actor (through use of BrZsActorOrderTableSet()
87). Order tables must be valid throughout rendering, i.e. between BrZsSceneRenderBegin()35 and BrZsSceneRenderEnd()37. Note that primitive data is re-used from the primitive heap (supplied to BrZsBegin()28) each rendering. Therefore, it is not possible to incorporate primitives from an order table generated in one scene into another scene.

There is a default order table which has 256 buckets and spans the depth of the view volume (its z range is set from the camera used for the rendering). It thus has just the flag BR_ORDER_TABLE_LEAVE_BOUNDS set. Do not attempt to modify the default order table - create your own.

Initialisation

Allocation performs most initialisation. The only remaining initialisation required is to set the z range (min_z and max_z) and the z sort position (sort_z), which only needs to be done if these member will not be set by using flags such as BR_ORDER_TABLE_NEW_BOUNDS and BR_ORDER_TABLE_INIT_BOUNDS.

Construction & Destruction

Order tables should be constructed using BrZsOrderTableAllocate()266 and destroyed using BrZsOrderTableFree()267.


BrZsOrderTableAllocate()

Description:
Allocate a new order table.

Declaration:
br_order_table* BrZsOrderTableAllocate(br_uint_16 size, br_uint_32 flags, br_uint_16 type)

Arguments:
br_uint_16 size

Number of buckets in order table (See br_uint_16 size, page 261).

br_uint_32 flags

Order table flags (See br_uint_32 flags, page 262).

br_uint_16 type

Order table type (See br_uint_16 type, page 262).

Preconditions:
Between BrZsBegin()28 & BrZsEnd()40.

Memory can be allocated.

Effects:
A br_order_table260 data structure is allocated (using BrResAllocate()48, from the BR_MEMORY_RENDER_DATA memory class) and initialised (See br_order_table260, Initialisation). The z range and sort z are initialised to zero.

Result:
br_order_table *

A pointer to the new br_order_table260 data structure.

Remarks:
Ensure min_z, max_z and sort_z are set appropriately if they will not be initialised automatically, i.e. if the BR_ORDER_TABLE_LEAVE_BOUNDS flag is set.

See Also:
BrZsOrderTableFree()
267


BrZsOrderTableFree()

Description:
Free an order table.

Declaration:
void BrZsOrderTableFree(br_order_table* order_table)

Arguments:
br_order_table * order_table

A non-Null pointer to an order table previously allocated using BrZsOrderTableAllocate()266.

Preconditions:
Between BrZsBegin()28 & BrZsEnd()40. Not currently rendering.

Effects:
Uses BrResFree()51 to release storage.

Remarks:
Ensure that no actor is currently using the order table before using this function. Do not attempt to free an active order table, such as is passed as an argument to a rendering call-back function, e.g. CBFnPrimitive()307.

See Also:
BrZsOrderTableAllocate()266, BrResFree()51.



Generated with CERN WebMaker