Skip to main content

Material variants

Material variants switch authored surface appearances while preserving the scene hierarchy and model identities.

The MaterialsVariantsShoe sample demonstrates this capability. Use Material variant to switch appearances without reloading the model. Drag to orbit and scroll to zoom.

GitHub
Loading examplePreparing GPU resources…

API​

MaterialVariants from @luma.gl/engine accepts named variants and explicit per-model material/parameter mappings. See scene controllers for the source-independent construction API.

For imported assets, createScenegraphsFromGLTF() exposes a variants controller. Read names to discover choices, call selectVariant(name) to apply one, and resetVariant() to restore authored defaults. The controller updates materials and pipeline state on existing models.

Usage​

import {MaterialVariants} from '@luma.gl/engine';

// modelNode is an existing ModelNode; paintedMaterial is a compatible Material.
const variants = new MaterialVariants({
  variants: [{name: 'paint', index: 0}],
  bindings: [{
    modelNode,
    defaultMaterial: modelNode.model.material,
    defaultParameters: {...modelNode.model.parameters},
    mappings: new Map([[0, {
      material: paintedMaterial,
      parameters: {...modelNode.model.parameters}
    }]])
  }]
});
variants.selectVariant('paint');
variants.resetVariant();

Alternate materials must remain compatible with the original shader feature layout. Selecting a variant does not rebuild the model shader to add previously absent texture or alpha-cutoff defines.

glTF support​

The importer supplies the same engine controller with source variant names and resolved primitive mappings:

import {createScenegraphsFromGLTF} from '@luma.gl/gltf';

const scenegraphs = createScenegraphsFromGLTF(device, gltf);
const variantName = scenegraphs.variants.names[0];
if (variantName) {
  scenegraphs.variants.selectVariant(variantName);
}
// Restore the original appearance.
scenegraphs.variants.resetVariant();

KHR_materials_variants defines named primitive-to-material mappings. Unmapped primitives return to their default materials when switching. See native glTF extensions.

See glTF materials and textures, glTF animation, and the extension support matrix for adapter details and current support limits.

All engine features