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.
new NodeIO().write('scene.gltf', doc);
// → scene.gltf, part1.bin, part2.bin

References:

Hierarchy

Properties

propertyType: string

Property type.

Methods

  • clone(): this
  • copy(other: this, resolve: PropertyResolver<Property>): this
  • Copies all data from another property to this one. Child properties are copied by reference, unless a 'resolve' function is given to override that.

  • detach(): this
  • Removes all inbound references to this object. At the end of the process the object is considered 'detached': it may hold references to child resources, but nothing holds references to it. A detached object may be re-attached.

  • 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.

  • getExtension<Prop>(name: string): Prop
  • getExtras(): object
  • 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.

  • 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.

  • 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.

  • isDisposed(): boolean
  • 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)
  • setExtension<Prop>(name: string, extensionProperty: Prop): this
  • setExtras(extras: object): this
  • Updates the Extras object, containing application-specific data for this Property. Extras should be an Object, not a primitive value, for best portability.

  • setName(name: string): this
  • 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.

  • setURI(uri: string): this
  • 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, f(📦) → 📦, where the argument and output are a box labeled 'glTF'.

Made by Don McCurdy TypeDoc documentation Copyright 2020 under MIT license