neo/openal/osx/OpenAL.framework/Versions/A/Resources/READ_ME

   1
   2 February 13th, 2004 - Apple Computer Inc.
   3 updated: March 15th, 2004 - Apple Computer Inc.
   4
   5 ----------------------------------------------------------------------------------------------------------------------
   6 READ ME: OPEN AL - OSX IMPLEMENTATION USING THE 3DMIXER AUDIOUNIT
   7 ----------------------------------------------------------------------------------------------------------------------
   8
   9 This Read Me should accompany the 3DMixer implementation of OpenAL (Open Audio Library).
  10
  11 CoreAUdio SDK Requirements
  12 -----------------------
  13 Building this implementation of OpenAL for Mac OSX requires the latest CoreAudio SDK (version 1.3.1), due to it use
  14 of new CoreAudio Public Utility classes.
  15
  16 CoreAudio Version requirements
  17 -----------------------
  18 There are Recommended and Minimum CoreAudio framework and component pieces for running this implementation
  19 of OpenAL for Mac OSX:
  20
  21     Recommended:
  22     ------------
  23     OSX: version 10.2.6 AND
  24     QuickTime: version 6.5.1
  25     AudioToolbox.framework (version 1.3.2)
  26     AudioUnit.framework (version 1.3.2)
  27     CoreAudio.component (version 1.3.2 - this version contains the 2.0 version of the 3DMixer AudioUnit)
  28
  29     Minimum:
  30     ------------
  31     OSX: version 10.2 (Jaguar) AND
  32     QuickTime: version 6.4
  33     AudioToolbox.framework (version 1.2xxxxx)
  34     AudioUnit.framework (version 1.2xxxxx)
  35     CoreAudio.component (version 1.2xxxxxx - this version contains the 1.3 version of the 3DMixer AudioUnit)
  36
  37 ----------------------------------------------------------------------------------------------------------------------
  38 OpenAL Extensions:
  39 ----------------------------------------------------------------------------------------------------------------------
  40
  41 This implementation has the following OpenAL extensions. These constants can be found in the included "alctypes.h" header.
  42
  43 ***** ALC_CONVERT_DATA_UPON_LOADING
  44 This extension allows the caller to tell OpenAL to preconvert to the native CoreAudio format, the audio data passed to the
  45 library with the alBufferData() call. Preconverting the audio data, reduces CPU usage by removing an audio data conversion
  46 (per source) at render timem at the expense of a larger memory footprint.
  47
  48 This feature is toggled on/off by using the alDisable() & alEnable() APIs. This setting will be applied to all subsequent
  49 calls to alBufferData().
  50
  51 ***** ALC_SPATIAL_RENDERING_QUALITY
  52 This extension allows the application to specify the quality of spatial rendering to better suit the resources of the CPU.
  53 At this time, the quality settings are only applied when rendering to stereo hw. All multichannel rendering uses the same
  54 spatilaization setting on the 3DMixer. Use the alSetInteger() & alGetInteger() APIs to specify and retrieve this setting.
  55 This implmentation provides 2 setting constants:    ALC_SPATIAL_RENDERING_QUALITY_HIGH  (HRTF)
  56                                                     ALC_SPATIAL_RENDERING_QUALITY_LOW   (EqualPowerPanning)
  57
  58 note: This implementation applies the setting to all the OAL Sources of an OAL Context. However, spatial settings can be applied to
  59 each input bus of the 3DMixer, so it is possible to have this setting on a per OAL Source basis, allowing the developer to give
  60 quality priorities to the various sounds used in an application.
  61
  62 note: Currently, all stereo sounds are 'passed thru' with no spatial rendering applied. This has the best output quality for rendering
  63 what are typically background sound tracks. However, the 3DMixer has the ability to render a stereo source to a spatial coordinate
  64 if this was desired and support to do so would be trivial.
  65
  66 ***** ALC_MIXER_OUTPUT_RATE
  67 This extension allows the developer to let the AudioGraph be efficient about sample rate conversion. If for example, all sounds
  68 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
  69 the audio data (Mixer Outputut Rate)  at 44k, letting the output AU rate convert the streams after they have been mixed. By default,
  70 this is set to 44k which is very common sample rate for sound hw.
  71
  72 ***** ALC_MIXER_MAXIMUM_BUSSES
  73 This extension allows the developer to optimize the 3DMixer by setting it available input bus count. This allows the 3DMixer to be as
  74 efficient as possible in resource allocations. By default, the 3DMixer currently defaults to 64 busses (note: the 1.3 version of the
  75 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).
  76 Use: set the bus count before making a call to alOpenDevice(). This will cause the library to set the mixer to you desired bus count.
  77 as it creates the AUGraph. Use the alSetInteger() & alGetInteger() APIs to specify and retrieve this setting.
  78
  79 ***** ALC_RENDER_CHANNEL_COUNT
  80 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
  81 to allow the user to clamp all rendering to stereo. Use the alSetInteger() & alGetInteger() APIs to specify and retrieve this setting.
  82 This implmentation provides 2 setting constants:    ALC_RENDER_CHANNEL_COUNT_STEREO         (clamp the 3DMixer output rendering to stereo, regardless of the hw capabilities)
  83                                                     ALC_RENDER_CHANNEL_COUNT_MULTICHANNEL   (try and render to the maximum speakers possible by interrogating the device)
  84
  85 ----------------------------------------------------------------------------------------------------------------------
  86 ----------------------------------------------------------------------------------------------------------------------