READ_ME   [plain text]


This Read Me should accompany the 3DMixer implementation of OpenAL (Open Audio Library). 

CoreAudio Version requirements
It is recommended that this implementation is run on MAC OS X SnowLeopard (10.6) or later. Certain features may not be
supported on older OS versions.

Xcode Version requirements
If Xcode 4.3 or later is installed, the CoreAudio Utility Classes must be installed at /Library/Developer
The CoreAudio Utility Classes can be obtained from the Mac OS X Developer Library located at the url

If the Xcode version is older than 4.3, the path to the PublicUtility folder in the OpenAL Xcode project file should be changed to

OpenAL Extensions:

This implementation has the following OpenAL extensions. More information on usage and setting specifics can be found in the 
MacOSX_OALExtensions.h header file.

The 'Apple Mac OSX Extension' contains various support for controlling aspects of Apple's OpenAL implementation that are specific to the platform.
The extension provides settings for:

	Rendering Quality 	- 	The Rendering Quality setting enables the application to specify from a number of available stereo/multi-channel 
					rendering algorithms.
	Channel Count 		- 	Apple's OpenAL implementation will render to stereo or multi-channel audio hardware based on the users system setup. 
					This setting can be used to force stereo rendering on a multi speaker audio system.
	Maximum Buses 		- 	This sets a maximum number of buses allocated by the system's 3DMixer AudioUnit, which provides the spatialized mixing of OpenAL
	Output Rate 		- 	Allows the application to optimize audio mixing performance based on the sampling rate of its audio assets (files)

This extension allows the caller to tell OpenAL to preconvert to the native CoreAudio format, the audio data passed to the 
library with the alBufferData() call. Preconverting the audio data, reduces CPU usage by removing an audio data conversion 
(per source) at render time at the expense of a larger memory footprint.

This extension provides a means for the caller to avoid the overhead associated with the alBufferData call which performs a physical copy 
of the data provided by the caller to internal buffers. When using the AL_EXT_STATIC_BUFFER extension, OpenAL's internal buffers use 
the data pointer provided by the caller for all data access.

Note: It is important that the caller does NOT free these buffers until OpenAL returns from alDeleteBuffers() without returning an error.

The ASA (Apple Spatial Audio) extension currently provides three main effects: reverb, occlusion and obstruction.

	Reverb:		A reverb effect with multiple presets and quality settings. Post EQ settings available for additional tonal control.

	Occlusion:	An effect that applies a low pass filter to an OpenAL source object for simulating objects 
			in different 'spaces' from the listener (post EQ, causing send to reverb to also be filtered)

	Obstruction:	An effect that applies a low pass filter to an OpenAL source object for simulating objects being 'obstructed' 
			from the listener (pre-EQ, allowing high frequencies of source object to remain in the reverb)

This extension allows use of the Roger Beep effect to simulate effects such as Walkie Talkie noise. Effect is activated when
the source audio data falls below a specified db threshold for a specified time.

This extension applies a distortion effect to a specified OpenAL source object. Different settings can be used to specify the style and 
degree of distortion applied.

**** AL_EXT_float32
The AL_EXT_float32 extension provides support for 32-bit float audio data (mono/stereo).

This extension provides an alternative to the OpenAL polling mechanism used for obtaining state about Source and Buffer objects. The caller subscribes to
the notification scheme by providing a callback function for the desired notification type. When a notification is received, the caller should then proceed
to get the current state using the native OpenAL api calls.

The available notification types are

	AL_SOURCE_STATE		- there is a change in the source's state
	AL_BUFFERS_PROCESSED	- there is a change in the number of buffers processed
	AL_QUEUE_HAS_LOOPED 	- the buffer queue has looped (if looping is enabled)