*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> audio/alResources (3d)              


alResources(3dm)					      alResources(3dm)

NAME    [Toc]    [Back]

     alResources - Audio Library resources

OVERVIEW    [Toc]    [Back]

     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 IDS    [Toc]    [Back]

     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    [Toc]    [Back]

     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 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

     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

     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.

DEVICES    [Toc]    [Back]

     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

     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

     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.


     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

INTERFACES    [Toc]    [Back]

     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.

PORTS    [Toc]    [Back]

     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    [Toc]    [Back]

     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.


     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:


     ports		     connections

     connections	     devices

     devices		     clock generators, interfaces

     clock generators	     master clocks

     subsystems		     devices

     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.

SEE ALSO    [Toc]    [Back]

     alParams(3dm), alSetParams(3dm), alGetParams(3dm),	alGetParamInfo(3dm),

									PPPPaaaaggggeeee 6666
[ Back ]
 Similar pages
Name OS Title
alConnect IRIX connect two audio I/O resources
alDisconnect IRIX delete a connection between two audio I/O resources
ALcloseport IRIX (obsolete) releases resources of an audio port
alParams IRIX Audio Library parameters
DTintro IRIX Introduction to the Silicon Graphics DAT Audio Library (DT)
alGetErrorString IRIX get a string corresponding to an Audio Library error code
CDintro IRIX Introduction to the Silicon Graphics CD Audio Library (CD)
cl_aware IRIX Aware Audio Schemes in the Compression Library
alIntro IRIX Introduction to the Silicon Graphics Audio Library (AL)
CLintro IRIX A library for working with compressed video and audio data
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service