Class CarbonMaterialInstance

The CarbonMaterialInstance class implements a Material that is backend by a CarbonMaterial that owns the underlying shader. This allows changes to the parent Carbon Material while further customizing its exposed parameters and textures.

If the parent Carbon Material is updated with a new graph, the instance updates automatically. Carbon Material Instances are a powerful feature to reuse a shader but apply customization to minimize the number of shaders that must be compiled. It is advisable to use Carbon Material Instances whenever possible.

Hierarchy (view full)

Constructors

constructor

Accessors

carbonMaterial carbonMaterialHandle handle isDestroyed isValid metaData model name shader shaderHandle surfaceModelType techniqueCount uuid variation

Methods

compileTechniqueAsync dispatchComputeAsync duplicate getBoolean getBuffer getColor getColorGradient getFloat getFloatCurve getInt32 getMatrix3 getMatrix4 getSamplerState getSpriteImage getSpriteTexture getTexture getUInt32 getVector2 getVector2I getVector2UI getVector3 getVector3I getVector3UI getVector4 getVector4I getVector4UI isAnimated onCreate onDeserializationEnded onDisable onEnable onInitialize onSerializationStart revert setBoolean setBuffer setColor setColorGradient setFloat setFloatCurve setInt32 setMatrix3 setMatrix4 setSamplerState setSpriteImage setTexture setTextureWithSurface setUInt32 setVector2 setVector2I setVector2UI setVector3 setVector3I setVector3UI setVector4 setVector4I setVector4UI unload

Constructors

constructor

Accessors

carbonMaterial

carbonMaterialHandle

handle

isDestroyed

  • get isDestroyed(): boolean

  • Determines if the resource is destroyed.

    Returns boolean

    Note

    This can happen when the Resource was forcefully unloaded or reverted. For this reason, it is safer to hold on to a instead of directly referencing a resource pointer, as the current Resource can always be retrieved via .value.

isValid

  • get isValid(): boolean

  • Returns boolean

metaData

model

  • get model(): MaterialModel

  • Sets a material model and applies all model parameters to the material.

    Returns MaterialModel

  • set model(value): void

  • Parameters

    Returns void

name

  • get name(): string

  • Name of the resource. Use primarily for easier identification and not important to the engine itself.

    Returns string

shader

  • get shader(): Shader

  • Sets a shader that will be used by the material. Material will be initialized using all compatible techniques from the shader. Shader must be set before doing any other operations with the material.

    Returns Shader

  • set shader(value): void

  • Sets a shader that will be used by the material. Material will be initialized using all compatible techniques from the shader. Shader must be set before doing any other operations with the material.

    Parameters

    Returns void

shaderHandle

  • get shaderHandle(): ResourceHandle<Shader>

  • Sets a shader that will be used by the material. Material will be initialized using all compatible techniques from the shader. Shader must be set before doing any other operations with the material.

    Returns ResourceHandle<Shader>

  • set shaderHandle(value): void

  • Parameters

    Returns void

surfaceModelType

techniqueCount

  • get techniqueCount(): number

  • Returns the total number of techniques supported by this material.

    Returns number

uuid

  • get uuid(): UUID

  • Returns a universally unique identifier of this resource.

    Returns UUID

variation

  • get variation(): ShaderVariation

  • Set of parameters that determine which subset of techniques in the assigned shader should be used. Only the techniques that have the provided parameters with the provided values will match. This will control which technique is considered the default technique and which subset of techniques are searched during a call to findTechnique().

    Returns ShaderVariation

  • set variation(value): void

  • Parameters

    Returns void

Methods

compileTechniqueAsync

  • compileTechniqueAsync(variation): AsyncOp<boolean, void>

  • Compiles the specified variation asynchronously, if the variation is already compiled, the operation will complete immediately.

    Parameters

    • variation: ShaderVariation

      The variation to compile, if unspecified, compiles the material default variation.

    Returns AsyncOp<boolean, void>

dispatchComputeAsync

  • dispatchComputeAsync(groupCountX, groupCountY, groupCountZ): UncertainAsyncOp<boolean, string>

  • Dispatch a compute shader using this material asynchronously.

    Parameters

    • groupCountX: number

      The number of thread groups to dispatch in the X dimension.

    • groupCountY: number

      The number of thread groups to dispatch in the Y dimension.

    • groupCountZ: number

      The number of thread groups to dispatch in the Z dimension.

    Returns UncertainAsyncOp<boolean, string>

    A handle to the async operation, which is marked as completed once the dispatch was queued on core.

    Note

    This method only queues the dispatch on the core thread, it does not wait for the dispatch to complete. The material must have a compute shader technique for this to work. Otherwise an error will be returned.

duplicate

  • duplicate(): Resource

  • Duplicates the resource and creates a unique UUID for the duplicated resource.

    Returns Resource

    The duplicated resource or null, if the duplication failed.

getBoolean

  • getBoolean(name, arrayIndex?): boolean

  • Returns a boolean value assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string

      Parameter name.

    • OptionalarrayIndex: number

      Position index as an array.

    Returns boolean

getBuffer

getColor

  • getColor(name, arrayIndex?): LinearColor

  • Returns a color assigned with the parameter with the specified name. If a color gradient is assigned to this parameter, returns the gradient color evaluated at time 0.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns LinearColor

getColorGradient

  • getColorGradient(name, arrayIndex?): ColorGradientHDR

  • Returns a color gradient assigned with the parameter with the specified name. If the parameter has a constant value bound instead of a gradient then this method returns an empty gradient.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns ColorGradientHDR

getFloat

  • getFloat(name, arrayIndex?): number

  • Returns a float value assigned with the parameter with the specified name. If a curve is assigned to this parameter, returns the curve value evaluated at time 0.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns number

getFloatCurve

  • getFloatCurve(name, arrayIndex?): AnimationCurve

  • Returns a curve value assigned to the parameter with the specified name. If the parameter has a constant value bound instead of a curve then this method returns an empty curve.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns AnimationCurve

getInt32

  • getInt32(name, arrayIndex?): number

  • Returns an integer value assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string

      Parameter name.

    • OptionalarrayIndex: number

      Position index as an array.

    Returns number

getMatrix3

  • getMatrix3(name, arrayIndex?): Matrix3

  • Returns a 3x3 matrix assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Matrix3

getMatrix4

  • getMatrix4(name, arrayIndex?): Matrix4

  • Returns a 4x4 matrix assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Matrix4

getSamplerState

getSpriteImage

getSpriteTexture

getTexture

  • getTexture(name): Texture

  • Returns a texture assigned to the material. If the material has a sprite texture assigned, this will return the parent texture of the sprite.

    Parameters

    • name: string

      Name of the texture parameter.

    Returns Texture

    Texture assigned to the specified material

getUInt32

  • getUInt32(name, arrayIndex?): number

  • Returns an unsigned integer value assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string

      Parameter name.

    • OptionalarrayIndex: number

      Position index as an array.

    Returns number

getVector2

  • getVector2(name, arrayIndex?): Vector2

  • Returns a 2D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector2

getVector2I

  • getVector2I(name, arrayIndex?): Vector2

  • Returns a 2D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector2

getVector2UI

  • getVector2UI(name, arrayIndex?): Vector2

  • Returns a 2D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector2

getVector3

  • getVector3(name, arrayIndex?): Vector3

  • Returns a 3D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector3

getVector3I

  • getVector3I(name, arrayIndex?): Vector3

  • Returns a 3D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector3

getVector3UI

  • getVector3UI(name, arrayIndex?): Vector3

  • Returns a 3D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector3

getVector4

  • getVector4(name, arrayIndex?): Vector4

  • Returns a 4D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector4

getVector4I

  • getVector4I(name, arrayIndex?): Vector4

  • Returns a 4D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector4

getVector4UI

  • getVector4UI(name, arrayIndex?): Vector4

  • Returns a 4D vector assigned with the parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index you which to retrieve.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns Vector4

isAnimated

  • isAnimated(name, arrayIndex?): boolean

  • Checks does the data parameter with the specified name currently contains animated data. This could be an animation curve or a color gradient.

    Parameters

    • name: string
    • OptionalarrayIndex: number

    Returns boolean

onCreate

  • onCreate(): void
  • Virtual

    Method called by RSX to perform actions required after the creation of the resource.

    Returns void

onDeserializationEnded

  • onDeserializationEnded(): void
  • Virtual

    Method called by RSX to perform any operations needed after deserialization.

    Returns void

    Note

    Use this API to restore your serializable data into live objects.

onDisable

  • onDisable(): void
  • Virtual

    Method called by RSX to disable the resource.

    Returns void

    Note

    Use this API to deactivate the resource before it is serialized.

onEnable

  • onEnable(): void
  • Virtual

    Method called by RSX to enable the resource.

    Returns void

    Note

    Use this API to activate the resource after it has been disabled by serialization.

onInitialize

  • onInitialize(): void
  • Virtual

    Method called by RSX to perform initialization of the resource.

    Returns void

    Note

    Use this API to initialize data and default construct all fields.

onSerializationStart

  • onSerializationStart(): void
  • Virtual

    Method called by RSX to perform any operations before serialization.

    Returns void

    Note

    Use this API to bake your live data into serializable data.

revert

  • revert(): boolean

  • Reverts the resource to the on-disk representation.

    Returns boolean

    Note

    This is a potentially expensive call, as it needs to deserialize and replace all existing in-memory resource handles.

setBoolean

  • setBoolean(name, value, arrayIndex?): void

  • Assigns a boolean value to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    • name: string
    • value: boolean
    • OptionalarrayIndex: number

    Returns void

setBuffer

  • setBuffer(name, value): void

  • Assigns a buffer to the shader parameter with the specified name.

    Parameters

    Returns void

setColor

  • setColor(name, value, arrayIndex?): void

  • Assigns a color to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setColorGradient

  • setColorGradient(name, value, arrayIndex?): void

  • Assigns a color gradient to the shader parameter with the specified name. The system will automatically evaluate the gradient with the passage of time and apply the evaluated value to the parameter.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setFloat

  • setFloat(name, value, arrayIndex?): void

  • Assigns a float value to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    • name: string
    • value: number
    • OptionalarrayIndex: number

    Returns void

setFloatCurve

setInt32

  • setInt32(name, value, arrayIndex?): void

  • Assigns an integer value to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    • name: string
    • value: number
    • OptionalarrayIndex: number

    Returns void

setMatrix3

  • setMatrix3(name, value, arrayIndex?): void

  • Assigns a 3x3 matrix to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setMatrix4

  • setMatrix4(name, value, arrayIndex?): void

  • Assigns a 4x4 matrix to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setSamplerState

  • setSamplerState(name, value): void

  • Assigns a sampler state to the shader parameter with the specified name.

    Parameters

    Returns void

setSpriteImage

setTexture

  • setTexture(name, texture): void

  • Assigns a texture to the specified material parameter.

    Parameters

    Returns void

setTextureWithSurface

  • setTextureWithSurface(name, texture, surface): void

  • Assigns a texture to the specified material parameter. Allows you to specify a surface parameter that allows you to bind only a sub-set of the texture.

    Parameters

    Returns void

setUInt32

  • setUInt32(name, value, arrayIndex?): void

  • Assigns an unsigned integer value to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    • name: string
    • value: number
    • OptionalarrayIndex: number

    Returns void

setVector2

  • setVector2(name, value, arrayIndex?): void

  • Assigns a 2D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector2I

  • setVector2I(name, value, arrayIndex?): void

  • Assigns a 2D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector2UI

  • setVector2UI(name, value, arrayIndex?): void

  • Assigns a 2D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector3

  • setVector3(name, value, arrayIndex?): void

  • Assigns a 3D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector3I

  • setVector3I(name, value, arrayIndex?): void

  • Assigns a 3D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector3UI

  • setVector3UI(name, value, arrayIndex?): void

  • Assigns a 3D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector4

  • setVector4(name, value, arrayIndex?): void

  • Assigns a 4D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector4I

  • setVector4I(name, value, arrayIndex?): void

  • Assigns a 4D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

setVector4UI

  • setVector4UI(name, value, arrayIndex?): void

  • Assigns a 4D vector to the shader parameter with the specified name.

    Optionally if the parameter is an array you may provide an array index to assign the value to.

    Parameters

    Returns void

unload

  • unload(): void

  • Forcefully unloads the resource.

    Returns void

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods