Module three::template

Expand description

Utilites for creating reusable templates for scene objects.

It is often the case that you will want to have multiple instances of the same model or hierarchy of objects in your scene. While you could manually construct each instance yourself, three-rs provides a templating system to allow you to describe your model’s hierarchy ahead of time, and then quickly create instances that three can efficiently batch render. Template describes the objects for a single model, and can be instantiated with Factory::instantiate_template.

The easiest way to create a template is to load one from a glTF file using Factory::load_gltf.

Object Relations

Often, one object needs to reference another object in the template, e.g. a bone needs to specify which skeleton it belongs to, and any object can specify that it belongs to a group in the template. When doing so, objects reference each other by their index in their respective arrays in Template. When such indices are used, the documentation will specify which array the index refers to.

Object Templates

The objects field of Template provides a flattened, type-erased list of all objects defined in the template. Each type of object provides its type-specific data in that type’s array, and then specifies the index of an ObjectTemplate in objects. Every object in the template must be represented in objects exactly once.

The full, flattened list of objects is primarily used by AnimationTemplate to allow tracks in the animation to reference the object targeted by the track regardless of the target object’s concrete type.

Animations

Templates can also describe animations that apply to the objects in a template. When instantiated, the resulting animation clips will be unique to that instance of of the template. This allows for instances of the template to be animated independently of each other, without requiring you to manually setup animations for each instance.

An animation in a template can target any of the objects described in the template. It does this by specifying the index of the objects in objects. See AnimationTemplate::tracks for more information.

Mesh Instancing

When setting up a mesh in a template, you must first upload your Geometry to the GPU using Factory::upload_geometry. This will give you an InstancedGeometry object that acts as a shared handle to the GPU resources for that geometry. By uploading the data to the GPU ahead of time, we can ensure that all mesh nodes that reference that geometry, and all Mesh instances created from the template, will share a single copy of the data on the GPU. This reduces GPU resource usage and, for any meshes that also share a material, allows three to render many objects at once.