Skip to content
AudityBy DarkEffekt

Struct AudityInstance

A handle to one live playing instance - the component-free control surface. Obtained from DarkEffekt.Audity.AuditySource.Instance or DarkEffekt.Audity.AudityPlayback.Play(DarkEffekt.Audity.AudityGraph%2cUnityEngine.Vector3%2cDarkEffekt.Audity.AudityQuantize%2cSystem.Single%2cUnityEngine.Audio.AudioMixerGroup%2cDarkEffekt.Audity.AudityMountSpec). Generation-counted: a handle outlives its instance harmlessly - every method validates and no-ops (returning false) once the instance is gone.

A handle addresses the LIVE instance only. It does not remember values across plays the way DarkEffekt.Audity.AuditySource does - stickiness is the component’s (and later the orchestration facade’s) job.

Assembly: DarkEffekt.Audity.Runtime
Section titled “Assembly: DarkEffekt.Audity.Runtime”
Declaration
public readonly struct AudityInstance

Properties

Section titled “Properties”

Invalid

Section titled “Invalid”

The never-valid handle.

Declaration
public static AudityInstance Invalid { get; }

IsValid

Section titled “IsValid”

True while the instance this handle was issued for is still registered.

Declaration
public bool IsValid { get; }

IsPlaying

Section titled “IsPlaying”

True while the instance is registered and its host is playing.

Declaration
public bool IsPlaying { get; }

Methods

Section titled “Methods”

Stop(float)

Section titled “Stop(float)”

Stops the instance, optionally fading out first.

Declaration
public bool Stop(float fadeOutSeconds = 0)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.Single fadeOutSeconds

Trigger(AudityQuantize)

Section titled “Trigger(AudityQuantize)”

Fires the anonymous trigger (hits every Trigger In).

Declaration
public bool Trigger(AudityQuantize quantize = AudityQuantize.Immediate)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityQuantize quantize

Trigger(AudityParameterId, AudityQuantize)

Section titled “Trigger(AudityParameterId, AudityQuantize)”
Declaration
public bool Trigger(AudityParameterId id, AudityQuantize quantize = AudityQuantize.Immediate)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
DarkEffekt.Audity.AudityQuantize quantize

Trigger(string, AudityQuantize)

Section titled “Trigger(string, AudityQuantize)”
Declaration
public bool Trigger(string name, AudityQuantize quantize = AudityQuantize.Immediate)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
DarkEffekt.Audity.AudityQuantize quantize

SetParameter(AudityParameterId, float, float, int)

Section titled “SetParameter(AudityParameterId, float, float, int)”

Sets a scalar member on the live instance (with glide). Not sticky, but it takes precedence over global parameter updates while this instance plays.

Declaration
public bool SetParameter(AudityParameterId id, float value, float smoothSeconds = -1, int elementIndex = 0)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
System.Single value
System.Single smoothSeconds
System.Int32 elementIndex

SetParameter(string, float, float, int)

Section titled “SetParameter(string, float, float, int)”
Declaration
public bool SetParameter(string name, float value, float smoothSeconds = -1, int elementIndex = 0)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
System.Single value
System.Single smoothSeconds
System.Int32 elementIndex

SetFloat(AudityParameterId, float, float, int)

Section titled “SetFloat(AudityParameterId, float, float, int)”
Declaration
public bool SetFloat(AudityParameterId id, float value, float smoothSeconds = -1, int elementIndex = 0)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
System.Single value
System.Single smoothSeconds
System.Int32 elementIndex

SetFloat(string, float, float, int)

Section titled “SetFloat(string, float, float, int)”
Declaration
public bool SetFloat(string name, float value, float smoothSeconds = -1, int elementIndex = 0)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
System.Single value
System.Single smoothSeconds
System.Int32 elementIndex

TryGetFloat(AudityParameterId, out float, int)

Section titled “TryGetFloat(AudityParameterId, out float, int)”

Reads back a member the GRAPH writes (Direction = Out): an Envelope Follower’s level, a Noise Gate’s Open, anything a Parameter Out node feeds. The counterpart of DarkEffekt.Audity.AudityInstance.SetParameter(DarkEffekt.Audity.AudityParameterId%2cSystem.Single%2cSystem.Single%2cSystem.Int32).

Declaration
public bool TryGetFloat(AudityParameterId id, out float value, int element = 0)
Returns
Section titled “Returns”

System.Boolean: False if this handle is no longer live, the member is not marked Out, or the engine has not reported it yet. The value is a snapshot as of the engine’s last report, roughly a frame old - it crosses the audio thread, so it can never be sample-accurate. Keep sample-accurate reactions inside the graph.

Parameters
Section titled “Parameters”
Type Name Description
DarkEffekt.Audity.AudityParameterId id
System.Single value
System.Int32 element Array/vector element; 0 for scalars.

TryGetFloat(string, out float, int)

Section titled “TryGetFloat(string, out float, int)”

Reads back a member the GRAPH writes (Direction = Out): an Envelope Follower’s level, a Noise Gate’s Open, anything a Parameter Out node feeds. The counterpart of DarkEffekt.Audity.AudityInstance.SetParameter(DarkEffekt.Audity.AudityParameterId%2cSystem.Single%2cSystem.Single%2cSystem.Int32).

Declaration
public bool TryGetFloat(string name, out float value, int element = 0)
Returns
Section titled “Returns”

System.Boolean: False if this handle is no longer live, the member is not marked Out, or the engine has not reported it yet. The value is a snapshot as of the engine’s last report, roughly a frame old - it crosses the audio thread, so it can never be sample-accurate. Keep sample-accurate reactions inside the graph.

Parameters
Section titled “Parameters”
Type Name Description
System.String name
System.Single value
System.Int32 element Array/vector element; 0 for scalars.

GetFloat(AudityParameterId, float, int)

Section titled “GetFloat(AudityParameterId, float, int)”

Read-back with a fallback, for call sites that would rather not branch.

Declaration
public float GetFloat(AudityParameterId id, float fallback = 0, int element = 0)
Returns
Section titled “Returns”

System.Single

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
System.Single fallback
System.Int32 element

GetFloat(string, float, int)

Section titled “GetFloat(string, float, int)”

Read-back with a fallback, for call sites that would rather not branch.

Declaration
public float GetFloat(string name, float fallback = 0, int element = 0)
Returns
Section titled “Returns”

System.Single

Parameters
Section titled “Parameters”
Type Name
System.String name
System.Single fallback
System.Int32 element

TryGetVector(AudityParameterId, out Vector4, int)

Section titled “TryGetVector(AudityParameterId, out Vector4, int)”

Reads back a Vector2/3/4 member the graph writes, componentwise.

Declaration
public bool TryGetVector(AudityParameterId id, out Vector4 value, int componentCount = 4)
Returns
Section titled “Returns”

System.Boolean: False if no component has been reported yet.

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
UnityEngine.Vector4 value
System.Int32 componentCount

TryGetVector(string, out Vector4, int)

Section titled “TryGetVector(string, out Vector4, int)”

Reads back a Vector2/3/4 member the graph writes, componentwise.

Declaration
public bool TryGetVector(string name, out Vector4 value, int componentCount = 4)
Returns
Section titled “Returns”

System.Boolean: False if no component has been reported yet.

Parameters
Section titled “Parameters”
Type Name
System.String name
UnityEngine.Vector4 value
System.Int32 componentCount

GetFloats(AudityParameterId, Span<float>)

Section titled “GetFloats(AudityParameterId, Span<float>)”

Reads a Float ARRAY member the graph writes - a Spectrum Analyzer’s bands, say - into destination, element 0 first. A float[] converts implicitly, so pass one you keep around rather than allocating per frame. Reading stops at the first element the engine has not reported, which is the member’s real length: a shorter member fills only its own elements and leaves the rest of the span untouched.

Declaration
public int GetFloats(AudityParameterId id, Span<float> destination)
Returns
Section titled “Returns”

System.Int32: How many elements were filled; 0 if the instance is not playing or nothing has been reported yet.

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
System.Span<System.Single> destination

GetFloats(string, Span<float>)

Section titled “GetFloats(string, Span<float>)”

Reads a Float ARRAY member the graph writes - a Spectrum Analyzer’s bands, say - into destination, element 0 first. A float[] converts implicitly, so pass one you keep around rather than allocating per frame. Reading stops at the first element the engine has not reported, which is the member’s real length: a shorter member fills only its own elements and leaves the rest of the span untouched.

Declaration
public int GetFloats(string name, Span<float> destination)
Returns
Section titled “Returns”

System.Int32: How many elements were filled; 0 if the instance is not playing or nothing has been reported yet.

Parameters
Section titled “Parameters”
Type Name
System.String name
System.Span<System.Single> destination

SetBool(AudityParameterId, bool)

Section titled “SetBool(AudityParameterId, bool)”
Declaration
public bool SetBool(AudityParameterId id, bool value)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
System.Boolean value

SetBool(string, bool)

Section titled “SetBool(string, bool)”
Declaration
public bool SetBool(string name, bool value)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
System.Boolean value

SetInt(AudityParameterId, int)

Section titled “SetInt(AudityParameterId, int)”
Declaration
public bool SetInt(AudityParameterId id, int value)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
System.Int32 value

SetInt(string, int)

Section titled “SetInt(string, int)”
Declaration
public bool SetInt(string name, int value)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
System.Int32 value

SetVector(AudityParameterId, Vector4, int, float)

Section titled “SetVector(AudityParameterId, Vector4, int, float)”

Sets a Vector2/3/4 member componentwise (per-element glide).

Declaration
public bool SetVector(AudityParameterId id, Vector4 value, int componentCount, float smoothSeconds = -1)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
UnityEngine.Vector4 value
System.Int32 componentCount
System.Single smoothSeconds

SetVector(AudityParameterId, Vector2, float)

Section titled “SetVector(AudityParameterId, Vector2, float)”
Declaration
public bool SetVector(AudityParameterId id, Vector2 value, float smoothSeconds = -1)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
UnityEngine.Vector2 value
System.Single smoothSeconds

SetVector(string, Vector2, float)

Section titled “SetVector(string, Vector2, float)”
Declaration
public bool SetVector(string name, Vector2 value, float smoothSeconds = -1)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
UnityEngine.Vector2 value
System.Single smoothSeconds

SetVector(AudityParameterId, Vector3, float)

Section titled “SetVector(AudityParameterId, Vector3, float)”
Declaration
public bool SetVector(AudityParameterId id, Vector3 value, float smoothSeconds = -1)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
UnityEngine.Vector3 value
System.Single smoothSeconds

SetVector(string, Vector3, float)

Section titled “SetVector(string, Vector3, float)”
Declaration
public bool SetVector(string name, Vector3 value, float smoothSeconds = -1)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
UnityEngine.Vector3 value
System.Single smoothSeconds

SetVector(AudityParameterId, Vector4, float)

Section titled “SetVector(AudityParameterId, Vector4, float)”
Declaration
public bool SetVector(AudityParameterId id, Vector4 value, float smoothSeconds = -1)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId id
UnityEngine.Vector4 value
System.Single smoothSeconds

SetVector(string, Vector4, float)

Section titled “SetVector(string, Vector4, float)”
Declaration
public bool SetVector(string name, Vector4 value, float smoothSeconds = -1)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String name
UnityEngine.Vector4 value
System.Single smoothSeconds

SetTempo(double, int)

Section titled “SetTempo(double, int)”
Declaration
public bool SetTempo(double bpm, int beatsPerBar = 4)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.Double bpm
System.Int32 beatsPerBar

BindSource(AudityParameterId, AudityBankHandle)

Section titled “BindSource(AudityParameterId, AudityBankHandle)”

Hot-path live rebind: points a source key at an already-resident bank on this instance only. The instance takes no ownership of the bank and never queues a cold load, so warm the bank yourself. For sticky, load-if-cold binding use DarkEffekt.Audity.AuditySource.BindSource(System.String%2cDarkEffekt.Audity.AuditySampleSet).

Declaration
public bool BindSource(AudityParameterId key, AudityBankHandle bank)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
DarkEffekt.Audity.AudityParameterId key
DarkEffekt.Audity.AudityBankHandle bank

BindSource(string, AudityBankHandle)

Section titled “BindSource(string, AudityBankHandle)”
Declaration
public bool BindSource(string key, AudityBankHandle bank)
Returns
Section titled “Returns”

System.Boolean

Parameters
Section titled “Parameters”
Type Name
System.String key
DarkEffekt.Audity.AudityBankHandle bank