br_order_table
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
typedef
order.h
for precise declaration and ordering)
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
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
BrZsActorOrderTableSet()
87
, BrZsActorOrderTableGet()
88
.
BrZsPrimitiveCallbackSet()
39
, BrZsPrimitiveBucketSelect()
309
.
br_primitive
305
, br_primitive_cbfn
307
.
Members
Parameters
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 [br_scalar min_z, max_z
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
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.
br_uint_16 size
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
br_uint_32 flags
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).
br_primitive ** table
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
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
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.
Non- Operations
Description:
Insert a rendering primitive into an order table.BrZsOrderTablePrimitiveInsert()
void BrZsOrderTablePrimitiveInsert(br_order_table* order_table, br_primitive* primitive, br_uint_16 bucket)
br_order_table * order_table
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.
A pointer to the order table to be used as the primary order table. If
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.BrZsOrderTablePrimaryEnable()
void BrZsOrderTablePrimaryEnable(br_order_table* order_table)
br_order_table * order_table
Null
is supplied, the default order table will be used.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
.
Description:
Disable the use of a primary order table. Note that the primary order table is disabled by default.BrZsOrderTablePrimaryDisable()
void BrZsOrderTablePrimaryDisable()
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
.
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.
A non-
Description:
Clear an order table, re-initialising its table of pointers to primitives.BrZsOrderTableClear()
void BrZsClearOrderTable(br_order_table* order_table)
br_order_table * order_table
Null
pointer to the order table to be cleared.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
.
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
Number of buckets in order table (See br_uint_16 size, page 261).
Order table flags (See br_uint_32 flags, page 262).
Order table type (See br_uint_16 type, page 262).
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
Description:
Allocate a new order table.BrZsOrderTableAllocate()
br_order_table* BrZsOrderTableAllocate(br_uint_16 size, br_uint_32 flags, br_uint_16 type)
br_uint_16 size
br_uint_32 flags
br_uint_16 type
BrZsBegin()
28 &
BrZsEnd()
40
Memory can be allocated.
Effects: A
br_order_table
260
data structure is allocated (using BrResAllocate()
48
, from the BR_MEMORY_RENDER_DATA
memory class) and initialised (See br_order_table
260
, Initialisation). The z range and sort z are initialised to zero.Result:
br_order_table *
A pointer to the new br_order_table
260 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
A non-
Description:
Free an order table.BrZsOrderTableFree()
void BrZsOrderTableFree(br_order_table* order_table)
br_order_table * order_table
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
.