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.
Structs
Template
.Bone
object.Camera
object.Mesh
.