API
Babylon Lite API|
ShaderMaterialOptions

Interface ShaderMaterialOptions

Options describing a ShaderMaterial: WGSL sources, attributes, uniforms, samplers, external textures, defines, and blend/depth state. Passed to createShaderMaterial().

interface ShaderMaterialOptions {
    attributes: readonly ShaderAttributeName[];
    backFaceCulling?: boolean;
    blend?: GPUBlendState;
    blendMode?: "additive" | "alpha";
    defines?: Readonly<Record<string, ShaderDefineValue>>;
    depthBias?: number;
    depthBiasSlopeScale?: number;
    depthCompare?: GPUCompareFunction;
    depthOnlyFragment?: boolean;
    depthWrite?: boolean;
    externalTextures?: readonly string[];
    fragmentSource: WgslSource;
    name?: string;
    needAlphaBlending?: boolean;
    needAlphaTesting?: boolean;
    samplers?: readonly ShaderSamplerOption[];
    storageBuffers?: readonly ShaderStorageBufferDecl[];
    topology?: "point-list" | "line-list" | "triangle-list";
    transmissive?: boolean;
    uniforms?: readonly ShaderUniformOption[];
    useThinInstanceColors?: boolean;
    vertexSource: WgslSource;
}
Index
attributes backFaceCulling? blend? blendMode? defines? depthBias? depthBiasSlopeScale? depthCompare? depthOnlyFragment? depthWrite? externalTextures? fragmentSource name? needAlphaBlending? needAlphaTesting? samplers? storageBuffers? topology? transmissive? uniforms? useThinInstanceColors? vertexSource
attributes: readonly ShaderAttributeName[]
backFaceCulling?: boolean
blend?: GPUBlendState

Explicit color-target blend state. When provided it REPLACES the blend needAlphaBlending/ blendMode would have chosen entirely — e.g. a material compositing color as ordinary src-over while stamping the target's ALPHA channel to a fixed value (alpha zero/zero).

blendMode?: "additive" | "alpha"

Blend equation used when needAlphaBlending is set. "alpha" (default) is standard src-over; "additive" adds the fragment's premultiplied-by-alpha color to the framebuffer, which is the right choice for glows/light FX.

defines?: Readonly<Record<string, ShaderDefineValue>>
depthBias?: number

Constant depth-bias added in the pipeline's depth-stencil state (units of the depth format's minimum representable value). Lets a surface that hugs another (e.g. tiles overlapping a cone, decals) win the depth test consistently and avoid z-fighting. Default 0 (no bias).

depthBiasSlopeScale?: number

Slope-scaled depth bias — extra bias proportional to the depth gradient, so steeply-angled (grazing) surfaces get more bias. Pairs with depthBias to kill z-fighting at oblique angles. Default 0.

depthCompare?: GPUCompareFunction
depthOnlyFragment?: boolean

Compile/run the fragment stage even for depth-only render targets (no colour attachments). Use for depth-only casters that need discard (alpha/clip masks). The fragment shader must not declare colour outputs when drawn into a depth-only target. Default false.

depthWrite?: boolean

Depth-buffer writes for this material's draws. Defaults to true for opaque materials and false for alpha-blended ones (needAlphaBlending). An EXPLICIT value always wins: a blended volume/veil may set depthWrite: true to publish its fragment depth so later draws depth-test against it instead of compositing over it.

externalTextures?: readonly string[]
fragmentSource: WgslSource
name?: string
needAlphaBlending?: boolean
needAlphaTesting?: boolean
samplers?: readonly ShaderSamplerOption[]
storageBuffers?: readonly ShaderStorageBufferDecl[]
topology?: "point-list" | "line-list" | "triangle-list"

Primitive topology for this material. Defaults to triangle-list. Strip topologies are not supported because their required index format is mesh-specific.

transmissive?: boolean

Mark this surface as transmissive/refractive: the renderer grabs the opaque scene color behind it just before it draws, so the fragment can sample what is through it (water, glass). Requires needAlphaBlending (the surface composites over the grabbed scene color). Enable the scene-color grab on the surface's render task with enableRenderTaskTransmission, then bind the resulting texture via setShaderTexture. Default false.

uniforms?: readonly ShaderUniformOption[]
useThinInstanceColors?: boolean

Bind and inject the mesh's optional thin-instance RGBA stream for this material. Disable on color-independent overrides (for example a depth caster) that need only the instance matrices.

vertexSource: WgslSource