XaudioSampleBuffer

Section: AUDIO Extension (3)
Updated: 2007-08-30
Index Return to Main Contents

NAME

XaudioCreateSampleBuffer, XaudioFreeSampleBuffer, XaudioSampleBufferSetBase, XaudioSampleBufferShiftBase, XaudioPutSamples, XaudioGetSamples, XaudioSampleBufferGetInfo - Server-side sample buffers

SYNOPSIS

#include <X11/extensions/Xaudio.h>

XaudioSampleBuffer XaudioCreateSampleBuffer(Display *display, unsigned int size);

void XaudioFreeSampleBuffer(Display *display , XaudioSampleBuffer buffer);

void XaudioSampleBufferSetBase(Display *display, XaudioSampleBuffer buffer, int offset);

void XaudioSampleBufferShiftBase(Display *display, XaudioSampleBuffer buffer, int rel_offset);

void XaudioPutSamples(Display *display, XaudioSampleBuffer buffer, unsigned int index, const void *data, unsigned int nsamples, unsigned int format);

void XaudioGetSamples(Display *display, XaudioSampleBuffer buffer, unsigned int index, void *data, unsigned int nsamples, unsigned int format);

void XaudioSampleBufferGetInfo(Display *display, XaudioSampleBuffer buffer, unsigned int *size, unsigned int *base);

ARGUMENTS

display: Specifies the connection to the X server.
size: Number of samples stored in the buffer.
buffer: Sample buffer to operate on.
index: Absolute sample index into sample buffer.
data: Pointer to sample data in client memory.
nsamples: Number of samples to transfer.
format: Format of the sample data.
offset: Index into sample buffer relative to current base index.
base: Base index of sample buffer.

DESCRIPTION

The XaudioCreateSampleBuffer function creates a server-side sample buffer that stores size samples. Each sample represents a single real value; the exact range of representable values is unspecified, but implementations must support at least a range of -127 to +127, at least 16 bits of precision over the whole range and at least 16 bits of precision over the range [-1;+1] of normalized sample values. If samples are intended to be output through a DAC they should be normalized, denormalized values are only useful as intermediate values in arithmetic operations.

Each sample can individually be addressed through its index. A sample buffer always stores size sample values with indices base, base+1, ... , base+size-1, where initially base=0. Write operations to any of these indices will modify the corresponding sample value, read operations will return the previously written value. Write operations to an index outside of this range will be silently discarded, read operations will yield 0. The base sample index of a sample buffer can be modified through the XaudioSampleBufferSetBase and XaudioSampleBufferShiftBase functions (which set a new absolute value or shift it with respect to its old base value, respectively). Any samples inside the intersection of old and new sample index ranges will be unaffected, all other samples will be set to zero.

The XaudioPutSamples function allows to upload samples from the client application into a server-side sample buffer. The format parameter indicates how data should be interpreted:

SAMPLE_FORMAT_SIGNED_8: Signed 8-bit data; the range [-127;127] is mapped to the range [-1;1]
SAMPLE_FORMAT_SIGNED_16: Signed 16-bit data; the range [-32767;32767] is mapped to the range [-1;1]
SAMPLE_FORMAT_FIXED_16_16: Signed 32-bit data; the range [-65536;65536] is mapped to the range [-1;1]; this format allows to represent sample values outside the range [-1;1]
SAMPLE_FORMAT_IEEE754_SINGLE: Single precision floating point data

The new values will replace the previous values of the samples with indices index, index+1, ... index+nsamples-1.

Conversely, XaudioGetSamples allows to transfer sample values stored in a server-side buffer to the client. If sample values cannot be represented in the desired format they are clamped to the maximum range supported by the format.

The XaudioSampleBufferGetInfo function returns the number of samples stored as well as the current base index.