mirror of
https://github.com/libretro/scummvm.git
synced 2025-01-09 19:32:11 +00:00
1bd7028c31
This is so that individual audio players can share the same mutex as the mixer. When they have their own, it's apparently quite easy to accidentally introduce deadlocks. Particularly when the audio player is shut down.
309 lines
8.3 KiB
C++
309 lines
8.3 KiB
C++
/* ScummVM - Graphic Adventure Engine
|
|
*
|
|
* ScummVM is the legal property of its developers, whose names
|
|
* are too numerous to list here. Please refer to the COPYRIGHT
|
|
* file distributed with this source distribution.
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* as published by the Free Software Foundation; either version 2
|
|
* of the License, or (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, write to the Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
*
|
|
*/
|
|
|
|
#ifndef AUDIO_MIXER_H
|
|
#define AUDIO_MIXER_H
|
|
|
|
#include "common/mutex.h"
|
|
#include "common/types.h"
|
|
#include "common/noncopyable.h"
|
|
|
|
namespace Audio {
|
|
|
|
class AudioStream;
|
|
class Channel;
|
|
class Timestamp;
|
|
|
|
/**
|
|
* @defgroup audio_mixer Mixer
|
|
* @ingroup audio
|
|
*
|
|
* @brief Mixer class used for playing audio streams.
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* A SoundHandle instance corresponds to a specific sound
|
|
* being played using the mixer. It can be used to control that
|
|
* sound (pause it, stop it, etc.).
|
|
* @see Mixer
|
|
*/
|
|
class SoundHandle {
|
|
friend class Channel;
|
|
friend class MixerImpl;
|
|
uint32 _val;
|
|
public:
|
|
inline SoundHandle() : _val(0xFFFFFFFF) {}
|
|
};
|
|
|
|
/**
|
|
* The main audio mixer that handles mixing of an arbitrary number of
|
|
* audio streams (in the form of AudioStream instances).
|
|
*/
|
|
class Mixer : Common::NonCopyable {
|
|
public:
|
|
/** Sound types. */
|
|
enum SoundType {
|
|
kPlainSoundType = 0, /*!< Plain sound. */
|
|
|
|
kMusicSoundType = 1, /*!< Music. */
|
|
kSFXSoundType = 2, /*!< Sound effects. */
|
|
kSpeechSoundType = 3 /*!< Speech. */
|
|
};
|
|
/** Max volumes. */
|
|
enum {
|
|
kMaxChannelVolume = 255, /*!< Max channel volume. */
|
|
kMaxMixerVolume = 256 /*!< Max global volume. */
|
|
};
|
|
|
|
public:
|
|
Mixer() {}
|
|
virtual ~Mixer() {}
|
|
|
|
|
|
|
|
/**
|
|
* Check whether the mixer is ready and set up.
|
|
*
|
|
* The mixer might not be set up on systems that do not support
|
|
* digital sound output. In such case, the mixer processing might
|
|
* never be called. That, in turn, can cause breakage in games that try to
|
|
* sync with an audio stream. In particular, the AdLib MIDI emulation.
|
|
*
|
|
* @return Whether the mixer is ready and set up.
|
|
*
|
|
* @todo get rid of this?
|
|
*/
|
|
virtual bool isReady() const = 0;
|
|
|
|
/**
|
|
* Return the mixer's internal mutex so that audio players can use it.
|
|
*/
|
|
virtual Common::Mutex &mutex() = 0;
|
|
|
|
/**
|
|
* Start playing the given audio stream.
|
|
*
|
|
* Note that the sound ID assigned here is unique. At most, one stream
|
|
* with the given ID can play at any given time. Trying to play a sound
|
|
* with an ID that is already in use causes the new sound to not be played.
|
|
*
|
|
* @param type Type of the stream - voice/SFX/music.
|
|
* @param handle A SoundHandle instance that can be used to reference and control
|
|
* the stream using suitable mixer methods.
|
|
* @param stream The actual AudioStream to be played.
|
|
* @param id Unique ID assigned to this stream.
|
|
* @param volume Volume with which to play the sound, ranging from 0 to 255.
|
|
* @param balance Balance with which to play the sound, ranging from -127 to 127 (full left to full right).
|
|
* 0 is balanced, -128 is invalid.
|
|
* @param autofreeStream If set, the stream will be freed after the playback is finished.
|
|
* @param permanent If set, a plain stopAll call will not stop this particular stream.
|
|
* @param reverseStereo If set, left and right channels will be swapped.
|
|
*/
|
|
virtual void playStream(
|
|
SoundType type,
|
|
SoundHandle *handle,
|
|
AudioStream *stream,
|
|
int id = -1,
|
|
byte volume = kMaxChannelVolume,
|
|
int8 balance = 0,
|
|
DisposeAfterUse::Flag autofreeStream = DisposeAfterUse::YES,
|
|
bool permanent = false,
|
|
bool reverseStereo = false) = 0;
|
|
|
|
/**
|
|
* Stop all currently playing sounds.
|
|
*/
|
|
virtual void stopAll() = 0;
|
|
|
|
/**
|
|
* Stop playing the sound with the given ID.
|
|
*
|
|
* @param id ID of the sound.
|
|
*/
|
|
virtual void stopID(int id) = 0;
|
|
|
|
/**
|
|
* Stop playing the sound corresponding to the given handle.
|
|
*
|
|
* @param handle The sound to stop playing.
|
|
*/
|
|
virtual void stopHandle(SoundHandle handle) = 0;
|
|
|
|
|
|
|
|
/**
|
|
* Pause or unpause all sounds, including all regular and permanent
|
|
* channels.
|
|
*
|
|
* @param paused True to pause everything, false to unpause.
|
|
*/
|
|
virtual void pauseAll(bool paused) = 0;
|
|
|
|
/**
|
|
* Pause or unpause the sound with the given ID.
|
|
*
|
|
* @param id ID of the sound.
|
|
* @param paused True to pause the sound, false to unpause it.
|
|
*/
|
|
virtual void pauseID(int id, bool paused) = 0;
|
|
|
|
/**
|
|
* Pause or unpause the sound corresponding to the given handle.
|
|
*
|
|
* @param handle The sound to pause or unpause.
|
|
* @param paused True to pause the sound, false to unpause it.
|
|
*/
|
|
virtual void pauseHandle(SoundHandle handle, bool paused) = 0;
|
|
|
|
|
|
|
|
/**
|
|
* Check whether a sound with the given ID is active.
|
|
*
|
|
* @param id ID of the sound to query.
|
|
*
|
|
* @return True if the sound is active.
|
|
*/
|
|
virtual bool isSoundIDActive(int id) = 0;
|
|
|
|
/**
|
|
* Get the sound ID for the given handle.
|
|
*
|
|
* @param handle The sound to query.
|
|
*
|
|
* @return Sound ID if the sound is active.
|
|
*/
|
|
virtual int getSoundID(SoundHandle handle) = 0;
|
|
|
|
/**
|
|
* Check whether a sound with the given handle is active.
|
|
*
|
|
* @param handle The sound to query.
|
|
*
|
|
* @return True if the sound is active.
|
|
*/
|
|
virtual bool isSoundHandleActive(SoundHandle handle) = 0;
|
|
|
|
|
|
/**
|
|
* Set the mute state for a given sound type.
|
|
*
|
|
* @param type Sound type. See @ref SoundType.
|
|
* @param mute Whether to mute (= true) or not (= false).
|
|
*/
|
|
virtual void muteSoundType(SoundType type, bool mute) = 0;
|
|
|
|
/**
|
|
* Query the mute state for a given sound type.
|
|
*
|
|
* @param type Sound type. See @ref SoundType.
|
|
*/
|
|
virtual bool isSoundTypeMuted(SoundType type) const = 0;
|
|
|
|
/**
|
|
* Set the channel volume for the given handle.
|
|
*
|
|
* @param handle The sound to affect.
|
|
* @param volume The new channel volume, in the range 0 - kMaxChannelVolume.
|
|
*/
|
|
virtual void setChannelVolume(SoundHandle handle, byte volume) = 0;
|
|
|
|
/**
|
|
* Get the channel volume for the given handle.
|
|
*
|
|
* @param handle The sound to affect.
|
|
*
|
|
* @return The channel volume.
|
|
*/
|
|
virtual byte getChannelVolume(SoundHandle handle) = 0;
|
|
|
|
/**
|
|
* Set the channel balance for the given handle.
|
|
*
|
|
* @param handle The sound to affect.
|
|
* @param balance The new channel balance:
|
|
* (-127 ... 0 ... 127) corresponds to (left ... center ... right)
|
|
*/
|
|
virtual void setChannelBalance(SoundHandle handle, int8 balance) = 0;
|
|
|
|
/**
|
|
* Get the channel balance for the given handle.
|
|
*
|
|
* @param handle The sound to affect.
|
|
*
|
|
* @return The channel balance.
|
|
*/
|
|
virtual int8 getChannelBalance(SoundHandle handle) = 0;
|
|
|
|
/**
|
|
* Get an approximation of for how long the channel has been playing.
|
|
*/
|
|
virtual uint32 getSoundElapsedTime(SoundHandle handle) = 0;
|
|
|
|
/**
|
|
* Get an approximation of for how long the channel has been playing.
|
|
*/
|
|
virtual Timestamp getElapsedTime(SoundHandle handle) = 0;
|
|
|
|
/**
|
|
* Check whether any channel of the given sound type is active.
|
|
*
|
|
* For example, this can be used to check whether any SFX sound
|
|
* is currently playing by checking for type kSFXSoundType.
|
|
*
|
|
* @param type The sound type to query.
|
|
*
|
|
* @return True if any channels of the specified type are active.
|
|
*/
|
|
virtual bool hasActiveChannelOfType(SoundType type) = 0;
|
|
|
|
/**
|
|
* Set the volume for the given sound type.
|
|
*
|
|
* @param type Sound type.
|
|
* @param volume The new global volume, in the range 0 - kMaxMixerVolume.
|
|
*/
|
|
virtual void setVolumeForSoundType(SoundType type, int volume) = 0;
|
|
|
|
/**
|
|
* Check what the global volume is for a sound type.
|
|
*
|
|
* @param type Sound type.
|
|
*
|
|
* @return The global volume, in the range 0 - kMaxMixerVolume.
|
|
*/
|
|
virtual int getVolumeForSoundType(SoundType type) const = 0;
|
|
|
|
/**
|
|
* Return the output sample rate of the system.
|
|
*
|
|
* @return The output sample rate in Hz.
|
|
*/
|
|
virtual uint getOutputRate() const = 0;
|
|
};
|
|
|
|
/** @} */
|
|
} // End of namespace Audio
|
|
|
|
#endif
|