KHR_materials_volume adds refraction, absorption, or scattering to a glTF PBR material already using transmission or translucency.

Illustration

Figure: Base color changes the amount of light passing through the volume boundary (left). The overall color of the object is the same everywhere, as if the object is covered with a colored, transparent foil. Absorption changes the amount of light traveling through the volume (right). The overall color depends on the distance the light traveled through it; at small distances (tail of the dragon) less light is absorbed and the color is brighter than at large distances. Source: Khronos Group.

By default, a glTF 2.0 material describes the scattering properties of a surface enclosing an infinitely thin volume. The surface defined by the mesh represents a thin wall. The volume extension makes it possible to turn the surface into an interface between volumes. The mesh to which the material is attached defines the boundaries of an homogeneous medium and therefore must be manifold. Volumes provide effects like refraction, absorption and scattering. Scattering effects will require future (TBD) extensions.

The volume extension must be combined with MaterialsTransmission or KHR_materials_translucency in order to define entry of light into the volume.

Properties:

Example

The MaterialsVolume class provides a single ExtensionProperty type, Volume, which may be attached to any Material instance. For example:

import { MaterialsVolume, Volume } from '@gltf-transform/extensions';

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

// Create a Volume property.
const volume = volumeExtension.createVolume()
    .setThicknessFactor(1.0)
    .setThicknessTexture(texture)
    .setAttenuationDistance(1.0)
    .setAttenuationColorHex(0xFFEEEE);

// Attach the property to a Material.
material.setExtension('KHR_materials_volume', volume);

A thickness texture is required in most realtime renderers, and can be baked in software such as Blender or Substance Painter. When thicknessFactor = 0, all volumetric effects are disabled.

Hierarchy

  • Extension
    • MaterialsVolume

Properties

extensionName: "KHR_materials_volume" = ...
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): MaterialsVolume
  • 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): MaterialsVolume
  • 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 2021 under MIT license