BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_actor
Next|Prev|Up
The Structure
Members
Operations
BrActorAdd()
BrActorRemove()
BrActorRelink()
BrActorToActorMatrix34()
BrActorToBounds()
BrScenePick3D()
BrActorToScreenMatrix4()
BrScenePick2D()
BrEnvironmentSet()
BrLightEnable()
BrLightDisable()
BrClipPlaneEnable()
BrClipPlaneDisable()
Copy/Assign
Access & Maintenance
BrZsActorOrderTableSet()
BrZsActorOrderTableGet()
Referencing & Lifetime
Initialisation
Construction & Destruction
BrActorAllocate()
BrActorFree()
Supplementary
BrActorEnum()
BrActorSearch()
BrActorSearchMany()
Import & Export
BrActorFileCount()
BrActorSave()
BrActorLoad()
BrActorSaveMany()
BrActorLoadMany()

br_actor


The Structure

The basic unit of scene construction. The br_actor
74 object is designed to facilitate hierarchical relationships between elements of a scene, particularly in terms of position and orientation.

See The Actor, page 12, in the structured description for further details.

The typedef

(See actor.h for precise declaration and ordering)

Hierarchical relationships

br_actor * parent Parent of this Actor

br_actor * next Next sibling of this Actor

br_actor ** prev Previous sibling of this Actor

br_actor * children Children of this Actor

br_uint_16 depth Depth of this Actor from root of hierarchy

Positional relationship

br_transform t Transform to convert to parent co-ordinates

Actor function

br_uint_8 type Actor type

void * type_data Extra, type specific data for this Actor

br_model * model Model data for model Actors

br_material * material Material data for model Actors

br_uint_8 render_style Rendering style for model Actors

Supplementary

char * identifier String to identify actor

void * user User data (application dependent)

Related Functions

Scene Rendering

See BrZbSceneRenderBegin()34, BrZbSceneRenderAdd()36, BrZbSceneRender()34, Br[Zb|Zs]ModelRender()249|249

Members

Hierarchical Relationships



Diagram showing linked list of sibling actors for three children of a root.

br_actor * parent

A pointer to the actor's parent actor in an actor hierarchy. If the actor has no parent, i.e. is the root actor of its hierarchy, parent is Null.

br_actor * next

A pointer to the next sibling actor in the linked list of sibling actors (parent's children). If the actor has no siblings or is the last sibling actor, next is Null.

br_actor ** prev

A pointer to the previous sibling actor's next member in the linked list of sibling actors (parent's children). If the first sibling, prev will point to its parent actor's children member. If the root actor, prev is Null. Given that the next member is the first member of br_actor74, prev can be cast to a pointer to the previous actor (where prev points to a next member).

br_actor * children

A pointer to the first actor in a linked list of child actors. If the actor has no children, children is Null.

br_uint_16 depth

The depth of the actor from the root of the hierarchy. depth is zero for the root actor and increases by one each generation (indirection through children).

Common Features of next, prev, children, depth

These members are maintained by BRender, and only ever changed during hierarchy construction (See BrActorAdd()
80, BrActorRemove()81, BrActorRelink()81). Although they should never be directly modified, direct use for traversal purposes is permitted.

Positional Relationship

br_transform t

This defines the transform to apply to co-ordinates of this actor (e.g. of models), to convert them to co-ordinates in its parent's co-ordinate system. This is the primary way of defining relative model positions and orientations. Any valid transform may be used.

This member is read when rendering and computing actor/actor transforms. It can be modified at any time, although it should be appreciated that this may have unpredictable effects if done during render call-back functions.

See BrActorToActorMatrix34()82 for information on obtaining transforms between actors other than parent and child.

Example

Remember that each actor can be considered to have its own (right handed) co-ordinate system. Consider a point (1,2,3), of a model vertex say. Let's suppose the actor has a transform that just translates by a vector of (1,0,0). In applying this transform we obtain the point (2,2,3), and these are now co-ordinates in the parent's co-ordinate's system. Now let's suppose the actor has a transform that also rotates by 90xbc about the x-axis (+y topples toward us, +z) and is then followed by the translation of (1,0,0). If we applied this transform we'd obtain the point (2,-3,2).

If you wished to perform this using BRender functions, you might first use BrTransformToMatrix34()343, and then BrMatrix34ApplyP()191.

Actor Function

br_uint_8 type

This member defines the type of function required of this actor. The actor's type should contain a value defined by one of the symbols described in the following table.



Although set at initialisation, this member can be changed outside rendering at any time (as long as the other members are set appropriately, and, if a Light or Clip Plane, it has first been disabled (See BrLightDisable()86 and BrClipPlaneDisable()86)). During rendering (within call-back functions) change is not recommended - Actors should not be changed to or from Lights or Clip Planes, and the particular Camera supplied for the rendering should not have its type changed.

void * type_data

This member is used to refer to additional, type specific data. It should point to data according to the contents of type as shown in the following table:

The type_data member should not be Null except for BR_ACTOR_NONE or BR_ACTOR_MODEL.

This member can be changed at any time, though not recommended during rendering.

Experienced C programmers will be familiar with the technique of supplying pointers to structures that are actually embodied within others, for the purpose of accessing attached application specific data*1. This technique is still a workable way of extending the amount of data within BRender data structures, particularly here*2. For example, it may be desired to introduce rotating lights. The corresponding details could be appended to the br_light145 structure as demonstrated in this example:


typedef struct				/* My light, which can be used instead of br_light */
{	br_light light;			/* The standard BRender light specification */
	unsigned type;			/* My extended light type */
	br_scalar speed;			/* Various properties */
	br_vector3 axis;
} my_light;

br_model * model

The model defines the geometry and any specific face characteristics to be rendered in this actor's co-ordinate space.

This member points to model information, which is used by this actor if it is a model actor, and descendent model actors that inherit it. If Null, model information is obtained (when required by a model actor) from the previous ancestor (parent) that supplied it. If no ancestor supplies it, a default br_model228 data structure is used which defines a cube (this is for diagnostic purposes only).

Note that an actor does not have to be a model actor in order for it to define a model to be inherited by a descendent model actor.

br_material * material

The material is used for a model's faces that don't specify a material.

This member points to material information, which is used by this actor if it is a model actor, and descendent model actors that inherit it. If Null, material information is obtained (when required by a model actor) from the previous ancestor (parent) that supplied it. If no ancestor supplies it, a default br_material151 data structure is used which defines a flat-shaded grey (this is for diagnostic purposes only). Out of interest, it is currently defined as follows:*3


{	"default",
	BR_COLOUR_RGB(255,255,255),					/* colour */
	255,					/* opacity */
	BR_UFRACTION(0.10),					/* Indexed ka */
	BR_UFRACTION(0.70),					/* kd */
	BR_UFRACTION(0.0),					/* ks */
	BR_SCALAR(20),					/* power */
	BR_MATF_LIGHT,					/* flags */
	{{	BR_VECTOR2(1,0),				/* map transform */
		BR_VECTOR2(0,1),
		BR_VECTOR2(0,0),
	}},
	0,63,					/* index base/range	*/
};

Note that an actor does not have to be a model actor in order for it to define a material to be inherited by a descendent model actor.

br_uint_8 render_style

This member determines the style of rendering, which is used by this actor if it is a model actor. If the Null style (BR_RSTYLE_DEFAULT) is specified, the rendering style is obtained (when required by a model actor) from the first ancestor (from the root) that defines a non-Null style. If no ancestor defines one, the model is rendered as though BR_RSTYLE_FACES had been specified.

This is subtly different from normal inheritance, in that non-default styles set by intervening actors have no effect. It is designed this way to facilitate the use of an attribute primarily intended for highlighting (obviously not one concerned with realism).

The render_style member should be set to a value defined by one of the following (enum) symbols:

Supplementary

char * identifier

Pointer to unique, zero terminated, character string (or Null if not required). Can be used as a handle to retrieve a pointer to the actor, given only an ancestral actor. Not intended for intensive use. Typically used to collect pointers to actors loaded using BrActorLoad()95 and BrActorLoadMany()96. Also ideal for diagnostic purposes.

A non-unique string can be supplied, but which of a set of actors having the same string will be matched by search functions (See BrActorSearch()91), is undefined. Also in consideration of searching, it is not recommended that non-alphabetic characters are used, especially Slash
(`/'), Asterisk (`*'), and Query (`?'), which are used for pattern matching.

This member can be modified by the programmer at any time.

If identifier is set by BrActorLoad()95 or BrActorLoadMany()96 it will have been constructed using BrResStrDup()49.

void* user

This member may be used by the application for its own purposes. It is initialised to Null upon allocation, and not accessed by BRender thereafter.

Operations

Hierarchical Relationships


BrActorAdd()

Description:
Add an actor hierarchy as a child of a given parent.

Declaration:
br_actor* BrActorAdd(br_actor* parent, br_actor* a)

Arguments:
br_actor * parent

A non-Null pointer to the parental actor.

br_actor * a

A non-Null pointer to its new child.

Preconditions:
Between BrBegin()
10 & BrEnd()11. New child must be root of its hierarchy, i.e. must not still be child of another parent.

Effects:
Parent's children member may be modified. Added hierarchy will be linked into linked list of parent's children. Members next and prev of some of parent's children and of added hierarchy will be modified. The parent member of the added hierarchy will be modified. All depth members of added hierarchy will be updated.

Result:
br_actor *

The new child pointer a is returned as supplied (for convenience).

Remarks:
Do not attempt to add an actor at more than one place in a hierarchy at a time - BRender currently only supports simple hierarchical actor structures, not directed acyclic (or cyclic) graph structures. Note that in spite of this restriction, models on the other hand, may be simultaneously referred to by any number of actors.

See Also:
BrActorRemove()81, BrActorRelink()81


BrActorRemove()

Description:
Remove an actor hierarchy from its parent.

Declaration:
br_actor* BrActorRemove(br_actor* a)

Arguments:
br_actor * a

A non-Null pointer to the hierarchy to remove.

Preconditions:
Between BrBegin()
10 & BrEnd()11. Actor to remove must be a child.

Effects:
Parent's children member may be modified. Removed hierarchy will be unlinked from linked list of parent's children. Members next and prev of some of parent's children and of removed hierarchy will be modified. The parent member of the removed hierarchy will be modified. All depth members of removed hierarchy will be updated.

Result:
br_actor *

The pointer to the removed hierarchy is returned as supplied (for convenience).

Remarks:
Note that a Light or Clip plane actor must be disabled before it is removed.

See Also:
BrActorAdd()80, BrActorRelink()81


BrActorRelink()

Description:
Move an actor in a hierarchy, but preserve its apparent world transformation by manipulating its own transformation as necessary.

Declaration:
void BrActorRelink(br_actor* parent, br_actor* a)

Arguments:
br_actor * parent

A non-Null pointer to the new parent.

br_actor * a

A non-Null pointer to the actor to move.

Preconditions:
Between BrBegin()
10 & BrEnd()11. Both supplied actors are in the same hierarchy.

Effects:
Equivalent to a call of BrActorRemove(a)81 followed by BrActorAdd(parent,a)80, except that the moved actor's transform is modified to reproduce the effects of the original transform.

Remarsk:
Note that a light or clip plane actor must be disabled before it is relinked.

See Also:
BrActorAdd()80, BrActorRemove()81


Positional Relationship


BrActorToActorMatrix34()

Description:
Accumulate the transformations between one actor and another, representing the result as a matrix.

Declaration:
br_uint_8 BrActorToActorMatrix34(br_matrix34* m, const br_actor* a, const br_actor* b)

Arguments:
br_matrix34 * m

A non-Null pointer to the destination matrix, into which will be placed the transform.

const br_actor * a

A non-Null pointer to the actor from whose co-ordinate space co-ordinates are to be transformed.

const br_actor * b

A non-Null pointer to the actor into whose co-ordinate space co-ordinates are to be transformed.

Preconditions:
Between BrBegin()
10 & BrEnd()11. Both actors must be in the same hierarchy.

Effects:
Will calculate the transform required to transform co-ordinates in the co-ordinate space of a, into the co-ordinate space of b.

Result:
br_uint_8

The type of the accumulated transformation, e.g. BR_TRANSFORM_MATRIX34 (see br_transform339).


BrActorToBounds()

Description:
Compute an actor hierarchy's bounding box, encompassing the bounding box of all models (including descendants).

Declaration:
br_bounds* BrActorToBounds(br_bounds* b, const br_actor* ap)

Arguments:
br_bounds * b

Non-Null pointer to resulting bounding box.

const br_actor * ap

Non-Null pointer to actor whose bounding box is required.

Preconditions:
Between BrBegin()
10 & BrEnd()11.

Effects:
Obtains smallest bounding box (in this actor's co-ordinate space) that will contain any model or descendant model.

Result:
br_bounds *

The bounding box result pointer b is returned as supplied (for convenience).

Remarks:
The default model is used in cases where a model actor would inherit from an ancestor of the supplied actor.

See Also:
BrBoundsToMatrix34()106, BrScenePick3D()81, br_bounds105, br_model228.


BrScenePick3D()

Description:
Traverse an actor hierarchy and invoke a call-back function for each model actor whose bounds intersect a given bounds in a given reference actor's space. If the call-back returns a non-zero value, traversal halts.

Declaration:
int BrScenePick3D(br_actor* world, const br_actor* reference, const br_bounds* bounds, br_pick3d_cbfn* callback, void* arg)

Arguments:
br_actor * world

A pointer to the root of a world hierarchy.

const br_actor * reference

A pointer to the reference actor.

const br_bounds * bounds

A pointer to a bounds structure.

br_pick3d_cbfn * callback

A pointer to a pick-3D call-back function.

void * arg

An optional argument to pass to the call-back function.

Result:
int

If the call-back returns a non-zero value and traversal halts, that value is returned.

Otherwise, zero is returned.

See Also:
BrScenePick2D()
84


BrActorToScreenMatrix4()

Description:
Accumulate the transformations between an actor and the screen, representing the result as a matrix.

Declaration:
void BrActorToScreenMatrix4(br_matrix4* m, const br_actor* a, const br_actor* camera)

Arguments:
br_matrix4 * m

A non-Null pointer to the destination matrix to receive the transform between homogenous co-ordinates in the actor's co-ordinate space into the homogenous screen space.

const br_actor * a

A non-Null pointer to an actor.

const br_actor * camera

A non-Null pointer to a camera actor.

Remarks:
The function BrMatrix4ApplyP()
216 is typically used with this function to convert co-ordinates in an actor's co-ordinate space into homogenous screen space (assuming a centred projection). Note though that the resultant 4-vector is a set of homogenous co-ordinates and thus the x, y and z values will need to be divided by the w component.

See Homogenous screen space, page 22.

See Also:
BrMatrix4Perspective()225.


BrScenePick2D()

Description:
Traverse a world hierarchy, picking model actors from the scene by casting a ray through a given viewport pixel attached to a given camera. A call-back is invoked for each actor whose bounds intersect the ray. If the call-back returns a non-zero value, traversal halts.

Declaration:
int BrScenePick2D(br_actor* world, const br_actor* camera, const br_pixelmap* viewport, int pick_x, int pick_y, br_pick2d_cbfn* callback, void* arg)

Arguments:
br_actor * world

A pointer to the root of a world hierarchy.

const br_actor * camera

A pointer to a camera actor.

const br_pixelmap * viewport

A pointer to the viewport through which the pick ray passes.

int pick_x, pick_y

Co-ordinates of viewport pixel through which the pick ray passes.

br_pick2d_cbfn * callback

A pointer to a pick-2D call-back function.

void * arg

An optional argument to pass to the call-back function.

Result:
int

If the call-back returns a non-zero value and traversal halts, that value is returned. Otherwise, zero is returned.

See Also:
BrScenePick3D()
82, BrModelPick2D()231


Actor Function


BrEnvironmentSet()

Description:
This function is relevant to model actors using environment mapping (set in their materials' flags member by using
BR_MATF_ENVIRONMENT_I or BR_MATF_ENVIRONMENT_L).

It set a new environment anchor for such model actors. By default, the reflective effect produced by an environment map on the surface of a model appears to rotate with the model itself. If this is unsatisfactory, the map can be anchored to an actor. If the actor is the root of a world hierarchy, then reflection effects will appear more realistic.

Declaration:
br_actor* BrEnvironmentSet(br_actor* a)

Arguments:
br_actor * a

A pointer to an actor to which all environment maps should be anchored. If Null, environment maps are not anchored, but rotate with models.

Result:
br_actor *

Returns a pointer to the old environment anchor.

Remarks:
Environment actors must be part of the rendered scene (a descendant of the effective root). If rendering a scene to produce a reflection environment map in another scene, then (unless the reflected scene also involves environment maps) the function should be called with Null before the reflected scene is rendered, and then called with an appropriate anchor actor (that is part of the latter scene, in which the environment map is used).


BrLightEnable()

Description:
Enable a light actor's effect as a light source within the scene. Light actors only affect the lighting of a scene if they are in the enabled state before rendering.

Declaration:
void BrLightEnable(br_actor* l)

Arguments:
br_actor * l

A non-Null pointer to a light actor.

Remarks:
By default, light actors are disabled.

Light actors must be in the disabled state before they are removed from, relinked within, or added to a hierarchy. They must also be disabled before they are freed (or a parent is).

For optimum performance, disable all lights known to have insignificant effect upon the scene. Some platforms are limited in the number simultaneously enabled lights that they can support.

See Also:
BrLightDisable()
86


BrLightDisable()

Description:
Disable a light actor's effect as a light source within the scene. Light actors only affect the lighting of a scene if they are in the enabled state before rendering.

Declaration:
void BrLightDisable(br_actor* l)

Arguments:
br_actor * l

A non-Null pointer to a light actor.

Remarks:
By default, light actors are disabled.

Light actors must be in the disabled state before they are removed from, relinked within, or added to a hierarchy. They must also be disabled before they are freed (or a parent is).

For optimum performance, disable all lights known to have insignificant effect upon the scene. Some platforms are limited in the number of simultaneously enabled lights that they can support.

See Also:
BrLightEnable()
85


BrClipPlaneEnable()

Description:
Enable a clip plane. Such clip plane actors affect the contents of a scene (as long as they are enabled before rendering).

Declaration:
void BrClipPlaneEnable(br_actor* cp)

Arguments:
br_actor * cp

A non-Null pointer to a clip plane actor.

Remarks:
By default, clip planes are disabled.

Clip planes must be in the disabled state before they are removed from, relinked within, or added to a hierarchy. They must also be disabled before they are freed (or a parent is).


BrClipPlaneDisable()

Description:
Disable a clip plane.

Declaration:
void BrClipPlaneDisable(br_actor* cp)

Arguments:
br_actor * cp

A non-Null pointer to a clip plane actor.

Remarks:
By default, clip planes are disabled.

Clip planes must be in the disabled state before they are removed from, relinked within, or added to a hierarchy. They must also be disabled before they are freed (or a parent is).


Copy/Assign

While it may be sensible to copy some members, it is generally not sensible to copy the actor as a whole.

Access & Maintenance

Given that the order in which a hierarchy is rendered is not defined, the benefits of modifying members during rendering are doubtful. The structure of the actor hierarchy should not be modified during rendering.

An actor may be indirectly accessed by BRender library functions if they are called while the actor is in a hierarchy that is thus modified or traversed (through rendering or otherwise). Consequently, particular care must be taken if modifying the actor while such indirect accesses may be taking place (especially within rendering call-back functions).

The only functions that indirectly modify an actor's public members are BrActorAdd()80, BrActorRemove()81, BrActorRelink()81 and BrActorFree()90, and these only affect some or all of the parent, next, prev, children and depth members.

If using the Z-Sort renderer it is likely that order tables will be need to be assigned to model actors on an individual basis. The following two functions are provided to specify and access an actor's order table.

No maintenance is required, except to ensure that members are valid. Hierarchical changes (Additions, Removals) are effected immediately (given that these are only performed by BRender functions). All ramifications of other changes will be effected each rendering.

See br_model228 and br_material151 for their maintenance requirements.


BrZsActorOrderTableSet()

Description:
Given a model actor, set the order table into which its primitives will be sorted.

Declaration:
br_order_table* BrZsActorOrderTableSet(br_actor* actor, br_order_table* order_table)

Arguments:
br_actor * actor

A non-Null pointer to a model actor.

br_order_table * order_table

A pointer to an order table. Null if the actor is to inherit an order table (the default condition).

Effects:
Assigns the specified order table to the actor, replacing the current one if any. Be very careful, if assigning an order table to more than one model actor (whether explicitly or by inheritance). In such cases judicious use of the order table flags, such as
BR_ORDER_TABLE_NEW_BOUNDS, may be required within a custom model call-back function.

Result:
br_order_table *

Returns order_table as supplied (for convenience).

Remarks:
Only useful to model actors involved during rendering by the Z-Sort renderer.

See Also:
BrZsActorOrderTableGet()
88


BrZsActorOrderTableGet()

Description:
Given a model actor, obtain a pointer to the currently set order table (into which its primitives will be sorted).

Declaration:
br_order_table* BrZsActorOrderTableGet(const br_actor* actor)

Arguments:
const br_actor * actor

A non-Null pointer to a model actor.

Result:
br_order_table *

Returns the order table currently assigned to the specified actor. Null is returned if no order table is explicitly assigned, i.e. an order table is inherited.

Remarks:
Only useful to model actors involved during rendering by the Z-Sort renderer.

See Also:
BrZsActorOrderTableSet()
87


Referencing & Lifetime

References are maintained to enabled Light or Clip Plane actors even if they are subsequently detached from a hierarchy that is then rendered. Thus it is important to disable such actors before removing them.

Actors must be maintained while they are part of an actor hierarchy, especially ones that will be rendered.

If the actor was allocated using BrActorAllocate()89 it will be freed by BrEnd()11 (if it hadn't been freed previously - as it should have been).

Initialisation

The actor is automatically initialised by BrActorAllocate()89, however, if you allocate it yourself, you should either use calloc(,sizeof(br_actor)) or memset(,0,sizeof(br_actor)), and ensure the following is done:

Refer to the respective description of each member for further details.

Construction & Destruction

Actors should be constructed using BrActorAllocate()89 and destroyed using BrActorFree()90. Although actors can be constructed any other way (as long as they observe the access & lifetime requirements), they should be detached (See BrActorRemove()81) from a hierarchy before any ancestor (parent) is freed using BrActorFree()90. This is because BrActorFree()90 will attempt to release storage for all of an actor's descendants - whether or not they were allocated by BrActorAllocate()89. In general, actors should be destroyed strictly using the complementary method of construction.

Note that BrActorLoad()95 and BrActorLoadMany()96 will effectively call BrActorAllocate()89 for each actor they import.


BrActorAllocate()

Description:
Allocate a new actor.

Declaration:
br_actor* BrActorAllocate(br_uint_8 actor_type, void* type_data)

Arguments:
br_uint_8 actor_type

Defines the type member of the actor allocated (See the type member of br_actor74 for a list of acceptable types). It is also used to determine suitable type specific data if Null is supplied for the type_data argument.

void * type_data

A pointer to optional, additional, type specific data used to determine the type_data member of the actor allocated. (See the type_data member of br_actor74 to determine the type of data structure that should be referenced). Null may be supplied in all cases.

Preconditions:
Between BrBegin()10 & BrEnd()11.

Memory can be allocated.

Effects:
A br_actor74 data structure is allocated and initialised (See br_actor74, Initialisation). Its type member is initialised with the value of actor_type. Where the actor requires type specific data, and Null has been supplied, the type_data member is initialised with a pointer to an appropriate, freshly allocated data structure containing default values.

Result:
br_actor *

A pointer to the new br_actor74 data structure.

Remarks:
If this function allocates type specific data, it is allocated and attached to the actor using BrResAllocate()48, so will be freed with the actor even if the actor's type_data member is subsequently changed. Until the actor is freed, the data may be freely accessed.

Example:
br_actor * t_pActor=BrActorAllocate(BR_ACTOR_MODEL,NULL);

See Also:
BrActorFree()90


BrActorFree()

Description:
Free an actor and all its descendants (children) if any.

Declaration:
void BrActorFree(br_actor* a)

Arguments:
br_actor * a

A pointer to an actor previously allocated using BrActorAllocate()89. Null is not acceptable. If a Light, or Clip Plane actor, it should have first been disabled. The actor should have first been detached from any hierarchy by using BrActorRemove()81.

Preconditions:
Between BrBegin()10 & BrEnd()11.

Effects:
Effectively applies BrActorRemove()81 and BrActorFree()90 to each child of the actor. Calls BrResFree()51 to release storage for the actor and any attached data (e.g. type specific data created by default).

Remarks:
Not recommended to be applied to an actor during rendering of the hierarchy that it is part of.

Ensure that any references to the actor or its children will not be used subsequent to this call. Remember that a light or clip plane should be disabled before it is removed and freed.

Example:
br_actor * t_pActor=BrActorAllocate(BR_ACTOR_MODEL,NULL);
BrActorFree(t_pActor);

See Also:
BrActorAllocate()89

BrResFree()51


Supplementary


BrActorEnum()

Description:
Enumerates an actor's children, calling a user supplied call-back function for each child actor.

Declaration:
br_uint_32 BrActorEnum(br_actor* parent, br_actor_enum_cbfn* callback, void* arg)

Arguments:
br_actor * parent

A pointer to the actor whose children are to be enumerated.

br_actor_enum_cbfn * callback

A pointer to the call-back function to be called for each child actor.

void * arg

The argument to pass to the call-back function (use Null if not required).

Preconditions:
Between BrBegin()
10 & BrEnd()11.

Effects:
For each child of parent, callback is invoked supplied with a pointer to the child and the arg pointer. If callback returns a non-zero result, the BrActorEnum()90 function will immediately return with the same result, otherwise the enumeration continues until all children have been enumerated.

Result:
br_uint_32

The result is zero, or the first and only non-zero result returned by callback.

Remarks:
An entire actor hierarchy can be enumerated simply by having the call-back function invoke BrActorEnum()90 itself.

Example:
br_uint_32 BR_CALLBACK CountDescendantsCB(br_actor* a,void* n)
{	++*(int*)n;
	return BrActorEnum(a,CountDescendantsCB,n);
}

int CountDescendants(br_actor* a)
{	int N=0;
	BrActorEnum(a,CountDescendantsCB,&N);
	return N;
}

See Also:
br_actor_enum_cbfn98


BrActorSearch()

Description:
Traverse an actor's descendants, searching for an actor of a particular generation with a lineage and identifier matching a specified wild carded string. To find actors anywhere within a hierarchy will require the additional use of BrActorEnum()
90.

Declaration:
br_actor* BrActorSearch(br_actor* root, const char* pattern)

Arguments:
br_actor * root

A pointer to an actor.

const char * pattern

Zero terminated character string containing the search pattern. This specifies the generation of actor required by separating descendants with slash characters
(`/'), e.g. "/<Child>/<Grand-child>/<Great grand-child>/etc.". Identifiers of actors along the lineage may be matched exactly or in combination with the wild-card characters `*' (match any number of any characters) and `?' (match any single character). The pattern is fully permuted, e.g. "b*an?s" will match "bananas", "banks", and "bandstands".

Preconditions:
Between BrBegin()10 & BrEnd()11.

Effects:
Compares the actor's descendants' identifiers with the respective component of the search pattern. Terminates as soon as the complete lineage matches, or all possible matching lineages have been explored.

Result:
br_actor *

A pointer to the first actor that was found whose lineage matched the search pattern, or Null if there was no match.

Remarks:
Note that the search pattern's first generation will be compared with the identifiers of the children of root - the identifier of root is not involved in the pattern matching process.

Where more than one match is possible, it is not recommended that any reliance be placed on which match is found first. No assumption should be made regarding how the actor hierarchy is traversed, e.g. whether branch by branch or generation by generation.

To find an actor irrespective of its lineage, use this function in combination with BrActorEnum()90.

Example:
Given a root actor with identifier "Root", children "Child1" and "Child2", and child "Child1" with grand-children "Grand-son1" and "Grand-daughter1", and child "Child2" with grand-children "Grand-son2" and "Grand-daughter2":

"Child?/Grand*1" would match either "Grand-son1" or "Grand-daughter1".

"Child1" would match "Child1".

"*/*son?" would match either "Grand-son1" or "Grand-son2".

See Also:
BrActorSearchMany()92

BrActorEnum()90


BrActorSearchMany()

Description:
Traverse an actor's descendants, searching for actors of a particular generation with a lineage and identifier matching a specified wild carded string.

Declaration:
br_uint_32 BrActorSearchMany(br_actor* root, const char* pattern, br_actor** actors, int max)

Arguments:
br_actor * root

A pointer to an actor.

const char * pattern

Zero terminated character string containing the search pattern. This specifies the generation of actor required by separating descendants with slash characters
(`/'), e.g. "/<Child>/<Grand-child>/<Great grand-child>/etc.". Identifiers of actors along the lineage may be matched exactly or in combination with the wild-card characters `*' (match any number of any characters) and `?' (match any single character). The pattern is fully permuted, e.g. "b*an?s" will match "bananas", "banks", and "bandstands".

br_actor ** actors

A pointer to a series of actor pointers. Storage must have been allocated (though not necessarily initialised) for at least max actor pointers.

int max

The maximum number of matched actors to store at actors.

Preconditions:
Between BrBegin()
10 & BrEnd()11.

Effects:
Compares the actor's descendants' identifiers with the respective component of the search pattern. Terminates as soon as the number of complete lineage matches has reached max, or all possible matching lineages have been explored.

Result:
br_uint_32

The number of matched actors stored at actors. This will be between zero and max (inclusive).

Remarks:
The same as BrActorSearch()91 except that it allows matches of more than one actor.

Note that the search pattern's first generation will be compared with the identifiers of the children of root - the identifier of root is not involved in the pattern matching process.

To find actors irrespective of their lineage, use this function in combination with BrActorEnum()90.

Example:
br_actor* t_aActorWheels[10];
int t_n;

t_n=BrActorSearchMany(pActorLorry,"Chassis/*Axle/Wheel?",t_aActorWheels,10);

ASSERT(!(t_n%2));	/* Even number of wheels */

See Also:
BrActorSearch()91, BrActorEnum()90


Import & Export

Actor hierarchies can be saved and loaded in their entirety. This can be useful for setting up scenes, or importing arbitrary, complex systems.


BrActorFileCount()

Description:
Locate a given file and count the number of actor hierarchies stored in it.

Declaration:
br_uint_32 BrActorFileCount(const char* filename, br_uint_16* num)

Arguments:
const char * filename

Name of the file previously created by BrActorSave()94 or BrActorSaveMany()96 (See Filing System Support, page 57).

br_uint_16 * num

Pointer to destination into which the number of actor hierarchies will be stored. If Null, the file will still be located and the success result returned, but no count will be made.

Preconditions:
Between BrBegin()10 & BrEnd()11. Filing system available.

Effects:
Searches for filename, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined).

Counts the number of actor hierarchies stored in the file. If the file is not an actor file, the function is still successful, but would obviously produce a zero count of actors.

Result:
br_uint_32

Returns zero if successful (the file was found), non-zero otherwise.

See Also:
BrActorLoad()95, BrActorLoadMany()96


BrActorSave()

Description:
Saves an actor and its descendants as a hierarchy.

Declaration:
br_uint_32 BrActorSave(const char* filename, const br_actor* actor)

Arguments:
const char * filename

The name of the file under which the hierarchy should be saved (See Filing System Support, page 57).

const br_actor * actor

A pointer to the effective root actor of the hierarchy to be saved.

Preconditions:
Between BrBegin()10 & BrEnd()11. Available filing system. Success depends on sufficient file space.

Effects:
If successful, the actor is written to a file*4 along with the identifier of its material (if non-Null), the identifier of its model (if non-Null), and any type specific data. This same process is then applied to each child in turn.

Result:
br_uint_32

The result is one if the hierarchy was saved successfully, and zero if not.

Remarks:
If the function fails (returns zero), the filing system can be considered returned to the state it was in just before the call, e.g. no file created.

The hierarchical relationship between actors is recorded implicitly, no use is made of the actor's parent, next, prev, children, or identifier members.

Note, that model and material data is not saved with actors, therefore this should be saved separately if required. It will need to be available to BrModelFind()240 and BrMaterialFind()162 (in the registry) before the actor hierarchy is loaded.

Example:
...
return BrActorSave("MyScene",pActorScene);

See Also:
BrActorLoad()95, BrActorSaveMany()96, BrWriteModeSet()63


BrActorLoad()

Description:
Load a hierarchy of actors from a file.

Declaration:
br_actor* BrActorLoad(const char* filename)

Arguments:
const char * filename

Name of the file previously created by BrActorSave()94 or BrActorSaveMany()96 (loads the first hierarchy) (See Filing System Support, page 57).

Preconditions:
Between BrBegin()10 & BrEnd()11. Filing system available. Memory can be allocated.

Effects:
Searches for filename, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined).

Allocates a root actor, reads members (type, identifier, render_style, t) in the order they were saved in, attempts to set model with BrModelFind()240 using the model identifier read, attempts to set material with BrMaterialFind()162 using the material identifier read, allocates and sets the type specific actor data. Any child actors are read using this same process (thus recursively), and then added to this actor using BrActorAdd()80. If a model or material was not found, the member is left at Null.

Result:
br_actor *

A pointer to the root actor of the loaded hierarchy, or Null if unsuccessful.

Remarks:
Ensure that necessary models and materials are loaded and added into the registry before calling this function.

Example:
br_actor* t_pMyScene=BrActorLoad("MyScene");

See Also:
BrActorSave()94, BrActorLoadMany()96


BrActorSaveMany()

Description:
Saves a series of actors and their descendants as hierarchies.

Declaration:
br_uint_32 BrActorSaveMany(const char* filename, const br_actor* const * actors, br_uint_16 num)

Arguments:
char * filename

The name of the file under which the hierarchies should be saved (See Filing System Support, page 57).

const br_actor * const * actors

A pointer to a series of num pointers to effective root actors of the hierarchies to be saved. The actors do not necessarily need to be from unrelated hierarchies.

br_uint_16 num

Number of hierarchies to save.

Preconditions:
Between BrBegin()10 & BrEnd()11. Available filing system. Success depends on sufficient file space.

Effects:
If successful for every one of the actor hierarchies, each is saved as described in BrActorSave()94, except that all are written to the same file*5.

Result:
br_uint_32

The function returns the number of complete actor hierarchies that were written to the file. This will be between zero and num (inclusive). Success is indicated by the return value being equal to num.

Remarks:
If the function fails (returns a value less than num), the filing system can be considered returned to the state it was in just before the call, e.g. no file created.

Note, that model and material data is not saved with actors, therefore this should be saved separately if required. It will need to be available to BrModelFind()240 and BrMaterialFind()162 (in the registry) before any of the actor hierarchies are loaded.

Example:
br_actor* apActorsInMyScene[N];
...
if (BrActorSaveMany("MyScene",apActorsInMyScene,(br_uint_16)N)<N)
...

See Also:
BrActorLoadMany()96, BrActorSave()94, BrWriteModeSet()63


BrActorLoadMany()

Description:
Load one or more hierarchies of actors from a file.

Declaration:
br_uint_32 BrActorLoadMany(const char* filename, br_actor** actors, br_uint_16 num)

Arguments:
const char * filename

Name of the file previously created by BrActorSaveMany()96 or BrActorSave()94. See Filing System Support for details of file naming.

br_actor ** actors

A pointer to a series of actor pointers. Storage must have been allocated (though not necessarily initialised) for at least num actor pointers. See BrActorFileCount()94 for a way of determining this value from a file.

br_uint_16 num

The maximum number of matched actors to store at actors.

Preconditions:
Between BrBegin()10 & BrEnd()11. Filing system available. Memory can be allocated.

Effects:
Searches for filename, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined).

Stores a pointer to the root actor of each loaded hierarchy into the respective element of actors. See BrActorLoad()95 for details of how each hierarchy is loaded.

Result:
br_uint_32

The number of actor hierarchies loaded successfully. Will be between zero and num (inclusive).

Remarks:
Ensure that necessary models and materials are loaded and added into the registry before calling this function.

Example:
br_actor* t_aScenes[5];
br_uint_32 t_u32;

t_u32=BrActorLoadMany("MyScenes",t_aScenes,5);

See Also:
BrActorSaveMany()96, BrActorLoad()95



Generated with CERN WebMaker