alGetParamInfo(3dm)alGetParamInfo(3dm)NAMEalGetParamInfo - get information about a parameter on a particular audio
resource
SYNOPSIS
#include <dmedia/audio.h>
int alGetParamInfo(int res, int param, ALparamInfo *pinfo);
PARAMETERS
res is the audio resource (see alResources(3dm)) to which the given
parameter applies.
param
is the parameter about which you desire information.
pinfo
is a pointer to an ALparamInfo structure allocated by the caller.
DESCRIPTIONalGetParamInfo returns information about the values supported for the
given parameter param on the given audio resource res. The information
is returned in an ALparamInfo structure:
typedef struct {
int resource; /* the resource */
int param; /* the parameter */
int valueType; /* type of the whole value (scalar,vector,set...) */
int maxElems; /* maximum number of elements */
int maxElems2; /* maximum number of elements (2nd dimension) */
int elementType; /* type of each element (enum, fixed, resource ...) */
char name[32]; /* name of the parameter */
ALvalue initial; /* initial value */
ALvalue min; /* maximum value (range parameters only) */
ALvalue max; /* maximum value (range parameters only) */
ALvalue minDelta; /* maximum delta between values (range parameters only) */
ALvalue maxDelta; /* maximum delta between values (range parameters only) */
int specialVals; /* special values not between min & max (range parms only) */
int operations; /* supported operations */
} ALparamInfo;
The fields are defined as follows:
resource is the audio resource to which the parameter applies. Param is
the parameter, as passed in to alGetParamInfo.
valueType is the aggregate type of the value supported for the parameter.
It indicates whether or not the value consists of a single element
(AL_SCALAR_VAL) or multiple elements. If there are multiple elements, it
indicates the relationship between the elements: are they an ordered list
Page 1
alGetParamInfo(3dm)alGetParamInfo(3dm)
(AL_VECTOR_VAL and AL_STRING_VAL), an unordered set (AL_SET_VAL), or a
two-dimensional matrix (AL_MATRIX_VAL)?
maxElems indicates the maximum number of elements that the value can have
on this particular resource. For scalar values, this is always 1. For
two-dimensional values, the field maxElems2 is also used, indicating the
maximum value for the second dimension.
elementType indicates the type of each element of the value. The
supported types are: AL_NO_ELEM, indicating that the parameter has no
associated value; AL_INT32_ELEM and AL_INT64_ELEM, for 32- and 64-bit
integer values, respectively; AL_FIXED_ELEM, for 64-bit fixed-point
values; AL_CHAR_ELEM, for 8-bit characters; AL_RESOURCE_ELEM, for values
which are audio resources; and AL_ENUM_ELEM, for values which are
enumerated 32-bit integer values.
Element types are divided into two classes: range types and enumerated
types. The only two enumerated element types are AL_ENUM_ELEM and
AL_RESOURCE_ELEM; all the others are considered range types. For
enumerated types, an application can get the entire set of possible
values via the alQueryValues call. For range types, the application can
examine certain properties about the range of values supported. These
properties are also returned in the ALparamInfo structure; see below.
The initial field gives the value for this parameter on this resource
when the audio system is first initialized.
The next fields apply only to range parameters. min and max give the
minimum and maximum values, respectively. minDelta and maxDelta give the
minimum and maximum difference between any two adjacent values.
specialVals describes what "special values" may be supported by the range
parameter. "Special values" are values outside the range described by
[min, max] and whose semantics may differ from the values inside that
range. The currently supported special values are: AL_NO_CHANGE, which,
when given as a value for alSetParams, means "Don't change the value of
this element;" and AL_NEG_INFINITY, which corresponds to a value of
negative infinity. Each special value has a corresponding bit in
specialVals which is set if that value is supported. The token for this
bit is the name of the special value plus "_BIT," e.g. AL_NO_CHANGE_BIT.
Finally, operations describes what operations are supported by this
parameter on this resource. To determine if an operation is supported,
see which of the bits AL_GET_OP, AL_SET_OP, AL_EVENT_OP, and AL_QUERY_OP
are set in operations. If AL_GET_OP is set, the resource supports
alGetParams(3dm) for that parameter. If AL_SET_OP is set, the resource
supports alSetParams(3dm) for that parameter. If AL_EVENT_OP is set, the
resource is capable of generating events when the parameter's value
changes. If AL_QUERY_OP is set, the resource supports calling
alQueryValues(3dm) for the parameter.
Page 2
alGetParamInfo(3dm)alGetParamInfo(3dm)EXAMPLE
ALparamInfo pinfo;
/*
* Grab some information about the gain parameter on this resource.
* We already know that AL_GAIN always takes a 64-bit fixed-point value, so
* we can assume that's the type of all the ALvalue fields in "pinfo."
*/
alGetParamInfo(resource, AL_GAIN, &pinfo);
/* Check to see if this resource supports a gain of minus infinity */
if (pinfo.specialVals & AL_NEG_INFINITY_BIT) {
printf("supports negative infinity\n");
}
printf("min: %lf dB; max: %lf dB; best resolution: %lf dB\n",
alFixedToDouble(pinfo.min.ll),alFixedToDouble(pinfo.max.ll),
alFixedToDouble(pinfo.minDelta.ll));
DIAGNOSTICS
Upon successful completion, alGetParamInfo returns 0. Otherwise
alGetParamInfo returns -1 and sets an error number which can be retrieved
with oserror(3C).
alGetParamInfo can fail for the following reasons:
AL_BAD_RESOURCE
resource is invalid.
AL_BAD_PARAM
param is not supported on the given resource.
SEE ALSOoserror(3C), alIntro(3dm), alQueryValues(3dm), alSetParams(3dm),
alGetParams(3dm)
Page 3
