Channel¶

Adds a new instance at the specified world position.

ChannelInstance Amplitude::Channel::AddInstance (
    const AmVector3 & location
) const

Creates a new position instance for this channel. In Blended mode, all instances share the same playback cursor. In Separate mode, each instance has an independent cursor starting from the current playback position.

Parameters:

• location The world position for the new instance.

Returns:

The created ChannelInstance handle.

Note:

Instancing must be enabled before adding instances.

See also: EnableInstancing

See also: ChannelInstance

Construct an uninitialized channel.

Amplitude::Channel::Channel () 

Note:

An uninitialized channel cannot have its data set or queried.

Creates a wrapper instance over the provided state.

explicit Amplitude::Channel::Channel (
    ChannelInternalState * state
) 

Parameters:

• state The internal state to wrap.

Warning:

This constructor is for internal usage only.

Uninitializes this channel.

void Amplitude::Channel::Clear () 

Note:

This does not stop the audio or destroy the internal state it references, it just removes this reference to it.

Removes all instances.

void Amplitude::Channel::ClearInstances () const

After calling this, the channel will have no position instances. Instancing will still be enabled with the same mode.

Disables multi-position mode, reverting to single-position behavior.

void Amplitude::Channel::DisableInstancing () const

All existing instances will be removed when instancing is disabled.

Enables multi-position mode for this channel.

void Amplitude::Channel::EnableInstancing (
    eChannelInstanceMode mode
) const

When enabled, this channel can have multiple position instances, allowing the same sound to be perceived from multiple locations simultaneously.

Parameters:

• mode The instance mode.

Note:

Must be called before adding instances. The mode cannot be changed while instancing is already enabled.

See also: eChannelInstanceMode

See also: AddInstance

Returns the Entity associated with this channel.

Entity Amplitude::Channel::GetEntity () const

Note:

If no Entity is associated with this channel, this method will return an uninitialized Entity object. You should check if the entity is valid before using it.

Returns:

The entity associated with this channel.

See also: Entity

Returns the gain on this channel.

AmReal32 Amplitude::Channel::GetGain () const

Returns:

The channel's gain.

Gets the ID of this channel.

AmChannelID Amplitude::Channel::GetId () const

Returns:

The ID of this channel.

Gets an instance by ID.

ChannelInstance Amplitude::Channel::GetInstance (
    AmChannelInstanceID instanceId
) const

Parameters:

• instanceId The ID of the instance to retrieve.

Returns:

The ChannelInstance handle, or an invalid instance if not found.

See also: ChannelInstance::Valid

Gets the number of active instances.

AmSize Amplitude::Channel::GetInstanceCount () const

Returns:

The number of position instances.

Gets the instancing mode.

eChannelInstanceMode Amplitude::Channel::GetInstancingMode () const

Returns:

The current instancing mode.

See also: eChannelInstanceMode

Returns the Listener associated with this channel.

Listener Amplitude::Channel::GetListener () const

Note:

If no Listener is associated with this channel, this method will return an uninitialized Listener object. You should check if the listener is valid before using it.

Returns:

The listener associated with this channel.

See also: Listener

Gets the location of this channel in the game environment.

const AmVector3 & Amplitude::Channel::GetLocation () const

If the audio on this channel doesn't support positional data, this method will return an invalid location.

Returns:

The location of this channel.

Gets this channel's current playback position.

AmTime Amplitude::Channel::GetPlaybackPosition () const

Returns:

The current playback position in milliseconds.

Returns the playback state of this channel.

eChannelPlaybackState Amplitude::Channel::GetPlaybackState () const

Returns:

An eChannelPlaybackState enumeration value representing the current state of the channel.

Returns the Room associated with this channel.

Room Amplitude::Channel::GetRoom () const

Note:

If no Room is associated with this channel, this method will return an uninitialized Room object. You should check if the room is valid before using it.

Returns:

The room associated with this channel.

Returns the internal state of this channel.

ChannelInternalState * Amplitude::Channel::GetState () const

Returns:

The internal state of this channel.

Warning:

This method is for internal usage only.

Checks if multi-position instancing is enabled.

bool Amplitude::Channel::IsInstancingEnabled () const

Returns:

true if instancing is enabled, false otherwise.

Registers a callback for a channel event.

void Amplitude::Channel::On (
    eChannelEvent event,
    ChannelEventCallback callback,
    void * userData=nullptr
) const

Parameters:

• event The channel event.
• callback The callback function.
• userData The user data to pass to the callback.

Note:

Events fire when the voice reports them, or on the next frame, not at the moment of the call. The userData must outlive the channel's Stop event, including the Stop that Engine::Deinitialize() raises for channels still playing. There is no way to unregister a callback.

See also: eChannelEvent

See also: ChannelEventCallback

Pauses the channel.

void Amplitude::Channel::Pause (
    AmTime duration=kMinFadeDuration
) const

Note:

A paused channel may be resumed where it left off.

Parameters:

• duration The fade out duration before to pause the channel.

See also: Resume

Pauses the channel at an exact frame of the audio clock.

void Amplitude::Channel::Pause (
    AmTime duration,
    AmUInt64 clock
) const

A duration of 0 still applies a short de-click fade.

Parameters:

• duration The fade out duration before to pause the channel.
• clock The frame, on Engine::GetAudioClock(), at which the pause begins.

Checks if the sound associated with this channel is playing.

bool Amplitude::Channel::Playing () const

Returns:

true if the channel is currently playing, false otherwise.

Removes an instance by ID.

void Amplitude::Channel::RemoveInstance (
    AmChannelInstanceID instanceId
) const

Parameters:

• instanceId The ID of the instance to remove.

See also: ChannelInstance::GetId

Resumes the channel.

void Amplitude::Channel::Resume (
    AmTime duration=kMinFadeDuration
) const

If this channel is paused, it will continue where it left off.

Parameters:

• duration The fade-in duration after resuming the channel.

See also: Pause

Resumes the channel at an exact frame of the audio clock.

void Amplitude::Channel::Resume (
    AmTime duration,
    AmUInt64 clock
) const

A duration of 0 still applies a short de-click fade.

Parameters:

• duration The fade-in duration after resuming the channel.
• clock The frame, on Engine::GetAudioClock(), at which the resume begins.

Starts this channel at an exact frame of the audio clock.

bool Amplitude::Channel::ScheduleStart (
    AmUInt64 clock
) const

Only valid on the frame the channel was returned by Engine::Play(), before the engine processes it.

Parameters:

• clock The audio-clock frame of the first sample. A frame already in the past starts the sound as soon as possible.

Returns:

true when the start was scheduled, false when the channel already started.

Sets the gain on this channel.

void Amplitude::Channel::SetGain (
    AmReal32 gain
) const

Parameters:

• gain The new gain value.

Sets the location of this channel in the game environment.

void Amplitude::Channel::SetLocation (
    const AmVector3 & location
) const

If the audio on this channel doesn't support positional data, this method does nothing.

Parameters:

• location The new location of the channel.

Sets this channel's playback position.

bool Amplitude::Channel::SetPlaybackPosition (
    AmTime position
) const

Parameters:

• position The playback position in milliseconds.

Returns:

true if the playback position was set, false otherwise.

Sets this channel's playback position at an exact frame of the audio clock.

bool Amplitude::Channel::SetPlaybackPosition (
    AmTime position,
    AmUInt64 clock
) const

Parameters:

• position The playback position in milliseconds.
• clock The frame, on Engine::GetAudioClock(), at which the seek lands.

Returns:

true if the seek was scheduled, false otherwise.

Stops the channel.

void Amplitude::Channel::Stop (
    AmTime duration=kMinFadeDuration
) const

Note:

A sound will stop on its own if it's not set to loop. Looped audio must be explicitly stopped.

Parameters:

• duration The fade out duration before to stop the channel.

Stops the channel at an exact frame of the audio clock.

void Amplitude::Channel::Stop (
    AmTime duration,
    AmUInt64 clock
) const

A duration of 0 still applies a short de-click fade. The channel keeps playing until clock, then settles when the fade ends.

Parameters:

• duration The fade out duration before to stop the channel.
• clock The frame, on Engine::GetAudioClock(), at which the stop begins.

Checks whether this channel has been initialized.

bool Amplitude::Channel::Valid () const

Returns:

true if this channel has been initialized, false otherwise.