Class CarbonMaterial

The CarbonMaterial class implements a Material that is backed by a CarbonMaterialGraph that generates the underlying shader that is directly owned and serialized together with the CarbonMaterial.

The CarbonMaterial supports the following features:

Hierarchy

  • Material
    • CarbonMaterial

Constructors

constructor

Properties

_lastProgramCode

Accessors

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

Methods

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

Events

onOutdatedCarbonMaterialDiscovered onOutdatedCarbonMaterialRecompiled onCompilationStateChanged

Constructors

constructor

  • new CarbonMaterial(isInternalConstructor?): CarbonMaterial

  • Creates a new empty carbon material.

    Parameters

    • OptionalisInternalConstructor: boolean

    Returns CarbonMaterial

Properties

Protected_lastProgramCode

_lastProgramCode: String

Stores the last program code used to avoid recompilation if the code hasn't changed. This can be a string representing the code or undefined if no code has been set.

Accessors

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

ProtectedcompileGraphInternal

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>

deserializeGraph

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

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

ProtectedgetGraphInternal

  • getGraphInternal(): Resource

  • Gets the CarbonGraph and cooks the underlying shader immediately.

    Returns Resource

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

getSpriteImage

  • getSpriteImage(name): 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.

getSpriteTexture

  • getSpriteTexture(name): SpriteImage

  • Parameters

    • name: string

    Returns SpriteImage

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.

recompileGraphAsync

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.

serializeGraph

  • serializeGraph(graph, force?): boolean

  • Stores the underlying graph.

    Parameters

    Returns boolean

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

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

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

  • Parameters

    Returns void

ProtectedsetGraphInternal

  • setGraphInternal(serializedGraphData, distilledShaderSource): boolean

  • Sets the CarbonGraph and cooks the underlying shader immediately.

    Parameters

    Returns boolean

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

setSpriteImage

  • setSpriteImage(name, 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

    Returns void

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

synchronizeParameters

  • synchronizeParameters(graph): void

  • Synchronizes the parameters of the graph with the current material parameters.

    Parameters

    Returns void

unload

  • unload(): void

  • Forcefully unloads the resource.

    Returns void

Events

Static ReadonlyonOutdatedCarbonMaterialDiscovered

onOutdatedCarbonMaterialDiscovered: Event<[ResourceHandle<Resource>], boolean>

Triggered when a carbon material was initialized that has outdated dependencies. If the event returns false, the automatic recompilation begins.

Static ReadonlyonOutdatedCarbonMaterialRecompiled

onOutdatedCarbonMaterialRecompiled: Event<[ResourceHandle<Resource>, EnumValue<TaskState, number>], void>

Triggered when a carbon material was recompiled that had outdated dependencies. The material should be saved to the project.

ReadonlyonCompilationStateChanged

onCompilationStateChanged: Event<[UUID, EnumValue<TaskState, number>, number], void>

Triggered when the state of a code compilation changed.

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods
Events