Wwise SDK 2022.1.8
Most of the SDK functions return an error code when an issue occurs. The Sound Engine, however, runs on its own thread, so it is possible that errors may occur without receiving a direct notification. Before being printed to the user, error codes are parsed by translators that will change the code into a meaningful message and resolve numerical identifiers to object names. By default, messages only go through the DefaultErrorMessageTranslator. See Error Message Translators for more details.
There are several ways to detect errors in the Sound Engine. You can do any of the following:
AK::Monitor::SetLocalOutput()to Enable/Disable local output of monitoring messages and errors. For this use case, be sure that the monitoring thread is started. Otherwise, the AkMonitor won't dispatch its notification and nothing will be sent to the local output. To start the monitoring, simply call
AkMonitor::Instance()->StartMonitoring(). In the case where you don't want a separate thread running, make sure
AkMonitor::Instance()->InitMonitoring()has been called and then manually call
Before sending error messages to the user, the Sound Engine sends an error code to the error message translators. The error message translators attempt to parse tags contained in the error code in order to create a more detailed error message. This page explains how to implement the translators in your project.
The following sections describe the two components needed when using error message translators.
First, a callback function must be set to receive the monitoring messages. This function has to follow the signature of
AK::Monitor::LocalOutputFunc and will be the function receiving the error message after the translation. It is in this function that you should define what you want to do with an error message. For example, in IntegrationDemo,
LocalErrorCallback is the callback function. In the demo, when an error message is received, the current page content is modified to show the error message in red. To set the callback function, call
AK::Monitor::SetLocalOutput() and pass the callback function pointer to be used.
The Sound Engine has one default translator which transforms the error codes in readable messages. However, this translator simply prints the information it receives, such as IDs, directly in the error message, without trying to transform them into useful information, such as object names. It is highly recommended that you add other translators to the project in order to receive more detailed error messages. The translators are located in the folder SDK/tools/AkWwiseErrorHandler.
|Note: Some translators may require that other libraries are added to the project. Refer to the documentation of each translator for details.|
Once the translators you want to use are added to the project, create an instance of them and install them in the monitor by calling
AK::Monitor::AddTranslator(). It's important to keep track of the newly created instance in order to be able to delete it.
There are four translator types:
Only the Default translator can handle standard printf-style tags (i.e., those that start with %). Each translator type can redefine how Wwise tags ($) should be handled. It's not necessary to handle every tag in a given translator. fallback translator can be defined, which is called after a translation attempt fails. A translator stack can then be created in order to chain multiple translators together until the translation is successful. The translator at the end of the stack is always a Default translator.
Translators use a tag system similar to the
printf() function. The following tags are supported:
If needed, it's possible to create a new error message translator. Simply create a new class that inherits from the AssistedErrorMessageTranslator interface.
This class has two abstract methods:
InitConnection(): Makes sure the connection to the external source was successful (i.e., ensures the translator is ready to be used)
GetInfoFromExternalSource(): Determines what to do with a given tag
Your new translator doesn't need to handle all tags. It can rely on the next translator in the stack.
|Note: If the new translator implements a way to handle the $p tag, make sure it handles both arguments: Plugin Id and ShareSet Id. See the ParseWwiseTag example in AkDefaultErrorMessageTranslator.cpp.|