[Scummvm-git-logs] scummvm master -> d082a4837ff0789c0f7dac0c067497370e094575
criezy
criezy at scummvm.org
Tue Dec 1 23:54:45 UTC 2020
This automated email contains information about 1 new commit which have been
pushed to the 'scummvm' repo located at https://github.com/scummvm/scummvm .
Summary:
d082a4837f DOXYGEN: Review headers from 'audio'
Commit: d082a4837ff0789c0f7dac0c067497370e094575
https://github.com/scummvm/scummvm/commit/d082a4837ff0789c0f7dac0c067497370e094575
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-12-01T23:54:42Z
Commit Message:
DOXYGEN: Review headers from 'audio'
This PR has 3 headers in scope of GSoD.
The files are:
- audiostream.h
- mixer.h
- timestamp.h
The rest of the files are only receiving a doxy group.
Changed paths:
audio/audiostream.h
audio/fmopl.h
audio/mididrv.h
audio/midiparser.h
audio/midiparser_qt.h
audio/midiplayer.h
audio/miles.h
audio/mixer.h
audio/mixer_intern.h
audio/mt32gm.h
audio/musicplugin.h
audio/rate.h
audio/timestamp.h
doc/doxygen/groups.dox
diff --git a/audio/audiostream.h b/audio/audiostream.h
index 7f9bbe0563..b32cb9d922 100644
--- a/audio/audiostream.h
+++ b/audio/audiostream.h
@@ -36,6 +36,14 @@ class SeekableReadStream;
namespace Audio {
+/**
+ * @defgroup audio_audiostream Audio streams
+ * @ingroup audio
+ *
+ * @brief API for managing audio input streams.
+ * @{
+ */
+
/**
* Generic audio input stream. Subclasses of this are used to feed arbitrary
* sampled audio data into ScummVM's audio mixer.
@@ -45,78 +53,89 @@ public:
virtual ~AudioStream() {}
/**
- * Fill the given buffer with up to numSamples samples. Returns the actual
- * number of samples read, or -1 if a critical error occurred (note: you
- * *must* check if this value is less than what you requested, this can
- * happen when the stream is fully used up).
+ * Fill the given buffer with up to @p numSamples samples.
*
- * Data has to be in native endianess, 16 bit per sample, signed. For stereo
- * stream, buffer will be filled with interleaved left and right channel
- * samples, starting with a left sample. Furthermore, the samples in the
+ * Data must be in native endianness, 16 bits per sample, signed. For stereo
+ * stream, the buffer will be filled with interleaved left and right channel
+ * samples, starting with the left sample. Furthermore, the samples in the
* left and right are summed up. So if you request 4 samples from a stereo
* stream, you will get a total of two left channel and two right channel
* samples.
+ *
+ * @return The actual number of samples read, or -1 if a critical error occurred.
+ *
+ * @note You *must* check whether the returned value is less than what you requested.
+ * This indicates that the stream is fully used up.
+ *
*/
virtual int readBuffer(int16 *buffer, const int numSamples) = 0;
- /** Is this a stereo stream? */
+ /** Check whether this is a stereo stream. */
virtual bool isStereo() const = 0;
/** Sample rate of the stream. */
virtual int getRate() const = 0;
/**
- * End of data reached? If this returns true, it means that at this
- * time there is no data available in the stream. However there may be
- * more data in the future.
+ * Check whether end of data has been reached.
+ *
+ * If this returns true, it indicates that at this time there is no data
+ * available in the stream. However, there might be more data in the future.
+ *
* This is used by e.g. a rate converter to decide whether to keep on
- * converting data or stop.
+ * converting data or to stop.
*/
virtual bool endOfData() const = 0;
/**
- * End of stream reached? If this returns true, it means that all data
- * in this stream is used up and no additional data will appear in it
- * in the future.
+ * Check whether end of stream has been reached.
+ *
+ * If this returns true, it indicates that all data in this stream is used up
+ * and no additional data will appear in it in the future.
+ *
* This is used by the mixer to decide whether a given stream shall be
* removed from the list of active streams (and thus be destroyed).
- * By default this maps to endOfData()
+ * By default, this maps to endOfData().
*/
virtual bool endOfStream() const { return endOfData(); }
};
/**
- * A rewindable audio stream. This allows for reseting the AudioStream
- * to its initial state. Note that rewinding itself is not required to
- * be working when the stream is being played by Mixer!
+ * A rewindable audio stream.
+ *
+ * This allows for resetting the AudioStream to its initial state.
+ * Note that rewinding itself is not required to be working when the stream
+ * is being played by the mixer.
*/
class RewindableAudioStream : public virtual AudioStream {
public:
/**
- * Rewinds the stream to its start.
+ * Rewind the stream to its start.
*
- * @return true on success, false otherwise.
+ * @return True on success, false otherwise.
*/
virtual bool rewind() = 0;
};
/**
- * A looping audio stream. This object does nothing besides using
- * a RewindableAudioStream to play a stream in a loop.
+ * A looping audio stream.
+ *
+ * This object does nothing besides using a RewindableAudioStream
+ * to play a stream in a loop.
*/
class LoopingAudioStream : public AudioStream {
public:
/**
- * Creates a looping audio stream object.
- *
- * Note that on creation of the LoopingAudioStream object
- * the underlying stream will be rewound.
+ * Create a looping audio stream object.
*
+ * On creation of the LoopingAudioStream object, the underlying stream will be rewound.
+ *
* @see makeLoopingAudioStream
*
- * @param stream Stream to loop
- * @param loops How often to loop (0 = infinite)
- * @param disposeAfterUse Destroy the stream after the LoopingAudioStream has finished playback.
+ * @param stream The stream to loop.
+ * @param loops How often to loop (0 = infinite).
+ * @param disposeAfterUse Destroy the stream after the LoopingAudioStream has finished playback.
+ * @param rewind If true, rewind the underlying stream.
*/
LoopingAudioStream(RewindableAudioStream *stream, uint loops, DisposeAfterUse::Flag disposeAfterUse = DisposeAfterUse::YES, bool rewind = true);
@@ -128,7 +147,7 @@ public:
int getRate() const { return _parent->getRate(); }
/**
- * Returns number of loops the stream has played.
+ * Return the number of loops that the stream has played.
*/
uint getCompleteIterations() const { return _completeIterations; }
private:
@@ -139,59 +158,66 @@ private:
};
/**
- * Wrapper functionality to efficiently create a stream, which might be looped.
+ * Wrapper functionality to efficiently create a stream that might be looped.
*
- * Note that this function does not return a LoopingAudioStream, because it does
+ * This function does not return a LoopingAudioStream, because it does
* not create one when the loop count is "1". This allows to keep the runtime
- * overhead down, when the code does not require any functionality only offered
+ * overhead down when the code does not require any functionality that is only offered
* by LoopingAudioStream.
*
- * @param stream Stream to loop (will be automatically destroyed, when the looping is done)
- * @param loops How often to loop (0 = infinite)
- * @return A new AudioStream, which offers the desired functionality.
+ * @param stream The stream to loop (will be automatically destroyed, when the looping is done).
+ * @param loops How often to loop (0 = infinite).
+ *
+ * @return A new AudioStream that offers the desired functionality.
*/
AudioStream *makeLoopingAudioStream(RewindableAudioStream *stream, uint loops);
/**
- * A seekable audio stream. Subclasses of this class implement an
- * interface for seeking. The seeking itself is not required to be
- * working while the stream is being played by Mixer!
+ * A seekable audio stream.
+ *
+ * Subclasses of this class implement an interface for seeking.
+ * The seeking itself is not required to be working while the stream
+ * is being played by the mixer.
*/
class SeekableAudioStream : public virtual RewindableAudioStream {
public:
/**
- * Tries to load a file by trying all available formats.
+ * Attempt to load a file by trying all available formats.
+ *
* In case of an error, the file handle will be closed, but deleting
* it is still the responsibility of the caller.
*
- * @param basename a filename without an extension
- * @return an SeekableAudioStream ready to use in case of success;
- * NULL in case of an error (e.g. invalid/nonexisting file)
+ * @param basename File name without an extension.
+ *
+ * @return A SeekableAudioStream ready to use in case of success.
+ * NULL in case of an error (e.g. invalid/non-existing file).
*/
static SeekableAudioStream *openStreamFile(const Common::String &basename);
/**
- * Seeks to a given offset in the stream.
+ * Seek to a given offset in the stream.
+ *
+ * @param where Offset in milliseconds.
*
- * @param where offset in milliseconds
- * @return true on success, false on failure.
+ * @return True on success, false on failure.
*/
bool seek(uint32 where) {
return seek(Timestamp(where, getRate()));
}
/**
- * Seeks to a given offset in the stream.
+ * Seek to a given offset in the stream.
*
- * @param where offset as timestamp
- * @return true on success, false on failure.
+ * @param where Offset as a timestamp.
+ *
+ * @return True on success, false on failure.
*/
virtual bool seek(const Timestamp &where) = 0;
/**
- * Returns the length of the stream.
+ * Return the length of the stream.
*
- * @return length as Timestamp.
+ * @return Length as a timestamp.
*/
virtual Timestamp getLength() const = 0;
@@ -199,49 +225,48 @@ public:
};
/**
- * Wrapper functionality to efficiently create a stream, which might be looped
+ * Wrapper functionality to efficiently create a stream that might be looped
* in a certain interval.
*
* This automatically starts the stream at time "start"!
*
- * Note that this function does not return a LoopingAudioStream, because it does
+ * This function does not return a LoopingAudioStream, because it does
* not create one when the loop count is "1". This allows to keep the runtime
- * overhead down, when the code does not require any functionality only offered
+ * overhead down when the code does not require any functionality that is only offered
* by LoopingAudioStream.
*
- * @param stream Stream to loop (will be automatically destroyed, when the looping is done)
- * @param start Starttime of the stream interval to be looped
- * @param end End of the stream interval to be looped (a zero time, means till end)
- * @param loops How often to loop (0 = infinite)
- * @return A new AudioStream, which offers the desired functionality.
+ * @param stream The stream to loop (will be automatically destroyed when the looping is done).
+ * @param start Start time of the stream interval to be looped.
+ * @param end End of the stream interval to be looped (a zero time means till the end).
+ * @param loops How often to loop (0 = infinite).
+ *
+ * @return A new AudioStream that offers the desired functionality.
*/
AudioStream *makeLoopingAudioStream(SeekableAudioStream *stream, Timestamp start, Timestamp end, uint loops);
/**
- * A looping audio stream, which features looping of a nested part of the
+ * A looping audio stream that features looping of a nested part of the
* stream.
*
- * NOTE:
- * Currently this implementation stops after the nested loop finished
- * playback.
+ * @note Currently this implementation stops after the nested loop finishes
+ * playback.
*
- * IMPORTANT:
- * This might be merged with SubSeekableAudioStream for playback purposes.
- * (After extending it to accept a start time).
+ * @b Important: This can be merged with SubSeekableAudioStream for playback purposes.
+ * To do this, it must be extended to accept a start time.
*/
class SubLoopingAudioStream : public AudioStream {
public:
/**
* Constructor for a SubLoopingAudioStream.
*
- * Note that on creation of the SubLoopingAudioStream object
+ * On creation of the SubLoopingAudioStream object,
* the underlying stream will be rewound.
*
- * @param stream Stream to loop
- * @param loops How often the stream should be looped (0 means infinite)
- * @param loopStart Start of the loop (this must be smaller than loopEnd)
- * @param loopEnd End of the loop (thus must be greater than loopStart)
- * @param disposeAfterUse Whether the stream should be disposed, when the
+ * @param stream The stream to loop.
+ * @param loops How often the stream should be looped (0 means infinite).
+ * @param loopStart Start of the loop (this must be smaller than @p loopEnd).
+ * @param loopEnd End of the loop (thus must be greater than @p loopStart).
+ * @param disposeAfterUse Whether the stream should be disposed when the
* SubLoopingAudioStream is destroyed.
*/
SubLoopingAudioStream(SeekableAudioStream *stream, uint loops,
@@ -267,18 +292,19 @@ private:
/**
- * A SubSeekableAudioStream provides access to a SeekableAudioStream
+ * A SubSeekableAudioStream class that provides access to a SeekableAudioStream
* just in the range [start, end).
+ *
* The same caveats apply to SubSeekableAudioStream as do to SeekableAudioStream.
*
- * Manipulating the parent stream directly /will/ mess up a substream.
+ * Manipulating the parent stream directly will break the substream.
*/
class SubSeekableAudioStream : public SeekableAudioStream {
public:
/**
- * Creates a new SubSeekableAudioStream.
+ * Create a new SubSeekableAudioStream.
*
- * @param parent parent stream object.
+ * @param parent Parent stream object.
* @param start Start time.
* @param end End time.
* @param disposeAfterUse Whether the parent stream object should be destroyed on destruction of the SubSeekableAudioStream.
@@ -305,37 +331,44 @@ private:
Timestamp _pos;
};
+/**
+ * A QueuingAudioStream class that allows for queuing multiple audio streams for playback.
+ */
+
class QueuingAudioStream : public Audio::AudioStream {
public:
/**
- * Queue an audio stream for playback. This stream plays all queued
- * streams, in the order they were queued. If disposeAfterUse is set to
- * DisposeAfterUse::YES, then the queued stream is deleted after all data
- * contained in it has been played.
+ * Queue an audio stream for playback.
+ *
+ * This stream plays all queued streams, in the order in which they were queued.
+ * If disposeAfterUse is set to DisposeAfterUse::YES, then the queued stream
+ * is deleted after all data contained in it has been played.
*/
virtual void queueAudioStream(Audio::AudioStream *audStream,
DisposeAfterUse::Flag disposeAfterUse = DisposeAfterUse::YES) = 0;
/**
- * Queue a block of raw audio data for playback. This stream plays all
- * queued block, in the order they were queued. If disposeAfterUse is set
- * to DisposeAfterUse::YES, then the queued block is released using free()
- * after all data contained in it has been played.
+ * Queue a block of raw audio data for playback.
+ *
+ * This stream plays all queued blocks, in the order in which they were queued.
+ * If disposeAfterUse is set to DisposeAfterUse::YES, then the queued block is
+ * released using free() after all data contained in it has been played.
*
* @note Make sure to allocate the data block with malloc(), not with new[].
*
- * @param data pointer to the audio data block
- * @param size length of the audio data block
- * @param disposeAfterUse if equal to DisposeAfterUse::YES, the block is released using free() after use.
- * @param flags a bit-ORed combination of RawFlags describing the audio data format
+ * @param data Pointer to the audio data block.
+ * @param size Length of the audio data block.
+ * @param disposeAfterUse If equal to DisposeAfterUse::YES, the block is released using free() after use.
+ * @param flags A bit-ORed combination of RawFlags describing the audio data format.
*/
void queueBuffer(byte *data, uint32 size, DisposeAfterUse::Flag disposeAfterUse, byte flags);
/**
- * Mark this stream as finished. That is, signal that no further data
- * will be queued to it. Only after this has been done can this
- * stream ever 'end'.
+ * Mark this stream as finished.
+ *
+ * This is used to signal that no further data will be queued to the stream.
+ * The stream is only considered as ended after this has been done.
*/
virtual void finish() = 0;
@@ -347,17 +380,17 @@ public:
};
/**
- * Factory function for an QueuingAudioStream.
+ * Factory function for a QueuingAudioStream.
*/
QueuingAudioStream *makeQueuingAudioStream(int rate, bool stereo);
/**
- * Converts a point in time to a precise sample offset
+ * Convert a point in time to a precise sample offset
* with the given parameters.
*
- * @param where Point in time.
- * @param rate Rate of the stream.
- * @param isStereo Is the stream a stereo stream?
+ * @param where Point in time.
+ * @param rate Rate of the stream.
+ * @param isStereo Whether the stream is a stereo stream.
*/
Timestamp convertTimeToStreamPos(const Timestamp &where, int rate, bool isStereo);
@@ -365,16 +398,16 @@ Timestamp convertTimeToStreamPos(const Timestamp &where, int rate, bool isStereo
* Factory function for an AudioStream wrapper that cuts off the amount of samples read after a
* given time length is reached.
*
- * @param parentStream The stream to limit
- * @param length The time length to limit the stream to
- * @param disposeAfterUse Whether the parent stream object should be destroyed on destruction of the returned stream
+ * @param parentStream The stream to limit.
+ * @param length The time length to limit the stream to.
+ * @param disposeAfterUse Whether the parent stream object should be destroyed on destruction of the returned stream.
*/
AudioStream *makeLimitingAudioStream(AudioStream *parentStream, const Timestamp &length, DisposeAfterUse::Flag disposeAfterUse = DisposeAfterUse::YES);
/**
* An AudioStream designed to work in terms of packets.
*
- * It is similar in concept to QueuingAudioStream, but does not
+ * It is similar in concept to the QueuingAudioStream, but does not
* necessarily rely on the data from each queued AudioStream
* being separate.
*/
@@ -389,21 +422,26 @@ public:
/**
* Mark this stream as finished. That is, signal that no further data
- * will be queued to it. Only after this has been done can this
- * stream ever 'end'.
+ *
+ * This is used to signal that no further data will be queued to the stream.
+ * The stream is only considered as ended after this has been done.
*/
virtual void finish() = 0;
};
/**
* A PacketizedAudioStream that works closer to a QueuingAudioStream.
- * It queues individual packets as whole AudioStream to an internal
+ *
+ * It queues individual packets as a whole AudioStream to an internal
* QueuingAudioStream. This is used for writing quick wrappers against
- * e.g. RawStream, which can be made into PacketizedAudioStreams with
- * little effort.
+ * e.g. RawStream, which can be then made into PacketizedAudioStreams.
*/
class StatelessPacketizedAudioStream : public PacketizedAudioStream {
public:
+ /**
+ * Create a StatelessPacketizedAudioStream with the specified sample rate
+ * and for the specified number of channels.
+ */
StatelessPacketizedAudioStream(uint rate, uint channels) :
_rate(rate), _channels(channels), _stream(makeQueuingAudioStream(rate, channels == 2)) {}
virtual ~StatelessPacketizedAudioStream() {}
@@ -419,11 +457,14 @@ public:
void queuePacket(Common::SeekableReadStream *data) { _stream->queueAudioStream(makeStream(data)); }
void finish() { _stream->finish(); }
+ /**
+ * Return how many channels this stream is using.
+ */
uint getChannels() const { return _channels; }
protected:
/**
- * Make the AudioStream for a given packet
+ * Create an AudioStream for a given packet.
*/
virtual AudioStream *makeStream(Common::SeekableReadStream *data) = 0;
@@ -438,7 +479,7 @@ private:
* endOfStream() has been reached.
*/
AudioStream *makeNullAudioStream();
-
+/** @} */
} // End of namespace Audio
#endif
diff --git a/audio/fmopl.h b/audio/fmopl.h
index ba0872d87b..cb8d6d01b4 100644
--- a/audio/fmopl.h
+++ b/audio/fmopl.h
@@ -41,6 +41,14 @@ namespace OPL {
class OPL;
+/**
+ * @defgroup audio_fmopl OPL emulation
+ * @ingroup audio
+ *
+ * @brief OPL class for managing an OPS emulator.
+ * @{
+ */
+
class Config {
public:
enum OplFlags {
@@ -279,7 +287,7 @@ private:
Audio::SoundHandle *_handle;
};
-
+/** @} */
} // End of namespace OPL
#endif
diff --git a/audio/mididrv.h b/audio/mididrv.h
index acba961ccf..b198a1e487 100644
--- a/audio/mididrv.h
+++ b/audio/mididrv.h
@@ -31,6 +31,14 @@
class MidiChannel;
+/**
+ * @defgroup audio_mididrv MIDI drivers
+ * @ingroup audio
+ *
+ * @brief API for managing MIDI drivers.
+ * @{
+ */
+
/**
* Music types that music drivers can implement and engines can rely on.
*/
@@ -462,5 +470,5 @@ public:
// SysEx messages
virtual void sysEx_customInstrument(uint32 type, const byte *instr) = 0;
};
-
+/** @} */
#endif
diff --git a/audio/midiparser.h b/audio/midiparser.h
index bad770aa40..5896cd47b2 100644
--- a/audio/midiparser.h
+++ b/audio/midiparser.h
@@ -30,6 +30,13 @@
class MidiDriver_BASE;
+/**
+ * @defgroup audio_midiparser MIDI parser
+ * @ingroup audio
+ *
+ * @brief A framework and common functionality for parsing event-based music streams.
+ * @{
+ */
//////////////////////////////////////////////////
@@ -488,5 +495,5 @@ public:
static MidiParser *createParser_QT();
static void timerCallback(void *data) { ((MidiParser *) data)->onTimer(); }
};
-
+/** @} */
#endif
diff --git a/audio/midiparser_qt.h b/audio/midiparser_qt.h
index 1c811fdb36..d7d9a435fb 100644
--- a/audio/midiparser_qt.h
+++ b/audio/midiparser_qt.h
@@ -29,6 +29,14 @@
#include "common/queue.h"
#include "common/quicktime.h"
+/**
+ * @defgroup audio_midiparser_qt QT MIDI parser
+ * @ingroup audio
+ *
+ * @brief The QuickTime Music version of MidiParser class.
+ * @{
+ */
+
/**
* The QuickTime Music version of MidiParser.
*
@@ -130,5 +138,5 @@ private:
void initCommon();
uint32 readUint32();
};
-
+/** @} */
#endif
diff --git a/audio/midiplayer.h b/audio/midiplayer.h
index 7b81cd9705..059c428910 100644
--- a/audio/midiplayer.h
+++ b/audio/midiplayer.h
@@ -31,6 +31,14 @@ class MidiParser;
namespace Audio {
+/**
+ * @defgroup audio_midiplayer MIDI player
+ * @ingroup audio
+ *
+ * @brief MidiPlayer class for playing MIDI sounds.
+ * @{
+ */
+
/**
* Simple MIDI playback class.
*
@@ -182,7 +190,7 @@ protected:
bool _nativeMT32;
};
-
+/** @} */
} // End of namespace Audio
#endif
diff --git a/audio/miles.h b/audio/miles.h
index 9773a9b735..73b3ba81a4 100644
--- a/audio/miles.h
+++ b/audio/miles.h
@@ -33,6 +33,14 @@
namespace Audio {
+/**
+ * @defgroup audio_miles Miles and XMIDI
+ * @ingroup audio
+ *
+ * @brief API for managing XMIDI files used by Miles Sound System.
+ * @{
+ */
+
// Miles Audio supported controllers for control change messages
#define MILES_CONTROLLER_SELECT_PATCH_BANK 114
#define MILES_CONTROLLER_PROTECT_VOICE 112
@@ -299,7 +307,7 @@ extern MidiDriver *MidiDriver_Miles_AdLib_create(const Common::String &filenameA
extern MidiDriver_Miles_Midi *MidiDriver_Miles_MT32_create(const Common::String &instrumentDataFilename);
extern MidiDriver_Miles_Midi *MidiDriver_Miles_MIDI_create(MusicType midiType, const Common::String &instrumentDataFilename);
-
+/** @} */
} // End of namespace Audio
#endif // AUDIO_MILES_MIDIDRIVER_H
diff --git a/audio/mixer.h b/audio/mixer.h
index 9f114c330a..f322d502ac 100644
--- a/audio/mixer.h
+++ b/audio/mixer.h
@@ -33,10 +33,18 @@ class Channel;
class Timestamp;
/**
- * A SoundHandle instances corresponds to a specific sound
- * being played via the mixer. It can be used to control that
+ * @defgroup audio_mixer Mixer
+ * @ingroup audio
+ *
+ * @brief Mixer class used for playing audio streams.
+ * @{
+ */
+
+/**
+ * A SoundHandle instance corresponds to a specific sound
+ * being played using the mixer. It can be used to control that
* sound (pause it, stop it, etc.).
- * @see The Mixer class
+ * @see Mixer
*/
class SoundHandle {
friend class Channel;
@@ -47,22 +55,23 @@ public:
};
/**
- * The main audio mixer handles mixing of an arbitrary number of
+ * The main audio mixer that handles mixing of an arbitrary number of
* audio streams (in the form of AudioStream instances).
*/
class Mixer : Common::NonCopyable {
public:
+ /** Sound types. */
enum SoundType {
- kPlainSoundType = 0,
+ kPlainSoundType = 0, /*!< Plain sound. */
- kMusicSoundType = 1,
- kSFXSoundType = 2,
- kSpeechSoundType = 3
+ kMusicSoundType = 1, /*!< Music. */
+ kSFXSoundType = 2, /*!< Sound effects. */
+ kSpeechSoundType = 3 /*!< Speech. */
};
-
+ /** Max volumes. */
enum {
- kMaxChannelVolume = 255,
- kMaxMixerVolume = 256
+ kMaxChannelVolume = 255, /*!< Max channel volume. */
+ kMaxMixerVolume = 256 /*!< Max global volume. */
};
public:
@@ -72,12 +81,14 @@ public:
/**
- * Is the mixer ready and setup? This may not be the case on systems which
- * don't support digital sound output. In that case, the mixer proc may
- * never be called. That in turn can cause breakage in games which try to
- * sync with an audio stream. In particular, the AdLib MIDI emulation...
+ * Check whether the mixer is ready and set up.
+ *
+ * The mixer might not be set up on systems that do not support
+ * digital sound output. In such case, the mixer processing might
+ * never be called. That, in turn, can cause breakage in games that try to
+ * sync with an audio stream. In particular, the AdLib MIDI emulation.
*
- * @return whether the mixer is ready and setup
+ * @return Whether the mixer is ready and set up.
*
* @todo get rid of this?
*/
@@ -87,22 +98,21 @@ public:
/**
* Start playing the given audio stream.
*
- * Note that the sound id assigned below is unique. At most one stream
- * with a given id can play at any given time. Trying to play a sound
- * with an id that is already in use causes the new sound to be not played.
+ * Note that the sound ID assigned here is unique. At most, one stream
+ * with the given ID can play at any given time. Trying to play a sound
+ * with an ID that is already in use causes the new sound to not be played.
*
- * @param type the type (voice/sfx/music) of the stream
- * @param handle a SoundHandle which can be used to reference and control
- * the stream via suitable mixer methods
- * @param stream the actual AudioStream to be played
- * @param id a unique id assigned to this stream
- * @param volume the volume with which to play the sound, ranging from 0 to 255
- * @param balance the balance with which to play the sound, ranging from -127 to 127 (full left to full right), 0 is balanced, -128 is invalid
- * @param autofreeStream a flag indicating whether the stream should be
- * freed after playback finished
- * @param permanent a flag indicating whether a plain stopAll call should
- * not stop this particular stream
- * @param reverseStereo a flag indicating whether left and right channels shall be swapped
+ * @param type Type of the stream - voice/SFX/music.
+ * @param handle A SoundHandle instance that can be used to reference and control
+ * the stream using suitable mixer methods.
+ * @param stream The actual AudioStream to be played.
+ * @param id Unique ID assigned to this stream.
+ * @param volume Volume with which to play the sound, ranging from 0 to 255.
+ * @param balance Balance with which to play the sound, ranging from -127 to 127 (full left to full right).
+ * 0 is balanced, -128 is invalid.
+ * @param autofreeStream If set, the stream will be freed after the playback is finished.
+ * @param permanent If set, a plain stopAll call will not stop this particular stream.
+ * @param reverseStereo If set, left and right channels will be swapped.
*/
virtual void playStream(
SoundType type,
@@ -121,68 +131,71 @@ public:
virtual void stopAll() = 0;
/**
- * Stop playing the sound with given ID.
+ * Stop playing the sound with the given ID.
*
- * @param id the ID of the sound to affect
+ * @param id ID of the sound.
*/
virtual void stopID(int id) = 0;
/**
* Stop playing the sound corresponding to the given handle.
*
- * @param handle the sound to affect
+ * @param handle The sound to stop playing.
*/
virtual void stopHandle(SoundHandle handle) = 0;
/**
- * Pause/unpause all sounds, including all regular and permanent
- * channels
+ * Pause or unpause all sounds, including all regular and permanent
+ * channels.
*
- * @param paused true to pause everything, false to unpause
+ * @param paused True to pause everything, false to unpause.
*/
virtual void pauseAll(bool paused) = 0;
/**
- * Pause/unpause the sound with the given ID.
+ * Pause or unpause the sound with the given ID.
*
- * @param id the ID of the sound to affect
- * @param paused true to pause the sound, false to unpause it
+ * @param id ID of the sound.
+ * @param paused True to pause the sound, false to unpause it.
*/
virtual void pauseID(int id, bool paused) = 0;
/**
- * Pause/unpause the sound corresponding to the given handle.
+ * Pause or unpause the sound corresponding to the given handle.
*
- * @param handle the sound to affect
- * @param paused true to pause the sound, false to unpause it
+ * @param handle The sound to pause or unpause.
+ * @param paused True to pause the sound, false to unpause it.
*/
virtual void pauseHandle(SoundHandle handle, bool paused) = 0;
/**
- * Check if a sound with the given ID is active.
+ * Check whether a sound with the given ID is active.
*
- * @param id the ID of the sound to query
- * @return true if the sound is active
+ * @param id ID of the sound to query.
+ *
+ * @return True if the sound is active.
*/
virtual bool isSoundIDActive(int id) = 0;
/**
- * Get the sound ID of handle sound
+ * Get the sound ID for the given handle.
+ *
+ * @param handle The sound to query.
*
- * @param handle sound to query
- * @return sound ID if active
+ * @return Sound ID if the sound is active.
*/
virtual int getSoundID(SoundHandle handle) = 0;
/**
- * Check if a sound with the given handle is active.
+ * Check whether a sound with the given handle is active.
*
- * @param handle sound to query
- * @return true if the sound is active
+ * @param handle The sound to query.
+ *
+ * @return True if the sound is active.
*/
virtual bool isSoundHandleActive(SoundHandle handle) = 0;
@@ -190,7 +203,7 @@ public:
/**
* Set the mute state for a given sound type.
*
- * @param type the sound type
+ * @param type Sound type. See @ref SoundType.
* @param mute Whether to mute (= true) or not (= false).
*/
virtual void muteSoundType(SoundType type, bool mute) = 0;
@@ -198,88 +211,93 @@ public:
/**
* Query the mute state for a given sound type.
*
- * @param type the sound type
+ * @param type Sound type. See @ref SoundType.
*/
virtual bool isSoundTypeMuted(SoundType type) const = 0;
/**
* Set the channel volume for the given handle.
*
- * @param handle the sound to affect
- * @param volume the new channel volume (0 - kMaxChannelVolume)
+ * @param handle The sound to affect.
+ * @param volume The new channel volume, in the range 0 - kMaxChannelVolume.
*/
virtual void setChannelVolume(SoundHandle handle, byte volume) = 0;
/**
* Get the channel volume for the given handle.
*
- * @param handle the sound to affect
- * @return channel volume
+ * @param handle The sound to affect.
+ *
+ * @return The channel volume.
*/
virtual byte getChannelVolume(SoundHandle handle) = 0;
/**
* Set the channel balance for the given handle.
*
- * @param handle the sound to affect
- * @param balance the new channel balance:
- * (-127 ... 0 ... 127) corresponds to (left ... center ... right)
+ * @param handle The sound to affect.
+ * @param balance The new channel balance:
+ * (-127 ... 0 ... 127) corresponds to (left ... center ... right)
*/
virtual void setChannelBalance(SoundHandle handle, int8 balance) = 0;
/**
* Get the channel balance for the given handle.
*
- * @param handle the sound to affect
- * @return channel balance
+ * @param handle The sound to affect.
+ *
+ * @return The channel balance.
*/
virtual int8 getChannelBalance(SoundHandle handle) = 0;
/**
- * Get approximation of for how long the channel has been playing.
+ * Get an approximation of for how long the channel has been playing.
*/
virtual uint32 getSoundElapsedTime(SoundHandle handle) = 0;
/**
- * Get approximation of for how long the channel has been playing.
+ * Get an approximation of for how long the channel has been playing.
*/
virtual Timestamp getElapsedTime(SoundHandle handle) = 0;
/**
* Check whether any channel of the given sound type is active.
+ *
* For example, this can be used to check whether any SFX sound
- * is currently playing, by checking for type kSFXSoundType.
+ * is currently playing by checking for type kSFXSoundType.
*
- * @param type the sound type to look for
- * @return true if any channels of the specified type are active.
+ * @param type The sound type to query.
+ *
+ * @return True if any channels of the specified type are active.
*/
virtual bool hasActiveChannelOfType(SoundType type) = 0;
/**
* Set the volume for the given sound type.
*
- * @param type the sound type
- * @param volume the new global volume, 0 - kMaxMixerVolume
+ * @param type Sound type.
+ * @param volume The new global volume, in the range 0 - kMaxMixerVolume.
*/
virtual void setVolumeForSoundType(SoundType type, int volume) = 0;
/**
- * Query the global volume.
+ * Check what the global volume is for a sound type.
+ *
+ * @param type Sound type.
*
- * @param type the sound type
- * @return the global music volume, 0 - kMaxMixerVolume
+ * @return The global volume, in the range 0 - kMaxMixerVolume.
*/
virtual int getVolumeForSoundType(SoundType type) const = 0;
/**
- * Query the system's audio output sample rate.
+ * Return the output sample rate of the system.
*
- * @return the output sample rate in Hz
+ * @return The output sample rate in Hz.
*/
virtual uint getOutputRate() const = 0;
};
-
+/** @} */
} // End of namespace Audio
#endif
diff --git a/audio/mixer_intern.h b/audio/mixer_intern.h
index bac256c8b5..44c187e406 100644
--- a/audio/mixer_intern.h
+++ b/audio/mixer_intern.h
@@ -29,6 +29,14 @@
namespace Audio {
+/**
+ * @defgroup audio_mixer_intern Mixer implementation
+ * @ingroup audio
+ *
+ * @brief The (default) implementation of the ScummVM audio mixing subsystem.
+ * @{
+ */
+
/**
* The (default) implementation of the ScummVM audio mixing subsystem.
*
@@ -141,7 +149,7 @@ public:
void setReady(bool ready);
};
-
+/** @} */
} // End of namespace Audio
#endif
diff --git a/audio/mt32gm.h b/audio/mt32gm.h
index 933b52e8e7..229dfb6ef5 100644
--- a/audio/mt32gm.h
+++ b/audio/mt32gm.h
@@ -27,7 +27,15 @@
#include "common/mutex.h"
#include "common/queue.h"
-/*
+/**
+ * @defgroup audio_mt32_gm MIDI driver for MT-32 and GM
+ * @ingroup audio
+ *
+ * @brief MIDI driver for MT-32 and GM compatible emulators and devices.
+ * @{
+ */
+
+/**
* MIDI driver for MT-32 and GM compatible emulators and devices.
*
* This class contains some commonly needed functionality for these devices and
@@ -661,5 +669,5 @@ public:
driver->_timer_proc(driver->_timer_param);
}
};
-
+/** @} */
#endif
diff --git a/audio/musicplugin.h b/audio/musicplugin.h
index 705d7a9552..aa3d59513d 100644
--- a/audio/musicplugin.h
+++ b/audio/musicplugin.h
@@ -33,6 +33,14 @@ class Error;
class MusicPluginObject;
+/**
+ * @defgroup audio_musicplugin Music devices and plugins
+ * @ingroup audio
+ *
+ * @brief API for managing music devices and music plugins.
+ * @{
+ */
+
/**
* Description of a Music device. Used to list the devices a Music driver
* can manage and their capabilities.
@@ -125,5 +133,5 @@ public:
/** Convenience shortcut for accessing the Music manager. */
#define MusicMan MusicManager::instance()
-
+/** @} */
#endif
diff --git a/audio/rate.h b/audio/rate.h
index cbfaf2c12b..ca9684e07e 100644
--- a/audio/rate.h
+++ b/audio/rate.h
@@ -26,6 +26,13 @@
#include "common/scummsys.h"
namespace Audio {
+/**
+ * @defgroup audio_rate Sample rate
+ * @ingroup audio
+ *
+ * @brief API for managing sound sample rate.
+ * @{
+ */
class AudioStream;
@@ -79,7 +86,7 @@ public:
};
RateConverter *makeRateConverter(st_rate_t inrate, st_rate_t outrate, bool stereo, bool reverseStereo = false);
-
+/** @} */
} // End of namespace Audio
#endif
diff --git a/audio/timestamp.h b/audio/timestamp.h
index 827a8e03f2..3c1721dee9 100644
--- a/audio/timestamp.h
+++ b/audio/timestamp.h
@@ -28,11 +28,16 @@
namespace Audio {
/**
- * Timestamps allow specifying points in time and measuring time intervals
- * with a sub-millisecond granularity.
+ * @defgroup audio_timestamp Timestamp
+ * @ingroup audio
*
- * When dealing with audio and video decoding, it is often necessary to
- * measure time (intervals) in terms of frames, relative to a fixed
+ * @brief Timestamp class for specifying points in time and measuring time intervals.
+ * @{
+ */
+
+/**
+* When dealing with audio and video decoding, it is often necessary to
+ * measure the time (intervals) in terms of frames, relative to a fixed
* frame rate (that is, a fixed number of frames per seconds). For
* example, in a typical video there are 24 frames per second, and in a
* typical sound there are 44100 frames (i.e. samples for mono sound
@@ -40,116 +45,145 @@ namespace Audio {
*
* At the same time, the system clock provided by ScummVM measures time
* in milliseconds. For syncing purposes and other reasons, it is often
- * necessary to convert between and compare time measures given on the
+ * necessary to convert between and compare time measures given on
* one hand as a frame count, and on the other hand as a number of
* milliseconds.
*
* If handled carelessly, this can introduce rounding errors that
- * quickly accumulate, resulting in user noticeable disturbance, such as
- * audio and video running out of sync. E.g. a typical approach is to
+ * quickly accumulate, resulting in user-noticeable disturbance, such as
+ * audio and video running out of sync. For example, a typical approach is to
* measure all time in milliseconds. But with a frame rate of 24 frames
* per second, one frame is 41.66666... milliseconds long. On the other
- * hand, if measuring in frames, then similar rounding issue occur when
+ * hand, if measuring in frames, then a similar rounding issue occurs when
* converting from milliseconds to frames.
*
* One solution is to use floating point arithmetic to compute with
* fractional frames resp. (milli)seconds. This has other undesirable
- * side effects; foremost, some platforms ScummVM runs on still have
+ * side effects. Foremost, some platforms that ScummVM runs on still have
* only limited (and slow) floating point support.
*
- * This class provides an alternate solution: It stores time in terms of
- * frames, but with a twist: Client code can specify arbitrary
- * (integral) framerates; but internally, Timestamp modifies the
- * framerate to be a multiple of 1000. This way, both numbers of frames
- * (relative to the original framerate) as well as milliseconds can be
+ * This class provides an alternative solution. It stores time in terms of
+ * frames, but with a twist: client code can specify arbitrary
+ * (integral) frame rates but, internally, Timestamp modifies the
+ * frame rate to be a multiple of 1000. This way, both the number of frames
+ * (relative to the original frame rate), as well as milliseconds can be
* represented as integers. This change is completely hidden from the
* user, however.
*
- * A Timestamp can be converted to a frame count or milliseconds at
- * virtually no cost. Likewise, it is posible to compute the difference
- * between two Timestamps in milliseconds or number of frames.
+ * A timestamp can be converted to a frame count or milliseconds at
+ * virtually no cost. Likewise, it is possible to compute the difference
+ * between two timestamps in terms of milliseconds or number of frames.
* Timestamps can be easily compared using regular comparison operators,
- * resulting in nicely readable code; this is even possible for
- * timestamps that are specified using different framerates.
- * Client code can modify Timestamps by adding a number of frames
+ * resulting in nicely readable code. This is even possible for
+ * timestamps that are specified using different frame rates.
+ * Client code can modify timestamps by adding a number of frames
* to it, or adding a number of milliseconds. Adding negative amounts is
- * also allowed, and a Timestamp can even represent a "negative time"
- * (mainly useful when using the Timestamp to store a time interval).
+ * also allowed, and a timestamp can even represent a "negative time",
+ * which is useful when using the timestamp to store a time interval.
*/
class Timestamp {
public:
/**
- * Set up a timestamp with a given time and framerate.
- * @param msecs starting time in milliseconds
- * @param framerate number of frames per second (must be > 0)
+ * Set up a timestamp with a given time and frame rate.
+ *
+ * @param msecs Starting time in milliseconds.
+ * @param framerate Number of frames per second (must be > 0).
*/
Timestamp(uint msecs = 0, uint framerate = 1);
/**
- * Set up a timestamp with a given time, frames and framerate.
- * @param secs starting time in seconds
- * @param frames starting frames
- * @param framerate number of frames per second (must be > 0)
+ * Set up a timestamp with the given time, frames, and frame rate.
+ *
+ * @param secs Starting time in seconds.
+ * @param frames Starting frames.
+ * @param framerate Number of frames per second (must be > 0).
*/
Timestamp(uint secs, uint frames, uint framerate);
/**
- * Return a timestamp which represents as closely as possible
- * the point in time describes by this timestamp, but with
- * a different framerate.
+ * Return a timestamp that represents as closely as possible
+ * the point in time described by this timestamp, but with
+ * a different frame rate.
*/
Timestamp convertToFramerate(uint newFramerate) const;
/**
- * Check whether to timestamps describe the exact same moment
- * in time. This means that two timestamps can compare
- * as equal even if they use different framerates.
+ * Check whether two timestamps describe the exact same moment
+ * in time.
+ *
+ * This means that two timestamps can compare as equal
+ * even if they use different frame rates.
*/
bool operator==(const Timestamp &ts) const;
+ /**
+ * Check whether two timestamps describe a different moment in time.
+ */
bool operator!=(const Timestamp &ts) const;
+ /**
+ * Check whether this timestamp describes an earlier moment in time than another timestamp.
+ */
bool operator<(const Timestamp &ts) const;
+ /**
+ * Check whether this timestamp describes an earlier or the same moment in time as another timestamp.
+ */
bool operator<=(const Timestamp &ts) const;
+ /**
+ * Check whether this timestamp describes a later moment in time than another timestamp.
+ */
bool operator>(const Timestamp &ts) const;
+ /**
+ * Check whether this timestamp describes a later or the same moment in time as another timestamp.
+ */
bool operator>=(const Timestamp &ts) const;
/**
- * Returns a new timestamp, which corresponds to the time encoded
+ * Return a new timestamp that corresponds to the time encoded
* by this timestamp with the given number of frames added.
- * @param frames number of frames to add
+ *
+ * @param frames Number of frames to add.
*/
Timestamp addFrames(int frames) const;
/**
- * Returns a new timestamp, which corresponds to the time encoded
+ * Return a new timestamp that corresponds to the time encoded
* by this timestamp with the given number of milliseconds added.
- * @param msecs number of milliseconds to add
+ *
+ * @param msecs Number of milliseconds to add.
*/
Timestamp addMsecs(int msecs) const;
- // unary minus
+ /**
+ * Return a new timestamp with the negative value of the time encoded
+ * by this timestamp.
+ *
+ * This is a unary minus operation.
+ */
Timestamp operator-() const;
/**
- * Compute the sum of two timestamps. This is only
- * allowed if they use the same framerate.
+ * Compute the sum of two timestamps.
+ *
+ * This is only allowed if they use the same frame rate.
*/
Timestamp operator+(const Timestamp &ts) const;
/**
- * Compute the difference between two timestamps. This is only
- * allowed if they use the same framerate.
+ * Compute the difference between two timestamps.
+ *
+ * This is only allowed if they use the same frame rate.
*/
Timestamp operator-(const Timestamp &ts) const;
/**
- * Computes the number of frames between this timestamp and ts.
- * The frames are with respect to the framerate used by this
- * Timestamp (which may differ from the framerate used by ts).
+ * Compute the number of frames between this timestamp and @p ts.
+ *
+ * The frames are counted with respect to the frame rate used by this
+ * timestamp (which may differ from the frame rate used by @p ts).
*/
int frameDiff(const Timestamp &ts) const;
- /** Computes the number off milliseconds between this timestamp and ts. */
+ /** Compute the number of milliseconds between this timestamp and @p ts. */
int msecsDiff(const Timestamp &ts) const;
/**
@@ -182,7 +216,7 @@ public:
return _numFrames / (int)_framerateFactor;
}
- /** Return the framerate used by this timestamp. */
+ /** Return the frame rate used by this timestamp. */
inline uint framerate() const { return _framerate / _framerateFactor; }
protected:
@@ -194,7 +228,7 @@ protected:
/**
* Normalize this timestamp by making _numFrames non-negative
- * and reducing it modulo _framerate.
+ * and reducing its modulo _framerate.
*/
void normalize();
@@ -208,41 +242,48 @@ protected:
* The seconds part of this timestamp.
* The total time in seconds represented by this timestamp can be
* computed as follows:
+ * @code
* _secs + (double)_numFrames / _framerate
+ * @endcode
*/
int _secs;
/**
- * The number of frames which together with _secs encodes the
- * timestamp. The total number of *internal* frames represented
+ * The number of frames that, together with @c _secs, encode the
+ * timestamp.
+ *
+ * The total number of *internal* frames represented
* by this timestamp can be computed as follows:
+ * @code
* _numFrames + _secs * _framerate
+ * @endcode
* To obtain the number of frames with respect to the original
- * framerate, this value has to be divided by _framerateFactor.
+ * frame rate, this value must be divided by _framerateFactor.
*
- * This is always a value greater or equal to zero.
- * The only reason this is an int and not an uint is to
+ * This is always a value greater than or equal to zero.
+ * The only reason this is an int and not a uint is to
* allow intermediate negative values.
*/
int _numFrames;
/**
- * The internal framerate, i.e. the number of frames per second.
- * This is computed as the least common multiple of the framerate
+ * The internal frame rate, i.e. the number of frames per second.
+ *
+ * This is computed as the least common multiple of the frame rate
* specified by the client code, and 1000.
- * This way, we ensure that we can store both frames and
- * milliseconds without any rounding losses.
+ * This ensures that both frames and milliseconds can be stored
+ * without any rounding losses.
*/
uint _framerate;
/**
- * Factor by which the original framerate specified by the client
- * code was multipled to obtain the internal _framerate value.
+ * Factor by which the original frame rate specified by the client
+ * code has been multiplied to obtain the internal _framerate value.
*/
uint _framerateFactor;
};
-
+/** @} */
} // End of namespace Audio
#endif
diff --git a/doc/doxygen/groups.dox b/doc/doxygen/groups.dox
index 88e2b66d9b..4b037bfe41 100644
--- a/doc/doxygen/groups.dox
+++ b/doc/doxygen/groups.dox
@@ -25,4 +25,17 @@
@defgroup image Image API
@brief API of various image decoders used in engines.
+*/
+
+/**
+
+ at defgroup audio Audio API
+ at brief APIs for managing in-game audio.
+
+*/
+/**
+
+ at defgroup image Image API
+ at brief API of various image decoders used in engines.
+
*/
\ No newline at end of file
More information about the Scummvm-git-logs
mailing list