1/********************************************************************************************************************************** 2* 3* OpenAL cross platform audio library 4* Copyright (c) 2006, Apple Computer, Inc., Copyright (c) 2014, Apple Inc. All rights reserved. 5* 6* Redistribution and use in source and binary forms, with or without modification, are permitted provided 7* that the following conditions are met: 8* 9* 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 10* 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following 11* disclaimer in the documentation and/or other materials provided with the distribution. 12* 3. Neither the name of Apple Inc. ("Apple") nor the names of its contributors may be used to endorse or promote 13* products derived from this software without specific prior written permission. 14* 15* THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 16* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS 17* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 18* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 19* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 20* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 21* 22**********************************************************************************************************************************/ 23 24#ifndef __MAC_OSX_OAL_EXTENSIONS_H__ 25#define __MAC_OSX_OAL_EXTENSIONS_H__ 26 27#include <OpenAL/al.h> 28#include <OpenAL/alc.h> 29 30/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 31 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 32 33/* 34 Convert Data When Loading. 35 Default false, currently applies only to monophonic sounds. Use with alEnable()/alDisable() 36*/ 37 #define ALC_MAC_OSX_CONVERT_DATA_UPON_LOADING 0xF001 38 39/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 40 ALC_EXT_MAC_OSX 41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 42 43typedef ALvoid (*alcMacOSXRenderingQualityProcPtr) (ALint value); 44typedef ALvoid (*alMacOSXRenderChannelCountProcPtr) (ALint value); 45typedef ALvoid (*alcMacOSXMixerMaxiumumBussesProcPtr) (ALint value); 46typedef ALvoid (*alcMacOSXMixerOutputRateProcPtr) (ALdouble value); 47 48typedef ALint (*alcMacOSXGetRenderingQualityProcPtr) (); 49typedef ALint (*alMacOSXGetRenderChannelCountProcPtr) (); 50typedef ALint (*alcMacOSXGetMixerMaxiumumBussesProcPtr) (); 51typedef ALdouble (*alcMacOSXGetMixerOutputRateProcPtr) (); 52 53/* Render Quality. Used with alcMacOSXRenderingQuality() */ 54 55 #define ALC_MAC_OSX_SPATIAL_RENDERING_QUALITY_HIGH 'rqhi' 56 #define ALC_MAC_OSX_SPATIAL_RENDERING_QUALITY_LOW 'rdlo' 57 58/* 59 Render Channels. Used with alMacOSXRenderChannelCount() 60 Allows a user to force OpenAL to render to stereo, regardless of the audio hardware being used 61*/ 62 #define ALC_MAC_OSX_RENDER_CHANNEL_COUNT_STEREO 'rcst' 63 #define ALC_MAC_OSX_RENDER_CHANNEL_COUNT_MULTICHANNEL 'rcmc' 64 65 66/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 67 AL_EXT_SOURCE_SPATIALIZATION 68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 69/* 70 Allows the rendering quality to be explicitly set on a source object, overriding the default 71 render quality set via alcMacOSXRenderingQuality(). A subsequent call to alcMacOSXRenderingQuality() 72 resets the render quality of all source objects. 73 74 Uses the same render settings (defined above) as alcMacOSXRenderingQuality(): 75 76 ALC_MAC_OSX_SPATIAL_RENDERING_QUALITY_HIGH 77 ALC_MAC_OSX_SPATIAL_RENDERING_QUALITY_LOW 78 ALC_IPHONE_SPATIAL_RENDERING_QUALITY_HEADPHONES 79 80 Retrieve functions via alcGetProcAddress() by passing in strings: alSourceRenderingQuality or alSourceGetRenderingQuality 81 */ 82 83typedef ALvoid (*alSourceRenderingQualityProcPtr) (ALuint sid, ALint value); 84typedef ALint (*alSourceGetRenderingQualityProcPtr) (ALuint sid); 85 86 87/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 88 AL_EXT_STATIC_BUFFER 89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 90 91typedef ALvoid AL_APIENTRY (*alBufferDataStaticProcPtr) (ALint bid, ALenum format, const ALvoid* data, ALsizei size, ALsizei freq); 92 93/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 94 AL_EXT_SOURCE_NOTIFICATIONS 95 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 96/* 97 Source Notifications 98 99 Eliminates the need for continuous polling for source state by providing a 100 mechanism for the application to receive source state change notifications. 101 Upon receiving a notification, the application can retrieve the actual state 102 corresponding to the notification ID for which the notification was sent. 103*/ 104 105#define AL_QUEUE_HAS_LOOPED 0x9000 106 107/* 108 Notification Proc: ALSourceNotificationProc 109 110 sid - source id 111 notificationID - id of state that has changed 112 userData - user data provided to alSourceAddNotification() 113*/ 114 115typedef ALvoid (*alSourceNotificationProc)(ALuint sid, ALuint notificationID, ALvoid* userData); 116 117/* 118 API: alSourceAddNotification 119 120 sid - source id 121 notificationID - id of state for which caller wants to be notified of a change 122 notifyProc - notification proc 123 userData - ptr to applications user data, will be returned in the notification proc 124 125 Returns AL_NO_ERROR if request is successful. 126 127 Valid IDs: 128 AL_SOURCE_STATE 129 AL_BUFFERS_PROCESSED 130 AL_QUEUE_HAS_LOOPED - notification sent when a looping source has looped to it's start point 131*/ 132typedef ALenum (*alSourceAddNotificationProcPtr) (ALuint sid, ALuint notificationID, alSourceNotificationProc notifyProc, ALvoid* userData); 133 134/* 135 API: alSourceRemoveStateNotification 136 137 sid - source id 138 notificationID - id of state for which caller wants to remove an existing notification 139 notifyProc - notification proc 140 userData - ptr to applications user data, will be returned in the notification proc 141*/ 142typedef ALvoid (*alSourceRemoveNotificationProcPtr) (ALuint sid, ALuint notificationID, alSourceNotificationProc notifyProc, ALvoid* userData); 143 144/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 145 ALC_EXT_ASA : Apple Spatial Audio Extension 146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 147/* 148 Used with the ASA API calls: alcASAGetSource(), alcASASetSource(), alcASAGetListener(), alcASASetListener() 149*/ 150 151typedef ALenum (*alcASAGetSourceProcPtr) (ALuint property, ALuint source, ALvoid *data, ALuint* dataSize); 152typedef ALenum (*alcASASetSourceProcPtr) (ALuint property, ALuint source, ALvoid *data, ALuint dataSize); 153typedef ALenum (*alcASAGetListenerProcPtr) (ALuint property, ALvoid *data, ALuint* dataSize); 154typedef ALenum (*alcASASetListenerProcPtr) (ALuint property, ALvoid *data, ALuint dataSize); 155 156 /* listener properties */ 157 #define ALC_ASA_REVERB_ON 'rvon' // type ALuint 158 #define ALC_ASA_REVERB_GLOBAL_LEVEL 'rvgl' // type ALfloat -40.0 db - 40.0 db 159 160 #define ALC_ASA_REVERB_ROOM_TYPE 'rvrt' // type ALint 161 162 /* reverb room type presets for the ALC_ASA_REVERB_ROOM_TYPE property */ 163 #define ALC_ASA_REVERB_ROOM_TYPE_SmallRoom 0 164 #define ALC_ASA_REVERB_ROOM_TYPE_MediumRoom 1 165 #define ALC_ASA_REVERB_ROOM_TYPE_LargeRoom 2 166 #define ALC_ASA_REVERB_ROOM_TYPE_MediumHall 3 167 #define ALC_ASA_REVERB_ROOM_TYPE_LargeHall 4 168 #define ALC_ASA_REVERB_ROOM_TYPE_Plate 5 169 #define ALC_ASA_REVERB_ROOM_TYPE_MediumChamber 6 170 #define ALC_ASA_REVERB_ROOM_TYPE_LargeChamber 7 171 #define ALC_ASA_REVERB_ROOM_TYPE_Cathedral 8 172 #define ALC_ASA_REVERB_ROOM_TYPE_LargeRoom2 9 173 #define ALC_ASA_REVERB_ROOM_TYPE_MediumHall2 10 174 #define ALC_ASA_REVERB_ROOM_TYPE_MediumHall3 11 175 #define ALC_ASA_REVERB_ROOM_TYPE_LargeHall2 12 176 177 #define ALC_ASA_REVERB_PRESET 'rvps' // type ALchar* - (set only) path to an au preset file 178 179 #define ALC_ASA_REVERB_EQ_GAIN 'rveg' // type ALfloat 180 #define ALC_ASA_REVERB_EQ_BANDWITH 'rveb' // type ALfloat 181 #define ALC_ASA_REVERB_EQ_FREQ 'rvef' // type ALfloat 182 183 #define ALC_ASA_REVERB_QUALITY 'rvqt' // type ALint 184 185 /* reverb quality settings for the ALC_ASA_REVERB_QUALITY property */ 186 #define ALC_ASA_REVERB_QUALITY_Max 0x7F 187 #define ALC_ASA_REVERB_QUALITY_High 0x60 188 #define ALC_ASA_REVERB_QUALITY_Medium 0x40 189 #define ALC_ASA_REVERB_QUALITY_Low 0x20 190 #define ALC_ASA_REVERB_QUALITY_Min 0 191 192 /* source properties */ 193 #define ALC_ASA_REVERB_SEND_LEVEL 'rvsl' // type ALfloat 0.0 (dry) - 1.0 (wet) (0-100% dry/wet mix, 0.0 default) 194 #define ALC_ASA_OCCLUSION 'occl' // type ALfloat -100.0 db (most occlusion) - 0.0 db (no occlusion, 0.0 default) 195 #define ALC_ASA_OBSTRUCTION 'obst' // type ALfloat -100.0 db (most obstruction) - 0.0 db (no obstruction, 0.0 default) 196 197/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 198 ALC_EXT_ASA_ROGER_BEEP : Apple Spatial Audio Extension for Roger Beep Effect 199 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 200 201/* 202 Roger Beep : an effect to simulate effects such as Walkie Talkie noise. It is designed to replace the 203 source audio data with a specific 'tone' when falling below a specified db threshold for a specified time. 204 This Extension will be present when the Roger Beep Audio Unit is present on the system (10.5 or greater) 205 Use the alcASAGetSource() and alcASASetSource() APIs in the ALC_EXT_ASA extension. 206*/ 207 208 /* source properties */ 209 #define ALC_ASA_ROGER_BEEP_ENABLE 'rben' // type ALboolean - initializes Roger Beep for use - returns error if source is not in a Stopped or Initial state 210 #define ALC_ASA_ROGER_BEEP_ON 'rbon' // type ALboolean - set effect on/off (bypass) - default setting is true (on) 211 #define ALC_ASA_ROGER_BEEP_GAIN 'rbgn' // type ALfloat - 20.0 (db) apply maximum effect : -80.0(db) apply minimum effect amount 212 #define ALC_ASA_ROGER_BEEP_SENSITIVITY 'rbsn' // type ALint - specifiy a predefined sensitivity setting 213 #define ALC_ASA_ROGER_BEEP_TYPE 'rbtp' // type ALint - choose predefined specific Roger Beep tone 214 #define ALC_ASA_ROGER_BEEP_PRESET 'rbps' // type ALchar* - path to an au preset file (set only) 215 216 /* settings for the ALC_ASA_ROGER_BEEP_TYPE property */ 217 #define ALC_ASA_ROGER_BEEP_TYPE_quindartone 0 218 #define ALC_ASA_ROGER_BEEP_TYPE_whitenoise 1 219 #define ALC_ASA_ROGER_BEEP_TYPE_walkietalkie 2 220 221 /* settings for the ALC_ASA_ROGER_BEEP_SENSITIVITY property */ 222 223 #define ALC_ASA_ROGER_BEEP_SENSITIVITY_Light 0 224 #define ALC_ASA_ROGER_BEEP_SENSITIVITY_Medium 1 225 #define ALC_ASA_ROGER_BEEP_SENSITIVITY_Heavy 2 226 227/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 228 ALC_EXT_ASA_DISTORTION : Apple Spatial Audio Extension for Distortion Effect 229 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 230 231/* 232 Distortion Effect 233 This Extension will be present when the Distortion Audio Unit is present on the system (10.5 or greater) 234 Use the alcASAGetSource() and alcASASetSource() APIs in the ALC_EXT_ASA extension. 235*/ 236 237 /* source properties */ 238 #define ALC_ASA_DISTORTION_ENABLE 'dsen' // type ALboolean - initializes Distortion for use - returns error if source is not in a Stopped or Initial state 239 #define ALC_ASA_DISTORTION_ON 'dson' // type ALboolean - set effect on/off (bypass) - default setting is true (on) 240 #define ALC_ASA_DISTORTION_MIX 'dsmx' // type ALfloat - mix balance between dry signal and distortion effect - 0.0 (no effect) - 100.0 (all effect) 241 #define ALC_ASA_DISTORTION_TYPE 'dstp' // type ALint - choose predefined distortion settings 242 #define ALC_ASA_DISTORTION_PRESET 'dsps' // type ALchar* - path to an au preset file (set only) 243 244 /* settings for the ALC_ASA_DISTORTION_TYPE property */ 245 #define ALC_ASA_DISTORTION_TYPE_BitBrush 0 246 #define ALC_ASA_DISTORTION_TYPE_BufferBeats 1 247 #define ALC_ASA_DISTORTION_TYPE_LoFi 2 248 #define ALC_ASA_DISTORTION_TYPE_BrokenSpeaker 3 249 #define ALC_ASA_DISTORTION_TYPE_Cellphone 4 250 #define ALC_ASA_DISTORTION_TYPE_Decimated1 5 251 #define ALC_ASA_DISTORTION_TYPE_Decimated2 6 252 #define ALC_ASA_DISTORTION_TYPE_Decimated3 7 253 #define ALC_ASA_DISTORTION_TYPE_Decimated4 8 254 #define ALC_ASA_DISTORTION_TYPE_DistortedFunk 9 255 #define ALC_ASA_DISTORTION_TYPE_DistortionCubed 10 256 #define ALC_ASA_DISTORTION_TYPE_DistortionSquared 11 257 #define ALC_ASA_DISTORTION_TYPE_Echo1 12 258 #define ALC_ASA_DISTORTION_TYPE_Echo2 13 259 #define ALC_ASA_DISTORTION_TYPE_EchoTight1 14 260 #define ALC_ASA_DISTORTION_TYPE_EchoTight2 15 261 #define ALC_ASA_DISTORTION_TYPE_EverythingBroken 16 262 #define ALC_ASA_DISTORTION_TYPE_AlienChatter 17 263 #define ALC_ASA_DISTORTION_TYPE_CosmicInteference 18 264 #define ALC_ASA_DISTORTION_TYPE_GoldenPi 19 265 #define ALC_ASA_DISTORTION_TYPE_RadioTower 20 266 #define ALC_ASA_DISTORTION_TYPE_Waves 21 267 268 269/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 270 ALC_EXT_OUTPUT_CAPTURER 271 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ 272/* 273 Allows an application to capture the rendered output of the current context. 274 The application prepares OpenAL for capturing the context output by specifying the data format 275 of the captured audio output data. Once capture has been started, the application then queries OpenAL 276 for the available number of captured samples, and requests the samples by providing a buffer to fill. 277 278 Retrieve functions via alcGetProcAddress() by passing in strings: alcOutputCapturerPrepare, alcOutputCapturerStart, 279 alcOutputCapturerStop, alcOutputCapturerAvailableSamples and alcOutputCapturerSamples 280 */ 281 282/* 283 API: alcOutputCapturerPrepare 284 285 Prepare output capturing of the current context by specifying the data format desired from OpenAL. 286 287 frequency - Sampling rate of the captured output. 288 289 format - Data format of the captured data. Specified as one of the native OpenAL data format types: 290 AL_FORMAT_MONO8 291 AL_FORMAT_MONO16 292 AL_FORMAT_STEREO8 293 AL_FORMAT_STEREO16 294 295 maxsamplecount - The maximum number of samples that will be requested by the application. 296 */ 297typedef ALvoid AL_APIENTRY (*alcOutputCapturerPrepareProcPtr) (ALCuint frequency, ALCenum format, ALCsizei maxsamplecount); 298 299/* 300 API: alcOutputCapturerStart 301 302 Start capturing samples rendered by the current context to a maximum of the sample count specified when calling alcOutputCapturerPrepare. 303 */ 304typedef ALvoid AL_APIENTRY (*alcOutputCapturerStartProcPtr) (); 305 306/* 307 API: alcOutputCapturerStop 308 309 Stop capturing samples rendered by the context. This function resets the captured audio samples to 0. 310 */ 311typedef ALvoid AL_APIENTRY (*alcOutputCapturerStopProcPtr) (); 312 313/* 314 API: alcOutputCapturerAvailableSamples 315 316 Get the number of captured samples currently available. 317 */ 318typedef ALint AL_APIENTRY (*alcOutputCapturerAvailableSamplesProcPtr) (); 319 320/* 321 API: alcOutputCapturerSamples 322 323 Write captured samples to an application provided buffer. 324 325 buffer - Application provided buffer to be filled with the requested amount of samples and must be of size 326 samplecount * size of sample. i.e. 100 samples of AL_FORMAT_STEREO16 data -> 100 * 4 = 400 bytes 327 The buffer must NOT be deallocated before the call to alcOutputCapturerSamples returns. 328 329 samplecount - Number of samples to be copied to the provided buffer. 330 Requesting more samples than currently available is an error. 331 */ 332typedef ALvoid AL_APIENTRY (*alcOutputCapturerSamplesProcPtr) (ALCvoid *buffer, ALCsizei samplecount); 333 334 335#endif // __MAC_OSX_OAL_EXTENSIONS_H__