The CryEngine AdioTranslationLayer uses this interface to communicate with an audio middleware

struct IAudioSystemImplementation {
};

IAudioSystemImplementation.h

Activate an audio-middleware-specific ATLTriggerImpl

virtual EAudioRequestStatus ActivateTrigger(IATLAudioObjectData* const pAudioObjectData, IATLTriggerImplData const* const pTriggerData, IATLEventData* const pEventData) = 0;

eARS_SUCCESS if the ATLTriggerImpl has been successfully activated by the audio middleware, eARS_FAILURE otherwise

SetRtpc, SetSwitchState, StopEvent

Free the memory and potentially other resources used by the supplied IATLEnvironmentImplData instance

virtual void DeleteAudioEnvironmentImplData(IATLEnvironmentImplData const* const pOldEnvironmentImplData) = 0;

Syntax: DeleteAudioEnvironmentImplData(pOldEnvironmentImplData)

NewAudioEnvironmentImplData

Free the memory and potentially other resources used by the supplied IATLEventData instance

virtual void DeleteAudioEventData(IATLEventData* const pOldEventData) = 0;

NewAudioEventData, ResetAudioEventData

Free the memory and potentially other resources used by the supplied IATLAudioFileEntryData instance. Normally, an IATLAudioFileEntryData instance is created by ParseAudioFileEntry() and a pointer is stored in a member of SATLAudioFileEntryInfo.

virtual void DeleteAudioFileEntryData(IATLAudioFileEntryData* const pOldAudioFileEntryData) = 0;

ParseAudioFileEntry

Free the memory and potentially other resources used by the supplied IATLListenerData instance

virtual void DeleteAudioListenerObjectData(IATLListenerData* const pOldListenerData) = 0;

NewDefaultAudioListenerObjectData, NewAudioListenerObjectData

Free the memory and potentially other resources used by the supplied IATLAudioObjectData instance

virtual void DeleteAudioObjectData(IATLAudioObjectData* const pOldObjectData) = 0;

NewAudioObjectData, NewGlobalAudioObjectData

Free the memory and potentially other resources used by the supplied IATLRtpcImplData instance

virtual void DeleteAudioRtpcImplData(IATLRtpcImplData const* const pOldRtpcImplData) = 0;

Syntax: DeleteAudioRtpcImplData(pOldRtpcImplData)

NewAudioRtpcImplData

Free the memory and potentially other resources used by the supplied IATLSwitchStateImplData instance

virtual void DeleteAudioSwitchStateImplData(IATLSwitchStateImplData const* const pOldAudioSwitchStateImplNode) = 0;

Syntax: DeleteAudioRtpcImplData(pOldAudioSwitchStateImplNode)

NewAudioSwitchStateImplData

Free the memory and potentially other resources used by the supplied IATLTriggerImplData instance

virtual void DeleteAudioTriggerImplData(IATLTriggerImplData const* const pOldTriggerImplData) = 0;

NewAudioTriggerImplData

Return a string describing the audio middleware used. This string is printed on the first line of the AudioDebug header shown on the screen whenever s_DrawAudioDebug is not 0

virtual char const* const GetImplementationNameString() const = 0;

A zero-terminated C-string with the description of the audio middleware used by this AudioSystemImplementation.

Fill in the oMemoryInfo describing the current memory usage of this AudioSystemImplementation. This data gets displayed in the AudioDebug header shown on the screen whenever s_DrawAudioDebug is not 0

virtual void GetMemoryInfo(SAudioImplMemoryInfo& oMemoryInfo) const = 0;

Initialize all internal components and the audio middleware.

virtual EAudioRequestStatus Init() = 0;

eARS_SUCCESS if the initialization was successful, eARS_FAILURE otherwise.

ShutDown

Mute all sounds, after this call there should be no audio coming from the audio middleware.

virtual EAudioRequestStatus MuteAll() = 0;

eARS_SUCCESS if the action was successful, eARS_FAILURE otherwise.

UnmuteAll, StopAllSounds

Parse the implementation-specific XML node that represents an ATLEnvironmentImpl, return a pointer to the data needed for identifying and using this ATLEnvironmentImpl instance inside the AudioSystemImplementation

virtual IATLEnvironmentImplData const* NewAudioEnvironmentImplData(XmlNodeRef const pAudioEnvironmentNode) = 0;

IATLEnvironmentImplData const* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding ATLEnvironmentImpl; NULL if the new IATLEnvironmentImplData instance was not created

DeleteAudioEnvironmentImplData

Create an object implementing IATLEventData that stores all of the data needed by the AudioSystemImplementation to identify and use an AudioEvent. Return a pointer to that object.

virtual IATLEventData* NewAudioEventData(TAudioEventID const nEventID) = 0;

IATLEventData* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding AudioEvent; NULL if the new IATLEventData instance was not created

DeleteAudioEventData, ResetAudioEventData

Create an object implementing IATLListenerData that stores all of the data needed by the AudioSystemImplementation to identify and use an AudioListener. Return a pointer to that object.

virtual IATLListenerData* NewAudioListenerObjectData(uint const nIndex) = 0;

IATLListenerData* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding AudioListener; NULL if the new IATLListenerData instance was not created

DeleteAudioListenerObjectData

Create an object implementing IATLAudioObjectData that stores all of the data needed by the AudioSystemImplementation to identify and use the AudioObject with the provided AudioObjectID. Return a pointer to that object.

virtual IATLAudioObjectData* NewAudioObjectData(TAudioObjectID const nObjectID) = 0;

IATLAudioObjectData* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding GlobalAudioObject; NULL if the new IATLAudioObjectData instance was not created

DeleteAudioObjectData

Parse the implementation-specific XML node that represents an ATLRtpcImpl, return a pointer to the data needed for identifying and using this ATLRtpcImpl instance inside the AudioSystemImplementation

virtual IATLRtpcImplData const* NewAudioRtpcImplData(XmlNodeRef const pAudioRtpcNode) = 0;

IATLRtpcImplData const* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding ATLRtpcImpl; NULL if the new AudioTriggerImplData instance was not created

DeleteAudioRtpcImplData

Parse the implementation-specific XML node that represents an ATLSwitchStateImpl, return a pointer to the data needed for identifying and using this ATLSwitchStateImpl instance inside the AudioSystemImplementation

virtual IATLSwitchStateImplData const* NewAudioSwitchStateImplData(XmlNodeRef const pAudioSwitchStateImplNode) = 0;

IATLRtpcImplData const* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding ATLSwitchStateImpl; NULL if the new AudioTriggerImplData instance was not created

DeleteAudioSwitchStateImplData

Parse the implementation-specific XML node that represents an ATLTriggerImpl, return a pointer to the data needed for identifying and using this ATLTriggerImpl instance inside the AudioSystemImplementation

virtual IATLTriggerImplData const* NewAudioTriggerImplData(XmlNodeRef const pAudioTriggerNode) = 0;

IATLRtpcImplData const* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding ATLTriggerImpl; NULL if the new AudioTriggerImplData instance was not created

DeleteAudioTriggerImplData

Create an object implementing IATLListenerData that stores all of the data needed by the AudioSystemImplementation to identify and use the DefaultAudioListener. Return a pointer to that object.

virtual IATLListenerData* NewDefaultAudioListenerObjectData() = 0;

IATLListenerData* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the DefaultAudioListener; NULL if the new IATLListenerData instance was not created

DeleteAudioListenerObjectData

Create an object implementing IATLAudioObjectData that stores all of the data needed by the AudioSystemImplementation to identify and use the GlobalAudioObject with the provided AudioObjectID

virtual IATLAudioObjectData* NewGlobalAudioObjectData(TAudioObjectID const nObjectID) = 0;

IATLAudioObjectData* pointer to the audio implementation-specific data needed by the audio middleware and the AudioSystemImplementation code to use the corresponding GlobalAudioObject; NULL if the new IATLAudioObjectData instance was not created

DeleteAudioObjectData

Perform a "hot restart" of the audio middleware. Reset all of the internal data.

virtual void OnAudioSystemRefresh() = 0;

Release, Init

This method is called every time the main Game (or Editor) window gets focus.

virtual EAudioRequestStatus OnGetFocus() = 0;

eARS_SUCCESS if the action was successful, eARS_FAILURE otherwise.

OnLoseFocus

This method is called every time the main Game (or Editor) window loses focus.

virtual EAudioRequestStatus OnLoseFocus() = 0;

eARS_SUCCESS if the action was successful, eARS_FAILURE otherwise.

OnGetFocus

Parse the implementation-specific XML node that represents an AudioFileEntry, fill the fields of the struct referenced by pFileEntryInfo with the data necessary to correctly access and store the file's contents in memory. Create an object implementing IATLAudioFileEntryData to hold implementation-specific data about the file and store a pointer to it in a member of pFileEntryInfo

virtual EAudioRequestStatus ParseAudioFileEntry(XmlNodeRef const pAudioFileEntryNode, SATLAudioFileEntryInfo* const pFileEntryInfo) = 0;

eARS_SUCCESS if the XML node was parsed successfully, eARS_FAILURE otherwise

Load the metadata and media needed by the audio middleware to execute the ATLTriggerImpl described by pTriggerData asynchronously. An active event that references pEventData is created on the corresponding AudioObject. The callback called once the loading is done must report that this event is finished. Preparing Triggers manually is only necessary if their data have not been loaded via PreloadRequests.

virtual EAudioRequestStatus PrepareTriggerAsync(IATLAudioObjectData* const pAudioObjectData, IATLTriggerImplData const* const pTriggerData, IATLEventData* const pEventData) = 0;

eARS_SUCCESS if the the request was successfully sent to the audio middleware, eARS_FAILURE otherwise

UnprepareTriggerAsync, PrepareTriggerSync, UnprepareTriggerSync

Load the metadata and media needed by the audio middleware to execute the ATLTriggerImpl described by pTriggerData. Preparing Triggers manually is only necessary if their data have not been loaded via PreloadRequests.

virtual EAudioRequestStatus PrepareTriggerSync(IATLAudioObjectData* const pAudioObjectData, IATLTriggerImplData const* const pTriggerData) = 0;

eARS_SUCCESS if the the data was successfully loaded, eARS_FAILURE otherwise

UnprepareTriggerSync, PrepareTriggerAsync, UnprepareTriggerAsync

Register an audio object with the audio middleware. An object needs to be registered for one to set position, execute triggers on it, or set Rtpcs and switches. This version of the method is meant to be used in the release builds.

virtual EAudioRequestStatus RegisterAudioObject(IATLAudioObjectData* const pObjectData) = 0;

eARS_SUCCESS if the object has been registered, eARS_FAILURE if the registration failed

UnregisterAudioObject, ResetAudioObject

Register an audio object with the audio middleware. An object needs to be registered for one to set position, execute triggers on it, or set Rtpcs and switches. This version of the method is meant be used in debug builds.

virtual EAudioRequestStatus RegisterAudioObject(IATLAudioObjectData* const pObjectData, char const* const sObjectName) = 0;

eARS_SUCCESS if the object has been registered, eARS_FAILURE if the registration failed

UnregisterAudioObject, ResetAudioObject

Inform the audio middleware about the memory location of a preloaded audio-data file

virtual EAudioRequestStatus RegisterInMemoryFile(SATLAudioFileEntryInfo* const pAudioFileEntry) = 0;

eARS_SUCCESS if the audio middleware is able to use the preloaded file, eARS_FAILURE otherwise

UnregisterInMemoryFile

Frees all of the resources used by the class and destroys the instance. This action is not reversible.

virtual EAudioRequestStatus Release() = 0;

eARS_SUCCESS if the action was successful, eARS_FAILURE otherwise.

ShutDown, Init

Reset all the members of an IATLEventData instance without releasing the memory, so that the instance can be returned to the pool to be reused.

virtual void ResetAudioEventData(IATLEventData* const pEventData) = 0;

Syntax: ResetAudioEventData(pEventData)

NewAudioEventData, DeleteAudioEventData

Clear out the object data and resets it so that the object can be returned to the pool of available Audio Object for reuse.

virtual EAudioRequestStatus ResetAudioObject(IATLAudioObjectData* const pObjectData) = 0;

eARS_SUCCESS if the object has been reset, eARS_FAILURE otherwise

RegisterAudioObject, UnregisterAudioObject

Set the provided value for the specified ATLEnvironmentImpl on the given AudioObject

virtual EAudioRequestStatus SetEnvironment(IATLAudioObjectData* const pAudioObjectData, IATLEnvironmentImplData const* const pEnvironmentImplData, float const fAmount) = 0;

eARS_SUCCESS if the provided the value has been successfully set, eARS_FAILURE otherwise

SetObstructionOcclusion

Set the world position of an AudioListener inside the audio middleware

virtual EAudioRequestStatus SetListenerPosition(IATLListenerData* const pListenerData, SATLWorldPosition const& oNewPosition) = 0;

eARS_SUCCESS if the AudioListener's position has been successfully set, eARS_FAILURE otherwise

SetPosition

Set the provided Obstruction and Occlusion values on the given AudioObject

virtual EAudioRequestStatus SetObstructionOcclusion(IATLAudioObjectData* const pAudioObjectData, float const fObstruction, float const fOcclusion) = 0;

eARS_SUCCESS if the provided the values been successfully set, eARS_FAILURE otherwise

SetEnvironment

Set the world position of an AudioObject inside the audio middleware

virtual EAudioRequestStatus SetPosition(IATLAudioObjectData* const pAudioObjectData, SATLWorldPosition const& oWorldPosition) = 0;

eARS_SUCCESS if the AudioObject's position has been successfully set, eARS_FAILURE otherwise

StopEvent, PrepareTriggerAsync, UnprepareTriggerAsync, ActivateTrigger

Set the ATLRtpcImpl to the specified value on the provided AudioObject

virtual EAudioRequestStatus SetRtpc(IATLAudioObjectData* const pAudioObjectData, IATLRtpcImplData const* const pRtpcData, float const fValue) = 0;

eARS_SUCCESS if the provided value has been successfully set on the passed ATLRtpcImpl, eARS_FAILURE otherwise

ActivateTrigger, SetSwitchState, SetEnvironment, SetPosition

Set the ATLSwitchStateImpl on the given AudioObject

virtual EAudioRequestStatus SetSwitchState(IATLAudioObjectData* const pAudioObjectData, IATLSwitchStateImplData const* const pSwitchStateData) = 0;

eARS_SUCCESS if the provided ATLSwitchStateImpl has been successfully set, eARS_FAILURE otherwise

ActivateTrigger, SetRtpc, SetEnvironment, SetPosition

Shuts down all of the internal components and the audio middleware.

virtual EAudioRequestStatus ShutDown() = 0;

eARS_SUCCESS if the shutdown was successful, eARS_FAILURE otherwise.

After a call to ShutDown(), the system can still be reinitialized by calling Init().

Release, Init

Stop all ATLEvents currently active on an AudioObject

virtual EAudioRequestStatus StopAllEvents(IATLAudioObjectData* const pAudioObjectData) = 0;

eARS_SUCCESS if all of the ATLEvents have been successfully stopped, eARS_FAILURE otherwise

StopEvent, PrepareTriggerAsync, UnprepareTriggerAsync, ActivateTrigger

Stop all currently playing sounds. Has no effect on anything triggered after this method is called.

virtual EAudioRequestStatus StopAllSounds() = 0;

eARS_SUCCESS if the action was successful, eARS_FAILURE otherwise.

MuteAll

Stop and ATLEvent active on an AudioObject

virtual EAudioRequestStatus StopEvent(IATLAudioObjectData* const pAudioObjectData, IATLEventData const* const pEventData) = 0;

eARS_SUCCESS if the ATLEvent has been successfully stopped, eARS_FAILURE otherwise

StopAllEvents, PrepareTriggerAsync, UnprepareTriggerAsync, ActivateTrigger

Restore the audio output of the audio middleware after a call to MuteAll().

virtual EAudioRequestStatus UnmuteAll() = 0;

eARS_SUCCESS if the action was successful, eARS_FAILURE otherwise.

MuteAll

Unload the metadata and media needed by the audio middleware to execute the ATLTriggerImpl described by pTriggerData asynchronously. An active event that references pEventData is created on the corresponding AudioObject. The callback called once the unloading is done must report that this event is finished. Un-preparing Triggers manually is only necessary if their data are not managed via PreloadRequests.

virtual EAudioRequestStatus UnprepareTriggerAsync(IATLAudioObjectData* const pAudioObjectData, IATLTriggerImplData const* const pTriggerData, IATLEventData* const pEventData) = 0;

eARS_SUCCESS if the the request was successfully sent to the audio middleware, eARS_FAILURE otherwise

PrepareTriggerAsync, PrepareTriggerSync, UnprepareTriggerSync

Release the metadata and media needed by the audio middleware to execute the ATLTriggerImpl described by pTriggerData Un-preparing Triggers manually is only necessary if their data are not managed via PreloadRequests.

virtual EAudioRequestStatus UnprepareTriggerSync(IATLAudioObjectData* const pAudioObjectData, IATLTriggerImplData const* const pTriggerData) = 0;

eARS_SUCCESS if the the data was successfully unloaded, eARS_FAILURE otherwise

PrepareTriggerSync, PrepareTriggerAsync, UnprepareTriggerAsync

Unregister an audio object with the audio middleware. After this action executing triggers, setting position, states or rtpcs should have no effect on the object referenced by pObjectData.

virtual EAudioRequestStatus UnregisterAudioObject(IATLAudioObjectData* const pObjectData) = 0;

eARS_SUCCESS if the object has been unregistered, eARS_FAILURE if the un-registration failed

RegisterAudioObject, ResetAudioObject

Inform the audio middleware that the memory containing the preloaded audio-data file should no longer be used

virtual EAudioRequestStatus UnregisterInMemoryFile(SATLAudioFileEntryInfo* const pAudioFileEntry) = 0;

eARS_SUCCESS if the audio middleware was able to unregister the preloaded file supplied, eARS_FAILURE otherwise

RegisterInMemoryFile

Update all of the internal components that require regular updates, update the audio middleware state.

virtual void Update(float const fUpdateIntervalMS) = 0;

void

Performs actions that need to be executed regularly on an AudioObject.

virtual EAudioRequestStatus UpdateAudioObject(IATLAudioObjectData* const pObjectData) = 0;

eARS_SUCCESS if the object has been reset, eARS_FAILURE otherwise

An enum that lists possible statuses of an AudioRequest. Used as a return type for many function used by the AudioSystem internally, and also for most of the IAudioSystemImplementation calls

enum ATL_ENUM_TYPE {
  eARS_NONE = 0,
  eARS_SUCCESS = 1,
  eARS_FAILURE = 2,
  eARS_PENDING = 3,
  eARS_FAILURE_INVALID_OBJECT_ID = 4,
  eARS_FAILURE_INVLAID_CONTROL_ID = 5,
  eARS_FAILURE_INVLAID_REQUEST = 6
};

IAudioSystemImplementation.h