From: Mikko Rasa Date: Sun, 24 Jun 2018 14:47:45 +0000 (+0300) Subject: Improve documentation of SoundDecoder X-Git-Url: http://git.tdb.fi/?a=commitdiff_plain;h=d71db75062556dc2aea073a33e0e102894b6dfa5;p=libs%2Fal.git Improve documentation of SoundDecoder --- diff --git a/source/mp3decoder.h b/source/mp3decoder.h index 201d68f..01fba63 100644 --- a/source/mp3decoder.h +++ b/source/mp3decoder.h @@ -18,6 +18,10 @@ private: }; +/** +Decoder for MPEG-2 audio files, a.k.a. MP2 and MP3 files. Normally you should +use one of the SoundDecoder::open_* functions to create a decoder. +*/ class Mp3Decoder: public SoundDecoder { private: diff --git a/source/oggdecoder.h b/source/oggdecoder.h index 3bf33b8..e194736 100644 --- a/source/oggdecoder.h +++ b/source/oggdecoder.h @@ -18,6 +18,10 @@ private: }; +/** +Decoder for Ogg Vorbis files. Normally you should use one of the +SoundDecoder::open_* functions to create a decoder. +*/ class OggDecoder: public SoundDecoder { private: diff --git a/source/sounddecoder.h b/source/sounddecoder.h index 37fddac..20b9d0f 100644 --- a/source/sounddecoder.h +++ b/source/sounddecoder.h @@ -17,8 +17,7 @@ public: /** -This class facilitates loading sound files. Currently only Ogg Vorbis is -supported. +Base class for sound decoders. */ class SoundDecoder { @@ -34,16 +33,29 @@ protected: public: virtual ~SoundDecoder(); + /** Opens a file and creates a decoder of an appropriate type for it. */ static SoundDecoder *open_file(const std::string &); + + /** Creates a decoder for an already-opened audio file. */ static SoundDecoder *open_io(IO::Seekable &); + /** Restarts decoding from the beginning of the file. */ virtual void rewind() { seek(0); } + + /** Sets decoding position expressed in PCM bytes. This may involve seeking + to the beginning and skipping until the desired position is reached.*/ virtual void seek(unsigned) = 0; + + /** Reads decoded sound data. Length is specified in bytes. */ virtual unsigned read(char *, unsigned) = 0; + bool eof() const { return eof_flag; } Format get_format() const { return format; } unsigned get_frequency() const { return freq; } + + /** Returns the total length of the sound data in bytes. Some decoders may + not be able to provide this information. */ unsigned get_size() const { return size; } };