EXT_mesh_gpu_instancing prepares mesh data for efficient GPU instancing.

NOTICE: Multi-vendor extensions (EXT_*) should be considered last-mile optimizations for an application known to support their use. Files using these extensions may not be widely portable in other software, and are not officially endorsed by the Khronos Group.

GPU instancing allows engines to render many copies of a single mesh at once using a small number of draw calls. Instancing is particularly useful for things like trees, grass, road signs, etc. Keep in mind that predefined batches, as used in this extension, may prevent frustum culling within a batch. Dividing batches into collocated cells may be preferable to using a single large batch.

NOTICE: While this extension stores mesh data optimized for GPU instancing, it is important to note that (1) GPU instancing and other optimizations are possible — and encouraged — even without this extension, and (2) other common meanings of the term "instancing" exist, distinct from this extension. See Appendix: Motivation and Purpose of the EXT_mesh_gpu_instancing specification.

Properties:

Example

The MeshGPUInstancing class provides a single ExtensionProperty type, InstancedMesh, which may be attached to any Node instance. For example:

import { MeshGPUInstancing } from '@gltf-transform/extensions';

// Create standard mesh, node, and scene hierarchy.
// ...

// Assign positions for each instance.
const batchPositions = doc.createAccessor('instance_positions')
    .setArray(new Float32Array([
        0, 0, 0,
        1, 0, 0,
        2, 0, 0,
    ]))
    .setType(Accessor.Type.VEC3)
    .setBuffer(buffer);

// Assign IDs for each instance.
const batchIDs = doc.createAccessor('instance_ids')
    .setArray(new Uint8Array([0, 1, 2]))
    .setType(Accessor.Type.SCALAR)
    .setBuffer(buffer);

// Create an Extension attached to the Document.
const batchExtension = document.createExtension(MeshGPUInstancing)
    .setRequired(true);
const batch = batchExtension.createInstancedMesh()
    .setAttribute('TRANSLATION', batchPositions)
    .setAttribute('_ID', batchIDs);

node
    .setMesh(mesh)
    .setExtension('EXT_mesh_gpu_instancing', batch);

Standard instance attributes are TRANSLATION, ROTATION, and SCALE, and support the accessor types allowed by the extension specification. Custom instance attributes are allowed, and should be prefixed with an underscore (_*).

Hierarchy

  • Extension
    • MeshGPUInstancing

Properties

extensionName: "EXT_mesh_gpu_instancing" = ...
prereadTypes: PropertyType[]

Before reading, extension should be called for these Property types. Most extensions don't need to implement this.

prewriteTypes: PropertyType[] = ...
readDependencies: string[]

Dependency IDs needed by this extension, to be installed before I/O.

Methods

  • dispose(): void
  • Disables and removes the extension from the Document.

  • Installs dependencies required by the extension.

  • isRequired(): boolean
  • Indicates to the client whether it is OK to load the asset when this extension is not recognized. Optional extensions are generally preferred, if there is not a good reason to require a client to completely fail when an extension isn't known.

  • preread(_readerContext: ReaderContext, _propertyType: PropertyType): MeshGPUInstancing
  • Used by the PlatformIO utilities when reading a glTF asset. This method may optionally be implemented by an extension, and should then support any property type declared by the Extension's Extension.prereadTypes list. The Extension will be given a ReaderContext instance, and is expected to update either the context or its JSONDocument with resources known to the Extension. Most extensions don't need to implement this.

  • Indicates to the client whether it is OK to load the asset when this extension is not recognized. Optional extensions are generally preferred, if there is not a good reason to require a client to completely fail when an extension isn't known.

  • register(): void
  • Performs first-time setup for the extension. Must be idempotent.

Function symbol, f(📦) → 📦, where the argument and output are a box labeled 'glTF'.

Made by Don McCurdy TypeDoc documentation Copyright 2020 under MIT license