Buffer

Buffers are low-level storage units for binary data.

glTF 2.0 has three concepts relevant to binary storage: accessors, buffer views, and buffers. In glTF Transform, an Accessor is referenced by any property that requires numeric typed array data. Meshes, Primitives, and Animations all reference Accessors. Buffers define how that data is organized into transmitted file(s). A .glb file has only a single Buffer, and when exporting to .glb your resources should be grouped accordingly. A .gltf file may reference one or more .bin files — each .bin is a Buffer — and grouping Accessors under different Buffers allow you to specify that structure.

For engines that can dynamically load portions of a glTF file, splitting data into separate buffers can allow you to avoid loading data until it is needed. For example, you might put binary data for specific meshes into a different .bin buffer, or put each animation's binary payload into its own .bin.

Buffer Views define how Accessors are organized within a given Buffer. glTF Transform creates an efficient Buffer View layout automatically at export: there is no Buffer View property exposed by the glTF Transform API, simplifying data management.

Usage:

// Create two buffers with custom filenames.
const buffer1 = doc.createBuffer('buffer1')
    .setURI('part1.bin');
const buffer2 = doc.createBuffer('buffer2')
    .setURI('part2.bin');

// Assign the attributes of two meshes to different buffers. If the meshes
// had indices or morph target attributes, you would also want to relocate
// those accessors.
mesh1
    .listPrimitives()
    .forEach((primitive) => primitive.listAttributes()
        .forEach((attribute) => attribute.setBuffer(buffer1)));
mesh2
    .listPrimitives()
    .forEach((primitive) => primitive.listAttributes()
        .forEach((attribute) => attribute.setBuffer(buffer2)));

// Write to disk. Each mesh's binary data will be in a separate binary file;
// any remaining accessors will be in a third (default) buffer.
await new NodeIO().write('scene.gltf', doc);
// → scene.gltf, part1.bin, part2.bin

References:

Hierarchy

Properties

propertyType: PropertyType.BUFFER

Methods

  • dispatchEvent(event: BaseEvent): this

  • Dispatches an event on the GraphNode, and on the associated Graph. Event types on the graph are prefixed, "node:[type]".

  • dispose(): void

  • Removes both inbound references to and outbound references from this object. At the end of the process the object holds no references, and nothing holds references to it. A disposed object is not reusable.

  • equals(other: Property, skip?: Set<string>): boolean

  • Returns true if two properties are deeply equivalent, recursively comparing the attributes of the properties. Optionally, a 'skip' set may be included, specifying attributes whose values should not be considered in the comparison.

    Example: Two Primitives are equivalent if they have accessors and materials with equivalent content — but not necessarily the same specific accessors and materials.

  • addEventListener(type: string, listener: EventListener<T>): this
  • removeEventListener(type: string, listener: EventListener<T>): this
  • getExtension(name: string): Prop | null
  • listExtensions(): ExtensionProperty[]
  • getExtras(): Record<string, unknown>

  • Returns a reference to the Extras object, containing application-specific data for this Property. Extras should be an Object, not a primitive value, for best portability.

  • setExtras(extras: Record<string, unknown>): Property

  • Updates the Extras object, containing application-specific data for this Property. Extras should be an Object, not a primitive value, for best portability.

  • isDisposed(): boolean

  • Returns true if the node has been permanently removed from the graph.

  • getName(): string

  • Returns the name of this property. While names are not required to be unique, this is encouraged, and non-unique names will be overwritten in some tools. For custom data about a property, prefer to use Extras.

  • Sets the name of this property. While names are not required to be unique, this is encouraged, and non-unique names will be overwritten in some tools. For custom data about a property, prefer to use Extras.

  • listParents(): Property[]

  • Returns a list of all properties that hold a reference to this property. For example, a material may hold references to various textures, but a texture does not hold references to the materials that use it.

    It is often necessary to filter the results for a particular type: some resources, like Accessors, may be referenced by different types of properties. Most properties include the Root as a parent, which is usually not of interest.

    Usage:

    const materials = texture
    .listParents()
    .filter((p) => p instanceof Material)
  • getURI(): string

  • Returns the URI (or filename) of this buffer (e.g. 'myBuffer.bin'). URIs are strongly encouraged to be relative paths, rather than absolute. Use of a protocol (like file://) is possible for custom applications, but will limit the compatibility of the asset with most tools.

    Buffers commonly use the extension .bin, though this is not required.

  • Sets the URI (or filename) of this buffer (e.g. 'myBuffer.bin'). URIs are strongly encouraged to be relative paths, rather than absolute. Use of a protocol (like file://) is possible for custom applications, but will limit the compatibility of the asset with most tools.

    Buffers commonly use the extension .bin, though this is not required.

Function symbol, where the argument and output are a box labeled 'glTF'.

Made by Don McCurdy. Documentation built with greendoc and published under Creative Commons Attribution 3.0.