Engine¶

Initializes and returns a new Entity .

virtual Entity Amplitude::Engine::AddEntity (
    AmEntityID id
) const = 0

Parameters:

• id The game entity ID.

Returns:

An initialized Entity.

See also: Entity

Initializes and return a new Environment .

virtual Environment Amplitude::Engine::AddEnvironment (
    AmEnvironmentID id
) const = 0

Parameters:

• id The game environment ID.

Returns:

An initialized Environment.

See also: Environment

Initializes and returns a new Listener .

virtual Listener Amplitude::Engine::AddListener (
    AmListenerID id
) const = 0

Parameters:

• id The new listener ID.

Returns:

An initialized Listener.

See also: Listener

Initializes and return a new Room .

virtual Room Amplitude::Engine::AddRoom (
    AmRoomID id
) const = 0

Parameters:

• id The room ID.

Returns:

An initialized Room.

See also: Room

Updates the engine state for the given number of milliseconds.

virtual void Amplitude::Engine::AdvanceFrame (
    AmTime delta
) const = 0

Parameters:

• delta The number of milliseconds since the last frame.

Cancels all events currently being processed.

virtual void Amplitude::Engine::CancelAllEvents () const = 0

Note:

This method cancels all events currently being processed by the engine. It does not cancel events that are queued for processing.

Cancels events triggered by the given entity.

virtual void Amplitude::Engine::CancelEvents (
    const Entity & entity
) const = 0

Parameters:

• entity The entity for which cancel triggered events.

Deinitializes the Amplitude engine.

virtual bool Amplitude::Engine::Deinitialize () = 0

Returns:

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

Make sure a sound bank is loaded in the engine.

virtual void Amplitude::Engine::EnsureSoundBankLoaded (
    const AmOsString & filename
) = 0

If the sound bank referenced by the iven file path is already loaded, the method will do nothing, and the sound bank reference count will be kept unchanged.

Parameters:

• filename The path to the sound bank asset file to load.

Returns the Bus with the specified name.

virtual Bus Amplitude::Engine::FindBus (
    const AmString & name
) const = 0

Parameters:

• name The name of the bus.

Note:

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

Returns:

A valid Bus if found, otherwise an invalid Bus.

See also: Bus

Returns the Bus with the given ID.

virtual Bus Amplitude::Engine::FindBus (
    AmBusID id
) const = 0

Parameters:

• id The ID of the bus.

Note:

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

Returns:

A valid Bus if found, otherwise an invalid Bus.

See also: Bus

Get the number of active entities in the engine.

virtual AmUInt32 Amplitude::Engine::GetActiveEntitiesCount () const = 0

Returns:

The number of active entities.

Get the number of active environments in the engine.

virtual AmUInt32 Amplitude::Engine::GetActiveEnvironmentsCount () const = 0

Returns:

The number of active environments.

Get the number of active listeners in the engine.

virtual AmUInt32 Amplitude::Engine::GetActiveListenersCount () const = 0

Returns:

The number of active listeners.

Get the number of active rooms in the engine.

virtual AmUInt32 Amplitude::Engine::GetActiveRoomsCount () const = 0

Returns:

The number of active rooms.

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

virtual AttenuationHandle Amplitude::Engine::GetAttenuationHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The AttenuationHandle for the given name, or an invalid handle if no attenuation with that name was found in any loaded sound bank.

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

virtual AttenuationHandle Amplitude::Engine::GetAttenuationHandle (
    AmAttenuationID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The AttenuationHandle for the given ID, or an invalid handle if no attenuation with that ID was found in any loaded sound bank.

Gets an AttenuationHandle given its asset's filename.

virtual AttenuationHandle Amplitude::Engine::GetAttenuationHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

Gets the channel with the given ID.

virtual Channel Amplitude::Engine::GetChannel (
    AmChannelID channelID
) const = 0

Parameters:

• channelID The ID of the channel to get.

Returns:

The channel.

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

virtual CollectionHandle Amplitude::Engine::GetCollectionHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The CollectionHandle for the given name, or an invalid handle if no collection with that name was found in any loaded sound bank.

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

virtual CollectionHandle Amplitude::Engine::GetCollectionHandle (
    AmCollectionID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The CollectionHandle for the given ID, or an invalid handle if no collection with that ID was found in any loaded sound bank.

Gets a CollectionHandle given its asset's filename.

virtual CollectionHandle Amplitude::Engine::GetCollectionHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

Gets the path to the loaded engine configuration file.

virtual const AmOsString & Amplitude::Engine::GetConfigurationPath () const = 0

Returns:

The path to the engine configuration file.

Gets the default audio Listener .

virtual Listener Amplitude::Engine::GetDefaultListener () const = 0

Returns:

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

See also: Listener

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

virtual AmReal32 Amplitude::Engine::GetDopplerFactor () const = 0

Returns:

The Doppler factor.

Gets the audio driver used by the Engine .

virtual std::shared_ptr< Driver > Amplitude::Engine::GetDriver () const = 0

Returns:

The audio driver.

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

virtual EffectHandle Amplitude::Engine::GetEffectHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The EffectHandle for the given name, or an invalid handle if no effect with that name was found in any loaded sound bank.

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

virtual EffectHandle Amplitude::Engine::GetEffectHandle (
    AmEffectID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The EffectHandle for the given ID, or an invalid handle if no effect with that ID was found in any loaded sound bank.

Gets an EffectHandle given its asset's filename.

virtual EffectHandle Amplitude::Engine::GetEffectHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

Returns the Entity with the given ID.

virtual Entity Amplitude::Engine::GetEntity (
    AmEntityID id
) const = 0

Parameters:

• id The game entity ID.

Returns:

An initialized Entity if that one has been registered before, otherwise an uninitialized Entity.

See also: Entity

Returns the Environment with the given ID.

virtual Environment Amplitude::Engine::GetEnvironment (
    AmEnvironmentID id
) const = 0

Parameters:

• id The game environment ID.

Returns:

An initialized Environment if that one has been registered before, otherwise an uninitialized Environment.

See also: Environment

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

virtual EventHandle Amplitude::Engine::GetEventHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The EventHandle for the given name, or an invalid handle if no event with that name was found in any loaded sound bank.

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

virtual EventHandle Amplitude::Engine::GetEventHandle (
    AmEventID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The EventHandle for the given ID, or an invalid handle if no event with that ID was found in any loaded sound bank.

Gets an EventHandle given its asset's filename.

virtual EventHandle Amplitude::Engine::GetEventHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

Gets the file system implementation used by the engine.

virtual std::shared_ptr< const FileSystem > Amplitude::Engine::GetFileSystem () const = 0

Returns:

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

Gets the HRIR sphere defined in the loaded engine configuration.

virtual std::shared_ptr< const HRIRSphere > Amplitude::Engine::GetHRIRSphere () const = 0

Returns:

The HRIR sphere. If no HRIR sphere is defined, it 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 also: HRIRSphere

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

virtual eHRIRSphereSamplingMode Amplitude::Engine::GetHRIRSphereSamplingMode () const = 0

Returns:

The HRIR sphere sampling mode.

Returns the Listener with the given ID.

virtual Listener Amplitude::Engine::GetListener (
    AmListenerID id
) const = 0

Parameters:

• id The listener ID.

Returns:

An initialized Listener if a one with the given ID has been registered before, otherwise an uninitialized Listener.

See also: Listener

Gets the mixer "master" gain.

virtual AmReal32 Amplitude::Engine::GetMasterGain () const = 0

Returns:

The mixer "master" gain.

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

virtual AmUInt32 Amplitude::Engine::GetMaxEntitiesCount () const = 0

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

Returns:

The maximum number of game entities.

Gets the maximum number of environments handled by the engine.

virtual AmUInt32 Amplitude::Engine::GetMaxEnvironmentsCount () const = 0

Returns:

The maximum number of environments.

Gets the maximum number of listeners handled by the engine.

virtual AmUInt32 Amplitude::Engine::GetMaxListenersCount () const = 0

Returns:

The maximum number of listeners.

Gets the maximum number of rooms handled by the engine.

virtual AmUInt32 Amplitude::Engine::GetMaxRoomsCount () const = 0

Returns:

The maximum number of rooms.

Gets the mixer instance.

virtual Amplimix * Amplitude::Engine::GetMixer () const = 0

Returns:

The Amplimix mixer instance.

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

virtual const Curve & Amplitude::Engine::GetObstructionCoefficientCurve () const = 0

Returns:

The obstruction coefficient curve.

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

virtual const Curve & Amplitude::Engine::GetObstructionGainCurve () const = 0

Returns:

The obstruction gain curve.

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

virtual const Curve & Amplitude::Engine::GetOcclusionCoefficientCurve () const = 0

Returns:

The occlusion coefficient curve.

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

virtual const Curve & Amplitude::Engine::GetOcclusionGainCurve () const = 0

Returns:

The occlusion gain curve.

Gets the panning mode defined in the loaded engine configuration.

virtual ePanningMode Amplitude::Engine::GetPanningMode () const = 0

Returns:

The panning mode.

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

virtual PipelineHandle Amplitude::Engine::GetPipelineHandle () const = 0

Note:

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

Returns:

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

Returns the Room with the given ID.

virtual Room Amplitude::Engine::GetRoom (
    AmRoomID id
) const = 0

Parameters:

• id The room ID.

Returns:

An initialized Room if that one has been registered before, otherwise an uninitialized Room.

See also: Room

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

virtual RtpcHandle Amplitude::Engine::GetRtpcHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The RtpcHandle for the given name, or an invalid handle if no RTPC with that name was found in any loaded sound bank.

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

virtual RtpcHandle Amplitude::Engine::GetRtpcHandle (
    AmRtpcID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The RtpcHandle for the given ID, or an invalid handle if no RTPC with that ID was found in any loaded sound bank.

Gets an RtpcHandle given its asset's filename.

virtual RtpcHandle Amplitude::Engine::GetRtpcHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

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

virtual AmUInt32 Amplitude::Engine::GetSamplesPerStream () const = 0

Returns:

The number of samples per stream.

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

virtual SoundHandle Amplitude::Engine::GetSoundHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The SoundHandle for the given name, or an invalid handle if no sound with that name was found in any loaded sound bank.

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

virtual SoundHandle Amplitude::Engine::GetSoundHandle (
    AmSoundID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The SoundHandle for the given ID, or an invalid handle if no sound with that ID was found in any loaded sound bank.

Gets a SoundHandle given its asset's filename.

virtual SoundHandle Amplitude::Engine::GetSoundHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

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

virtual SoundObjectHandle Amplitude::Engine::GetSoundObjectHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

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.

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

virtual SoundObjectHandle Amplitude::Engine::GetSoundObjectHandle (
    AmSoundID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

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.

Gets a SoundObjectHandle given its asset's filename.

virtual SoundObjectHandle Amplitude::Engine::GetSoundObjectHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

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

virtual AmReal32 Amplitude::Engine::GetSoundSpeed () const = 0

Returns:

The speed of sound.

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

virtual SwitchContainerHandle Amplitude::Engine::GetSwitchContainerHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The SwitchContainerHandle for the given name, or an invalid handle if no switch container with that name was found in any loaded sound bank.

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

virtual SwitchContainerHandle Amplitude::Engine::GetSwitchContainerHandle (
    AmSwitchContainerID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The SwitchContainerHandle for the given ID, or an invalid handle if no switch container with that ID was found in any loaded sound bank.

Gets a SwitchContainerHandle given its asset's filename.

virtual SwitchContainerHandle Amplitude::Engine::GetSwitchContainerHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

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

virtual SwitchHandle Amplitude::Engine::GetSwitchHandle (
    const AmString & name
) const = 0

Parameters:

• name The unique name as defined in the asset file.

Returns:

The SwitchHandle for the given name, or an invalid handle if no switch with that name was found in any loaded sound bank.

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

virtual SwitchHandle Amplitude::Engine::GetSwitchHandle (
    AmSwitchID id
) const = 0

Parameters:

• id The unique ID as defined in the asset file.

Returns:

The SwitchHandle for the given ID, or an invalid handle if no switch with that ID was found in any loaded sound bank.

Gets a SwitchHandle given its asset's filename.

virtual SwitchHandle Amplitude::Engine::GetSwitchHandleFromFile (
    const AmOsString & filename
) const = 0

Parameters:

• filename The asset's filename.

Note:

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

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

Returns:

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.

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

virtual AmTime Amplitude::Engine::GetTotalTime () const = 0

Returns:

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

Checks if a sound bank with the given filename has been loaded.

virtual bool Amplitude::Engine::HasLoadedSoundBank (
    const AmOsString & filename
) const = 0

Parameters:

• filename The file to check.

Returns:

true if the sound bank has been loaded, false otherwise.

Checks if a sound bank with the given ID has been loaded.

virtual bool Amplitude::Engine::HasLoadedSoundBank (
    AmBankID id
) const = 0

Parameters:

• id The sound bank id to check.

Returns:

true if the sound bank has been loaded, false otherwise.

Checks if any sound banks have been loaded.

virtual bool Amplitude::Engine::HasLoadedSoundBanks () const = 0

Returns:

true if any sound banks have been loaded, false otherwise.

Initializes the Amplitude engine.

virtual bool Amplitude::Engine::Initialize (
    const AmOsString & configFile
) = 0

Parameters:

• configFile The path to the configuration file.

Returns:

true when the engine has been successfully initialized, false otherwise.

Checks whether the game is tracking environment amounts himself.

virtual bool Amplitude::Engine::IsGameTrackingEnvironmentAmounts () const = 0

Returns:

Whether the game is tracking the environment amounts.

Checks if the Amplitude engine has been successfully initialized.

virtual bool Amplitude::Engine::IsInitialized () const = 0

Returns:

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

Checks whether the engine is currently muted.

virtual bool Amplitude::Engine::IsMuted () const = 0

Returns:

true if the engine is muted, false otherwise.

Checks whether the engine is currently paused.

virtual bool Amplitude::Engine::IsPaused () const = 0

Returns:

true if the engine is currently paused, false otherwise.

Checks if the engine is stopping.

virtual bool Amplitude::Engine::IsStopping () const = 0

Returns:

true if the engine is stopping, false otherwise.

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

virtual bool Amplitude::Engine::LoadSoundBank (
    const AmOsString & filename
) = 0

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.

Parameters:

• filename The path to the sound bank asset file.

Returns:

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

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

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

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.

Parameters:

• filename The path to the sound bank asset file.
• outID The ID of the loaded sound bank.

Returns:

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

Loads a sound bank from memory.

virtual bool Amplitude::Engine::LoadSoundBankFromMemoryView (
    AmConstVoidPtr ptr,
    AmSize size
) = 0

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.

Parameters:

• ptr The pointer to the sound bank data to be loaded.
• 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.

Returns:

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

Loads a sound bank from memory.

virtual bool Amplitude::Engine::LoadSoundBankFromMemoryView (
    AmConstVoidPtr ptr,
    AmSize size,
    AmBankID & outID
) = 0

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.

Parameters:

• ptr The pointer to the sound bank data to be loaded.
• size The size of the memory to read.
• 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.

Returns:

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

Executes the given callback on the next frame.

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

Note:

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

Parameters:

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

Pauses or resumes all playing sounds and streams.

virtual void Amplitude::Engine::Pause (
    bool pause
) const = 0

Parameters:

• pause Whether to pause or resume the engine.

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

virtual Channel Amplitude::Engine::Play (
    SwitchContainerHandle handle
) const = 0

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

Parameters:

• handle A handle to the switch container to play.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SwitchContainerHandle handle,
    const AmVector3 & location
) const = 0

Parameters:

• handle A handle to the switch container to play.
• location The location at which the switch container should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SwitchContainerHandle handle,
    const AmVector3 & location,
    AmReal32 userGain
) const = 0

Parameters:

• handle A handle to the switch container to play.
• location The location at which the switch container should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SwitchContainerHandle handle,
    const Entity & entity
) const = 0

Note:

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

Parameters:

• handle A handle to the switch container to play.
• entity The entity on which the switch container should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SwitchContainerHandle handle,
    const Entity & entity,
    AmReal32 userGain
) const = 0

Note:

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

Parameters:

• handle A handle to the switch container to play.
• entity The entity on which the switch container should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    CollectionHandle handle
) const = 0

Parameters:

• handle A handle to the collection to play.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    CollectionHandle handle,
    const AmVector3 & location
) const = 0

Parameters:

• handle A handle to the collection to play.
• location The location at which the collection should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    CollectionHandle handle,
    const AmVector3 & location,
    AmReal32 userGain
) const = 0

Parameters:

• handle A handle to the collection to play.
• location The location at which the collection should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    CollectionHandle handle,
    const Entity & entity
) const = 0

Note:

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

Parameters:

• handle A handle to the collection to play.
• entity The entity on which the collection should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    CollectionHandle handle,
    const Entity & entity,
    AmReal32 userGain
) const = 0

Note:

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

Parameters:

• handle A handle to the collection to play.
• entity The entity on which the collection should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SoundHandle handle
) const = 0

Parameters:

• handle A handle to the sound to play.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SoundHandle handle,
    const AmVector3 & location
) const = 0

Parameters:

• handle A handle to the sound to play.
• location The location at which the sound should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SoundHandle handle,
    const AmVector3 & location,
    AmReal32 userGain
) const = 0

Parameters:

• handle A handle to the sound to play.
• location The location at which the sound should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SoundHandle handle,
    const Entity & entity
) const = 0

Note:

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

Parameters:

• handle A handle to the sound to play.
• entity The entity on which the sound should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    SoundHandle handle,
    const Entity & entity,
    AmReal32 userGain
) const = 0

Note:

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

Parameters:

• handle A handle to the sound to play.
• entity The entity on which the sound should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    const AmString & name
) const = 0

Note:

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

Parameters:

• name The name of the sound object to play.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    const AmString & name,
    const AmVector3 & location
) const = 0

Note:

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

Parameters:

• name The name of the sound object to play.
• location The location at which the sound should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    const AmString & name,
    const AmVector3 & location,
    AmReal32 userGain
) const = 0

Note:

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

Parameters:

• name The name of the sound object to play.
• location The location at which the sound should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    const AmString & name,
    const Entity & entity
) const = 0

Note:

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.

Parameters:

• name The name of the sound object to play.
• entity The entity on which the sound object should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    const AmString & name,
    const Entity & entity,
    AmReal32 userGain
) const = 0

Note:

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.

Parameters:

• name The name of the sound object to play.
• entity The entity on which the sound object should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    AmObjectID id
) const = 0

Note:

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

Parameters:

• id The ID of the sound object to play.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    AmObjectID id,
    const AmVector3 & location
) const = 0

Note:

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

Parameters:

• id The ID of the sound object to play.
• location The location at which the sound object should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    AmObjectID id,
    const AmVector3 & location,
    AmReal32 userGain
) const = 0

Note:

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

Parameters:

• id The ID of the sound object to play.
• location The location at which the sound object should be played.
• 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.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    AmObjectID id,
    const Entity & entity
) const = 0

Note:

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.

Parameters:

• id The ID of the sound object to play.
• entity The entity on which the sound object should be played.

Returns:

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.

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

virtual Channel Amplitude::Engine::Play (
    AmObjectID id,
    const Entity & entity,
    AmReal32 userGain
) const = 0

Note:

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.

Parameters:

• id The ID of the sound object to play.
• entity The entity on which the sound object should be played.
• 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.

Returns:

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.

Removes an Entity .

virtual void Amplitude::Engine::RemoveEntity (
    const Entity * entity
) const = 0

Parameters:

• entity The game entity to be removed.

See also: Entity

Removes an Entity given its ID.

virtual void Amplitude::Engine::RemoveEntity (
    AmEntityID id
) const = 0

Parameters:

• id The ID of the game entity to be removed.

See also: Entity

Removes an Environment .

virtual void Amplitude::Engine::RemoveEnvironment (
    const Environment * environment
) const = 0

Parameters:

• environment The game environment to be removed.

See also: Environment

Removes an Environment given its ID.

virtual void Amplitude::Engine::RemoveEnvironment (
    AmEnvironmentID id
) const = 0

Parameters:

• id The ID of the game environment to be removed.

See also: Environment

Removes a Listener given its ID.

virtual void Amplitude::Engine::RemoveListener (
    AmListenerID id
) const = 0

Parameters:

• id The ID of the Listener to be removed.

See also: Listener

Removes a Listener given its handle.

virtual void Amplitude::Engine::RemoveListener (
    const Listener * listener
) const = 0

Parameters:

• listener The Listener to be removed.

See also: Listener

Removes a Room .

virtual void Amplitude::Engine::RemoveRoom (
    const Room * room
) const = 0

Parameters:

• room The room to be removed.

See also: Room

Removes a Room given its ID.

virtual void Amplitude::Engine::RemoveRoom (
    AmRoomID id
) const = 0

Parameters:

• id The ID of the room to be removed.

See also: Room

Sets the default sound listener.

virtual void Amplitude::Engine::SetDefaultListener (
    const Listener * listener
) = 0

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

Note:

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

Parameters:

• listener A valid and initialized Listener instance.