BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_model_custom_cbfn
Next|Prev|Up
The Call-Back Function
Specification
CBFnModelCustom()
Operations
BrZbModelRender()
BrZsModelRender()
BrOnScreenCheck()
BrOriginToScreenXY()
BrPointToScreenXY()
BrPointToScreenXYMany()
BrOriginToScreenXYZO()
BrPointToScreenXYZO()
BrPointToScreenXYZOMany()

br_model_custom_cbfn


The Call-Back Function

This type defines a call-back function, primarily intended for the custom member of the br_model
228 structure. It enables an application to customise rendering for particular models, or to perform computations that require information only obtainable at the time a model is rendered.

The typedef

(See model.h for a precise declaration)

void br_model_custom_cbfn(br_actor*, br_model*, const br_material*, void*, br_uint_8, int, const br_matrix34*, const br_matrix4*) Custom model renderer

Related Functions

Functions dedicated for use within rendering call-backs: Br[Zb|Zs]ModelRender()249|249, BrOnScreenCheck()250, BrOriginToScreenXY()251, BrPointToScreenXY()251, BrPointToScreenXYMany()251, BrOriginToScreenXYZO()252, BrPointToScreenXYZO()252, BrPointToScreenXYZOMany()253.

Related Structures

See br_renderbounds_cbfn307 for a post-model rendering call-back. See br_primitive_cbfn307 for a primitive insertion call-back used within the Z-Sort renderer.

Specification


CBFnModelCustom()

Description:
An application defined call-back function that is called when a model (whose custom member defined as the address of this function) is about to be processed by the rendering engine. If this function does nothing, the model will not be rendered. The pass through equivalent would be for this function to call Br[Zb|Zs]ModelRender()
249|249.

Declaration:
void BR_CALLBACK CBFnModelCustom(br_actor* actor, br_model* model, const br_material* material, void* render_data, br_uint_8 style, int on_screen, const br_matrix34* model_to_view, const br_matrix4* model_to_screen)

Arguments:
br_actor * actor

Pointer to model actor referencing the model referring to this call-back.

br_model * model

Pointer to model referring to this call-back.

const br_material * material

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

void * render_data

A pointer to the order table the primitives for this model would be inserted into, if the Z-Sort renderer is used. The value is Null if no data is appropriate for the renderer, e.g. when using the Z-Buffer renderer.

br_uint_8 style

Actor's rendering style, or default. BRender will not supply BR_RSTYLE_DEFAULT or BR_RSTYLE_NONE.

int on_screen

On-screen flag (see BrOnScreenCheck()250). The call-back will never be called by BRender with the flag value OSC_REJECT.

const br_matrix34 * model_to_view

A pointer to a matrix giving the model to view space transformation.

const br_matrix4 * model_to_screen

A pointer to a matrix giving the model to screen transformation.

Preconditions:
BRender has completed initialisation. Rendering is in progress. The model's bounds intersect or are within the viewing volume.

Effects:
Behaviour is up to the application. Br[Zb|Zs]ModelRender()
249|249 or any of the operations described for br_model_custom_cbfn247 can be used.

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

Example:
Possible uses include:

See Also:
br_renderbounds_cbfn307, br_primitive_cbfn307, br_pick2d_cbfn268, br_pick3d_cbfn270.


Operations

The following functions are provided solely for use within CBFnModelCustom()
247, CBFnRenderBounds()307, and CBFnPrimitive()307 functions. Br[Zb|Zs]ModelRender()249|249 is the equivalent of the function that would have been called had the model not specified a call-back (but it shouldn't be specified as the call-back itself). Br[Zb|Zs]ModelRender()249|249 should not be called within CBFnRenderBounds()307 or CBFnPrimitive()307.


BrZbModelRender()

Description:
Render a model actor as part of the current Z-Buffer rendering.

Declaration:
void BrZbModelRender(br_actor* actor, br_model* model, const br_material* material, br_uint_8 style, int on_screen, int use_custom)

Arguments:
br_actor * actor

The pointer to the model actor referencing the supplied model (must not be Null).

br_model * model

The pointer to the model to be rendered (must not be Null).

const br_material * material

A pointer to the material to use for rendering faces that don't specify a material (must not be Null).

br_uint_8 style

The rendering style to use for rendering the model (any defined style may be specified, even BR_RSTYLE_NONE).

int on_screen

A flag specifying whether the model is either partially or completely on-screen (either OSC_PARTIAL or OSC_ACCEPT). If OSC_ACCEPT is specified, even off-screen faces will be rendered. See BrOnScreenCheck()249.

int use_custom

If non-zero, invoke the specified model's custom call-back function. This is typically zero if the same model is specified.


BrZsModelRender()

Description:
Render a model actor as part of the current Z-Sort rendering.

Declaration:
void BrZsModelRender(br_actor* actor, br_model* model, const br_material* material, br_order_table* order_table, br_uint_8 style, int on_screen, int use_custom)

Arguments:
br_actor * actor

The pointer to the model actor referencing the supplied model (must not be Null).

br_model * model

The pointer to the model to be rendered (must not be Null).

const br_material * material

A pointer to the material to use for rendering faces that don't specify a material (must not be Null).

br_order_table * order_table

A pointer to the order table the model's primitives should be inserted into (must not be Null).

br_uint_8 style

The rendering style to use for rendering the model (any defined style may be specified, even BR_RSTYLE_NONE).

int on_screen

A flag specifying whether the model is either partially or completely on-screen (either OSC_PARTIAL or OSC_ACCEPT). If OSC_ACCEPT is specified, even off-screen faces will be rendered. See BrOnScreenCheck()249.

int use_custom

If non-zero, invoke the specified model's custom call-back function. This is typically zero if the same model is specified.


BrOnScreenCheck()

Description:
Check a bounding box in the model space against the view volume and any clip-planes.

Declaration:
br_uint_8 BrOnScreenCheck(const br_bounds* bounds)

Arguments:
const br_bounds * bounds

A pointer to a br_bounds105 structure giving the bounding box dimensions in the model's co-ordinate space.

Result:
br_uint_8

Returns one of the following:


BrOriginToScreenXY()

Description:
Transform and project the origin in the model's co-ordinate space onto the screen.

Declaration:
br_uint_8 BrOriginToScreenXY(br_vector2* screen)

Arguments:
br_vector2 * screen

A pointer to the destination vector to receive the co-ordinates of the point in projected screen space (See Projected screen space, page 22). Note that the point is not necessarily on screen, i.e. inside the bounds of the output pixel map.

Result:
br_uint_8

Returns zero if the point is in front of the eye (the viewing pyramid).


BrPointToScreenXY()

Description:
Transform and project a single point in the model's co-ordinate space onto the screen.

Declaration:
br_uint_8 BrPointToScreenXY(br_vector2* screen, const br_vector3* point)

Arguments:
br_vector2 * screen

A pointer to the destination vector to receive the co-ordinates of the point in projected screen space (See Projected screen space, page 22). Note that the point is not necessarily on screen, i.e. inside the bounds of the output pixel map.

const br_vector3 * point

A pointer to the source vector containing the co-ordinates of the point to project.

Result:
br_uint_8

Returns zero if the point is in front of the eye (the viewing pyramid).


BrPointToScreenXYMany()

Description:
Transform and project a number of points in the model's co-ordinate system onto the screen.

Declaration:
void BrPointToScreenXYMany(br_vector2* screens, const br_vector3* points, br_uint_32 npoints)

Arguments:
br_vector2 * screens

A pointer to an array of destination vectors to receive the co-ordinates of each point in projected screen space (See Projected screen space, page 22). Note that the points are not necessarily on screen, i.e. inside the bounds of the output pixel map.

const br_vector3 * points

A pointer to an array of source vectors containing co-ordinates of points in model space.

br_uint_32 npoints

Number of points to process.

Effects:
Equivalent to a call of BrPointToScreenXY()251 for each screen and point vector.


BrOriginToScreenXYZO()

Description:
Transform and project the origin in the model's co-ordinate space onto the screen, generating x, y and z co-ordinates. If it is off-screen, it is not projected.

Declaration:
br_uint_32 BrOriginToScreenXYZO(br_vector3* screen)

Arguments:
br_vector3 * screen

A pointer to the destination vector to receive the co-ordinates of the point in projected screen space (See Projected screen space, page 22).

Effects:
The origin is checked against the viewing volume. If within, the equivalent screen and depth buffer co-ordinates are calculated, otherwise the function has no effect.

Result:
br_uint_32

If the co-ordinates have been placed in the destination vector the function returns zero, otherwise the origin is off-screen, in which case its out-code, made up from a combination of the flags in the following table is returned.


BrPointToScreenXYZO()

Description:
Transform and project a point in the model's co-ordinate space onto the screen, generating x, y and z co-ordinates. If it is off-screen, it is not projected.

Declaration:
br_uint_32 BrPointToScreenXYZO(br_vector3* screen, const br_vector3* point)

Arguments:
br_vector3 * screen

A pointer to the destination vector to receive the co-ordinates of the point in projected screen space (See Projected screen space, page 22).

const br_vector3 * point

A pointer to the source vector.

Effects:
The point is checked against the viewing volume. If within, the equivalent screen and depth buffer co-ordinates are calculated, otherwise the function has no effect.

Result:
br_uint_32

If the co-ordinates have been placed in the destination vector the function returns zero, otherwise the point is off-screen, in which case its out-code, made up from a combination of the flags in the following table is returned.

See Also:
BrOriginToScreenXYZO()252


BrPointToScreenXYZOMany()

Description:
Transform and project a number of points in the model's co-ordinate space onto the screen, generating a series x, y and z co-ordinates and out-codes. All those that are off-screen are not projected.

Declaration:
void BrPointToScreenXYZOMany(br_vector3* screens, br_uint_32* outcodes, const br_vector3* points, br_uint_32 npoints)

Arguments:
br_vector3 * screens

A pointer to a list of destination vectors, each of which will receive co-ordinates of each point in projected screen space (See Projected screen space, page 22).

br_uint_32 * outcodes

A pointer to an array of out-codes for each point. If the co-ordinates have been placed in the corresponding destination vector the out-code will be zero, otherwise the point is off-screen, in which case only its out-code (see BrPointToScreenXYZO()252) is stored.

const br_vector3 * points

A pointer to an array of source vectors containing the points to be projected.

br_uint32 npoints

Number of points.

Effects:
Equivalent to a call of BrPointToScreenXYZO()252 for each point. Only co-ordinates of points in the viewing volume are written to corresponding elements of screens.

See Also:
BrOriginToScreenXYZO()252



Generated with CERN WebMaker