The Call-Back Function

This type defines a call-back function, which can be specified by using the function BrZsPrimitiveCallbackSet()39. It is called for each primitive generated from a model actor in the actor hierarchies supplied to BrZsSceneRender()34 and BrZsSceneRenderAdd()37 (it may also be called by BrZsModelRender()249). It enables an application to perform customised insertion of primitives into order tables, or to perform computations that require information only obtainable just after a primitive has been generated by the rendering engine.

The `typedef`

(See zsproto.h for a precise declaration)

void br_primitive_cbfn(br_primitive*, br_actor*, const br_model*, const br_material*, br_order_table*, const br_scalar*) Primitive call-back

Related Functions

For details of how to specify that a primitive call-back function should be called during rendering see BrZsPrimitiveCallbackSet()39.

Functions dedicated for use within primitive call-backs: BrZsOrderTablePrimitiveInsert()263, BrZsPrimitiveBucketSelect()309, BrOnScreenCheck()250, BrOriginToScreenXY()251, BrPointToScreenXY()251, BrPointToScreenXYMany()251, BrOriginToScreenXYZO()252, BrPointToScreenXYZO()252, BrPointToScreenXYZOMany()253.

Related Structures

See br_primitive305 for details of the primitive data structure. See br_model_custom_cbfn247 for a substitute custom model rendering call-back. See br_order_table260 for details of inserting primitives into order tables.

Specification

`CBFnPrimitive()`

Description:

An application defined call-back function that is called at some point during rendering - at precisely what point is undefined, and whether its children have been processed is also undefined. The pass through equivalent for this call-back is described in the example. The function may call any non-rendering functions available to a model's custom call-back function - see br_model_custom_cbfn247.

Declaration:

void BR_CALLBACK CBFnPrimitive(br_primitive* primitive, br_actor* actor, const br_model* model, const br_material* material, br_order_table* order_table, const br_scalar* z)

Arguments:

br_primitive * primitive

Primitive to be inserted in order_table.

br_actor * actor

Pointer to model actor referencing the model from which the primitive was generated.

const br_model * model

Pointer to the model from which the primitive was generated.

const br_material * material

Pointer to actor's material if defined, or default material otherwise.

br_order_table * order_table

Order table into which the primitive was about to be inserted.

const br_scalar * z

Non-Null pointer to one or more depth values of the primitive's vertices ([hither_z, yon_z] in camera co-ordinate space (linearly) mapped to [hither_z,+yon_z]). The number of values pointer to can be determined from the type member of primitive.

Preconditions:

BRender has completed initialisation. Rendering is in progress (by the Z-Sort renderer). The rendering engine has generated a primitive that faces the viewer.

Effects:

Behaviour is up to the application. Any of the operations described for br_model_custom_cbfn247 can be used apart from Br[Zb|Zs]ModelRender()249|249.

Remarks:

Any other BRender functions may be called from within this call-back with the following restrictions:

Don't call any rendering functions, e.g. BrZsSceneRenderAdd()37.
Don't modify any light, clip-plane or camera actors.
Do not access output buffer until rendering has completed.
Don't change the environment actor.
For best performance, avoid adding, updating or removing registry items - try to do these things before rendering.
Do not modify the actor hierarchy.

Example:

The following code demonstrates a primitive call-back function that performs the equivalent of BRender's normal primitive insertion, and so can be used for collection of statistics, say.


void BR_CALLBACK CBFnPrimitive(br_primitive* primitive, br_actor* actor, const br_model* model, const br_material* material, br_order_table* order_table, const br_scalar* z)
{
	BrZsOrderTablePrimitiveInsert
	(	order_table
	,	primitive
	,	BrZsPrimitiveBucketSelect
		(	z
			primitive->type
			order_table->min_z
			order_table->max_z
			order_table->size
			order_table->type
		)
	)
	...
	/* Collect statistics here */
	...
}

Operations

The following functions are provided solely for appropriate use within CBFnModelCustom()247, CBFnRenderBounds()307 and CBFnPrimitive()307 functions (see br_model_custom_cbfn247).

`BrZsPrimitiveBucketSelect()`

Description:

Determine into which bucket a primitive would be placed given a particular sorting method.

Declaration:

br_uint_16 BrZsPrimitiveBucketSelect(const br_scalar* z, br_uint_16 pr_type, br_scalar min_z, br_scalar max_z, br_uint_16 ot_size, br_uint_16 ot_type)

Arguments:

const br_scalar * z

A non-Null pointer to the z values corresponding to each vertex. This should point to as many values as are indicated by the primitive type pr_type.

br_int_16 pr_type

The primitive type (see br_primitive305).

br_scalar min_z, max_z

Depth range of buckets (use BrZsScreenZToDepth()32 if wishing to work with screen ordinates).

br_uint_16 ot_size

Number of buckets (see br_order_table260).

br_uint_16 ot_type

How the bucket should be determined (see br_order_table260).

Result:

br_uint_16

The index of the bucket as would be passed to BrZsOrderTablePrimitiveInsert()263.

Remarks:

Although the calculation performed by this function is trivial, it is provided to allow applications to ensure that the same bucket selection occurs in primitive call-back functions as would occur otherwise.

Generated with CERN WebMaker

br_primitive_cbfn

The Call-Back Function

The typedef