alIntro(3dm)alIntro(3dm)NAME
alIntro, audio - Introduction to the Silicon Graphics Audio Library (AL)
SYNOPSIS
#include <dmedia/audio.h>
-laudio
DESCRIPTION
The Silicon Graphics Audio Library (AL) provides a uniform, device-
independent programming interface to real-time audio I/O on Silicon
Graphics workstations.
The AL was designed to enable multiple programs to share the audio
resources of the workstation. Multiple programs may have input and output
streams open concurrently, either sharing audio devices or using
independent audio devices.
The Audio Library provides four major capabilities:
1. input and output of digital audio data
2. control of the attributes of the digital audio data
3. control of physical parameters of the audio subsystem
4. Audio subsystem event notification
The first two of these capabilities are briefly described in the section
"Basic I/O." The device control capabilities are described in the section
"Resources and Control." The audio event notification model is described
in the "Audio Events" section.
BASIC I/O
The basic data types for the Audio Library are ALconfig and ALport. An
application uses an ALconfig to define the attributes of the digital
audio data it wishes to send or receive. It then opens an ALport, which
actually writes or reads the audio data to or from the hardware.
The Audio Library includes the following functions:
alNewConfig(3dm) - create a new ALconfig
alFreeConfig(3dm) - free ALconfig
alSetConfig(3dm) - set an ALconfig on an existing ALport
alGetConfig(3dm) - get the ALconfig from an ALport
Page 1
alIntro(3dm)alIntro(3dm)alSetQueueSize(3dm) - set the sample queue size for an audio port
alGetQueueSize(3dm) - get the sample queue size for an audio port
alSetWidth(3dm) - set the sample wordsize for an audio port
alGetWidth(3dm) - get the sample wordsize for an audio port
alSetSampFmt(3dm) - set the sample data type and format for an
audio port
alGetSampFmt(3dm) - get the sample data type and format for an
audio port
alSetChannels(3dm) - set the number of channels for an audio port
alGetChannels(3dm) - get the number of channels for an audio port
alSetFloatMax(3dm) - set the max. amplitude of floating point data
for an AL port
alGetFloatMax(3dm) - get the max. amplitude of floating point data
for an AL port
alSetLimiting(3dm) - specify if limiting is required for floating-
point data
alGetLimiting(3dm) - determine whether or not limiting is specified
for an ALconfig
alOpenPort(3dm) - open an audio port and begin I/O
alClosePort(3dm) - close an audio port and stop I/O
alGetFilled(3dm) - get number of filled spots in an audio port
alGetFillable(3dm) - get number of fillable spots in an audio port
alReadFrames(3dm) - read interleaved sample frames from an audio
port
alWriteFrames(3dm) - write interleaved sample frames to an audio
port
alZeroFrames(3dm) - write zero-valued sample-frames to an output
audio port
alDiscardFrames(3dm) - discard data from an input or output audio
port
Page 2
alIntro(3dm)alIntro(3dm)alReadBuffers(3dm) - read flexibly interleaved or non-interleaved
sample frames from an audio port
alWriteBuffers(3dm) - write flexibly interleaved or non-interleaved
sample frames to an audio port
alGetFD(3dm) - get a file descriptor for an audio port, so
that one can use select(2) or poll(2) to block
waiting for a fillpoint
alSetFillPoint(3dm) - define audio port high-/low-water mark
(fillpoint) to unblock application
alGetFillPoint(3dm) - get the current fillpoint from an audio port.
alGetFrameNumber(3dm) - get the absolute sample frame number
associated with a port
alGetFrameTime(3dm) - get the time at which a sample frame came in
or will go out
RESOURCES AND CONTROL
The AL manages a number of hardware and software entities called
resources (see alResources(3dm) for a more detailed description).
Resources include devices, ports, clock generators, master clocks,
connections, interfaces, subsystems, and the system resource.
Applications can acquire or change the state of the audio resources
through the following functions:
alParams(3dm)
- general information about AL parameters
alGetParams(3dm)
- get parameter values from an audio resource
alSetParams(3dm)
- set parameter values on an audio resource
alGetParamInfo(3dm)
- find out what kinds of values a parameter can have on a specific
resource
alQueryValues(3dm)
- find the set of possible values for a discrete-valued parameter
alIsSubtype(3dm)
- determine if one resource type is a subtype of another
alGetResourceByName(3dm)
- find a resource with a given name
Page 3
alIntro(3dm)alIntro(3dm)alConnect(3dm)
- connect the output of one audio I/O resource to the input of
another
alDisconnect(3dm)
- disconnect one audio I/O resource from another
AUDIO EVENTS
The AL provides event notification for applications interested in
monitoring audio system changes. An audio event is represented by an
ALevent structure. This structure includes the parameter which changed
of event, the new parameter value in many cases, the time at which the
event was posted, and the sources of the event. Events are delivered to
each application via an ALeventQueue. Following is the list of event-
related functions:
alOpenEventQueue(3dm)
- Allocate and initialize an event queue
alCloseEventQueue(3dm)
- Deallocate a previously initialized event queue
alNewEvent(3dm)
- Allocate and initialize an event
alFreeEvent(3dm)
- Deallocate a previously initialized event
alSelectEvents(3dm)
- Select events to be received into event queue
alDeselectEvents(3dm)
- Deselect events from event queue
alGetEventQueueFD(3dm)
- Get file descriptor of event queue
alNextEvent(3dm)
- Retrieves the next event from an event queue
alCheckEvent(3dm)
- Check for a particular event in an event queue
alPendingEvents(3dm)
- Get the number of pending events in an event queue
alFlushEvents(3dm)
- Flush all events from event queue
alGetEventParam(3dm)
- Returns the event parameter
Page 4
alIntro(3dm)alIntro(3dm)alGetEventResource(3dm)
- Returns the id of the resource that posted the event
alGetEventSrcResource(3dm)
- Returns the id of the resource that generated the event
alGetEventUST(3dm)
- Returns the Unadjusted System Time of an event
alGetEventValue(3dm)
- Return the new value of the event parameter
alGetEventData(3dm)
- Returns a pointer to an event info struct
MISCELLANEOUSalGetErrorString(3dm)
- get a text message associated with an AL error return code
alDoubleToFixed(3dm)
- convert from double-precision to AL-format fixed-point
alFixedToDouble(3dm)
- convert from AL-format fixed-point to double-precision
alSetErrorHandler(3dm)
- specify a user-defined error handler, if desired
/usr/include/dmedia/audio.h - Audio Library header file
/usr/share/src/dmedia/audio/* - code examples
/usr/share/src/dmedia/soundcommands/* - code examples
/usr/share/src/dmedia/soundplayer/* - code examples
SEE ALSO
DOCUMENTATION:
Digital Media Programming Guide: Audio, MIDI, Video, and Compression
RELATED LIBRARIES:
AFintro(3dm) - Introduction to the Audio File Library
CDaudio(3) - Introduction to the audio Compact Disc library
DATaudio(3) - Introduction to the Digital Audio Tape Library
Page 5
alIntro(3dm)alIntro(3dm)mdIntro(3dm) - Introduction to the Silicon Graphics MIDI Library
(libmd)
IRIX Real-time Support:
select(2), sproc(2), setitimer(2), schedctl(2), prctl(2), poll(2),
mpin(2)
Page 6
