alSetParams(3dm)alSetParams(3dm)NAMEalSetParams - 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.
DESCRIPTIONalSetParams 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
Page 1
alSetParams(3dm)alSetParams(3dm)
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");
Page 2
alSetParams(3dm)alSetParams(3dm)
}
}
DIAGNOSTICSalSetParams 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 ALSOalParams(3dm), alGetParams(3dm), alGetParamInfo(3dm), oserror(3C)
Page 3
