comparison data/fileio/AudioFileReader.h @ 1809:73447d746db3

Comments and debug-related bits

      */
     virtual sv_samplerate_t getNativeRate() const { return m_sampleRate; }
 
     /**
      * Return the location of the audio data in the reader (as passed
-     * in to the FileSource constructor, for example).
+     * in to the FileSource constructor, for example). This might be a
+     * remote URL.
+     *
+     * See also getLocalFilename().
      */
-    virtual QString getLocation() const { return ""; }
+    virtual QString getLocation() const = 0;
+
+    /**
+     * Return the local file path of the audio data. This is the
+     * filesystem location most likely to contain readable audio data,
+     * but it may be in a different place or format from the
+     * originally specified location - for example, if the file has
+     * been retrieved and decoded, then it will be the (possibly
+     * temporary) decode target file.
+     *
+     * This returns a non-empty value only if there is some local
+     * filename that contains exactly the audio data being provided by
+     * this reader. In some cases this may not exist, for example when
+     * a file has been resampled or normalised directly into a memory
+     * buffer. In this case, return an empty string.
+     *
+     * See also getLocation().
+     */
+    virtual QString getLocalFilename() const = 0;
     
     /**
      * Return the title of the work in the audio file, if known.  This
      * may be implemented by subclasses that support file tagging.
      * This is not the same thing as the file name.

      * conductor, artist etc).
      */
     virtual QString getMaker() const = 0;
 
     /**
-     * Return the local file path of the audio data. This is the
-     * location most likely to contain readable audio data: it may be
-     * in a different place or format from the originally specified
-     * location, for example if the file has been retrieved and
-     * decoded. In some cases there may be no local file path, and
-     * this will return "" if there is none.
+     * Return any tag pairs picked up from the audio file. See also
+     * getTitle and getMaker, and note that a reader which does not
+     * implement getTags may still return values from those.
      */
-    virtual QString getLocalFilename() const { return ""; }
-    
     typedef std::map<QString, QString> TagMap;
     virtual TagMap getTags() const { return TagMap(); }
 
     /**
      * Return true if this file supports fast seek and random
      * access. Typically this will be true for uncompressed formats
      * and false for compressed ones.
      */
     virtual bool isQuicklySeekable() const = 0;
+
+    /**
+     * Return a percentage value indicating how far through decoding
+     * the audio file we are. This should be implemented by subclasses
+     * that will not know exactly how long the audio file is (in
+     * sample frames) until it has been completely decoded. A reader
+     * that initialises the frame count directly within its
+     * constructor should always return 100 from this.
+    */
+    virtual int getDecodeCompletion() const { return 100; }
+
+    /**
+     * Return true if decoding is still in progress and the frame
+     * count may change.
+     */
+    virtual bool isUpdating() const { return false; }
 
     /** 
      * Return interleaved samples for count frames from index start.
      * The resulting vector will contain count * getChannelCount()
      * samples (or fewer if end of file is reached).

      * each (or fewer if end of file is reached).
      */
     virtual std::vector<floatvec_t> getDeInterleavedFrames(sv_frame_t start,
                                                            sv_frame_t count) const;
 
-    // only subclasses that do not know exactly how long the audio
-    // file is until it's been completely decoded should implement this
-    virtual int getDecodeCompletion() const { return 100; } // %
-
-    virtual bool isUpdating() const { return false; }
-
 signals:
     void frameCountChanged();
     
 protected:
     sv_frame_t m_frameCount;