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

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


alParams(3dm)							 alParams(3dm)

NAME    [Toc]    [Back]

     alParams -	Audio Library parameters

DESCRIPTION    [Toc]    [Back]

     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


     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

     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

     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


     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

     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.

SYSTEM PARAMETERS    [Toc]    [Back]

     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.

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

		     (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

     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)	      */

									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

     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.

DEVICE PARAMETERS    [Toc]    [Back]

     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

     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

		     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

									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

     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.

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

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

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

		     (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

		     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,

     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.

     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

		     Note:In general, the master clock should be specified
		     when the rate is changed.

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

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


     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.

EXAMPLES    [Toc]    [Back]

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

								       PPPPaaaaggggeeee 11110000
[ Back ]
 Similar pages
Name OS Title
afQuery IRIX retrieve static parameters associated with the Audio File Library formats
AFinitcompression IRIX configure the audio compression type and parameters in an AFfilesetup structure for an audio track
mvGetAudioWidth IRIX get and set the parameters of a an audio track
alGetParams IRIX get the values of audio resource parameters
dmSetAudioDefaults IRIX parameters for digital-media audio
alSetParams IRIX set the values of audio resource parameters
afSetConversionParams IRIX set/get the parameters associated with format conversion for a specified audio track via dmParams
AFgetcompression IRIX get the compression type and parameters for an audio track from an AFfilehandle structure
alResources IRIX Audio Library resources
alGetErrorString IRIX get a string corresponding to an Audio Library error code
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service