Interface Material3DOptions

Options for Material3D

Each extension (emissive, specular, iridescence, transmission, clearcoat, sheen, anisotropy) is a group that turns the feature on when passed, even empty: clearcoat: {} adds a full-strength coat. Inside a group, each factor and strength defaults to 1 and each colour to white; the glTF loader passes each extension's own defaults instead.

Example

const options: Material3DOptions = { baseColor: 0x8c1c13, roughness: 0.4, clearcoat: {} };
const carPaint = new Material3D(options);

interface Material3DOptions {
    alpha?: number;
    alphaCutoff?: number;
    alphaMode?: AlphaMode;
    anisotropy?: AnisotropyOptions;
    baseColor?: ColorSource;
    baseColorTexture?: Texture<TextureSource<any>>;
    clearcoat?: ClearcoatOptions;
    doubleSided?: boolean;
    emissive?: EmissiveOptions;
    extraBits?: readonly ShaderBit[];
    flatShading?: boolean;
    fog?: boolean;
    ior?: number;
    iridescence?: IridescenceOptions;
    label?: string;
    metallic?: number;
    metallicRoughnessTexture?: Texture<TextureSource<any>>;
    normalScale?: number;
    normalTexture?: Texture<TextureSource<any>>;
    occlusionStrength?: number;
    occlusionTexture?: Texture<TextureSource<any>>;
    passes?: Record<string, boolean | PassDescriptorOptions>;
    roughness?: number;
    sheen?: SheenOptions;
    specular?: SpecularOptions;
    textures?: Record<string, Texture<TextureSource<any>> | undefined>;
    topology?: Topology;
    transmission?: TransmissionOptions;
    uvTransform?: Matrix;
    vertexColors?: boolean;
}

Hierarchy

Omit<BaseMaterial3DOptions, "descriptor">
- Material3DOptions

Properties

`Optional`alpha

alpha?: number

Base opacity; alphaMode: 'opaque' ignores it

Default

Example

new Material3D({ alphaMode: 'blend', alpha: 0.4 });

`Optional`alphaCutoff

alphaCutoff?: number

Alpha below which fragments are discarded when alphaMode is 'mask'

Default

0.5

Example

new Material3D({ baseColorTexture: leafTexture, alphaMode: 'mask', alphaCutoff: 0.3 });

`Optional`alphaMode

alphaMode?: AlphaMode

How alpha is treated; see AlphaMode

Default

'opaque'

Example

new Material3D({ baseColorTexture: leafTexture, alphaMode: 'mask' });

`Optional`anisotropy

anisotropy?: AnisotropyOptions

Highlights stretched along one direction; passing the group turns it on

Example

const pan = new Material3D({ metallic: 1, anisotropy: {} });

`Optional`baseColor

baseColor?: ColorSource

Base colour tint; the source's alpha is ignored, BaseMaterial3DOptions#alpha sets opacity

Example

new Material3D({ baseColor: 0xff7733 });

`Optional`baseColorTexture

baseColorTexture?: Texture<TextureSource<any>>

Base colour (albedo) texture

Default

Texture.WHITE

Example

new Material3D({ baseColorTexture: crateTexture });

`Optional`clearcoat

clearcoat?: ClearcoatOptions

Clear lacquer layer on top; passing the group turns it on

Example

const pianoBlack = new Material3D({ baseColor: 0x050505, clearcoat: {} });

`Optional`doubleSided

doubleSided?: boolean

When true, back faces are drawn too and lit with their normal flipped

Fixed at construction.

Default

false

Example

new Material3D({ baseColorTexture: leafTexture, alphaMode: 'mask', doubleSided: true });

`Optional`emissive

emissive?: EmissiveOptions

The material's own glow; passing the group turns it on

Example

const lava = new Material3D({ emissive: { texture: lavaGlow, strength: 4 } });

`Optional` `Advanced`extraBits

extraBits?: readonly ShaderBit[]

Extra shader bits composed into the material's shader, fixed for its lifetime

Material3D, PhongMaterial and FlatMaterial each document where they sit in their bit list; on a material built from a raw descriptor, as ToonMaterial and PortalMaterial are, they follow its bits. A bit may declare material fields and textures; fill its textures through the textures option, or later through BaseMaterial3D#textures. A bit that uses PI or INV_PI lists mathConstantsBit in its ShaderBit#requires rather than declaring them, and one that calls screenUVFromWorld or sampleScreenCopy lists screenSpaceFuncsBit. To add bits to a material that exists, such as one the glTF loader built, material.clone({ extraBits }) makes a copy with them and everything else the material has. For billboarding, set Mesh3D#billboardMode instead.

Example

new Material3D({ baseColor: 0xff3355, extraBits: [glossBit] });

`Optional`flatShading

flatShading?: boolean

When true, each triangle is shaded with its face normal instead of the smooth vertex normal

Gives a faceted, low-poly look with no duplicated vertices, so one geometry can draw smooth or faceted depending on its material. A normal map still applies on top. No visible effect on an unlit material such as FlatMaterial. Fixed at construction.

Default

false

Example

new Material3D({ baseColor: 0x8a7f72, flatShading: true });

`Optional`fog

fog?: boolean

Whether the view's distance fog may reach this material

Turn it off for skyboxes, water and anything else with its own distance falloff; a sky dome past the fog's far distance would turn flat fog colour. Fixed at construction.

Default

true

Example

new Material3D({ baseColorTexture: skyTexture, fog: false });

`Optional`ior

ior?: number

Index of refraction, see Material3D#ior

Default

1.5

Example

const water = new Material3D({ ior: 1.33, transmission: { thickness: 1 } });

`Optional`iridescence

iridescence?: IridescenceOptions

Thin-film colour shift; passing the group turns it on

Example

const soapBubble = new Material3D({ iridescence: {}, transmission: {} });

`Optional`label

label?: string

Name for debugging and for finding the material; the glTF loader sets it to the name in the file

Example

new Material3D({ label: 'Paint' });

`Optional`metallic

metallic?: number

Metalness, from 0 (non-metal) to 1 (metal)

Default

Example

const gold = new Material3D({ baseColor: 0xffc356, metallic: 1, roughness: 0.25 });

`Optional`metallicRoughnessTexture

metallicRoughnessTexture?: Texture<TextureSource<any>>

Map with roughness in green and metalness in blue, as in glTF; scales roughness and metallic

Example

const rusty = new Material3D({ metallic: 1, metallicRoughnessTexture: rustMap });

`Optional`normalScale

normalScale?: number

Strength of the normal map's bumps

Default

Example

const shallow = new Material3D({ normalTexture: brickNormals, normalScale: 0.5 });

`Optional`normalTexture

normalTexture?: Texture<TextureSource<any>>

Tangent-space normal map, green up as in glTF and OpenGL

Invert the green channel of a DirectX-style map, or its bumps light from the wrong side. Needs UVs on the geometry, and uses its tangents when it has them. Can be assigned later through material.textures.normal; a material without one pays nothing for normal mapping.

Example

const bricks = new Material3D({ baseColorTexture: brickColour, normalTexture: brickNormals });

`Optional`occlusionStrength

occlusionStrength?: number

Multiplier on the occlusion, see Material3D#occlusionStrength

Default

Example

const softer = new Material3D({ occlusionTexture: crateOcclusion, occlusionStrength: 0.8 });

`Optional`occlusionTexture

occlusionTexture?: Texture<TextureSource<any>>

Ambient occlusion map, read from red; it darkens ambient and environment light only

Example

const crate = new Material3D({ baseColorTexture: crateColour, occlusionTexture: crateOcclusion });

`Optional`passes

passes?: Record<string, boolean | PassDescriptorOptions>

Extra render passes this material draws in, keyed by the pass's name

true: draw in the pass with the pass's own shader and state.
a PassDescriptorOptions object: draw in it with your own shader, state or topology. PassDescriptor says how these combine with the pass's own; they can't change later.
false, or left out: don't draw in it. Useful for opting out of a pass that spread options or a subclass default turned on.

A material can name a pass before the pass exists. A page has room for 24 custom pass names, 'outline' included, each taken the first time anything names it; a name past that joins nothing, and a pass with it draws no meshes, without a warning.

Example

view.passes = [new OutlinePass({ width: 0.05 })];
const hero = new Material3D({ baseColor: 0xff7733, passes: { outline: true } });

`Optional`roughness

roughness?: number

Perceptual roughness, from 0 (mirror-like) to 1 (fully rough)

Default

Example

const polished = new Material3D({ roughness: 0.1 });

`Optional`sheen

sheen?: SheenOptions

Cloth sheen; passing the group turns it on

Example

const cushion = new Material3D({ sheen: { color: 0xffffff, roughness: 0.5 } });

`Optional`specular

specular?: SpecularOptions

Strength and tint of non-metal reflections; passing the group turns it on

Example

const lacquer = new Material3D({ specular: { color: 0xfff4e0 } });

`Optional` `Advanced`textures

textures?: Record<string, Texture<TextureSource<any>> | undefined>

Textures by slot name, for the slots a descriptor or extraBits declares

The bits' textures arrays decide which slots exist; this map only fills them. A slot left out gets Texture.WHITE. A baseColor entry here wins over BaseMaterial3DOptions#baseColorTexture.

Example

new BaseMaterial3D({
  descriptor: { bitsGpu: [waterBit], bitsGl: [waterBit] },
  textures: { waterNormal: waterNormalTexture },
});

`Optional`topology

topology?: Topology

Primitive topology for every pass that doesn't set its own; left out, the geometry's is used

'line-list' joins the indices in pairs, so a triangle index buffer drawn that way isn't a wireframe: it draws some edges and misses others. Use a geometry with line indices for that.

Example

new FlatMaterial({ baseColor: 0x00ff00, topology: 'point-list' });

`Optional`transmission

transmission?: TransmissionOptions

Glass and other see-through surfaces; passing the group turns it on

Example

const pane = new Material3D({ roughness: 0, transmission: {} });

`Optional`uvTransform

uvTransform?: Matrix

UV transform for every texture of the material; see BaseMaterial3D#uvTransform

Leave it out to let a framed (spritesheet) base colour texture set the transform.

Example

new Material3D({ baseColorTexture: tileTexture, uvTransform: new Matrix().scale(4, 4) });

`Optional`vertexColors

vertexColors?: boolean

Whether a geometry's vertex colours (its colors) tint this material; see BaseMaterial3D#vertexColors

Default

false

Example

new Material3D({ vertexColors: true });

Interface Material3DOptions

Example

Hierarchy

Index

Properties

Properties

Optionalalpha

Default

Example

OptionalalphaCutoff

Default

Example

OptionalalphaMode

Default

Example

Optionalanisotropy

Example

OptionalbaseColor

Example

OptionalbaseColorTexture

Default

Example

Optionalclearcoat

Example

OptionaldoubleSided

Default

Example

Optionalemissive

Example

Optional AdvancedextraBits

Example

OptionalflatShading

Default

Example

Optionalfog

Default

Example

Optionalior

Default

Example

Optionaliridescence

Example

Optionallabel

Example

Optionalmetallic

Default

Example

OptionalmetallicRoughnessTexture

Example

OptionalnormalScale

Default

Example

OptionalnormalTexture

Example

OptionalocclusionStrength

Default

Example

OptionalocclusionTexture

Example

Optionalpasses

Example

Optionalroughness

Default

Example

Optionalsheen

Example

Optionalspecular

Example

Optional Advancedtextures

Example

Optionaltopology

Example

Optionaltransmission

Example

OptionaluvTransform

Example

OptionalvertexColors

Default

Example

Settings

`Optional`alpha

`Optional`alphaCutoff

`Optional`alphaMode

`Optional`anisotropy

`Optional`baseColor

`Optional`baseColorTexture

`Optional`clearcoat

`Optional`doubleSided

`Optional`emissive

`Optional` `Advanced`extraBits

`Optional`flatShading

`Optional`fog

`Optional`ior

`Optional`iridescence

`Optional`label

`Optional`metallic

`Optional`metallicRoughnessTexture

`Optional`normalScale

`Optional`normalTexture

`Optional`occlusionStrength

`Optional`occlusionTexture

`Optional`passes

`Optional`roughness

`Optional`sheen

`Optional`specular

`Optional` `Advanced`textures

`Optional`topology

`Optional`transmission

`Optional`uvTransform

`Optional`vertexColors