ALwritesamps(3dm)

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

DESCRIPTION
     ALwritesamps 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.
     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.
     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 ALSO
     ALopenport(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)