Initial commit
This commit is contained in:
398
audio/mixer.h
Normal file
398
audio/mixer.h
Normal file
@@ -0,0 +1,398 @@
|
||||
/* 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 3 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, see <http://www.gnu.org/licenses/>.
|
||||
*
|
||||
*/
|
||||
|
||||
#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 = 0xffffffff;
|
||||
|
||||
public:
|
||||
/**
|
||||
* Determine whether two handles are the same.
|
||||
*/
|
||||
bool operator==(const SoundHandle &h) const { return _val == h._val; }
|
||||
|
||||
/**
|
||||
* Determine whether two handles are not the same.
|
||||
*/
|
||||
bool operator!=(const SoundHandle &h) const { return _val != h._val; }
|
||||
};
|
||||
|
||||
/**
|
||||
* 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;
|
||||
|
||||
/**
|
||||
* Set the channel's left fader level for the given handle.
|
||||
*
|
||||
* @param handle The sound to affect.
|
||||
* @param faderL The channel's new left fader level, in the range of 0-255.
|
||||
*/
|
||||
virtual void setChannelFaderL(SoundHandle handle, uint8 faderL) = 0;
|
||||
|
||||
/**
|
||||
* Get the channel's left fader level for the given handle.
|
||||
*
|
||||
* @param handle The sound to affect.
|
||||
*
|
||||
* @return The channel's left fader level.
|
||||
*/
|
||||
virtual uint8 getChannelFaderL(SoundHandle handle) = 0;
|
||||
|
||||
/**
|
||||
* Set the channel's right fader level for the given handle.
|
||||
*
|
||||
* @param handle The sound to affect.
|
||||
* @param faderR The channel's new right fader level, in the range of 0-255.
|
||||
*/
|
||||
virtual void setChannelFaderR(SoundHandle handle, uint8 faderR) = 0;
|
||||
|
||||
/**
|
||||
* Get the channel's right fader level for the given handle.
|
||||
*
|
||||
* @param handle The sound to affect.
|
||||
*
|
||||
* @return The channel's right fader level.
|
||||
*/
|
||||
virtual uint8 getChannelFaderR(SoundHandle handle) = 0;
|
||||
|
||||
/**
|
||||
* Set the sample rate for the given handle.
|
||||
*
|
||||
* @param handle The sound to affect.
|
||||
* @param rate The new sample rate. Must be less than 131072
|
||||
*/
|
||||
virtual void setChannelRate(SoundHandle handle, uint32 rate) = 0;
|
||||
|
||||
/**
|
||||
* Get the sample rate for the given handle.
|
||||
*
|
||||
* @param handle The sound to affect.
|
||||
*
|
||||
* @return The current sample rate of the channel.
|
||||
*/
|
||||
virtual uint32 getChannelRate(SoundHandle handle) = 0;
|
||||
|
||||
/**
|
||||
* Reset the sample rate of the channel back to its
|
||||
* AudioStream's native rate.
|
||||
*
|
||||
* @param handle The sound to affect.
|
||||
*/
|
||||
virtual void resetChannelRate(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;
|
||||
|
||||
/**
|
||||
* Replace the channel's stream with a version that loops indefinitely.
|
||||
*/
|
||||
virtual void loopChannel(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;
|
||||
|
||||
/**
|
||||
* Check whether the output is stereo.
|
||||
*
|
||||
* @return true if output is stereo, false if not.
|
||||
*/
|
||||
virtual bool getOutputStereo() const = 0;
|
||||
|
||||
/**
|
||||
* Return the output sample buffer size of the system.
|
||||
*
|
||||
* The return value is measured in frame units instead of bytes. It can be converted
|
||||
* to bytes by multiplying it with the sample size and the number of channels. For
|
||||
* example, for 16-bit stereo output it should be multiplied by 4.
|
||||
*
|
||||
* @return The number of samples processed at each audio callback.
|
||||
*/
|
||||
virtual uint getOutputBufSize() const = 0;
|
||||
};
|
||||
|
||||
/** @} */
|
||||
} // End of namespace Audio
|
||||
|
||||
#endif
|
||||
Reference in New Issue
Block a user