alReadBuffers(3dm)                                          alReadBuffers(3dm)


NAME
     alReadBuffers - read flexibly interleaved or non-interleaved audio data
     from an audio port

SYNOPSIS
     #include <dmedia/audio.h>

     int alReadBuffers(const ALport port, void **bufs, int *strides, const int framecount)

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

     bufs         is an array of pointers to sample buffers, each element of
                  which corresponds to a single channel of audio input.

     strides      is an array of integers, one corresponding to each input
                  channel. Each element indicates the number of interleaved
                  channels you desire in the sample buffer for that channel.

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

DESCRIPTION
     alReadBuffers transfers data from an audio port to a set of buffers, or
     to different locations in a single buffer. alReadBuffers allows the
     application to specify how the data is to be interleaved.

     bufs is an array of pointers to sample buffers. Each element of bufs
     corresponds to one input channel. If the element is 0, that channel will
     be ignored; this allows an application to only read audio from the
     channels of interest.

     The sample buffers can be arbitrarily interleaved; the strides parameter
     indicates the number of channels in each target sample buffer. For
     example, if strides[n] is 1, then bufs[n] will be mono; if strides[n] is
     2, then bufs[n] will be interleaved stereo, and alReadBuffers will write
     to every other sample in that buffer.  The elements of strides can have
     any value. If strides is 0, all the sample buffers will be mono, and
     alReadBuffers does non-interleaved input.

     There must be exactly as many elements in bufs and strides as the number
     of channels specified for the port with alSetChannels(3dm).

     alReadBuffers blocks until framecount sample frames have been read from
     the port.  If you do not wish to block, make sure that framecount is less
     than the return value of alGetFilled(3dm).

     The target format of each sample depends upon the configuration of the
     audio port. Each sample can be an 8-, 16-, or 32-bit integer, or a
     single- or double-precision floating-point value or subcode data; see
     alSetSampFmt(3dm) and alSetWidth(3dm) for a description of how these


     formats work. By default, the sample format is 16-bit integer (short).

     Note that since an audio port contains an internal queue, samples read
     from the port may have come in some time ago. For precise synchronization
     of audio and other media, use alGetFrameTime(3dm) and
     alGetFrameNumber(3dm) to determine when samples arrived.

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

EXAMPLES
     The following code fragment opens an 8-channel audio input port and reads
     8 separate mono buffers from it. For more examples, see the man page for
     alWriteBuffers(3dm) and the code in /usr/share/src/dmedia/audio.

          ALport p;
          short buf[8][1000];
          void *bufs[8];
          int i,j;
          ALconfig c;

          c = alNewConfig();
          if (!c) {
              printf("config create failed:%s\n", alGetErrorString(oserror()));
              exit(-1);
          }

          alSetChannels(c, 8);

          /* open a port with our configuration */
          p = alOpenPort("alReadBuffers example","r",c);

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

          /*
           * set up bufs
           */
          for (i = 0; i < 8; i++) {
                  bufs[i] = buf[i];
          }

          alReadBuffers(p, bufs, 0, 1000);          /* read 1000 8-channel frames */
          }


DIAGNOSTICS
     alReadBuffers always returns 0.

NOTE
     This function was introduced via patch to IRIX 6.3 and 6.4, and is
     present by default in later OS releases.  You should ensure that the
     target system will have the functionality before calling this function;
     otherwise, your program will crash when you attempt to make the function
     call. To determine if the feature is present, check the value of
     AL_VERSION on the system resource. The parameter must be present and its
     value must be at least 6.

                  pv.param = AL_VERSION;
                  alGetParams(AL_SYSTEM,&pv,1);
                  if (pv.sizeOut < 0 || pv.value.i < 6) {
                      /* feature not present */
                  }


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 3