alResources man page on IRIX

Man page or keyword search:  
man Server   31559 pages
apropos Keyword Search (all sections)
Output format
IRIX logo
[printable version]



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:

									Page 1

alResources(3dm)					      alResources(3dm)

     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.

									Page 2

alResources(3dm)					      alResources(3dm)

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.

									Page 3

alResources(3dm)					      alResources(3dm)

     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.

									Page 4

alResources(3dm)					      alResources(3dm)

     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

									Page 5

alResources(3dm)					      alResources(3dm)

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

[top]

List of man pages available for IRIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net