alResources(3dm) alResources(3dm) NAME alResources - Audio Library resources OVERVIEW 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. RESOURCE IDS 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. RESOURCE TYPES 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, clock- generators, 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 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: RAD Built-in audio on the Octane and Onyx2, and as a Professional Option Card. MAD Built-in audio on the Tezro, and as an option on the Onyx350 and Onyx4. A3 Built-in audio on the O2. EMU Audio option on the Fuel, Onyx350, and Onyx4. USB Audio option on the Fuel. DEVICES 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 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. 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. INTERFACES 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 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. PORTS 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. CONNECTIONS 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 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. 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 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. SEE ALSO alParams(3dm), alSetParams(3dm), alGetParams(3dm), alGetParamInfo(3dm), alQueryValues(3dm) Page 6