1 /* Patrick 5/6/97 ------------------------------------------------------------- 2 AvP sound management header 3 Provides support for sound samples, and for playing CDDA tracks. 4 NB These two systems are entirely seperate. 5 ----------------------------------------------------------------------------*/ 6 #ifndef PSND_H 7 #define PSND_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 #include "psndproj.h" 14 15 /* Patrick 10/6/97 -------------------------------------------------------------- 16 SUPPORT FOR SOUND SAMPLE SYSTEM 17 -----------------------------------------------------------------------------*/ 18 19 /* Patrick 5/6/97 -------------------------------------------------------------- 20 Enumeration of different sound priorities: sounds created with the maximum 21 priority may stop and displace sounds with the minimum priority, if the 22 maximum number of sounds is being played. 23 -----------------------------------------------------------------------------*/ 24 typedef enum activesoundpriority 25 { 26 ASP_Minimum, 27 ASP_Maximum, 28 }ACTIVESOUNDPRIORITY; 29 30 /* this is a structure for new 3d sound support */ 31 32 typedef struct sound3ddata 33 { 34 VECTORCH position; 35 VECTORCH velocity; 36 int inner_range; 37 int outer_range; 38 39 } SOUND3DDATA; 40 41 42 /* Patrick 5/6/97 -------------------------------------------------------------- 43 Some platform independant defines: 44 SOUND_NOACTIVEINDEX: used to invalidate sound handles 45 MAX\MIN VOLUME: range of values accepted by functions for sound volume settings 46 MAX\MIN PITCH: range of values accepted by functions for sound pitch settings, 47 covers +- 4 octaves in 128ths of a semi-tone 48 -----------------------------------------------------------------------------*/ 49 #define SOUND_NOACTIVEINDEX (-1) 50 #define SOUND_PLATFORMERROR (-1) 51 52 #define VOLUME_MAX (127) 53 #define VOLUME_MIN (0) 54 #define VOLUME_DEFAULT (127) 55 #define VOLUME_FADERATE (16) /* per second */ 56 57 #define PITCH_MAX (6144) 58 #define PITCH_MIN (-6144) 59 #define PITCH_DEFAULT (0) 60 61 /* Patrick 5/6/97 -------------------------------------------------------------- 62 SoundSys_Start() & SoundSys_End(): initialise and de-initialise the sound 63 system. 64 -----------------------------------------------------------------------------*/ 65 extern void SoundSys_Start(void); 66 extern void SoundSys_End(void); 67 /* Patrick 5/6/97 -------------------------------------------------------------- 68 The management function: cleans up sounds that have finished playing, and 69 updates 3d sounds. This must be called during the game loop, whenever sounds 70 are required. 71 -----------------------------------------------------------------------------*/ 72 extern void SoundSys_Management(void); 73 /* Patrick 5/6/97 -------------------------------------------------------------- 74 StopAll: stops all current sounds. New ones may be started immediately afterwards. 75 RemoveAll(): stops all sounds, and then unloads any loaded sounds. The 76 sound system remains initialised, but no sounds can be played until they are loaded. 77 -----------------------------------------------------------------------------*/ 78 extern void SoundSys_StopAll(void); 79 extern void SoundSys_RemoveAll(void); 80 /* Patrick 5/6/97 -------------------------------------------------------------- 81 Switch On/Off: can be used to turn on\off sound. If turened off, al sounds 82 stop and no further ones will be started until switched on again. Switch on 83 only succeeds if the sound system has been initialised succesfully. 84 -----------------------------------------------------------------------------*/ 85 extern void SoundSys_SwitchOn(void); 86 extern void SoundSys_SwitchOff(void); 87 /* Patrick 5/6/97 -------------------------------------------------------------- 88 IsOn returns true (1) if the sound system is currently switched on, 89 or false (0) otherwise. 90 NB IsOn always returns false if the sound system has not been initialised, ie 91 if SoundSys_Start() has not been called, or if the platform initialisation 92 failed. 93 -----------------------------------------------------------------------------*/ 94 extern int SoundSys_IsOn(void); 95 /* Patrick 5/6/97 -------------------------------------------------------------- 96 Change volume controls, which effect all current and future sounds. 97 NB These do not effect the CDDA player. 98 -----------------------------------------------------------------------------*/ 99 extern void SoundSys_ChangeVolume(int volume); 100 101 102 /* New fading functionality KJL 99/4/5 */ 103 extern void SoundSys_ResetFadeLevel(void); 104 extern void SoundSys_FadeIn(void); 105 extern void SoundSys_FadeOut(void); 106 extern void SoundSys_FadeOutFast(void); 107 108 109 /* Patrick 5/6/97 -------------------------------------------------------------- 110 Sound play function: creates and plays and instance of a loaded game sound. 111 Has no effect if the maximum number of sounds are playing, or the maximum 112 number of the specified sound are playing (these are defined in psndplat.h) 113 The second paramter is a format string which identifies any further paramters, 114 and flags. If the second parameter is NULL, or points to a null string, the 115 sound is played in 2D, at default volume and pitch, with lowest priority, 116 will not loop, and will not return a handle to itself. 117 The following characters may be used in the format string (all others ignored): 118 'd': play the sound as 3d- The next parameter must be the world position, and 119 of type VECTORCH * 120 'n': play the sound as new 3d- The next parameter must be the world position, and 121 of type SOUND3DDATA * 122 'e': external sound handle refernce- the next parameter must be a pointer 123 to the external reference, and of type int*. The external refernce 124 may br used to subsequently stop the sound, change it's volume or 125 pitch, or update it's world space position. If the sound play function 126 fails, or if/when the sound subsequently stops playing, 127 SOUND_NOACTIVEINDEX is written to this external reference. 128 'v': Volume- the next parameter must be the sounds starting volume 129 of type int. Out of range values are forced into range. 130 'p': Pitch- the next parameter must be the sounds starting pitch shift (shifted from 131 the sound's base pitch value), and of type int. Out of range values are forced 132 into range. 133 'l': play the sound looping (an external reference must be supplied, or the 134 function has n effect) 135 'h': play sound with maximum priority (minimum is the default) 136 'm': flag for marines to ignore. 137 -----------------------------------------------------------------------------*/ 138 extern void Sound_Play(SOUNDINDEX soundNumber, char* format, ...); 139 /* Patrick 5/6/97 -------------------------------------------------------------- 140 The remaining functions are used to modify existing playing sounds. All take 141 a handle to a sound. If an invalid handle is passed, the functions have no 142 effect. Out or range volume or pitch values are forced into range. 143 ChangeVolume works on an absolute scale (where the sounds original volume 144 corresponds to the maximum volume), and ChangePitch works as a pitch-shift 145 from the base pitch of the sound. 146 -----------------------------------------------------------------------------*/ 147 extern void Sound_Stop(int activeSoundNumber); 148 extern void Sound_ChangeVolume(int activeSoundNumber, int volume); 149 extern void Sound_ChangePitch(int activeSoundNumber, int pitch); 150 extern void Sound_Update3d(int activeSoundNumber, VECTORCH* posn); 151 extern void Sound_UpdateNew3d(int activeSoundNumber, SOUND3DDATA * s3d); 152 extern unsigned int SoundNumActiveVoices(); 153 154 155 extern void Load_SoundState(int* soundHandle); 156 extern void Save_SoundState(int* soundHandle); 157 158 #ifdef __cplusplus 159 } 160 #endif 161 162 #endif 163 164 165 166 167 168 169 170 171 172 173