Interface BaseMaterial3DOptions

Constructor options shared by every BaseMaterial3D subclass

Example

interface MyGlowMaterialOptions extends BaseMaterial3DOptions {
  intensity?: number;
}

interface BaseMaterial3DOptions {
    alpha?: number;
    alphaCutoff?: number;
    alphaMode?: AlphaMode;
    baseColor?: ColorSource;
    baseColorTexture?: Texture<TextureSource<any>>;
    descriptor?: ShaderDescriptorOptions;
    doubleSided?: boolean;
    extraBits?: readonly ShaderBit[];
    flatShading?: boolean;
    fog?: boolean;
    label?: string;
    passes?: Record<string, boolean | PassDescriptorOptions>;
    textures?: Record<string, Texture<TextureSource<any>> | undefined>;
    topology?: Topology;
    uvTransform?: Matrix;
    vertexColors?: boolean;
}

Hierarchy (View Summary)

BaseMaterial3DOptions
- PortalMaterialOptions
- ToonMaterialOptions

Index

Properties

alpha? alphaCutoff? alphaMode? baseColor? baseColorTexture? descriptor? doubleSided? extraBits? flatShading? fog? label? passes? textures? topology? uvTransform? vertexColors?

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`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` `Advanced`descriptor

descriptor?: ShaderDescriptorOptions

Shader bits for the material's main pass, for a custom material

The material's textures and data are laid out from bitsGpu, so bitsGl must declare the same texture names in the same order, or the constructor throws. A material whose bits change with its settings overrides BaseMaterial3D#getPrimaryDescriptor instead.

Example

new BaseMaterial3D({
  descriptor: { bitsGpu: [myBit], bitsGl: [myBit] },
});

`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` `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`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`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` `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`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 BaseMaterial3DOptions

Example

Hierarchy (View Summary)

Index

Properties

Properties

Optionalalpha

Default

Example

OptionalalphaCutoff

Default

Example

OptionalalphaMode

Default

Example

OptionalbaseColor

Example

OptionalbaseColorTexture

Default

Example

Optional Advanceddescriptor

Example

OptionaldoubleSided

Default

Example

Optional AdvancedextraBits

Example

OptionalflatShading

Default

Example

Optionalfog

Default

Example

Optionallabel

Example

Optionalpasses

Example

Optional Advancedtextures

Example

Optionaltopology

Example

OptionaluvTransform

Example

OptionalvertexColors

Default

Example

Settings

On This Page

`Optional`alpha

`Optional`alphaCutoff

`Optional`alphaMode

`Optional`baseColor

`Optional`baseColorTexture

`Optional` `Advanced`descriptor

`Optional`doubleSided

`Optional` `Advanced`extraBits

`Optional`flatShading

`Optional`fog

`Optional`label

`Optional`passes

`Optional` `Advanced`textures

`Optional`topology

`Optional`uvTransform

`Optional`vertexColors