KHRMaterialsVolume

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 KHRMaterialsTransmission or KHR_materials_translucency in order to define entry of light into the volume.

Properties:

Example

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

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

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

// Create a Volume property.
const volume = volumeExtension.createVolume()
    .setThicknessFactor(1.0)
    .setThicknessTexture(texture)
    .setAttenuationDistance(1.0)
    .setAttenuationColorFactor([1, 0.5, 0.5]);

// 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

Static properties

EXTENSION_NAME: "KHR_materials_volume"

Properties

extensionName: "KHR_materials_volume"
prereadTypes: import("/Users/donmccurdy/Documents/Projects/glTF-Transform/packages/core/src/constants").PropertyType[]
prewriteTypes: import("/Users/donmccurdy/Documents/Projects/glTF-Transform/packages/core/src/constants").PropertyType[]

Methods

  • dispose(): void
  • 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.

  • listProperties(): ExtensionProperty[]
  • 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.

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.