alParams man page on IRIX

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



alParams(3dm)							 alParams(3dm)

NAME
     alParams - Audio Library parameters

DESCRIPTION
     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
     alDeselectEvents(3dm).

PARAMETERS AND VALUES
     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
		     fixed-point.

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

     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
     alGetEventValue(3dm).

UNIVERSAL PARAMETERS
     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
		     information.

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

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

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

     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)	      */
		     }ALsetChangeInfo;

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

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

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

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

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

     AL_PORT_COUNT   (32-bit integer, get only)
		     The number of ports currently open against this device.

     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.

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

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

									Page 5

alParams(3dm)							 alParams(3dm)

		     specifications for the transmission of digital audio
		     signals. For ADAT subcode, this value is 4.

     AL_SUBCODE_CHANNELS
		     (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 multi-
		     channel frame of subcode data.

     AL_AES_CHANNEL_STATUS, AL_AES_USER, AL_AES_VALIDITY
		     (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(3dm) 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.

INTERFACE PARAMETERS
     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.

									Page 6

alParams(3dm)							 alParams(3dm)

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

		     Some interfaces only support a gain of negative infinity
		     decibels (mute) when all channels are set to
		     AL_NEG_INFINITY. These interfaces will have
		     AL_GLOBAL_MUTE_BIT 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
		     interfaces).

		     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

									Page 7

alParams(3dm)							 alParams(3dm)

		     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,
		     respectively.

     AL_TYPE	     (32-bit integer, get)
		     The type of the interface. All are subtypes of
		     AL_INTERFACE_TYPE. Digital interfaces will be subtypes of
		     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.

CLOCK-GENERATOR PARAMETERS
     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 clock-
		     generator. 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
		     representations.

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

									Page 8

alParams(3dm)							 alParams(3dm)

     AL_RATE_FRACTION_N, AL_RATE_FRACTION_D
		     (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.

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

MASTER-CLOCK PARAMETERS
     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
		     changes.

     AL_TYPE	     (int, get only)
		     The type of the master clock. All are subtypes of
		     AL_MCLK_TYPE.  Fixed-rate master clocks, such as video-
		     based 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_VARIABLE_MCLK_TYPE.

     AL_LOCKED	     (int, get only)
		     This parameter is 1 if the master clock is locked and 0
		     if the master clock is unlocked.  This parameter applies
		     only to variable-rate master clocks (those with type
		     AL_VARIABLE_MCLK_TYPE), such as those derived from AES

									Page 9

alParams(3dm)							 alParams(3dm)

		     and ADAT sources.	Master clocks for digital inputs are
		     locked if a valid source is connected.

     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.

CONNECTION PARAMETERS
     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.

     AL_DEST	     (resource, get only)
		     The destination of the connection.

EXAMPLES
SEE ALSO
     alSetParams(3dm), alGetParams(3dm), alGetParamInfo(3dm),
     alQueryValues(3dm)

								       Page 10

[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