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 Summary)

Material
- CarbonMaterialInstance

Index

Constructors

constructor

Accessors

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

Constructors

constructor

new CarbonMaterialInstance(
carbonMaterial: CarbonMaterial | ResourceHandle<CarbonMaterial>,
isInternalConstructor?: boolean,
): CarbonMaterialInstance
Creates a new carbon material instance that uses the specified carbonMaterial as parent.
Parameters
- carbonMaterial: CarbonMaterial | ResourceHandle<CarbonMaterial>
- OptionalisInternalConstructor: boolean
Returns CarbonMaterialInstance

Overrides Material.constructor

Accessors

carbonMaterial

get carbonMaterial(): CarbonMaterial

The parent material that is being instanced.

Returns CarbonMaterial

carbonMaterialHandle

get carbonMaterialHandle(): ResourceHandle<CarbonMaterial>

The parent material that is being instanced.

Returns ResourceHandle<CarbonMaterial>

handle

get handle(): ResourceHandle<CarbonMaterialInstance>

Returns a reference handle for this resource.

Returns ResourceHandle<CarbonMaterialInstance>

Overrides Material.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.

Inherited from Material.isDestroyed

isValid

get isValid(): boolean

Returns boolean

Inherited from Material.isValid

metaData

get metaData(): ResourceMetaData

Returns the meta data of this resource.

Returns ResourceMetaData

Inherited from Material.metaData

model

get model(): MaterialModel

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

Returns MaterialModel

Inherited from Material.model
set model(value: MaterialModel): void
Parameters
- value: MaterialModel
Returns void

Inherited from Material.model

name

get name(): string

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

Returns string

Inherited from Material.name

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

Inherited from Material.shader
set shader(value: Shader): 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
- value: Shader
Returns void

Inherited from Material.shader

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>

Inherited from Material.shaderHandle
set shaderHandle(value: Shader | ResourceHandle<Shader>): void
Parameters
- value: Shader | ResourceHandle<Shader>
Returns void

Inherited from Material.shaderHandle

surfaceModelType

get surfaceModelType(): EnumValue<PBRMaterialSurfaceModelType>

Gets the surface model type of the material. Typically this depends on the shader implementation and controls which buffers are bound during rendering.

Returns EnumValue<PBRMaterialSurfaceModelType>

Inherited from Material.surfaceModelType

techniqueCount

get techniqueCount(): number

Returns the total number of techniques supported by this material.

Returns number

Inherited from Material.techniqueCount

uuid

get uuid(): UUID

Returns a universally unique identifier of this resource.

Returns UUID

Inherited from Material.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

Inherited from Material.variation
set variation(value: ShaderVariation): void
Parameters
- value: ShaderVariation
Returns void

Inherited from Material.variation

Methods

compileTechniqueAsync

compileTechniqueAsync(variation: ShaderVariation): AsyncOp<boolean>
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>

Inherited from Material.compileTechniqueAsync

dispatchComputeAsync

dispatchComputeAsync(
    groupCountX: number,
    groupCountY: number,
    groupCountZ: number,
): 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.

Inherited from Material.dispatchComputeAsync

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.

Inherited from Material.duplicate

getBoolean

getBoolean(name: string, arrayIndex?: number): 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

Inherited from Material.getBoolean

getBuffer

getBuffer(name: string): GPUBuffer
Returns a buffer assigned with the parameter with the specified name.
Parameters
- name: string
Returns GPUBuffer

Inherited from Material.getBuffer

getColor

getColor(name: string, arrayIndex?: number): 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

Inherited from Material.getColor

getColorGradient

getColorGradient(name: string, arrayIndex?: number): 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

Inherited from Material.getColorGradient

getFloat

getFloat(name: string, arrayIndex?: number): 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

Inherited from Material.getFloat

getFloatCurve

getFloatCurve(name: string, arrayIndex?: number): 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

Inherited from Material.getFloatCurve

getInt32

getInt32(name: string, arrayIndex?: number): 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

Inherited from Material.getInt32

getMatrix3

getMatrix3(name: string, arrayIndex?: number): 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

Inherited from Material.getMatrix3

getMatrix4

getMatrix4(name: string, arrayIndex?: number): 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

Inherited from Material.getMatrix4

getSamplerState

getSamplerState(name: string): SamplerState
Returns a sampler state assigned with the parameter with the specified name.
Parameters
- name: string
Returns SamplerState

Inherited from Material.getSamplerState

getSpriteImage

getSpriteImage(name: string): SpriteImage
Returns a SpriteImage assigned to the material parameter.
Parameters
- name: string
  Name of the texture parameter.
Returns SpriteImage
SpriteImage assigned to the specified material or null if not found.

Inherited from Material.getSpriteImage

getSpriteTexture

getSpriteTexture(name: string): SpriteImage
Parameters
- name: string
Returns SpriteImage

Inherited from Material.getSpriteTexture

getTexture

getTexture(name: string): 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

Inherited from Material.getTexture

getUInt32

getUInt32(name: string, arrayIndex?: number): 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

Inherited from Material.getUInt32

getVector2

getVector2(name: string, arrayIndex?: number): 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

Inherited from Material.getVector2

getVector2I

getVector2I(name: string, arrayIndex?: number): 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

Inherited from Material.getVector2I

getVector2UI

getVector2UI(name: string, arrayIndex?: number): 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

Inherited from Material.getVector2UI

getVector3

getVector3(name: string, arrayIndex?: number): 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

Inherited from Material.getVector3

getVector3I

getVector3I(name: string, arrayIndex?: number): 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

Inherited from Material.getVector3I

getVector3UI

getVector3UI(name: string, arrayIndex?: number): 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

Inherited from Material.getVector3UI

getVector4

getVector4(name: string, arrayIndex?: number): 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

Inherited from Material.getVector4

getVector4I

getVector4I(name: string, arrayIndex?: number): 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

Inherited from Material.getVector4I

getVector4UI

getVector4UI(name: string, arrayIndex?: number): 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

Inherited from Material.getVector4UI

isAnimated

isAnimated(name: string, arrayIndex?: number): 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

Inherited from Material.isAnimated

onCreate

onCreate(): void

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

Returns void

Inherited from Material.onCreate

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.

Inherited from Material.onDeserializationEnded

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.

Inherited from Material.onDisable

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.

Inherited from Material.onEnable

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.

Inherited from Material.onInitialize

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.

Inherited from Material.onSerializationStart

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.

Inherited from Material.revert

setBoolean

setBoolean(name: string, value: boolean, arrayIndex?: number): 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

Inherited from Material.setBoolean

setBuffer

setBuffer(name: string, value: GPUBuffer): void
Assigns a buffer to the shader parameter with the specified name.
Parameters
- name: string
- value: GPUBuffer
Returns void

Inherited from Material.setBuffer

setColor

setColor(name: string, value: Immutable<LinearColor>, arrayIndex?: number): 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
- name: string
- value: Immutable<LinearColor>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setColor

setColorGradient

setColorGradient(
    name: string,
    value: ColorGradientHDR,
    arrayIndex?: number,
): 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
- name: string
- value: ColorGradientHDR
- OptionalarrayIndex: number
Returns void

Inherited from Material.setColorGradient

setFloat

setFloat(name: string, value: number, arrayIndex?: number): 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

Inherited from Material.setFloat

setFloatCurve

setFloatCurve(name: string, value: AnimationCurve, arrayIndex?: number): void
Parameters
- name: string
- value: AnimationCurve
- OptionalarrayIndex: number
Returns void

Inherited from Material.setFloatCurve

setInt32

setInt32(name: string, value: number, arrayIndex?: number): 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

Inherited from Material.setInt32

setMatrix3

setMatrix3(name: string, value: Immutable<Matrix3>, arrayIndex?: number): 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
- name: string
- value: Immutable<Matrix3>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setMatrix3

setMatrix4

setMatrix4(name: string, value: Immutable<Matrix4>, arrayIndex?: number): 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
- name: string
- value: Immutable<Matrix4>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setMatrix4

setSamplerState

setSamplerState(name: string, value: SamplerState): void
Assigns a sampler state to the shader parameter with the specified name.
Parameters
- name: string
- value: SamplerState
Returns void

Inherited from Material.setSamplerState

setSpriteImage

setSpriteImage(
name: string,
spriteImage: SpriteImage | ResourceHandle<SpriteImage>,
): void
Assigns a SpriteImage to the specified material parameter. The sprite image is allowed to be animated, or just used for referencing a subset of a texture atlas.
Parameters
- name: string
  Name of the texture parameter.
- spriteImage: SpriteImage | ResourceHandle<SpriteImage>
  SpriteImage resource to assign.
Returns void

Inherited from Material.setSpriteImage

setTexture

setTexture(name: string, texture: Texture | ResourceHandle<Texture>): void
Assigns a texture to the specified material parameter.
Parameters
- name: string
  Name of the texture parameter.
- texture: Texture | ResourceHandle<Texture>
  Texture resource to assign.
Returns void

Inherited from Material.setTexture

setTextureWithSurface

setTextureWithSurface(
    name: string,
    texture: Texture | ResourceHandle<Texture>,
    surface: Immutable<TextureSurface>,
): 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
- name: string
  Name of the texture parameter.
- texture: Texture | ResourceHandle<Texture>
  Texture resource to assign.
- surface: Immutable<TextureSurface>
  Subset of the texture to assign.
Returns void

Inherited from Material.setTextureWithSurface

setUInt32

setUInt32(name: string, value: number, arrayIndex?: number): 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

Inherited from Material.setUInt32

setVector2

setVector2(name: string, value: Immutable<Vector2>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector2>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector2

setVector2I

setVector2I(name: string, value: Immutable<Vector2>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector2>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector2I

setVector2UI

setVector2UI(name: string, value: Immutable<Vector2>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector2>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector2UI

setVector3

setVector3(name: string, value: Immutable<Vector3>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector3>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector3

setVector3I

setVector3I(name: string, value: Immutable<Vector3>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector3>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector3I

setVector3UI

setVector3UI(name: string, value: Immutable<Vector3>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector3>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector3UI

setVector4

setVector4(name: string, value: Immutable<Vector4>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector4>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector4

setVector4I

setVector4I(name: string, value: Immutable<Vector4>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector4>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector4I

setVector4UI

setVector4UI(name: string, value: Immutable<Vector4>, arrayIndex?: number): 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
- name: string
- value: Immutable<Vector4>
- OptionalarrayIndex: number
Returns void

Inherited from Material.setVector4UI

unload

unload(): void

Forcefully unloads the resource.

Returns void

Inherited from Material.unload

Class CarbonMaterialInstance

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns CarbonMaterialInstance

Accessors

carbonMaterial

Returns CarbonMaterial

carbonMaterialHandle

Returns ResourceHandle<CarbonMaterial>

handle

Returns ResourceHandle<CarbonMaterialInstance>

isDestroyed

Returns boolean

Note

isValid

Returns boolean

metaData

Returns ResourceMetaData

model

Returns MaterialModel

Parameters

Returns void

name

Returns string

shader

Returns Shader

Parameters

Returns void

shaderHandle

Returns ResourceHandle<Shader>

Parameters

Returns void

surfaceModelType

Returns EnumValue<PBRMaterialSurfaceModelType>

techniqueCount

Returns number

uuid

Returns UUID

variation

Returns ShaderVariation

Parameters

Returns void

Methods

compileTechniqueAsync

Parameters

Returns AsyncOp<boolean>

dispatchComputeAsync

Parameters

Returns UncertainAsyncOp<boolean, string>

Note

duplicate

Returns Resource

getBoolean

Parameters

Returns boolean

getBuffer

Parameters

Returns GPUBuffer

getColor

Parameters

Returns LinearColor

getColorGradient

Parameters

Returns ColorGradientHDR

getFloat

Parameters

Returns number

getFloatCurve

Parameters

Returns AnimationCurve

getInt32

Parameters

Returns number

getMatrix3