alSetParams(3dm) alSetParams(3dm)
alSetParams - set the values of audio resource parameters
#include <dmedia/audio.h>
int alSetParams(int resource, ALpv *pvs, int npvs)
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.
alSetParams 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.
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)
}
}
alSetParams 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 [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), alGetParams(3dm), alGetParamInfo(3dm), oserror(3C)
Page 3
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.
Page 3
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)
PPPPaaaaggggeeee 4444 [ Back ]
|