sound.h

/* 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 NANCY_SOUND_H
#define NANCY_SOUND_H
 
#include "engines/nancy/commontypes.h"
 
#include "audio/mixer.h"
 
namespace Common {
class SeekableReadStream;
}
 
namespace Audio {
class SeekableAudioStream;
class QueuingAudioStream;
}
 
namespace Nancy {
 
class IFF;
class NancyConsole;
class NancyEngine;
 
class SoundManager {
public:
    // Settings for playing a sound, used in nancy3 and up
    // Older versions had a different, non-bitflag enum, but testing
    // indicates those were never actually implemented
    enum PlayCommandFlags {
        kPlaySequential             = 0x0001,       // Play normally
        kPlaySequentialPosition     = 0x0003,       // Play at fixed position in 3D space
        kPlaySequentialFrameAnchor  = 0x0007,       // Position in 3D space is tied to a background frame, ignoring 3D coordinates
 
        kPlayRandomTime             = 0x0010,   // Play at random time intervals
        kPlayRandomPosition         = 0x0020,   // Play at random 3D positions
 
        kPlayMoveLinear             = 0x0100,   // Move sound position in 3D space. The movement is linear unless kPlayMoveCircular is also set
        kPlayMoveCircular           = 0x0300,   // Move sound position in a circular direction (see SoundRotationAxis)
        kPlayRandomMove             = 0x0500    // Move along random vector. Does not combine with kPlayMoveCircular
    };
 
    SoundManager();
    ~SoundManager();
 
    void loadCommonSounds(IFF *boot);
    void initSoundChannels();
 
    // Load a sound into a channel without starting it
    void loadSound(const SoundDescription &description, SoundEffectDescription **effectData = nullptr, bool forceReload = false);
 
    void playSound(uint16 channelID);
    void playSound(const SoundDescription &description);
    void playSound(const Common::String &chunkName);
 
    void pauseSound(uint16 channelID, bool pause);
    void pauseSound(const SoundDescription &description, bool pause);
    void pauseSound(const Common::String &chunkName, bool pause);
    void pauseAllSounds(bool pause);
 
    bool isSoundPlaying(uint16 channelID) const;
    bool isSoundPlaying(const SoundDescription &description) const;
    bool isSoundPlaying(const Common::String &chunkName) const;
 
    void stopSound(uint16 channelID);
    void stopSound(const SoundDescription &description);
    void stopSound(const Common::String &chunkName);
    void stopAllSounds();
 
    byte getVolume(uint16 channelID);
    byte getVolume(const SoundDescription &description);
    byte getVolume(const Common::String &chunkName);
 
    void setVolume(uint16 channelID, uint16 volume);
    void setVolume(const SoundDescription &description, uint16 volume);
    void setVolume(const Common::String &chunkName, uint16 volume);
 
    // The volume a channel was last given, by the sound loaded into it or by
    // setVolume(), from 0 to 100. Nancy20 scripts read it back.
    uint16 getRequestedVolume(uint16 channelID) const;
 
    // Nancy 11+ Update3DSound (AR 156). Adjusts a playing fixed-position
    // 3D sound's position and/or its min/max audible distance.
    void update3DSoundPosition(uint16 channelID, int32 x, int32 y, int32 z);
    void update3DSoundMinDistance(uint16 channelID, uint32 minDistance);
    void update3DSoundMaxDistance(uint16 channelID, uint32 maxDistance);
 
    // Nancy12 Set3DSoundListenerPosition (AR 168). Overrides the 3D listener
    // position, which is otherwise taken from the scene summary. The override
    // is cleared when a new scene is loaded.
    void setListenerPosition(const Math::Vector3d &position);
    void clearListenerPositionOverride();
 
    uint32 getRate(uint16 channelID);
    uint32 getRate(const SoundDescription &description);
    uint32 getRate(const Common::String &chunkName);
 
    uint32 getBaseRate(uint16 channelID);
    uint32 getBaseRate(const SoundDescription &description);
    uint32 getBaseRate(const Common::String &chunkName);
 
    void setRate(uint16 channelID, uint32 rate);
    void setRate(const SoundDescription &description, uint32 rate);
    void setRate(const Common::String &chunkName, uint32 rate);
 
    Audio::Timestamp getLength(uint16 channelID);
    Audio::Timestamp getLength(const SoundDescription &description);
    Audio::Timestamp getLength(const Common::String &chunkName);
 
    bool isCommonSound(const Common::String &soundName) const { return _commonSounds.contains(soundName); }
 
    void soundEffectMaintenance();
    void recalculateSoundEffects();
 
    Math::Vector3d &getOrientation() { return _orientation; }
    Common::String getChannelInfo(uint16 channelID);
 
    // Used when changing scenes
    void stopAndUnloadSceneSpecificSounds();
    void pauseSceneSpecificSounds(bool pause);
 
    static Audio::SeekableAudioStream *makeHISStream(Common::SeekableReadStream *stream, DisposeAfterUse::Flag disposeAfterUse, uint32 overrideSamplesPerSec = 0);
 
protected:
    struct Channel {
        ~Channel();
        Common::String name;
        Audio::Mixer::SoundType type = Audio::Mixer::SoundType::kPlainSoundType;
        uint16 playCommands = 1;
        uint16 numLoops = 0;
        uint volume = 0;
        uint16 requestedVolume = 0;
        uint16 panAnchorFrame = 0;
        bool isPanning = false;
        Audio::SeekableAudioStream *stream = nullptr;
        Audio::AudioStream *streamForMixer = nullptr;
        Audio::SoundHandle handle;
        bool isPersistent = false;
 
        // Sound effect data, not applicable to nancy2 and below
        SoundEffectDescription *effectData = nullptr;
        Math::Vector3d position;
        Math::Vector3d positionDelta;
        uint32 nextStepTime = 0;
        uint16 stepsLeft = 0;
        uint32 nextRepeatTime = 0;
    };
 
    void soundEffectMaintenance(uint16 channelID, bool force = false);
 
    // Nancy 13 introduced the MMIX ("music mix") boot chunk, a table mapping a
    // short location code (e.g. "CAM", "BRI") to a set of interchangeable music /
    // ambience tracks. When a sound is loaded by such a code, the engine picks one
    // of the mapped tracks at random and plays that instead. Returns the resolved
    // filename, or the input name unchanged when it doesn't match any mix record.
    Common::String resolveMusicMix(const Common::String &name) const;
 
    // Returns the listener position override if one is active, otherwise
    // the scene summary's listener position
    Math::Vector3d getListenerPosition() const;
 
    Audio::Mixer *_mixer;
 
    Common::Array<Channel> _channels;
    Common::HashMap<Common::String, SoundDescription> _commonSounds;
 
    bool _shouldRecalculate;
 
    Math::Vector3d _orientation;
    Math::Vector3d _position;
    uint _positionLerp = 0;
 
    Math::Vector3d _listenerPositionOverride;
    bool _hasListenerPositionOverride = false;
};
 
} // End of namespace Nancy
 
#endif // NANCY_SOUND_H