alReadBuffers(3dm)alReadBuffers(3dm)NAMEalReadBuffers - read flexibly interleaved or non-interleaved audio data
from an audio port
SYNOPSIS
#include <dmedia/audio.h>
int alReadBuffers(const ALport port, void **bufs, int *strides, const int framecount)
PARAMETER
port is the audio input port from which you want to read samples.
This is the returned value of an alOpenPort(3dm) call.
bufs is an array of pointers to sample buffers, each element of
which corresponds to a single channel of audio input.
strides is an array of integers, one corresponding to each input
channel. Each element indicates the number of interleaved
channels you desire in the sample buffer for that channel.
framecount is the number of sample frames that you want to read from
the audio port.
DESCRIPTIONalReadBuffers transfers data from an audio port to a set of buffers, or
to different locations in a single buffer. alReadBuffers allows the
application to specify how the data is to be interleaved.
bufs is an array of pointers to sample buffers. Each element of bufs
corresponds to one input channel. If the element is 0, that channel will
be ignored; this allows an application to only read audio from the
channels of interest.
The sample buffers can be arbitrarily interleaved; the strides parameter
indicates the number of channels in each target sample buffer. For
example, if strides[n] is 1, then bufs[n] will be mono; if strides[n] is
2, then bufs[n] will be interleaved stereo, and alReadBuffers will write
to every other sample in that buffer. The elements of strides can have
any value. If strides is 0, all the sample buffers will be mono, and
alReadBuffers does non-interleaved input.
There must be exactly as many elements in bufs and strides as the number
of channels specified for the port with alSetChannels(3dm).
alReadBuffers blocks until framecount sample frames have been read from
the port. If you do not wish to block, make sure that framecount is less
than the return value of alGetFilled(3dm).
The target format of each sample depends upon the configuration of the
audio port. Each sample can be an 8-, 16-, or 32-bit integer, or a
single- or double-precision floating-point value or subcode data; see
alSetSampFmt(3dm) and alSetWidth(3dm) for a description of how these
Page 1
alReadBuffers(3dm)alReadBuffers(3dm)
formats work. By default, the sample format is 16-bit integer (short).
Note that since an audio port contains an internal queue, samples read
from the port may have come in some time ago. For precise synchronization
of audio and other media, use alGetFrameTime(3dm) and
alGetFrameNumber(3dm) to determine when samples arrived.
In order to achieve the best possible performance, alReadBuffers does not
attempt to verify that port, bufs, or strides are valid. You should make
certain these values are valid before passing them as arguments to
alReadBuffers.
EXAMPLES
The following code fragment opens an 8-channel audio input port and reads
8 separate mono buffers from it. For more examples, see the man page for
alWriteBuffers(3dm) and the code in /usr/share/src/dmedia/audio.
ALport p;
short buf[8][1000];
void *bufs[8];
int i,j;
ALconfig c;
c = alNewConfig();
if (!c) {
printf("config create failed:%s\n", alGetErrorString(oserror()));
exit(-1);
}
alSetChannels(c, 8);
/* open a port with our configuration */
p = alOpenPort("alReadBuffers example","r",c);
if (!p) {
printf("port open failed:%s\n", alGetErrorString(oserror()));
exit(-1);
}
/*
* set up bufs
*/
for (i = 0; i < 8; i++) {
bufs[i] = buf[i];
}
alReadBuffers(p, bufs, 0, 1000); /* read 1000 8-channel frames */
}
Page 2
alReadBuffers(3dm)alReadBuffers(3dm)DIAGNOSTICSalReadBuffers always returns 0.
NOTE
This function was introduced via patch to IRIX 6.3 and 6.4, and is
present by default in later OS releases. You should ensure that the
target system will have the functionality before calling this function;
otherwise, your program will crash when you attempt to make the function
call. To determine if the feature is present, check the value of
AL_VERSION on the system resource. The parameter must be present and its
value must be at least 6.
pv.param = AL_VERSION;
alGetParams(AL_SYSTEM,&pv,1);
if (pv.sizeOut < 0 || pv.value.i < 6) {
/* feature not present */
}
SEE ALSOalOpenPort(3dm), alGetFillable(3dm), alGetFilled(3dm),
alSetChannels(3dm), alSetWidth(3dm), alReadFrames(3dm),
alZeroFrames(3dm), alSetConfig(3dm), alSetQueueSize(3dm),
alSetSampFmt(3dm), alSetFloatMax(3dm)
Page 3
