Creating Mesh Instances

A mesh instance places a given mesh at a given matrix within the world space of a scene. Essentially, it is a mapping from the object space of the mesh to the world space in the scene, with a small set of additional information specific to the instance such as render stats and material overrides.

Setting up a mesh instance

You can only set up a mesh instance in the context of setting up a scene. See also Creating a Scene.

To set up a mesh instance:

Create a new ILBInstanceHandle.
Initialize the instance by calling ILBCreateInstance(). In your call, you must provide the handle of the mesh that this instance will instantiate, a unique name for the instance within the scene, and a 4x4 matrix that defines the transformation of the mesh from its object space into the world space of the scene.

For example:

ILBInstanceHandle floorInstance;
ILBMatrix4x4 floorTrans (/* matrix */);
bex::apiCall(ILBCreateInstance(scene, floorMesh, "FloorInstance", &floorTrans, &floorInstance));

Setting render stats

The render stats of a mesh instance determine whether or not the instance is taken into account during different types of rendering and lighting calculations. For example, you can specify for each instance whether or not it should cast and receive shadows, whether or not it should be considered in ambient occlusion calculations as an occluder, whether or not it should receive light from a global illumination pass, etc. The full set of controls are listed in the ILBRenderStats enumeration.

To customize the render stats for an instance, call the ILBSetRenderStats() function. You provide this function with:

A bitmask composed from the ILBRenderStats enumeration that specifies the render stats that you want to modify.
A value from the ILBRenderStatOperation enumeration that indicates whether you want to enable the render stats you have identified. May be ILB_RSOP_DISABLE to disable the specified render stats, or ILB_RSOP_ENABLE to enable them.

For example:

ILBSetRenderStats(instance, 
                          ILB_RS_CAST_SHADOWS | ILB_RS_RECEIVE_SHADOWS | ILB_RS_CAST_OCCLUSION, 
                          ILB_RSOP_DISABLE);

Overriding materials

You can override the materials specified in the source mesh for each instance you create by calling ILBSetMaterialOverrides(). The first material handle that you provide in this call is used for all triangles in the instance, regardless of the material names assigned to the triangles in the source mesh.

Currently, the material override affects all triangles in the source mesh. You cannot override different material groups in the source mesh with different materials in an instance. As a workaround, you can instead split each material group in your source mesh into a separate mesh. When you create an instance of one of those smaller meshes, you can override its material with a different material in your scene.

Modifying an instance

You have a limited amount of freedom to modify the instances in your scene after creating them. This may be particularly useful for live eRnsT sessions, in which the artist moves objects from place to place in the level editor.

You can move an instance to a different translation and rotation in 3D space by calling ILBSetInstanceTransform().
You can change the mesh assigned to an instance by calling ILBSetInstanceMesh().

Thread safety

You should only operate on a mesh instance from a single thread.

Related API functions

API functions related to the creation and setup of mesh instances are declared in the beastinstance.h file.