intern/audaspace/intern/AUD_IDevice.h

   1 /*
   2  * $Id$
   3  *
   4  * ***** BEGIN LGPL LICENSE BLOCK *****
   5  *
   6  * Copyright 2009 Jörg Hermann Müller
   7  *
   8  * This file is part of AudaSpace.
   9  *
  10  * AudaSpace is free software: you can redistribute it and/or modify
  11  * it under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation, either version 3 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * AudaSpace is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with AudaSpace.  If not, see <http://www.gnu.org/licenses/>.
  22  *
  23  * ***** END LGPL LICENSE BLOCK *****
  24  */
  25
  26 #ifndef AUD_IDEVICE
  27 #define AUD_IDEVICE
  28
  29 #include "AUD_Space.h"
  30 class AUD_IFactory;
  31
  32 /// Handle structure, for inherition.
  33 struct AUD_Handle
  34 {
  35 };
  36
  37 /**
  38  * This class represents an output device for sound sources.
  39  * Output devices may be several backends such as plattform independand like
  40  * SDL or OpenAL or plattform specific like DirectSound, but they may also be
  41  * files, RAM buffers or other types of streams.
  42  * \warning Thread safety must be insured so that no reader is beeing called
  43  *          twice at the same time.
  44  */
  45 class AUD_IDevice
  46 {
  47 public:
  48         /**
  49          * Destroys the device.
  50          */
  51         virtual ~AUD_IDevice() {}
  52
  53         /**
  54          * Returns the specification of the device.
  55          */
  56         virtual AUD_DeviceSpecs getSpecs() const=0;
  57
  58         /**
  59          * Plays a sound source.
  60          * \param factory The factory to create the reader for the sound source.
  61          * \param keep When keep is true the sound source will not be deleted but
  62          *             set to paused when its end has been reached.
  63          * \return Returns a handle with which the playback can be controlled.
  64          *         This is NULL if the sound couldn't be played back.
  65          * \exception AUD_Exception Thrown if there's an unexpected (from the
  66          *            device side) error during creation of the reader.
  67          */
  68         virtual AUD_Handle* play(AUD_IFactory* factory, bool keep = false)=0;
  69
  70         /**
  71          * Pauses a played back sound.
  72          * \param handle The handle returned by the play function.
  73          * \return
  74          *        - true if the sound has been paused.
  75          *        - false if the sound isn't playing back or the handle is invalid.
  76          */
  77         virtual bool pause(AUD_Handle* handle)=0;
  78
  79         /**
  80          * Resumes a paused sound.
  81          * \param handle The handle returned by the play function.
  82          * \return
  83          *        - true if the sound has been resumed.
  84          *        - false if the sound isn't paused or the handle is invalid.
  85          */
  86         virtual bool resume(AUD_Handle* handle)=0;
  87
  88         /**
  89          * Stops a played back or paused sound. The handle is definitely invalid
  90          * afterwards.
  91          * \param handle The handle returned by the play function.
  92          * \return
  93          *        - true if the sound has been stopped.
  94          *        - false if the handle is invalid.
  95          */
  96         virtual bool stop(AUD_Handle* handle)=0;
  97
  98         /**
  99          * Gets the behaviour of the device for a played back sound when the sound
 100          * doesn't return any more samples.
 101          * \param handle The handle returned by the play function.
 102          * \return
 103          *        - true if the source will be paused when it's end is reached
 104          *        - false if the handle won't kept or is invalid.
 105          */
 106         virtual bool getKeep(AUD_Handle* handle)=0;
 107
 108         /**
 109          * Sets the behaviour of the device for a played back sound when the sound
 110          * doesn't return any more samples.
 111          * \param handle The handle returned by the play function.
 112          * \param keep True when the source should be paused and not deleted.
 113          * \return
 114          *        - true if the behaviour has been changed.
 115          *        - false if the handle is invalid.
 116          */
 117         virtual bool setKeep(AUD_Handle* handle, bool keep)=0;
 118
 119         /**
 120          * Seeks in a played back sound.
 121          * \param handle The handle returned by the play function.
 122          * \param position The new position from where to play back, in seconds.
 123          * \return
 124          *        - true if the handle is valid.
 125          *        - false if the handle is invalid.
 126          * \warning Whether the seek works or not depends on the sound source.
 127          */
 128         virtual bool seek(AUD_Handle* handle, float position)=0;
 129
 130         /**
 131          * Retrieves the current playback position of a sound.
 132          * \param handle The handle returned by the play function.
 133          * \return The playback position in seconds, or 0.0 if the handle is
 134          *         invalid.
 135          */
 136         virtual float getPosition(AUD_Handle* handle)=0;
 137
 138         /**
 139          * Returns the status of a played back sound.
 140          * \param handle The handle returned by the play function.
 141          * \return
 142          *        - AUD_STATUS_INVALID if the sound has stopped or the handle is
 143          *.         invalid
 144          *        - AUD_STATUS_PLAYING if the sound is currently played back.
 145          *        - AUD_STATUS_PAUSED if the sound is currently paused.
 146          * \see AUD_Status
 147          */
 148         virtual AUD_Status getStatus(AUD_Handle* handle)=0;
 149
 150         /**
 151          * Locks the device.
 152          * Used to make sure that between lock and unlock, no buffers are read, so
 153          * that it is possible to start, resume, pause, stop or seek several
 154          * playback handles simultaneously.
 155          * \warning Make sure the locking time is as small as possible to avoid
 156          *          playback delays that result in unexpected noise and cracks.
 157          */
 158         virtual void lock()=0;
 159
 160         /**
 161          * Unlocks the previously locked device.
 162          */
 163         virtual void unlock()=0;
 164
 165         /**
 166          * Retrieves the overall device volume.
 167          * \return The overall device volume.
 168          */
 169         virtual float getVolume() const=0;
 170
 171         /**
 172          * Sets the overall device volume.
 173          * \param handle The sound handle.
 174          * \param volume The overall device volume.
 175          */
 176         virtual void setVolume(float volume)=0;
 177
 178         /**
 179          * Retrieves the volume of a playing sound.
 180          * \param handle The sound handle.
 181          * \return The volume.
 182          */
 183         virtual float getVolume(AUD_Handle* handle)=0;
 184
 185         /**
 186          * Sets the volume of a playing sound.
 187          * \param handle The sound handle.
 188          * \param volume The volume.
 189          * \return
 190          *        - true if the handle is valid.
 191          *        - false if the handle is invalid.
 192          */
 193         virtual bool setVolume(AUD_Handle* handle, float volume)=0;
 194
 195         /**
 196          * Retrieves the pitch of a playing sound.
 197          * \return The pitch.
 198          */
 199         virtual float getPitch(AUD_Handle* handle)=0;
 200
 201         /**
 202          * Sets the pitch of a playing sound.
 203          * \param handle The sound handle.
 204          * \param pitch The pitch.
 205          * \return
 206          *        - true if the handle is valid.
 207          *        - false if the handle is invalid.
 208          */
 209         virtual bool setPitch(AUD_Handle* handle, float pitch)=0;
 210
 211         /**
 212          * Retrieves the loop count of a playing sound.
 213          * A negative value indicates infinity.
 214          * \return The remaining loop count.
 215          */
 216         virtual int getLoopCount(AUD_Handle* handle)=0;
 217
 218         /**
 219          * Sets the loop count of a playing sound.
 220          * A negative value indicates infinity.
 221          * \param handle The sound handle.
 222          * \param count The new loop count.
 223          * \return
 224          *        - true if the handle is valid.
 225          *        - false if the handle is invalid.
 226          */
 227         virtual bool setLoopCount(AUD_Handle* handle, int count)=0;
 228 };
 229
 230 #endif //AUD_IDevice