Metallic and rough surfaces

Base color, metallic response, and roughness describe surfaces ranging from matte dielectrics to polished metals.

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

GitHub

Loading examplePreparing GPU resources…

Scroll page · Ctrl/⌘ + scroll to interact

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.

Field	Type	Default	Description
baseColorFactor	Readonly<Vector4 | NumberArray4>	[1, 1, 1, 1]	RGBA base color multiplied by the base-color texture when enabled.
metallicRoughnessValues	Readonly<Vector2 | NumberArray2>	[1, 1]	Metallic factor followed by roughness, each in the range 0–1.
baseColorMapEnabled	boolean	false	Enables base-color texture sampling.
metallicRoughnessMapEnabled	boolean	false	Enables metallic-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.

Field	Model define	Description
pbr_baseColorSampler	HAS_BASECOLORMAP: true	Texture resource for the baseColor slot.
pbr_metallicRoughnessSampler	HAS_METALROUGHNESSMAP: true	Texture resource for the metallicRoughness 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.

Usage

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

// device is an initialized Device.
const material: PBRMaterial = createPBRMaterial(device, {
  uniforms: {
    baseColorFactor: [0.8, 0.5, 0.2, 1],
    metallicRoughnessValues: [0.7, 0.25]
  }
});

// Pass material to a compatible Model through its material prop.

See base color, ambient occlusion, and opacity and cutouts for independent surface inputs.

glTF support

Core glTF pbrMetallicRoughness supplies these values without an extension. The adapter maps metallicFactor and roughnessFactor into the canonical pair. The metallic-roughness texture uses blue for metallic and green for roughness. Legacy KHR_materials_pbrSpecularGlossiness data is preserved by the loader but is not converted into this shader path.

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

All engine features