alGetParamInfo(3dm) alGetParamInfo(3dm) NAME alGetParamInfo - 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. DESCRIPTION alGetParamInfo 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 (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. 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 ALSO oserror(3C), alIntro(3dm), alQueryValues(3dm), alSetParams(3dm), alGetParams(3dm) Page 3