path: root/src/audiere.h

/**
 * @file
 *
 * Audiere Sound System
 * Version 1.9.4
 * (c) 2001-2003 Chad Austin
 *
 * This API uses principles explained at
 * http://aegisknight.org/cppinterface.html
 *
 * This code licensed under the terms of the LGPL.  See doc/license.txt.
 *
 *
 * Note: When compiling this header in gcc, you may want to use the
 * -Wno-non-virtual-dtor flag to get rid of those annoying "class has
 * virtual functions but no virtual destructor" warnings.
 *
 * This file is structured as follows:
 * - includes, macro definitions, other general setup
 * - interface definitions
 * - DLL-safe entry points (not for general use)
 * - inline functions that use those entry points
 */

#ifndef AUDIERE_H
#define AUDIERE_H


#include <vector>
#include <string>
#include <cstring>

#ifdef _MSC_VER
#pragma warning(disable : 4786)
#endif


#ifndef __cplusplus
  #error Audiere requires C++
#endif


// DLLs in Windows should use the standard (Pascal) calling convention
#ifndef ADR_CALL
  #if defined(WIN32) || defined(_WIN32)
    #define ADR_CALL __stdcall
  #else
    #define ADR_CALL
  #endif
#endif

// Export functions from the DLL
#ifndef ADR_DECL
#  if defined(WIN32) || defined(_WIN32)
#    ifdef AUDIERE_EXPORTS
#      define ADR_DECL __declspec(dllexport)
#    else
#      define ADR_DECL __declspec(dllimport)
#    endif
#  else
#    define ADR_DECL
#  endif
#endif



#define ADR_FUNCTION(ret) extern "C" ADR_DECL ret ADR_CALL
#define ADR_METHOD(ret) virtual ret ADR_CALL


namespace audiere {

  class RefCounted {
  protected:
    /**
     * Protected so users of refcounted classes don't use std::auto_ptr
     * or the delete operator.
     *
     * Interfaces that derive from RefCounted should define an inline,
     * empty, protected destructor as well.
     */
    ~RefCounted() { }

  public:
    /**
     * Add a reference to the internal reference count.
     */
    ADR_METHOD(void) ref() = 0;

    /**
     * Remove a reference from the internal reference count.  When this
     * reaches 0, the object is destroyed.
     */
    ADR_METHOD(void) unref() = 0;
  };


  template<typename T>
  class RefPtr {
  public:
    RefPtr(T* ptr = 0) {
      m_ptr = 0;
      *this = ptr;
    }

    RefPtr(const RefPtr<T>& ptr) {
      m_ptr = 0;
      *this = ptr;
    }

    ~RefPtr() {
      if (m_ptr) {
        m_ptr->unref();
        m_ptr = 0;
      }
    }
 
    RefPtr<T>& operator=(T* ptr) {
      if (ptr != m_ptr) {
        if (m_ptr) {
          m_ptr->unref();
        }
        m_ptr = ptr;
        if (m_ptr) {
          m_ptr->ref();
        }
      }
      return *this;
    }

    RefPtr<T>& operator=(const RefPtr<T>& ptr) {
      *this = ptr.m_ptr;
      return *this;
    }

    T* operator->() const {
      return m_ptr;
    }

    T& operator*() const {
      return *m_ptr;
    }

    operator bool() const {
      return (m_ptr != 0);
    }

    T* get() const {
      return m_ptr;
    }

  private:
    T* m_ptr;
  };


  template<typename T, typename U>
  bool operator==(const RefPtr<T>& a, const RefPtr<U>& b) {
      return (a.get() == b.get());
  }

  template<typename T>
  bool operator==(const RefPtr<T>& a, const T* b) {
      return (a.get() == b);
  }

  template<typename T>
  bool operator==(const T* a, const RefPtr<T>& b) {
      return (a == b.get());
  }
  

  template<typename T, typename U>
  bool operator!=(const RefPtr<T>& a, const RefPtr<U>& b) {
      return (a.get() != b.get());
  }

  template<typename T>
  bool operator!=(const RefPtr<T>& a, const T* b) {
      return (a.get() != b);
  }

  template<typename T>
  bool operator!=(const T* a, const RefPtr<T>& b) {
      return (a != b.get());
  }


  /**
   * Represents a random-access file, usually stored on a disk.  Files
   * are always binary: that is, they do no end-of-line
   * transformations.  File objects are roughly analogous to ANSI C
   * FILE* objects.
   *
   * This interface is not synchronized.
   */
  class File : public RefCounted {
  protected:
    ~File() { }

  public:
    /**
     * The different ways you can seek within a file.
     */
    enum SeekMode {
      BEGIN,
      CURRENT,
      END,
    };

    /**
     * Read size bytes from the file, storing them in buffer.
     *
     * @param buffer  buffer to read into
     * @param size    number of bytes to read
     *
     * @return  number of bytes successfully read
     */
    ADR_METHOD(int) read(void* buffer, int size) = 0;

    /**
     * Jump to a new position in the file, using the specified seek
     * mode.  Remember: if mode is END, the position must be negative,
     * to seek backwards from the end of the file into its contents.
     * If the seek fails, the current position is undefined.
     *
     * @param position  position relative to the mode
     * @param mode      where to seek from in the file
     *
     * @return  true on success, false otherwise
     */
    ADR_METHOD(bool) seek(int position, SeekMode mode) = 0;

    /**
     * Get current position within the file.
     *
     * @return  current position
     */
    ADR_METHOD(int) tell() = 0;
  };
  typedef RefPtr<File> FilePtr;


  /// Storage formats for sample data.
  enum SampleFormat {
    SF_U8,  ///< unsigned 8-bit integer [0,255]
    SF_S16, ///< signed 16-bit integer in host endianness [-32768,32767]
  };


  /// Supported audio file formats.
  enum FileFormat {
    FF_AUTODETECT,
    FF_WAV,
    FF_OGG,
    FF_FLAC,
    FF_MP3,
    FF_MOD,
    FF_AIFF,
    FF_SPEEX,
  };


  /**
   * Source of raw PCM samples.  Sample sources have an intrinsic format
   * (@see SampleFormat), sample rate, and number of channels.  They can
   * be read from or reset.
   *
   * Some sample sources are seekable.  Seekable sources have two additional
   * properties: length and position.  Length is read-only.
   *
   * This interface is not synchronized.
   */
  class SampleSource : public RefCounted {
  protected:
    ~SampleSource() { }

  public:
    /**
     * Retrieve the number of channels, sample rate, and sample format of
     * the sample source.
     */
    ADR_METHOD(void) getFormat(
      int& channel_count,
      int& sample_rate,
      SampleFormat& sample_format) = 0;

    /**
     * Read frame_count samples into buffer.  buffer must be at least
     * |frame_count * GetSampleSize(format) * channel_count| bytes long.
     *
     * @param frame_count  number of frames to read
     * @param buffer       buffer to store samples in
     *
     * @return  number of frames actually read
     */
    ADR_METHOD(int) read(int frame_count, void* buffer) = 0;

    /**
     * Reset the sample source.  This has the same effect as setPosition(0)
     * on a seekable source.  On an unseekable source, it resets all internal
     * state to the way it was when the source was first created.
     */
    ADR_METHOD(void) reset() = 0;

    /**
     * @return  true if the stream is seekable, false otherwise
     */
    ADR_METHOD(bool) isSeekable() = 0;

    /**
     * @return  number of frames in the stream, or 0 if the stream is not
     *          seekable
     */
    ADR_METHOD(int) getLength() = 0;
    
    /**
     * Sets the current position within the sample source.  If the stream
     * is not seekable, this method does nothing.
     *
     * @param position  current position in frames
     */
    ADR_METHOD(void) setPosition(int position) = 0;

    /**
     * Returns the current position within the sample source.
     *
     * @return  current position in frames
     */
    ADR_METHOD(int) getPosition() = 0;

    /**
     * @return  true if the sample source is set to repeat
     */
    ADR_METHOD(bool) getRepeat() = 0;

    /**
     * Sets whether the sample source should repeat or not.  Note that not
     * all sample sources repeat by starting again at the beginning of the
     * sound.  For example MOD files can contain embedded loop points.
     *
     * @param repeat  true if the source should repeat, false otherwise
     */
    ADR_METHOD(void) setRepeat(bool repeat) = 0;

    /// Returns number of metadata tags present in this sample source.
    ADR_METHOD(int) getTagCount() = 0;

    /**
     * Returns the key of the i'th tag in the source.  If the tag is
     * "author=me", the key is "author".
     */
    virtual const char* ADR_CALL getTagKey(int i) = 0;

    /**
     * Returns the value of the i'th tag in the source.  If the tag is
     * "author=me", the value is "me".
     */
    virtual const char* ADR_CALL getTagValue(int i) = 0;

    /**
     * Returns the type of the i'th tag in the source.  The type is where
     * the tag comes from, i.e. "ID3v1", "ID3v2", or "vorbis".
     */
    virtual const char* ADR_CALL getTagType(int i) = 0;

    /**
     * Returns the order of the source. This is only for formats
     * supported by dumb.
     */
    ADR_METHOD(int) getOrder() { return 0; }

    /**
     * Sets the order of the source. This is only for formats
     * supported by dumb.
     */
    ADR_METHOD(bool) setOrder(int order) { return false; }

    /**
     * Returns the row of the source. This is only for formats
     * supported by dumb.
     */
    ADR_METHOD(int) getRow() { return 0; }

    /**
     * Returns the volume of specified channel of the source. This is
     * only for formats supported by dumb.
     */
    ADR_METHOD(float) getChannelVolume(int channel = 0) { return 1.0f; }

    /**
     * Sets the volume of specified of the source. This is only for
     * formats supported by dumb.
     */
    ADR_METHOD(bool) setChannelVolume(int channel, float volume) { return false; }
  };
  typedef RefPtr<SampleSource> SampleSourcePtr;


  /**
   * LoopPointSource is a wrapper around another SampleSource, providing
   * custom loop behavior.  LoopPointSource maintains a set of links
   * within the sample stream and whenever the location of one of the links
   * (i.e. a loop point) is reached, the stream jumps to that link's target.
   * Each loop point maintains a count.  Every time a loop point comes into
   * effect, the count is decremented.  Once it reaches zero, that loop point
   * is temporarily disabled.  If a count is not a positive value, it
   * cannot be disabled.  Calling reset() resets all counts to their initial
   * values.
   *
   * Loop points only take effect when repeating has been enabled via the
   * setRepeat() method.
   *
   * Loop points are stored in sorted order by their location.  Each one
   * has an index based on its location within the list.  A loop point's
   * index will change if another is added before it.
   *
   * There is always one implicit loop point after the last sample that
   * points back to the first.  That way, this class's default looping
   * behavior is the same as a standard SampleSource.  This loop point
   * does not show up in the list.
   */
  class LoopPointSource : public SampleSource {
  protected:
    ~LoopPointSource() { }

  public:
    /**
     * Adds a loop point to the stream.  If a loop point at 'location'
     * already exists, the new one replaces it.  Location and target are
     * clamped to the actual length of the stream.
     *
     * @param location   frame where loop occurs
     * @param target     frame to jump to after loop point is hit
     * @param loopCount  number of times to execute this jump.
     */
    ADR_METHOD(void) addLoopPoint(
      int location, int target, int loopCount) = 0;

    /**
     * Removes the loop point at index 'index' from the stream.
     *
     * @param index  index of the loop point to remove
     */
    ADR_METHOD(void) removeLoopPoint(int index) = 0;

    /**
     * Returns the number of loop points in this stream.
     */
    ADR_METHOD(int) getLoopPointCount() = 0;

    /**
     * Retrieves information about a specific loop point.
     *
     * @param index      index of the loop point
     * @param location   frame where loop occurs
     * @param target     loop point's target frame
     * @param loopCount  number of times to loop from this particular point
     *
     * @return  true if the index is valid and information is returned
     */
    ADR_METHOD(bool) getLoopPoint(
      int index, int& location, int& target, int& loopCount) = 0;
  };
  typedef RefPtr<LoopPointSource> LoopPointSourcePtr;


  /**
   * A connection to an audio device.  Multiple output streams are
   * mixed by the audio device to produce the final waveform that the
   * user hears.
   *
   * Each output stream can be independently played and stopped.  They
   * also each have a volume from 0.0 (silence) to 1.0 (maximum volume).
   */
  class OutputStream : public RefCounted {
  protected:
    ~OutputStream() { }

  public:
    /**
     * Start playback of the output stream.  If the stream is already
     * playing, this does nothing.
     */
    ADR_METHOD(void) play() = 0;

    /**
     * Stop playback of the output stream.  If the stream is already
     * stopped, this does nothing.
     */
    ADR_METHOD(void) stop() = 0;

    /**
     * @return  true if the output stream is playing, false otherwise
     */
    ADR_METHOD(bool) isPlaying() = 0;

    /**
     * Reset the sample source or buffer to the beginning. On seekable
     * streams, this operation is equivalent to setPosition(0).
     *
     * On some output streams, this operation can be moderately slow, as up to
     * several seconds of PCM buffer must be refilled.
     */
    ADR_METHOD(void) reset() = 0;

    /**
     * Set whether the output stream should repeat.
     *
     * @param repeat  true if the stream should repeat, false otherwise
     */
    ADR_METHOD(void) setRepeat(bool repeat) = 0;

    /**
     * @return  true if the stream is repeating
     */
    ADR_METHOD(bool) getRepeat() = 0;

    /**
     * Sets the stream's volume.
     *
     * @param  volume  0.0 = silence, 1.0 = maximum volume (default)
     */
    ADR_METHOD(void) setVolume(float volume) = 0;

    /**
     * Gets the current volume.
     *
     * @return  current volume of the output stream
     */
    ADR_METHOD(float) getVolume() = 0;

    /**
     * Set current pan.
     *
     * @param pan  -1.0 = left, 0.0 = center (default), 1.0 = right
     */
    ADR_METHOD(void) setPan(float pan) = 0;

    /**
     * Get current pan.
     */
    ADR_METHOD(float) getPan() = 0;

    /**
     * Set current pitch shift.
     *
     * @param shift  can range from 0.5 to 2.0.  default is 1.0.
     */
    ADR_METHOD(void) setPitchShift(float shift) = 0;

    /**
     * Get current pitch shift.  Defaults to 1.0.
     */
    ADR_METHOD(float) getPitchShift() = 0;

    /**
     * @return  true if the stream is seekable, false otherwise
     */
    ADR_METHOD(bool) isSeekable() = 0;

    /**
     * @return  number of frames in the stream, or 0 if the stream is not
     *          seekable
     */
    ADR_METHOD(int) getLength() = 0;
    
    /**
     * Sets the current position within the sample source.  If the stream
     * is not seekable, this method does nothing.
     *
     * @param position  current position in frames
     */
    ADR_METHOD(void) setPosition(int position) = 0;

    /**
     * Returns the current position within the sample source.
     *
     * @return  current position in frames
     */
    ADR_METHOD(int) getPosition() = 0;
  };
  typedef RefPtr<OutputStream> OutputStreamPtr;


  /// An integral code representing a specific type of event.
  enum EventType {
    ET_STOP, ///< See StopEvent and StopCallback
  };


  /// Base interface for event-specific data passed to callbacks.
  class Event : public RefCounted {
  protected:
    ~Event() { }

  public:
    /// Returns the EventType code for this event.
    ADR_METHOD(EventType) getType() = 0;
  };
  typedef RefPtr<Event> EventPtr;


  /**
   * An event object that gets passed to implementations of StopCallback
   * when a stream has stopped playing.
   */
  class StopEvent : public Event {
  protected:
    ~StopEvent() { }

  public:
    EventType ADR_CALL getType() { return ET_STOP; }

    /// A code representing the reason the stream stopped playback.
    enum Reason {
      STOP_CALLED,  ///< stop() was called from an external source.
      STREAM_ENDED, ///< The stream reached its end.
    };

    /**
     * @return Pointer to the OutputStream that stopped playback.
     */
    ADR_METHOD(OutputStream*) getOutputStream() = 0;

    /**
     * @return Reason for the stop event.
     */
    ADR_METHOD(Reason) getReason() = 0;
  };
  typedef RefPtr<StopEvent> StopEventPtr;


  /**
   * Base interface for all callbacks.  See specific callback implementations
   * for descriptions.
   */  
  class Callback : public RefCounted {
  protected:
    ~Callback() { }

  public:
    /**
     * Returns the event type that this callback knows how to handle.
     */
    ADR_METHOD(EventType) getType() = 0;

    /**
     * Actually executes the callback with event-specific data.  This is
     * only called if event->getType() == this->getType().
     */
    ADR_METHOD(void) call(Event* event) = 0;
  };
  typedef RefPtr<Callback> CallbackPtr;

  
  /**
   * To listen for stream stopped events on a device, implement this interface
   * and call registerStopCallback() on the device, passing your
   * implementation.  streamStopped() will be called whenever a stream on that
   * device stops playback.
   *
   * WARNING: StopCallback is called from another thread.  Make sure your
   * callback is thread-safe.
   */
  class StopCallback : public Callback {
  protected:
    ~StopCallback() { }

  public:
    EventType ADR_CALL getType() { return ET_STOP; }
    void ADR_CALL call(Event* event) {
      streamStopped(static_cast<StopEvent*>(event));
    }

    /**
     * Called when a stream has stopped.
     *
     * @param event  Information pertaining to the event.
     */
    ADR_METHOD(void) streamStopped(StopEvent* event) = 0;
  };
  typedef RefPtr<StopCallback> StopCallbackPtr;


  /**
   * AudioDevice represents a device on the system which is capable
   * of opening and mixing multiple output streams.  In Windows,
   * DirectSound is such a device.
   *
   * This interface is synchronized.  update() and openStream() may
   * be called on different threads.
   */
  class AudioDevice : public RefCounted {
  protected:
    ~AudioDevice() { }

  public:
    /**
     * Tell the device to do any internal state updates.  Some devices
     * update on an internal thread.  If that is the case, this method
     * does nothing.
     */
    ADR_METHOD(void) update() = 0;

    /**
     * Open an output stream with a given sample source.  If the sample
     * source ever runs out of data, the output stream automatically stops
     * itself.
     *
     * The output stream takes ownership of the sample source, even if
     * opening the output stream fails (in which case the source is
     * immediately deleted).
     *
     * @param  source  the source used to feed the output stream with samples
     *
     * @return  new output stream if successful, 0 if failure
     */
    ADR_METHOD(OutputStream*) openStream(SampleSource* source) = 0;

    /**
     * Open a single buffer with the specified PCM data.  This is sometimes
     * more efficient than streaming and works on a larger variety of audio
     * devices.  In some implementations, this may download the audio data
     * to the sound card's memory itself.
     *
     * @param samples  Buffer containing sample data.  openBuffer() does
     *                 not take ownership of the memory.  The application
     *                 is responsible for freeing it.  There must be at
     *                 least |frame_count * channel_count *
     *                 GetSampleSize(sample_format)| bytes in the buffer.
     *
     * @param frame_count  Number of frames in the buffer.
     *
     * @param channel_count  Number of audio channels.  1 = mono, 2 = stereo.
     *
     * @param sample_rate  Number of samples per second.
     *
     * @param sample_format  Format of samples in buffer.
     *
     * @return  new output stream if successful, 0 if failure
     */
    ADR_METHOD(OutputStream*) openBuffer(
      void* samples,
      int frame_count,
      int channel_count,
      int sample_rate,
      SampleFormat sample_format) = 0;

    /**
     * Gets the name of the audio device.  For example "directsound" or "oss".
     *
     * @return name of audio device
     */
    ADR_METHOD(const char*) getName() = 0;

    /**
     * Registers 'callback' to receive events.  Callbacks can be
     * registered multiple times.
     */
    ADR_METHOD(void) registerCallback(Callback* callback) = 0;
    
    /**
     * Unregisters 'callback' once.  If it is registered multiple times,
     * each unregisterStopCallback call unregisters one of the instances.
     */
    ADR_METHOD(void) unregisterCallback(Callback* callback) = 0;

    /// Clears all of the callbacks from the device.
    ADR_METHOD(void) clearCallbacks() = 0;
  };
  typedef RefPtr<AudioDevice> AudioDevicePtr;


  /**
   * A readonly sample container which can open sample streams as iterators
   * through the buffer.  This is commonly used in cases where a very large
   * sound effect is loaded once into memory and then streamed several times
   * to the audio device.  This is more efficient memory-wise than loading
   * the effect multiple times.
   *
   * @see CreateSampleBuffer
   */
  class SampleBuffer : public RefCounted {
  protected:
    ~SampleBuffer() { }

  public:

    /**
     * Return the format of the sample data in the sample buffer.
     * @see SampleSource::getFormat
     */
    ADR_METHOD(void) getFormat(
      int& channel_count,
      int& sample_rate,
      SampleFormat& sample_format) = 0;

    /**
     * Get the length of the sample buffer in frames.
     */
    ADR_METHOD(int) getLength() = 0;

    /**
     * Get a readonly pointer to the samples contained within the buffer.  The
     * buffer is |channel_count * frame_count * GetSampleSize(sample_format)|
     * bytes long.
     */
    virtual const void* ADR_CALL getSamples() = 0;

    /**
     * Open a seekable sample source using the samples contained in the
     * buffer.
     */
    ADR_METHOD(SampleSource*) openStream() = 0;
  };
  typedef RefPtr<SampleBuffer> SampleBufferPtr;


  /**
   * Defines the type of SoundEffect objects.  @see SoundEffect
   */
  enum SoundEffectType {
    SINGLE,
    MULTIPLE,
  };


  /**
   * SoundEffect is a convenience class which provides a simple
   * mechanism for basic sound playback.  There are two types of sound
   * effects: SINGLE and MULTIPLE.  SINGLE sound effects only allow
   * the sound to be played once at a time.  MULTIPLE sound effects
   * always open a new stream to the audio device for each time it is
   * played (cleaning up or reusing old streams if possible).
   */
  class SoundEffect : public RefCounted {
  protected:
    ~SoundEffect() { }

  public:
    /**
     * Trigger playback of the sound.  If the SoundEffect is of type
     * SINGLE, this plays the sound if it isn't playing yet, and
     * starts it again if it is.  If the SoundEffect is of type
     * MULTIPLE, play() simply starts playing the sound again.
     */
    ADR_METHOD(void) play() = 0;

    /**
     * If the sound is of type SINGLE, stop the sound.  If it is of
     * type MULTIPLE, stop all playing instances of the sound.
     */
    ADR_METHOD(void) stop() = 0;

    /**
     * Sets the sound's volume.
     *
     * @param  volume  0.0 = silence, 1.0 = maximum volume (default)
     */
    ADR_METHOD(void) setVolume(float volume) = 0;

    /**
     * Gets the current volume.
     *
     * @return  current volume of the output stream
     */
    ADR_METHOD(float) getVolume() = 0;

    /**
     * Set current pan.
     *
     * @param pan  -1.0 = left, 0.0 = center (default), 1.0 = right
     */
    ADR_METHOD(void) setPan(float pan) = 0;

    /**
     * Get current pan.
     */
    ADR_METHOD(float) getPan() = 0;

    /**
     * Set current pitch shift.
     *
     * @param shift  can range from 0.5 to 2.0.  default is 1.0.
     */
    ADR_METHOD(void) setPitchShift(float shift) = 0;

    /**
     * Get current pitch shift.  Defaults to 1.0.
     */
    ADR_METHOD(float) getPitchShift() = 0;
  };
  typedef RefPtr<SoundEffect> SoundEffectPtr;


  /**
   * Represents a device capable of playing CD audio. Internally, this
   * uses the MCI subsystem in windows and libcdaudio on other platforms.
   * MCI subsystem: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/multimed/htm/_win32_multimedia_command_strings.asp
   * libcdaudio: http://cdcd.undergrid.net/libcdaudio/
   */
  class CDDevice : public RefCounted {
  protected:
    virtual ~CDDevice() { }

  public:
    /**
     * Returns the name of this CD Device, often just the device name
     * it was created with.
     */
    virtual const char* ADR_CALL getName() = 0;

    /**
     * Returns the number of audio tracks on the disc.
     */
    ADR_METHOD(int) getTrackCount() = 0;

    /**
     * Starts playback of the given track. If another track was
     * already playing, the previous track is stopped.  IMPORTANT: Tracks are
     * indexed from 0 to getTrackCount() - 1.
     */
    ADR_METHOD(void) play(int track) = 0;

    /**
     * Stops the playback, if the playback was already stopped, this
     * does nothing.
     */
    ADR_METHOD(void) stop() = 0;
    
    /**
     * pauses playback of the track that is currently playing (if any)
     * This does nothing if no track is playing
     */
    ADR_METHOD(void) pause() = 0;

    /**
     * Resumes playback of the track that is currently paused (if any).
     * This does nothing if no track is paused.
     */
    ADR_METHOD(void) resume() = 0;

    /**
     * Returns true if the CD is currently playing a sound, this could
     * be through us, or through some other program.
     */
    ADR_METHOD(bool) isPlaying() = 0;

    /**
     * Returns true if the drive contains a cd. This might be slow
     * on some systems, use with care.
     */
    ADR_METHOD(bool) containsCD() = 0;

    /// Returns true if the door is open.
    ADR_METHOD(bool) isDoorOpen() = 0;

    /// Opens this device's door.
    ADR_METHOD(void) openDoor() = 0;

    /// Closes this device's door.
    ADR_METHOD(void) closeDoor() = 0;
  };
  typedef RefPtr<CDDevice> CDDevicePtr;


  /**
   * An opened MIDI song that can be played, stopped, and seeked within.
   * Uses MCI under Windows and is not supported in other platforms.
   */
  class MIDIStream : public RefCounted {
  protected:
    virtual ~MIDIStream() { }

  public:
    /**
     * Begins playback of the song and does nothing if the song is already
     * playing.
     */
    ADR_METHOD(void) play() = 0;

    /// Stops playback of the song and seeks to the beginning.
    ADR_METHOD(void) stop() = 0;

    /**
     * Stops playback of the song and does not change its current position.
     * A subsequent play() will resume the song where it left off.
     */
    ADR_METHOD(void) pause() = 0;

    /// Returns true if the song is currently playing, false otherwise.
    ADR_METHOD(bool) isPlaying() = 0;

    /// Returns the length of the song in milliseconds.
    ADR_METHOD(int) getLength() = 0;

    /// Returns the current position of the song in milliseconds.
    ADR_METHOD(int) getPosition() = 0;

    /// Sets the current position of the song.
    ADR_METHOD(void) setPosition(int position) = 0;

    /// Returns true if this song is set to repeat.
    ADR_METHOD(bool) getRepeat() = 0;

    /// Sets whether the song should repeat on completion.  Defaults to false.
    ADR_METHOD(void) setRepeat(bool repeat) = 0;
  };
  typedef RefPtr<MIDIStream> MIDIStreamPtr;


  /**
   * A MIDIDevice must be instantiated in order to open MIDIStreams.
   */
  class MIDIDevice : public RefCounted {
  protected:
    virtual ~MIDIDevice() { }

  public:
    /**
     * Returns the name of the device.
     */
    ADR_METHOD(const char*) getName() = 0;

    /**
     * openStream() creates and returns a new MIDIStream object from the
     * file with the specified name, which then can be queried and played.
     * This method returns NULL if the stream cannot be opened.
     *
     * Note: MCI subsystem limitations do not allow loading MIDIStream
     * objects from an audiere File implementation.  This may be addressed
     * in future versions of this API.
     */
    ADR_METHOD(MIDIStream*) openStream(const char* filename) = 0;
  };
  typedef RefPtr<MIDIDevice> MIDIDevicePtr;


  /// PRIVATE API - for internal use only
  namespace hidden {

    // these are extern "C" so we don't mangle the names

    ADR_FUNCTION(const char*) AdrGetVersion();

    ADR_FUNCTION(long) AdrAtomicIncrement(volatile long& var);
    ADR_FUNCTION(long) AdrAtomicDecrement(volatile long& var);

    /**
     * Returns a formatted string that lists the file formats that Audiere
     * supports.  This function is DLL-safe.
     *
     * It is formatted in the following way:
     *
     * description1:ext1,ext2,ext3;description2:ext1,ext2,ext3
     */
    ADR_FUNCTION(const char*) AdrGetSupportedFileFormats();

    /**
     * Returns a formatted string that lists the audio devices Audiere
     * supports.  This function is DLL-safe.
     *
     * It is formatted in the following way:
     *
     * name1:description1;name2:description2;...
     */
    ADR_FUNCTION(const char*) AdrGetSupportedAudioDevices();

    ADR_FUNCTION(int) AdrGetSampleSize(SampleFormat format);

    ADR_FUNCTION(AudioDevice*) AdrOpenDevice(
      const char* name,
      const char* parameters);

    ADR_FUNCTION(SampleSource*) AdrOpenSampleSource(
      const char* filename,
      FileFormat file_format);
    ADR_FUNCTION(SampleSource*) AdrOpenSampleSourceFromFile(
      File* file,
      FileFormat file_format);
    ADR_FUNCTION(SampleSource*) AdrCreateTone(double frequency);
    ADR_FUNCTION(SampleSource*) AdrCreateSquareWave(double frequency);
    ADR_FUNCTION(SampleSource*) AdrCreateWhiteNoise();
    ADR_FUNCTION(SampleSource*) AdrCreatePinkNoise();

    ADR_FUNCTION(LoopPointSource*) AdrCreateLoopPointSource(
      SampleSource* source);

    ADR_FUNCTION(OutputStream*) AdrOpenSound(
      AudioDevice* device,
      SampleSource* source,
      bool streaming);

    ADR_FUNCTION(SampleBuffer*) AdrCreateSampleBuffer(
      void* samples,
      int frame_count,
      int channel_count,
      int sample_rate,
      SampleFormat sample_format);
    ADR_FUNCTION(SampleBuffer*) AdrCreateSampleBufferFromSource(
      SampleSource* source);

    ADR_FUNCTION(SoundEffect*) AdrOpenSoundEffect(
      AudioDevice* device,
      SampleSource* source,
      SoundEffectType type);

    ADR_FUNCTION(File*) AdrOpenFile(
      const char* name,
      bool writeable);

    ADR_FUNCTION(File*) AdrCreateMemoryFile(
      const void* buffer,
      int size);

    ADR_FUNCTION(const char*) AdrEnumerateCDDevices();

    ADR_FUNCTION(CDDevice*) AdrOpenCDDevice(
      const char* name);  // Parameters?

    ADR_FUNCTION(MIDIDevice*) AdrOpenMIDIDevice(
      const char* name);  // Parameters?
  }




  /*-------- PUBLIC API FUNCTIONS --------*/


  /**
   * Returns the Audiere version string.
   *
   * @return  Audiere version information
   */
  inline const char* GetVersion() {
    return hidden::AdrGetVersion();
  }


  /**
   * Atomically increments a counter.  Returns incremented value.
   */
  inline long AtomicIncrement(volatile long& var) {
    return hidden::AdrAtomicIncrement(var);
  }

  /**
   * Atomically decrements a counter.  Returns decremented value.
   */
  inline long AtomicDecrement(volatile long& var) {
    return hidden::AdrAtomicDecrement(var);
  }

  inline void SplitString(
    std::vector<std::string>& out,
    const char* in,
    char delim)
  {
    out.clear();
    while (*in) {
      const char* next = strchr(in, delim);
      if (next) {
        out.push_back(std::string(in, next));
      } else {
        out.push_back(in);
      }

      in = (next ? next + 1 : "");
    }
  }


  /// Describes a file format that Audiere supports.
  struct FileFormatDesc {
    /// Short description of format, such as "MP3 Files" or "Mod Files"
    std::string description;

    /// List of support extensions, such as {"mod", "it", "xm"}
    std::vector<std::string> extensions;
  };

  /// Populates a vector of FileFormatDesc structs.
  inline void GetSupportedFileFormats(std::vector<FileFormatDesc>& formats) {
    std::vector<std::string> descriptions;
    SplitString(descriptions, hidden::AdrGetSupportedFileFormats(), ';');

    formats.resize(descriptions.size());
    for (unsigned i = 0; i < descriptions.size(); ++i) {
      const char* d = descriptions[i].c_str();
      const char* colon = strchr(d, ':');
      formats[i].description.assign(d, colon);

      SplitString(formats[i].extensions, colon + 1, ',');
    }
  }


  /// Describes a supported audio device.
  struct AudioDeviceDesc {
    /// Name of device, i.e. "directsound", "winmm", or "oss"
    std::string name;

    // Textual description of device.
    std::string description;
  };

  /// Populates a vector of AudioDeviceDesc structs.
  inline void GetSupportedAudioDevices(std::vector<AudioDeviceDesc>& devices) {
    std::vector<std::string> descriptions;
    SplitString(descriptions, hidden::AdrGetSupportedAudioDevices(), ';');

    devices.resize(descriptions.size());
    for (unsigned i = 0; i < descriptions.size(); ++i) {
      std::vector<std::string> d;
      SplitString(d, descriptions[i].c_str(), ':');
      devices[i].name        = d[0];
      devices[i].description = d[1];
    }
  }


  /**
   * Get the size of a sample in a specific sample format.
   * This is commonly used to determine how many bytes a chunk of
   * PCM data will take.
   *
   * @return  Number of bytes a single sample in the specified format
   *          takes.
   */
  inline int GetSampleSize(SampleFormat format) {
    return hidden::AdrGetSampleSize(format);
  }

  /**
   * Open a new audio device. If name or parameters are not specified,
   * defaults are used. Each platform has its own set of audio devices.
   * Every platform supports the "null" audio device.
   *
   * @param  name  name of audio device that should be used
   * @param  parameters  comma delimited list of audio-device parameters;
   *                     for example, "buffer=100,rate=44100"
   *
   * @return  new audio device object if OpenDevice succeeds, and 0 in case
   *          of failure
   */
  inline AudioDevice* OpenDevice(
    const char* name = 0,
    const char* parameters = 0)
  {
    return hidden::AdrOpenDevice(name, parameters);
  }

  /**
   * Create a streaming sample source from a sound file.  This factory simply
   * opens a default file from the system filesystem and calls
   * OpenSampleSource(File*).
   *
   * @see OpenSampleSource(File*)
   */
  inline SampleSource* OpenSampleSource(
    const char* filename,
    FileFormat file_format = FF_AUTODETECT)
  {
    return hidden::AdrOpenSampleSource(filename, file_format);
  }

  /**
   * Opens a sample source from the specified file object.  If the sound file
   * cannot be opened, this factory function returns 0.
   *
   * @note  Some sound files support seeking, while some don't.
   *
   * @param file         File object from which to open the decoder
   * @param file_format  Format of the file to load.  If FF_AUTODETECT,
   *                     Audiere will try opening the file in each format.
   *
   * @return  new SampleSource if OpenSampleSource succeeds, 0 otherwise
   */
  inline SampleSource* OpenSampleSource(
    const FilePtr& file,
    FileFormat file_format = FF_AUTODETECT)
  {
    return hidden::AdrOpenSampleSourceFromFile(file.get(), file_format);
  }

  /**
   * Create a tone sample source with the specified frequency.
   *
   * @param  frequency  Frequency of the tone in Hz.
   *
   * @return  tone sample source
   */
  inline SampleSource* CreateTone(double frequency) {
    return hidden::AdrCreateTone(frequency);
  }

  /**
   * Create a square wave with the specified frequency.
   *
   * @param  frequency  Frequency of the wave in Hz.
   *
   * @return  wave sample source
   */
  inline SampleSource* CreateSquareWave(double frequency) {
    return hidden::AdrCreateSquareWave(frequency);
  }

  /**
   * Create a white noise sample source.  White noise is just random
   * data.
   *
   * @return  white noise sample source
   */
  inline SampleSource* CreateWhiteNoise() {
    return hidden::AdrCreateWhiteNoise();
  }

  /**
   * Create a pink noise sample source.  Pink noise is noise with equal
   * power distribution among octaves (logarithmic), not frequencies.
   *
   * @return  pink noise sample source
   */
  inline SampleSource* CreatePinkNoise() {
    return hidden::AdrCreatePinkNoise();
  }

  /**
   * Create a LoopPointSource from a SampleSource.  The SampleSource must
   * be seekable.  If it isn't, or the source isn't valid, this function
   * returns 0.
   */
  inline LoopPointSource* CreateLoopPointSource(
    const SampleSourcePtr& source)
  {
    return hidden::AdrCreateLoopPointSource(source.get());
  }

  /**
   * Creates a LoopPointSource from a source loaded from a file.
   */
  inline LoopPointSource* CreateLoopPointSource(
    const char* filename,
    FileFormat file_format = FF_AUTODETECT)
  {
    return CreateLoopPointSource(OpenSampleSource(filename, file_format));
  }

  /**
   * Creates a LoopPointSource from a source loaded from a file.
   */
  inline LoopPointSource* CreateLoopPointSource(
    const FilePtr& file,
    FileFormat file_format = FF_AUTODETECT)
  {
    return CreateLoopPointSource(OpenSampleSource(file, file_format));
  }

  /**
   * Try to open a sound buffer using the specified AudioDevice and
   * sample source.  If the specified sample source is seekable, it
   * loads it into memory and uses AudioDevice::openBuffer to create
   * the output stream.  If the stream is not seekable, it uses
   * AudioDevice::openStream to create the output stream.  This means
   * that certain file types must always be streamed, and therefore,
   * OpenSound will hold on to the file object.  If you must guarantee
   * that the file on disk is no longer referenced, you must create
   * your own memory file implementation and load your data into that
   * before calling OpenSound.
   *
   * @param device  AudioDevice in which to open the output stream.
   *
   * @param source  SampleSource used to generate samples for the sound
   *                object.  OpenSound takes ownership of source, even
   *                if it returns 0.  (In that case, OpenSound immediately
   *                deletes the SampleSource.)
   *
   * @param streaming  If false or unspecified, OpenSound attempts to
   *                   open the entire sound into memory.  Otherwise, it
   *                   streams the sound from the file.
   *
   * @return  new output stream if successful, 0 otherwise
   */
  inline OutputStream* OpenSound(
    const AudioDevicePtr& device,
    const SampleSourcePtr& source,
    bool streaming = false)
  {
    return hidden::AdrOpenSound(device.get(), source.get(), streaming);
  }

  /**
   * Calls OpenSound(AudioDevice*, SampleSource*) with a sample source
   * created via OpenSampleSource(const char*).
   */
  inline OutputStream* OpenSound(
    const AudioDevicePtr& device,
    const char* filename,
    bool streaming = false,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(filename, file_format);
    return OpenSound(device, source, streaming);
  }

  /**
   * Calls OpenSound(AudioDevice*, SampleSource*) with a sample source
   * created via OpenSampleSource(File* file).
   */
  inline OutputStream* OpenSound(
    const AudioDevicePtr& device,
    const FilePtr& file,
    bool streaming = false,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(file, file_format);
    return OpenSound(device, source, streaming);
  }

  /**
   * Create a SampleBuffer object using the specified samples and formats.
   *
   * @param samples  Pointer to a buffer of samples used to initialize the
   *                 new object.  If this is 0, the sample buffer contains
   *                 just silence.
   *
   * @param frame_count  Size of the sample buffer in frames.
   *
   * @param channel_count  Number of channels in each frame.
   *
   * @param sample_rate  Sample rate in Hz.
   *
   * @param sample_format  Format of each sample.  @see SampleFormat.
   *
   * @return  new SampleBuffer object
   */
  inline SampleBuffer* CreateSampleBuffer(
    void* samples,
    int frame_count,
    int channel_count,
    int sample_rate,
    SampleFormat sample_format)
  {
    return hidden::AdrCreateSampleBuffer(
      samples, frame_count,
      channel_count, sample_rate, sample_format);
  }

  /**
   * Create a SampleBuffer object from a SampleSource.
   *
   * @param source  Seekable sample source used to create the buffer.
   *                If the source is not seekable, then the function
   *                fails.
   *
   * @return  new sample buffer if success, 0 otherwise
   */
  inline SampleBuffer* CreateSampleBuffer(const SampleSourcePtr& source) {
    return hidden::AdrCreateSampleBufferFromSource(source.get());
  }

  /**
   * Open a SoundEffect object from the given sample source and sound
   * effect type.  @see SoundEffect
   *
   * @param device  AudioDevice on which the sound is played.
   *
   * @param source  The sample source used to feed the sound effect
   *                with data.
   *
   * @param type  The type of the sound effect.  If type is MULTIPLE,
   *              the source must be seekable.
   *
   * @return  new SoundEffect object if successful, 0 otherwise
   */
  inline SoundEffect* OpenSoundEffect(
    const AudioDevicePtr& device,
    const SampleSourcePtr& source,
    SoundEffectType type)
  {
    return hidden::AdrOpenSoundEffect(device.get(), source.get(), type);
  }

  /**
   * Calls OpenSoundEffect(AudioDevice*, SampleSource*,
   * SoundEffectType) with a sample source created from the filename.
   */
  inline SoundEffect* OpenSoundEffect(
    const AudioDevicePtr& device,
    const char* filename,
    SoundEffectType type,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(filename, file_format);
    return OpenSoundEffect(device, source, type);
  }

  /**
   * Calls OpenSoundEffect(AudioDevice*, SampleSource*,
   * SoundEffectType) with a sample source created from the file.
   */
  inline SoundEffect* OpenSoundEffect(
    const AudioDevicePtr& device,
    const FilePtr& file,
    SoundEffectType type,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(file, file_format);
    return OpenSoundEffect(device, source, type);
  }

  /**
   * Opens a default file implementation from the local filesystem.
   *
   * @param filename   The name of the file on the local filesystem.
   * @param writeable  Whether the writing to the file is allowed.
   */
  inline File* OpenFile(const char* filename, bool writeable) {
    return hidden::AdrOpenFile(filename, writeable);
  }

  /**
   * Creates a File implementation that reads from a buffer in memory.
   * It stores a copy of the buffer that is passed in.
   *
   * The File object does <i>not</i> take ownership of the memory buffer.
   * When the file is destroyed, it will not free the memory.
   *
   * @param buffer  Pointer to the beginning of the data.
   * @param size    Size of the buffer in bytes.
   *
   * @return  0 if size is non-zero and buffer is null. Otherwise,
   *          returns a valid File object.
   */
  inline File* CreateMemoryFile(const void* buffer, int size) {
    return hidden::AdrCreateMemoryFile(buffer, size);
  }

  /**
   * Generates a list of available CD device names.
   *
   * @param devices A vector of strings to be filled.
   */
  inline void EnumerateCDDevices(std::vector<std::string>& devices) {
    const char* d = hidden::AdrEnumerateCDDevices();
    while (d && *d) {
      devices.push_back(d);
      d += strlen(d) + 1;
    }
  }

  /**
   * Opens the specified CD playback device.
   * 
   * @param device  The filesystem device to be played.
   *                e.g. Linux: "/dev/cdrom", Windows: "D:"
   *
   * @return  0 if opening device failed, valid CDDrive object otherwise.
   */
  inline CDDevice* OpenCDDevice(const char* device) {
    return hidden::AdrOpenCDDevice(device);
  }

  /**
   * Opens the specified MIDI synthesizer device.
   *
   * @param device  The name of the device.  Unused for now.
   *
   * @return  0 if opening device failed, valid MIDIDevice object otherwise.
   */
  inline MIDIDevice* OpenMIDIDevice(const char* device) {
    return hidden::AdrOpenMIDIDevice(device);
  }


  /**
   * A basic implementation of the RefCounted interface.  Derive
   * your implementations from RefImplementation<YourInterface>.
   */
  template<class Interface>
  class RefImplementation : public Interface {
  protected:
    RefImplementation() {
      m_ref_count = 0;
    }

    /**
     * So the implementation can put its destruction logic in the destructor,
     * as natural C++ code does.
     */
    virtual ~RefImplementation() { }

  public:
    void ADR_CALL ref() {
      AtomicIncrement(m_ref_count);
    }

    void ADR_CALL unref() {
      if (AtomicDecrement(m_ref_count) == 0) {
        delete this;
      }
    }

  private:
    volatile long m_ref_count;
  };

}


#endif