KHR_materials_variants defines alternate Material states for any Primitive in the scene.

Illustration

Figure: A sneaker, in three material variants. Source: Khronos Group.

Uses include product configurators, night/day states, healthy/damaged states, etc. The MaterialsVariants class provides three ExtensionProperty types: Variant, Mapping, and MappingList. When attached to Primitive properties, these offer flexible ways of defining the variants available to an application. Triggering a variant is out of scope of this extension, but could be handled in the application with a UI dropdown, particular game states, and so on.

Mesh geometry cannot be changed by this extension, although another extension (tentative: KHR_mesh_variants) is under consideration by the Khronos Group, for that purpose.

Properties:

Example

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

// Create an Extension attached to the Document.
const variantExtension = document.createExtension(MaterialsVariants);

// Create some Variant states.
const healthyVariant = variantExtension.createVariant('Healthy');
const damagedVariant = variantExtension.createVariant('Damaged');

// Create mappings from a Variant state to a Material.
const healthyMapping = variantExtension.createMapping()
    .addVariant(healthyVariant)
    .setMaterial(healthyMat);
const damagedMapping = variantExtension.createMapping()
    .addVariant(damagedVariant)
    .setMaterial(damagedMat);

// Attach the mappings to a Primitive.
primitive.setExtension(
    'KHR_materials_variants',
    variantExtension.createMappingList()
        .addMapping(healthyMapping)
        .addMapping(damagedMapping)
);

A few notes about this extension:

  1. Viewers that don't recognized this extension will show the default material for each primitive instead, so assign that material accordingly. This material can be — but doesn't have to be — associated with one of the available variants.
  2. Mappings can list multiple Variants. In that case, the first Mapping containing an active Variant will be chosen by the viewer.
  3. Variant names are how these states are identified, so choose informative names.
  4. When writing the file to an unpacked .gltf, instead of an embedded .glb, viewers will have the option of downloading only textures associated with the default state, and lazy-loading any textures for inactive Variants only when they are needed.

Hierarchy

  • Extension
    • MaterialsVariants

Properties

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

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

prewriteTypes: PropertyType[]

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

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): MaterialsVariants
  • 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.

  • prewrite(_writerContext: WriterContext, _propertyType: PropertyType): MaterialsVariants
  • Used by the PlatformIO utilities when writing 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.prewriteTypes list. The Extension will be given a WriterContext 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