alSetParams(3dm)                                              alSetParams(3dm)


NAME
     alSetParams - set the values of audio resource parameters

SYNOPSIS
     #include <dmedia/audio.h>

     int alSetParams(int resource, ALpv *pvs, int npvs)

PARAMETERS
     resource
            expects the resource on which you wish to set parameter values.

     pvs    is an array of ALpv structures, each of which contains a single
            parameter and its desired value.

     npvs   is the number of ALpv items in the array.

DESCRIPTION
     alSetParams sets the values for a list of parameters on a specific audio
     resource.

     Each parameter/value pair is represented by a single ALpv structure:

          typedef struct {
              int     param;          /* parameter */
              ALvalue value;          /* value */
              short   sizeIn;         /* size in -- 1st dimension */
              short   size2In;         /* size out -- 2nd dimension */
              short   sizeOut;        /* size out */
              short   size2Out;        /* size out -- 2nd dimension */
          } ALpv;


     The application should set the param field in each ALpv to indicate which
     parameter is of interest.

     For parameters taking scalar values, the application should fill in the
     appropriate field of the value field. For 32-bit integer values, this is
     the integer field (value.i). For 64-bit integer or fixed-point values,
     this is the long long field (value.ll).

     For parameters requiring non-scalar values, the application must set the
     pointer field of value (value.ptr) to point to the structure, and set
     sizeIn to indicate the size of the structure, in elements.

     alSetParams will set the sizeOut field of each ALpv to indicate how many
     elements of that value it accepted. For valid scalar parameters, this is
     always 1.  For non-scalar parameters, it will set sizeOut to be the
     number of elements accepted. For any parameter, it can also set sizeOut
     to a negative value to indicate an error with that particular
     parameter/value pair. This can be AL_INVALID_PARAM, indicating that the
     given parameter was unrecognized by the given resource, or


     AL_INVALID_VALUE, indicating that the parameter was recognized but that
     the value was unacceptable.

     See the alParams(3dm) man page for more information on the semantics of
     particular parameters.

EXAMPLE
     The following example takes the name of a device and a rate in Hz as a
     command-line argument, and sets the rate on that device. Note that the
     device can be an input or output device (however, on a digital input
     device, the rate will be ignored, since such devices get their sample
     rate externally).

          #include <audio.h>
          #include <math.h>        /* for atof */

          main(int argc, char **argv)
          {
              int rv;
              double rate;
              ALpv x[2];

              if (argc != 3) {
                  printf("usage: %s <device> <rate>\n",argv[0]);
                  exit(-1);
              }

              /*
               * Get an audio resource of a particular type (AL_DEVICE_TYPE)
               * from the name given on the command line.
               */
              rv = alGetResourceByName(AL_SYSTEM,argv[1],AL_DEVICE_TYPE);
              if (!rv) {
                   printf("invalid device\n");
                   exit(-1);
              }

              rate = atof(argv[2]);

              /*
               * Attempt to set a crystal-based 48000 Hz sample-rate on the
               * given device.
               */
              x[0].param = AL_MASTER_CLOCK;
              x[0].value.i = AL_CRYSTAL_MCLK_TYPE;
              x[1].param = AL_RATE;
              x[1].value.ll = alDoubleToFixed(rate);
              if (alSetParams(rv,x, 2)<0) {
                   printf("setparams failed: %s\n",alGetErrorString(oserror()));
              }
              if (x[1].sizeOut < 0) {
               printf("rate was invalid\n");


              }
          }


DIAGNOSTICS
     alSetParams returns the number of recognized parameters in the given PV
     list. It can also return a negative value, and set an error code, to
     indicate errors with the entire alSetParams call. In this case, the error
     code retrieved by oserror(3C) will be one of:

     AL_BAD_PVBUFFER
          pvs is invalid.

     AL_BAD_BUFFERLENGTH
          npvs is patently wrong (e.g. negative).

     AL_BAD_DEVICE_ACCESS
          The audio system is inaccessible, either because it is not installed
          on the system, or because it is incorrectly configured.

     AL_BAD_RESOURCE
          The given resource resource does not exist.

SEE ALSO
     alParams(3dm), alGetParams(3dm), alGetParamInfo(3dm), oserror(3C)


                                                                        Page 3