sound.hpp

Go to the documentation of this file.

/*
    Copyright (C) 2003 - 2025
    by David White <dave@whitevine.net>
    Part of the Battle for Wesnoth Project https://www.wesnoth.org/
 
    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.
 
    See the COPYING file for more details.
*/
 
#pragma once
 
#include "events.hpp"
#include "map/location.hpp"
#include "sound_tracks.hpp"
#include "sound_music_track.hpp"
#include "utils/optional_fwd.hpp"
 
#include <map>
#include <string>
 
class config;
 
namespace sound {
 
std::string current_driver();
std::vector<std::string> enumerate_drivers();
 
struct driver_status
{
    bool initialized{false};
    int frequency{0};
    SDL_AudioFormat format{SDL_AUDIO_UNKNOWN};
    int channels{0};
 
    static driver_status query();
};
 
bool init_sound();
void close_sound();
 
void stop_music();
void stop_sound();
void stop_UI_sound();
void stop_bell();
 
void restart_music();
void restart_sound();
void restart_bell();
void restart_UI_sound();
 
// Read config entry, alter track list accordingly.
void play_music_config(const config &music_node, bool allow_interrupt_current_track = false, int i = -1);
// Act on any track list changes from above.
void commit_music_changes();
 
// Play this particular music file once, then silence.
void play_music_once(const std::string& id);
// Empty the playlist
void empty_playlist();
// Start playing current music.
void play_music();
 
// Change parameters of a playing sound, given its id
void reposition_sound(unsigned id, unsigned int distance);
 
constexpr inline int distance_silent = 255;
constexpr inline int distance_none = 0;
 
// Check if there's a sound associated with given id playing
bool is_sound_playing(int id);
 
// Stop sound associated with a given id
void stop_sound(unsigned id);
 
// Play sound, or random one of comma-separated sounds.
void play_sound(const std::string& files, sound_tracks::type group = sound_tracks::type::sound_fx, unsigned int repeats = 0);
 
// Play sound, or random one of comma-separated sounds. Use specified
// distance and associate it with specified id (of a sound source).
void play_sound_positioned(const std::string &files, int repeats, unsigned int distance, unsigned int id);
 
// Play sound, or random one of comma-separated sounds in bell channel
void play_bell(const std::string& files);
 
// Play sound, or random one of comma-separated sounds in timer channel
void play_timer(const std::string& files, const std::chrono::milliseconds& loop_ticks, const std::chrono::milliseconds& fadein_ticks);
 
// Play user-interface sound, or random one of comma-separated sounds.
void play_UI_sound(const std::string& files);
 
// A class to periodically check for new music that needs to be played
class music_thinker : public events::pump_monitor {
    void process();
};
 
// A class to mute music when the game is in background
class music_muter : public events::sdl_handler {
public:
    music_muter();
    void handle_event(const SDL_Event&) override {}
    void handle_window_event(const SDL_Event& event) override;
};
 
// Save music playlist for snapshot
void write_music_play_list(config& snapshot);
 
class volume
{
public:
    constexpr explicit volume(float factor)
        : gain(factor)
    {
    }
 
    constexpr static volume from_percent(float percentage)
    { return volume{percentage / 100.f}; }
 
    constexpr float as_percent() const
    { return gain * 100.f; }
 
    /** Implicit conversion for use with SDL. */
    constexpr operator float() const
    { return gain; }
 
    constexpr auto operator*(const volume& other) const
    { return volume{gain * other.gain}; }
 
    constexpr auto operator/(const volume& other) const
    { return volume{gain / other.gain}; }
 
    constexpr auto operator+(const volume& other) const
    { return volume{gain + other.gain}; }
 
    constexpr auto operator-(const volume& other) const
    { return volume{gain - other.gain}; }
 
private:
    float gain{1.0};
};
 
constexpr inline volume silence{0.f};
constexpr inline volume full_volume{1.f};
constexpr inline volume max_volume{1.28f};
 
volume get_music_volume();
volume get_sound_volume();
 
void set_music_volume(volume vol);
void set_sound_volume(volume vol);
void set_bell_volume(volume vol);
void set_UI_volume(volume vol);
 
utils::optional<std::size_t> get_current_track_index();
std::shared_ptr<sound::music_track> get_current_track();
std::shared_ptr<sound::music_track> get_previous_music_track();
unsigned int get_num_tracks();
void remove_track(unsigned int i);
void play_track(unsigned int i);
 
void flush_cache();
 
}