ALreadsamps(3dm)

NAME
     ALreadsamps - (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.

DESCRIPTION
     ALreadsamps 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.
     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).

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 ALSO
     ALopenport(3dm), ALgetfillable(3dm), ALgetfilled(3dm),
     ALsetchannels(3dm), ALsetwidth(3dm), ALwritesamps(3dm), ALsetconfig(3dm),
     ALsetqueuesize(3dm), ALsetsampfmt(3dm), ALsetfloatmax(3dm),
     ALgetminmax(3dm), oserror(3C)