Xaudio Data Structures


Structure Index


XA_DecoderInfo

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.
nameread-onlyName of the decoder (currently ignored).
inputread-onlyPointer to a read-only XA_InputInfo structure that contains the information about the current input object (if any has been instantiated).
outputread-onlyPointer to a read-only XA_OutputInfo structure that contains the information about the current output object (if any has been instantiated).
codecread-onlyPointer to a read-only XA_CodecInfo structure that contains the information about the current codec object (if any has been instantiated).
modulesread-onlyPointer to a read-only XA_ModulesInfo structure that contains the information about the currently registered input and output modules.
statusread-onlyPointer to a read-only XA_StatusInfo structure that contains the information about the current status of the decoder.
output_bufferread-onlyPointer to a read-only XA_OutputBufferInfo structure that contains information about the output buffer (audio samples) that has just been decoded.
notification_clientread-writeRead-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.
callbacksread-onlyA read-only fucntion table that provides callback functions to be used by input/output modules and input/output filters.
hiddenprivatePointer 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.

XA_InputInfo

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.
stateread-onlyCurrent 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).
positionread-onlyCurrent 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).
sizeread-onlySize (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).
deviceprivatePointer 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.
moduleread-onlyFunction 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.

XA_OutputInfo

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.
stateread-onlyCurrent 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).
capsread-onlyBitmask 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).
channelsread-writeChannel 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).
deviceprivatepointer 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.
moduleread-onlyFunction 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.

XA_InputModule

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_probeMethod to probe the input module.
input_module_queryMethod to get information about an input module.
input_newMethod to instantiate a new input object.
input_deleteMethod to delete an input object.
input_openMethod to open an input object.
input_closeMethod to close an input object.
input_readMethod to read bytes from an input object.
input_seekMethod to seek to an specific location in an input object's stream.
input_get_capsMethod to get the capabilities of an input object.
input_get_sizeMethod to get the the of the stream of an input object.
input_send_messageMethod to send a private message to an input object.

XA_InputModuleQuery

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.
indexread-writeSpecifies 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.
flagsread-writeSpecifies 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.
nameread-onlyString that contains the name of an input module or input device.
descriptionread-onlyString that contains the short description of an input module or input device.

XA_TimeCode

typedef struct {
    unsigned int h;
    unsigned int m;
    unsigned int s;
    unsigned int f;
} XA_TimeCode;
Structure used to describe a timecode.
hHours.
mMinutes.
sSeconds.
fFractions (100th of a second).

XA_AbsoluteTime

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.

XA_InputStreamInfo

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.
levelMPEG syntax level (1 for MPEG1, 2 for MPEG2, 0 for MPEG2.5).
layerMPEG layer (1, 2 or 3).
bitrateMPEG bitrate (in bits per second).
frequencyMPEG sampling frequency (in Hz).
modeMPEG mode (0 for stereo, 1 for joint-stereo, 2 for dual-channel, 3 for mono).
durationestimated stream duration (in milliseconds).

XA_OutputBufferInfo

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).
changedread-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_samplesread-onlypointer to the memory buffer where the PCM samples are stored.
sizeread-only Number of bytes in the PCM buffer.
bytes_per_sampleread-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).
channelsread-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_rateread-only Number of samples per second.

XA_OutputControl

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.

XA_OutputModuleQuery

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.
indexread-only The module returns in this field the number of devices or device classes that it handles.
flagsread-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.
nameread-only The module returns in this field its name.
descriptionread-only the module returns in this field a short descriprion of itself.
indexread-write The caller writes in this field the index of the device it whishes to retrieve information about. Device indexes start at 0.
flagsread-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.
nameread-only The module returns the name of the device at index 'index'.
descriptionread-only The module returns a short description of the device at index 'index'.

XA_OutputModule

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.

XA_EqualizerInfo

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.

XA_StatusInfo

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.