a1d4bc80c2
Single line comments starting with `///` are interpreted by Microsoft Visual Studio as documentation containing XML code. Therefore single line comments starting with `///<` unfortunately cause a parsing error, as IntelliSense will assume the `<` is the start of an XML tag. This is not the case, but unfortunately, IntelliSense will still complain about the following space character rather than displaying the raw string. This commit alters all such comments to start with `//!<` instead, which prevents the issue. This fixes issue #1622.
338 lines
12 KiB
C++
338 lines
12 KiB
C++
////////////////////////////////////////////////////////////
|
|
//
|
|
// SFML - Simple and Fast Multimedia Library
|
|
// Copyright (C) 2007-2019 Laurent Gomila (laurent@sfml-dev.org)
|
|
//
|
|
// This software is provided 'as-is', without any express or implied warranty.
|
|
// In no event will the authors be held liable for any damages arising from the use of this software.
|
|
//
|
|
// Permission is granted to anyone to use this software for any purpose,
|
|
// including commercial applications, and to alter it and redistribute it freely,
|
|
// subject to the following restrictions:
|
|
//
|
|
// 1. The origin of this software must not be misrepresented;
|
|
// you must not claim that you wrote the original software.
|
|
// If you use this software in a product, an acknowledgment
|
|
// in the product documentation would be appreciated but is not required.
|
|
//
|
|
// 2. Altered source versions must be plainly marked as such,
|
|
// and must not be misrepresented as being the original software.
|
|
//
|
|
// 3. This notice may not be removed or altered from any source distribution.
|
|
//
|
|
////////////////////////////////////////////////////////////
|
|
|
|
#ifndef SFML_MUSIC_HPP
|
|
#define SFML_MUSIC_HPP
|
|
|
|
////////////////////////////////////////////////////////////
|
|
// Headers
|
|
////////////////////////////////////////////////////////////
|
|
#include <SFML/Audio/Export.hpp>
|
|
#include <SFML/Audio/SoundStream.hpp>
|
|
#include <SFML/Audio/InputSoundFile.hpp>
|
|
#include <SFML/System/Mutex.hpp>
|
|
#include <SFML/System/Time.hpp>
|
|
#include <string>
|
|
#include <vector>
|
|
|
|
|
|
namespace sf
|
|
{
|
|
class InputStream;
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Streamed music played from an audio file
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
class SFML_AUDIO_API Music : public SoundStream
|
|
{
|
|
public:
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Structure defining a time range using the template type
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
template <typename T>
|
|
struct Span
|
|
{
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Default constructor
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
Span()
|
|
{
|
|
|
|
}
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Initialization constructor
|
|
///
|
|
/// \param off Initial Offset
|
|
/// \param len Initial Length
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
Span(T off, T len):
|
|
offset(off),
|
|
length(len)
|
|
{
|
|
|
|
}
|
|
|
|
T offset; //!< The beginning offset of the time range
|
|
T length; //!< The length of the time range
|
|
};
|
|
|
|
// Define the relevant Span types
|
|
typedef Span<Time> TimeSpan;
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Default constructor
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
Music();
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Destructor
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
~Music();
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Open a music from an audio file
|
|
///
|
|
/// This function doesn't start playing the music (call play()
|
|
/// to do so).
|
|
/// See the documentation of sf::InputSoundFile for the list
|
|
/// of supported formats.
|
|
///
|
|
/// \warning Since the music is not loaded at once but rather
|
|
/// streamed continuously, the file must remain accessible until
|
|
/// the sf::Music object loads a new music or is destroyed.
|
|
///
|
|
/// \param filename Path of the music file to open
|
|
///
|
|
/// \return True if loading succeeded, false if it failed
|
|
///
|
|
/// \see openFromMemory, openFromStream
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
bool openFromFile(const std::string& filename);
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Open a music from an audio file in memory
|
|
///
|
|
/// This function doesn't start playing the music (call play()
|
|
/// to do so).
|
|
/// See the documentation of sf::InputSoundFile for the list
|
|
/// of supported formats.
|
|
///
|
|
/// \warning Since the music is not loaded at once but rather streamed
|
|
/// continuously, the \a data buffer must remain accessible until
|
|
/// the sf::Music object loads a new music or is destroyed. That is,
|
|
/// you can't deallocate the buffer right after calling this function.
|
|
///
|
|
/// \param data Pointer to the file data in memory
|
|
/// \param sizeInBytes Size of the data to load, in bytes
|
|
///
|
|
/// \return True if loading succeeded, false if it failed
|
|
///
|
|
/// \see openFromFile, openFromStream
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
bool openFromMemory(const void* data, std::size_t sizeInBytes);
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Open a music from an audio file in a custom stream
|
|
///
|
|
/// This function doesn't start playing the music (call play()
|
|
/// to do so).
|
|
/// See the documentation of sf::InputSoundFile for the list
|
|
/// of supported formats.
|
|
///
|
|
/// \warning Since the music is not loaded at once but rather
|
|
/// streamed continuously, the \a stream must remain accessible
|
|
/// until the sf::Music object loads a new music or is destroyed.
|
|
///
|
|
/// \param stream Source stream to read from
|
|
///
|
|
/// \return True if loading succeeded, false if it failed
|
|
///
|
|
/// \see openFromFile, openFromMemory
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
bool openFromStream(InputStream& stream);
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Get the total duration of the music
|
|
///
|
|
/// \return Music duration
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
Time getDuration() const;
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Get the positions of the of the sound's looping sequence
|
|
///
|
|
/// \return Loop Time position class.
|
|
///
|
|
/// \warning Since setLoopPoints() performs some adjustments on the
|
|
/// provided values and rounds them to internal samples, a call to
|
|
/// getLoopPoints() is not guaranteed to return the same times passed
|
|
/// into a previous call to setLoopPoints(). However, it is guaranteed
|
|
/// to return times that will map to the valid internal samples of
|
|
/// this Music if they are later passed to setLoopPoints().
|
|
///
|
|
/// \see setLoopPoints
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
TimeSpan getLoopPoints() const;
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Sets the beginning and end of the sound's looping sequence using sf::Time
|
|
///
|
|
/// Loop points allow one to specify a pair of positions such that, when the music
|
|
/// is enabled for looping, it will seamlessly seek to the beginning whenever it
|
|
/// encounters the end. Valid ranges for timePoints.offset and timePoints.length are
|
|
/// [0, Dur) and (0, Dur-offset] respectively, where Dur is the value returned by getDuration().
|
|
/// Note that the EOF "loop point" from the end to the beginning of the stream is still honored,
|
|
/// in case the caller seeks to a point after the end of the loop range. This function can be
|
|
/// safely called at any point after a stream is opened, and will be applied to a playing sound
|
|
/// without affecting the current playing offset.
|
|
///
|
|
/// \warning Setting the loop points while the stream's status is Paused
|
|
/// will set its status to Stopped. The playing offset will be unaffected.
|
|
///
|
|
/// \param timePoints The definition of the loop. Can be any time points within the sound's length
|
|
///
|
|
/// \see getLoopPoints
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
void setLoopPoints(TimeSpan timePoints);
|
|
|
|
protected:
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Request a new chunk of audio samples from the stream source
|
|
///
|
|
/// This function fills the chunk from the next samples
|
|
/// to read from the audio file.
|
|
///
|
|
/// \param data Chunk of data to fill
|
|
///
|
|
/// \return True to continue playback, false to stop
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
virtual bool onGetData(Chunk& data);
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Change the current playing position in the stream source
|
|
///
|
|
/// \param timeOffset New playing position, from the beginning of the music
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
virtual void onSeek(Time timeOffset);
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Change the current playing position in the stream source to the loop offset
|
|
///
|
|
/// This is called by the underlying SoundStream whenever it needs us to reset
|
|
/// the seek position for a loop. We then determine whether we are looping on a
|
|
/// loop point or the end-of-file, perform the seek, and return the new position.
|
|
///
|
|
/// \return The seek position after looping (or -1 if there's no loop)
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
virtual Int64 onLoop();
|
|
|
|
private:
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Initialize the internal state after loading a new music
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
void initialize();
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Helper to convert an sf::Time to a sample position
|
|
///
|
|
/// \param position Time to convert to samples
|
|
///
|
|
/// \return The number of samples elapsed at the given time
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
Uint64 timeToSamples(Time position) const;
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \brief Helper to convert a sample position to an sf::Time
|
|
///
|
|
/// \param samples Sample count to convert to Time
|
|
///
|
|
/// \return The Time position of the given sample
|
|
///
|
|
////////////////////////////////////////////////////////////
|
|
Time samplesToTime(Uint64 samples) const;
|
|
|
|
////////////////////////////////////////////////////////////
|
|
// Member data
|
|
////////////////////////////////////////////////////////////
|
|
InputSoundFile m_file; //!< The streamed music file
|
|
std::vector<Int16> m_samples; //!< Temporary buffer of samples
|
|
Mutex m_mutex; //!< Mutex protecting the data
|
|
Span<Uint64> m_loopSpan; //!< Loop Range Specifier
|
|
};
|
|
|
|
} // namespace sf
|
|
|
|
|
|
#endif // SFML_MUSIC_HPP
|
|
|
|
|
|
////////////////////////////////////////////////////////////
|
|
/// \class sf::Music
|
|
/// \ingroup audio
|
|
///
|
|
/// Musics are sounds that are streamed rather than completely
|
|
/// loaded in memory. This is especially useful for compressed
|
|
/// musics that usually take hundreds of MB when they are
|
|
/// uncompressed: by streaming it instead of loading it entirely,
|
|
/// you avoid saturating the memory and have almost no loading delay.
|
|
/// This implies that the underlying resource (file, stream or
|
|
/// memory buffer) must remain valid for the lifetime of the
|
|
/// sf::Music object.
|
|
///
|
|
/// Apart from that, a sf::Music has almost the same features as
|
|
/// the sf::SoundBuffer / sf::Sound pair: you can play/pause/stop
|
|
/// it, request its parameters (channels, sample rate), change
|
|
/// the way it is played (pitch, volume, 3D position, ...), etc.
|
|
///
|
|
/// As a sound stream, a music is played in its own thread in order
|
|
/// not to block the rest of the program. This means that you can
|
|
/// leave the music alone after calling play(), it will manage itself
|
|
/// very well.
|
|
///
|
|
/// Usage example:
|
|
/// \code
|
|
/// // Declare a new music
|
|
/// sf::Music music;
|
|
///
|
|
/// // Open it from an audio file
|
|
/// if (!music.openFromFile("music.ogg"))
|
|
/// {
|
|
/// // error...
|
|
/// }
|
|
///
|
|
/// // Change some parameters
|
|
/// music.setPosition(0, 1, 10); // change its 3D position
|
|
/// music.setPitch(2); // increase the pitch
|
|
/// music.setVolume(50); // reduce the volume
|
|
/// music.setLoop(true); // make it loop
|
|
///
|
|
/// // Play it
|
|
/// music.play();
|
|
/// \endcode
|
|
///
|
|
/// \see sf::Sound, sf::SoundStream
|
|
///
|
|
////////////////////////////////////////////////////////////
|