
Xaudio Data Structures
Structure Index
typedef struct _XA_DecoderInfo {
const char *name;
XA_InputInfo *input;
XA_OutputInfo *output;
XA_CodecInfo *codec;
XA_ModulesInfo *modules;
XA_StatusInfo *status;
XA_OutputBufferInfo *output_buffer;
XA_NotificationClient notification_client;
XA_DecoderCallbackTable callbacks;
struct _XA_DecoderPrivateInfo *hidden;
} XA_DecoderInfo;
Contains information about a decoder object.
name | read-only | Name of the decoder (currently ignored). |
input | read-only | Pointer to a read-only XA_InputInfo structure that contains the information about the current input object (if any has been instantiated). |
output | read-only | Pointer to a read-only XA_OutputInfo structure that contains the information about the current output object (if any has been instantiated). |
codec | read-only | Pointer to a read-only XA_CodecInfo structure that contains the information about the current codec object (if any has been instantiated). |
modules | read-only | Pointer to a read-only XA_ModulesInfo structure that contains the information about the currently registered input and output modules. |
status | read-only | Pointer to a read-only XA_StatusInfo structure that contains the information about the current status of the decoder. |
output_buffer | read-only | Pointer to a read-only XA_OutputBufferInfo structure that contains information about the output buffer (audio samples) that has just been decoded. |
notification_client | read-write | Read-write XA_NotificationClient structure that the client of the decoder fills in to let the decoder know which functions should be called when it need to do a notification callback (progress nofitication, debug notification or error notification). See section about callbacks for more details. |
callbacks | read-only | A read-only fucntion table that provides callback functions to be used by input/output modules and input/output filters. |
hidden | private | Pointer to an opaque data buffer, used by the decoder to keeps its internal data structures. This pointer is of no use the the client software. |
typedef struct {
enum XA_IOState state;
unsigned long caps;
unsigned long position;
unsigned long size;
void *device;
const XA_InputModule *module;
const char *name;
} XA_InputInfo;
Contains information about an input object.
state | read-only | Current state of the input object. Values are XA_IO_STATE_CLOSED if the input is closed or XA_IO_STATE_OPEN it is open.@caps:read-only:Bitmask of flags indicating the capabilities of the current input object. See section on input capabilities for more details. This field is only valid when the input is open (XA_IO_STATE_OPEN state). |
position | read-only | Current read position of the input. This is an integer representing the number of bytes that have been read from the input stream since the last open() or seek(). This field is only valid when the input is open (XA_IO_STATE_OPEN state). |
size | read-only | Size (in bytes) of the input stream, it is is known. If the size is unknown, this value is 0. This field is only valid when the input is open (XA_IO_STATE_OPEN state). |
device | private | Pointer to an opaque data structure (handle) representing the input object. This is the value returned by the input_new() function of the input module. This field is only valid when the input has been instantiated.vtable:read-only:Virtual function table used by the decoder to make calls to methods of the input object. Use of this structure is reserved for the internal decoder routines. The values of this table cannot be set by the client. |
module | read-only | Function table containing pointer to the methods of the current input object. Use of this structure is reserved for the internal decoder routines.name:read-only:character string containing the name of the current input stream. |
typedef struct {
enum XA_IOState state;
unsigned long caps;
enum XA_OutputChannelsMode channels;
void *device;
const XA_OutputModule *module;
const char *name;
} XA_OutputInfo;
Contains information about an output object.
state | read-only | Current state of the output object. Values are XA_IO_STATE_CLOSED if the output is closed or XA_IO_STATE_OPEN it is open.@caps:read-only:bitmask of flags indicating the capabilities of the current output object. See section on output capabilities for more details. This field is only valid when the output is open (XA_IO_STATE_OPEN state). |
caps | read-only | Bitmask of flags indicating the capabilities of the current output object. See section on output capabilities for more details. This field is only valid when the output is open (XA_IO_STATE_OPEN state). |
channels | read-write | Channel configuration of the output stream. Set this value to XA_OUTPUT_STEREO for stereo output (if the stream is mono, mono will be used instead), XA_OUTPUT_MONO_LEFT for mono left-channel only, XA_OUTPUT_MONO_RIGHT for mono right-channel only (if the stream is mono, XA_OUTPUT_MONO_LEFT and XA_OUTPUT_MONO_RIGHT will produce the same output), or XA_OUTPUT_MONO_MIX for a 50/50 mix of the left and right channels (if the stream is mono, mono will be used instead). |
device | private | pointer to an opaque data structure (handle) representing the output object. This is the value returned by the output_new() function of the output module. This field is only valid when the output has been instantiated.vtable:read-only:Virtual function table used by the decoder to make calls to methods of the output object. Use of this structure is reserved for the internal decoder routines. The values of this table cannot be set by the client. |
module | read-only | Function table containing pointer to the methods of the current output object. Use of this structure is reserved for the internal decoder routines.name:read-only:Character string containing the name of the current output stream. |
typedef struct {
int (*input_module_probe)(const char *name);
int (*input_module_query)(@@STRUCTLINK(XA_InputModuleQuery) *query, unsigned long query_mask);
int (*input_new)(void **input, const char *name, int module_id, struct _XA_DecoderInfo *decoder);
int (*input_delete)(void *input);
int (*input_open)(void *input);
int (*input_close)(void *input);
int (*input_read)(void *input, void *buffer, unsigned long n);
int (*input_seek)(void *input, unsigned long offset);
unsigned long (*input_get_caps)(void *input);
unsigned long (*input_get_size)(void *input);
int (*input_send_message)(void *input, int type, const void *data, unsigned int size);
} XA_InputModule;
Contains the pointer to the functions (function table) that implement the methods of an input module. See section on Input Modules for more details about each of the methods that can be implemented.
input_module_probe | Method to probe the input module. |
input_module_query | Method to get information about an input module. |
input_new | Method to instantiate a new input object. |
input_delete | Method to delete an input object. |
input_open | Method to open an input object. |
input_close | Method to close an input object. |
input_read | Method to read bytes from an input object. |
input_seek | Method to seek to an specific location in an input object's stream. |
input_get_caps | Method to get the capabilities of an input object. |
input_get_size | Method to get the the of the stream of an input object. |
input_send_message | Method to send a private message to an input object. |
typedef struct {
int index;
unsigned long flags;
char name[XA_DECODER_QUERY_MAX_NAME_LENGTH];
char description[XA_DECODER_QUERY_MAX_DESCRIPTION_LENGTH];
} XA_InputModuleQuery;
Used to query an input module for information. It contains the query flags to specify which information to return, and the required information upon return from the query call. See decoder_input_module_query() for more details.
index | read-write | Specifies which device of the input module to query (each registered input module can support multiple input devices). This field is ignored when the query flag XA_DECODER_INPUT_QUERY_MODULE_NAME is set. When the query call returns, this field contains the returned number of devices if the query flag XA_DECODER_INPUT_QUERY_NB_DEVICES was set for the query. |
flags | read-write | Specifies which information is being queried. Valid query flags are XA_DECODER_INPUT_QUERY_MODULE_NAME (to get the name and description of an input module), XA_DECODER_INPUT_QUERY_NB_DEVICES (to get the number of devices of the input module), XA_DECODER_INPUT_QUERY_DEVICE_NAME (to get the name and description of a specific device of the input module. When using this flag, the index field of the query structure must be set to the device index that is being queried). When the query call returns, the required information is stored in the name and description fields, as well as the flags and index fields for some queries. |
name | read-only | String that contains the name of an input module or input device. |
description | read-only | String that contains the short description of an input module or input device. |
typedef struct {
unsigned int h;
unsigned int m;
unsigned int s;
unsigned int f;
} XA_TimeCode;
Structure used to describe a timecode.
h | Hours. |
m | Minutes. |
s | Seconds. |
f | Fractions (100th of a second). |
typedef struct {
unsigned long seconds;
unsigned long microseconds;
} XA_AbsoluteTime;
Structure used to describe an absolute time value.
seconds | Number of seconds. |
microseconds | Number of microseconds. |
typedef struct {
unsigned int changed;
unsigned int level;
unsigned int layer;
unsigned int bitrate;
unsigned int frequency;
unsigned int mode;
unsigned int duration;
} XA_InputStreamInfo;
Structure used to hold informtation about an MPEG Audio stream.
changed | 0 if the stream information has not changed since the last decoded frame, or non zero if it has. |
level | MPEG syntax level (1 for MPEG1, 2 for MPEG2, 0 for MPEG2.5). |
layer | MPEG layer (1, 2 or 3). |
bitrate | MPEG bitrate (in bits per second). |
frequency | MPEG sampling frequency (in Hz). |
mode | MPEG mode (0 for stereo, 1 for joint-stereo, 2 for dual-channel, 3 for mono). |
duration | estimated stream duration (in milliseconds). |
typedef struct {
unsigned int changed;
short *pcm_samples;
unsigned int size;
unsigned int bytes_per_sample;
unsigned int channels;
unsigned int sample_rate;
unsigned long delay;
} XA_OutputBufferInfo;
Structure that describes a decoded audio buffer. This is a read-only structure (the fields are filled-in by the decoder when decoding a frame of the input stream).
changed | read-only | 0 if the parameters have not changed (sample_rate, stereo, etc...), or non 0 if they have changed since the last decoded buffer. |
pcm_samples | read-only | pointer to the memory buffer where the PCM samples are stored. |
size | read-only | Number of bytes in the PCM buffer. |
bytes_per_sample | read-only | Number of bytes per PCM sample (1 8 bits or 2 for 16 bits). By default, this is 16 bits, unless the output module declares that it cannot support 16 bits, in which case the decoder will downgrade the sample to 8 bits (1 byte per sample). |
channels | read-only | 2 if the buffer is stereo, 1 if it is mono (samples in a stereo buffer are interleaved: L,R,L,R,L,R,...). |
sample_rate | read-only | Number of samples per second. |
| | |
typedef struct {
unsigned int bytes_per_sample;
unsigned int sample_rate;
unsigned int channels;
unsigned int master_level;
unsigned int pcm_level;
unsigned int balance;
unsigned int ports;
} XA_OutputControl;
Structure used to pass or retrieve parameters to/from the output module.
bytes_per_sample | Number of bytes per sample (1 for 8 bits, 2 for 16 bits). |
sample_rate | Number of samples per second. |
channels | 1 for mono, 2 for stereo. |
master_level | Master sound volume (value between 0 and 100). |
pcm_level | PCM sound volume (value between 0 and 100). |
balance | Sound balance (value betweem 0 and 100, 0 being full left, 100 begin full right, 50 being even left/right). |
ports | bit flag for the enabled/disabled output ports. |
typedef struct {
int index;
unsigned long flags;
char name[XA_DECODER_QUERY_MAX_NAME_LENGTH];
char description[XA_DECODER_QUERY_MAX_DESCRIPTION_LENGTH];
} XA_OutputModuleQuery;
Structure used to retrieve information about an input or output module and the devices that they handle.
| | |
index | read-only | The module returns in this field the number of devices or device classes that it handles. |
flags | read-write | The caller sets the flags to indicate which information the module should return. Flags can be XA_DECODER_OUTPUT_QUERY_MODULE_NAME to retrieve the module's name and description or XA_DECODER_OUTPUT_QUERY_NB_DEVICES to retrieve the number of devices or device classes handled by the module. |
name | read-only | The module returns in this field its name. |
description | read-only | the module returns in this field a short descriprion of itself. |
| | |
index | read-write | The caller writes in this field the index of the device it whishes to retrieve information about. Device indexes start at 0. |
flags | read-write | The caller sets the flags to indicate which inforamtion about the device should be returned. Flags can be XA_DECODER_OUTPUT_QUERY_DEVICE_NAME to retrieve the device's name and description. |
name | read-only | The module returns the name of the device at index 'index'. |
description | read-only | The module returns a short description of the device at index 'index'. |
typedef struct {
int (*output_module_probe)(const char *name);
int (*output_module_query)(XA_OutputModuleQuery *query,
unsigned long query_mask);
int (*output_new)(void **output, const char *name, int module_id,
struct _XA_DecoderInfo *decoder);
int (*output_delete)(void *output);
int (*output_open)(void *output);
int (*output_close)(void *output);
int (*output_write)(void *output, void *buffer,
unsigned long size, int bytes_per_sample,
unsigned int channels, unsigned int sample_rate);
void* (*output_get_buffer)(void *output, unsigned long size);
int (*output_set_control)(void *output,
XA_OutputControl *control,
unsigned long flags);
int (*output_get_control)(void *output,
XA_OutputControl *control,
unsigned long control_mask);
int (*output_get_status)(void *output,
XA_OutputStatus *status);
long (*output_get_caps)(void *output);
int (*output_send_message)(void *output, int message, void *data);
} XA_OutputModule;
Contains the pointer to the functions (function table) that implement the methods of an output module. See section on Output Modules for more details about each of the methods that can be implemented.
output_module_probe | Method to probe the output module. |
output_module_query | Method to get information about an output module. |
output_new | Method to instantiate a new output object. |
output_delete | Method to delete an output object. |
output_open | Method to open an output object. |
output_close | Method to close an output object. |
output_write | Method to write PCM samples to the output. |
output_get_buffer | Method implemented by the output if it needs to provide its own PCM buffers for the decoding. |
output_set_control | Method to set the parameters of the output. |
output_get_control | Method to get the parameters of the output. |
output_get_status | Method to get the output's status. |
output_get_caps | Method to get the output capabilities. |
output_send_message | Method to send a private message to an output object. |
typedef struct {
signed char left[32];
signed char right[32];
} XA_EqualizerInfo;
Structure used to set or get the equalizer band's values. Each coefficient correspond to one of the 32 frequency bands of a channel. A coefficient is a vlue between -128 and +127. A value of 0 means no change to the frequency bands. Negative values attenuate the frequencies in the band, positive values amplify the frequencies in the band.
left | Array of 32 coefficients for the left channel. |
right | Array of 32 coefficients for the right channel. |
typedef struct {
int frame;
float position;
XA_InputStreamInfo info;
XA_TimeCode timecode;
} XA_StatusInfo;
Structure used to give information about the current status of the decoder.
frame | Current frame number. |
position | Value between 0.0 and 1.0 giving the relative position in the stream. |
info | Pointer to a XA_InputStreamInfo structure containing informations about the current stream. |
timecode | Pointer to a XA_TimeCode structure containing the current timecode. |