ALwritesamps(3dm)ALwritesamps(3dm)NAMEALwritesamps - (obsolete) write samples to an audio port
SYNOPSIS
#include <dmedia/audio.h>
int ALwritesamps(ALport port, void *samples, long samplecount)
PARAMETER
port expects the ALport structure for the audio port to which
you want to write samples. This structure is the returned
value of the ALopenport(3dm) call.
samples expects a pointer to a buffer from which you want to
transfer the sound samples into the audio port.
samplecount expects the number of samples that you want to write to the
port.
DESCRIPTIONALwritesamps is obsolete and is provided for backward compatibility. The
preferred function is alWriteFrames(3dm), which uses units of sample
frames.
ALwritesamps(3dm) writes samples to the audio port buffer. If there is
not sufficient buffer space in the audio port, ALwritesamps(3dm) will
block until enough space becomes available for the transfer to complete.
Normally, ALwritesamps(3dm) will return before the sound has finished
playing.
To delay until the sound has finished playing, keep calling
ALgetfilled(3dm) and sginap(2) until ALgetfilled(3dm) returns 0, or set
the fillpoint to the queuesize minus one and call select(2) or poll(2).
By calling ALgetfillable(3dm) you can determine how many samples will fit
into the internal buffer without blocking.
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 which 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. Only the
least significant 24 bits of the long are used by the audio hardware.
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.
Page 1
ALwritesamps(3dm)ALwritesamps(3dm)
When you send samples to a stereo audio port, ALwritesamps(3dm) sends the
odd numbered samples to the right channel and sends the even numbered
samples to the left channel. This notion of odd and even includes all the
samples that have ever been sent to this port, so channel swapping
confusion can be avoided by always sending an even number of samples to a
stereo audio port (i.e. samplecount is an integer multiple of the frame
size, in this case 2).
In the case of a 4-channel port, you should write only an integer number
of frames of data (viz., samplecount should be a multiple of 4) to a
port. If a non-integer number of frames is written to a port,
ALwritesamps(3dm) will not transfer the samples and will return an error.
Though 4-channel audio ports can be opened successfully for all IRIS
workstations with high-quality audio, not all hardware can support 4
line-level electrical connections (e.g. Indigo). In the case that the
hardware is unable to support these connections, ALwritesamps(3dm) will
mix the two pairs of samples to a stereo signal.
Consider the following situation: 4 samples (L1, R1, L2, R2) are written
to a 4-channel port on a machine without the 4-channel capability. In
this case, the 4 samples will be summed to 2 samples in the following
manner: (L1, R1, L2, R2) becomes (L1+L2, R1+R2). These sums are then
limited to avoid overflow and sent to the audio hardware as a stereo
pair. Thus, no information is lost when using a 4-channel port on a
machine without the 4-channel capability.
In the case that the hardware is capable of 4 line-level output signals
ALwritesamps(3dm) will send the samples (L1, R1, L2, R2) to the output
connections in the following manner: sample pair (L1, R1) will be sent to
the regular line-level output; and sample pair (L2, R2) will be sent to
the headphone output (which is electrically configured to line-level by
ALsetparams(3dm) using the AL_CHANNEL_MODE/AL_4CHANNEL parameter/value
pair).
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).
ALwritesamps(3dm) can fail for the 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.
Page 2
ALwritesamps(3dm)ALwritesamps(3dm)
In order to achieve the best possible performance, ALwritesamps(3dm) does
not verify that port or samples are valid. You should make certain these
values are valid before passing them as arguments to ALwritesamps(3dm).
DIAGNOSTICS
Upon successful completion, ALwritesamps(3dm) returns 0. Otherwise
ALwritesamps(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), ALgetchannels(3dm), ALgetwidth(3dm),
ALsetfillpoint(3dm), ALsetsampfmt(3dm), ALsetfloatmax(3dm),
ALgetminmax(3dm), sginap(2), oserror(3C)
Page 3
