
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.

----------------------------------------------------------------------------------------------------------------------
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
-----------------------
Building this implementation of OpenAL for Mac OSX requires the CoreAudio SDK that accompanies the XCode 2.2 or greater developer release.
-----------------------

    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:
----------------------------------------------------------------------------------------------------------------------


	ALenum  alcASAGetSource (const ALuint property, ALuint source, ALvoid *data, ALuint* dataSize);
	ALenum  alcASASetSource (const ALuint property, ALuint source, ALvoid *data, ALuint dataSize);
	
	ALenum  alcASAGetListener (const ALuint property, ALvoid *data, ALuint* dataSize);
	ALenum  alcASASetListener (const ALuint property, ALvoid *data, ALuint dataSize);

	/* LISTENER properties */
		
		ALC_ASA_REVERB_ON			// type ALboolean
		ALC_ASA_REVERB_GLOBAL_LEVEL		// type ALfloat	-40.0 db - 40.0 db
		
		ALC_ASA_REVERB_ROOM_TYPE		// type ALint (see list of room types below)
		
			/* reverb room type presets for the ALC_ASA_REVERB_ROOM_TYPE property */
			ALC_ASA_REVERB_ROOM_TYPE_SmallRoom
			ALC_ASA_REVERB_ROOM_TYPE_MediumRoom
			ALC_ASA_REVERB_ROOM_TYPE_LargeRoom
			ALC_ASA_REVERB_ROOM_TYPE_MediumHall
			ALC_ASA_REVERB_ROOM_TYPE_LargeHall
			ALC_ASA_REVERB_ROOM_TYPE_Plate
			ALC_ASA_REVERB_ROOM_TYPE_MediumChamber
			ALC_ASA_REVERB_ROOM_TYPE_LargeChamber
			ALC_ASA_REVERB_ROOM_TYPE_Cathedral
			ALC_ASA_REVERB_ROOM_TYPE_LargeRoom2
			ALC_ASA_REVERB_ROOM_TYPE_MediumHall2
			ALC_ASA_REVERB_ROOM_TYPE_MediumHall3
			ALC_ASA_REVERB_ROOM_TYPE_LargeHall2

		ALC_ASA_REVERB_PRESET			// type ALchar* - path to an .aupreset file containing a Matrix Reverb preset file

		/* Reverb EQ Properties - contained in aupreset files or settable at runtime */
		ALC_ASA_REVERB_EQ_GAIN			// type ALfloat
		ALC_ASA_REVERB_EQ_BANDWITH		// type ALfloat
		ALC_ASA_REVERB_EQ_FREQ			// type ALfloat

		ALC_ASA_REVERB_QUALITY			// type ALint (see list of qualities below)
	
			/* reverb quality settings for the ALC_ASA_REVERB_QUALITY property */
			ALC_ASA_REVERB_QUALITY_Max
			ALC_ASA_REVERB_QUALITY_High
			ALC_ASA_REVERB_QUALITY_Medium
			ALC_ASA_REVERB_QUALITY_Low
			ALC_ASA_REVERB_QUALITY_Min
	
	/* SOURCE properties */
		ALC_ASA_REVERB_SEND_LEVEL		// type ALfloat	0.0 (dry) - 1.0 (wet) (0-100% dry/wet mix, 0.0 default)
		ALC_ASA_OCCLUSION			// type ALfloat	-100.0 db (most occlusion) - 0.0 db (no occlusion, 0.0 default)
		ALC_ASA_OBSTRUCTION			// type ALfloat	-100.0 db (most obstruction) - 0.0 db (no obstruction, 0.0 default)	


----------------------------------------------------------------------------------------------------------------------
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.
----------------------------------------------------------------------------------------------------------------------

	ALvoid	alBufferDataStatic (const ALint bid, ALenum format, ALvoid* data, ALsizei size, ALsizei freq);

----------------------------------------------------------------------------------------------------------------------
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)


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