From b9d48d2f9b74a99d4709383d5e9fad63d64dd730 Mon Sep 17 00:00:00 2001 From: Dom Light Date: Tue, 17 Nov 2015 00:42:23 +0000 Subject: [PATCH] Document audio.h --- src/audio/audio.c | 42 +++++++++++++---------- src/audio/audio.h | 79 +++++++++++++++++++++++++++++++++++++------ src/rct2.c | 2 +- src/windows/options.c | 2 +- src/world/climate.c | 10 ++---- 5 files changed, 97 insertions(+), 38 deletions(-) diff --git a/src/audio/audio.c b/src/audio/audio.c index 32d6f999e4..e3606baebf 100644 --- a/src/audio/audio.c +++ b/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(); } /** diff --git a/src/audio/audio.h b/src/audio/audio.h index ceb42682ca..48a488a52e 100644 --- a/src/audio/audio.h +++ b/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 diff --git a/src/rct2.c b/src/rct2.c index 80ce5c8ba1..7781f5af7b 100644 --- a/src/rct2.c +++ b/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(); diff --git a/src/windows/options.c b/src/windows/options.c index 95778854e2..6fcb3a819b 100644 --- a/src/windows/options.c +++ b/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); diff --git a/src/world/climate.c b/src/world/climate.c index 5692acb13b..ed1cac08d2 100644 --- a/src/world/climate.c +++ b/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; } }