Skip to content

Bundled Assets (glTF & Others)

Bundled/Composite Asset Files#

using var carBundle = factory.AssetLoader.LoadBundledAsset(@"Assets/Models/ToyCar.glb"); // (1)!
using var carModelInstances = factory.ObjectBuilder.CreateModelInstances(carBundle); // (2)!
scene.Add(carModelInstances); // (3)!

  1. This line instructs TinyFFR to load the "ToyCar.glb" model file from "Assets/Models/ToyCar.glb".

    The returned carBundle is a ModelBundle (explained below) containing all loaded meshes, textures, materials, and models.

  2. This line creates a single ModelInstance for each Model (explained below) loaded amongst carBundle.

    The returned carModelInstances is a ModelInstanceGroup (essentially a specialized ResourceGroup) that contains all loaded model instances.

  3. This line adds all the newly-instantiated model instances to a pre-existing Scene; ready to be rendered.

Modern 3D assets are typically packaged in a composite/bundled "transmission" format such as .glTF or .glb. These files usually contain the meshes, textures, materials definitions, and animations required to define a single unified asset.

Supported Formats

TinyFFR can load the following asset formats. Some more esoteric features of 3D model formats such as scenes, multi-material objects, or exported material systems are not loaded, and therefore support for some of the file formats listed below may be partial.

What's Actually Loaded#

LoadBundledAsset() reads every Mesh, Texture and Material inside the target file. It associates linked Meshes and Materials in to Models (see below).

Skeletal animation data, if present, will also be loaded. See Skeletal Meshes for more info on how this data is loaded, or see Playing Skeletal Animations for information on playing the animations in a scene.

Everything is returned inside a single returned resource called a ModelBundle:

ModelBundles#

LoadBundledAsset() returns a ModelBundle. As its name implies, it represents a bundle of tightly-related loaded resources (in this case all textures, meshes, materials, models, and any shared animation data loaded as part of the composite asset file).

The Textures, Materials, Meshes and Models properties let you enumerate each kind of resource in the bundle, while Animations and Skeleton expose the bundle's shared animation data.

CalculateCombinedBoundingBox() returns the box enclosing every mesh in the bundle (i.e. the model-space bounding box of a group of instances created from it), and CalculateScalingForSize() calculates the scaling that makes such a group measure a given size (see Size).

Disposing the ModelBundle also disposes all contained resources, meaning invoking carBundle.Dispose() also disposes every Mesh, Material, Texture, etc loaded by LoadBundledAsset().

Models#

When you invoke LoadBundledAsset() TinyFFR determines which materials are meant for which meshes and pairs them in to Model instances. Most of the time, when loading composite asset files (such as glTF/glb) it's the Models that we actually want to use.

A Model does not itself represent any loaded data on the system; instead it is a logical pairing of a Mesh and Material that combined make up a single fully-textured object model.

We can pass a Model or ModelBundle to the factory.ObjectBuilder to create instances of those models. Passing the whole ModelBundle (as in the example at the top of this page) creates an instance of every model in it. Those ModelInstances can then be added to any Scene.

Creating Models Manually

If you wish to logically link a Mesh and Material together in to your own Model, it's as simple as invoking factory.AssetLoader.CreateModel(mesh, material).

The returned Model must be disposed before disposing its constituent Mesh and Material.

Customizing the Load Operation#

You can pass a ModelCreationConfig and a ModelReadConfig to LoadBundledAsset() to customize how the bundled data should be loaded:

ModelCreationConfig#

MeshConfig

This specifies the MeshCreationConfig that should be applied to every Mesh contained in the composite asset file.

TextureConfig

This specifies the TextureCreationConfig that should be applied to every Texture contained in the composite asset file.

The DataType property required on this TextureCreationConfig is used only for textures that have no specific data type or interpretation specified by the file format. In most cases all textures in a composite format file do have a specific data type/interpretation, so this property is largely ignored in this context.

If in doubt, you can set it to ColorSrgb which covers a lot of common texture types.

TransmissiveMaterialQuality

The quality used for any transmissive (e.g. glass) materials found in the file. Defaults to FullReflectionsAndRefraction.

Setting this to SkyboxOnlyReflectionsAndRefraction can make scenes with visible glass or mirror surfaces considerably cheaper to render, at the cost of the glass/mirror showing only the backdrop (rather than the other objects in the scene).

ModelReadConfig#

MeshConfig

This specifies the MeshReadConfig that should be applied to every Mesh contained in the composite asset file.

TextureConfig

This specifies the TextureReadConfig that should be applied to every Texture contained in the composite asset file.

HandleUriEscapedStrings

Some file formats embed references to sub-assets using a URI-encoded string format (e.g. my%20file.jpg rather than my file.jpg). By default, TinyFFR does not attempt to interpret and decode these strings.

Setting this property to true enables this decoding.

EmissiveStrengthScalar

A factor applied to emissive strengths read from the file (defaults to 0.05f).

Some file types (most notably glTF/glb) record emissive strength on a scale that does not correspond to TinyFFR's, so a file's values are scaled down to keep glowing surfaces from overwhelming the scene. Raise this if imported emissive surfaces look too dim; lower it if they seem too bright.

EmissiveStrengthCap

A normalized value (0 to 1) indicating the max emissive strength of any material imported from this file.

Defaults to 1f.

EmbeddedTextureMapScalingStrategy

Sometimes composite asset files provide multiple texture files for different material properties that must be combined in to a single map file.

In the case those texture files have differing resolutions, this property controls how the lower-resolution textures should be upscaled.

ShininessMapInterpretation

Older file formats (such as FBX and OBJ) have no dedicated slot for a roughness map, so some exporters store one in the "shininess" slot instead of the glossiness map that slot is meant to hold. Most notably, Blender does this. Reading the map the wrong way round makes glossy surfaces look rough and vice versa.

By default (Auto), TinyFFR treats the map as roughness when the file reports that it was exported from Blender, and as glossiness otherwise. Set this to Roughness or Glossiness to override that choice; for example, Blender-exported OBJ files do not record where they came from, so they need Roughness set explicitly.

Comments