Introduction

OpenAL Xtra is a free, open source scripting Xtra for Macromedia Director that extends Lingo with the basic functions of OpenAL, a cross-platform 3D audio API. With the OpenAL Xtra, a Director developer can arrange sounds around a virtual listener in a simulated, three-dimensional space.

This document aims to describe the setup and syntactical usage of the OpenAL Xtra. For an explanation of OpenAL concepts and other useful information that will hopefully help you to use this Xtra effectively please refer to the OpenAL documentation available from the OpenAL website at http://www.openal.org.

OpenAL Xtra Online Resources

The OpenAL Xtra project is hosted by SourceForge. For the latest release, support, documentation or to network with other OpenAL Xtra users please visit the OpenAL Xtra project page at http://sourceforge.net/projects/openalxtra/

For more information on the OpenAL API on which OpenAL Xtra is based, please visit the OpenAL web site at http://www.openal.org.

Installation

OpenAL Runtime

OpenAL Xtra requires an OpenAL runtime to be installed. Some functions require that the OpenAL runtime implementation be compliant with the OpenAL 1.1 specification. For OpenAL runtimes, please visit the OpenAL website at http://www.openal.org.

Windows

Decompress the binary distribution archive and copy the OpenAL.x32 file to your Xtra’s folder and restart Director. That’s it. If you have an earlier version of the OpenAL.x32 file, be sure to remove or replace it.

These are the default locations for the Xtra folder in Director 8.5 and Director MX:

Director 8.5: C:\Program Files\Macromedia\Director 8.5\Xtras

Director MX: C:\Program Files\Macromedia\Director MX\Xtras

Add the OpenAL Xtra to your Director movie.

Initialization and Shutting Down

alxInit

Initializes the OpenAL subsystem. This call must be made before any other function calls.

alxShutdown

Shuts down the OpenAL subsystem. This call should appear after you are done using the OpenAL_XTRA (usually at the end of the movie). It releases all memory used by the OpenAL subsystem. It is important to call this at the end of your movie while you are inside Director. In addition to unloading the OpenAL subsystem, it also effectively calls alxReleaseSound() for each cast member.

Distance Model

The attenuation by distance of sound sources is affected by the distance model in use. The distance model has a global effect on all sound sources. For a detailed explanation of distance models, please consult the OpenAL documentation at http://www.openal.org/.

OpenAL Xtra currently supports the three distance models defined by OpenAL 1.0. The additional distance models added by OpenAL 1.1 will be supported in a future release. The following symbols identify the supported models:

#alxNone

Bypasses distance attenuation for all sound sources.

#alxInverseDistance

Inverse distance attenuation described by the following formula:

Gain = ReferenceDistance / (ReferenceDistance + RolloffFactor * (Distance – ReferenceDistance)

#alxInverseDistanceClamped

Essentially the #alxInverseDistance model extended to guarantee that for distances below the ReferenceDistance, gain is clamped.

alxSetDistanceModel modelID

Sets the global distance model.

Parameters:
modelID	The symbol representing the model to be set.

modelID alxGetDistanceModel()

Gets the symbol representing the active global distance model.

Results:

The symbol representing the active distance model.

OpenAL Version Properties

majorVersion alxGetOpenALMajorVersion()

Gets the major version number of the underlying OpenAL runtime. Example: if the OpenAL runtime is version 1.0, the return value would be 1.

Results:

The major version number of the underlying OpenAL runtime.

minorVersion alxGetOpenALMinorVersion()

Gets the minor version number of the underlying OpenAL runtime. Example: if the OpenAL runtime is version 1.0, the return value would be 0.

Results:

The minor version number of the underlying OpenAL runtime.

supportsOffset alxHasExtensionOffset()

Indicates if the underlying OpenAL runtime supports the getting and setting of the sound offset position. Support is present in OpenAL 1.1, but may also be supported by extensions to OpenAL 1.0.

Results:

True (1) if offset functions are supported; otherwise False (0).

Listener Properties

Listener Gain

alxSetListenerGain gain

Sets the global gain applied to all sounds. A gain of 0 effectively mutes the sound. A gain of 1 applies no attenuation. A value between 0 and 1 scales the volume in a linear fashion. Some OpenAL implementations permit values greater than one, effectively amplifying the original sounds.

Parameters:
gain	The gain multiplier for the sound [0..1].

gain alxGetListenerGain()

Gets the global gain applied to all sounds. A gain of 0 effectively mutes the sound. A gain of 1 applies no attenuation. A value between 0 and 1 scales the volume in a linear fashion. Some OpenAL implementations permit values greater than one, effectively amplifying the original sounds.

Results:

The gain multiplier for the sound [0..1].

Listener Position

alxSetListenerPosition vector

Sets the listener’s position in 3D space.

Parameters:
vector	A list of 3 numbers representing the listener’s spatial position.

vector alxGetListenerPosition()

Gets the listener’s position in 3D space.

Results:

A list of 3 numbers representing the listener’s spatial position.

Listener Direction

alxSetListenerDirection vector

Sets the listener’s direction vector in 3D space. The direction vector, along with the up vector specify the listeners orientation.

Parameters:
vector	A list of 3 numbers representing the listener’s direction vector.

vector alxGetListenerDirection()

Gets the listener’s direction vector in 3D space. The direction vector, along with the up vector specify the listeners orientation.

Results:

A list of 3 numbers representing the listener’s direction vector.

Listener Up

alxSetListenerUp vector

Sets the listener’s up vector in 3D space. The up vector, along with the director vector specify the listeners orientation.

Parameters:
vector	A list of 3 numbers representing the listener’s up vector.

vector alxGetListenerUp()

Gets the listener’s up vector in 3D space. The up vector, along with the director vector specify the listeners orientation.

Results:

A list of 3 numbers representing the listener’s up vector.

Listener Velocity

alxSetListenerVelocity

Sets the sound's velocity. The velocity is used to calculate Doppler effects - the listener’s position is not changed over time.

Parameters:
vector	A list of 3 numbers representing the listener’s velocity.

vector alxGetListenerVelocity

Gets the sound's velocity. The velocity is used to calculate Doppler effects - the listener’s position is not changed over time.

Results:

A list of 3 numbers representing the listener’s velocity.

Creating and Releasing Sounds

Because all of the sound data is stored in Director cast members, you must first load the sound data into the OpenAL Xtra before it can be played. Sounds are loaded by passing an explicit cast member reference to alxCreateSound(), which returns a sound id that is passed to other OpenAL functions.

Audio cast members must be mono WAV format.

All created sounds are released when alxShutdown() is invoked.

sound_id alxCreateSound( cast_member )

Loads the sound data in the cast member identified by cast_member. This call must be made for each cast member that contains sound data.

Parameters:
cast_member	An explicit reference to a sound cast member.

Results:

A handle to the created sound.

alxReleaseSound sound_id

Releases a sound created by alxCreateSound. All sounds are also released by alxShutdown, thus if you call alxShutdown when your movie ends and don’t have need to free memory while the movie is executing, you need not call alxReleaseSound for each created sound.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Playing Sounds

alxPlaySound sound_id

Starts playback of the sound buffer.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

alxStopSound sound_id

Stops playback of the sound buffer. The position is reset to the beginning of the audio.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

alxPauseSound sound_id

Pauses playback of the sound buffer.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

alxRewindSound sound_id

Resets the playback position to the beginning of the sound buffer.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

alxSetSoundLoop sound_id, will_loop

Sets whether the sound will loop when playback of the suffer is complete. If will_loop evaluates to true (not 0), the sound will loop, otherwise it will not loop.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
will_loop	Boolean interpreted value indicating if the sound is to loop.

will_loop alxGetSoundLoop( sound_id )

Gets whether the sound will loop when playback of the buffer is complete. If the return value is true (1), the sound will loop, if false (0) the sound will not loop.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

True (1) if the sound is set to loop, otherwise false (0).

alxSetSoundOffset sound_id, seconds

Sets the current playback position of the sound buffer.

This function requires a OpenAL 1.1 or an extension of OpenAL 1.0.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
seconds	Offset into the sound buffer for the new playback position.

seconds alxGetSoundOffset( sound_id )

Gets the current playback position of the sound buffer.

This function requires a OpenAL 1.1 or an extension of OpenAL 1.0.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

Offset into the sound buffer of the current playback position.

Sound Properties

Sound Source Volume

alxSetSoundGain sound_id, gain

Sets the gain (volume) of the sound source. A gain of 0 effectively mutes the sound. A gain of 1 plays the sound at full recorded volumes. A value between 0 and 1 scales the volume in a linear fashion. Some OpenAL implementations permit values greater than one, effectively amplifying the original sound.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
gain	The gain multiplier for the sound [0..1].

gain alxGetSoundGain( sound_id )

Gets the gain (volume) of the sound source. A gain of 0 effectively mutes the sound. A gain of 1 plays the sound at full recorded volumes. A value between 0 and 1 scales the volume in a linear fashion. Some OpenAL implementations permit values greater than one, effectively amplifying the original sound.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The gain multiplier for the sound [0..1].

Sound Source Position

alxSetSoundPosition sound_id, vector

Sets the sound source’s position in 3D space.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
vector	A list of 3 numbers representing the sound source’s spatial position.

vector alxGetSoundPosition( sound_id )

Gets the sound source’s position in 3D space.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

A list of 3 numbers representing the sound source’s spatial position.

Sound Source Relative Position

alxSetSoundSourceRelative sound_id, is_relative

Sets whether the sound sources position should be set relative to the listener. If the return value is true (1), the sound source will move with the listener, if false (0) the sound source position is absolute.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
is_relative	True (1) if the sound source’s position is relative to the listeners.

is_relative alxGetSoundSourceRelative ( sound_id )

Gets whether the sound sources position should be set relative to the listener. If the return value is true (1), the sound source will move with the listener, if false (0) the sound source position is absolute.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

True (1) if the sound source’s position is relative to the listeners.

Sound Source Velocity

alxSetSoundVelocity sound_id, vector

Sets the sound's velocity. The velocity is used to calculate Doppler effects - the sound's position is not changed over time.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
vector	A list of 3 numbers representing the sound source’s velocity vector.

vector alxGetSoundVelocity( sound_id )

Gets the sound's velocity. The velocity is used to calculate Doppler effects - the sound's position is not changed over time.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

A list of 3 numbers representing the sound source’s velocity vector.

Bounds on Sound Source Volume

The functions below set and get minimum and maximum gains for a sound source. At the end of the processing of various attenuation factors such as inverse distance based attenuation and source gain, the effective gain is compared to these minimum and maximum values and bound if necessary.

alxSetSoundMinGain sound_id, gain

Sets the minimum gain (volume) of the sound source.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
gain	The minimum gain for the sound.

gain alxGetSoundMinGain( sound_id )

Gets the minimum gain (volume) of the sound source.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The minimum gain for the sound.

alxSetSoundMaxGain sound_id, gain

Sets the maximum gain (volume) of the sound source.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
gain	The maximum gain for the sound.

gain alxGetSoundMaxGain( sound_id )

Gets the maximum gain (volume) of the sound source.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The maximum gain for the sound.

Sound Source Direction and Cone

Each source can be directional, depending on the settings set by alxSetSoundInnerConeAngle and alxSetSoundOuterConeAngle. There are three zones defined: the inner cone, the outside zone, and the transitional zone in between. The angle-dependent gain for a directional source is constant inside the inner cone, and changes over the transitional zone to the value specified outside the outer cone. Source gain level as set by alxSetSoundGain is applied for the inner cone, with an application selectable outer gain factor that may be set by alxSetSoundOuterConeGain. In the transitional zone OpenAL-implementation-dependent interpolation between source gain and source gain times outer cone gain is applied.

alxSetSoundDirection sound_id, vector

Sets the sound's direction in 3D space.

The zero vector is default, indicating that a source is not directional. Specifying a nonzero vector will make the source directional. Specifying a zero vector for a directional source will effectively mark it as non-directional.

The sound emission is presumed to be symmetric around the direction vector (cylinder symmetry). Sources are not oriented in full 3 degrees of freedom, only two angles are effectively needed.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
vector	A list of 3 numbers representing the sound source’s direction vector.

vector alxGetSoundDirection( sound_id )

Gets the sound's direction in 3D space.

The zero indicates that a source is not directional.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

A list of 3 numbers representing the sound source’s direction vector.

alxSetSoundInnerConeAngle sound_id, angle

Sets the sound's inner cone angle. The default of 360 degrees indicates that the sound is omni directional.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
angle	The angle for the cone.

angel alxGetSoundInnerConeAngle ( sound_id )

Gets the sound's inner cone angle. The default of 360 degrees indicates that the sound is omni directional.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The angle for the cone.

alxSetSoundOuterConeAngle sound_id, angle

Sets the sound's outer cone angle. The default of 360 degrees indicates that the sound is omni directional. If the inner cone angle is also 360 then the zone for angle-dependent attenuation is zero.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
angle	The angle for the cone.

angle alxGetSoundOuterConeAngle ( sound_id )

Gets the sound's outer cone angle. The default of 360 degrees indicates that the sound is omni directional. If the inner cone angle is also 360 then the zone for angle-dependent attenuation is zero.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The angle for the cone.

alxSetSoundOuterConeGain sound_id, gain_factor

Sets the sound's outer cone gain factor. This is the factor with which the sound source gain set by alxSetSoundGain is multiplied to determine the effective gain outside the cone defined by the outer angle.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
gain_factor	The gain factor applied outside the outer cone.

gain_factor alxGetSoundOuterConeGain ( sound_id )

Gets the sound's outer cone gain factor. This is the factor with which the sound source gain set by alxSetSoundGain is multiplied to determine the effective gain outside the cone defined by the outer angle.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The gain factor applied outside the outer cone.

Sound Source Distance Model Properties

These attributes affect the sound differently depending on the distance model in use. The distance model is set with alxSetDistanceModel.

alxSetSoundReferenceDistance sound_id, distance

Sets the sound's reference distance. The reference distance is used in distance attenuation based on inverse distance with roll off. Depending on the distance model it will also act as a distance threshold below which gain is clamped.

Please read the section on Distance Models in the OpenAL documentation for details.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
distance	The reference distance.

distance alxGetSoundReferenceDistance ( sound_id )

Gets the sound's reference distance. The reference distance is used in distance attenuation based on inverse distance with roll off. Depending on the distance model it will also act as a distance threshold below which gain is clamped.

Please read the section on Distance Models in the OpenAL documentation for details.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The reference distance.

alxSetSoundRolloffFactor sound_id, factor

Sets the sound's roll off factor. The roll off factor is used in distance attenuation based on inverse distance with roll off. For distances smaller than the max distance (set with alxSetSoundMaxDistance), and depending on the distance model, distances larger than the reference distance (set with alxSetSoundReferenceDistance) this will scale the distance attenuation over the applicable range.

The roll off factor can be set to 0 for sounds that should be exempt from distance attenuation.

Please read the section on Distance Models in the OpenAL documentation for details.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
factor	The roll off factor.

factor alxGetSoundRolloffFactor ( sound_id )

Gets the sound's roll off factor. The roll off factor is used in distance attenuation based on inverse distance with roll off. For distances smaller than the max distance (set with alxSetSoundMaxDistance), and depending on the distance model, distances larger than the reference distance (set with alxSetSoundReferenceDistance) this will scale the distance attenuation over the applicable range.

Please read the section on Distance Models in the OpenAL documentation for details.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The roll off factor.

alxSetSoundMaxDistance sound_id, distance

Sets the sound's max distance. The max distance is used in distance attenuation based on inverse distance with roll off if the Inverse Clamped Distance Model is used. Distances greater than max distance will be clamped to max distance.

Please read the section on Distance Models in the OpenAL documentation for details.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
distance	The max distance.

distance alxGetSoundMaxDistance ( sound_id )

Gets the sound's max distance. The max distance is used in distance attenuation based on inverse distance with roll off if the Inverse Clamped Distance Model is used. Distances greater than max distance will be clamped to max distance.

Please read the section on Distance Models in the OpenAL documentation for details.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The max distance.

Sound Source Pitch

alxSetSoundPitch sound_id, freqMultiplier

Sets the pitch shift applied to the sound. A setting of 1.0 had no effect. Each reduction by 50 percent equals a one octave reduction in pitch. Each doubling of the pitch equals a one octave increase in pitch.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.
freqMultipliert	The Pitch multiplier.

freqMultilier alxGetSoundPitch( sound_id )

Gets the pitch shift applied to the sound. A setting of 1.0 had no effect. Each reduction by 50 percent equals a one octave reduction in pitch. Each doubling of the pitch equals a one octave increase in pitch.

Parameters:
sound_id	The handle to a sound created by a previous call to alxCreateSound.

Results:

The Pitch multiplier.

Error Handling

All OpenAL Xtra functions return the symbol #alxError in the event of error. A string describing the last error can be retrieved by calling alxGetLastError().

string alxGetLastError()

Gets a string describing the last error condition.

Results:

A string describing the last error condition.

Function Index

alxCreateSound

alxGetDistanceModel

alxGetLastError

alxGetListenerDirection

alxGetListenerGain

alxGetListenerPosition

alxGetListenerUp

alxGetListenerVelocity

alxGetOpenALMajorVersion

alxGetOpenALMinorVersion

alxGetSoundDirection

alxGetSoundPitch

alxGetSoundGain

alxGetSoundInnerConeAngle

alxGetSoundLoop

alxGetSoundMaxDistance

alxGetSoundMaxGain

alxGetSoundMinGain

alxGetSoundOffset

alxGetSoundOuterConeAngle

alxGetSoundOuterConeGain

alxGetSoundPosition

alxGetSoundReferenceDistance

alxGetSoundRolloffFactor

alxGetSoundSourceRelative

alxGetSoundVelocity

alxHasExtensionOffset

alxSetListenerDirection

alxSetListenerGain

alxSetListenerPosition

alxSetListenerUp

alxSetListenerVelocity

alxSetSoundDirection

alxSetSoundPitch

alxSetSoundGain

alxSetSoundInnerConeAngle

alxSetSoundLoop

alxSetSoundMaxDistance

alxSetSoundMaxGain

alxSetSoundMinGain

alxSetSoundOffset

alxSetSoundOuterConeAngle

alxSetSoundOuterConeGain

alxSetSoundPosition

alxSetSoundReferenceDistance

alxSetSoundRolloffFactor

alxSetSoundSourceRelative

alxSetSoundVelocity

alxStopSound

Credits

OpenAL Xtra comes out of the Georgia Tech College of Computing's Augmented Environments Lab, where it is a component of DART, the Designers Augmented Reality Toolkit . DART is in impressive testament to the power and flexibility of Macromedia Director—check it out!

The current version of OpenAL Xtra was written by Jeremy Johnson of Georgia Tech’s Interactive Media Technology Center, based on the original code of Russ Morris.

Portions of this documentation are based on the OpenAL 1.1 specification, available from http://www.openal.org/.

OpenAL is a trademark of Creative Labs, Inc.

Contents

Introduction

OpenAL Xtra Online Resources

Installation

Initialization and Shutting Down

OpenAL Version Properties

Listener Properties

Creating and Releasing Sounds

Playing Sounds

Sound Properties

Error Handling

Function Index

Credits