ALgetparams(3dm) ALgetparams(3dm)
ALgetparams, ALsetparams - (obsolete) get/set the value of the specified
audio device states
#include <dmedia/audio.h>
int ALgetparams(long device, long *PVbuffer, long bufferlength)
int ALsetparams(long device, long *PVbuffer, long bufferlength)
device expects the device to which this command applies.
Currently, there is only one device, AL_DEFAULT_DEVICE.
PVbuffer expects an array of longs. The even elements of this
array should each contain a device state variable that you
choose to read or change. The subsequent odd elements are
the current or new value of these variables.
bufferlength expects the number of longs in the buffer pointed to by
PVbuffer. This value must be even.
ALgetparams and ALsetparams are obsolete and are provided for backward
compatibility. The preferred functions are alGetParams(3dm) and
alSetParams(3dm).
ALgetparams(3dm) returns the current values for the device state
variables referenced in the PVbuffer array. The values are written into
the odd locations of PVbuffer immediately after the corresponding state
variable. Unrecognized parameters are ignored.
ALsetparams(3dm) sets the current state of the device state variables
referenced in the PVbuffer array. Unrecognized parameters are ignored.
Since the audio system is a shared resource, changing the value of a
system parameter with ALsetparams(3dm) may affect other programs
adversely. For example, changing the input sample rate could cause an
undesired effect for a program currently sampling input data. In general
it is a good practice to determine whether other audio applications are
currently active by retrieving the number of open input/output audio
ports (see AL_INPUT_COUNT and AL_OUTPUT_COUNT below).
The currently defined set of device parameters are defined in audio.h:
[not all parameters are present on all systems]
Page 1
ALgetparams(3dm) ALgetparams(3dm)
AL_INPUT_SOURCE
AL_INPUT_LINE, AL_INPUT_MIC, or AL_INPUT_DIGITAL
AL_LEFT_INPUT_ATTEN
0 to 255 0=no attenuation, 255=maximum attenuation
AL_RIGHT_INPUT_ATTEN
0 to 255 0=no attenuation, 255=maximum attenuation
AL_INPUT_RATE
Sample rate of analog inputs. Positive values indicate sample rate
in Hz. Negative values indicate the rate value is a
logical value as opposed to a numeric one. Logical values include:
AL_RATE_AES1=set input analog sample rate to be identical to the
input digital stream sample rate. Future hardware may provide
additional logical rates.
AL_OUTPUT_RATE
Positive values indicate sample rate in Hz.
Negative values indicate the rate value is a logical value as
opposed to a numeric one. Logical values include:
AL_RATE_INPUTRATE=set output sample rate to be identical to
the input sample rate.
AL_RATE_AES1=set output sample rate to be identical to the
input digital stream sample rate.
Future hardware may provide additional logical rates.
AL_LEFT_SPEAKER_GAIN
0 to 255 0=off, 255=maximum volume.
This also affects the headphone output.
AL_RIGHT_SPEAKER_GAIN
0 to 255 0=off, 255=maximum volume
This also affects the headphone output.
AL_INPUT_COUNT
read-only. It contains the number of open input ALports.
AL_OUTPUT_COUNT
read-only. It contains the number of open output ALports.
AL_UNUSED_COUNT
read-only. It contains the number of unopened ALports.
AL_SYNC_INPUT_TO_AES
This parameter is obsolete. 0 is always returned.
1=sync to digital input clock, 0=use internal clock.
AL_SYNC_OUTPUT_TO_AES
This parameter is obsolete. 0 is always returned.
1=sync to digital input clock, 0=use internal clock.
AL_MONITOR_CTL
Enabling monitoring causes a copy of the input stream to be
copied directly to the output of the audio system with minimal
delay. The parameter AL_MONITOR_CTL can take the following
values:
AL_MONITOR_ON=enables monitoring of audio.
AL_MONITOR_OFF=disables monitoring of audio.
AL_LEFT_MONITOR_ATTEN
Indigo and 4D/35 only.
0 to 255 where 0=no attenuation and 255=maximum attenuation
AL_RIGHT_MONITOR_ATTEN
Indigo and 4D/35 only.
Page 2
ALgetparams(3dm) ALgetparams(3dm)
0 to 255 where 0=no attenuation and 255=maximum attenuation
AL_CHANNEL_MODE
Indigo2 and Indy only.
AL_STEREO=configure hardware for stereo audio.
AL_4CHANNEL=configure hardware for 4-channel audio.
AL_SPEAKER_MUTE_CTL
AL_SPEAKER_MUTE_ON=speaker and headphones muted.
AL_SPEAKER_MUTE_OFF=speaker and headphones unmuted.
AL_MIC_MODE
Indigo2 and Indy only.
AL_MONO or AL_STEREO
AL_DIGITAL_INPUT_RATE
Indigo2 and Indy only.
read-only. Positive values indicate sample rate in Hz. Negative
value indicates a logical rate (viz., AL_RATE_UNDEFINED). The
digital input rate is encoded in the input digital audio
stream, which can change over time.
Logical rates:
AL_RATE_UNDEFINED=digital input signal valid, but rate
not encoded in signal
AL_RATE_UNACQUIRED=digital input signal valid, but rate
not yet acquired from input signal
AL_RATE_NO_DIGITAL_INPUT=digital input signal not valid
AL_LEFT2_INPUT_ATTEN
Indigo2 and Indy only.
0 to 255 0=no attenuation, 255=maximum attenuation
This parameter is available on systems with 4-channel capability
only.
AL_RIGHT2_INPUT_ATTEN
Indigo2 and Indy only.
0 to 255 0=no attenuation, 255=maximum attenuation
This parameter is available on systems with 4-channel capability
only.
#include <dmedia/audio.h>
...
/* Set the speaker gains to 128 */
long buf[4] = {
AL_LEFT_SPEAKER_GAIN, 128,
AL_RIGHT_SPEAKER_GAIN, 128
};
ALsetparams(AL_DEFAULT_DEVICE,buf,4);
ALgetparams(3dm) and ALsetparams(3dm) can fail for the following reasons:
AL_BAD_DEVICE device is not AL_DEFAULT_DEVICE.
ALgetparams(3dm) ALgetparams(3dm)
AL_BAD_PVBUFFER PVbuffer is null (0) valued.
AL_BAD_BUFFERLENGTH_NEG bufferlength is negative.
AL_BAD_BUFFERLENGTH_ODD bufferlength is odd.
AL_BAD_DEVICE_ACCESS audio hardware is inaccessible.
Setting AL_LEFT_SPEAKER_GAIN or AL_RIGHT_SPEAKER_GAIN automatically sets
AL_SPEAKER_MUTE_CTL to AL_SPEAKER_MUTE_OFF.
Setting AL_CHANNEL_MODE to AL_4CHANNEL causes the input and output sample
rates to be identical.
When AL_CHANNEL_MODE is set to AL_4CHANNEL, the AL_INPUT_SOURCE parameter
controls the behavior of the second set of analog inputs (normally the
microphone input). In this state, the normal line-level inputs are always
active. Setting AL_INPUT_SOURCE to AL_INPUT_MIC causes the second set of
inputs to be mic-level. Setting AL_INPUT_SOURCE to AL_INPUT_LINE causes
the second set of analog inputs to be line-level.
Upon successful completion, ALgetparams(3dm) and ALsetparams(3dm) return
0. Otherwise, these functions return -1 and set an error number which can
be retrieved with oserror(3C).
ALqueryparams(3dm), ALgetminmax(3dm), ALgetdefault(3dm), ALgetname(3dm),
oserror(3C)
Page 4
alGetParams(3dm) alGetParams(3dm)
alGetParams - get the values of audio resource parameters
#include <dmedia/audio.h>
int alGetParams(int resource, ALpv *pvs, int npvs)
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.
alGetParams 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.
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]));
}
alGetParams 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 [Toc] [Back]
pvs is invalid.
AL_BAD_BUFFERLENGTH [Toc] [Back]
npvs is patently wrong (e.g. negative).
AL_BAD_DEVICE_ACCESS [Toc] [Back]
The audio system is inaccessible, either because it is not installed
on the system, or because it is incorrectly configured.
AL_BAD_RESOURCE [Toc] [Back]
The given resource resource does not exist.
alParams(3dm), alSetParams(3dm), alGetParamInfo(3dm), oserror(3C)
PPPPaaaaggggeeee 3333 [ Back ]
|
