Name AL_SOFT_events Contributors Chris Robinson Contact Chris Robinson (chris.kcat 'at' gmail.com) Status Complete Dependencies This extension is for OpenAL 1.1. This extension interacts with ALC_EXT_disconnect. Overview This extension provides a method for applications to receive notifications about audio events via an asynchronous callback. This can help alleviate the need for applications to continually poll the AL to check if an event happened, and instead allow them to respond when events happen. Such events can include a source changing state or a device becoming disconnected. Issues Q: Given a mixer that runs in a real-time context, what restrictions are there on the handler for events generated by the mixer? A: The callback does not need to be real-time safe, so locks and I/O are allowed. The implementation is responsible for ensuring the events are marshalled to a separate event-handler thread if the mixer thread is unsuitable for non-real-time code. Note, however, that despite not running in the mixer context, there may be a limited queue for events to be stored, so the callback should still try to be expedient. Be aware also that this means the callback may run after the event occured, so for example, querying the device's ALC_CONNECTED state could return ALC_FALSE before the callback was invoked for the disconnection event. Q: What types of events should be specified? A: For now, source state changes, buffers in a source's buffer queue becoming processed, and device disconnection. Additional events can be added with future extensions as necessary. New Procedures and Functions void AL_APIENTRY alEventControlSOFT(ALsizei count, const ALenum *types, ALboolean enable); void AL_APIENTRY alEventCallbackSOFT(ALEVENTPROCSOFT callback, ALvoid *userParam); ALvoid* AL_APIENTRY alGetPointerSOFT(ALenum pname); void AL_APIENTRY alGetPointervSOFT(ALenum pname, ALvoid **values); New Types typedef void (AL_APIENTRY *ALEVENTPROCSOFT)(ALenum eventType, ALuint object, ALuint param, ALsizei length, const ALchar *message, ALvoid *userParam); New Tokens Accepted as the parameter of alGetPointerSOFT and alGetPointervSOFT: AL_EVENT_CALLBACK_FUNCTION_SOFT 0x19A2 AL_EVENT_CALLBACK_USER_PARAM_SOFT 0x19A3 Accepted as an element in the parameter of alEventControlSOFT, and provided as the parameter of ALEVENTPROCSOFT callback functions: AL_EVENT_TYPE_BUFFER_COMPLETED_SOFT 0x19A4 AL_EVENT_TYPE_SOURCE_STATE_CHANGED_SOFT 0x19A5 AL_EVENT_TYPE_DISCONNECTED_SOFT 0x19A6 Additions to Specification Asychronous Events When OpenAL asynchronously processes updates and renders samples, certain events may occur that an application may be interested in reacting to. OpenAL itself may also asynchronously receive events from the system that an application may be interested in knowing about. Normally such events will alter the appropriate object's state which the application can then query. However, sometimes an application would prefer to be alerted to an event happening rather than querying it to check. To do so, a callback can be set to receive notification of the desired events. The callback should follow the prototype typedef void (AL_APIENTRY *ALEVENTPROCSOFT)(ALenum eventType, ALuint object, ALuint param, ALsizei length, const ALchar *message, ALvoid *userParam); The callback is not allowed to make AL function calls, or undefined behavior results. To set the callback to be invoked with information about events, use the function void AL_APIENTRY alEventCallbackSOFT(ALEVENTPROCSOFT callback, ALvoid *userParam); with specifying the address of a function following the ALEVENTPROCSOFT prototype. Only one event callback can be set per context, and setting NULL will disable the event callback. The pointer will be stored with the function address and passed as a parameter to the callback when it's invoked. When changing the function callback, any current or pending invocations of the previous function will finish prior to the alEventCallbackSOFT call returning. Along with , the event type, an event type-dependent object ID, and an event type-dependent parameter value are provided as the , , and callback parameters. A string description of the event is provided in the pointer, with as the number of bytes in the string (excluding the null-terminator). The string will be UTF-8 encoded. The current callback function address and user parameter pointer can be retrieved by calling alGetPointerSOFT or alGetPointervSOFT, with AL_EVENT_CALLBACK_FUNCTION_SOFT and AL_EVENT_CALLBACK_USER_PARAM_SOFT specified for respectively. By default, no event types are set to be reported. Event types can be enabled, and subsequently disabled, for being reported using the function void AL_APIENTRY alEventControlSOFT(ALsizei count, const ALenum *types, ALboolean enable); is the number of event types pointed to by . If is AL_TRUE, the specified event types will be enabled. Otherwise, if is AL_FALSE, the specified event types will be disabled. Any event types not specified in will retain its last-specified state. Disabling an event type that is already disabled, and enabling an event type that is already enabled, are legal no-ops. Events that have already occurred prior to the event type being enabled will not be retroactively reported. When disabling event types, invocations of the callback for those event types will finish prior to the alEventControlSOFT call returning. Pending invocations may also be dropped. Available Event Types The event types that can be reported with the callback, along with the meaning of the and callback parameters, are described in the following table. AL_EVENT_TYPE_BUFFER_COMPLETED_SOFT ---------------------------------------------------------------------- A streaming source's buffer queue has finished processing one or more buffers. -------------------------------------------------------------------------- | ------------------------------------|------------------------------------- ID of the source that finished | The number of buffers that finished processing some buffers. | processing with this event. AL_EVENT_TYPE_SOURCE_STATE_CHANGED_SOFT ---------------------------------------- A source's playing state has changed. -------------------------------------------------------------------------- | --------------------------------------|----------------------------------- ID of the source whose state changed. | The source's new state. AL_EVENT_TYPE_DISCONNECTED_SOFT ---------------------------------------------------------------------- The context's device became disconnected (as per ALC_EXT_disconnect). -------------------------------------------------------------------------- | ------------------------------------|------------------------------------- Unused/undefined. | Unused/undefined. Errors An AL_INVALID_ENUM error is generated if an unknown event type enum is passed to alEventControlSOFT's array.