audio_render_open :: Quanser C Functions

navigation bar

audio_render_open

Opens an audio render device, such as a speaker.

Description

The audio_render_open function opens an audio render device, such as a speaker. The handle to the render session returned by this function is used by the other functions in the Multimedia API to refer to the session. This handle must be closed using the audio_render_close function when the session is no longer in use.

Prototype

t_error
audio_render_open(const char * url, t_double sample_rate, t_uint num_channels, t_audio_format format, t_uint buffer_size, t_audio_render * render);

Parameters

const char * url

A string identifying the audio render device to be opened, as a URL. For a speaker device, the URL takes the form:

audio://localhost:<port>

where <port> is the number of the render device. For instance, to open first speaker enumerated on the system, the URL would be:

audio://localhost:0

t_double sample_rate

A real number specifying the sample rate at which audio output will be rendered in Hertz. A value such as 44100 Hz or 48000 Hz is typical.

t_uint num_channels

The number of audio channels to render. Typical values are 1 or 2.

t_audio_format format

The format in which the audio data to be rendered will be provided. Valid audio formats are listed in the table below. The recommended format is AUDIO_FORMAT_FLOAT.

Format	Description
AUDIO_FORMAT_PCM	Audio data is encoded as signed 16-bit values (`t_int16`), where each value is the quantized amplitude of the time-domain signal to be produced at the specified sample rate.
AUDIO_FORMAT_FLOAT	Audio data is encoded as signed single-precision floating-point values (`t_single`), where each value is the quantized amplitude of the time-domain signal to be produced at the specified sample rate.

t_uint buffer_size

The size of the audio buffer in samples (where one sample includes all channels). A buffer large enough for at least 1 second of audio is recommended i.e. sample_rate.

t_audio_render * render

The address of a t_audio_render variable in which the handle to the render session will be stored. This handle is then passed to the other audio render functions to identify the render session.

Return value

The return value is 0 if the audio render session is opened successfully. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

Requirements

Include Files	Libraries
quanser_audio.h	quanser_media.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_audio_render render;
t_error result = audio_render_open("audio://localhost:3", 44100, NUM_CHANNELS, AUDIO_FORMAT_FLOAT, 44100, &render);
if (result >= 0) {
    ...
    audio_render_close(render);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open audio render session. %s (error %d)\n"), message, -result);
}