Class dalia::Engine¶

#include <Engine.h>

Public Functions¶

Type	Name
Result	AttachEffect (EffectHandle effect, const char * busIdentifier, uint32_t effectSlot) Inserts an allocated effect into the processing chain of a specified bus.
Result	CreateBiquadFilter (EffectHandle & effect, BiquadFilterType type, const BiquadConfig & config) Creates a new Biquad filter effect.
Result	CreateBus (const char * identifier, const char * parentIdentifier="Master") Creates a new mixing bus.
Result	CreatePlayback (PlaybackHandle & playback, SoundHandle sound, PlaybackExitCallback callback=nullptr) Creates a playback instance with a sound and prepares it for playback.
Result	DestroyBus (const char * identifier) Decrements the reference count of a bus and destroys it if the count reaches zero.
Result	DestroyEffect (EffectHandle effect) Destroys an effect.
Result	DetachEffect (EffectHandle effect) Removes an effect from the mix graph, regardless of which bus it is routed to.
	Engine ()
	Engine (const Engine &) = delete
Result	Init (const EngineConfig & config=EngineConfig{}) Initializes the engine, hardware device and background threads.
Result	LoadSoundAsync (SoundHandle & sound, SoundType type, const char * filepath, AssetLoadCallback callback=nullptr, uint32_t * outRequestId=nullptr) Asynchronously loads a sound into memory or prepares a file for streaming.
Result	PausePlayback (PlaybackHandle playback) Pauses a playback instance.
Result	PlayPlayback (PlaybackHandle playback) Starts or resumes a playback instance.
Result	RouteBus (const char * identifier, const char * parentIdentifier) Modifies the routing topology by changing the output destination of an existing bus.
Result	RoutePlayback (PlaybackHandle playback, const char * busIdentifier) Routes a playback instance to output its audio into the specified mixing bus.
Result	SeekPlayback (PlaybackHandle playback, double timeInSeconds) Seeks a playback instance to a specified time offset.
Result	SetBiquadParams (EffectHandle effect, const BiquadConfig & config) Updates the DSP parameters of an existing Biquad filter.
Result	SetBusVolumeDb (const char * identifier, float volumeDb) Sets the mixing volume of a bus in decibels (dB).
Result	SetGlobalDopplerFactor (float globalDopplerFactor) Sets the global scaling factor for the Doppler effect for the entire engine.
Result	SetListener3DAttributes (uint32_t listenerIndex, const Listener3DAttributes & attributes) Updates the complete 3D state of a listener.
Result	SetListenerActive (uint32_t listenerIndex, bool active) Enables or disables a listener.
Result	SetListenerDistanceProbePosition (uint32_t listenerIndex, const Vec3 & distanceProbePosition) Sets the distance probe world position for a listener.
Result	SetListenerOrientation (uint32_t listenerIndex, const Vec3 & forward, const Vec3 & up) Sets the facing direction of a listener.
Result	SetListenerPosition (uint32_t listenerIndex, const Vec3 & position) Updates the world position of a listener.
Result	SetListenerVelocity (uint32_t listenerIndex, const Vec3 & velocity) Sets the velocity of a listener.
Result	SetPlaybackAttenuationCurve (PlaybackHandle playback, AttenuationCurve curve) Sets the curve used to evaluate volume drop-off over distance for a playback instance.
Result	SetPlaybackDistanceMode (PlaybackHandle playback, DistanceMode mode) Defines which listener position is used when calculating the distance attenuation for a playback instance.
Result	SetPlaybackDopplerFactor (PlaybackHandle playback, float dopplerFactor) Sets the scaling factor for the Doppler effect for a playback instance.
Result	SetPlaybackListenerMask (PlaybackHandle playback, ListenerMask mask) Sets the listener routing mask for a playback instance.
Result	SetPlaybackLooping (PlaybackHandle playback, bool looping) Sets the looping state a playback instance.
Result	SetPlaybackMinMaxDistance (PlaybackHandle playback, float minDistance, float maxDistance) Defines the distance boundaries for the attenuation curve of a playback instance.
Result	SetPlaybackPitch (PlaybackHandle playback, float pitch) Sets the pitch of a playback instance.
Result	SetPlaybackPosition (PlaybackHandle playback, const Vec3 & position) Updates the 3D world position of a playback instance.
Result	SetPlaybackSpatial (PlaybackHandle playback, bool spatial) Enables or disables 3D spatialization for a playback instance.
Result	SetPlaybackStereoPan (PlaybackHandle playback, float pan) Sets the stereo pan of a playback instance.
Result	SetPlaybackUseDoppler (PlaybackHandle playback, bool useDoppler) Enables or disables the Doppler effect for a playback instance.
Result	SetPlaybackVelocity (PlaybackHandle playback, const Vec3 & velocity) Sets the velocity of a playback instance.
Result	SetPlaybackVolumeDb (PlaybackHandle playback, float volumeDb) Sets the mixing volume of a playback instance in decibels (dB).
Result	Shutdown () Halts all audio processing, terminates all background threads and frees allocated engine memory.
Result	StopPlayback (PlaybackHandle playback) Stops a playback instance.
Result	UnloadSound (SoundHandle soundHandle) Decrements the reference count of a sound and unloads it if the count reaches zero.
void	Update () The per-frame tick method for the engine.
Engine &	operator= (const Engine &) = delete
	~Engine ()

Public Functions Documentation¶

function AttachEffect¶

Inserts an allocated effect into the processing chain of a specified bus.

Result dalia::Engine::AttachEffect (
    EffectHandle effect,
    const char * busIdentifier,
    uint32_t effectSlot
)

A bus can hold up to four effects at a time. Attached effects are processed sequentially from slot 0 to slot 3.

Note:

[Exclusive Routing] A single effect instance can only be attached to one bus at a time. Attaching an effect that is already attached to a bus will forcefully detach that effect from its old bus. Doing so is generally not recommended if the bus is being played through as it can potentially cause a pop in the audio output due to bypassing the built-in effect fade-out.

Note:

[Hot-Swap] If the specified slot on the target bus is already occupied by another effect, the existing effect will be forcefully detached and replaced by the new effect. Doing so is generally not recommended for the same reasons mentioned above.

Parameters:

effect The handle to the effect.
busIdentifier The unique string identifier of the target bus.
effectSlot The index in the effect rack of the bus (0 to 3).

Return value:

Result::Ok The effect was successfully attached to the bus.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The effect handle is not recognized.
Result::ExpiredHandle The effect handle points to an already destroyed effect.
Result::BusNotFound The target bus does not exist.
Result::InvalidEffectSlot The requested slot exceeds the rack index limit.

function CreateBiquadFilter¶

Creates a new Biquad filter effect.

Result dalia::Engine::CreateBiquadFilter (
    EffectHandle & effect,
    BiquadFilterType type,
    const BiquadConfig & config
)

The effect is unattached upon creation.

Parameters:

effect The handle to the effect.
type The mathematical curve of the filter.
config The initial DSP parameters of the filter. The DSP parameters are automatically clamped. Frequencies are clamped between 20Hz and 20kHz and Resonance is clamped between 0.1 and 10.0.

Return value:

Result::Ok The filter was successfully created.
Result::NotInitialized The engine is not initialized.
Result::BiquadFilterPoolExhausted The allocated Biquad filter capacity has been reached.

function CreateBus¶

Creates a new mixing bus.

Result dalia::Engine::CreateBus (
    const char * identifier,
    const char * parentIdentifier="Master"
)

Note:

[Reference Counting] Buses are reference counted via their string identifiers. If CreateBus is called for an identifier that already exists, the engine will increment its reference count. If the bus already exists, any new parentIdentifier provided in subsequent calls is ignored and a warning is logged.

Parameters:

identifier The unique string identifier of the bus.
parentIdentifier Optional. The unique string identifier of the parent bus (defaults to Master).

Return value:

Result::Ok The bus was successfully created or its reference count was incremented.
Result::NotInitialized The engine is not initialized.
Result::BusNotFound The parent bus does not exist.
Result::BusPoolExhausted The allocated bus capacity has been reached.

function CreatePlayback¶

Creates a playback instance with a sound and prepares it for playback.

Result dalia::Engine::CreatePlayback (
    PlaybackHandle & playback,
    SoundHandle sound,
    PlaybackExitCallback callback=nullptr
)

This function does not start playback.

Note:

[Deferred Playback] This function will still succeed if the sound is still being loaded asynchronously.

Note:

[Playback Lifecycle] Playback instances are immediately invalidated upon stopping. Because of this, always check the return value of any playback modifying methods to make sure the handle is still valid.

Parameters:

playback The handle to the playback instance.
sound The handle to the sound.
callback Optional. If provided, this function will be called when the playback terminates.

Return value:

Result::Ok The playback instance was successfully created.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The sound handle is not recognized.
Result::SoundLoadError The sound asset previously failed to load.
Result::VoicePoolExhausted The allocated voice capacity has been reached.
Result::StreamPoolExhausted The allocated stream capacity has been reached.
Result::IoStreamRequestQueueFull The I/O streaming request queue is at capacity.

function DestroyBus¶

Decrements the reference count of a bus and destroys it if the count reaches zero.

Result dalia::Engine::DestroyBus (
    const char * identifier
)

If the bus is destroyed, any child buses or active playbacks that are routed to this bus are orphaned. An orphaned bus can be rerouted to a new parent bus, but an orphaned voice will immediately be stopped by the engine with the exit condition ExplicitStop.

Note:

[Master Immunity] The Master bus is permanently allocated by the engine and cannot be destroyed.

Parameters:

identifier The unique string identifier of the bus.

Return value:

Result::Ok The bus was successfully destroyed or its reference count was decremented.
Result::NotInitialized The engine is not initialized.
Result::BusNotFound The bus does not exist or has already been destroyed.
Result::Error Attempted to destroy Master bus.

function DestroyEffect¶

Destroys an effect.

Result dalia::Engine::DestroyEffect (
    EffectHandle effect
)

If the effect is attached to a bus, the engine will automatically detach it before destroying it.

Note:

[Attached Effects] Destroying an effect that is attached to a bus that is being played through is generally not recommended as it can cause a pop in the audio output due to bypassing the built-in effect fade-out.

Parameters:

effect The handle to the effect.

Return value:

Result::Ok The effect was successfully destroyed.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The effect handle is not recognized.
Result::ExpiredHandle The effect handle points to an already destroyed effect.

function DetachEffect¶

Removes an effect from the mix graph, regardless of which bus it is routed to.

Result dalia::Engine::DetachEffect (
    EffectHandle effect
)

Note:

[Effect Lifetime] Detaching an effect does not destroy it.

Parameters:

effect The handle to the effect.

Return value:

Result::Ok The effect was successfully detached.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The effect handle is not recognized.
Result::ExpiredHandle The effect handle points to an already destroyed effect.

function Engine [1/2]¶

dalia::Engine::Engine ()

function Engine [2/2]¶

dalia::Engine::Engine (
    const Engine &
) = delete

function Init¶

Initializes the engine, hardware device and background threads.

Result dalia::Engine::Init (
    const EngineConfig & config=EngineConfig {}
)

This function allocates all internal memory pools and starts the background audio thread, I/O loading thread, and I/O streaming thread. It must be called once before any other engine methods are used.

Note:

[Hardware Device] The engine will default to the OS's default audio device.

Parameters:

config The initialization settings for the engine.

Return value:

Result::Ok The engine was successfully initialized and is ready for use.
Result::AlreadyInitialized Attempted to initialize an already initialized engine.
Result::DeviceFailed The operating system failed to initialize or start the audio device.

function LoadSoundAsync¶

Asynchronously loads a sound into memory or prepares a file for streaming.

Result dalia::Engine::LoadSoundAsync (
    SoundHandle & sound,
    SoundType type,
    const char * filepath,
    AssetLoadCallback callback=nullptr,
    uint32_t * outRequestId=nullptr
)

This function returns immediately and does not block the calling thread. The provided sound is valid immediately if the call succeeds. If playback using the sound is attempted before the load is complete, the engine will safely defer the playback request internally.

Note:

[Reference Counting] Sounds are reference counted. If the requested filepath with the same SoundType is already loaded, this function increments a reference count and returns the already loaded sound. Because of this, one must also unload a sound the same number of times as it has been loaded in order to properly unload it from the engine.

Parameters:

sound The handle to the sound.
type Specifies if the sound should be fully decoded into memory (Resident) or streamed directly from disk (Stream).
filepath The string path to the audio asset.
callback Optional. If provided, this function will be called when the load finishes.
outRequestId Optional. Populated with a unique ID for the async request. It will evaluate to INVALID_REQUEST_ID if the asset is already loaded.

Return value:

Result::Ok The request was successfully queued for load or is already loaded.
Result::NotInitialized The engine is not initialized.
Result::ResidentSoundPoolExhausted The allocated capacity for resident sounds has been reached.
Result::StreamSoundPoolExhausted The allocated capacity for stream sounds has been reached.

function PausePlayback¶

Pauses a playback instance.

Result dalia::Engine::PausePlayback (
    PlaybackHandle playback
)

Parameters:

playback The handle to the playback instance.

Return value:

Result::Ok The playback instance was successfully set to pause.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function PlayPlayback¶

Starts or resumes a playback instance.

Result dalia::Engine::PlayPlayback (
    PlaybackHandle playback
)

If the playback instance is paused, calling this function will resume it from the current position. If it is inactive, it will play from the start.

Note:

[Deferred Playback] It is safe to call this function on a playback instance that is still waiting for its sound to load. The playback will start as soon as the sound has been loaded in.

Parameters:

playback The handle to the playback instance.

Return value:

Result::Ok The playback instance was successfully set to play.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.
Result::PlaybackCorrupted The internal state of the playback instance has been corrupted.

function RouteBus¶

Modifies the routing topology by changing the output destination of an existing bus.

Result dalia::Engine::RouteBus (
    const char * identifier,
    const char * parentIdentifier
)

Moves a bus and all of its attached children (buses and playbacks) to a new parent bus in the mixing hierarchy.

Note:

[Hierarchy Protection] The mixing hierarchy must always remain a strict directed acyclic graph (DAG). If an attempt is made to route a bus into itself or into one of its own descendants, this function will return an error. Additionally, the Master bus cannot be re-routed.

Parameters:

identifier The unique string identifier of the bus.
parentIdentifier The unique string identifier of the new parent bus (must be an existing bus).

Return value:

Result::Ok The bus was successfully re-routed.
Result::NotInitialized The engine is not initialized.
Result::InvalidRouting Attempted a route that would result in a cyclic bus hierarchy, or attempted to route Master.
Result::BusNotFound Either the bus or the parent bus does not exist.

function RoutePlayback¶

Routes a playback instance to output its audio into the specified mixing bus.

Result dalia::Engine::RoutePlayback (
    PlaybackHandle playback,
    const char * busIdentifier
)

This function can be called both before and during playback.

Parameters:

playback The handle to the playback instance.
busIdentifier The unique string identifier of the target bus.

Return value:

Result::Ok The voice was successfully routed.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.
Result::BusNotFound The target bus does not exist.

function SeekPlayback¶

Seeks a playback instance to a specified time offset.

Result dalia::Engine::SeekPlayback (
    PlaybackHandle playback,
    double timeInSeconds
)

Parameters:

playback The handle to the playback instance.
timeInSeconds The time offset from the start of the sound (in seconds). This value is automatically clamped between 0.0 and the length of the sound.

Return value:

Result::Ok The seek was successfully performed.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetBiquadParams¶

Updates the DSP parameters of an existing Biquad filter.

Result dalia::Engine::SetBiquadParams (
    EffectHandle effect,
    const BiquadConfig & config
)

Parameters:

effect The handle to the effect.
config The new DSP parameters for the Biquad filter.

Return value:

Result::Ok
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The effect handle is not recognized or is for a different effect type.
Result::ExpiredHandle The effect handle points to an already destroyed effect.

function SetBusVolumeDb¶

Sets the mixing volume of a bus in decibels (dB).

Result dalia::Engine::SetBusVolumeDb (
    const char * identifier,
    float volumeDb
)

Parameters:

identifier The unique string identifier of the bus.
volumeDb The new volume in decibels (dB). A value of 0.0 represents unity gain. The volume is automatically clamped to the engine's safe operating range (between -60.0dB and +12.0dB).

Return value:

Result::Ok The mixing volume of the bus was successfully updated.
Result::NotInitialized The engine is not initialized.
Result::BusNotFound The bus does not exist.

function SetGlobalDopplerFactor¶

Sets the global scaling factor for the Doppler effect for the entire engine.

Result dalia::Engine::SetGlobalDopplerFactor (
    float globalDopplerFactor
)

Parameters:

globalDopplerFactor The global scaling factor. Clamped internally between 0.0 and 10.0.

Return value:

Result::Ok The global scaling factor for the Doppler effect was successfully set.
Result::NotInitialized The engine is not initialized.

function SetListener3DAttributes¶

Updates the complete 3D state of a listener.

Result dalia::Engine::SetListener3DAttributes (
    uint32_t listenerIndex,
    const Listener3DAttributes & attributes
)

Parameters:

listenerIndex The zero-based index of the listener.
attributes The new 3D attributes.

Return value:

Result::Ok The listener 3D attributes were successfully set.
Result::NotInitialized The engine is not initialized.
Result::ListenerNotFound The listener index exceeds the allocated listener capacity.

function SetListenerActive¶

Enables or disables a listener.

Result dalia::Engine::SetListenerActive (
    uint32_t listenerIndex,
    bool active
)

Parameters:

listenerIndex The zero-based index of the listener.
active True to enable the listener, false to disable it.

Return value:

Result::Ok The listener was successfully enabled or disabled.
Result::NotInitialized The engine is not initialized.
Result::ListenerNotFound The listener index exceeds the allocated listener capacity.

function SetListenerDistanceProbePosition¶

Sets the distance probe world position for a listener.

Result dalia::Engine::SetListenerDistanceProbePosition (
    uint32_t listenerIndex,
    const Vec3 & distanceProbePosition
)

Note:

[Usage] This position is only used for distance attenuation by playback instances with distance mode set to FromDistanceProbe.

Parameters:

listenerIndex The zero-based index of the listener.
distanceProbePosition The new world position.

Return value:

Result::Ok The listener's distance probe world position was successfully set.
Result::NotInitialized The engine is not initialized.
Result::ListenerNotFound The listener index exceeds the allocated listener capacity.

function SetListenerOrientation¶

Sets the facing direction of a listener.

Result dalia::Engine::SetListenerOrientation (
    uint32_t listenerIndex,
    const Vec3 & forward,
    const Vec3 & up
)

Parameters:

listenerIndex The zero-based index of the listener.
forward The forward-facing direction vector. Normalized internally.
up The upward-facing direction vector. Normalized internally.

Return value:

Result::Ok The listener orientation was successfully set.
Result::NotInitialized The engine is not initialized.
Result::ListenerNotFound The listener index exceeds the allocated listener capacity.

function SetListenerPosition¶

Updates the world position of a listener.

Result dalia::Engine::SetListenerPosition (
    uint32_t listenerIndex,
    const Vec3 & position
)

Parameters:

listenerIndex The zero-based index of the listener.
position The new world position.

Return value:

Result::Ok The listener world position was successfully set.
Result::NotInitialized The engine is not initialized.
Result::ListenerNotFound The listener index exceeds the allocated listener capacity.

function SetListenerVelocity¶

Sets the velocity of a listener.

Result dalia::Engine::SetListenerVelocity (
    uint32_t listenerIndex,
    const Vec3 & velocity
)

Parameters:

listenerIndex The zero-based index of the listener.
velocity The velocity vector (in m/s).

Return value:

Result::Ok The listener velocity was successfully set.
Result::NotInitialized The engine is not initialized.
Result::ListenerNotFound The listener index exceeds the allocated listener capacity.

function SetPlaybackAttenuationCurve¶

Sets the curve used to evaluate volume drop-off over distance for a playback instance.

Result dalia::Engine::SetPlaybackAttenuationCurve (
    PlaybackHandle playback,
    AttenuationCurve curve
)

Note:

[Spatial only] This only affects playback instances that have spatialization enabled.

Parameters:

playback The handle to the playback instance.
curve The attenuation curve to apply.

Return value:

Result::Ok The playback attenuation curve was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackDistanceMode¶

Defines which listener position is used when calculating the distance attenuation for a playback instance.

Result dalia::Engine::SetPlaybackDistanceMode (
    PlaybackHandle playback,
    DistanceMode mode
)

Note:

[Spatial only] This only affects playback instances that have spatialization enabled.

Parameters:

playback The handle to the playback instance.
mode The distance evaluation mode to apply.

Return value:

Result::Ok The playback distance mode was successfully applied.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackDopplerFactor¶

Sets the scaling factor for the Doppler effect for a playback instance.

Result dalia::Engine::SetPlaybackDopplerFactor (
    PlaybackHandle playback,
    float dopplerFactor
)

Note:

[Spatial only] This only affects playback instances that have spatialization and Doppler pitch-shifting enabled.

Parameters:

playback The handle to the playback instance.
dopplerFactor The scaling factor. Clamped internally between 0.0 and 10.0.

Return value:

Result::Ok The playback Doppler effect's scaling factor was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackListenerMask¶

Sets the listener routing mask for a playback instance.

Result dalia::Engine::SetPlaybackListenerMask (
    PlaybackHandle playback,
    ListenerMask mask
)

The routing mask determines which listeners are allowed to hear and evaluate the playback instance.

Note:

[Spatial only] This only affects playback instances that have spatialization enabled.

Parameters:

playback The handle to the playback instance.
mask The listener routing bitmask.

Return value:

Result::Ok The listener routing mask for the playback instance was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackLooping¶

Sets the looping state a playback instance.

Result dalia::Engine::SetPlaybackLooping (
    PlaybackHandle playback,
    bool looping
)

This method updates whether a playback instance will automatically restart upon finishing.

Parameters:

playback The handle to the playback instance.
looping The looping state.

Return value:

Result::Ok The playback instance looping state was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackMinMaxDistance¶

Defines the distance boundaries for the attenuation curve of a playback instance.

Result dalia::Engine::SetPlaybackMinMaxDistance (
    PlaybackHandle playback,
    float minDistance,
    float maxDistance
)

Note:

[Spatial only] This only affects playback instances that have spatialization enabled.

Note:

[Safe values] The engine internally ensures that maxDistance is never less than minDistance, and that minDistance respects the engine's absolute floor limit to prevent division-by-zero.

Parameters:

playback The handle to the playback instance.
minDistance The radius where the volume drop-off begins.
maxDistance The radius where the volume drops to silence.

Return value:

Result::Ok The playback min and max distance were successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackPitch¶

Sets the pitch of a playback instance.

Result dalia::Engine::SetPlaybackPitch (
    PlaybackHandle playback,
    float pitch
)

Parameters:

playback The handle to the playback instance.
pitch The new pitch. This is clamped internally between 0.1 and 4.0 to prevent performance issues.

Return value:

Result::Ok The pitch of the playback instance was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackPosition¶

Updates the 3D world position of a playback instance.

Result dalia::Engine::SetPlaybackPosition (
    PlaybackHandle playback,
    const Vec3 & position
)

Note:

[Spatial only] This only affects playback instances that have spatialization enabled.

Parameters:

playback The handle to the playback instance.
position The new 3D world coordinates.

Return value:

Result::Ok The playback world position was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackSpatial¶

Enables or disables 3D spatialization for a playback instance.

Result dalia::Engine::SetPlaybackSpatial (
    PlaybackHandle playback,
    bool spatial
)

Parameters:

playback The handle to the playback instance.
spatial True to enable 3D spatialization, false for 2D/global playback.

Return value:

Result::Ok The playback spatialization was successfully enabled or disabled.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackStereoPan¶

Sets the stereo pan of a playback instance.

Result dalia::Engine::SetPlaybackStereoPan (
    PlaybackHandle playback,
    float pan
)

Note:

[Spatial] This only affects playback instances that have spatialization disabled.

Parameters:

playback The handle to the playback instance.
pan The normalized pan position. A value of 0.0 represents an equal distribution between L and R, -1.0 is full L and 1.0 is full R.

Return value:

Result::Ok The pan of the playback instance was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackUseDoppler¶

Enables or disables the Doppler effect for a playback instance.

Result dalia::Engine::SetPlaybackUseDoppler (
    PlaybackHandle playback,
    bool useDoppler
)

Note:

[Spatial only] This only affects playback instances that have spatialization enabled.

Note:

[Requirements] In order for the doppler pitch shifting to be used, both listener and playback velocity must be supplied to the engine every frame.

Parameters:

playback The handle to the playback instance.
useDoppler True to enable Doppler pitch shifting, false to disable it.

Return value:

Result::Ok The playback Doppler effect was successfully enabled or disabled.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackVelocity¶

Sets the velocity of a playback instance.

Result dalia::Engine::SetPlaybackVelocity (
    PlaybackHandle playback,
    const Vec3 & velocity
)

Velocity is used exclusively to calculate the Doppler effect. If the Effect is disabled, this value is ignored.

Note:

[Spatial only] This only affects playback instances that have spatialization enabled.

Parameters:

playback The handle to the playback instance.
velocity The velocity vector (in m/s).

Return value:

Result::Ok The playback velocity was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function SetPlaybackVolumeDb¶

Sets the mixing volume of a playback instance in decibels (dB).

Result dalia::Engine::SetPlaybackVolumeDb (
    PlaybackHandle playback,
    float volumeDb
)

Parameters:

playback The handle to the playback instance.
volumeDb The new volume in decibels (dB). A value of 0.0 represents unity gain. The volume is automatically clamped to the engine's safe operating range (between -60.0dB and +12.0dB).

Return value:

Result::Ok The mixing volume of the playback instance was successfully set.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function Shutdown¶

Halts all audio processing, terminates all background threads and frees allocated engine memory.

Result dalia::Engine::Shutdown ()

Note:

[Blocking Operation] This method will block the calling thread until all background threads have fully joined.

Note:

[Handle Invalidation] Calling this method will invalidate all handles.

Return value:

Result::Ok The engine was successfully shut down.
Result::NotInitialized Attempted to shut down an engine that is not initialized.
Result::DeviceFailed The operating system failed to release the hardware device.

function StopPlayback¶

Stops a playback instance.

Result dalia::Engine::StopPlayback (
    PlaybackHandle playback
)

If a callback function was provided when creating the playback instance, it will be called with the exit condition ExplicitStop once the playback has been stopped.

Note:

[Playback Lifecycle] Successfully calling this function invalidates the provided PlaybackHandle. A stopped playback cannot be restarted.

Parameters:

playback The handle to the playback instance.

Return value:

Result::Ok The playback instance was successfully set to stop.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The playback handle is not recognized.
Result::ExpiredHandle The playback handle has already stopped playing.

function UnloadSound¶

Decrements the reference count of a sound and unloads it if the count reaches zero.

Result dalia::Engine::UnloadSound (
    SoundHandle soundHandle
)

If the reference count of a sound reaches zero, all active playbacks using the sound will be stopped with the exit condition ExplicitStop. The engine will also immediately abort all pending playback requests with the same exit condition.

Parameters:

soundHandle The handle to the sound.

Return value:

Result::Ok The sound was successfully unloaded or its reference count was decremented.
Result::NotInitialized The engine is not initialized.
Result::InvalidHandle The sound handle is not recognized, or has already been freed.

function Update¶

The per-frame tick method for the engine.

void dalia::Engine::Update ()

This method is the primary synchronization router between the API (calling) thread and the background threads. It must be called exactly once per frame inside the update loop of your main thread.

Note:

[Callback Execution] This method processes all events happening within the engine. It is within this method that any provided AudioEventCallback and AssetLoadCallback functions are invoked.

function operator=¶

Engine & dalia::Engine::operator= (
    const Engine &
) = delete

function ~Engine¶

dalia::Engine::~Engine ()

The documentation for this class was generated from the following file engine/include/dalia/audio/Engine.h