Channel¶
class Channel
An object that represents a single channel of audio.
The Channel class is a lightweight reference to a ChannelInternalState object which is managed by the Engine. Multiple channels may point to the same underlying data.
Functions¶
| Name | Description |
|---|---|
| Channel | Construct an uninitialized Channel. |
| Channel | Creates a wrapper instance over the provided state. |
| Clear | Uninitializes this Channel. |
| Valid | Checks whether this Channel has been initialized. |
| GetId | Gets the ID of this Channel. |
| Playing | Checks if the sound associated to this Channel is playing. |
| Stop | Stops the Channel. |
| Pause | Pauses the Channel. |
| Resume | Resumes the Channel. |
| GetLocation | Gets the location of this Channel. |
| SetLocation | Sets the location of this Channel. |
| SetGain | Sets the gain on this Channel. |
| GetGain | Returns the gain on this Channel. |
| GetPlaybackState | Returns the playback state of this Channel. |
| GetEntity | Returns the Entity associated with this Channel. |
| GetListener | Returns the Listener associated with this Channel. |
| GetRoom | Returns the Room associated with this Channel. |
| GetState | Returns the internal state of this Channel. |
| On | Registers a callback for a channel event. |
Function Details¶
Channel¶
Channel()
Construct an uninitialized Channel.
An uninitialized Channel cannot have its data set or queried.
explicit Channel(ChannelInternalState* state)
Creates a wrapper instance over the provided state.
- Parameter
state - The internal state to wrap.
Warning
This constructor is for internal usage only.
Clear¶
void Clear()
Uninitializes this Channel.
Note that this does not stop the audio or destroy the internal state it references, it just removes this reference to it.
GetEntity¶
[[nodiscard]] Entity GetEntity() const
Returns the Entity associated with this Channel.
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.
- Return
- The entity associated with this
Channel. - See
- Entity
GetGain¶
[[nodiscard]] AmReal32 GetGain() const
Returns the gain on this Channel.
- Return
- The channel's gain.
GetId¶
[[nodiscard]] AmUInt64 GetId() const
Gets the ID of this Channel.
- Return
- The ID of this
Channel.
GetListener¶
[[nodiscard]] Listener GetListener() const
Returns the Listener associated with this Channel.
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.
- Return
- The listener associated with this
Channel. - See
- Listener
GetLocation¶
[[nodiscard]] const AmVec3& GetLocation() const
Gets the location of this Channel.
If the audio on this channel is not set to be Positional, this method will return an invalid location.
- Return
- The location of this
Channel.
GetPlaybackState¶
[[nodiscard]] ChannelPlaybackState GetPlaybackState() const
Returns the playback state of this Channel.
- Return
- A
ChannelPlaybackStateenumeration value representing the current state of theChannel.
GetRoom¶
[[nodiscard]] Room GetRoom() const
Returns the Room associated with this Channel.
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.
- Return
- The room associated with this Channel.
GetState¶
[[nodiscard]] ChannelInternalState* GetState() const
Returns the internal state of this Channel.
- Return
- The internal state of this Channel.
Warning
This method is for internal usage only.
On¶
void On(ChannelEvent event, ChannelEventCallback callback, void* userData = nullptr) const
Registers a callback for a channel event.
- Parameter
event - The channel event.
- Parameter
callback - The callback function.
- Parameter
userData - The user data to pass to the callback.
- See
- ChannelEvent
- See
- ChannelEventCallback
Pause¶
void Pause(AmTime duration = kMinFadeDuration) const
Pauses the Channel.
A paused channel may be resumed where it left off.
- Parameter
duration - The fade out duration before to pause the channel.
Playing¶
[[nodiscard]] bool Playing() const
Checks if the sound associated to this Channel is playing.
- Return
- Whether the channel is currently playing.
Resume¶
void Resume(AmTime duration = kMinFadeDuration) const
Resumes the Channel.
If this channel was paused it will continue where it left off.
- Parameter
duration - The fade in duration after resuming the channel.
SetGain¶
void SetGain(AmReal32 gain) const
Sets the gain on this Channel.
- Parameter
gain - The new gain value.
SetLocation¶
void SetLocation(const AmVec3& location) const
Sets the location of this Channel.
If the audio on this channel is not set to be Positional, this method does nothing.
- Parameter
location - The new location of the
Channel.
Stop¶
void Stop(AmTime duration = kMinFadeDuration) const
Stops the Channel.
A sound will stop on its own if its not set to loop. Looped audio must be explicitly stopped.
- Parameter
duration - The fade out duration before to stop the channel.
Valid¶
[[nodiscard]] bool Valid() const
Checks whether this Channel has been initialized.
- Return
trueif thisChannelhas been initialized.