alWriteFrames(3dm)                                          alWriteFrames(3dm)


NAME
     alWriteFrames - write interleaved sample frames to an audio port

SYNOPSIS
     #include <dmedia/audio.h>

     int alWriteFrames(const ALport port, void *samples, const int framecount)

PARAMETER
     port         is the audio output port to which you want to write samples.
                  This is the returned value of an alOpenPort(3dm) call.

     samples      is the buffer containing the samples.

     framecount   is the number of sample frames that you want to write to the
                  audio port.

DESCRIPTION
     alWriteFrames transfers data to an audio port from the samples buffer.
     alWriteFrames blocks until framecount sample frames have been written to
     the port.  If you do not wish to block, make sure that framecount is less
     than the return value of alGetFillable(3dm).

     The format of the audio data expected by alWriteFrames depends upon the
     configuration of the port. Each sample can be an 8-, 16-, or 32-bit
     integer, or a single- or double-precision floating-point value or a block
     of subcode data; see alSetSampFmt(3dm), alSetFloatMax(3dm) and
     alSetWidth(3dm) for a description of how these formats work. By default,
     the sample format is 16-bit integer (short).

     Within each sample frame, alWriteFrames expects interleaved data.  The
     number of samples per sample frame varies according to the value
     specified by alSetChannels(3dm). By default, the port accepts stereo data
     (2 samples per frame).

     Note that since an audio port contains an internal queue, samples written
     to the port will not immediately come out the associated audio device or
     devices. alGetFilled(3dm) will indicate how many samples are currently in
     this queue. Also, alGetFrameTime(3dm) and alGetFrameNumber(3dm) provide
     facilities for precise synchronization of audio and other media.

     In order to achieve the best possible performance, alWriteFrames does not
     attempt to verify that port or samples are valid. You should make certain
     these values are valid before passing them as arguments to alWriteFrames.

EXAMPLE
     The following code fragment opens an audio output port and writes a bit
     of (zero) audio data to it.


          ALport p;
          short buf[10000];   /* 5000 stereo frames */

          /* open a port with the default configuration */
          p = alOpenPort("alWriteFrames example","w",0);

          if (!p) {
              printf("port open failed:%s\n", alGetErrorString(oserror()));
              exit(-1);
          }

          /*
           * Fill our buffer. Really we'd want to do something more interesting
           * than generating silence.
           */
          bzero(buf, 10000*sizeof(short));

          alWriteFrames(p, buf, 5000);       /* write 5000 stereo frames */


DIAGNOSTICS
     alWriteFrames always returns 0.

NOTES
     On output, the data from all ports on the system writing to a particular
     output device will be mixed together, except in the case of subcode data.
     Because subcode data is treated as inherently logical information, no
     amount mathematics can be applied to perform operations such as mixing.

SEE ALSO
     alOpenPort(3dm), alGetFillable(3dm), alGetFilled(3dm),
     alSetChannels(3dm), alSetWidth(3dm), alReadFrames(3dm),
     alZeroFrames(3dm), alSetConfig(3dm), alSetQueueSize(3dm),
     alSetSampFmt(3dm), alSetFloatMax(3dm)


                                                                        Page 2