KhronosPbrMaterial

class KhronosPbrMaterial : Material

Represents a lit PBR (Physically-Based Rendering) material, which defines the visual appearance of a surface by simulating its interaction with light.

This material implements the Khronos PBR (Physically-Based Rendering) metallic-roughness model. It is a direct implementation of the following glTF features:

Summary

Public companion functions
suspend KhronosPbrMaterial
@MainThread
create(session: Session, alphaMode: Int)

Asynchronously creates a KhronosPbrMaterial.

Public functions
open Unit

Closes the KhronosPbrMaterial and releases its underlying graphics resources.
Unit
@MainThread
setAlphaCutoff(alphaCutoff: @FloatRange(from = 0.0, to = 1.0) Float)

Sets the alpha cutoff threshold.
Unit

Sets a linear multiplier for the base color.
Unit

Sets the material's base color using a texture.
Unit
@MainThread
setClearcoatFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float)

Sets a scalar multiplier for the clearcoat layer's intensity.
Unit
@MainThread
setClearcoatNormalTexture(
    texture: Texture,
    scale: @FloatRange(from = 0.0) Float,
    sampler: TextureSampler
)

Sets the normal map texture for the clearcoat layer.
Unit
@MainThread
setClearcoatRoughnessFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float)

Sets a scalar multiplier for the clearcoat layer's roughness.
Unit

Sets the clearcoat roughness texture.
Unit

Sets the clearcoat intensity texture.
Unit

Sets a linear multiplier for the emissive color.
Unit

Sets the emissive texture, defining light emitted by the material.
Unit
@MainThread
setMetallicFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float)

Sets a scalar multiplier for the material's metallic property.
Unit

Sets a texture defining metallic and roughness properties.
Unit
@MainThread
setNormalTexture(
    texture: Texture,
    scale: @FloatRange(from = 0.0) Float,
    sampler: TextureSampler
)

Sets the normal map texture for surface detail.
Unit
@MainThread
setOcclusionTexture(
    texture: Texture,
    strength: @FloatRange(from = 0.0, to = 1.0) Float,
    sampler: TextureSampler
)

Sets the ambient occlusion texture.
Unit
@MainThread
setRoughnessFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float)

Sets a scalar multiplier for the material's roughness.
Unit

Sets a linear multiplier for the sheen color.
Unit

Sets the sheen color texture, for materials like fabric.
Unit
@MainThread
setSheenRoughnessFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float)

Sets a scalar multiplier for the sheen layer's roughness.
Unit

Sets the sheen roughness texture.

Public companion functions

create

@MainThread
suspend fun create(session: Session, alphaMode: Int): KhronosPbrMaterial

Asynchronously creates a KhronosPbrMaterial.

Parameters
session: Session

The active Session in which to create the material.
alphaMode: Int

The AlphaMode to use for the material.
Returns
KhronosPbrMaterial

The newly created KhronosPbrMaterial.

Public functions

close

@MainThread
open fun close(): Unit

Closes the KhronosPbrMaterial and releases its underlying graphics resources.

After being closed, the KhronosPbrMaterial should not be used further.

setAlphaCutoff

Added in 1.0.0-alpha08
@MainThread
fun setAlphaCutoff(alphaCutoff: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Sets the alpha cutoff threshold.

This value is only used when the material's alphaMode is AlphaMode.ALPHA_MODE_MASK.

Parameters
alphaCutoff: @FloatRange(from = 0.0, to = 1.0) Float

The alpha cutoff. Fragments with alpha below this value are discarded. Default is 0.5. Valid values are between 0.0 and 1.0, inclusive.
Throws
kotlin.IllegalArgumentException

if the material's alphaMode is not ALPHA_MODE_MASK.

setBaseColorFactor

Added in 1.0.0-alpha08
@MainThread
fun setBaseColorFactor(factor: Vector4): Unit

Sets a linear multiplier for the base color.

By default this is 1, 1, 1, 1.

Parameters
factor: Vector4

The Vector4 (RGBA) factor multiplied component-wise with the base color texture.

setBaseColorTexture

Added in 1.0.0-alpha08
@MainThread
fun setBaseColorTexture(
    texture: Texture,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the material's base color using a texture.

By default this is a white texture, where all pixels are 1, 1, 1, 1. In other words, if this is left as default, the base color will always be the base color factor.

Parameters
texture: Texture

The Texture to be used as the base color texture, in sRGB color space.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the base color texture.

setClearcoatFactor

Added in 1.0.0-alpha08
@MainThread
fun setClearcoatFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Sets a scalar multiplier for the clearcoat layer's intensity.

Other methods for controlling the clearcoat layer include:

Parameters
factor: @FloatRange(from = 0.0, to = 1.0) Float

The clearcoat intensity factor. Default is 0.0. Valid values are between 0.0 and 1.0, inclusive.

setClearcoatNormalTexture

Added in 1.0.0-alpha08
@MainThread
fun setClearcoatNormalTexture(
    texture: Texture,
    scale: @FloatRange(from = 0.0) Float = 1.0f,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the normal map texture for the clearcoat layer.

By default the texture is unset, in which case no normal mapping is done for the clearcoat, even if the base color has normal mapping.

Parameters
texture: Texture

The Texture to be used as the clearcoat normal texture, in tangent space and linear color.
scale: @FloatRange(from = 0.0) Float = 1.0f

A scalar multiplier controlling the strength of the clearcoat normal. Default is 1.0.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the texture.

setClearcoatRoughnessFactor

Added in 1.0.0-alpha08
@MainThread
fun setClearcoatRoughnessFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Sets a scalar multiplier for the clearcoat layer's roughness.

Parameters
factor: @FloatRange(from = 0.0, to = 1.0) Float

The clearcoat roughness factor. Default is 0.0. Valid values are between 0.0 and 1.0, inclusive.

setClearcoatRoughnessTexture

Added in 1.0.0-alpha08
@MainThread
fun setClearcoatRoughnessTexture(
    texture: Texture,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the clearcoat roughness texture.

By default this is a white texture, where all pixels are 1, 1, 1, 1. In other words, if this is left as default, the clearcoat roughness values will always come from the clearcoat roughness factor.

Parameters
texture: Texture

The Texture to be used. It defines the clearcoat layer's roughness, using the green channel in linear space.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the texture.

setClearcoatTexture

Added in 1.0.0-alpha08
@MainThread
fun setClearcoatTexture(
    texture: Texture,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the clearcoat intensity texture.

By default this is a white texture, where all pixels are 1, 1, 1, 1. In other words, if this is left as default, the clearcoat intensity values will always come from the clearcoat factor.

Parameters
texture: Texture

The Texture to be used. The texture defines the clearcoat layer's strength, using the red channel in linear space.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the texture.

setEmissiveFactor

Added in 1.0.0-alpha08
@MainThread
fun setEmissiveFactor(factor: Vector3): Unit

Sets a linear multiplier for the emissive color.

By default this is 0, 0, 0.

Parameters
factor: Vector3

The Vector3 (in red, green, blue format) factor multiplied component-wise with the emissive texture.

setEmissiveTexture

Added in 1.0.0-alpha08
@MainThread
fun setEmissiveTexture(
    texture: Texture,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the emissive texture, defining light emitted by the material.

By default this is a white texture, where all pixels are 1, 1, 1, 1. In other words, if this is left as default, the emissive values will always come from the emissive factor.

Parameters
texture: Texture

The Texture to be used as the emissive texture, in sRGB color space.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the emissive texture.

setMetallicFactor

Added in 1.0.0-alpha08
@MainThread
fun setMetallicFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Sets a scalar multiplier for the material's metallic property.

Parameters
factor: @FloatRange(from = 0.0, to = 1.0) Float

The metallic factor. Default is 1.0. Valid values are between 0.0 and 1.0, inclusive.

setMetallicRoughnessTexture

Added in 1.0.0-alpha08
@MainThread
fun setMetallicRoughnessTexture(
    texture: Texture,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets a texture defining metallic and roughness properties.

By default this is a white texture, where all pixels are 1, 1, 1, 1. In other words, if this is left as default, the metalic and roughness values will always come from the corresponding factors.

Parameters
texture: Texture

The Texture to be used. The texture must use its blue channel for metallic and green channel for roughness, in linear space.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the texture.

setNormalTexture

Added in 1.0.0-alpha08
@MainThread
fun setNormalTexture(
    texture: Texture,
    scale: @FloatRange(from = 0.0) Float = 1.0f,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the normal map texture for surface detail.

By default the texture is unset, in which case no normal mapping is done.

Parameters
texture: Texture

The Texture to be used as the normal map, in tangent space and linear color.
scale: @FloatRange(from = 0.0) Float = 1.0f

A scalar multiplier controlling the strength of the normal map. Default is 1.0.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the normal texture.

setOcclusionTexture

Added in 1.0.0-alpha08
@MainThread
fun setOcclusionTexture(
    texture: Texture,
    strength: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the ambient occlusion texture.

By default this is unset, in which case there is no ambient occlusion.

Parameters
texture: Texture

The Texture to be used. It must use the red channel in linear space.
strength: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f

A scalar multiplier controlling the strength of the occlusion. Default is 1.0. Valid values are between 0.0 and 1.0, inclusive.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the texture.
Throws
kotlin.IllegalArgumentException

if strength is outside of the range 0-1, inclusive.

setRoughnessFactor

Added in 1.0.0-alpha08
@MainThread
fun setRoughnessFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Sets a scalar multiplier for the material's roughness.

Parameters
factor: @FloatRange(from = 0.0, to = 1.0) Float

The roughness factor. Default is 1.0. Valid values are between 0.0 and 1.0, inclusive.

setSheenColorFactor

Added in 1.0.0-alpha08
@MainThread
fun setSheenColorFactor(factor: Vector3): Unit

Sets a linear multiplier for the sheen color.

By default this is 0, 0, 0.

Parameters
factor: Vector3

The Vector3 (RGB) factor multiplied component-wise with the sheen color texture.

setSheenColorTexture

Added in 1.0.0-alpha08
@MainThread
fun setSheenColorTexture(
    texture: Texture,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the sheen color texture, for materials like fabric.

By default this is a white texture, where all pixels are 1, 1, 1, 1. In other words, if this is left as default, the sheen color values will always come from the sheen color factor.

Parameters
texture: Texture

The Texture to be used, in sRGB.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the texture.

setSheenRoughnessFactor

Added in 1.0.0-alpha08
@MainThread
fun setSheenRoughnessFactor(factor: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Sets a scalar multiplier for the sheen layer's roughness.

Parameters
factor: @FloatRange(from = 0.0, to = 1.0) Float

The sheen roughness factor. Default is 0.0. Valid values are between 0.0 and 1.0, inclusive.

setSheenRoughnessTexture

Added in 1.0.0-alpha08
@MainThread
fun setSheenRoughnessTexture(
    texture: Texture,
    sampler: TextureSampler = TextureSampler()
): Unit

Sets the sheen roughness texture.

By default this is a white texture, where all pixels are 1, 1, 1, 1. In other words, if this is left as default, the sheen roughness values will always come from the sheen roughness factor.

Parameters
texture: Texture

The Texture to be used. It defines the sheen layer's roughness, using the alpha channel in linear space.
sampler: TextureSampler = TextureSampler()

The TextureSampler to be used when sampling the texture.