From 287e79d47740c1fa8d232e0c5e3586a995683915 Mon Sep 17 00:00:00 2001 From: Johannes Schickel Date: Sat, 3 Nov 2007 23:32:15 +0000 Subject: Documenting the sound code a bit. svn-id: r29392 --- engines/kyra/sound.h | 156 +++++++++++++++++++++++++++++++++++++++-- engines/kyra/sound_digital.cpp | 4 -- 2 files changed, 152 insertions(+), 8 deletions(-) diff --git a/engines/kyra/sound.h b/engines/kyra/sound.h index 41c11580b3..72ae61595b 100644 --- a/engines/kyra/sound.h +++ b/engines/kyra/sound.h @@ -59,27 +59,89 @@ class AudioStream; namespace Kyra { -class AUDStream; - +/** + * Analog audio output device API for Kyrandia games. + * It countains functionallity to play music tracks, + * sound effects and voices. + */ class Sound { public: Sound(KyraEngine *vm, Audio::Mixer *mixer); virtual ~Sound(); + /** + * Initializes the output device. + * + * @return true on success, else false + */ virtual bool init() = 0; + + /** + * Updates the device, this is needed for some devices. + */ virtual void process() {} + /** + * Set the volume of the device. + * + * @param volume value between 0 and 255 + * + * @see getVolume + */ virtual void setVolume(int volume) = 0; + + /** + * Returns the current volume. + * + * @return volume + * + * @see setVolume + */ virtual int getVolume() = 0; + /** + * Sets the soundfiles the output device will use + * when playing a track and/or sound effect. + * + * @param list soundfile list + * @param s number of soundfiles + */ virtual void setSoundFileList(const char * const *list, uint s) { _soundFileList = list; _soundFileListSize = s; } + + /** + * Load a specifc sound file for use of + * playing music and sound effects. + */ virtual void loadSoundFile(uint file) = 0; + /** + * Plays the specified track. + * + * @param track track number + */ virtual void playTrack(uint8 track) = 0; + + /** + * Stop playback of the current track + */ virtual void haltTrack() = 0; + /** + * Plays the specified sound effect + * + * @param track sound effect id + */ virtual void playSoundEffect(uint8 track) = 0; + /** + * Starts fading out the volume. + * + * This keeps fading out the output until + * it is silenced, but does not change + * the volume set by setVolume! It will + * automatically reset the volume when + * playing a new track or sound effect. + */ virtual void beginFadeOut() = 0; void enableMusic(int enable) { _musicEnabled = enable; } @@ -87,9 +149,30 @@ public: void enableSFX(bool enable) { _sfxEnabled = enable; } bool sfxEnabled() const { return _sfxEnabled; } + /** + * Plays the specified voice file. + * + * Also before starting to play the + * specified voice file, it stops the + * current voice. + * + * TODO: add support for queueing voice + * files + * + * @param file file to be played + */ void voicePlay(const char *file); - void voiceUnload() {} + + /** + * Checks if a voice is being played. + * + * @return true when playing, else false + */ bool voiceIsPlaying(); + + /** + * Stops playback of the current voice. + */ void voiceStop(); protected: @@ -99,6 +182,7 @@ protected: KyraEngine *_vm; Audio::Mixer *_mixer; + private: const char * const *_soundFileList; uint _soundFileListSize; @@ -122,6 +206,17 @@ private: class AdlibDriver; +/** + * AdLib implementation of the sound output device. + * + * It uses a special sound file format special to + * Dune II, Kyrandia 1 and 2. While Dune II and + * Kyrandia 1 are using exact the same format, the + * one of Kyrandia 2 slightly differs. + * + * See AdlibDriver for more information. + * @see AdlibDriver + */ class SoundAdlibPC : public Sound { public: SoundAdlibPC(KyraEngine *vm, Audio::Mixer *mixer); @@ -165,6 +260,18 @@ private: static const int _kyra1SoundTriggers[]; }; +/** + * MIDI output device. + * + * This device supports both MT-32 MIDI, as used in + * Kyrandia 1 and 2, and GM MIDI, as used in Kyrandia 2. + * + * Currently it does not initialize the MT-32 output properly, + * so MT-32 output does sound a bit odd in some cases. + * + * TODO: this code needs some serious cleanup and rework + * to support MT-32 and GM properly. + */ class SoundMidiPC : public MidiDriver, public Sound { public: SoundMidiPC(KyraEngine *vm, Audio::Mixer *mixer, MidiDriver *driver); @@ -320,18 +427,59 @@ private: Sound *_music, *_sfx; }; +// Digital Audio + #define SOUND_STREAMS 4 +class AUDStream; + +/** + * Digital audio output device. + * + * This is just used for Kyrandia 3. + */ class SoundDigital { public: SoundDigital(KyraEngine *vm, Audio::Mixer *mixer); ~SoundDigital(); - bool init(); + bool init() { return true; } + /** + * Plays a sound. + * + * @param fileHandle file handle used for playback. + * It will be deleted when playback is finished + * @param loop true if the sound should loop (endlessly) + * @param fadeIn true if the sound should be faded in volume wise + * @param channel tell the sound player to use a specific channel for playback + * + * @return channel playing the sound + */ int playSound(Common::File *fileHandle, bool loop = false, bool fadeIn = false, int channel = -1); + + /** + * Checks if a given channel is playing a sound. + * + * @param channel channel number to check + * @return true if playing, else false + */ bool isPlaying(int channel); + + /** + * Stop the playback of a sound in the given + * channel. + * + * @param channel channel number + */ void stopSound(int channel); + + /** + * Makes the sound in a given channel + * fading out. + * + * @param channel channel number + */ void beginFadeOut(int channel); private: KyraEngine *_vm; diff --git a/engines/kyra/sound_digital.cpp b/engines/kyra/sound_digital.cpp index 72d19ffd32..8b31cf4684 100644 --- a/engines/kyra/sound_digital.cpp +++ b/engines/kyra/sound_digital.cpp @@ -328,10 +328,6 @@ SoundDigital::~SoundDigital() { stopSound(i); } -bool SoundDigital::init() { - return true; -} - int SoundDigital::playSound(Common::File *fileHandle, bool loop, bool fadeIn, int channel) { Sound *use = 0; if (channel != -1 && channel < SOUND_STREAMS) { -- cgit v1.2.3