filament/io.github.erkko68.filament/MaterialInstance

MaterialInstance

class MaterialInstance(nativeHandle: NativePointer)

MaterialInstance customizes the parameters of a Material for per-object rendering.

Each Material can spawn multiple MaterialInstances with different parameter values (colors, textures, numeric uniforms, etc.). Changes to a MaterialInstance only affect renderables using that specific instance, not the Material or other instances.

Creating and destroying: Create instances via Material.createInstance() and destroy with Engine.destroy(instance). You can duplicate an existing instance using the companion object's duplicate() method.

Setting parameters: Use setParameter() overloads to set uniforms (booleans, floats, vectors, matrices, textures). Parameter names and types must match those defined in the material. Array parameters are also supported via setParameter(name, element, array, offset, count) variants.

Rendering state customization: Each MaterialInstance can override per-instance rendering behavior:

Scissor rectangle for pixel-perfect clipping
Polygon offset for depth artifacts
Culling mode (override material's cull setting)
Depth test configuration
Stencil test and operations
Color and depth write masks

These settings override the Material's defaults.

Constructors

MaterialInstance

constructor(nativeHandle: NativePointer)

Types

BooleanElement

enum BooleanElement : Enum<MaterialInstance.BooleanElement>

Element types for boolean parameter arrays.

Companion

object Companion

FloatElement

enum FloatElement : Enum<MaterialInstance.FloatElement>

Element types for floating-point parameter arrays.

IntElement

enum IntElement : Enum<MaterialInstance.IntElement>

Element types for integer parameter arrays.

StencilFace

enum StencilFace : Enum<MaterialInstance.StencilFace>

Which face(s) the stencil operation applies to.

StencilOperation

enum StencilOperation : Enum<MaterialInstance.StencilOperation>

Stencil test operation determines how the stencil buffer is modified.

UIntElement

enum UIntElement : Enum<MaterialInstance.UIntElement>

Element types for unsigned integer parameter arrays, passed as IntArray bit patterns.

Properties

cullingMode

var cullingMode: Material.CullingMode

Gets/sets the face culling mode, for both the color and shadow passes.

depthFunc

var depthFunc: TextureSampler.CompareFunc

Gets/sets the depth function.

isColorWriteEnabled

var isColorWriteEnabled: Boolean

Gets/sets whether color write is enabled.

isDepthCullingEnabled

var isDepthCullingEnabled: Boolean

Gets/sets whether depth culling (depth testing) is enabled.

isDepthWriteEnabled

var isDepthWriteEnabled: Boolean

Gets/sets whether depth write is enabled.

isDoubleSided

var isDoubleSided: Boolean

Gets/sets whether double-sided lighting is enabled.

isStencilWriteEnabled

var isStencilWriteEnabled: Boolean

Gets/sets whether stencil write is enabled.

maskThreshold

var maskThreshold: Float

Gets/sets the alpha mask threshold for masked blending mode.

material

val material: Material

The Material associated with this instance.

name

val name: String

The name associated with this instance.

nativeObject

val nativeObject: NativePointer

The native object, for interop with code calling the Fila* C API directly. Read-only: this wrapper owns it.

shadowCullingMode

val shadowCullingMode: Material.CullingMode

The face culling mode for the shadow passes.

specularAntiAliasingThreshold

var specularAntiAliasingThreshold: Float

Gets/sets the clamping threshold used to suppress estimation errors when applying specular anti-aliasing.

specularAntiAliasingVariance

var specularAntiAliasingVariance: Float

Gets/sets the screen space variance of the filter kernel used when applying specular anti-aliasing.

transparencyMode

var transparencyMode: Material.TransparencyMode

Gets/sets the transparency rendering mode.

Functions

commit

fun commit(engine: Engine)

Uploads this instance's pending parameter changes. The engine does this for every instance it renders; call it for instances only used outside of rendering, e.g. by compute.

compile

fun compile(priority: Material.CompilerPriorityQueue, variants: Int = UserVariantFilterBit.ALL, callback: (MaterialInstance) -> Unit? = null)

Asynchronously ensures that a subset of this MaterialInstance's variants are compiled, taking its specialization constants into account.

getConstantBoolean

fun getConstantBoolean(name: String): Boolean

Returns the boolean value of a specialization constant.

getConstantFloat

fun getConstantFloat(name: String): Float

Returns the float value of a specialization constant.

getConstantInt

fun getConstantInt(name: String): Int

Returns the integer value of a specialization constant.

getParameter

fun getParameter(name: String, element: MaterialInstance.FloatElement): FloatArray

Gets the value of a float parameter.

fun getParameter(name: String, element: MaterialInstance.IntElement): IntArray

Gets the value of an integer parameter.

fun getParameter(name: String, element: MaterialInstance.UIntElement): IntArray

Gets the value of an unsigned integer parameter.

setConstant

fun setConstant(name: String, value: Boolean)

fun setConstant(name: String, value: Float)

fun setConstant(name: String, value: Int)

Sets the value of a specialization constant, overriding the Material's. Panics if the constant doesn't exist or has another type. Compiles new programs when the value changes, so prefer Material.Builder.constant where the value is known up front.

setCullingMode