Skip to main content

Clearcoat

Clearcoat adds a secondary glossy layer over a base surface, useful for varnish, lacquer, and automotive paint.

The CompareClearcoat sample demonstrates this capability. Drag to orbit and scroll to zoom.

GitHub
Loading examplePreparing GPU resources…

PBRMaterial reference​

PBRMaterial from @luma.gl/experimental is a typed engine Material backed by the shared pbrMaterial shader module. Its material fields are defined by PBRMaterialUniforms from @luma.gl/shadertools. Pass them through createPBRMaterial(device, {uniforms}) or update them with material.setProps({pbrMaterial: {...}}).

The fields below are optional. Defaults are the shared shader defaults; imported assets can supply other values.

FieldTypeDefaultDescription
clearcoatFactornumber0Strength of the secondary clearcoat layer, in the range 0–1.
clearcoatRoughnessFactornumber0Roughness of the clearcoat layer, in the range 0–1.
clearcoatMapEnabledbooleanfalseEnables clearcoat-strength texture sampling.
clearcoatRoughnessMapEnabledbooleanfalseEnables clearcoat-roughness texture sampling.

PBRMaterialBindings​

Texture resources are supplied separately through PBRMaterialBindings. Each field below is optional and accepts Texture | null. createPBRMaterial() derives map-enabled flags from these resources. Enable the corresponding Model shader define listed below when supplying a texture; the helper does not choose the model shader defines.

FieldModel defineDescription
pbr_clearcoatSamplerHAS_CLEARCOATMAP: trueTexture resource for the clearcoat slot.
pbr_clearcoatRoughnessSamplerHAS_CLEARCOATROUGHNESSMAP: trueTexture resource for the clearcoatRoughness slot.
pbr_clearcoatNormalSamplerHAS_CLEARCOATNORMALMAP: trueTexture resource for the clearcoatNormal slot.

Supporting APIs​

createPBRMaterial​

createPBRMaterial(device, {uniforms, bindings, factory}) from @luma.gl/experimental returns a PBRMaterial. uniforms sets the fields listed above, bindings supplies material textures, and the optional factory shares a compatible binding schema across materials. The helper derives map-enabled flags from the supplied bindings; explicit uniform values take precedence.

MaterialFactory​

createPBRMaterialFactory(device) from @luma.gl/experimental creates a reusable engine MaterialFactory configured with the pbrMaterial shader module. Pass this factory to createPBRMaterial() when creating several compatible materials.

Material​

Material from @luma.gl/engine owns material uniforms and texture resources. setProps({pbrMaterial: {...}}) updates uniform values. Pass the material to a compatible Model through its material prop; models sharing it observe the same updates. Use clone({bindings: {...}}) when an appearance needs separate texture resources. Adding a texture or changing a shader feature may require matching defines and a compatible model shader layout.

See the materials guide and pbrMaterial reference.

The extended PBR shader path is disabled by default. Set USE_MATERIAL_EXTENSIONS: true in the Model construction defines to enable this feature; uniform values alone do not enable it. The glTF material parser supplies this define for imported extension materials.

Usage​

import {Model} from '@luma.gl/engine';
import {createPBRMaterial, type PBRMaterial} from '@luma.gl/experimental';

// device is an initialized Device.
const material: PBRMaterial = createPBRMaterial(device, {
  uniforms: {
    metallicRoughnessValues: [0.5, 0.4],
    clearcoatFactor: 1,
    clearcoatRoughnessFactor: 0.1
  }
});

// modelProps contains your existing shaders, geometry, and buffer layout.
const model = new Model(device, {
  ...modelProps,
  material,
  defines: {...modelProps.defines, USE_MATERIAL_EXTENSIONS: true}
});

glTF support​

KHR_materials_clearcoat supplies layer strength, roughness, and optional layer normal textures. The stock shader adds a secondary clearcoat lobe.

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

All engine features