KhronosPbrMaterial

public final class KhronosPbrMaterial implements 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 methods
void

Closes the KhronosPbrMaterial and releases its underlying graphics resources.
static final @NonNull KhronosPbrMaterial
@MainThread
create(@NonNull Session session, int alphaMode)

Asynchronously creates a KhronosPbrMaterial.
final void
@MainThread
setAlphaCutoff(@FloatRange(from = 0.0, to = 1.0) float alphaCutoff)

Sets the alpha cutoff threshold.
final void

Sets a linear multiplier for the base color.
final void

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

Sets a scalar multiplier for the clearcoat layer's intensity.
final void
@MainThread
setClearcoatNormalTexture(
    @NonNull Texture texture,
    @FloatRange(from = 0.0) float scale,
    @NonNull TextureSampler sampler
)

Sets the normal map texture for the clearcoat layer.
final void
@MainThread
setClearcoatRoughnessFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

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

Sets the clearcoat roughness texture.
final void

Sets the clearcoat intensity texture.
final void

Sets a linear multiplier for the emissive color.
final void
@MainThread
setEmissiveTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

Sets the emissive texture, defining light emitted by the material.
final void
@MainThread
setMetallicFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

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

Sets a texture defining metallic and roughness properties.
final void
@MainThread
setNormalTexture(
    @NonNull Texture texture,
    @FloatRange(from = 0.0) float scale,
    @NonNull TextureSampler sampler
)

Sets the normal map texture for surface detail.
final void
@MainThread
setOcclusionTexture(
    @NonNull Texture texture,
    @FloatRange(from = 0.0, to = 1.0) float strength,
    @NonNull TextureSampler sampler
)

Sets the ambient occlusion texture.
final void
@MainThread
setRoughnessFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

Sets a scalar multiplier for the material's roughness.
final void

Sets a linear multiplier for the sheen color.
final void

Sets the sheen color texture, for materials like fabric.
final void
@MainThread
setSheenRoughnessFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

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

Sets the sheen roughness texture.

Public methods

close

@MainThread
public void close()

Closes the KhronosPbrMaterial and releases its underlying graphics resources.

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

create

@MainThread
public static final @NonNull KhronosPbrMaterial create(@NonNull Session session, int alphaMode)

Asynchronously creates a KhronosPbrMaterial.

Parameters
@NonNull Session session

The active Session in which to create the material.
int alphaMode

The AlphaMode to use for the material.
Returns
@NonNull KhronosPbrMaterial

The newly created KhronosPbrMaterial.

setAlphaCutoff

Added in 1.0.0-alpha08
@MainThread
public final void setAlphaCutoff(@FloatRange(from = 0.0, to = 1.0) float alphaCutoff)

Sets the alpha cutoff threshold.

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

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

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
public final void setBaseColorFactor(@NonNull Vector4 factor)

Sets a linear multiplier for the base color.

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

Parameters
@NonNull Vector4 factor

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

setBaseColorTexture

Added in 1.0.0-alpha08
@MainThread
public final void setBaseColorTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

The Texture to be used as the base color texture, in sRGB color space.
@NonNull TextureSampler sampler

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

setClearcoatFactor

Added in 1.0.0-alpha08
@MainThread
public final void setClearcoatFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

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

Other methods for controlling the clearcoat layer include:

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

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
public final void setClearcoatNormalTexture(
    @NonNull Texture texture,
    @FloatRange(from = 0.0) float scale,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

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

A scalar multiplier controlling the strength of the clearcoat normal. Default is 1.0.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the texture.

setClearcoatRoughnessFactor

Added in 1.0.0-alpha08
@MainThread
public final void setClearcoatRoughnessFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

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

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

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
public final void setClearcoatRoughnessTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

The Texture to be used. It defines the clearcoat layer's roughness, using the green channel in linear space.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the texture.

setClearcoatTexture

Added in 1.0.0-alpha08
@MainThread
public final void setClearcoatTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

The Texture to be used. The texture defines the clearcoat layer's strength, using the red channel in linear space.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the texture.

setEmissiveFactor

Added in 1.0.0-alpha08
@MainThread
public final void setEmissiveFactor(@NonNull Vector3 factor)

Sets a linear multiplier for the emissive color.

By default this is 0, 0, 0.

Parameters
@NonNull Vector3 factor

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

setEmissiveTexture

Added in 1.0.0-alpha08
@MainThread
public final void setEmissiveTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

The Texture to be used as the emissive texture, in sRGB color space.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the emissive texture.

setMetallicFactor

Added in 1.0.0-alpha08
@MainThread
public final void setMetallicFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

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

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

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
public final void setMetallicRoughnessTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

The Texture to be used. The texture must use its blue channel for metallic and green channel for roughness, in linear space.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the texture.

setNormalTexture

Added in 1.0.0-alpha08
@MainThread
public final void setNormalTexture(
    @NonNull Texture texture,
    @FloatRange(from = 0.0) float scale,
    @NonNull TextureSampler sampler
)

Sets the normal map texture for surface detail.

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

Parameters
@NonNull Texture texture

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

A scalar multiplier controlling the strength of the normal map. Default is 1.0.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the normal texture.

setOcclusionTexture

Added in 1.0.0-alpha08
@MainThread
public final void setOcclusionTexture(
    @NonNull Texture texture,
    @FloatRange(from = 0.0, to = 1.0) float strength,
    @NonNull TextureSampler sampler
)

Sets the ambient occlusion texture.

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

Parameters
@NonNull Texture texture

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

A scalar multiplier controlling the strength of the occlusion. Default is 1.0. Valid values are between 0.0 and 1.0, inclusive.
@NonNull TextureSampler sampler

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
public final void setRoughnessFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

Sets a scalar multiplier for the material's roughness.

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

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
public final void setSheenColorFactor(@NonNull Vector3 factor)

Sets a linear multiplier for the sheen color.

By default this is 0, 0, 0.

Parameters
@NonNull Vector3 factor

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

setSheenColorTexture

Added in 1.0.0-alpha08
@MainThread
public final void setSheenColorTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

The Texture to be used, in sRGB.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the texture.

setSheenRoughnessFactor

Added in 1.0.0-alpha08
@MainThread
public final void setSheenRoughnessFactor(@FloatRange(from = 0.0, to = 1.0) float factor)

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

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

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
public final void setSheenRoughnessTexture(
    @NonNull Texture texture,
    @NonNull TextureSampler sampler
)

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
@NonNull Texture texture

The Texture to be used. It defines the sheen layer's roughness, using the alpha channel in linear space.
@NonNull TextureSampler sampler

The TextureSampler to be used when sampling the texture.