alResources(3dm) alResources(3dm)
alResources - Audio Library resources
Audio Library resources are hardware or software objects that each
perform a specific function in the audio I/O process. Each resource has
a set of parameters which describes its state. See alParams(3dm) for more
information about parameters.
This manual page provides general information about the different types
of resources, how they relate to each other, how they are named, and
where to find specific information about programming each type of
resource.
Each specific instance of a resource has a unique 32-bit integer
identifier, or resource ID. Resource IDs are the "handles" by which an
application refers to that resource when calling AL functions.
There are a number of different types of resources. Each resource shares
some parameters in common with others, and each has parameters unique to
its type. Resource types are similar in some ways to classes in an
object-oriented language; one resource type can be a subtype of another,
and the subtype can extend the set of parameters supported by the
supertype. The function alIsSubtype(3dm) indicates whether or not one
resource or resource type is a subtype of another. In general, an
application should never compare resource types directly; it should use
alIsSubtype where possible.
Specific resource types include: system, subsystems, devices, clockgenerators,
master clocks, interfaces, ports, and connections.
Below is a description of the main resource types. For more information
on the parameters supported by each type, see alParams(3dm).
THE SYSTEM AND SUBSYSTEMS [Toc] [Back] The audio system is a software resource which manages the global
parameters of the audio system. Currently there is one system resource
per machine. The system has a fixed resource ID given by the macro
AL_SYSTEM.
An audio subsystem is a collection of tightly integrated hardware
resources. Typically this represents a single card or chip on which
multiple devices and their associated resources are implemented. The
subsystem exists mainly as a way of distinguishing between similar groups
of devices on the same system. See below under "Resource Naming" for more
information.
All subsystems are some subtype of AL_SUBSYSTEM_TYPE. Current types of
subsystems include:
Page 1
alResources(3dm) alResources(3dm)
RAD Built-in audio on the OCTANE and Onyx2, or a Professional
Option Card.
A2 Built-in audio on the Indigo2 or Indy, or an Audio/Serial
Option card.
A3 Built-in audio on the O2.
An audio device represents a single independent stream of input or output
audio data. It is where applications connect their ports to perform I/O.
Devices can be shared between multiple applications. On input, each
application using an audio device will get a copy of the input data. On
output, the data from all applications using the device will be mixed
together.
Each device performs N simultaneous channels of audio input or output at
a single sample-rate. The sample clock is provided to the device by a
separate resource called a clock generator (see below). In practice,
each device almost always has its own clock generator, allowing devices
to have independent sample-rates from other devices.
The audio device gets its input signal, or produces its output signal,
through a resource called an interface. Each interface corresponds to a
physical audio jack on the system. A device often has access to multiple
interfaces. On an input device, this indicates that there are multiple
inputs for the same device. For example, the analog input device on most
systems can select between a microphone input and a line-level input. An
input device can only use one input at a time.
An output device will either drive all its interfaces simultaneously, or
it may have the ability to select a single interface from several. To
determine whether or not the interface is selectable, use alGetParamInfo
to see if the device supports setting the value of its AL_INTERFACE
parameter.
The audio system also provides two special devices, the default input
(resource ID == AL_DEFAULT_INPUT) and the default output (resource ID ==
AL_DEFAULT_OUTPUT). For most operations, if an audio application does not
explicitly specify a device, the operation will apply to the default
input or output.
All devices are subtypes of AL_DEVICE_TYPE. They will also be subtypes of
either AL_INPUT_DEVICE_TYPE or AL_OUTPUT_DEVICE_TYPE, depending upon
whether or not they perform input or output. No devices can perform both.
CLOCK GENERATORS AND MASTER CLOCKS [Toc] [Back] As mentioned above, a clock generator provides a sample clock to a device
or set of devices. All clock generators follow the same basic model: each
takes an input sample clock, and synthesizes an output sample clock whose
rate is a rational fraction of the input sample clock. The input sample
clock is usually called the master clock; it is a separate resource.
Page 2
alResources(3dm) alResources(3dm)
This model thus distinguishes between nominal sample rate and timebase.
The clock generator controls the nominal sample rate, while the master
clock provides the underlying timebase. Two clock generators providing
different sample rates, but relative to the same master clock, will be
precisely related to each other, and will not drift over time.
Conversely, two clock generators providing the same nominal sample rates,
but relative to two different master clocks, will drift over time. For
example, one clock generator may provide 44.1kHz relative to an internal
crystal, while another may provide 44.1kHz relative to an external video
input. These two clock generators are asynchronous and will drift, though
they are both nominally 44.1kHz. This is a critical distinction for
applications which provide precise long-term synchronization.
Master clocks are all subtypes of AL_MCLK_TYPE. Beneath the AL_MCLK_TYPE
are two important subtypes: AL_FIXED_MCLK_TYPE, and
AL_VARIABLE_MCLK_TYPE, denoting fixed-rate and variable-rate master
clocks, respectively. Fixed-rate master clocks provide a timebase at a
known, nominally fixed rate. Typically these are internal crystals or
video-related timebases. Variable-rate master clocks can change their
nominal sample rate at any time, and the nominal rate may be unknown.
Typically these are derived from digital audio inputs, where the external
device providing the rate can change it at will.
From the application point-of-view, the critical distinction between the
two types of master clocks is the preferred method to program the clock
generators using them. A clock generator using a fixed-rate master clock
can be programmed in Hz using the AL_RATE parameter, or as a fraction of
the master clock rate, using the AL_RATE_FRACTION_N and
AL_RATE_FRACTION_D parameters. Here the two methods are equivalent;
setting the rate in Hz sets the internal fraction, and vice-versa.
However, if the clock generator uses a variable master-clock, it is best
programmed with a fraction. The application can still use the AL_RATE
parameter, and the audio system will attempt to set or return the correct
nominal rate, but if the nominal rate is unknown, the operation will
fail. Moreover, as the master clock rate changes, the audio system will
not reprogram the clock generator to maintain a constant nominal rate in
Hz.
An interface resource generally corresponds to a particular physical
input or output jack on the system. An input device may have access to
multiple input interfaces to indicate that input stream can be driven
from one of several input sources. An output device may be capable of
driving several interfaces simultaneously, or it may be able to select
one of several.
All interfaces are subtypes of AL_INTERFACE_TYPE. They will also be
subtypes of either AL_ANALOG_IF_TYPE or AL_DIGITAL_IF_TYPE, depending
upon whether or not they are analog or digital interfaces, respectively.
Some other useful types are AL_MIC_IF_TYPE, AL_LINE_IF_TYPE,
AL_AES_IF_TYPE, and AL_ADAT_IF_TYPE. Some interfaces can support more
than one type of I/O. For example, AL_OPTICAL_IF_TYPE represents an
Page 3
alResources(3dm) alResources(3dm)
optical interface shared between an AES and an ADAT device; it is a
subtype of both AL_AES_IF_TYPE and AL_ADAT_IF_TYPE.
An audio port is an application-created, temporary resource through which
the application sends and receives sample data. It is a software
equivalent to a device, in that both send and receive sample data and
both can accept connections. See alOpenPort(3dm) for information on how
to create an audio port.
All ports are subtypes of AL_PORT_TYPE.
A connection moves audio data between two devices, or between a port and
a device. The producer of the audio data is called the source resource;
the consumer of the data is called the destination. These correspond to
the AL_SOURCE and AL_DEST parameters, respectively. Multiple connections
into the same destination will mix together. Multiple connections out of
the same source will provide multiple streams of identical data.
A connection is usually created implicitly when the application creates a
port with alOpenPort(3dm), unless the application has set
AL_NULL_RESOURCE as the desired device for the port. The application can
also explicitly create a connection using alConnect(3dm).
A connection can also perform translation between differing numbers of
channels at the source and destination. Let M be the number of channels
at the source, and N be the number of channels at the destination. There
is currently only one available behavior for a given (M, N) pair. If M <
N, the AL always pads with (M-N) zero-filled channels. There are two
different rules for M > N. If either M or N is greater than 4, the AL
drops the (M-N) extra channels. For backward compatibility, for
{M=4,N=2}, the AL mixes input channels 1 and 3 into output channel 1, and
mixes input channels 2 and 4 into output channel 2.
All connections are subtypes of AL_CONNECTION_TYPE.
RESOURCE RELATIONSHIPS AND PARAMETER INHERITANCE [Toc] [Back] The audio system keeps careful track of the dependencies between
resources. A resource that relies upon another resource for part of its
behavior is said to use that resource. For example:
A device uses a clock generator to get its sample rate.
A clock generator uses a master clock to get its timebase.
A port uses a connection to get its audio data.
The description of which resources use which forms a directed graph
called the resource hierarchy. This hierarchy is a critical part of the
AL control mechanism.
Page 4
alResources(3dm) alResources(3dm)
If an application attempts a parameter operation on a resource which does
not recognize the parameter, that resource will pass the parameter to all
the resources it uses. If these resources do not recognize the parameter,
they will in turn pass the parameter on to the resources they use, and so
on, until the parameter reaches the bottom of the hierarchy. This
behavior is called parameter inheritance.
In practice, this allows an application to send clock generator or master
clock parameters to a device, or even to a port, and the parameters will
automatically be passed to the correct resource. Under most circumstances
this obviates the need for the application to look up the clock
generator, or to track master clock changes, and so on. It also allows an
application to set parameters on all the devices to which a port is
connected, simply by setting the parameters on the port.
Note that the behavior of parameter inheritance when setting parameter
values differs slightly from that of getting parameter values. When
setting a parameter value, the value is distributed to a set of
applicable resources. When getting a value, only one value can be
returned, so the audio system will choose the most appropriate resource
from which to actually obtain the value.
For example, if an application sets a sample rate on a port which is
connected to two devices, the sample rate will propagate to the clock
generators for both devices. If the sample rate changes on one device,
then the question arises: if the application requests the sample rate
from the port, from which device will the sample rate request be
satisfied? Since the port can only have one sample rate, its rate must
match only one of the devices to which it is connected. It is that sample
rate which will be returned.
There are fixed definitions governing which types of resources can use
which other types of resources. The rules are as follows:
RESOURCE TYPE USE RESOURCE TYPE(S)
ports connections
connections devices
devices clock generators, interfaces
clock generators master clocks
subsystems devices
RESOURCE NAMING AND LABELING
In addition to resource IDs, resources all have names and labels.
The label (parameter AL_LABEL) is a human-readable string with which the
application labels a resource when presenting it to a user. If identical
labels exist on a system, the AL will render them unique by prepending
Page 5
alResources(3dm) alResources(3dm)
them with the labels of their respective subsystems. For example, if a
system has a device "ADAT In", and the user installs a second audio
subsystem with an identical device, the AL will label these "RAD 1.ADAT
In" and "RAD 2.ADAT In," assuming the two subsystems are called "RAD 1"
and "RAD 2," respectively.
Labels can also be modified by an application, in order to allow the user
to customize the appearance of the audio system. For example, a user may
choose to relabel the audio inputs to correspond to the devices which are
connected to them, e.g. "Tape Deck A" instead of "Line In". An
application cannot set a label which contains the reserved characters
same subsystem.
Labels should be used to label resources in the application user
interface. Because they can change dynamically, they should not be used
as keys with which to look up devices. Consider, for example, an
application which presents a menu of resources, using labels for the menu
entries. It should keep the resource ID for each menu entry, and use that
to refer internally to the resource. It should not try to look up the
resource by the label in the menu entry; the label may have changed since
the menu was created.
The AL also defines a fixed, unique name (parameter AL_NAME) for each
resource. Names will always be fully qualified with the subsystem of the
resource, for example "RAD1.ADATIn" or "A2.CG2". This makes it the
preferred method of referring to a resource on the command-line or from a
shell script.
Most programs will accept names or labels interchangeably, because they
use alGetResourceByName(3dm) to look up the resources. See
alGetResourceByName(3dm) for information on how to search for resources
by name, by label, or by type.
alParams(3dm), alSetParams(3dm), alGetParams(3dm), alGetParamInfo(3dm),
alQueryValues(3dm)
PPPPaaaaggggeeee 6666 [ Back ]
|
