ALreadsamps(3dm)ALreadsamps(3dm)NAMEALreadsamps - (obsolete) read samples from an audio port
SYNOPSIS
#include <dmedia/audio.h>
int ALreadsamps(const ALport port, void *samples, const long samplecount)
PARAMETER
port expects the ALport structure for the audio port from which
you want to read samples. This structure is the returned
value of the ALopenport(3dm) call.
samples expects a pointer to a buffer into which you want to
transfer the samples read from the audio port.
samplecount expects the number of samples that you want to read from
the audio port.
DESCRIPTIONALreadsamps is obsolete and is provided for backward compatibility. The
preferred function is alReadFrames(3dm), which uses units of sample
frames.
ALreadsamps(3dm) transfers data from the internal buffer of an audio port
to the samples buffer. ALreadsamps(3dm) blocks until samplecount samples
have been transferred to the samples buffer. To prevent blocking, make
sure that samplecount is less than the return value of ALgetfilled(3dm).
The samples buffer is interpreted differently depending on the current
configuration of the port. In particular, the width setting specified by
ALsetwidth(3dm) determines which of the bits in the buffer make up the
sound samples. Samples of width AL_SAMPLE_8 (char) and AL_SAMPLE_16
(short) are treated as normal signed numbers. The samples will contain
the most significant 8 or 16 bits of the audio amplitude measurement,
respectively. Samples of width AL_SAMPLE_24 (long) are treated as signed
24 bit numbers packed into the low 24 bits sign extended to fill a long.
They may be treated as longs in the range -8388608 to 8388607.
In the case that the port is configured to use floating point or double
precision floating point samples (see ALsetsampfmt(3dm)), the width
setting is ignored, and the samples are treated as floating point or
double precision floating point, respectively.
The channels setting you specified for ALsetchannels(3dm) determines from
which channels the samples will come. For ports set to AL_MONO the left
and right channels are averaged and returned as a single sample. For
AL_STEREO, the even samples are from the left channel and the odd samples
are from the right channel. This parity is from the time the port is
opened, so if you were to read an odd number of samples from a AL_STEREO
port, then on the subsequent read, the even samples would be from the
right channel and the odd samples would be from the left channel.
Page 1
ALreadsamps(3dm)ALreadsamps(3dm)
For ports created as AL_4CHANNEL, you should read an integer number of
frames (a frame is 4 samples for 4-channel ports). If the number of
samples to be read is not an integer multiple of the frame size,
ALreadsamps(3dm) will not transfer any samples from the port to the
sample buffer and will return an error.
Though 4-channel ports are supported on all systems with high-quality
audio, not all hardware can support 4 line-level electrical connections.
In this case ALreadsamps(3dm) will provide 4 samples per frame, but the
second pair of samples will be 0.
For instance, suppose a 4-channel port is opened on a machine with stereo
input only (e.g. Indigo). ALreadsamps(3dm) will provide 4 samples for
every sample interval, but the second pair of samples will be 0. Thus,
for every frame you will get (L1, R1, 0, 0) where `L1' and `R1' are valid
audio samples. ALreadsamps(3dm) will behave in the same way for data
streams that are not defined for 4-channels (viz., digital input). In
this case, ALreadsamps(3dm) will also place 0 in the second pair of
samples.
For a system that is properly configured with 4-channel connections,
ALreadsamps(3dm) provides 4 samples for every sampling interval (L1, R1,
L2, R2). The first sample pair (L1, R1) will be associated with the
regular line input of the machine. The second sample pair (L2, R2) is
associated with the signals on the microphone input (see ALsetparams(3dm)
for documentation on the configuration of the second set of analog
inputs).
You can determine whether a system has the 4-channel capability with
ALgetminmax(3dm). Once you have determined that a system does possess
this capability, you can configure the system for 4-channels with
ALsetparams(3dm). Note that hardware with the 4-channel capability must
be configured to have the proper 4-channel line-level connections. By
default, all hardware will behave as a stereo device.
If you want to change the sample format, the maximum value for floating
point/double precision data, or sample size settings, you can call
ALsetsampfmt(3dm), ALsetfloatmax(3dm), and ALsetwidth(3dm) followed by a
call to ALsetconfig(3dm).
ALreadsamps(3dm) can fail for following reason:
AL_BAD_TRANSFER_SIZE samplecount is not a multiple of the frame size
set by ALsetchannels(3dm). This error pertains to
4-channel ports only.
In order to achieve the best possible performance, ALreadsamps(3dm) does
not verify that port or samples are valid. You should make certain these
values are valid before passing them as arguments to ALreadsamps(3dm).
Page 2
ALreadsamps(3dm)ALreadsamps(3dm)DIAGNOSTICS
Upon successful completion, ALreadsamps(3dm) returns 0. Otherwise
ALreadsamps(3dm) returns -1 and sets an error number which can be
retrieved with oserror(3C).
SEE ALSOALopenport(3dm), ALgetfillable(3dm), ALgetfilled(3dm),
ALsetchannels(3dm), ALsetwidth(3dm), ALwritesamps(3dm), ALsetconfig(3dm),
ALsetqueuesize(3dm), ALsetsampfmt(3dm), ALsetfloatmax(3dm),
ALgetminmax(3dm), oserror(3C)
Page 3
