alParams(3dm) alParams(3dm)
alParams - Audio Library parameters
This manual page describes the semantics of Audio Library (AL)
parameters. Parameters are the AL's mechanism for obtaining or setting
the state of each software or hardware audio resource. Parameters are
also used to set/unset audio event notification.
Each type of AL resource accepts different parameters. This manual page
is divided up into sections, each of which describes a resource type and
the parameters it accepts. See alResources for a more thorough
description of resources and their properties.
For more information about actually setting and acquiring the values of
parameters, see alGetParams(3dm) and alSetParams(3dm).
For more information on selecting and deselecting parameters for audio
event notification, refer to alSelectEvents(3dm) and
alDeselectEvents(3dm).
PARAMETERS AND VALUES [Toc] [Back] Parameters are retrieved or set using an ALpv structure. The most
important two fields in the ALpv are:
typedef union {
int param; /* the parameter */
ALvalue value; /* the associated value */
[...]
} ALpv;
The ALvalue structure is a union of three types:
typedef union {
int i; /* 32-bit integer values */
long long ll; /* 64-bit integer and fixed-point values */
void* ptr; /* pointer values */
} ALvalue;
The AL supports a small number of data types, each of which uses a
specific field of the ALvalue. These are:
32-bit integer Uses the value.i field.
Resource Uses the value.i field.
Enumeration Uses the value.i field.
64-bit integer Uses the value.ll field.
Page 1
alParams(3dm) alParams(3dm)
Fixed-point Uses the value.ll field. alFixedToDouble(3dm) and
alDoubleToFixed(3dm) are convenience functions to convert
between double-precision floating-point and 64-bit
fixed-point.
Vectors, Sets, Matrices, Strings
The value.ptr field must point to the actual value.
There are also required size fields for these data types.
See alGetParams(3dm) and alSetParams(3dm) for more
information.
In addition, some parameters may support only some subset of
alGetParams(3dm), alSetParams(3dm), alQueryValues(3dm),
alSelectEvents(3dm) and alDeselectEvents(3dm). Also, unless otherwise
stated, event data information should be retrieved with
alGetEventValue(3dm).
The following parameters apply to all resources.
AL_TYPE (32-bit integer, get only)
The type of the resource. All resources have types. Some
types are subtypes of another; in this case, parameters
which apply to the supertype also apply to the subtype.
See the alIsSubtype(3dm) manual page for more
information.
AL_NAME (character string, get only)
The name of the resource. This name is typically used
internally in applications, for example, for saving
parameters to files. It can be passed into
alGetResourceByName(3dm) to retrieve the original
resource. It is constant and unique for a given resource
on a given system.
AL_LABEL (character string, get/set/events)
The label of the resource. This is a human-readable
description of the resource. Use this, for example, for
resource selection in menus, or for otherwise displaying
resources to users. It is unique on a given system. It is
also user-configurable.
Attempts to set its value to equal an existing label on
the same subsystem will be rejected. If the same label
exists on another subsystem, the system will render them
unique by prepending the names of the subsystems to the
labels. The characters '.' and ':' are reserved and
cannot be used in labels.
To retrieve event data information use alGetParams(3dm).
Page 2
alParams(3dm) alParams(3dm)
AL_NO_OP (no type, get/set)
The ALpv structure associated with this parameter is
ignored. This effectively allows a program to "comment
out" individual parameter/value pairs in a larger list
without restructuring the list.
AL_PARAMS (set of enum, query)
Returns the set of parameters supported by this resource.
Each computer has a single system resource, with a fixed resource ID of
AL_SYSTEM, representing global parameters of the audio software. The
following parameters apply to the system resource.
AL_MAX_PORTS (32-bit integer, get only)
The maximum number of audio ports that can be
simultaneously open on the system.
AL_UNUSED_PORTS (32-bit integer, get only)
The number of unused ports on the system.
AL_MAX_SETSIZE (32-bit integer, get only)
The maximum number of elements used by any set-valued
parameter across the system.
AL_DEFAULT_INPUT
(resource, get/set/query/events)
The current default input device for the system. The
resource supplied must be a device. alQueryValues on this
parameter will return the set of available input devices.
AL_DEFAULT_OUTPUT
(resource, get/set/query/events)
The current default output device for the system. The
resource supplied must be a device. alQueryValues on this
parameter will return the set of available output
devices.
AL_DEVICES (set of resources, query only)
The set of devices available on the system.
AL_PORTS (set of resources, query/events: ALsetChangeInfo *)
The set of ports currently in use.
Creation or deletion of audio ports will generate events.
To retrieve the event value data, use
alGetEventData(3dm). This function returns a void pointer
to an ALsetChangeInfo struct:
typedef struct _ALsetChangeInfo {
ALvalue val; /* value of set element */
int total; /* total number of elements */
int pchange;/* delta ( +1 or -1) */
}ALsetChangeInfo;
Page 3
alParams(3dm) alParams(3dm)
The structure consists of val, the inserted or deleted
set element; total, the new number of elements in the
set; and delta, indicating the change in number of
elements.
AL_CONNECTIONS (set of resources, query/events: ALsetChangeInfo)
The set of connections currently in use. Events will get
generated as connections (or disconnections) are made to
devices in the audio system. To retrieve the event value
data use alGetEventData(3dm). This function returns a
void pointer to an ALsetChangeInfo struct. Refer to
AL_PORTS for more information.
The set of connections currently in use.
AL_TYPE (32-bit integer, get only)
Returns AL_SYSTEM_TYPE.
An audio device is the top level of control for an input or output audio
data stream. It is the place to which applications connect their ports to
perform input or output. Each device has a clock-generator to provide it
with a sample-rate, and potentially a number of interfaces, each of which
corresponds with a physical audio jack on the system. A device will
accept parameters for the clock-generator and interfaces it is currently
using.
AL_CHANNELS (32-bit integer, get/set/query/events)
The number of channels supported by the device. Some
devices may support variable numbers of channels.
AL_INTERFACE (resource, get/set/query/events on input devices; query
only for output devices)
For input devices, this is the interface (input source)
currently in use. Input devices can use only one
interface at a time, and typically support setting
AL_INTERFACE.
Output devices usually drive all available interfaces
simultaneously; in this case, they will not support
setting AL_INTERFACE, and will always return a value of
AL_ALL_INTERFACES for this parameter. However, a few
output devices share interfaces with other devices, and
therefore allow setting of AL_INTERFACE. Use the
operations field of alGetParamInfo(3dm) to determine if
AL_INTERFACE is settable on a particular device.
The interface can be specified as a specific resource or
by type (for example, AL_MIC_IF_TYPE to indicate a
microphone interface). If the interface is given by type,
the AL will choose an appropriate interface of the given
type.
Page 4
alParams(3dm) alParams(3dm)
alQueryValues(3dm) returns the set of interfaces
available to the device.
AL_CLOCK_GEN (resource, get/set/query/events)
The clock-generator this device is using to provide its
sample-rate. alQueryValues(3dm) returns the set of
clock-generators available to the device.
AL_TYPE (32-bit integer, get only)
The type of the device. Input devices will return some
subtype of AL_INPUT_DEVICE_TYPE; output devices will
return some subtype of AL_OUTPUT_DEVICE_TYPE. Use
alIsSubtype(3dm) to determine if one type is a subtype of
another.
AL_CONNECT (ALconnectionInfo*, events only: ALconnectionInfo)
A connection involving the device occurred. To retrieve
the event value data, use alGetEventData(3dm). This
function returns a void pointer to an ALconnectionInfo
struct. The struct contains the id for the source
resource, destination resource and connection resource.
It is defined as:
typedef struct _ALconnectionInfo {
int source;
int dest;
int connection;
} ALconnectionInfo;
AL_DISCONNECT (ALconnectionInfo*, events only: ALconnectionInfo) A
disconnect involving the device occurred. To retrieve
the event information data use: alGetEventData(3dm). This
function returns a void pointer to al ALconnectionInfo.
Refer to AL_CONNECT for more information.
AL_SUBCODE_FORMAT
(set of enum, query)
The set of subcode data formats supported by the device.
Values can be AL_AES_CHANNEL_STATUS, AL_AES_USER,
AL_AES_VALIDITY. Subcode data streams describe distinct
channels of continuous non-audio data that are inherently
associated with a digital audio stream.
AL_SUBCODE_FRAMESIZE
(int, get only)
If supported, indicates the number of bytes into which a
single channel of subcode data will fit. This value is
often used in conjunction with AL_SUBCODE_CHANNELS to
determine sizing for memory allocation. For AES subcode,
this value is 24, as defined by the IEC958/AES3
specifications for the transmission of digital audio
signals. For ADAT subcode, this value is 4.
Page 5
alParams(3dm) alParams(3dm)
AL_SUBCODE_CHANNELS
(int, get only)
If supported, the number of subcode channels supported by
a device for all subcode formats. This value when
multiplied by the value provided by AL_SUBCODE_FRAMESIZE
gives the size, in bytes of an entire multi-channel frame
of subcode data.
AL_INTERVAL (int, get only)
If supported, indicates the number of audio frames
required for the complete transmission of one multichannel
frame of subcode data.
AL_AES_CHANNEL_STATUS, AL_AES_USER, AL_AES_VALIDITY
(vector of bytes, get/set) These parameters, if
supported, provide a means for a quick get or set of
subcode data. They are not intended for real-time use.
For input devices, these parameters are get-only and the
returned vector of bytes is most recently captured full
multi-channel subcode frame corresponding to the subcode
data format parameter. For output devices, these
parameters may have either get/set or get-only
capabilities (depending on hardware -- use
alGetParamInfo(3a) to check) and indicate the default
multi-channel subcode frame to be transmitted.
Subcode data bit ordering always puts subcode Byte 0, bit
0 in the most significant bit of Byte 0, thus allowing a
big-endian bit shift operation to correspond to a subcode
data time shift. See the IEC958 "Digital Audio
Interface" and AES3-1992 "Serial Transmission Format For
Two-Channel Linearly Represented Audio Data"
specifications for the details on what the AES subcode
data bits actually represent.
Each device has a number of interfaces, each of which corresponds to a
physical audio jack or set of jacks on the machine. Input devices use
one interface at a time.
Output devices usually drive all their interfaces simultaneously with the
same audio data. In some cases, an output device will only drive one
interface at a time, usually because it is sharing an interface with
another device. For example, the AESOut and ADATOut devices on some
systems can share an optical interface, in which case each device drives
only one interface at a time.
AL_GAIN (vector of fixed-point values, get/set/events)
The gain, in decibels (dB), per channel. Positive values
represent gain; negative values represent attenuation.
Interfaces without gain capability will return values of
Page 6
alParams(3dm) alParams(3dm)
0 dB. The audio system will round unsupported gain values
down to the nearest supported value.
There are two special values for gain. An application
can set a value of AL_NO_CHANGE on any channel, causing
the gain value for that channel to remain unchanged. This
value is supported on all interfaces. Also, the special
value of AL_NEG_INFINITY corresponds to a gain of
negative infinity decibels (mute). AL_NEG_INFINITY is
only supported on some interfaces.
To determine the gain range for an interface, and whether
or not it supports AL_NEG_INFINITY, use the
alGetParamInfo(3dm) call. This returns an ALparamInfo
structure for the AL_GAIN parameter on a particular
interface. The min and max fields of the ALparamInfo
correspond to the minimum and maximum finite gain values,
respectively. If AL_NEG_INFINITY is supported, the
AL_NEG_INFINITY_BIT will be set in the specialVals field.
To obtain event data information use alGetParams(3dm).
AL_MUTE (32-bit integer, get/set/events) If true, mutes an output
interface. If false, the interface is unmuted. Some
output interfaces may ignore this (e.g. most digital
interfaces).
This parameter does not affect the value of the AL_GAIN
parameter. An application which desires the "true" gain
of the interface should look at both AL_GAIN and AL_MUTE.
AL_WORDSIZE (32-bit integer, get/set/query/events)
The number of significant bits on the interface. Though
the AL will accept or produce 8-,16-, and 24-bit data
with any interface, different interfaces will have
differing numbers of significant bits. For example, most
digital interfaces have 24 significant bits, while most
analog interfaces have 16 or 18.
AL_CHANNELS (32-bit integer, get/set/query/events)
The number of significant channels supported by the
interface. Note that this may differ from the number of
channels supported by the device using the interface. For
example, a stereo input device may have one mono
microphone input and one stereo line-level input. In
this case, the device returns AL_CHANNELS=2, and the
interfaces return AL_CHANNELS=1 and AL_CHANNELS=2,
respectively.
AL_TYPE (32-bit integer, get)
The type of the interface. All are subtypes of
AL_INTERFACE_TYPE. Digital interfaces will be subtypes of
Page 7
alParams(3dm) alParams(3dm)
AL_DIGITAL_INTERFACE_TYPE; analog interfaces will be
subtypes of AL_ANALOG_INTERFACE_TYPE. Refer to audio.h
for a complete listing of interface types, and to
alIsSubtype(3dm) for information on subtypes in general.
CLOCK-GENERATOR PARAMETERS
A clock-generator provides the sample-rate clock to an audio device. Each
clock-generator takes a particular frequency reference, called a master
clock, and provides a precise fraction of that master clock to the audio
device. For simplicity, an audio device will accept parameters on behalf
of the clock-generator it uses.
AL_RATE (fixed-point, get/set/events)
The nominal sample-rate, in hertz. Unsupported values are
rounded to the nearest supported value.
When an application gets the value of AL_RATE, the AL
will return the current nominal master clock rate times
the current rate-fraction (see AL_RATE_FRACTION_*,
below). In some cases, when the AL cannot determine the
nominal sample-rate of the master clock, it will be
unable to return a nominal sample-rate for the clockgenerator.
In these cases, the AL will return a negative
value for AL_RATE.
When an application sets the value of AL_RATE, the AL
will set the value of the rate-fraction (see
AL_RATE_FRACTION_*, below) based upon the nominal master
clock rate. If the nominal master clock rate is unknown,
the AL will not change the sample-rate. Also, if the
master clock rate changes, the AL will not automatically
update the rate-fraction for a rate set by AL_RATE. For
variable-rate master clocks, it is therefore usually
better to use AL_RATE_FRACTION_* to set the sample-rate.
For fixed-rate master clocks, such as crystals or video
sources, AL_RATE and AL_RATE_FRACTION_* are equivalent
representations.
Note:In general, the master clock should be specified
when the rate is changed.
AL_RATE_FRACTION_N, AL_RATE_FRACTION_D
(32-bit integer, get/set/events)
The sample-rate, represented as an exact fraction (N/D)
of the master clock. The value of (N/D) must lie between
0 and 1. If the exact fraction given cannot be
supported, the AL will substitute a nearby fraction.
If these two parameters are given in the same call to
alSetParams(3dm) or alGetParams(3dm), they will be set or
acquired atomically.
Page 8
alParams(3dm) alParams(3dm)
In general, the master clock should be specified when the
rate is changed.
AL_MASTER_CLOCK (resource; get/set/query/events)
The master clock from which this clock-generator derives
its rate.
The master clock can be specified as a specific resource
or by type (for example, AL_CRYSTAL_MCLK_TYPE to indicate
a crystal-based master clock). If the master clock is
given by type, the AL will choose an appropriate master
clock of the given type.
alQueryValues(3dm) returns the set of master clocks
available to the clock-generator.
AL_TYPE (int, get only)
The type of the clock-generator. Returns
AL_CLOCKGEN_TYPE.
MASTER-CLOCK PARAMETERS [Toc] [Back] AL_RATE (fixed-point, get/events)
The nominal rate of the master clock, in hertz. If the
nominal rate is unknown, a negative value is returned.
Some master clocks have variable sampling rates. An
event will be generated if the rate of the master clock
changes.
AL_TYPE (int, get only)
The type of the master clock. All are subtypes of
AL_MCLK_TYPE. Fixed-rate master clocks, such as videobased
clocks and crystal-based clocks, are subtypes of
AL_FIXED_MCLK_TYPE. Variable-rate master clocks, such as
AES- and ADAT-derived rates, are subtypes of
AL_VARIABLE_MCLK_TYPE.
AL_VIDEO_SYNC (enum, get/set/query/events)
This parameter is only applicable on master clocks which
are subtypes of AL_VIDEO_MCLK_TYPE. Valid values are
AL_VID_INTERNAL and AL_VID_EXTERNAL, depending on whether
the video timing signal is to come from an internal video
sync bus or via an external video blackburst fed directly
into the audio subsystem.
CONNECTION PARAMETERS [Toc] [Back] A connection is a resource which moves audio data between an audio device
and an audio port, or between two audio devices. See the man page for
alConnect(3dm) for more information.
AL_SOURCE (resource, get only)
The source of the connection.
Page 9
alParams(3dm) alParams(3dm)
AL_DEST (resource, get only)
The destination of the connection.
SEE ALSO
alSetParams(3dm), alGetParams(3dm), alGetParamInfo(3dm),
alQueryValues(3dm)
PPPPaaaaggggeeee 11110000 [ Back ]
|
