1 /*(GPL) 2 --------------------------------------------------------------------------- 3 audio.h - Public Audio Engine Interface 4 --------------------------------------------------------------------------- 5 * Copyright (C) 19??, Masanao Izumo 6 * Copyright (C) 2001-2003, 2007 David Olofson 7 * 8 * Written for SGI DMedia API by Masanao Izumo <mo@goice.co.jp> 9 * Mostly rewritten by David Olofson <do@reologica.se>, 2001 10 * 11 * This program is free software; you can redistribute it and/or modify it 12 * under the terms of the GNU General Public License as published by the 13 * Free Software Foundation; either version 2.1 of the License, or (at your 14 * option) any later version. 15 * 16 * This program is distributed in the hope that it will be useful, but 17 * WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 19 * General Public License for more details. 20 * 21 * You should have received a copy of the GNU General Public License along 22 * with this program; if not, write to the Free Software Foundation, Inc., 23 * 675 Mass Ave, Cambridge, MA 02139, USA. 24 */ 25 26 #ifndef _AUDIO_H_ 27 #define _AUDIO_H_ 28 29 #include "config.h" 30 #include "a_types.h" 31 #include "a_commands.h" 32 #include "a_wave.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /* Define this to get range checking in the API entry calls. */ 39 #define AUDIO_SAFE 40 41 /* Limits - exceed these and things may blow up! */ 42 #define AUDIO_MIN_OUTPUT_RATE 8000 43 #define AUDIO_MAX_OUTPUT_RATE 48000 44 #define AUDIO_MAX_MIX_RATE 128000 45 #define AUDIO_MAX_OVERSAMPLING 16 46 47 /* Sounds */ 48 #define AUDIO_MAX_WAVES 128 49 #define AUDIO_MAX_PATCHES 128 50 51 /* Control */ 52 /* Grous and channels; virtually no per-unit overhead. */ 53 #define AUDIO_MAX_GROUPS 8 54 #define AUDIO_MAX_CHANNELS 32 55 56 /* 57 * Changes (David): 58 *------------------ 59 * play_stop(-1) feature removed. 60 * Silent channels are now released automatically. 61 * 62 * get_audio_volume() removed. 63 * It cannot safely be used the way XKobo used it 64 * due to the asynchronous nature of the modified 65 * audio engine. (Background music attenuation is 66 * now done in a more reliable way.) 67 * 68 * play_loop() removed. 69 * Not needed with a callback or thread driven 70 * audio engine. 71 * 72 * API cleaned up; all function names now begin with 73 * 'audio_'. 74 * 75 * audio_control() API added. 76 * 77 * 78 * Changes in 0.4-pre6: 79 *---------------------- 80 * audio_volume() removed, as it was redundant. 81 * 82 * AC_SEND_# dry/fx level controls added. 83 * 84 * AC_GROUP added. 85 * 86 * The term "channel" is replaced with "voice". 87 * 88 * The new term "channel" is different from "voice". 89 * Just like before, channel indices are used as 90 * addresses when starting/stopping sounds and 91 * sending control commands. However, the "new" 92 * channels are internally separated from the 93 * engine's mixing voices, which means that it's 94 * possible to implement polyphonic channels and 95 * dynamic channel allocation. 96 * 97 * New term "group" introduced. 98 * Channels are organized in groups. A group is 99 * physically a structure that holds "modifications" 100 * that are applied as control commands are passed 101 * from channels belonging to the group to the 102 * voices controlled by the respective channels. 103 * What this means is basically that a group can 104 * be used as a central master control for all 105 * channels that belong to it. 106 * 107 * Volume/send format changed to 16:16 fixed point. 108 * 109 * Float API added, where 1.0 corresponds to 110 * 0x0001.0000. 111 * 112 * Master volume and reverb API now uses float values. 113 * 114 * AC_PLAYRESET renamed AC_DETACH. 115 * The new version works in a slightly different way 116 * to AC_PLAYRESET. 117 * 118 * Normally (AC_DETACH == 0), the engine behaves 119 * like a MIDI synth; all control commands to a 120 * channel instantly affects *all* voices started 121 * from that channel. Voices are not disconnected 122 * until they stop playing. Group default control 123 * values are never used after initialization. 124 * 125 * With AC_DETACH enabled, audio_play() disconnects 126 * voices, so that they are not affected by any 127 * further control commands. That is, control 128 * commands to a new voice have to be sent *before* 129 * the voice is actually started! After a voice has 130 * been started and detached, all channel controls 131 * are reset to the defaults for the group which 132 * the channel belongs to. 133 * 134 * Note that audio_stop() *always* stops all voices 135 * started from a channel. 136 * 137 * Note that audio_group_control() is affected by 138 * the AC_DETACH feature as well. As it's 139 * impossible to update detached voices properly, 140 * audio_group_control() never touches AC_DETACH 141 * mode channels directly. New voices are still 142 * affected when they're launched, as that's when 143 * AC_DETACH mode channels check the controls of 144 * their parent groups. 145 * 146 * Removed the hardcoded 8 kHz default AC_SPEED. 147 * 148 * *Lots* of other changes, like: 149 * * Switched to channel->bus->master architecture. 150 * * Added mono8, mono16 and stereo16 data support. 151 * * Added high quality voice mixers. 152 * * Added uniform plugin API. 153 * * Cleaned up engine and API namespace. 154 * 155 * Changes in 0.4pre7: 156 *--------------------- 157 * More than I can keep track of... Some of it is in 158 * ChangeLog, I hope! :-) 159 * 160 * Changes in 0.4pre8: 161 *--------------------- 162 * (See Kobo Deluxe 0.4pre8 ChangeLog.) 163 */ 164 165 /*---------------------------------------------------------- 166 Init/close 167 ----------------------------------------------------------*/ 168 /* 169 * Initialize audio engine. Will do nothing if called when 170 * the engine is already open. 171 * 172 * Returns 0 on success, or a negative value in the case 173 * of failure. 174 */ 175 int audio_open(void); 176 177 /* 178 * Start audio engine. Can also be used for restarting 179 * the engine with new parameters. Will open the engine 180 * first if required. Any loaded sounds and patches (if 181 * the engine is open, that is) are unaffected. 182 * 183 * Returns 0 on success, or a negative value in the case 184 * of failure. 185 */ 186 int audio_start(int rate, int latency, int use_oss, int use_midi, int pollaudio); 187 188 /* 189 * "Driver" call for engine low priority housekeeping 190 * work. Call this "frequently" - at least ten times per 191 * second if possible. 192 * 193 * Note that while this call may not do anything 194 * at all on some platforms, it could provide 195 * CRITICAL SERVICES to the engine on others! 196 * 197 * (Mac OS Classic would be an example of the latter; 198 * since the engine is running in interrupt context, 199 * plugins must be instantiated and destroyed in the 200 * context of audio_run() instead.) 201 * 202 * With "pollaudio" enabled: 203 * Fills up the driver's audio buffer, calling the 204 * engine callback as needed to generate data. In 205 * this mode, audio_run() must be called rather 206 * frequently to avoid drop-outs. (The exact 207 * requirement depends on the configured latency.) 208 */ 209 void audio_run(void); 210 211 /* Returns the estimated time of the next callback */ 212 int audio_next_callback(void); 213 214 /* 215 * Stop the audio engine. Does not unload sounds or 216 * patches. 217 */ 218 void audio_stop(void); 219 220 /* 221 * Stops the audio engine if running, and then unloads 222 * all waves & patches. 223 */ 224 void audio_close(void); 225 226 void audio_quality(audio_quality_t quality); 227 void audio_set_limiter(float thres, float rels); 228 229 /* 230 * Patch Construction (low level) 231 */ 232 void audio_patch_param(int pid, int param, int arg); 233 void audio_patch_paramf(int pid, int param, float arg); 234 void audio_patch_control(int pid, int layer, int ctl, int arg); 235 void audio_patch_controlf(int pid, int layer, int ctl, float arg); 236 237 #ifdef __cplusplus 238 }; 239 #endif 240 241 #endif /* _AUDIO_H_ */ 242