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
The easiest way to create a template is to load one from a glTF file using
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.
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
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.
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.
When setting up a mesh in a template, you must first upload your
Geometry to the GPU
Factory::upload_geometry. This will give you an
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.
The definition for an animation targeting objects in a
A template for a
A template for a
Geometry data that has been loaded to the GPU.
Common information for instantiating the various types of lights.
Information for instantiating a
Common data used by all object types.
A template representing a hierarchy of objects.
Template information about the different sub-types for light.