br_actor
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.
typedef
actor.h
for precise declaration and ordering)
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
br_transform t Transform to convert to parent co-ordinates
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
char * identifier String to identify actor
void * user User data (application dependent)
BrZbSceneRenderBegin()
34
, BrZbSceneRenderAdd()
36
, BrZbSceneRender()
34
, Br
[Zb
|Zs
]ModelRender()
249
|
249
Diagram showing linked list of sibling actors for three children of a root.
Members
Hierarchical Relationships
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, br_actor * parent
parent
is Null
.
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, br_actor * next
next
is Null
.
A pointer to the previous sibling actor's br_actor ** prev
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_actor
74,
prev
can be cast to a pointer to the previous actor (where prev
points to a next
member).
br_actor * children
children
is Null
.
br_uint_16 depth
depth
is zero for the root actor and increases by one each generation (indirection through children
).
next
, prev
, children
, depth
BrActorAdd()
80
, BrActorRemove()
81
, BrActorRelink()
81
). Although they should never be directly modified, direct use for traversal purposes is permitted.
br_transform t
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.
If you wished to perform this using BRender functions, you might first use BrTransformToMatrix34()
343, and then
BrMatrix34ApplyP()
191.
br_uint_8 type
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
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_light
145 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
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_model
228 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
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_material
151 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
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:
char * identifier
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
Null
upon allocation, and not accessed by BRender thereafter.
A non-
A non-
Operations
Hierarchical Relationships
Description:
Add an actor hierarchy as a child of a given parent.BrActorAdd()
br_actor* BrActorAdd(br_actor* parent, br_actor* a)
br_actor * parent
Null
pointer to the parental actor.br_actor * a
Null
pointer to its new child.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
A non-
Description:
Remove an actor hierarchy from its parent.BrActorRemove()
br_actor* BrActorRemove(br_actor* a)
br_actor * a
Null
pointer to the hierarchy to remove.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
A non-
A non-
Description:
Move an actor in a hierarchy, but preserve its apparent world transformation by manipulating its own transformation as necessary.BrActorRelink()
void BrActorRelink(br_actor* parent, br_actor* a)
br_actor * parent
Null
pointer to the new parent.br_actor * a
Null
pointer to the actor to move.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
BrActorToActorMatrix34()
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_transform
339).
Non-
Non-
Description:
Compute an actor hierarchy's bounding box, encompassing the bounding box of all models (including descendants).BrActorToBounds()
br_bounds* BrActorToBounds(br_bounds* b, const br_actor* ap)
br_bounds * b
Null
pointer to resulting bounding box.const br_actor * ap
Null
pointer to actor whose bounding box is required.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_bounds
105
, br_model
228
.
A pointer to the root of a world hierarchy.
A pointer to the reference actor.
A pointer to a bounds structure.
A pointer to a pick-3D call-back function.
An optional argument to pass to the call-back function.
If the call-back returns a non-zero value and traversal halts, that value is returned.
Otherwise, zero is returned.
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.BrScenePick3D()
int BrScenePick3D(br_actor* world, const br_actor* reference, const br_bounds* bounds, br_pick3d_cbfn* callback, void* arg)
br_actor * world
const br_actor * reference
const br_bounds * bounds
br_pick3d_cbfn * callback
void * arg
int
BrScenePick2D()
84
A non-
A non-
A non-
Description:
Accumulate the transformations between an actor and the screen, representing the result as a matrix.BrActorToScreenMatrix4()
void BrActorToScreenMatrix4(br_matrix4* m, const br_actor* a, const br_actor* camera)
br_matrix4 * m
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
Null
pointer to an actor.const br_actor * camera
Null
pointer to a camera actor.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
.
A pointer to the root of a world hierarchy.
A pointer to a camera actor.
A pointer to the viewport through which the pick ray passes.
Co-ordinates of viewport pixel through which the pick ray passes.
A pointer to a pick-2D call-back function.
An optional argument to pass to the call-back function.
If the call-back returns a non-zero value and traversal halts, that value is returned. Otherwise, zero is returned.
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.BrScenePick2D()
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)
br_actor * world
const br_actor * camera
const br_pixelmap * viewport
int pick_x, pick_y
br_pick2d_cbfn * callback
void * arg
int
BrScenePick3D()
82,
BrModelPick2D()
231
BrEnvironmentSet()
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).
A non-
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.
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.BrLightEnable()
void BrLightEnable(br_actor* l)
br_actor * l
Null
pointer to a light actor.BrLightDisable()
86
A non-
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.
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.BrLightDisable()
void BrLightDisable(br_actor* l)
br_actor * l
Null
pointer to a light actor.BrLightEnable()
85
A non-
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).
A non-
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).
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
Description:
Enable a clip plane. Such clip plane actors affect the contents of a scene (as long as they are enabled before rendering).BrClipPlaneEnable()
void BrClipPlaneEnable(br_actor* cp)
br_actor * cp
Null
pointer to a clip plane actor.
Description:
Disable a clip plane.BrClipPlaneDisable()
void BrClipPlaneDisable(br_actor* cp)
br_actor * cp
Null
pointer to a clip plane actor.
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.BrActorAdd()
80BrActorRemove()
81BrActorRelink()
81BrActorFree()
90
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_model
228 and
br_material
151 for their maintenance requirements.
A non-
A pointer to an order table.
Returns
Description:
Given a model actor, set the order table into which its primitives will be sorted.BrZsActorOrderTableSet()
br_order_table* BrZsActorOrderTableSet(br_actor* actor, br_order_table* order_table)
br_actor * actor
Null
pointer to a model actor.br_order_table * order_table
Null
if the actor is to inherit an order table (the default condition).BR_ORDER_TABLE_NEW_BOUNDS
, may be required within a custom model call-back function.br_order_table *
order_table
as supplied (for convenience).BrZsActorOrderTableGet()
88
A non-
Returns the order table currently assigned to the specified actor.
Description:
Given a model actor, obtain a pointer to the currently set order table (into which its primitives will be sorted).BrZsActorOrderTableGet()
br_order_table* BrZsActorOrderTableGet(const br_actor* actor)
const br_actor * actor
Null
pointer to a model actor.br_order_table *
Null
is returned if no order table is explicitly assigned, i.e. an order table is inherited.BrZsActorOrderTableSet()
87
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
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:
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.
Defines the
Description:
Allocate a new actor.BrActorAllocate()
br_actor* BrActorAllocate(br_uint_8 actor_type, void* type_data)
br_uint_8 actor_type
type
member of the actor allocated (See the type
member of br_actor
74Null
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_actor
74 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_actor
74
data structure is allocated and initialised (See br_actor
74
, 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_actor
74 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
A pointer to an actor previously allocated using
Description:
Free an actor and all its descendants (children) if any.BrActorFree()
void BrActorFree(br_actor* a)
br_actor * a
BrActorAllocate()
89Null
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
BrActorEnum()
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_cbfn
98
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 BrActorSearch()
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"
. 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
A pointer to an actor.
Zero terminated character string containing the search pattern. This specifies the generation of actor required by separating descendants with slash characters
A pointer to a series of actor pointers. Storage must have been allocated (though not necessarily initialised) for at least
The maximum number of matched actors to store at
Description:
Traverse an actor's descendants, searching for actors of a particular generation with a lineage and identifier matching a specified wild carded string.BrActorSearchMany()
br_uint_32 BrActorSearchMany(br_actor* root, const char* pattern, br_actor** actors, int max)
br_actor * root
const char * pattern
(`/
'), 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
max
actor pointers.int max
actors
.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
Description:
Locate a given file and count the number of actor hierarchies stored in it.BrActorFileCount()
br_uint_32 BrActorFileCount(const char* filename, br_uint_16* num)
const char * filename
or BrActorSaveMany()
96
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
The name of the file under which the hierarchy should be saved (See Filing System Support, page 57).
A pointer to the effective root actor of the hierarchy to be saved.
Description:
Saves an actor and its descendants as a hierarchy.BrActorSave()
br_uint_32 BrActorSave(const char* filename, const br_actor* actor)
const char * filename
const br_actor * actor
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
Description:
Load a hierarchy of actors from a file.BrActorLoad()
br_actor* BrActorLoad(const char* filename)
const char * filename
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
The name of the file under which the hierarchies should be saved (See Filing System Support, page 57).
A pointer to a series of
Number of hierarchies to save.
Description:
Saves a series of actors and their descendants as hierarchies.BrActorSaveMany()
br_uint_32 BrActorSaveMany(const char* filename, const br_actor* const * actors, br_uint_16 num)
char * filename
const br_actor * const * actors
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
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
Description:
Load one or more hierarchies of actors from a file.BrActorLoadMany()
br_uint_32 BrActorLoadMany(const char* filename, br_actor** actors, br_uint_16 num)
const char * filename
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