Make sound format support optional

[libs/al.git] / source / sounddecoder.h

diff --git a/source/sounddecoder.h b/source/sounddecoder.h
index 7a08644117317623d629b88559788036b5f16e8b..20b9d0fb7f4e3d6afa4bd2d9a3dc8806e5477c5e 100644 (file)
--- a/source/sounddecoder.h
+++ b/source/sounddecoder.h
@@ -8,9 +8,16 @@
 namespace Msp {
 namespace AL {
 
+class unsupported_sound: public std::runtime_error
+{
+public:
+       unsupported_sound(const std::string &);
+       virtual ~unsupported_sound() throw() { }
+};
+
+
 /**
-This class facilitates loading sound files.  Currently only Ogg Vorbis is
-supported.
+Base class for sound decoders.
 */
 class SoundDecoder
 {
@@ -26,15 +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 &);
 
-       virtual void rewind() = 0;
+       /** 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; }
 };