2 * Copyright (C) Volition, Inc. 1999. All rights reserved.
4 * All source code herein is the property of Volition, Inc. You may not sell
5 * or otherwise commercially exploit the source or things you created based on
10 * $Logfile: /Freespace2/code/Sound/ds.h $
15 * Header file for interface to DirectSound
18 * Revision 1.6 2005/10/01 21:38:32 taylor
19 * some reorg of includes to not requires the same headers in many different files
20 * handle FS1 specific language changes
21 * some OS X changes for paths and to handle socklen_t better
23 * Revision 1.5 2005/08/13 17:01:34 taylor
24 * gah, fix stupid commit message
26 * Revision 1.4 2005/08/12 08:47:24 taylor
27 * use new audiostr code rather than old windows and *nix version
28 * update all OpenAL commands with new error checking macros
29 * fix play_position to properly account for real position, fixes the talking heads and message text cutting out early
30 * movies will now use better filtering when scaled
32 * Revision 1.3 2002/06/09 04:41:12 relnev
33 * added copyright header
35 * Revision 1.2 2002/05/27 01:06:01 theoddone33
38 * Revision 1.1.1.1 2002/05/03 03:28:12 root
42 * 5 8/27/99 6:38p Alanl
43 * crush the blasted repeating messages bug
45 * 4 8/01/99 2:06p Alanl
46 * increase the rolloff for A3D
48 * 3 5/23/99 8:11p Alanl
49 * Added support for EAX
51 * 2 10/07/98 10:54a Dave
54 * 1 10/07/98 10:51a Dave
56 * 21 5/05/98 4:49p Lawrance
57 * Put in code to authenticate A3D, improve A3D support
59 * 20 4/20/98 12:03a Lawrance
60 * Allow prioritizing of CTRL3D buffers
62 * 19 4/18/98 9:12p Lawrance
63 * Added Aureal support.
65 * 18 4/13/98 5:04p Lawrance
66 * Write functions to determine how many milliseconds are left in a sound
68 * 17 3/23/98 10:32a Lawrance
69 * Add functions for extracting raw sound data
71 * 16 2/15/98 11:10p Lawrance
72 * more work on real-time voice system
74 * 15 2/15/98 4:43p Lawrance
75 * work on real-time voice
77 * 14 2/06/98 7:30p John
78 * Added code to monitor the number of channels of sound actually playing.
80 * 13 2/06/98 8:56a Allender
81 * fixed calling convention problem with DLL handles
83 * 12 2/04/98 6:08p Lawrance
84 * Read function pointers from dsound.dll, further work on
87 * 11 1/31/98 5:48p Lawrance
88 * Start on real-time voice recording
90 * 10 12/05/97 5:19p Lawrance
91 * re-do sound priorities to make more general and extensible
93 * 9 11/20/97 5:36p Dave
94 * Hooked in a bunch of main hall changes (including sound). Made it
95 * possible to reposition (rewind/ffwd)
96 * sound buffer pointers. Fixed animation direction change framerate
99 * 8 10/13/97 7:41p Lawrance
100 * store duration of sound
102 * 7 7/28/97 11:39a Lawrance
103 * allow individual volume scaling on 3D buffers
105 * 6 7/17/97 9:32a John
106 * made all directX header files name start with a v
108 * 5 7/15/97 11:15a Lawrance
109 * limit the max instances of simultaneous sound effects, implement
110 * priorities to force critical sounds
112 * 4 6/09/97 11:50p Lawrance
113 * integrating DirectSound3D
115 * 3 6/02/97 1:45p Lawrance
116 * implementing hardware mixing
118 * 2 5/29/97 12:04p Lawrance
119 * creation of file to hold DirectSound specific portions
134 #define DS_HARDWARE (1<<0)
136 #define DS_USE_DS3D (1<<2)
138 // Constants that DirectSound should assign, but doesn't
139 #define MAX_PAN 1500.0f
140 #define MIN_PITCH 100
141 #define MAX_PITCH 100000
144 // limits placed on how many concurrent sounds of the same type can play simultaneously
145 #define DS_MUST_PLAY 0
146 #define DS_LIMIT_ONE 1
147 #define DS_LIMIT_TWO 2
148 #define DS_LIMIT_THREE 3
150 #define DS_DUP_FAILED -99
152 typedef struct sound_info {
153 int format; // WAVE_FORMAT_* defines from mmreg.h
156 int avg_bytes_per_sec;
160 int duration; // time in ms for duration of sound
164 extern int ds_initialized;
179 extern const char* openal_error_string();
181 // if an error occurs after executing 'x' then do 'y'
182 #define OpenAL_ErrorCheck( x, y ) do { \
184 const char *error_text = openal_error_string(); \
185 if ( error_text != NULL ) { \
186 while ( error_text != NULL ) { \
187 nprintf(("Warning", "SOUND: %s:%d - OpenAL error = '%s'\n", __FILE__, __LINE__, error_text)); \
188 error_text = openal_error_string(); \
194 // like OpenAL_ErrorCheck() except that it gives the error message from x but does nothing about it
195 #define OpenAL_ErrorPrint( x ) do { \
197 const char *error_text = openal_error_string(); \
198 if ( error_text != NULL ) { \
199 while ( error_text != NULL ) { \
200 nprintf(("Sound", "OpenAL ERROR: \"%s\" in %s, line %i\n", error_text, __FILE__, __LINE__)); \
201 error_text = openal_error_string(); \
208 extern LPDIRECTSOUNDBUFFER pPrimaryBuffer;
209 extern LPDIRECTSOUND pDirectSound;
211 extern HRESULT (__stdcall *pfn_DirectSoundCaptureCreate)(LPGUID lpGUID, LPDIRECTSOUNDCAPTURE *lplpDSC, LPUNKNOWN pUnkOuter);
214 int ds_init(int use_a3d, int use_eax);
216 void ds_get_primary_format(WAVEFORMATEX *wfx);
217 int ds_parse_wave(char *filename, ubyte **dest, uint *dest_size, WAVEFORMATEX **header);
218 int ds_load_buffer(int *sid, int *hid, int *final_size, void *header, sound_info *si, int flags);
219 void ds_unload_buffer(int sid, int hid);
220 int ds_play(int sid, int hid, int snd_id, int priority, int volume, int pan, int looping, bool is_voice_msg = false);
221 int ds_convert_volume(float volume); // Convert a volume from 0.0f->1.0f to -10000 -> 0
222 float ds_get_percentage_vol(int ds_vol); // Convert a volume from -10000 -> 0 to 0.0f->1.0f
223 int ds_get_channel(int sig);
224 int ds_is_channel_playing(int channel);
225 void ds_stop_channel(int channel);
226 void ds_stop_channel_all();
227 void ds_set_volume( int channel, int vol );
228 void ds_set_pan( int channel, int pan );
229 int ds_get_pitch(int channel);
230 void ds_set_pitch(int channel, int pitch);
231 void ds_chg_loop_status(int channel, int loop);
232 void ds_set_position(int channel, DWORD offset);
233 DWORD ds_get_play_position(int channel);
234 DWORD ds_get_write_position(int channel);
235 int ds_get_data(int sid, char *data);
236 int ds_get_size(int sid, int *size);
238 int ds_create_buffer(int frequency, int bits_per_sample, int nchannels, int nseconds);
239 int ds_lock_data(int sid, unsigned char *data, int size);
240 int ds_play_easy(int sid, int volume);
241 void ds_stop_easy(int sid);
242 int ds_get_channel_size(int channel);
243 int ds_is_3d_buffer(int sid);
247 unsigned int ds_get_primary_buffer_interface();
248 unsigned int ds_get_dsound_interface();
249 unsigned int ds_get_property_set_interface();
251 // Returns the number of channels that are actually playing
252 int ds_get_number_channels();
254 int ds3d_play( int sid, int hid, int snd_id, vector *pos, vector *vel, int min, int max, int looping, int max_volume, int estimated_vol, int priority=DS_MUST_PLAY );
256 // Get a character string for the error code
257 char *get_DSERR_text(int DSResult);
261 // --------------------
265 // --------------------
267 // EAX (listener) reverb property set {4a4e6fc1-c341-11d1-b73a-444553540000}
269 DEFINE_GUID(DSPROPSETID_EAX_ReverbProperties,
273 0xb7, 0x3a, 0x44, 0x45, 0x53, 0x54, 0x00, 0x00);
278 DSPROPERTY_EAX_ALL, // all reverb properties
279 DSPROPERTY_EAX_ENVIRONMENT, // standard environment no.
280 DSPROPERTY_EAX_VOLUME, // loudness of the reverb
281 DSPROPERTY_EAX_DECAYTIME, // how long the reverb lasts
282 DSPROPERTY_EAX_DAMPING // the high frequencies decay faster
283 } DSPROPERTY_EAX_REVERBPROPERTY;
285 #define EAX_NUM_STANDARD_PROPERTIES (DSPROPERTY_EAX_DAMPING + 1)
287 // use this structure for get/set all properties...
290 unsigned long environment; // 0 to EAX_ENVIRONMENT_COUNT-1
291 float fVolume; // 0 to 1
292 float fDecayTime_sec; // seconds, 0.1 to 100
293 float fDamping; // 0 to 1
294 } EAX_REVERBPROPERTIES;
299 EAX_ENVIRONMENT_GENERIC,
300 EAX_ENVIRONMENT_PADDEDCELL,
301 EAX_ENVIRONMENT_ROOM,
302 EAX_ENVIRONMENT_BATHROOM,
303 EAX_ENVIRONMENT_LIVINGROOM,
304 EAX_ENVIRONMENT_STONEROOM,
305 EAX_ENVIRONMENT_AUDITORIUM,
306 EAX_ENVIRONMENT_CONCERTHALL,
307 EAX_ENVIRONMENT_CAVE,
308 EAX_ENVIRONMENT_ARENA,
309 EAX_ENVIRONMENT_HANGAR,
310 EAX_ENVIRONMENT_CARPETEDHALLWAY,
311 EAX_ENVIRONMENT_HALLWAY,
312 EAX_ENVIRONMENT_STONECORRIDOR,
313 EAX_ENVIRONMENT_ALLEY,
314 EAX_ENVIRONMENT_FOREST,
315 EAX_ENVIRONMENT_CITY,
316 EAX_ENVIRONMENT_MOUNTAINS,
317 EAX_ENVIRONMENT_QUARRY,
318 EAX_ENVIRONMENT_PLAIN,
319 EAX_ENVIRONMENT_PARKINGLOT,
320 EAX_ENVIRONMENT_SEWERPIPE,
321 EAX_ENVIRONMENT_UNDERWATER,
322 EAX_ENVIRONMENT_DRUGGED,
323 EAX_ENVIRONMENT_DIZZY,
324 EAX_ENVIRONMENT_PSYCHOTIC,
326 EAX_ENVIRONMENT_COUNT // total number of environments
329 #define EAX_MAX_ENVIRONMENT (EAX_ENVIRONMENT_COUNT - 1)
331 // EAX buffer reverb property set {4a4e6fc0-c341-11d1-b73a-444553540000}
333 DEFINE_GUID(DSPROPSETID_EAXBUFFER_ReverbProperties,
337 0xb7, 0x3a, 0x44, 0x45, 0x53, 0x54, 0x00, 0x00);
342 DSPROPERTY_EAXBUFFER_ALL, // all reverb buffer properties
343 DSPROPERTY_EAXBUFFER_REVERBMIX // the wet source amount
344 } DSPROPERTY_EAXBUFFER_REVERBPROPERTY;
346 // use this structure for get/set all properties...
349 float fMix; // linear factor, 0.0F to 1.0F
350 } EAXBUFFER_REVERBPROPERTIES;
352 #define EAX_REVERBMIX_USEDISTANCE -1.0F // out of normal range
353 // signifies the reverb engine should
354 // calculate it's own reverb mix value
362 int ds_eax_set_preset(unsigned long envid);
364 int ds_eax_set_volume(float volume);
365 int ds_eax_set_decay_time(float seconds);
366 int ds_eax_set_damping(float damp);
367 int ds_eax_set_environment(unsigned long envid);
368 int ds_eax_set_all(unsigned long id, float volume, float damping, float decay);
369 int ds_eax_get_all(EAX_REVERBPROPERTIES *er);
370 int ds_eax_is_inited();
372 #endif /* __DS_H__ */