br_model

Casts a ray into a model and calls a call-back for all faces that intersect the ray. This can be used in conjunction with BrScenePick2D()84 to give face/edge/vertex picking.

Declaration:

int BrModelPick2D(br_model* model, const br_material* material, const br_vector3* ray_pos, const br_vector3* ray_dir, br_scalar t_near, br_scalar t_far, br_modelpick2d_cbfn* callback, void* arg)

Arguments:

br_model * model

Non-Null pointer to model.

const br_material * material

Non-Null pointer to model's default material.

const br_vector3 * ray_pos

Non-Null pointer to a 3D vector giving a starting position of a pick ray in the model's co-ordinate space.

const br_vector3 * ray_dir

Non-Null pointer to a 3D vector giving the direction of the pick ray.

br_scalar t_near, t_far

Coefficients of ray_dir defining the section of the ray that should be considered. Intersections outside this section are ignored. t_near should be less than t_far.

br_modelpick2d_cbfn * callback

Non-Null pointer to call-back function to be called for each face intersecting the specified ray section.

void * arg

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

Preconditions:

Between BrBegin()10 and BrEnd()11. BRender has completed initialisation. The specified model and material have been updated.

Effects:

The model's geometry is scanned to find faces that intersect the specified ray section. The supplied call-back is called for each intersecting face.

Result:

int

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

Remarks:

This function is typically used within BrScenePick2D()84 to refine selection further down to the face level. Perspective texture co-ordinates are also available to provide such things as 3D texture editing, or surface controls.

Example:

The following code gives an example of call-backs that enable changing the material assigned to a face of a (non-inherited) model under a particular screen pixel.

int BR_CALLBACK MyPickNearestModelCallback(br_model* model, const br_material* material, const br_vector3* ray_pos, const br_vector3* ray_dir, br_scalar t, int f,int e, int v, const br_vector3* p, const br_vector2* map, my_pick_nearest* pn)
{	if (t<pn->t)	/* has its own model & nearer */
	{	pn->t=t;
		pn->actor=pn->temp_actor;
		pn->model=model;
		pn->material=material;
		pn->point=*p;
		pn->face=f;
		pn->edge=e;
		pn->vertex=v;
		pn->map=*map;
	}
	return 0;
}

/* Test callback */
int BR_CALLBACK MyPickNearestCallback(br_actor* actor, const br_model* model, const br_material* material, const br_vector3* ray_pos, const br_vector3* ray_dir, br_scalar t_near, br_scalar t_far, my_pick_nearest* pn)
{	pn->temp_actor=actor;
	if (actor->model)
		BrModelPick2D(actor->model, material, ray_pos, ray_dir, t_near, t_far, MyPickNearestModelCallback, pn);
	return 0;
}
...
BrScenePick2D(test_world, observer, back_buffer, PickCursor_X, PickCursor_Y, MyPickNearestCallback, &PickNearest);
if(PickNearest.model)
{	PickNearest.model->faces[PickNearest.face].material=pick_material;
	BrModelUpdate(PickNearest.model,BR_MODU_ALL);
}
...

See Also:

BrScenePick2D()84

`BrModelApplyMap()`

Generate texture co-ordinates (u,v) for a model's vertices, using a planar, spherical, cylindrical, disc or null mapping. The model's vertices can be pre-transformed by an optional matrix.

void BrModelApplyMap(br_model* model, int map_type, const br_matrix34* xform)

A pointer to a model.

int map_type

Mapping type. This determines how a texture is wrapped around a model. Each type is described in the following table.

The disc mapping can be visualised by considering a cylindrical mapping, but shrinking one end of the cylinder to a point and then flattening it to form a disc.

The cylindrical mapping, predictably, can be visualised by imagining a texture wrapped around the outside of a cylinder. The spherical mapping is similar to a cylindrical mapping, but the ends of the cylinder are shrunk to single points.

const br_matrix34 * xform

A pointer to an optional matrix. If NULL, the identity transformation is used.

BrModelFitMap()233

`BrModelFitMap()`

Generate a transformation which will map the bounds of a model onto a cube defined by the corner co-ordinates (-1,-1,-1) and (1,1,1). When passed to BrModelApplyMap()231, texture co-ordinates will be generated which fit the model exactly. The two axes along which the mapping is applied must be specified.

Declaration:

br_matrix34* BrModelFitMap(const br_model* model, int axis_0, int axis_1, br_matrix34* transform)

Arguments:

const br_model * model

A pointer to a model.

int axis_0, axis_1

Mapping axes, defined as follows:

br_matrix34 * transform

A pointer to the destination transformation matrix.

Result:

br_matrix34 *

Returns a pointer to the destination transformation matrix as supplied (for convenience).

See Also:

BrModelApplyMap()231

`BrSceneModelLight()`

Generate prelit lighting values for the vertices of a given model, using the current rendering's lighting set-up.

void BrSceneModelLight(br_model* model, const br_material* default_material, const br_actor* root, const br_actor* a)

Models must be added to the registry if they are involved in rendering a scene. They should not be modified during rendering.

Non-Null pointer to model to calculate prelit values for.

const br_material * default_material

Non-Null pointer to default material to use for model.

const br_actor* root

Pointer to root actor of scene, e.g. as supplied to BrZbSceneRenderBegin()35. If this function is called from within a custom model call-back, Null may be used to indicate that the root effective for the current actor is to be used.

const br_actor* a

Pointer to actor defining the required co-ordinate space for the model to be prelit. If this function is called from within a custom model call-back, Null may be used to indicate that the current actor should is to be used.

Preconditions:

Between BrBegin()10 and BrEnd()11. Currently rendering, e.g. between BrZbSceneRenderBegin()35 and BrZbSceneRenderEnd()37.

Effects:

Works out lighting for the supplied model as though it were attached to the supplied actor. Modifies the appropriate prelit members of each vertex in accordance with the model and its material.

Remarks:

Generally useful for scenes having little change in lighting. Lights may be enabled for the first frame, this function called to pre-light various models and then most or all lighting disabled for performance in subsequent frames. Note that each model whose vertices are so set will need a BrModelUpdate()237 applied before the next rendering.

See Also:

br_vertex367

Copy/Assign

The br_model228 structure should not be copied directly, e.g. by structure assignment. If a similar model is required, a new one should be allocated and pertinent members copied individually. Do not copy vertex and face lists by reference unless you have allocated them yourself. Care may be needed in copying identifier.

Access & Maintenance

Models that have been added to the registry may be accessed by BRender during rendering.

If any changes are made to models involved in rendering, they must be updated before the next rendering in which they are involved.

`BrModelAdd()`

Add a model to the registry, updating it as necessary. All models must be added to the registry before they are subsequently involved in rendering.

br_model* BrModelAdd(br_model* model)

A pointer to a model.

Returns a pointer to the added model, else Null if unsuccessful.

BrModelUpdate()237, BrModelAddMany()236, BrModelLoad()243, BrModelFind()240, BrModelRemove()237.

`BrModelAddMany()`

Add a number of models to the registry, updating them as necessary.

br_uint_32 BrModelAddMany(br_model* const* models, int n)

br_model * const * models

A pointer to an array of pointers to models.

int n

Number of models to add to the registry.

Returns the number of models added successfully.

BrModelUpdate()237, BrModelAdd()235, BrModelRemove()237, BrModelRemoveMany()238

`BrModelUpdate()`

Update a model that has changed in some respect since the previous update of this model (or BrModelAdd()235).

Declaration:

void BrModelUpdate(br_model* model, br_uint_16 flags)

Arguments:

br_model * model

A pointer to a model.

br_uint_16 flags

Model update flags. In general, BR_MODU_ALL should be used. However, the following table describes when to use more specific update flags. Note that flags can be combined using the `Or' operation (BR_MODU_ALL is such a combination of the other flags, for your convenience).

BrModelAdd()235.

`BrModelRemove()`

Remove a model from the registry.

br_model* BrModelRemove(br_model* model)

A pointer to a model.

Returns a pointer to the model removed.

BrModelAdd()235

`BrModelRemoveMany()`

Remove a number of models from the registry.

br_uint_32 BrModelRemoveMany(br_model* const* models, int n)

br_model * const * models

A pointer to an array of pointers to models.

int n

Number of models to remove from the registry.

Returns the number of models removed successfully.

Models may be multiply referenced. The model may be referenced by more than one model actor as long as its lifetime is longer than the actors that refer to them. Models must have been added to the registry if they will be involved in rendering. The model must be maintained while it is in the registry or being referenced.

BrModelAddMany()236

Referencing & Lifetime

Initialisation

The model is automatically initialised to zero by BrModelAllocate()239. Members should then be set appropriately. Re-initialisation is not recommended - destroy and reconstruct.

Construction & Destruction

Apart from import and platform specific functions, models should only be constructed by the following BRender function. Destruction should naturally be performed by the corresponding `free' function, usually BrModelFree()239. Note that a model should be removed from the registry before being destroyed.

`BrModelAllocate()`

Allocate a new model.

br_model* BrModelAllocate(const char* name, int nvertices, int nfaces)

Size of vertex list to allocate. This should be set to zero if maintaining the vertex list separately (in which case BR_MODF_KEEP_ORIGINAL should be immediately set in the returned structure).

const char * name

String to initialise the identifier member to.

int nvertices

int nfaces

Size of face list to allocate. This should be set to zero if maintaining the face list separately (in which case BR_MODF_KEEP_ORIGINAL should be immediately set in the returned structure).

Returns a pointer to the new model, or Null if unsuccessful.

`BrModelFree()`

Deallocate a model and any associated memory.

void BrModelFree(br_model* m)

br_model * m

A pointer to a model.

Supplementary

`BrModelCount()`

Count the number of registered models whose names match a given search pattern. The search pattern can include the standard wild cards `*' and `?'.

br_uint_32 BrModelCount(const char* pattern)

const char * pattern

Search pattern.

Returns the number of models matching the search pattern.

BrModelEnum()240, BrModelFind()240

`BrModelEnum()`

Calls a call-back function for every model in the registry matching a given search pattern. The call-back is passed a pointer to each matching model, and its second argument is an optional pointer supplied by the user. The search pattern can include the standard wild cards `*' and `?'. The call-back itself returns a br_uint_32348 value. The enumeration will halt at any stage if the return value is non-zero.

Declaration:

br_uint_32 BrModelEnum(const char* pattern, br_model_enum_cbfn* callback, void* arg)

Arguments:

const char * pattern

Search pattern.

br_model_enum_cbfn * callback

A pointer to a call-back function.

void * arg

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

Result:

br_uint_32

Returns the first non-zero call-back return value, or zero if all matching models are enumerated.

Example:

br_uint_32 BR_CALLBACK test_callback(br_model* model, void* arg)
{	br_uint_32 count;
...
	return(count);
}
...
{	br_uint_32 enum;
...
	enum = BrModelEnum("model",&test_callback,NULL);
}

`BrModelFind()`

Find a model in the registry by name. A call-back function can be setup to be called if the search is unsuccessful. The search pattern can include the standard wild cards `*' and `?'.

br_model* BrModelFind(const char* pattern)

const char * pattern

Search pattern.

Returns a pointer to the model if found, otherwise Null. If a call-back exists and is called, the call-back's return value is returned.

BrModelFindHook()241, BrModelFindMany()241

`BrModelFindMany()`

Find a number of models in the registry by name. The search pattern can include the standard wild cards `*' and `?'.

br_uint_32 BrModelFindMany(const char* pattern, br_model** models, int max)

const char * pattern

Search pattern.

br_model * * models

A pointer to an array of pointers to models.

int max

Maximum number of models to find.

Returns the number of models found. The pointer array is filled with pointers to the found models.

BrModelFind()240, BrModelFindHook()241

`BrModelFindHook()`

Functions to set up a call-back.

br_model_find_cbfn* BrModelFindHook(br_model_find_cbfn* hook)

br_model_find_cbfn * hook

A pointer to a call-back function.

If BrModelFind()240 is unsuccessful and a call-back has been set up, the call-back is passed the search pattern as its only argument. The call-back should then return a pointer to a substitute or default model.

For example, a call-back could be set up to return a default model if the desired model cannot be found in the registry.

The function BrModelFindFailedLoad()242 is provided and will probably be sufficient in many cases.

Result:

br_model_find_cbfn *

Returns a pointer to the old call-back function.

Example:

br_model BR_CALLBACK * test_callback(const char* pattern)
{	br_model* default_model;
...
	return(default_model);
}
...
{	br_model* model;
...
	BrModelFindHook(&test_callback);
	model = BrModelFind("non_existent_model");
}

See Also:

BrModelFindFailedLoad()242

`BrModelFindFailedLoad()`

This function is provided as a suitable function to supply to BrModelFindHook()241.

Declaration:

br_model* BrModelFindFailedLoad(const char* name)

Arguments:

const char * name

The name supplied to BrModelFind()240.

Effects:

Attempts to load the model from the filing system using name as the filename. Searches in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined). If successful, sets this name as the identifier of the loaded model and adds the model to the registry.

Result:

br_model *

Returns a pointer to the model, if found, else Null.

Example:

BrModelFindHook(BrModelFindFailedLoad);

Import & Export

`BrModelFileCount()`

Locate a given file and count the number of models in it.

br_uint_32 BrModelFileCount(const char* filename, br_uint_16* num)

const char * filename

Name of the file containing the models to count.

br_uint_16 * num

Pointer to the variable in which to store the number of models counted in the file. If Null, the file will still be located and appropriate success returned, but no count will be made.

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). If a file is found, will count the number of models stored in it.

Returns zero if the file was found (even if it is not a models file), non-zero otherwise.

`BrModelLoad()`

Load a model. Note that it is not added to the registry.

br_model* BrModelLoad(const char* filename)

const char * filename

Name of the file containing the model to load.

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).

Returns a pointer to the loaded model, or Null if unsuccessful.

BrModelLoadMany()244, BrModelSave()245, BrModelAdd()235.

`BrModelLoadMany()`

Load a number of models. Note that they are not added to the registry.

br_uint_32 BrModelLoadMany(const char* filename, br_model** models, br_uint_16 num)

const char * filename

Name of the file containing the models to load.

br_model ** models

A non-Null pointer to an array of pointers to models.

br_uint_16 num

Maximum number of models to load.

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).

Returns the number of models loaded successfully. The pointer array if supplied, is filled with pointers to the loaded models.

See BrModelFileCount()242 to determine the number of models in a file.

`BrFmtASCLoad()`

Import 3D studio models (geometry only). The models are neither updated nor registered.

br_uint_32 BrFmtASCLoad(const char* name, br_model** mtable, br_uint_16 max_models)

const char * name

Name of the file containing the models.

br_model ** mtable

A pointer to an array of pointers to models, which will be filled as they are imported. If NULL, the models are still imported, but must be referenced subsequently by name.

int max_models

The maximum number of models to import.

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).