
February 13th, 2004 - Apple Computer Inc.
updated: March 15th, 2004 - Apple Computer Inc.
updated: July 1st, 2005 - Apple Computer Inc.
updated: July 25, 2006 - Apple Computer Inc.
updated: April 20, 2010 - Apple Inc.

----------------------------------------------------------------------------------------------------------------------
READ ME: OPENAL - MAC OS X IMPLEMENTATION USING THE 3DMIXER AUDIOUNIT
----------------------------------------------------------------------------------------------------------------------

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

CoreAudio SDK Requirements
-----------------------

The accompanying XCode project is setup for building on Mac OS X 10.6 (or greater), and XCode 3.x (or greater). To build
on prior OS/XCode release, the path to the Public Utility folder should be changed in the XCode project to:

	/Developer/Extras/CoreAudio/PublicUtility

-----------------------

    Recommended:
    ------------
    MAC OS X: version 10.4.7 or later (These systems include v2.2 3DMixer AudioUnit needed to support the ASA (Apple Spatial Audio extension)
    
    Minimum:
    ------------
    OSX: version 10.2.8 (Jaguar) AND
    QuickTime: version 6.4

----------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------
OpenAL Extensions:

This implementation has the following OpenAL extensions. 
Function Prototypes Typedefs and Constant for all of these extensions can be found in the MacOSX_OALExtensions.h header.
----------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------
ALC_EXT_ASA - Apple Spatial Audio Extension

The ASA Extension is for providing Reverb, Occlusion and Obstruction spatial effects. It consists of 4 APIs:  Get/Set
functions for both the Listener and Source objects. Property constants are defined in the MacOSX_OALExtensions.h header
and can(should) really be obtained via alGetEnumValue() API. These constanst are described below:
----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------
ALC_EXT_ASA_ROGER_BEEP - Apple Spatial Audio Extension for Roger Beep Effect

Roger Beep : an effect to simulate effects such as Walkie Talkie noise. It is designed to replace the source audio data 
with a specific 'tone' when falling below a specified db threshold for a specified time. This Extension will be present 
when the Roger Beep Audio Unit is present on the system (10.5 or greater) Use the alcASAGetSource() and alcASASetSource() 
APIs in the ALC_EXT_ASA extension.
----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------
ALC_EXT_ASA_DISTORTION - Apple Spatial Audio Extension for Distortion Effect

This Extension will be present when the Distortion Audio Unit is present on the system (10.5 or greater)
Use the alcASAGetSource() and alcASASetSource() APIs in the ALC_EXT_ASA extension.
----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------
AL_EXT_STATIC_BUFFER - Static Buffer Extension

This extension allows the OpenAL application to own the audio data memory used by the OALBuffer object. This eliminates 
the need for the OpenAL library to do a memcpy of the audio data into it's own buffer memory. Use of this API has
the same contract as alBufferData(). In other words, the call will fail when the buffer object is marked as pending
in a source queue.
----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------
ALC_EXT_MAC_OSX - Apple Mac OSX Extension

This extension allows the OpenAL application some control of the CoreAudio engine that the implementation is based upon.
Many of these features existed in the 1.0 implementation via defines in the al.h and alc.h headers. In the 1.1
implementation, they are exposed in the formal OpenAL extension mechanism. In other words, functions should
be obtained at runtime via alGetProcAddress(). Existing 1.0 applications that used these features will continue
to run for compatibility.
----------------------------------------------------------------------------------------------------------------------


 RENDERING QUALITY  
Allows the application to specify the quality of spatial rendering to better suit the resources of the CPU.
At this time, the quality settings are only applied when rendering to stereo hw. All multichannel rendering uses the same 
spatialization setting on the 3DMixer.
                                                    
note: This implementation applies the setting to all the OAL Sources of an OAL Context. 
note: Currently, all stereo sounds are 'passed thru' with no spatial rendering applied. This has the best output quality for rendering
what are typically background sound tracks.

Available via these Get/Set APIs:

	ALvoid alcMacOSXRenderingQuality (const ALint value);
	ALint alcMacOSXGetRenderingQuality ();

	Provided setting constants:    	ALC_SPATIAL_RENDERING_QUALITY_HIGH  (HRTF)
                                        ALC_SPATIAL_RENDERING_QUALITY_LOW   (EqualPowerPanning)


 RENDER CHANNEL COUNT  
Because the audio system has no way to know if a user has actually connected a speaker to an output of the audio hardware, it may be desired
to allow the user to clamp all rendering to stereo.

Available via these Get/Set APIs:

	ALvoid alMacOSXRenderChannelCount (const ALint value);
	ALint alMacOSXGetRenderChannelCount ();

	Provided setting constants:    ALC_RENDER_CHANNEL_COUNT_STEREO         (clamp the 3DMixer output rendering to stereo, regardless of the hw capabilities)
                                       ALC_RENDER_CHANNEL_COUNT_MULTICHANNEL   (try and render to the maximum speakers possible by interrogating the device) 

 MIXER OUTPUT RATE  
Allows the developer to let the AudioGraph be efficient about sample rate conversion. If for example, all sounds
being played have a sample rate of 44k, but the output hardware is set to 48k, then it is best for the 3DMixer to leave the
the audio data (Mixer Outputut Rate)  at 44k, letting the output AU rate convert the streams after they have been mixed.

Available via these Get/Set APIs:

	ALvoid alcMacOSXMixerOutputRate (const ALdouble value);
	ALdouble alcMacOSXGetMixerOutputRate ();

 MAXIMUM MIXER BUSSES  
Allows the developer to optimize the 3DMixer by setting it's available input bus count. This allows the 3DMixer to be as
efficient as possible in resource allocations. By default, the 3DMixer currently defaults to 64 busses (note: the 1.3 version of the
3DMixer does not respect this setting, so always confirm the bus count with a get call, after setting the bus count and creating a new device). 
Use: set the bus count before making a call to alOpenDevice(). This will cause the library to set the mixer to your desired bus count,
as it sets up the 3DMixer AudioUnit

	ALvoid alcMacOSXMixerMaxiumumBusses (const ALint value);
	ALint alcMacOSXGetMixerMaxiumumBusses ();


 ALC_CONVERT_DATA_UPON_LOADING  
This setting 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 feature is toggled on/off by using the alDisable() & alEnable() APIs. This setting will be applied to all subsequent 
calls to alBufferData(). (note: will not be applied when using the alBufferDataStatic() extension API)


----------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------
