alGetParams(3dm)alGetParams(3dm)NAMEalGetParams - get the values of audio resource parameters
SYNOPSIS
#include <dmedia/audio.h>
int alGetParams(int resource, ALpv *pvs, int npvs)
PARAMETERS
resource
expects the resource from which you wish to get parameter values.
pvs is an array of ALpv structures, each of which contains a single
parameter and will contain the associated value upon return from
alGetParams.
npvs is the number of ALpv items in the array.
DESCRIPTIONalGetParams acquires the current values for a set of parameters from 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 scalar parameters, this is sufficient; alGetParams will fill in the
corresponding value field.
For non-scalar parameters, the application is responsible for allocating
the memory required to hold the value. In addition to setting param, the
application must set the pointer field of value (value.ptr) to point to
the allocated buffer, and set sizeIn to indicate the size of the buffer,
in elements. alGetParams will write the value to the given buffer,
filling in at most sizeIn elements.
alGetParams will set the sizeOut field of each ALpv to indicate how many
elements it returned. For valid scalar parameters, this is always 1. For
non-scalar parameters, it return the number of elements available, even
if greater than sizeIn. For any parameter, it can also set sizeOut to a
negative value to indicate an error with that particular parameter.
Page 1
alGetParams(3dm)alGetParams(3dm)alGetParams currently supports only one negative sizeOut value:
AL_INVALID_PARAM, which indicates that the given parameter was
unrecognized by the given resource.
See the alParams(3dm) man page for more information on the semantics of
particular parameters.
EXAMPLE
The following code fragment gets the value of the sample rate, the gain,
and the name of the default audio input device.
int i;
ALpv pvs[3];
char name[32];
ALfixed gain[8];
pvs[0].param = AL_RATE; /* a scalar parameter */
pvs[1].param = AL_GAIN; /* a vector parameter */
pvs[1].value.ptr = gain; /* the vector we've allocated */
pvs[1].sizeIn = 8; /* the number of elements in gain */
pvs[2].param = AL_NAME; /* a string parameter */
pvs[2].value.ptr = name; /* the string we've allocated */
pvs[2].sizeIn = 32; /* the array size, in characters,
including space for NULL */
/*
* Now we ask the default input device for its sample rate, name,
* and current input gain. Note that there's nothing input-specific
* about this code. To use a default output device, we simply supply
* AL_DEFAULT_OUTPUT as the resource to alGetParams.
*/
if (alGetParams(AL_DEFAULT_INPUT, pvs, 3) < 0) {
printf("alGetParams failed: %s\n", alGetErrorString(oserror()));
}
printf("name is %s, rate is %lf\n",
name, alFixedToDouble(pvs[0].value.ll));
for (i = 0; i < pvs[1].sizeOut; i++) {
printf("gain[%d] = %lf dB\n", alFixedToDouble(gain[i]));
}
DIAGNOSTICSalGetParams 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 alGetParams call. In this case, the error
code retrieved by oserror(3C) will be one of:
Page 2
alGetParams(3dm)alGetParams(3dm)
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), alSetParams(3dm), alGetParamInfo(3dm), oserror(3C)
Page 3
