Document audio.h

src/audio/audio.c

@@ -46,6 +46,8 @@ rct_vehicle_sound gVehicleSoundList[AUDIO_MAX_VEHICLE_SOUNDS];
 rct_vehicle_sound_params gVehicleSoundParamsList[AUDIO_MAX_VEHICLE_SOUNDS];
 rct_vehicle_sound_params *gVehicleSoundParamsListEnd;
 
+void audio_stop_channel(void **channel);
+
 void audio_init()
 {
 	int result = SDL_Init(SDL_INIT_AUDIO);
@@ -240,10 +242,7 @@ void audio_stop_ride_music()
 */
 void audio_stop_crowd_sound()
 {
-	if (gCrowdSoundChannel) {
-		Mixer_Stop_Channel(gCrowdSoundChannel);
-		gCrowdSoundChannel = 0;
-	}
+	audio_stop_channel(&gCrowdSoundChannel);
 }
 
 /**
@@ -252,28 +251,35 @@ void audio_stop_crowd_sound()
 */
 void audio_stop_title_music()
 {
-	if (gTitleMusicChannel) {
-		Mixer_Stop_Channel(gTitleMusicChannel);
-		gTitleMusicChannel = 0;
-	}
+	audio_stop_channel(&gTitleMusicChannel);
 }
 
-void stop_rain_sound()
+void audio_stop_rain_sound()
 {
-	if (gRainSoundChannel) {
-		Mixer_Stop_Channel(gRainSoundChannel);
-		gRainSoundChannel = 0;
-	}
+	audio_stop_channel(&gRainSoundChannel);
+}
+
+/**
+* Stops the specified audio channel from playing.
+* @param channel The channel to stop.
+*/
+void audio_stop_channel(void **channel)
+{
+	if (!*channel)
+		return;
+
+	Mixer_Stop_Channel(*channel);
+	*channel = 0;
 }
 
 /**
 *
 *  rct2: 0x006BA8E0
 */
-void audio_init1()
+void audio_init_ride_sounds_and_info()
 {
 	int deviceNum = 0;
-	audio_init2(deviceNum);
+	audio_init_ride_sounds(deviceNum);
 
 	for (int m = 0; m < countof(gRideMusicInfoList); m++) {
 		rct_ride_music_info *rideMusicInfo = gRideMusicInfoList[m];
@@ -295,7 +301,7 @@ void audio_init1()
 *
 *  rct2: 0x006BA9B5
 */
-void audio_init2(int device)
+void audio_init_ride_sounds(int device)
 {
 	audio_close();
 	for (int i = 0; i < AUDIO_MAX_VEHICLE_SOUNDS; i++) {
@@ -320,7 +326,7 @@ void audio_close()
 	audio_stop_crowd_sound();
 	audio_stop_title_music();
 	audio_stop_ride_music();
-	stop_rain_sound();
+	audio_stop_rain_sound();
 	RCT2_GLOBAL(RCT2_ADDRESS_CURRENT_SOUND_DEVICE, uint32) = -1;
 }
 
@@ -345,7 +351,7 @@ void audio_pause_sounds()
 	audio_stop_vehicle_sounds();
 	audio_stop_ride_music();
 	audio_stop_crowd_sound();
-	stop_rain_sound();
+	audio_stop_rain_sound();
 }
 
 /**

src/audio/audio.h

@@ -29,11 +29,11 @@
 #define AUDIO_MAX_VEHICLE_SOUNDS 14
 #define NUM_DEFAULT_MUSIC_TRACKS 46
 
-typedef struct {
+typedef struct audio_device {
 	char name[AUDIO_DEVICE_NAME_SIZE];
 } audio_device;
 
-typedef struct {
+typedef struct rct_ride_music {
 	uint8 ride_id;
 	uint8 tune_id;
 	sint16 volume;
@@ -42,14 +42,14 @@ typedef struct {
 	void* sound_channel;
 } rct_ride_music;
 
-typedef struct {
+typedef struct rct_ride_music_info {
 	uint32 length;
 	uint32 offset;
 	uint8 path_id;
 	uint8 var_9;
 } rct_ride_music_info;
 
-typedef struct {
+typedef struct rct_ride_music_params {
 	uint8 ride_id;
 	uint8 tune_id;
 	sint32 offset;
@@ -58,7 +58,7 @@ typedef struct {
 	uint16 frequency;
 } rct_ride_music_params;
 
-typedef struct {
+typedef struct rct_vehicle_sound {
 	uint16 id;
 	sint16 volume;
 	uint16 sound1_id;
@@ -73,7 +73,7 @@ typedef struct {
 	void* sound2_channel;
 } rct_vehicle_sound;
 
-typedef struct {
+typedef struct rct_vehicle_sound_params {
 	uint16 id;
 	sint16 pan_x;
 	sint16 pan_y;
@@ -82,7 +82,7 @@ typedef struct {
 	uint16 var_A;
 } rct_vehicle_sound_params;
 
-typedef enum {
+typedef enum RCT2_SOUND {
 	SOUND_LIFT_1 = 0,
 	SOUND_TRACK_FRICTION_1 = 1,
 	SOUND_LIFT_2 = 2,
@@ -163,20 +163,79 @@ extern rct_vehicle_sound gVehicleSoundList[AUDIO_MAX_VEHICLE_SOUNDS];
 extern rct_vehicle_sound_params gVehicleSoundParamsList[AUDIO_MAX_VEHICLE_SOUNDS];
 extern rct_vehicle_sound_params *gVehicleSoundParamsListEnd;
 
+/**
+* Deregisters the audio device.
+*/
 void audio_close();
+/*
+* Initialises the audio subsystem.
+*/
 void audio_init();
-void audio_init1();
-void audio_init2(int device);
+/**
+* Loads the ride sounds and info.
+*/
+void audio_init_ride_sounds_and_info();
+/**
+Loads the ride sounds.
+*/
+void audio_init_ride_sounds(int device);
+/**
+* Temporarily stops playing sounds until audio_unpause_sounds() is called.
+*/
 void audio_pause_sounds();
+/**
+* Populates the gAudioDevices array with the available audio devices.
+*/
 void audio_populate_devices();
+/**
+* Terminates the audio subsystem.
+* This appears to be unused.
+*/
 void audio_quit();
-int audio_sound_play_panned(int soundId, int ebx, sint16 x, sint16 y, sint16 z);
+/** Plays the specified sound effect at the specified virtual location.
+* @param soundId The sound effect to play.
+* @param mode If set to 0x8001, play the sound at the specified location; if
+* set to 0x8000, play the sound at the center of the viewport; if set to
+* anything else, use the value of mode as a relative position to the center of
+* the viewport.
+* @param x The x coordinate of the location.
+* @param y The y coordinate of the location.
+* @param z The z coordinate of the location.
+* @return 0 if the sound was played successfully, otherwise, soundId.
+*/
+int audio_sound_play_panned(int soundId, int mode, sint16 x, sint16 y, sint16 z);
+/**
+* Starts playing the title music.
+*/
 void audio_start_title_music();
+/**
+* Stops the crowd sound effect from playing.
+*/
 void audio_stop_crowd_sound();
+/**
+* Stops the rain sound effect from playing.
+*/
+void audio_stop_rain_sound();
+/**
+* Stops ride music from playing.
+*/
 void audio_stop_ride_music();
+/**
+* Stops the title music from playing.
+*/
 void audio_stop_title_music();
+/**
+* Stops vehicle sounds from playing.
+*/
 void audio_stop_vehicle_sounds();
+/**
+* Toggles whether all sounds should be played.
+*/
 void audio_toggle_all_sounds();
+/**
+* Resumes playing sounds that had been paused by a call to
+* audio_pause_sounds().
+*/
 void audio_unpause_sounds();
 
 #endif

src/rct2.c

@@ -104,7 +104,7 @@ int rct2_init()
 	font_sprite_initialise_characters();
 	if (!gOpenRCT2Headless) {
 		platform_init();
-		audio_init1();
+		audio_init_ride_sounds_and_info();
 	}
 	viewport_init_all();
 	news_item_init_queue();

src/windows/options.c

@@ -1069,7 +1069,7 @@ static void window_options_dropdown(rct_window *w, int widgetIndex, int dropdown
 	case WINDOW_OPTIONS_PAGE_AUDIO:
 		switch (widgetIndex) {
 		case WIDX_SOUND_DROPDOWN:
-			audio_init2(dropdownIndex);
+			audio_init_ride_sounds(dropdownIndex);
 			if (dropdownIndex < gAudioDeviceCount) {
 				if (dropdownIndex == 0) {
 					Mixer_Init(NULL);

src/world/climate.c

@@ -108,10 +108,7 @@ void climate_reset(int climate)
 	_lightningTimer = 0;
 	_thunderTimer = 0;
 	if (_rainVolume != 1){
-		if (gRainSoundChannel) {
-			Mixer_Stop_Channel(gRainSoundChannel);
-			gRainSoundChannel = 0;
-		}
+		audio_stop_rain_sound();
 		_rainVolume = 1;
 	}
 
@@ -272,10 +269,7 @@ static void climate_update_rain_sound()
 				Mixer_Channel_Volume(gRainSoundChannel, DStoMixerVolume(_rainVolume));
 			}
 		} else {
-			if (gRainSoundChannel) {
-				Mixer_Stop_Channel(gRainSoundChannel);
-				gRainSoundChannel = 0;
-			}
+			audio_stop_rain_sound();
 			_rainVolume = 1;
 		}
 	}