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 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 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 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 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 MISCELLANEOUS alGetErrorString(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 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