Engine¶

class Engine

The Amplitude Engine.

This is the main class of the library that manages all the entities and provides methods to create, destroy, and manipulate them. You can also access to the internal state of the engine through the public API.

The Engine is a singleton class and you can access it using the amEngine macro. Before using most of the methods of the engine, you need to initialize the engine first, for example:

amEngine->Initialize("config.amconfig");
//...
amEngine->Deinitialize();

Functions¶

Name	Description
Version	Gets the version structure.
Initialize	Initializes the Amplitude engine.
Deinitialize	Deinitializes the Amplitude engine.
IsInitialized	Checks if the Amplitude engine has been successfully initialized.
SetFileSystem	Sets a file system implementation to be used by the engine.
GetFileSystem	Gets the file system implementation used by the engine.
StartOpenFileSystem	Opens the file system, usually in a separate thread.
TryFinalizeOpenFileSystem	Checks if the file system has been fully loaded.
StartCloseFileSystem	Closes the file system, usually in a separate thread.
TryFinalizeCloseFileSystem	Checks if the file system has been fully closed.
AdvanceFrame	Updates the engine state for the given number of milliseconds.
OnNextFrame	Executes the given callback on the next frame.
WaitUntilNextFrame	Waits until the next frame is ready.
WaitUntilFrames	Waits until the specified number of frames are ready.
GetTotalTime	Gets the total elapsed time in milliseconds since the start of the engine.
LoadSoundBank	Loads a sound bank from a binary asset file (`.ambank`).
LoadSoundBank	Loads a sound bank from a binary asset file (`.ambank`).
LoadSoundBankFromMemory	Loads a sound bank from memory.
LoadSoundBankFromMemory	Loads a sound bank from memory.
LoadSoundBankFromMemoryView	Loads a sound bank from memory.
LoadSoundBankFromMemoryView	Loads a sound bank from memory.
UnloadSoundBank	Unloads a sound bank given its filename.
UnloadSoundBank	Unloads a sound bank given its ID.
UnloadSoundBanks	Unloads all the loaded sound banks.
StartLoadSoundFiles	Starts the loading of sound files referenced in loaded sound banks.
TryFinalizeLoadSoundFiles	Checks if the loading of sound files has been completed, and releases used resources.
GetSwitchContainerHandle	Gets a `SwitchContainerHandle` given its name as defined in its asset file (`.amswitchcontainer`).
GetSwitchContainerHandle	Gets a `SwitchContainerHandle` given its ID as defined in its asset file (`.amswitchcontainer`).
GetSwitchContainerHandleFromFile	Gets a `SwitchContainerHandle` given its asset's filename.
GetCollectionHandle	Gets a `CollectionHandle` given its name as defined in its asset file (`.amcollection`).
GetCollectionHandle	Gets a `CollectionHandle` given its ID as defined in its asset file (`.amcollection`).
GetCollectionHandleFromFile	Gets a `CollectionHandle` given its asset's filename.
GetSoundHandle	Gets a `SoundHandle` given its name as defined in its asset file (`.amsound`).
GetSoundHandle	Gets a `SoundHandle` given its ID as defined in its asset file (`.amsound`).
GetSoundHandleFromFile	Gets a `SoundHandle` given its asset's filename.
GetSoundObjectHandle	Gets a `SoundObjectHandle` given its name as defined in its asset file.
GetSoundObjectHandle	Gets a `SoundObjectHandle` given its ID as defined in its asset file.
GetSoundObjectHandleFromFile	Gets a `SoundObjectHandle` given its asset's filename.
GetEventHandle	Gets an `EventHandle` given its name as defined in its asset file (`.amevent`).
GetEventHandle	Gets an `EventHandle` given its ID as defined in its asset file (`.amevent`).
GetEventHandleFromFile	Gets an `EventHandle` given its asset's filename.
GetAttenuationHandle	Gets an `AttenuationHandle` given its name as defined in its asset file (`.amattenuation`).
GetAttenuationHandle	Gets an `AttenuationHandle` given its ID as defined in its asset file (`.amattenuation`).
GetAttenuationHandleFromFile	Gets an `AttenuationHandle` given its asset's filename.
GetSwitchHandle	Gets a `SwitchHandle` given its name as defined in its asset file (`.amswitch`).
GetSwitchHandle	Gets a `SwitchHandle` given its ID as defined in its asset file (`.amswitch`).
GetSwitchHandleFromFile	Gets a `SwitchHandle` given its asset's filename.
GetRtpcHandle	Gets a `RtpcHandle` given its name as defined in its asset file (`.amrtpc`).
GetRtpcHandle	Gets an `RtpcHandle` given its ID as defined in its asset file (`.amrtpc`).
GetRtpcHandleFromFile	Gets an `RtpcHandle` given its asset's filename.
GetEffectHandle	Gets an `EffectHandle` given its name as defined in its asset file (`.amfx`).
GetEffectHandle	Gets an `EffectHandle` given its ID as defined in its asset file (`.amfx`).
GetEffectHandleFromFile	Gets an `EffectHandle` given its asset's filename.
GetPipelineHandle	Gets a `PipelineHandle` from the loaded pipeline asset file (`.ampipeline`).
SetMasterGain	Adjusts the master gain of the mixer.
GetMasterGain	Gets the mixer master gain.
SetMute	Mutes the engine, but keep processing audio.
IsMuted	Checks whether the engine is currently muted.
Pause	Pauses or resumes all playing sounds and streams.
IsPaused	Checks whether the engine is currently paused.
SetDefaultListener	Sets the default sound listener.
SetDefaultListener	Sets the default sound listener.
GetDefaultListener	Gets the default audio `Listener`.
AddListener	Initializes and returns a new `Listener`.
GetListener	Returns the `Listener` with the given ID.
RemoveListener	Removes a `Listener` given its ID.
RemoveListener	Removes a `Listener` given its handle.
AddEntity	Initializes and returns a new `Entity`.
GetEntity	Returns the `Entity` with the given ID.
RemoveEntity	Removes an `Entity`.
RemoveEntity	Removes an `Entity` given its ID.
AddEnvironment	Initializes and return a new `Environment`.
GetEnvironment	Returns the `Environment` with the given ID.
RemoveEnvironment	Removes an `Environment`.
RemoveEnvironment	Removes an `Environment` given its ID.
AddRoom	Initializes and return a new `Room`.
GetRoom	Returns the `Room` with the given ID.
RemoveRoom	Removes a `Room`.
RemoveRoom	Removes a `Room` given its ID.
FindBus	Returns the `Bus` with the specified name.
FindBus	Returns the `Bus` with the given ID.
Play	Plays a switch container associated with the given handle in the World scope.
Play	Plays a switch container associated with the given handle in the World scope.
Play	Plays a switch container associated with the given handle in the World scope.
Play	Plays a switch container associated with the given handle in an Entity scope.
Play	Plays a switch container associated with the given handle in an Entity scope.
Play	Plays a collection associated with the given handle in the World scope.
Play	Plays a collection associated with the given handle in the World scope.
Play	Plays a collection associated with the given handle in the World scope.
Play	Plays a collection associated with the given handle in the Entity scope.
Play	Plays a collection associated with the given handle in an Entity scope.
Play	Plays a sound associated with the given handle in the World scope.
Play	Plays a sound associated with the given handle in the World scope.
Play	Plays a sound associated with the given handle in the World scope.
Play	Plays a sound associated with the given sound handle in an Entity scope.
Play	Plays a sound associated with the given sound handle in an Entity.
Play	Plays a sound object associated with the given name in the World scope.
Play	Plays a sound object associated with the given name in the World scope.
Play	Plays a sound object associated with the given name in the World scope.
Play	Plays a sound object associated with the given name in an Entity scope.
Play	Plays a sound object associated with the given name in an Entity scope.
Play	Plays a sound object associated with the given ID in the World scope.
Play	Plays a sound object associated with the given ID in the World scope.
Play	Plays a sound object associated with the given ID in the World scope.
Play	Plays a sound object associated with the given ID in an Entity scope.
Play	Plays a sound object associated with the given ID in an Entity scope.
StopAll	Stops all playing sound objects.
Trigger	Triggers the event associated to the given handle.
Trigger	Triggers the event associated to the given handle.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetSwitchState	Sets the active state of the defined `Switch`.
SetRtpcValue	Sets the value of a `RTPC`.
SetRtpcValue	Sets the value of a `RTPC`.
SetRtpcValue	Sets the value of a `RTPC`.
GetDriver	Gets the audio driver used by the Engine.
GetMixer	Gets the mixer instance.
GetSoundSpeed	Gets the speed of sound, as set in the loaded engine configuration file.
GetDopplerFactor	Get the Doppler factor, as set in the loaded engine configuration file.
GetSamplesPerStream	Get the number of samples to process in one stream, as set in the loaded engine configuration file.
IsGameTrackingEnvironmentAmounts	Checks whether the game is tracking environment amounts himself.
GetMaxListenersCount	Gets the maximum number of listeners handled by the engine.
GetMaxEntitiesCount	Gets the maximum number of game entities handled by the engine.
GetOcclusionCoefficientCurve	Gets the occlusion coefficient curve, as set in the loaded engine configuration file.
GetOcclusionGainCurve	Gets the occlusion gain curve, as set in the loaded engine configuration file.
GetObstructionCoefficientCurve	Gets the obstruction coefficient curve, as set in the loaded engine configuration file.
GetObstructionGainCurve	Gets the obstruction gain curve, as set in the loaded engine configuration file.
GetPanningMode	Gets the panning mode defined in the loaded engine configuration.
GetHRIRSphereSamplingMode	Gets the HRIR sphere sampling mode defined in the loaded engine configuration.
GetHRIRSphere	Gets the HRIR sphere defined in the loaded engine configuration.
LoadPlugin	Loads a plugin library from the given path.
AddPluginSearchPath	Adds a path in the plugins search paths list.
RemovePluginSearchPath	Removes a path from the plugins search paths list.
RegisterDefaultPlugins	Register all default plugins.
UnregisterDefaultPlugins	Unregister all default plugins.
GetInstance	Returns an unique instance of the Amplitude Engine.
DestroyInstance	Destroys the unique instance of the Amplitude Engine.

Function Details¶

AddEntity ¶

[[nodiscard]] virtual Entity AddEntity(AmEntityID id) const = 0

Initializes and returns a new Entity.

Parameter id: The game entity ID.
Return: An initialized Entity.

AddEnvironment ¶

[[nodiscard]] virtual Environment AddEnvironment(AmEnvironmentID id) const = 0

Initializes and return a new Environment.

Parameter id: The game environment ID.
Return: An initialized Environment.

AddListener ¶

[[nodiscard]] virtual Listener AddListener(AmListenerID id) const = 0

Initializes and returns a new Listener.

Parameter id: The new listener ID.
Return: An initialized Listener.

AddPluginSearchPath ¶

static void AddPluginSearchPath(const AmOsString& path)

Adds a path in the plugins search paths list.

Parameter path: The path to add in the plugins search paths list.

AddRoom ¶

[[nodiscard]] virtual Room AddRoom(AmRoomID id) const = 0

Initializes and return a new Room.

Parameter id: The room ID.
Return: An initialized Room.

AdvanceFrame ¶

virtual void AdvanceFrame(AmTime delta) const = 0

Updates the engine state for the given number of milliseconds.

Parameter delta: The number of milliseconds since the last frame.

Deinitialize ¶

virtual bool Deinitialize() = 0

Deinitializes the Amplitude engine.

Return: true when the engine has been successfully deinitialized, false otherwise.

DestroyInstance ¶

static void DestroyInstance()

Destroys the unique instance of the Amplitude Engine.

FindBus ¶

[[nodiscard]] virtual Bus FindBus(const AmString& name) const = 0

Returns the Bus with the specified name.

Parameter name: The name of the bus.

Note

The name should match one of the buses loaded from the asset file (.ambus).

Return: A valid Bus if found, otherwise an invalid Bus.

[[nodiscard]] virtual Bus FindBus(AmBusID id) const = 0

Returns the Bus with the given ID.

Parameter id: The ID of the bus.

Note

The ID should match one of the buses loaded from the asset file (.ambus).

Return: A valid Bus if found, otherwise an invalid Bus.

GetAttenuationHandle ¶

[[nodiscard]] virtual AttenuationHandle GetAttenuationHandle(const AmString& name) const = 0

Gets an AttenuationHandle given its name as defined in its asset file (.amattenuation).

Parameter name: The unique name as defined in the asset file.
Return: The AttenuationHandle for the given name, or an invalid handle if no attenuation with that name was found in any loaded sound bank.

[[nodiscard]] virtual AttenuationHandle GetAttenuationHandle(AmAttenuationID id) const = 0

Gets an AttenuationHandle given its ID as defined in its asset file (.amattenuation).

Parameter id: The unique ID as defined in the asset file.
Return: The AttenuationHandle for the given ID, or an invalid handle if no attenuation with that ID was found in any loaded sound bank.

GetAttenuationHandleFromFile ¶

[[nodiscard]] virtual AttenuationHandle GetAttenuationHandleFromFile(const AmOsString& filename) const = 0

Gets an AttenuationHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the attenuators directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "attenuators/impact.amattenuation"
AttenuationHandle handle = amEngine->GetAttenuationHandleFromFile("impact.amattenuation");

Return: The AttenuationHandle for the given asset's filename, or an invalid handle if no attenuation with that filename was found in any loaded sound bank.

GetCollectionHandle ¶

[[nodiscard]] virtual CollectionHandle GetCollectionHandle(const AmString& name) const = 0

Gets a CollectionHandle given its name as defined in its asset file (.amcollection).

Parameter name: The unique name as defined in the asset file.
Return: The CollectionHandle for the given name, or an invalid handle if no collection with that name was found in any loaded sound bank.

[[nodiscard]] virtual CollectionHandle GetCollectionHandle(AmCollectionID id) const = 0

Gets a CollectionHandle given its ID as defined in its asset file (.amcollection).

Parameter id: The unique ID as defined in the asset file.
Return: The CollectionHandle for the given ID, or an invalid handle if no collection with that ID was found in any loaded sound bank.

GetCollectionHandleFromFile ¶

[[nodiscard]] virtual CollectionHandle GetCollectionHandleFromFile(const AmOsString& filename) const = 0

Gets a CollectionHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the collections directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "collections/weapons/ak47_gunfires.amcollection"
CollectionHandle handle = amEngine->GetCollectionHandleFromFile("weapons/ak47_gunfires.amcollection");

Return: The CollectionHandle for the given asset's filename, or an invalid handle if no collection with that filename was found in any loaded sound bank.

GetDefaultListener ¶

[[nodiscard]] virtual Listener GetDefaultListener() const = 0

Gets the default audio Listener.

Return: An initialized Listener object if a default listener was set, otherwise an uninitialized Listener object.

GetDopplerFactor ¶

[[nodiscard]] virtual AmReal32 GetDopplerFactor() const = 0

Get the Doppler factor, as set in the loaded engine configuration file.

Return: The Doppler factor.

GetDriver ¶

* GetDriver() const

Gets the audio driver used by the Engine.

Return: The audio driver.

GetEffectHandle ¶

[[nodiscard]] virtual EffectHandle GetEffectHandle(const AmString& name) const = 0

Gets an EffectHandle given its name as defined in its asset file (.amfx).

Parameter name: The unique name as defined in the asset file.
Return: The EffectHandle for the given name, or an invalid handle if no effect with that name was found in any loaded sound bank.

[[nodiscard]] virtual EffectHandle GetEffectHandle(AmEffectID id) const = 0

Gets an EffectHandle given its ID as defined in its asset file (.amfx).

Parameter id: The unique ID as defined in the asset file.
Return: The EffectHandle for the given ID, or an invalid handle if no effect with that ID was found in any loaded sound bank.

GetEffectHandleFromFile ¶

[[nodiscard]] virtual EffectHandle GetEffectHandleFromFile(const AmOsString& filename) const = 0

Gets an EffectHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the effects directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "effects/echo.amfx"
EffectHandle handle = amEngine->GetEffectHandleFromFile("echo.amfx");

Return: The EffectHandle for the given asset's filename, or an invalid handle if no effect with that filename was found in any loaded sound bank.

GetEntity ¶

[[nodiscard]] virtual Entity GetEntity(AmEntityID id) const = 0

Returns the Entity with the given ID.

Parameter id: The game entity ID.
Return: An initialized Entity if that one has been registered before, otherwise an uninitialized Entity.

GetEnvironment ¶

[[nodiscard]] virtual Environment GetEnvironment(AmEnvironmentID id) const = 0

Returns the Environment with the given ID.

Parameter id: The game environment ID.
Return: An initialized Environment if that one has been registered before, otherwise an uninitialized Environment.

GetEventHandle ¶

[[nodiscard]] virtual EventHandle GetEventHandle(const AmString& name) const = 0

Gets an EventHandle given its name as defined in its asset file (.amevent).

Parameter name: The unique name as defined in the asset file.
Return: The EventHandle for the given name, or an invalid handle if no event with that name was found in any loaded sound bank.

[[nodiscard]] virtual EventHandle GetEventHandle(AmEventID id) const = 0

Gets an EventHandle given its ID as defined in its asset file (.amevent).

Parameter id: The unique ID as defined in the asset file.
Return: The EventHandle for the given ID, or an invalid handle if no event with that ID was found in any loaded sound bank.

GetEventHandleFromFile ¶

[[nodiscard]] virtual EventHandle GetEventHandleFromFile(const AmOsString& filename) const = 0

Gets an EventHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the events directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "events/gameplay/start_menu.amevent"
EventHandle handle = amEngine->GetEventHandleFromFile("gameplay/start_menu.amevent");

Return: The EventHandle for the given asset's filename, or an invalid handle if no event with that filename was found in any loaded sound bank.

GetFileSystem ¶

* GetFileSystem() const

Gets the file system implementation used by the engine.

Return: The current file system implementation used by the engine, or nullptr if no file system has been set.

GetHRIRSphere ¶

* GetHRIRSphere() const

Gets the HRIR sphere defined in the loaded engine configuration.

Return: The HRIR sphere. If no HRIR sphere is defined, returns nullptr.

Note

The HRIR sphere is optional and can be null in some cases. If the engine does not have an HRIR sphere defined, this function will return nullptr.

See: HRIRSphere

GetHRIRSphereSamplingMode ¶

[[nodiscard]] virtual eHRIRSphereSamplingMode GetHRIRSphereSamplingMode() const = 0

Gets the HRIR sphere sampling mode defined in the loaded engine configuration.

Return: The HRIR sphere sampling mode.

GetInstance ¶

[[nodiscard]] static Engine* GetInstance()

Returns an unique instance of the Amplitude Engine.

GetListener ¶

[[nodiscard]] virtual Listener GetListener(AmListenerID id) const = 0

Returns the Listener with the given ID.

Parameter id: The listener ID.
Return: An initialized Listener if a one with the given ID has been registered before, otherwise an uninitialized Listener.

GetMasterGain ¶

[[nodiscard]] virtual AmReal32 GetMasterGain() const = 0

Gets the mixer master gain.

Return: The mixer master gain.

GetMaxEntitiesCount ¶

[[nodiscard]] virtual AmUInt32 GetMaxEntitiesCount() const = 0

Gets the maximum number of game entities handled by the engine.

This value does not reflect the maximum number of simultaneous sound handled by the engine.

Return: The maximum number of game entities.

GetMaxListenersCount ¶

[[nodiscard]] virtual AmUInt32 GetMaxListenersCount() const = 0

Gets the maximum number of listeners handled by the engine.

Return: The maximum number of listeners.

GetMixer ¶

* GetMixer() const

Gets the mixer instance.

Return: The Amplimix mixer instance.

GetObstructionCoefficientCurve ¶

[[nodiscard]] virtual const Curve& GetObstructionCoefficientCurve() const = 0

Gets the obstruction coefficient curve, as set in the loaded engine configuration file.

Return: The obstruction coefficient curve.

GetObstructionGainCurve ¶

[[nodiscard]] virtual const Curve& GetObstructionGainCurve() const = 0

Gets the obstruction gain curve, as set in the loaded engine configuration file.

Return: The obstruction gain curve.

GetOcclusionCoefficientCurve ¶

[[nodiscard]] virtual const Curve& GetOcclusionCoefficientCurve() const = 0

Gets the occlusion coefficient curve, as set in the loaded engine configuration file.

Return: The occlusion coefficient curve.

GetOcclusionGainCurve ¶

[[nodiscard]] virtual const Curve& GetOcclusionGainCurve() const = 0

Gets the occlusion gain curve, as set in the loaded engine configuration file.

Return: The occlusion gain curve.

GetPanningMode ¶

[[nodiscard]] virtual ePanningMode GetPanningMode() const = 0

Gets the panning mode defined in the loaded engine configuration.

Return: The panning mode.

GetPipelineHandle ¶

[[nodiscard]] virtual PipelineHandle GetPipelineHandle() const = 0

Gets a PipelineHandle from the loaded pipeline asset file (.ampipeline).

Note

Only one pipeline can be loaded at a time. The loaded pipeline asset is defined in the engine configuration file.

Return: The PipelineHandle for the loaded pipeline. This method should always return a valid handle.

GetRoom ¶

[[nodiscard]] virtual Room GetRoom(AmRoomID id) const = 0

Returns the Room with the given ID.

Parameter id: The room ID.
Return: An initialized Room if that one has been registered before, otherwise an uninitialized Room.

GetRtpcHandle ¶

[[nodiscard]] virtual RtpcHandle GetRtpcHandle(const AmString& name) const = 0

Gets a RtpcHandle given its name as defined in its asset file (.amrtpc).

Parameter name: The unique name as defined in the asset file.
Return: The RtpcHandle for the given name, or an invalid handle if no RTPC with that name was found in any loaded sound bank.

[[nodiscard]] virtual RtpcHandle GetRtpcHandle(AmRtpcID id) const = 0

Gets an RtpcHandle given its ID as defined in its asset file (.amrtpc).

Parameter id: The unique ID as defined in the asset file.
Return: The RtpcHandle for the given ID, or an invalid handle if no RTPC with that ID was found in any loaded sound bank.

GetRtpcHandleFromFile ¶

[[nodiscard]] virtual RtpcHandle GetRtpcHandleFromFile(const AmOsString& filename) const = 0

Gets an RtpcHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the rtpc directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "rtpc/music_volume.amrtpc"
RtpcHandle handle = amEngine->GetRtpcHandleFromFile("music_volume.amrtpc");

Return: The RtpcHandle for the given asset's filename, or an invalid handle if no RTPC with that filename was found in any loaded sound bank.

GetSamplesPerStream ¶

[[nodiscard]] virtual AmUInt32 GetSamplesPerStream() const = 0

Get the number of samples to process in one stream, as set in the loaded engine configuration file.

Return: The number of samples per stream.

GetSoundHandle ¶

[[nodiscard]] virtual SoundHandle GetSoundHandle(const AmString& name) const = 0

Gets a SoundHandle given its name as defined in its asset file (.amsound).

Parameter name: The unique name as defined in the asset file.
Return: The SoundHandle for the given name, or an invalid handle if no sound with that name was found in any loaded sound bank.

[[nodiscard]] virtual SoundHandle GetSoundHandle(AmSoundID id) const = 0

Gets a SoundHandle given its ID as defined in its asset file (.amsound).

Parameter id: The unique ID as defined in the asset file.
Return: The SoundHandle for the given ID, or an invalid handle if no sound with that ID was found in any loaded sound bank.

GetSoundHandleFromFile ¶

[[nodiscard]] virtual SoundHandle GetSoundHandleFromFile(const AmOsString& filename) const = 0

Gets a SoundHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the sounds directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "sounds/env/forest/calm_lake_bg.amsound"
SoundHandle handle = amEngine->GetSoundHandleFromFile("env/forest/calm_lake_bg.amsound");

Return: The SoundHandle for the given asset's filename, or an invalid handle if no sound with that filename was found in any loaded sound bank.

GetSoundObjectHandle ¶

[[nodiscard]] virtual SoundObjectHandle GetSoundObjectHandle(const AmString& name) const = 0

Gets a SoundObjectHandle given its name as defined in its asset file.

Parameter name: The unique name as defined in the asset file.
Return: The SoundObjectHandle for the given name, or an invalid handle if no sound object with that name was found in any loaded sound bank.

Note

The return value can be a SwitchContainerHandle, a CollectionHandle, or a SoundHandle.

[[nodiscard]] virtual SoundObjectHandle GetSoundObjectHandle(AmSoundID id) const = 0

Gets a SoundObjectHandle given its ID as defined in its asset file.

Parameter id: The unique ID as defined in the asset file.
Return: The SoundObjectHandle for the given ID, or an invalid handle if no sound object with that ID was found in any loaded sound bank.

Note

The return value can be a SwitchContainerHandle, a CollectionHandle, or a SoundHandle.

GetSoundObjectHandleFromFile ¶

[[nodiscard]] virtual SoundObjectHandle GetSoundObjectHandleFromFile(const AmOsString& filename) const = 0

Gets a SoundObjectHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the sounds, collections, or switch_containers directories of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "sounds/env/forest/calm_lake_bg.amsound"
// Note that the return value in this case is a indeed a `SoundHandle`
SoundObjectHandle handle = amEngine->GetSoundObjectHandleFromFile("env/forest/calm_lake_bg.amsound");

Return: The SoundObjectHandle for the given asset's filename, or an invalid handle if no sound object with that filename was found in any loaded sound bank.

Note

The return value can be a SwitchContainerHandle, a CollectionHandle, or a SoundHandle.

GetSoundSpeed ¶

[[nodiscard]] virtual AmReal32 GetSoundSpeed() const = 0

Gets the speed of sound, as set in the loaded engine configuration file.

Return: The speed of sound.

GetSwitchContainerHandle ¶

[[nodiscard]] virtual SwitchContainerHandle GetSwitchContainerHandle(const AmString& name) const = 0

Gets a SwitchContainerHandle given its name as defined in its asset file (.amswitchcontainer).

Parameter name: The unique name as defined in the asset file.
Return: The SwitchContainerHandle for the given name, or an invalid handle if no switch container with that name was found in any loaded sound bank.

[[nodiscard]] virtual SwitchContainerHandle GetSwitchContainerHandle(AmSwitchContainerID id) const = 0

Gets a SwitchContainerHandle given its ID as defined in its asset file (.amswitchcontainer).

Parameter id: The unique ID as defined in the asset file.
Return: The SwitchContainerHandle for the given ID, or an invalid handle if no switch container with that ID was found in any loaded sound bank.

GetSwitchContainerHandleFromFile ¶

[[nodiscard]] virtual SwitchContainerHandle GetSwitchContainerHandleFromFile(const AmOsString& filename) const = 0

Gets a SwitchContainerHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the switch_containers directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "switch_containers/footsteps.amswitchcontainer"
SwitchContainerHandle handle = amEngine->GetSwitchContainerHandleFromFile("footsteps.amswitchcontainer");

Return: The SwitchContainerHandle for the given asset's filename, or an invalid handle if no switch container with that filename was found in any loaded sound bank.

GetSwitchHandle ¶

[[nodiscard]] virtual SwitchHandle GetSwitchHandle(const AmString& name) const = 0

Gets a SwitchHandle given its name as defined in its asset file (.amswitch).

Parameter name: The unique name as defined in the asset file.
Return: The SwitchHandle for the given name, or an invalid handle if no switch with that name was found in any loaded sound bank.

[[nodiscard]] virtual SwitchHandle GetSwitchHandle(AmSwitchID id) const = 0

Gets a SwitchHandle given its ID as defined in its asset file (.amswitch).

Parameter id: The unique ID as defined in the asset file.
Return: The SwitchHandle for the given ID, or an invalid handle if no switch with that ID was found in any loaded sound bank.

GetSwitchHandleFromFile ¶

[[nodiscard]] virtual SwitchHandle GetSwitchHandleFromFile(const AmOsString& filename) const = 0

Gets a SwitchHandle given its asset's filename.

Parameter filename: The asset's filename.

Note

The asset's filename should be relative path from the switches directory of your Amplitude project, not an absolute path from the filesystem base path.

Example

// Assuming the asset file is located in "switches/env/surfaces.amswitch"
SwitchHandle handle = amEngine->GetSwitchHandleFromFile("env/surfaces.amswitch");

Return: The SwitchHandle for the given asset's filename, or an invalid handle if no switch with that filename was found in any loaded sound bank.

GetTotalTime ¶

[[nodiscard]] virtual AmTime GetTotalTime() const = 0

Gets the total elapsed time in milliseconds since the start of the engine.

Return: The total elapsed time in milliseconds since the start of the engine.

Initialize ¶

virtual bool Initialize(const AmOsString& configFile) = 0

Initializes the Amplitude engine.

Parameter configFile: The path to the configuration file.
Return: true when the engine has been successfully initialized, false otherwise.

IsGameTrackingEnvironmentAmounts ¶

[[nodiscard]] virtual bool IsGameTrackingEnvironmentAmounts() const = 0

Checks whether the game is tracking environment amounts himself.

Return: Whether the game is tracking environment amounts.

IsInitialized ¶

[[nodiscard]] virtual bool IsInitialized() const = 0

Checks if the Amplitude engine has been successfully initialized.

Return: true if the engine has been successfully initialized, false otherwise.

IsMuted ¶

[[nodiscard]] virtual bool IsMuted() const = 0

Checks whether the engine is currently muted.

Return: true if the engine is muted, false otherwise.

IsPaused ¶

[[nodiscard]] virtual bool IsPaused() const = 0

Checks whether the engine is currently paused.

Return: true if the engine is currently paused, false otherwise.

LoadPlugin ¶

static AmVoidPtr LoadPlugin(const AmOsString& pluginLibraryName)

Loads a plugin library from the given path.

Parameter pluginLibraryName: The name of the plugin library to load.
Return: A handle to the loaded plugin library.

LoadSoundBank ¶

virtual bool LoadSoundBank(const AmOsString& filename) = 0

Loads a sound bank from a binary asset file (.ambank).

This method queues the sound files in that sound bank for loading. Call StartLoadSoundFiles() to trigger the loading of sound files on a separate thread.

Parameter filename: The path to the sound bank asset file.
Return: true when the sound bank is successfully loaded, false otherwise.

virtual bool LoadSoundBank(const AmOsString& filename, AmBankID& outID) = 0

Loads a sound bank from a binary asset file (.ambank).

This method queues the sound files in that sound bank for loading. Call StartLoadSoundFiles() to trigger the loading of sound files on a separate thread.

Parameter filename: The path to the sound bank asset file.
Parameter outID: The ID of the loaded sound bank.
Return: true when the sound bank is successfully loaded, false otherwise.

LoadSoundBankFromMemory ¶

virtual bool LoadSoundBankFromMemory(const char* fileData) = 0

Loads a sound bank from memory.

This method queues the sound files in that sound bank for loading. Call StartLoadSoundFiles() to trigger the loading of sound files on a separate thread.

Parameter fileData: The sound bank data to be loaded.

Note

The fileData pointer should be null terminated.

Warning

The fileData pointer should remain valid until the sound bank is unloaded.

Return: true when the sound bank is successfully loaded, false otherwise.

virtual bool LoadSoundBankFromMemory(const char* fileData, AmBankID& outID) = 0

Loads a sound bank from memory.

This method queues the sound files in that sound bank for loading. Call StartLoadSoundFiles() to trigger the loading of sound files on a separate thread.

Parameter fileData: The sound bank data to be loaded.
Parameter outID: The ID of the loaded sound bank.

Note

The fileData pointer should be null terminated.

Warning

The fileData pointer should remain valid until the sound bank is unloaded.

Return: true when the sound bank is successfully loaded, false otherwise.

LoadSoundBankFromMemoryView ¶

virtual bool LoadSoundBankFromMemoryView(AmVoidPtr ptr, AmSize size) = 0

Loads a sound bank from memory.

This method queues the sound files in that sound bank for loading. Call StartLoadSoundFiles() to trigger the loading of sound files on a separate thread.

Parameter ptr: The pointer to the sound bank data to be loaded.
Parameter size: The size of the memory to read.

Note

The fileData pointer should be null terminated.

Warning

The fileData pointer should remain valid until the sound bank is unloaded.

Return: true when the sound bank is successfully loaded, false otherwise.

virtual bool LoadSoundBankFromMemoryView(AmVoidPtr ptr, AmSize size, AmBankID& outID) = 0

Loads a sound bank from memory.

This method queues the sound files in that sound bank for loading. Call StartLoadSoundFiles() to trigger the loading of sound files on a separate thread.

Parameter ptr: The pointer to the sound bank data to be loaded.
Parameter size: The size of the memory to read.
Parameter outID: The ID of the loaded sound bank.

Note

The ptr pointer should be null terminated.

Warning

The ptr pointer should remain valid until the sound bank is unloaded.

Return: true when the sound bank is successfully loaded, false otherwise.

OnNextFrame ¶

virtual void OnNextFrame(std::function<void(AmTime delta)> callback) const = 0

Executes the given callback on the next frame.

Note

The given callback will be executed at the beginning of the next frame, before doing the actual frame update.

Parameter callback: The callback to be called when the next frame is ready.

Pause ¶

virtual void Pause(bool pause) const = 0

Pauses or resumes all playing sounds and streams.

Parameter pause: Whether to pause or resume the engine.

Play ¶

[[nodiscard]] virtual Channel Play(SwitchContainerHandle handle) const = 0

Plays a switch container associated with the given handle in the World scope.

This method is recommended for switch containers with spatialization disabled, since no positional information need to be provided.

Parameter handle: A handle to the switch container to play.
Return: The channel the switch container is being played on. If the switch container could not be played, or the given handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const AmVec3& location) const = 0

Plays a switch container associated with the given handle in the World scope.

Parameter handle: A handle to the switch container to play.
Parameter location: The location at which switch container should be played.
Return: The channel the switch container is being played on. If the switch container could not be played, or the given handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const AmVec3& location, AmReal32 userGain) const = 0

Plays a switch container associated with the given handle in the World scope.

Parameter handle: A handle to the switch container to play.
Parameter location: The location at which the switch container should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the switch container is being played on. If the switch container could not be played, or the given handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const Entity& entity) const = 0

Plays a switch container associated with the given handle in an Entity scope.

Note

Switch containers played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter handle: A handle to the switch container to play.
Parameter entity: The entity on which the switch container should be played.
Return: The channel the switch container is being played on. If the switch container could not be played, the given handle is invalid, or the given entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const Entity& entity, AmReal32 userGain) const = 0

Plays a switch container associated with the given handle in an Entity scope.

Note

Switch containers played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter handle: A handle to the switch container to play.
Parameter entity: The entity on which the switch container should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the switch container is being played on. If the switch container could not be played, the given handle is invalid, or the given entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(CollectionHandle handle) const = 0

Plays a collection associated with the given handle in the World scope.

Parameter handle: A handle to the collection to play.
Return: The channel the collection is being played on. If the collection could not be played, or the handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(CollectionHandle handle, const AmVec3& location) const = 0

Plays a collection associated with the given handle in the World scope.

Parameter handle: A handle to the collection to play.
Parameter location: The location at which the collection should be played.
Return: The channel the collection is being played on. If the collection could not be played, or the handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(CollectionHandle handle, const AmVec3& location, AmReal32 userGain) const = 0

Plays a collection associated with the given handle in the World scope.

Parameter handle: A handle to the collection to play.
Parameter location: The location at which the collection should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the collection is being played on. If the collection could not be played, or the handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(CollectionHandle handle, const Entity& entity) const = 0

Plays a collection associated with the given handle in the Entity scope.

Note

Collections played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter handle: A handle to the collection to play.
Parameter entity: The entity on which the collection should be played.
Return: The channel the collection is being played on. If the collection could not be played, the given handle is invalid, or the given entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(CollectionHandle handle, const Entity& entity, AmReal32 userGain) const = 0

Plays a collection associated with the given handle in an Entity scope.

Note

Collections played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter handle: A handle to the collection to play.
Parameter entity: The entity on which the collection should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the collection is being played on. If the collection could not be played, the given handle is invalid, or the given entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SoundHandle handle) const = 0

Plays a sound associated with the given handle in the World scope.

Parameter handle: A handle to the sound to play.
Return: The channel the sound is being played on. If the sound could not be played, the given handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SoundHandle handle, const AmVec3& location) const = 0

Plays a sound associated with the given handle in the World scope.

Parameter handle: A handle to the sound to play.
Parameter location: The location at which the sound should be played.
Return: The channel the sound is being played on. If the sound could not be played, the given handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SoundHandle handle, const AmVec3& location, AmReal32 userGain) const = 0

Plays a sound associated with the given handle in the World scope.

Parameter handle: A handle to the sound to play.
Parameter location: The location at which the sound should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the sound is being played on. If the sound could not be played, the given handle is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SoundHandle handle, const Entity& entity) const = 0

Plays a sound associated with the given sound handle in an Entity scope.

Note

Sounds played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter handle: A handle to the sound to play.
Parameter entity: The entity on which the sound should be played.
Return: The channel the sound is being played on. If the sound could not be played, the given handle is invalid, or the given entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(SoundHandle handle, const Entity& entity, AmReal32 userGain) const = 0

Plays a sound associated with the given sound handle in an Entity.

Note

Sounds played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter handle: A handle to the sound to play.
Parameter entity: The entity on which the sound should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the sound is being played on. If the sound could not be played, the given handle is invalid, or the given entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(const AmString& name) const = 0

Plays a sound object associated with the given name in the World scope.

Tip

Playing a sound object with its handle is faster than using the name as using the name requires an internal lookup.

Parameter name: The name of the sound object to play.
Return: The channel the sound object is being played on. If the object could not be played, or an object with the given name was not found, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(const AmString& name, const AmVec3& location) const = 0

Plays a sound object associated with the given name in the World scope.

Tip

Playing a sound object with its handle is faster than using the name as using the name requires an internal lookup.

Parameter name: The name of the sound object to play.
Parameter location: The location at which the sound should be played.
Return: The channel the sound object is being played on. If the object could not be played, or an object with the given name was not found, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(const AmString& name, const AmVec3& location, AmReal32 userGain) const = 0

Plays a sound object associated with the given name in the World scope.

Tip

Playing a sound object with its handle is faster than using the name as using the name requires an internal lookup.

Parameter name: The name of the sound object to play.
Parameter location: The location at which the sound should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the sound object is being played on. If the object could not be played, or an object with the given name was not found, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(const AmString& name, const Entity& entity) const = 0

Plays a sound object associated with the given name in an Entity scope.

Tip

Playing a sound object with its handle is faster than using the name as using the name requires an internal lookup.

Note

Sound objects played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter name: The name of the sound object to play.
Parameter entity: The entity on which the sound object should be played.
Return: The channel the sound object is being played on. If the object could not be played, an object with the given name was not found, or the entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(const AmString& name, const Entity& entity, AmReal32 userGain) const = 0

Plays a sound object associated with the given name in an Entity scope.

Tip

Playing a sound object with its handle is faster than using the name as using the name requires an internal lookup.

Note

Sound objects played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter name: The name of the sound object to play.
Parameter entity: The entity on which the sound object should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the sound object is being played on. If the object could not be played, an object with the given name was not found, or the entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(AmObjectID id) const = 0

Plays a sound object associated with the given ID in the World scope.

Tip

Playing a sound object with its handle is faster than using the ID as using the ID requires an internal lookup.

Parameter id: The ID of the sound object to play.
Return: The channel the sound object is being played on. If the object could not be played, or an object with the given ID was not found, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(AmObjectID id, const AmVec3& location) const = 0

Plays a sound object associated with the given ID in the World scope.

Tip

Playing a sound object with its handle is faster than using the ID as using the ID requires an internal lookup.

Parameter id: The ID of the sound object to play.
Parameter location: The location at which the sound object should be played.
Return: The channel the sound object is being played on. If the object could not be played, or an object with the given ID was not found, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(AmObjectID id, const AmVec3& location, AmReal32 userGain) const = 0

Plays a sound object associated with the given ID in the World scope.

Tip

Playing a sound object with its handle is faster than using the ID as using the ID requires an internal lookup.

Parameter id: The ID of the sound object to play.
Parameter location: The location at which the sound object should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the sound object is being played on. If the object could not be played, or an object with the given ID was not found, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(AmObjectID id, const Entity& entity) const = 0

Plays a sound object associated with the given ID in an Entity scope.

Tip

Playing a sound object with its handle is faster than using the ID as using the ID requires an internal lookup.

Note

Sound objects played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter id: The ID of the sound object to play.
Parameter entity: The entity on which the sound object should be played.
Return: The channel the sound object is being played on. If the object could not be played, an object with the given ID was not found, or the entity is invalid, an invalid Channel is returned.

[[nodiscard]] virtual Channel Play(AmObjectID id, const Entity& entity, AmReal32 userGain) const = 0

Plays a sound object associated with the given ID in an Entity scope.

Tip

Playing a sound object with its handle is faster than using the ID as using the ID requires an internal lookup.

Note

Sound objects played using this method should have been set in the Entity scope from their asset file. See more here.

Parameter id: The ID of the sound object to play.
Parameter entity: The entity on which the sound object should be played.
Parameter userGain: The gain of the sound. Must be in the range [0, 1].

Note

The userGain parameter will not be used directly, but instead, it will be used in the final gain computation, which may include other factors like the attenuation and the master gain.

Return: The channel the sound object is being played on. If the object could not be played, an object with the given ID was not found, or the entity is invalid, an invalid Channel is returned.

RegisterDefaultPlugins ¶

static bool RegisterDefaultPlugins()

Register all default plugins.

RemoveEntity ¶

virtual void RemoveEntity(const Entity* entity) const = 0

Removes an Entity.

Parameter entity: The game entity to be removed.

virtual void RemoveEntity(AmEntityID id) const = 0

Removes an Entity given its ID.

Parameter id: The ID of the game entity to be removed.

RemoveEnvironment ¶

virtual void RemoveEnvironment(const Environment* environment) const = 0

Removes an Environment.

Parameter environment: The game environment to be removed.

virtual void RemoveEnvironment(AmEnvironmentID id) const = 0

Removes an Environment given its ID.

Parameter id: The ID of the game environment to be removed.

RemoveListener ¶

virtual void RemoveListener(AmListenerID id) const = 0

Removes a Listener given its ID.

Parameter id: The ID of the Listener to be removed.

virtual void RemoveListener(const Listener* listener) const = 0

Removes a Listener given its handle.

Parameter listener: The Listener to be removed.

RemovePluginSearchPath ¶

static void RemovePluginSearchPath(const AmOsString& path)

Removes a path from the plugins search paths list.

Parameter path: The path to remove from the plugins search path list.

RemoveRoom ¶

virtual void RemoveRoom(const Room* room) const = 0

Removes a Room.

Parameter room: The room to be removed.

virtual void RemoveRoom(AmRoomID id) const = 0

Removes a Room given its ID.

Parameter id: The ID of the room to be removed.

SetDefaultListener ¶

virtual void SetDefaultListener(const Listener* listener) = 0

Sets the default sound listener.

This method will set the default listener that will render every played sound sources.

Note

This method takes effect only if the listener_fetch_mode engine setting is set to Default.

Parameter listener: A valid and initialized Listener instance.

virtual void SetDefaultListener(AmListenerID id) = 0

Sets the default sound listener.

This method will set the default listener that will render every played sound sources.

Note

This method takes effect only if the listener_fetch_mode engine setting is set to Default.

Parameter id: The ID of a valid and registered Listener.

SetFileSystem ¶

virtual void SetFileSystem(FileSystem* fs) = 0

Sets a file system implementation to be used by the engine.

Parameter fs: The file system implementation.

SetMasterGain ¶

virtual void SetMasterGain(AmReal32 gain) const = 0

Adjusts the master gain of the mixer.

Parameter gain: The master gain.

SetMute ¶

virtual void SetMute(bool mute) const = 0

Mutes the engine, but keep processing audio.

Parameter mute: Whether to mute or unmute the engine.

SetRtpcValue ¶

virtual void SetRtpcValue(RtpcHandle handle, double value) const = 0

Sets the value of a RTPC.

Parameter handle: The handle of the RTPC to update.
Parameter value: The value to set to the RTPC.

virtual void SetRtpcValue(AmRtpcID id, double value) const = 0

Sets the value of a RTPC.

Parameter id: The ID of the RTPC to update.
Parameter value: The value to set to the RTPC.

virtual void SetRtpcValue(const AmString& name, double value) const = 0

Sets the value of a RTPC.

Parameter name: THe name of the RTPC to update.
Parameter value: The value to set to the RTPC.

SetSwitchState ¶

virtual void SetSwitchState(SwitchHandle handle, AmObjectID stateId) const = 0

Sets the active state of the defined Switch.

Parameter handle: The handle of the Switch.
Parameter stateId: The ID of the active state to set.

virtual void SetSwitchState(SwitchHandle handle, const AmString& stateName) const = 0

Sets the active state of the defined Switch.

Parameter handle: The handle of the Switch.
Parameter stateName: The name of the active state to set.

virtual void SetSwitchState(SwitchHandle handle, const SwitchState& state) const = 0

Sets the active state of the defined Switch.

Parameter handle: The handle of the Switch.
Parameter state: The active state to set.

virtual void SetSwitchState(AmSwitchID id, AmObjectID stateId) const = 0

Sets the active state of the defined Switch.

Parameter id: The ID of the Switch to update.
Parameter stateId: The ID of the active state to set.

virtual void SetSwitchState(AmSwitchID id, const AmString& stateName) const = 0

Sets the active state of the defined Switch.

Parameter id: The ID of the Switch to update.
Parameter stateName: The name of the active state to set.

virtual void SetSwitchState(AmSwitchID id, const SwitchState& state) const = 0

Sets the active state of the defined Switch.

Parameter id: The ID of the Switch to update.
Parameter state: The active state to set.

virtual void SetSwitchState(const AmString& name, AmObjectID stateId) const = 0

Sets the active state of the defined Switch.

Parameter name: The name of the Switch to update.
Parameter stateId: The ID of the active state to set.

virtual void SetSwitchState(const AmString& name, const AmString& stateName) const = 0

Sets the active state of the defined Switch.

Parameter name: The name of the Switch to update.
Parameter stateName: The name of the active state to set.

virtual void SetSwitchState(const AmString& name, const SwitchState& state) const = 0

Sets the active state of the defined Switch.

Parameter name: The name of the Switch to update.
Parameter state: The active state to set.

StartCloseFileSystem ¶

virtual void StartCloseFileSystem() = 0

Closes the file system, usually in a separate thread.

StartLoadSoundFiles ¶

virtual void StartLoadSoundFiles() = 0

Starts the loading of sound files referenced in loaded sound banks.

This process will run in another thread. You must call TryFinalizeLoadSoundFiles() to know when the loading has completed, and to automaticaly release used resources.

StartOpenFileSystem ¶

virtual void StartOpenFileSystem() = 0

Opens the file system, usually in a separate thread.

StopAll ¶

virtual void StopAll() const = 0

Stops all playing sound objects.

This is the equivalent of calling Stop() on all generated channels.

Trigger ¶

[[nodiscard]] virtual EventCanceler Trigger(EventHandle handle, const Entity& entity) const = 0

Triggers the event associated to the given handle.

Parameter handle: The handle of the event to trigger.
Parameter entity: The entity on which trigger the event.
Return: An EventCanceler object which may be used to cancel the execution of the event.

[[nodiscard]] virtual EventCanceler Trigger(const AmString& name, const Entity& entity) const = 0

Triggers the event associated to the given handle.

Tip

Triggering an event with its EventHandle is faster than using the event name as using the name requires an internal lookup.

Parameter name: The name of event to trigger.
Parameter entity: The entity on which trigger the event.
Return: An EventCanceler object which may be used to cancel the execution of the event.

TryFinalizeCloseFileSystem ¶

virtual bool TryFinalizeCloseFileSystem() = 0

Checks if the file system has been fully closed.

This method is helpful when the file system implementation is closed asynchronously. You can use this method to wait until the file system is fully closed.

Example

// Close the file system
amEngine->StartCloseFileSystem();
while (!amEngine->TryFinalizeCloseFileSystem()) {
    // Wait until the file system is fully closed
    Thread::Sleep(100);
}
// The file system is now closed
//...

Return: true if the file system has been fully closed, false otherwise.

TryFinalizeLoadSoundFiles ¶

virtual bool TryFinalizeLoadSoundFiles() = 0

Checks if the loading of sound files has been completed, and releases used resources.

Note

This method should be called after calling StartLoadSoundFiles().

Example

// Start loading sound files
amEngine->StartLoadSoundFiles();
while (!amEngine->TryFinalizeLoadSoundFiles()) {
    // Wait for loading to complete
    Thread::Sleep(100);
}
// Sound files have been loaded, and used resources has been released

Return: true when the sound files have been successfully loaded, false otherwise.

TryFinalizeOpenFileSystem ¶

virtual bool TryFinalizeOpenFileSystem() = 0

Checks if the file system has been fully loaded.

This method is helpful when the file system implementation is loaded asynchronously. You can use this method to wait until the file system is fully loaded before using it.

Example

// Open the file system
amEngine->StartOpenFileSystem();
while (!amEngine->TryFinalizeOpenFileSystem()) {
    // Wait until the file system is fully loaded
    Thread::Sleep(100);
}
// Use the file system now
//...

Return: true if the file system has been fully loaded, false otherwise.

UnloadSoundBank ¶

virtual void UnloadSoundBank(const AmOsString& filename) = 0

Unloads a sound bank given its filename.

Parameter filename: The file to unload.

virtual void UnloadSoundBank(AmBankID id) = 0

Unloads a sound bank given its ID.

Parameter id: The sound bank id to unload.

UnloadSoundBanks ¶

virtual void UnloadSoundBanks() = 0

Unloads all the loaded sound banks.

UnregisterDefaultPlugins ¶

static bool UnregisterDefaultPlugins()

Unregister all default plugins.

Version ¶

* Version() const

Gets the version structure.

Return: The version string structure

WaitUntilFrames ¶

virtual void WaitUntilFrames(AmUInt64 frameCount) const = 0

Waits until the specified number of frames are ready.

This method blocks the current thread until the specified number of frames are ready.

Parameter frameCount: The number of frames to wait until.

WaitUntilNextFrame ¶

virtual void WaitUntilNextFrame() const = 0

Waits until the next frame is ready.

This method blocks the current thread until the next frame is ready.

Engine¶

Functions¶

Function Details¶

AddEntity¶

AddEnvironment¶

AddListener¶

AddPluginSearchPath¶

AddRoom¶

AdvanceFrame¶

Deinitialize¶

DestroyInstance¶

FindBus¶

GetAttenuationHandle¶

GetAttenuationHandleFromFile¶

GetCollectionHandle¶

GetCollectionHandleFromFile¶

GetDefaultListener¶

GetDopplerFactor¶

GetDriver¶

GetEffectHandle¶

GetEffectHandleFromFile¶

GetEntity¶

GetEnvironment¶

GetEventHandle¶

GetEventHandleFromFile¶

GetFileSystem¶

GetHRIRSphere¶

GetHRIRSphereSamplingMode¶

GetInstance¶

GetListener¶

GetMasterGain¶

GetMaxEntitiesCount¶

GetMaxListenersCount¶

GetMixer¶

GetObstructionCoefficientCurve¶

GetObstructionGainCurve¶

GetOcclusionCoefficientCurve¶

GetOcclusionGainCurve¶

GetPanningMode¶

GetPipelineHandle¶

GetRoom¶

GetRtpcHandle¶

GetRtpcHandleFromFile¶

GetSamplesPerStream¶

GetSoundHandle¶

GetSoundHandleFromFile¶

GetSoundObjectHandle¶

GetSoundObjectHandleFromFile¶

GetSoundSpeed¶

GetSwitchContainerHandle¶

GetSwitchContainerHandleFromFile¶

GetSwitchHandle¶

GetSwitchHandleFromFile¶

GetTotalTime¶

Initialize¶

IsGameTrackingEnvironmentAmounts¶

IsInitialized¶

IsMuted¶

IsPaused¶

LoadPlugin¶

LoadSoundBank¶

LoadSoundBankFromMemory¶

LoadSoundBankFromMemoryView¶

OnNextFrame¶

Pause¶

Play¶

RegisterDefaultPlugins¶

RemoveEntity¶

RemoveEnvironment¶

RemoveListener¶

RemovePluginSearchPath¶

RemoveRoom¶

SetDefaultListener¶

SetFileSystem¶

SetMasterGain¶

SetMute¶

SetRtpcValue¶

SetSwitchState¶

StartCloseFileSystem¶

StartLoadSoundFiles¶

AddEntity ¶

AddEnvironment ¶

AddListener ¶

AddPluginSearchPath ¶

AddRoom ¶

AdvanceFrame ¶

Deinitialize ¶

DestroyInstance ¶

FindBus ¶

GetAttenuationHandle ¶

GetAttenuationHandleFromFile ¶

GetCollectionHandle ¶

GetCollectionHandleFromFile ¶

GetDefaultListener ¶

GetDopplerFactor ¶

GetDriver ¶

GetEffectHandle ¶

GetEffectHandleFromFile ¶

GetEntity ¶

GetEnvironment ¶

GetEventHandle ¶

GetEventHandleFromFile ¶

GetFileSystem ¶

GetHRIRSphere ¶

GetHRIRSphereSamplingMode ¶

GetInstance ¶

GetListener ¶

GetMasterGain ¶

GetMaxEntitiesCount ¶

GetMaxListenersCount ¶

GetMixer ¶

GetObstructionCoefficientCurve ¶

GetObstructionGainCurve ¶

GetOcclusionCoefficientCurve ¶

GetOcclusionGainCurve ¶

GetPanningMode ¶

GetPipelineHandle ¶

GetRoom ¶

GetRtpcHandle ¶

GetRtpcHandleFromFile ¶

GetSamplesPerStream ¶

GetSoundHandle ¶

GetSoundHandleFromFile ¶

GetSoundObjectHandle ¶

GetSoundObjectHandleFromFile ¶

GetSoundSpeed ¶

GetSwitchContainerHandle ¶

GetSwitchContainerHandleFromFile ¶

GetSwitchHandle ¶

GetSwitchHandleFromFile ¶

GetTotalTime ¶

Initialize ¶

IsGameTrackingEnvironmentAmounts ¶

IsInitialized ¶

IsMuted ¶

IsPaused ¶

LoadPlugin ¶

LoadSoundBank ¶

LoadSoundBankFromMemory ¶

LoadSoundBankFromMemoryView ¶

OnNextFrame ¶

Pause ¶

Play ¶

RegisterDefaultPlugins ¶

RemoveEntity ¶

RemoveEnvironment ¶

RemoveListener ¶

RemovePluginSearchPath ¶

RemoveRoom ¶

SetDefaultListener ¶

SetFileSystem ¶

SetMasterGain ¶

SetMute ¶

SetRtpcValue ¶

SetSwitchState ¶

StartCloseFileSystem ¶

StartLoadSoundFiles ¶

StartOpenFileSystem ¶

StopAll ¶

Trigger ¶