[Openal-devel] Three Extensions

[Richard Furse]

Skipped content of type multipart/alternative-------------- next part --------------
#ifndef AL_AL_BFORMAT_H
#define AL_AL_BFORMAT_H

// PROVISIONAL
// 
// THIS HAS NOT YET BEEN REGISTERED IN THE OPENAL EXTENSION DATABASE
// OR SETTLED FOR ANY REAL USE AS YET.

/*
 * This extension indicates support for the AL_FORMAT_BFORMAT8,
 * AL_FORMAT_BFORMAT16 and AL_FORMAT_BFORMAT_FLOAT32 buffer formats.
 * 
 * These are, respectively, 8bit int, 16bit int and ALfloat support
 * for Ambisonic four-channel B-Format (using W X Y Z channel
 * ordering, encoded as the first four channels of Furse-Malham higher
 * order Ambisonics). Use of these formats indicate that sources are
 * Ambisonic sources. Such sources can be oriented via alSourcefv()
 * using the AL_ORIENTATION tag, which takes the same parameters as
 * the alListenerfv(AL_ORIENTATION,...). Such sources DO support
 * AL_SOURCE_RELATIVE and the soundfield will rotate to reflect the
 * listener's orientation if this is off (the default). Other
 * behaviour is as for stereo or multichannel assets.
 *
 * Note that Ambisonics orients X, Y and Z axes in a different way to
 * OpenAL. For clarity, we ignore the Ambisonic coordinate system in
 * the API and stick to the OpenAL one, making sure that the Front of
 * the Ambisonic soundfield (actually Ambisonic +X) matches the Front
 * of the OpenAL coordinate system (-Z by default) etc. For instance,
 * if the orientation of the source is set so that the "at" vector is
 * to the left, then the front of the B-Format soundfield will be
 * presented to the left.
 */
#define AL_EXT_BFORMAT_NAME "AL_EXT_BFORMAT"

#define AL_FORMAT_BFORMAT8            0x20001
#define AL_FORMAT_BFORMAT16           0x20002
#define AL_FORMAT_BFORMAT_FLOAT32     0x20003

#endif /* AL_AL_BFORMAT_H */
-------------- next part --------------
#ifndef AL_AL_FOLDBACK_H
#define AL_AL_FOLDBACK_H

// PROVISIONAL
// 
// THIS HAS NOT YET BEEN REGISTERED IN THE OPENAL EXTENSION DATABASE
// OR SETTLED FOR ANY REAL USE AS YET.

#include "al.h"

#if defined(__cplusplus)
extern "C" {
#endif

#define AL_EXT_FOLDBACK_NAME "AL_EXT_FOLDBACK"

#define AL_FOLDBACK_MODE_MONO   0x4101
#define AL_FOLDBACK_MODE_STEREO 0x4102

#define AL_FOLDBACK_EVENT_START 0x4111
#define AL_FOLDBACK_EVENT_BLOCK 0x4112
#define AL_FOLDBACK_EVENT_STOP  0x4113

/** 
 * Foldback Notes:
 *
 * This OpenAL extension provides a "foldback" facility to OpenAL,
 * allowing a mono or stereo mix of the overall OpenAL output to be
 * fed back to the originating software for further processing,
 * recording etc.
 * 
 * The OpenAL extension can be detected by a call to
 * alIsExtensionPresent requesting extension "AL_EXT_FOLDBACK"
 * (defined by macro AL_EXT_FOLDBACK_NAME).
 *
 * If it is present, the calls "alRequestFoldbackStart" (of type
 * LPALREQUESTFOLDBACKSTART) and "alRequestFoldbackStop" (of type
 * LPALREQUESTFOLDBACKSTOP) will be available from
 * alGetProcAddress. Both of these calls are asynchronous and start an
 * event stream to be handled by a callback function required by
 * alRequestFoldbackStart.
 * 
 * The calling software is required to provide a range of memory into
 * which foldback data will be written. This range of memory is a
 * circular buffer, divided into fixed-size blocks. Data is
 * interleaved if stereo is required. The callback function indicates
 * when a block of memory is ready for processing. The callbacks are
 * delivered asynchronously and in sequence - it is up to the calling
 * software to keep up with the data flow.
 * 
 * If the alRequestFoldbackStart call succeeds, the callback function
 * will be fed events. The first event is an AL_FOLDBACK_EVENT_START
 * event indicating that streaming has begun. Subsequent events are
 * zero or more AL_FOLDBACK_EVENT_BLOCK events indicating each block
 * as it becomes ready, with a final AL_FOLDBACK_EVENT_STOP to
 * indicate that processing has ended. The memory region should not be
 * released until an AL_FOLDBACK_EVENT_STOP event has been received
 * (normally this occurs after alRequestFoldbackStop has returned).
 */

/**
 * Foldback Callback.
 *
 * Three different "event" values are defined: AL_FOLDBACK_EVENT_START
 * indicates that streaming has begun, AL_FOLDBACK_EVENT_BLOCK
 * indicates a data block is ready and AL_FOLDBACK_EVENT_STOP
 * indicates that streaming has ended.
 *
 * The "blockIndex" value is defined only where the event is
 * AL_FOLDBACK_EVENT_BLOCK. In this context, it indicates which block
 * (indexed from zero) within the memory region provided to
 * alRequestFoldbackStart is ready. Note that the blockIndex value
 * wraps around, returning to zero when the bufferCount is reached.
 */
typedef void (AL_APIENTRY *LPALFOLDBACKCALLBACK) ( ALenum event, ALsizei blockIndex );
  
/**
 * Function name: alRequestFoldbackStart
 *
 * If this call succeeds, then it is guaranteed that the callback
 * function be called at least once with a start event and once with a
 * stop event. 
 * 
 * If this call sets AL_INVALID_VALUE, this may be because the
 * blockCount and blockLength are not large enough for the current
 * renderer, so it may be worth trying a larger value.
 * 
 * Data is written into the region of memory starting at bufferMemory
 * in sequential blocks of floats of length blockLength, or twice
 * blockLength if stereo is used (data is interleaved). After each
 * block is written, a callback is queued for delivery.
 * 
 * "foldbackMode" may be AL_FOLDBACK_MODE_MONO for mono or
 * AL_FOLDBACK_MODE_STEREO for interleaved stereo.
 *
 * "blockCount" indicates the number of blocks of audio that should
 * be available at bufferMemory. This must be at least two.
 * 
 * "blockLength" indicates the number of frames of audio that should
 * be available within each block. Note that there will be two samples
 * per frame if stereo is in use.
 *
 * "bufferMemory" indicates the start of the region of memory,
 * provided by the calling software, which will be used for the shared
 * circular buffer. It is required to allow space for a number of
 * floats: blockLength*blockCount floats if foldbackMode is
 * AL_FOLDBACK_MODE_MONO or blockLength*2*blockCount floats if
 * foldbackMode is AL_FOLDBACK_MODE_STEREO. The memory is owned by the
 * calling software and should not be deleted until an
 * AL_FOLDBACK_EVENT_STOP event has been received.
 *
 * "callback" is the pointer to a function provided by the calling
 * software that will handle foldback streaming events (see above).
 */
typedef void (AL_APIENTRY *LPALREQUESTFOLDBACKSTART) ( ALenum foldbackMode, ALsizei blockCount, ALsizei blockLength, ALfloat * bufferMemory, LPALFOLDBACKCALLBACK callback );
/**
 * Function name: alRequestFoldbackStop
 *
 * This call requests an end to foldback. 
 * 
 * Note that this call does not stop foldback immediately - any queued
 * blocks must still be processed. A stop event
 * (AL_FOLDBACK_EVENT_STOP) will be received to indicate that the
 * foldback has actually completed and buffer memory should not be
 * freed before then.
 */
typedef void (AL_APIENTRY *LPALREQUESTFOLDBACKSTOP) ( void );

#if defined(__cplusplus)
}  /* extern "C" */
#endif

#endif /* AL_AL_FOLDBACK_H */
-------------- next part --------------
#ifndef AL_EFX_DEDICATED_H
#define AL_EFX_DEDICATED_H

// PROVISIONAL
// 
// THIS HAS NOT YET BEEN REGISTERED IN THE OPENAL EXTENSION DATABASE
// OR SETTLED FOR ANY REAL USE AS YET.

/*
 * Audio rendered to this effect is routed to a subwoofer if one is 
 * present. Otherwise, it is discarded.
 */
#define AL_EFFECT_DEDICATED_LOW_FREQUENCY_EFFECT 0x9000

/*
 * Audio rendered to this effect is routed to a front centre 
 * speaker if one is present. Otherwise, it is rendered to the 
 * front centre using the normal spatialisation logic.
 */
#define AL_EFFECT_DEDICATED_DIALOGUE             0x9001

#endif /* AL_EFX_DEDICATED_H */