sound/mixer.h

   1 /* ScummVM - Graphic Adventure Engine
   2  *
   3  * ScummVM is the legal property of its developers, whose names
   4  * are too numerous to list here. Please refer to the COPYRIGHT
   5  * file distributed with this source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20  *
  21  * $URL$
  22  * $Id$
  23  *
  24  */
  25
  26 #ifndef SOUND_MIXER_H
  27 #define SOUND_MIXER_H
  28
  29 #include "common/scummsys.h"
  30 #include "common/mutex.h"
  31
  32
  33 class OSystem;
  34
  35
  36 namespace Audio {
  37
  38 class AudioStream;
  39 class Channel;
  40 class Mixer;
  41 class MixerImpl;
  42
  43 /**
  44  * A SoundHandle instances corresponds to a specific sound
  45  * being played via the mixer. It can be used to control that
  46  * sound (pause it, stop it, etc.).
  47  * @see The Mixer class
  48  */
  49 class SoundHandle {
  50         friend class Channel;
  51         friend class MixerImpl;
  52         uint32 _val;
  53 public:
  54         inline SoundHandle() : _val(0xFFFFFFFF) {}
  55 };
  56
  57 /**
  58  * The main audio mixer handles mixing of an arbitrary number of
  59  * input audio streams (in the form of AudioStream instances).
  60  */
  61 class Mixer {
  62 public:
  63         /**
  64          * Various flags which can be bit-ORed and then passed to
  65          * Mixer::playRaw resp. makeLinearInputStream to control their
  66          * behavior.
  67          *
  68          * Engine authors are advised not to rely on a certain value or
  69          * order of these flags (in particular, do not store them verbatim
  70          * in savestates).
  71          */
  72         enum RawFlags {
  73                 /** unsigned samples (default: signed) */
  74                 FLAG_UNSIGNED = 1 << 0,
  75
  76                 /** sound is 16 bits wide (default: 8bit) */
  77                 FLAG_16BITS = 1 << 1,
  78
  79                 /** samples are little endian (default: big endian) */
  80                 FLAG_LITTLE_ENDIAN = 1 << 2,
  81
  82                 /** sound is in stereo (default: mono) */
  83                 FLAG_STEREO = 1 << 3,
  84
  85                 /** reverse the left and right stereo channel */
  86                 FLAG_REVERSE_STEREO = 1 << 4,
  87
  88                 /** sound buffer is freed automagically at the end of playing */
  89                 FLAG_AUTOFREE = 1 << 5,
  90
  91                 /** loop the audio */
  92                 FLAG_LOOP = 1 << 6
  93         };
  94
  95         enum SoundType {
  96                 kPlainSoundType = 0,
  97
  98                 kMusicSoundType = 1,
  99                 kSFXSoundType = 2,
 100                 kSpeechSoundType = 3
 101         };
 102
 103         enum {
 104                 kMaxChannelVolume = 255,
 105                 kMaxMixerVolume = 256
 106         };
 107
 108 public:
 109         Mixer() {}
 110         virtual ~Mixer() {}
 111
 112
 113
 114         /**
 115          * Is the mixer ready and setup? This may not be the case on systems which
 116          * don't support digital sound output. In that case, the mixer proc may
 117          * never be called. That in turn can cause breakage in games which try to
 118          * sync with an audio stream. In particular, the Adlib MIDI emulation...
 119          *
 120          * @return whether the mixer is ready and setup
 121          *
 122          * @todo get rid of this?
 123          */
 124         virtual bool isReady() const = 0;
 125
 126
 127
 128         /**
 129          * Start playing the given raw sound data.
 130          * Internally, this simply creates an audio input stream wrapping the data
 131          * (using the makeLinearInputStream factory function), which is then
 132          * passed on to playInputStream.
 133          */
 134         virtual void playRaw(
 135                 SoundType type,
 136                 SoundHandle *handle,
 137                 void *sound, uint32 size, uint rate, byte flags,
 138                 int id = -1, byte volume = kMaxChannelVolume, int8 balance = 0,
 139                 uint32 loopStart = 0, uint32 loopEnd = 0) = 0;
 140
 141         /**
 142          * Start playing the given audio input stream.
 143          *
 144          * Note that the sound id assigned below is unique. At most one stream
 145          * with a given id can play at any given time. Trying to play a sound
 146          * with an id that is already in use causes the new sound to be not played.
 147          *
 148          * @param type  the type (voice/sfx/music) of the stream
 149          * @param handle        a SoundHandle which can be used to reference and control
 150          *                  the stream via suitable mixer methods
 151          * @param input the actual AudioStream to be played
 152          * @param id    a unique id assigned to this stream
 153          * @param volume        the volume with which to play the sound, ranging from 0 to 255
 154          * @param balance       the balance with which to play the sound, ranging from -128 to 127
 155          * @param autofreeStream        a flag indicating whether the stream should be
 156          *                          freed after playback finished
 157          * @param permanent     a flag indicating whether a plain stopAll call should
 158          *                  not stop this particular stream
 159          * @param reverseStereo a flag indicating whether left and right channels shall be swapped
 160          */
 161         virtual void playInputStream(
 162                 SoundType type,
 163                 SoundHandle *handle,
 164                 AudioStream *input,
 165                 int id = -1, byte volume = kMaxChannelVolume, int8 balance = 0,
 166                 bool autofreeStream = true,
 167                 bool permanent = false,
 168                 bool reverseStereo = false) = 0;
 169
 170
 171
 172         /**
 173          * Stop all currently playing sounds.
 174          */
 175         virtual void stopAll() = 0;
 176
 177         /**
 178          * Stop playing the sound with given ID.
 179          *
 180          * @param id the ID of the sound to affect
 181          */
 182         virtual void stopID(int id) = 0;
 183
 184         /**
 185          * Stop playing the sound corresponding to the given handle.
 186          *
 187          * @param handle the sound to affect
 188          */
 189         virtual void stopHandle(SoundHandle handle) = 0;
 190
 191
 192
 193         /**
 194          * Pause/unpause all sounds, including all regular and permanent
 195          * channels
 196          *
 197          * @param paused true to pause everything, false to unpause
 198          */
 199         virtual void pauseAll(bool paused) = 0;
 200
 201         /**
 202          * Pause/unpause the sound with the given ID.
 203          *
 204          * @param id the ID of the sound to affect
 205          * @param paused true to pause the sound, false to unpause it
 206          */
 207         virtual void pauseID(int id, bool paused) = 0;
 208
 209         /**
 210          * Pause/unpause the sound corresponding to the given handle.
 211          *
 212          * @param handle the sound to affect
 213          * @param paused true to pause the sound, false to unpause it
 214          */
 215         virtual void pauseHandle(SoundHandle handle, bool paused) = 0;
 216
 217
 218
 219         /**
 220          * Check if a sound with the given ID is active.
 221          *
 222          * @param id the ID of the sound to query
 223          * @return true if the sound is active
 224          */
 225         virtual bool isSoundIDActive(int id) = 0;
 226
 227         /**
 228          * Get the sound ID of handle sound
 229          *
 230          * @param handle sound to query
 231          * @return sound ID if active
 232          */
 233         virtual int getSoundID(SoundHandle handle) = 0;
 234
 235         /**
 236          * Check if a sound with the given handle is active.
 237          *
 238          * @param handle sound to query
 239          * @return true if the sound is active
 240          */
 241         virtual bool isSoundHandleActive(SoundHandle handle) = 0;
 242
 243
 244
 245         /**
 246          * Set the channel volume for the given handle.
 247          *
 248          * @param handle the sound to affect
 249          * @param volume the new channel volume (0 - kMaxChannelVolume)
 250          */
 251         virtual void setChannelVolume(SoundHandle handle, byte volume) = 0;
 252
 253         /**
 254          * Set the channel balance for the given handle.
 255          *
 256          * @param handle the sound to affect
 257          * @param balance the new channel balance:
 258          *        (-127 ... 0 ... 127) corresponds to (left ... center ... right)
 259          */
 260         virtual void setChannelBalance(SoundHandle handle, int8 balance) = 0;
 261
 262         /**
 263          * Get approximation of for how long the channel has been playing.
 264          */
 265         virtual uint32 getSoundElapsedTime(SoundHandle handle) = 0;
 266
 267         /**
 268          * Check whether any channel of the given sound type is active.
 269          * For example, this can be used to check whether any SFX sound
 270          * is currently playing, by checking for type kSFXSoundType.
 271          *
 272          * @param  type the sound type to look for
 273          * @return true if any channels of the specified type are active.
 274          */
 275         virtual bool hasActiveChannelOfType(SoundType type) = 0;
 276
 277         /**
 278          * Set the volume for the given sound type.
 279          *
 280          * @param type the sound type
 281          * @param volume the new global volume, 0 - kMaxMixerVolume
 282          */
 283         virtual void setVolumeForSoundType(SoundType type, int volume) = 0;
 284
 285         /**
 286          * Query the global volume.
 287          *
 288          * @param type the sound type
 289          * @return the global music volume, 0 - kMaxMixerVolume
 290          */
 291         virtual int getVolumeForSoundType(SoundType type) const = 0;
 292
 293         /**
 294          * Query the system's audio output sample rate. This returns
 295          * the same value as OSystem::getOutputSampleRate().
 296          *
 297          * @return the output sample rate in Hz
 298          */
 299         virtual uint getOutputRate() const = 0;
 300 };
 301
 302
 303 } // End of namespace Audio
 304
 305 #endif