lauchmelder/SFML
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Source code changes.

Browse source 
* Changed newlines to \n.
* Removed whitespace before colons.
* Fixed several alignments.
This commit is contained in:
Stefan Schindler 2014-09-30 16:07:25 +02:00
parent b27cbd5036
commit f24ca9a840
268 changed files with 40227 additions and 40227 deletions
Download patch file Download diff file Expand all files Collapse all files

468
include/SFML/Audio/Listener.hpp
View file

@ -1,234 +1,234 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_LISTENER_HPP
#define SFML_LISTENER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Vector3.hpp>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief The audio listener is the point in the scene
/// from where all the sounds are heard
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API Listener
{
public :
////////////////////////////////////////////////////////////
/// \brief Change the global volume of all the sounds and musics
///
/// The volume is a number between 0 and 100; it is combined with
/// the individual volume of each sound / music.
/// The default value for the volume is 100 (maximum).
///
/// \param volume New global volume, in the range [0, 100]
///
/// \see getGlobalVolume
///
////////////////////////////////////////////////////////////
static void setGlobalVolume(float volume);
////////////////////////////////////////////////////////////
/// \brief Get the current value of the global volume
///
/// \return Current global volume, in the range [0, 100]
///
/// \see setGlobalVolume
///
////////////////////////////////////////////////////////////
static float getGlobalVolume();
////////////////////////////////////////////////////////////
/// \brief Set the position of the listener in the scene
///
/// The default listener's position is (0, 0, 0).
///
/// \param x X coordinate of the listener's position
/// \param y Y coordinate of the listener's position
/// \param z Z coordinate of the listener's position
///
/// \see getPosition, setDirection
///
////////////////////////////////////////////////////////////
static void setPosition(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the position of the listener in the scene
///
/// The default listener's position is (0, 0, 0).
///
/// \param position New listener's position
///
/// \see getPosition, setDirection
///
////////////////////////////////////////////////////////////
static void setPosition(const Vector3f& position);
////////////////////////////////////////////////////////////
/// \brief Get the current position of the listener in the scene
///
/// \return Listener's position
///
/// \see setPosition
///
////////////////////////////////////////////////////////////
static Vector3f getPosition();
////////////////////////////////////////////////////////////
/// \brief Set the forward vector of the listener in the scene
///
/// The direction (also called "at vector") is the vector
/// pointing forward from the listener's perspective. Together
/// with the up vector, it defines the 3D orientation of the
/// listener in the scene. The direction vector doesn't
/// have to be normalized.
/// The default listener's direction is (0, 0, -1).
///
/// \param x X coordinate of the listener's direction
/// \param y Y coordinate of the listener's direction
/// \param z Z coordinate of the listener's direction
///
/// \see getDirection, setUpVector, setPosition
///
////////////////////////////////////////////////////////////
static void setDirection(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the forward vector of the listener in the scene
///
/// The direction (also called "at vector") is the vector
/// pointing forward from the listener's perspective. Together
/// with the up vector, it defines the 3D orientation of the
/// listener in the scene. The direction vector doesn't
/// have to be normalized.
/// The default listener's direction is (0, 0, -1).
///
/// \param direction New listener's direction
///
/// \see getDirection, setUpVector, setPosition
///
////////////////////////////////////////////////////////////
static void setDirection(const Vector3f& direction);
////////////////////////////////////////////////////////////
/// \brief Get the current forward vector of the listener in the scene
///
/// \return Listener's forward vector (not normalized)
///
/// \see setDirection
///
////////////////////////////////////////////////////////////
static Vector3f getDirection();
////////////////////////////////////////////////////////////
/// \brief Set the upward vector of the listener in the scene
///
/// The up vector is the vector that points upward from the
/// listener's perspective. Together with the direction, it
/// defines the 3D orientation of the listener in the scene.
/// The up vector doesn't have to be normalized.
/// The default listener's up vector is (0, 1, 0). It is usually
/// not necessary to change it, especially in 2D scenarios.
///
/// \param x X coordinate of the listener's up vector
/// \param y Y coordinate of the listener's up vector
/// \param z Z coordinate of the listener's up vector
///
/// \see getUpVector, setDirection, setPosition
///
////////////////////////////////////////////////////////////
static void setUpVector(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the upward vector of the listener in the scene
///
/// The up vector is the vector that points upward from the
/// listener's perspective. Together with the direction, it
/// defines the 3D orientation of the listener in the scene.
/// The up vector doesn't have to be normalized.
/// The default listener's up vector is (0, 1, 0). It is usually
/// not necessary to change it, especially in 2D scenarios.
///
/// \param upVector New listener's up vector
///
/// \see getUpVector, setDirection, setPosition
///
////////////////////////////////////////////////////////////
static void setUpVector(const Vector3f& upVector);
////////////////////////////////////////////////////////////
/// \brief Get the current upward vector of the listener in the scene
///
/// \return Listener's upward vector (not normalized)
///
/// \see setUpVector
///
////////////////////////////////////////////////////////////
static Vector3f getUpVector();
};
} // namespace sf
#endif // SFML_LISTENER_HPP
////////////////////////////////////////////////////////////
/// \class sf::Listener
/// \ingroup audio
///
/// The audio listener defines the global properties of the
/// audio environment, it defines where and how sounds and musics
/// are heard. If sf::View is the eyes of the user, then sf::Listener
/// is his ears (by the way, they are often linked together --
/// same position, orientation, etc.).
///
/// sf::Listener is a simple interface, which allows to setup the
/// listener in the 3D audio environment (position, direction and
/// up vector), and to adjust the global volume.
///
/// Because the listener is unique in the scene, sf::Listener only
/// contains static functions and doesn't have to be instantiated.
///
/// Usage example:
/// \code
/// // Move the listener to the position (1, 0, -5)
/// sf::Listener::setPosition(1, 0, -5);
///
/// // Make it face the right axis (1, 0, 0)
/// sf::Listener::setDirection(1, 0, 0);
///
/// // Reduce the global volume
/// sf::Listener::setGlobalVolume(50);
/// \endcode
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_LISTENER_HPP
#define SFML_LISTENER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Vector3.hpp>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief The audio listener is the point in the scene
/// from where all the sounds are heard
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API Listener
{
public:
////////////////////////////////////////////////////////////
/// \brief Change the global volume of all the sounds and musics
///
/// The volume is a number between 0 and 100; it is combined with
/// the individual volume of each sound / music.
/// The default value for the volume is 100 (maximum).
///
/// \param volume New global volume, in the range [0, 100]
///
/// \see getGlobalVolume
///
////////////////////////////////////////////////////////////
static void setGlobalVolume(float volume);
////////////////////////////////////////////////////////////
/// \brief Get the current value of the global volume
///
/// \return Current global volume, in the range [0, 100]
///
/// \see setGlobalVolume
///
////////////////////////////////////////////////////////////
static float getGlobalVolume();
////////////////////////////////////////////////////////////
/// \brief Set the position of the listener in the scene
///
/// The default listener's position is (0, 0, 0).
///
/// \param x X coordinate of the listener's position
/// \param y Y coordinate of the listener's position
/// \param z Z coordinate of the listener's position
///
/// \see getPosition, setDirection
///
////////////////////////////////////////////////////////////
static void setPosition(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the position of the listener in the scene
///
/// The default listener's position is (0, 0, 0).
///
/// \param position New listener's position
///
/// \see getPosition, setDirection
///
////////////////////////////////////////////////////////////
static void setPosition(const Vector3f& position);
////////////////////////////////////////////////////////////
/// \brief Get the current position of the listener in the scene
///
/// \return Listener's position
///
/// \see setPosition
///
////////////////////////////////////////////////////////////
static Vector3f getPosition();
////////////////////////////////////////////////////////////
/// \brief Set the forward vector of the listener in the scene
///
/// The direction (also called "at vector") is the vector
/// pointing forward from the listener's perspective. Together
/// with the up vector, it defines the 3D orientation of the
/// listener in the scene. The direction vector doesn't
/// have to be normalized.
/// The default listener's direction is (0, 0, -1).
///
/// \param x X coordinate of the listener's direction
/// \param y Y coordinate of the listener's direction
/// \param z Z coordinate of the listener's direction
///
/// \see getDirection, setUpVector, setPosition
///
////////////////////////////////////////////////////////////
static void setDirection(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the forward vector of the listener in the scene
///
/// The direction (also called "at vector") is the vector
/// pointing forward from the listener's perspective. Together
/// with the up vector, it defines the 3D orientation of the
/// listener in the scene. The direction vector doesn't
/// have to be normalized.
/// The default listener's direction is (0, 0, -1).
///
/// \param direction New listener's direction
///
/// \see getDirection, setUpVector, setPosition
///
////////////////////////////////////////////////////////////
static void setDirection(const Vector3f& direction);
////////////////////////////////////////////////////////////
/// \brief Get the current forward vector of the listener in the scene
///
/// \return Listener's forward vector (not normalized)
///
/// \see setDirection
///
////////////////////////////////////////////////////////////
static Vector3f getDirection();
////////////////////////////////////////////////////////////
/// \brief Set the upward vector of the listener in the scene
///
/// The up vector is the vector that points upward from the
/// listener's perspective. Together with the direction, it
/// defines the 3D orientation of the listener in the scene.
/// The up vector doesn't have to be normalized.
/// The default listener's up vector is (0, 1, 0). It is usually
/// not necessary to change it, especially in 2D scenarios.
///
/// \param x X coordinate of the listener's up vector
/// \param y Y coordinate of the listener's up vector
/// \param z Z coordinate of the listener's up vector
///
/// \see getUpVector, setDirection, setPosition
///
////////////////////////////////////////////////////////////
static void setUpVector(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the upward vector of the listener in the scene
///
/// The up vector is the vector that points upward from the
/// listener's perspective. Together with the direction, it
/// defines the 3D orientation of the listener in the scene.
/// The up vector doesn't have to be normalized.
/// The default listener's up vector is (0, 1, 0). It is usually
/// not necessary to change it, especially in 2D scenarios.
///
/// \param upVector New listener's up vector
///
/// \see getUpVector, setDirection, setPosition
///
////////////////////////////////////////////////////////////
static void setUpVector(const Vector3f& upVector);
////////////////////////////////////////////////////////////
/// \brief Get the current upward vector of the listener in the scene
///
/// \return Listener's upward vector (not normalized)
///
/// \see setUpVector
///
////////////////////////////////////////////////////////////
static Vector3f getUpVector();
};
} // namespace sf
#endif // SFML_LISTENER_HPP
////////////////////////////////////////////////////////////
/// \class sf::Listener
/// \ingroup audio
///
/// The audio listener defines the global properties of the
/// audio environment, it defines where and how sounds and musics
/// are heard. If sf::View is the eyes of the user, then sf::Listener
/// is his ears (by the way, they are often linked together --
/// same position, orientation, etc.).
///
/// sf::Listener is a simple interface, which allows to setup the
/// listener in the 3D audio environment (position, direction and
/// up vector), and to adjust the global volume.
///
/// Because the listener is unique in the scene, sf::Listener only
/// contains static functions and doesn't have to be instantiated.
///
/// Usage example:
/// \code
/// // Move the listener to the position (1, 0, -5)
/// sf::Listener::setPosition(1, 0, -5);
///
/// // Make it face the right axis (1, 0, 0)
/// sf::Listener::setDirection(1, 0, 0);
///
/// // Reduce the global volume
/// sf::Listener::setGlobalVolume(50);
/// \endcode
///
////////////////////////////////////////////////////////////

456
include/SFML/Audio/Music.hpp
View file

@ -1,228 +1,228 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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/System/Mutex.hpp>
#include <SFML/System/Time.hpp>
#include <string>
#include <vector>
namespace sf
{
namespace priv
{
class SoundFile;
}
class InputStream;
////////////////////////////////////////////////////////////
/// \brief Streamed music played from an audio file
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API Music : public SoundStream
{
public :
////////////////////////////////////////////////////////////
/// \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).
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \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).
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
/// Since the music is not loaded completely but rather streamed
/// continuously, the \a data must remain available as long as the
/// music is playing (ie. you can't deallocate it 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).
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
/// Since the music is not loaded completely but rather streamed
/// continuously, the \a stream must remain alive as long as the
/// music is playing (ie. you can't destroy it right after calling
/// this function).
///
/// \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;
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);
private :
////////////////////////////////////////////////////////////
/// \brief Initialize the internal state after loading a new music
///
////////////////////////////////////////////////////////////
void initialize();
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
priv::SoundFile* m_file; ///< Sound file
Time m_duration; ///< Music duration
std::vector<Int16> m_samples; ///< Temporary buffer of samples
Mutex m_mutex; ///< Mutex protecting the data
};
} // 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.
///
/// 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
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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/System/Mutex.hpp>
#include <SFML/System/Time.hpp>
#include <string>
#include <vector>
namespace sf
{
namespace priv
{
class SoundFile;
}
class InputStream;
////////////////////////////////////////////////////////////
/// \brief Streamed music played from an audio file
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API Music : public SoundStream
{
public:
////////////////////////////////////////////////////////////
/// \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).
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \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).
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
/// Since the music is not loaded completely but rather streamed
/// continuously, the \a data must remain available as long as the
/// music is playing (ie. you can't deallocate it 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).
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
/// Since the music is not loaded completely but rather streamed
/// continuously, the \a stream must remain alive as long as the
/// music is playing (ie. you can't destroy it right after calling
/// this function).
///
/// \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;
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);
private:
////////////////////////////////////////////////////////////
/// \brief Initialize the internal state after loading a new music
///
////////////////////////////////////////////////////////////
void initialize();
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
priv::SoundFile* m_file; ///< Sound file
Time m_duration; ///< Music duration
std::vector<Int16> m_samples; ///< Temporary buffer of samples
Mutex m_mutex; ///< Mutex protecting the data
};
} // 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.
///
/// 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
///
////////////////////////////////////////////////////////////

528
include/SFML/Audio/Sound.hpp
View file

@ -1,264 +1,264 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUND_HPP
#define SFML_SOUND_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/Audio/SoundSource.hpp>
#include <SFML/System/Time.hpp>
#include <cstdlib>
namespace sf
{
class SoundBuffer;
////////////////////////////////////////////////////////////
/// \brief Regular sound that can be played in the audio environment
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API Sound : public SoundSource
{
public :
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
////////////////////////////////////////////////////////////
Sound();
////////////////////////////////////////////////////////////
/// \brief Construct the sound with a buffer
///
/// \param buffer Sound buffer containing the audio data to play with the sound
///
////////////////////////////////////////////////////////////
explicit Sound(const SoundBuffer& buffer);
////////////////////////////////////////////////////////////
/// \brief Copy constructor
///
/// \param copy Instance to copy
///
////////////////////////////////////////////////////////////
Sound(const Sound& copy);
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
~Sound();
////////////////////////////////////////////////////////////
/// \brief Start or resume playing the sound
///
/// This function starts the stream if it was stopped, resumes
/// it if it was paused, and restarts it from beginning if it
/// was it already playing.
/// This function uses its own thread so that it doesn't block
/// the rest of the program while the sound is played.
///
/// \see pause, stop
///
////////////////////////////////////////////////////////////
void play();
////////////////////////////////////////////////////////////
/// \brief Pause the sound
///
/// This function pauses the sound if it was playing,
/// otherwise (sound already paused or stopped) it has no effect.
///
/// \see play, stop
///
////////////////////////////////////////////////////////////
void pause();
////////////////////////////////////////////////////////////
/// \brief stop playing the sound
///
/// This function stops the sound if it was playing or paused,
/// and does nothing if it was already stopped.
/// It also resets the playing position (unlike pause()).
///
/// \see play, pause
///
////////////////////////////////////////////////////////////
void stop();
////////////////////////////////////////////////////////////
/// \brief Set the source buffer containing the audio data to play
///
/// It is important to note that the sound buffer is not copied,
/// thus the sf::SoundBuffer instance must remain alive as long
/// as it is attached to the sound.
///
/// \param buffer Sound buffer to attach to the sound
///
/// \see getBuffer
///
////////////////////////////////////////////////////////////
void setBuffer(const SoundBuffer& buffer);
////////////////////////////////////////////////////////////
/// \brief Set whether or not the sound should loop after reaching the end
///
/// If set, the sound will restart from beginning after
/// reaching the end and so on, until it is stopped or
/// setLoop(false) is called.
/// The default looping state for sound is false.
///
/// \param loop True to play in loop, false to play once
///
/// \see getLoop
///
////////////////////////////////////////////////////////////
void setLoop(bool loop);
////////////////////////////////////////////////////////////
/// \brief Change the current playing position of the sound
///
/// The playing position can be changed when the sound is
/// either paused or playing. Changing the playing position
/// when the sound is stopped has no effect, since playing
/// the sound would reset its position.
///
/// \param timeOffset New playing position, from the beginning of the sound
///
/// \see getPlayingOffset
///
////////////////////////////////////////////////////////////
void setPlayingOffset(Time timeOffset);
////////////////////////////////////////////////////////////
/// \brief Get the audio buffer attached to the sound
///
/// \return Sound buffer attached to the sound (can be NULL)
///
////////////////////////////////////////////////////////////
const SoundBuffer* getBuffer() const;
////////////////////////////////////////////////////////////
/// \brief Tell whether or not the sound is in loop mode
///
/// \return True if the sound is looping, false otherwise
///
/// \see setLoop
///
////////////////////////////////////////////////////////////
bool getLoop() const;
////////////////////////////////////////////////////////////
/// \brief Get the current playing position of the sound
///
/// \return Current playing position, from the beginning of the sound
///
/// \see setPlayingOffset
///
////////////////////////////////////////////////////////////
Time getPlayingOffset() const;
////////////////////////////////////////////////////////////
/// \brief Get the current status of the sound (stopped, paused, playing)
///
/// \return Current status of the sound
///
////////////////////////////////////////////////////////////
Status getStatus() const;
////////////////////////////////////////////////////////////
/// \brief Overload of assignment operator
///
/// \param right Instance to assign
///
/// \return Reference to self
///
////////////////////////////////////////////////////////////
Sound& operator =(const Sound& right);
////////////////////////////////////////////////////////////
/// \brief Reset the internal buffer of the sound
///
/// This function is for internal use only, you don't have
/// to use it. It is called by the sf::SoundBuffer that
/// this sound uses, when it is destroyed in order to prevent
/// the sound from using a dead buffer.
///
////////////////////////////////////////////////////////////
void resetBuffer();
private :
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
const SoundBuffer* m_buffer; ///< Sound buffer bound to the source
};
} // namespace sf
#endif // SFML_SOUND_HPP
////////////////////////////////////////////////////////////
/// \class sf::Sound
/// \ingroup audio
///
/// sf::Sound is the class to use to play sounds.
/// It provides:
/// \li Control (play, pause, stop)
/// \li Ability to modify output parameters in real-time (pitch, volume, ...)
/// \li 3D spatial features (position, attenuation, ...).
///
/// sf::Sound is perfect for playing short sounds that can
/// fit in memory and require no latency, like foot steps or
/// gun shots. For longer sounds, like background musics
/// or long speeches, rather see sf::Music (which is based
/// on streaming).
///
/// In order to work, a sound must be given a buffer of audio
/// data to play. Audio data (samples) is stored in sf::SoundBuffer,
/// and attached to a sound with the setBuffer() function.
/// The buffer object attached to a sound must remain alive
/// as long as the sound uses it. Note that multiple sounds
/// can use the same sound buffer at the same time.
///
/// Usage example:
/// \code
/// sf::SoundBuffer buffer;
/// buffer.loadFromFile("sound.wav");
///
/// sf::Sound sound;
/// sound.setBuffer(buffer);
/// sound.play();
/// \endcode
///
/// \see sf::SoundBuffer, sf::Music
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUND_HPP
#define SFML_SOUND_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/Audio/SoundSource.hpp>
#include <SFML/System/Time.hpp>
#include <cstdlib>
namespace sf
{
class SoundBuffer;
////////////////////////////////////////////////////////////
/// \brief Regular sound that can be played in the audio environment
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API Sound : public SoundSource
{
public:
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
////////////////////////////////////////////////////////////
Sound();
////////////////////////////////////////////////////////////
/// \brief Construct the sound with a buffer
///
/// \param buffer Sound buffer containing the audio data to play with the sound
///
////////////////////////////////////////////////////////////
explicit Sound(const SoundBuffer& buffer);
////////////////////////////////////////////////////////////
/// \brief Copy constructor
///
/// \param copy Instance to copy
///
////////////////////////////////////////////////////////////
Sound(const Sound& copy);
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
~Sound();
////////////////////////////////////////////////////////////
/// \brief Start or resume playing the sound
///
/// This function starts the stream if it was stopped, resumes
/// it if it was paused, and restarts it from beginning if it
/// was it already playing.
/// This function uses its own thread so that it doesn't block
/// the rest of the program while the sound is played.
///
/// \see pause, stop
///
////////////////////////////////////////////////////////////
void play();
////////////////////////////////////////////////////////////
/// \brief Pause the sound
///
/// This function pauses the sound if it was playing,
/// otherwise (sound already paused or stopped) it has no effect.
///
/// \see play, stop
///
////////////////////////////////////////////////////////////
void pause();
////////////////////////////////////////////////////////////
/// \brief stop playing the sound
///
/// This function stops the sound if it was playing or paused,
/// and does nothing if it was already stopped.
/// It also resets the playing position (unlike pause()).
///
/// \see play, pause
///
////////////////////////////////////////////////////////////
void stop();
////////////////////////////////////////////////////////////
/// \brief Set the source buffer containing the audio data to play
///
/// It is important to note that the sound buffer is not copied,
/// thus the sf::SoundBuffer instance must remain alive as long
/// as it is attached to the sound.
///
/// \param buffer Sound buffer to attach to the sound
///
/// \see getBuffer
///
////////////////////////////////////////////////////////////
void setBuffer(const SoundBuffer& buffer);
////////////////////////////////////////////////////////////
/// \brief Set whether or not the sound should loop after reaching the end
///
/// If set, the sound will restart from beginning after
/// reaching the end and so on, until it is stopped or
/// setLoop(false) is called.
/// The default looping state for sound is false.
///
/// \param loop True to play in loop, false to play once
///
/// \see getLoop
///
////////////////////////////////////////////////////////////
void setLoop(bool loop);
////////////////////////////////////////////////////////////
/// \brief Change the current playing position of the sound
///
/// The playing position can be changed when the sound is
/// either paused or playing. Changing the playing position
/// when the sound is stopped has no effect, since playing
/// the sound would reset its position.
///
/// \param timeOffset New playing position, from the beginning of the sound
///
/// \see getPlayingOffset
///
////////////////////////////////////////////////////////////
void setPlayingOffset(Time timeOffset);
////////////////////////////////////////////////////////////
/// \brief Get the audio buffer attached to the sound
///
/// \return Sound buffer attached to the sound (can be NULL)
///
////////////////////////////////////////////////////////////
const SoundBuffer* getBuffer() const;
////////////////////////////////////////////////////////////
/// \brief Tell whether or not the sound is in loop mode
///
/// \return True if the sound is looping, false otherwise
///
/// \see setLoop
///
////////////////////////////////////////////////////////////
bool getLoop() const;
////////////////////////////////////////////////////////////
/// \brief Get the current playing position of the sound
///
/// \return Current playing position, from the beginning of the sound
///
/// \see setPlayingOffset
///
////////////////////////////////////////////////////////////
Time getPlayingOffset() const;
////////////////////////////////////////////////////////////
/// \brief Get the current status of the sound (stopped, paused, playing)
///
/// \return Current status of the sound
///
////////////////////////////////////////////////////////////
Status getStatus() const;
////////////////////////////////////////////////////////////
/// \brief Overload of assignment operator
///
/// \param right Instance to assign
///
/// \return Reference to self
///
////////////////////////////////////////////////////////////
Sound& operator =(const Sound& right);
////////////////////////////////////////////////////////////
/// \brief Reset the internal buffer of the sound
///
/// This function is for internal use only, you don't have
/// to use it. It is called by the sf::SoundBuffer that
/// this sound uses, when it is destroyed in order to prevent
/// the sound from using a dead buffer.
///
////////////////////////////////////////////////////////////
void resetBuffer();
private:
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
const SoundBuffer* m_buffer; ///< Sound buffer bound to the source
};
} // namespace sf
#endif // SFML_SOUND_HPP
////////////////////////////////////////////////////////////
/// \class sf::Sound
/// \ingroup audio
///
/// sf::Sound is the class to use to play sounds.
/// It provides:
/// \li Control (play, pause, stop)
/// \li Ability to modify output parameters in real-time (pitch, volume, ...)
/// \li 3D spatial features (position, attenuation, ...).
///
/// sf::Sound is perfect for playing short sounds that can
/// fit in memory and require no latency, like foot steps or
/// gun shots. For longer sounds, like background musics
/// or long speeches, rather see sf::Music (which is based
/// on streaming).
///
/// In order to work, a sound must be given a buffer of audio
/// data to play. Audio data (samples) is stored in sf::SoundBuffer,
/// and attached to a sound with the setBuffer() function.
/// The buffer object attached to a sound must remain alive
/// as long as the sound uses it. Note that multiple sounds
/// can use the same sound buffer at the same time.
///
/// Usage example:
/// \code
/// sf::SoundBuffer buffer;
/// buffer.loadFromFile("sound.wav");
///
/// sf::Sound sound;
/// sound.setBuffer(buffer);
/// sound.play();
/// \endcode
///
/// \see sf::SoundBuffer, sf::Music
///
////////////////////////////////////////////////////////////

718
include/SFML/Audio/SoundBuffer.hpp
View file

@ -1,359 +1,359 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDBUFFER_HPP
#define SFML_SOUNDBUFFER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Time.hpp>
#include <string>
#include <vector>
#include <set>
namespace sf
{
namespace priv
{
class SoundFile;
}
class Sound;
class InputStream;
////////////////////////////////////////////////////////////
/// \brief Storage for audio samples defining a sound
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundBuffer
{
public :
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
////////////////////////////////////////////////////////////
SoundBuffer();
////////////////////////////////////////////////////////////
/// \brief Copy constructor
///
/// \param copy Instance to copy
///
////////////////////////////////////////////////////////////
SoundBuffer(const SoundBuffer& copy);
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
~SoundBuffer();
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from a file
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \param filename Path of the sound file to load
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromMemory, loadFromStream, loadFromSamples, saveToFile
///
////////////////////////////////////////////////////////////
bool loadFromFile(const std::string& filename);
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from a file in memory
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \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 loadFromFile, loadFromStream, loadFromSamples
///
////////////////////////////////////////////////////////////
bool loadFromMemory(const void* data, std::size_t sizeInBytes);
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from a custom stream
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \param stream Source stream to read from
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromFile, loadFromMemory, loadFromSamples
///
////////////////////////////////////////////////////////////
bool loadFromStream(InputStream& stream);
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from an array of audio samples
///
/// The assumed format of the audio samples is 16 bits signed integer
/// (sf::Int16).
///
/// \param samples Pointer to the array of samples in memory
/// \param sampleCount Number of samples in the array
/// \param channelCount Number of channels (1 = mono, 2 = stereo, ...)
/// \param sampleRate Sample rate (number of samples to play per second)
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromFile, loadFromMemory, saveToFile
///
////////////////////////////////////////////////////////////
bool loadFromSamples(const Int16* samples, std::size_t sampleCount, unsigned int channelCount, unsigned int sampleRate);
////////////////////////////////////////////////////////////
/// \brief Save the sound buffer to an audio file
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \param filename Path of the sound file to write
///
/// \return True if saving succeeded, false if it failed
///
/// \see loadFromFile, loadFromMemory, loadFromSamples
///
////////////////////////////////////////////////////////////
bool saveToFile(const std::string& filename) const;
////////////////////////////////////////////////////////////
/// \brief Get the array of audio samples stored in the buffer
///
/// The format of the returned samples is 16 bits signed integer
/// (sf::Int16). The total number of samples in this array
/// is given by the getSampleCount() function.
///
/// \return Read-only pointer to the array of sound samples
///
/// \see getSampleCount
///
////////////////////////////////////////////////////////////
const Int16* getSamples() const;
////////////////////////////////////////////////////////////
/// \brief Get the number of samples stored in the buffer
///
/// The array of samples can be accessed with the getSamples()
/// function.
///
/// \return Number of samples
///
/// \see getSamples
///
////////////////////////////////////////////////////////////
std::size_t getSampleCount() const;
////////////////////////////////////////////////////////////
/// \brief Get the sample rate of the sound
///
/// The sample rate is the number of samples played per second.
/// The higher, the better the quality (for example, 44100
/// samples/s is CD quality).
///
/// \return Sample rate (number of samples per second)
///
/// \see getChannelCount, getDuration
///
////////////////////////////////////////////////////////////
unsigned int getSampleRate() const;
////////////////////////////////////////////////////////////
/// \brief Get the number of channels used by the sound
///
/// If the sound is mono then the number of channels will
/// be 1, 2 for stereo, etc.
///
/// \return Number of channels
///
/// \see getSampleRate, getDuration
///
////////////////////////////////////////////////////////////
unsigned int getChannelCount() const;
////////////////////////////////////////////////////////////
/// \brief Get the total duration of the sound
///
/// \return Sound duration
///
/// \see getSampleRate, getChannelCount
///
////////////////////////////////////////////////////////////
Time getDuration() const;
////////////////////////////////////////////////////////////
/// \brief Overload of assignment operator
///
/// \param right Instance to assign
///
/// \return Reference to self
///
////////////////////////////////////////////////////////////
SoundBuffer& operator =(const SoundBuffer& right);
private :
friend class Sound;
////////////////////////////////////////////////////////////
/// \brief Initialize the internal state after loading a new sound
///
/// \param file Sound file providing access to the new loaded sound
///
/// \return True on succesful initialization, false on failure
///
////////////////////////////////////////////////////////////
bool initialize(priv::SoundFile& file);
////////////////////////////////////////////////////////////
/// \brief Update the internal buffer with the cached audio samples
///
/// \param channelCount Number of channels
/// \param sampleRate Sample rate (number of samples per second)
///
/// \return True on success, false if any error happened
///
////////////////////////////////////////////////////////////
bool update(unsigned int channelCount, unsigned int sampleRate);
////////////////////////////////////////////////////////////
/// \brief Add a sound to the list of sounds that use this buffer
///
/// \param sound Sound instance to attach
///
////////////////////////////////////////////////////////////
void attachSound(Sound* sound) const;
////////////////////////////////////////////////////////////
/// \brief Remove a sound from the list of sounds that use this buffer
///
/// \param sound Sound instance to detach
///
////////////////////////////////////////////////////////////
void detachSound(Sound* sound) const;
////////////////////////////////////////////////////////////
// Types
////////////////////////////////////////////////////////////
typedef std::set<Sound*> SoundList; ///< Set of unique sound instances
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
unsigned int m_buffer; ///< OpenAL buffer identifier
std::vector<Int16> m_samples; ///< Samples buffer
Time m_duration; ///< Sound duration
mutable SoundList m_sounds; ///< List of sounds that are using this buffer
};
} // namespace sf
#endif // SFML_SOUNDBUFFER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundBuffer
/// \ingroup audio
///
/// A sound buffer holds the data of a sound, which is
/// an array of audio samples. A sample is a 16 bits signed integer
/// that defines the amplitude of the sound at a given time.
/// The sound is then restituted by playing these samples at
/// a high rate (for example, 44100 samples per second is the
/// standard rate used for playing CDs). In short, audio samples
/// are like texture pixels, and a sf::SoundBuffer is similar to
/// a sf::Texture.
///
/// A sound buffer can be loaded from a file (see loadFromFile()
/// for the complete list of supported formats), from memory, from
/// a custom stream (see sf::InputStream) or directly from an array
/// of samples. It can also be saved back to a file.
///
/// Sound buffers alone are not very useful: they hold the audio data
/// but cannot be played. To do so, you need to use the sf::Sound class,
/// which provides functions to play/pause/stop the sound as well as
/// changing the way it is outputted (volume, pitch, 3D position, ...).
/// This separation allows more flexibility and better performances:
/// indeed a sf::SoundBuffer is a heavy resource, and any operation on it
/// is slow (often too slow for real-time applications). On the other
/// side, a sf::Sound is a lightweight object, which can use the audio data
/// of a sound buffer and change the way it is played without actually
/// modifying that data. Note that it is also possible to bind
/// several sf::Sound instances to the same sf::SoundBuffer.
///
/// It is important to note that the sf::Sound instance doesn't
/// copy the buffer that it uses, it only keeps a reference to it.
/// Thus, a sf::SoundBuffer must not be destructed while it is
/// used by a sf::Sound (i.e. never write a function that
/// uses a local sf::SoundBuffer instance for loading a sound).
///
/// Usage example:
/// \code
/// // Declare a new sound buffer
/// sf::SoundBuffer buffer;
///
/// // Load it from a file
/// if (!buffer.loadFromFile("sound.wav"))
/// {
/// // error...
/// }
///
/// // Create a sound source and bind it to the buffer
/// sf::Sound sound1;
/// sound1.setBuffer(buffer);
///
/// // Play the sound
/// sound1.play();
///
/// // Create another sound source bound to the same buffer
/// sf::Sound sound2;
/// sound2.setBuffer(buffer);
///
/// // Play it with a higher pitch -- the first sound remains unchanged
/// sound2.setPitch(2);
/// sound2.play();
/// \endcode
///
/// \see sf::Sound, sf::SoundBufferRecorder
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDBUFFER_HPP
#define SFML_SOUNDBUFFER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Time.hpp>
#include <string>
#include <vector>
#include <set>
namespace sf
{
namespace priv
{
class SoundFile;
}
class Sound;
class InputStream;
////////////////////////////////////////////////////////////
/// \brief Storage for audio samples defining a sound
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundBuffer
{
public:
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
////////////////////////////////////////////////////////////
SoundBuffer();
////////////////////////////////////////////////////////////
/// \brief Copy constructor
///
/// \param copy Instance to copy
///
////////////////////////////////////////////////////////////
SoundBuffer(const SoundBuffer& copy);
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
~SoundBuffer();
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from a file
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \param filename Path of the sound file to load
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromMemory, loadFromStream, loadFromSamples, saveToFile
///
////////////////////////////////////////////////////////////
bool loadFromFile(const std::string& filename);
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from a file in memory
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \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 loadFromFile, loadFromStream, loadFromSamples
///
////////////////////////////////////////////////////////////
bool loadFromMemory(const void* data, std::size_t sizeInBytes);
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from a custom stream
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \param stream Source stream to read from
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromFile, loadFromMemory, loadFromSamples
///
////////////////////////////////////////////////////////////
bool loadFromStream(InputStream& stream);
////////////////////////////////////////////////////////////
/// \brief Load the sound buffer from an array of audio samples
///
/// The assumed format of the audio samples is 16 bits signed integer
/// (sf::Int16).
///
/// \param samples Pointer to the array of samples in memory
/// \param sampleCount Number of samples in the array
/// \param channelCount Number of channels (1 = mono, 2 = stereo, ...)
/// \param sampleRate Sample rate (number of samples to play per second)
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromFile, loadFromMemory, saveToFile
///
////////////////////////////////////////////////////////////
bool loadFromSamples(const Int16* samples, std::size_t sampleCount, unsigned int channelCount, unsigned int sampleRate);
////////////////////////////////////////////////////////////
/// \brief Save the sound buffer to an audio file
///
/// Here is a complete list of all the supported audio formats:
/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
///
/// \param filename Path of the sound file to write
///
/// \return True if saving succeeded, false if it failed
///
/// \see loadFromFile, loadFromMemory, loadFromSamples
///
////////////////////////////////////////////////////////////
bool saveToFile(const std::string& filename) const;
////////////////////////////////////////////////////////////
/// \brief Get the array of audio samples stored in the buffer
///
/// The format of the returned samples is 16 bits signed integer
/// (sf::Int16). The total number of samples in this array
/// is given by the getSampleCount() function.
///
/// \return Read-only pointer to the array of sound samples
///
/// \see getSampleCount
///
////////////////////////////////////////////////////////////
const Int16* getSamples() const;
////////////////////////////////////////////////////////////
/// \brief Get the number of samples stored in the buffer
///
/// The array of samples can be accessed with the getSamples()
/// function.
///
/// \return Number of samples
///
/// \see getSamples
///
////////////////////////////////////////////////////////////
std::size_t getSampleCount() const;
////////////////////////////////////////////////////////////
/// \brief Get the sample rate of the sound
///
/// The sample rate is the number of samples played per second.
/// The higher, the better the quality (for example, 44100
/// samples/s is CD quality).
///
/// \return Sample rate (number of samples per second)
///
/// \see getChannelCount, getDuration
///
////////////////////////////////////////////////////////////
unsigned int getSampleRate() const;
////////////////////////////////////////////////////////////
/// \brief Get the number of channels used by the sound
///
/// If the sound is mono then the number of channels will
/// be 1, 2 for stereo, etc.
///
/// \return Number of channels
///
/// \see getSampleRate, getDuration
///
////////////////////////////////////////////////////////////
unsigned int getChannelCount() const;
////////////////////////////////////////////////////////////
/// \brief Get the total duration of the sound
///
/// \return Sound duration
///
/// \see getSampleRate, getChannelCount
///
////////////////////////////////////////////////////////////
Time getDuration() const;
////////////////////////////////////////////////////////////
/// \brief Overload of assignment operator
///
/// \param right Instance to assign
///
/// \return Reference to self
///
////////////////////////////////////////////////////////////
SoundBuffer& operator =(const SoundBuffer& right);
private:
friend class Sound;
////////////////////////////////////////////////////////////
/// \brief Initialize the internal state after loading a new sound
///
/// \param file Sound file providing access to the new loaded sound
///
/// \return True on succesful initialization, false on failure
///
////////////////////////////////////////////////////////////
bool initialize(priv::SoundFile& file);
////////////////////////////////////////////////////////////
/// \brief Update the internal buffer with the cached audio samples
///
/// \param channelCount Number of channels
/// \param sampleRate Sample rate (number of samples per second)
///
/// \return True on success, false if any error happened
///
////////////////////////////////////////////////////////////
bool update(unsigned int channelCount, unsigned int sampleRate);
////////////////////////////////////////////////////////////
/// \brief Add a sound to the list of sounds that use this buffer
///
/// \param sound Sound instance to attach
///
////////////////////////////////////////////////////////////
void attachSound(Sound* sound) const;
////////////////////////////////////////////////////////////
/// \brief Remove a sound from the list of sounds that use this buffer
///
/// \param sound Sound instance to detach
///
////////////////////////////////////////////////////////////
void detachSound(Sound* sound) const;
////////////////////////////////////////////////////////////
// Types
////////////////////////////////////////////////////////////
typedef std::set<Sound*> SoundList; ///< Set of unique sound instances
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
unsigned int m_buffer; ///< OpenAL buffer identifier
std::vector<Int16> m_samples; ///< Samples buffer
Time m_duration; ///< Sound duration
mutable SoundList m_sounds; ///< List of sounds that are using this buffer
};
} // namespace sf
#endif // SFML_SOUNDBUFFER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundBuffer
/// \ingroup audio
///
/// A sound buffer holds the data of a sound, which is
/// an array of audio samples. A sample is a 16 bits signed integer
/// that defines the amplitude of the sound at a given time.
/// The sound is then restituted by playing these samples at
/// a high rate (for example, 44100 samples per second is the
/// standard rate used for playing CDs). In short, audio samples
/// are like texture pixels, and a sf::SoundBuffer is similar to
/// a sf::Texture.
///
/// A sound buffer can be loaded from a file (see loadFromFile()
/// for the complete list of supported formats), from memory, from
/// a custom stream (see sf::InputStream) or directly from an array
/// of samples. It can also be saved back to a file.
///
/// Sound buffers alone are not very useful: they hold the audio data
/// but cannot be played. To do so, you need to use the sf::Sound class,
/// which provides functions to play/pause/stop the sound as well as
/// changing the way it is outputted (volume, pitch, 3D position, ...).
/// This separation allows more flexibility and better performances:
/// indeed a sf::SoundBuffer is a heavy resource, and any operation on it
/// is slow (often too slow for real-time applications). On the other
/// side, a sf::Sound is a lightweight object, which can use the audio data
/// of a sound buffer and change the way it is played without actually
/// modifying that data. Note that it is also possible to bind
/// several sf::Sound instances to the same sf::SoundBuffer.
///
/// It is important to note that the sf::Sound instance doesn't
/// copy the buffer that it uses, it only keeps a reference to it.
/// Thus, a sf::SoundBuffer must not be destructed while it is
/// used by a sf::Sound (i.e. never write a function that
/// uses a local sf::SoundBuffer instance for loading a sound).
///
/// Usage example:
/// \code
/// // Declare a new sound buffer
/// sf::SoundBuffer buffer;
///
/// // Load it from a file
/// if (!buffer.loadFromFile("sound.wav"))
/// {
/// // error...
/// }
///
/// // Create a sound source and bind it to the buffer
/// sf::Sound sound1;
/// sound1.setBuffer(buffer);
///
/// // Play the sound
/// sound1.play();
///
/// // Create another sound source bound to the same buffer
/// sf::Sound sound2;
/// sound2.setBuffer(buffer);
///
/// // Play it with a higher pitch -- the first sound remains unchanged
/// sound2.setPitch(2);
/// sound2.play();
/// \endcode
///
/// \see sf::Sound, sf::SoundBufferRecorder
///
////////////////////////////////////////////////////////////

276
include/SFML/Audio/SoundBufferRecorder.hpp
View file

@ -1,138 +1,138 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDBUFFERRECORDER_HPP
#define SFML_SOUNDBUFFERRECORDER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/Audio/SoundBuffer.hpp>
#include <SFML/Audio/SoundRecorder.hpp>
#include <vector>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Specialized SoundRecorder which stores the captured
/// audio data into a sound buffer
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundBufferRecorder : public SoundRecorder
{
public :
////////////////////////////////////////////////////////////
/// \brief Get the sound buffer containing the captured audio data
///
/// The sound buffer is valid only after the capture has ended.
/// This function provides a read-only access to the internal
/// sound buffer, but it can be copied if you need to
/// make any modification to it.
///
/// \return Read-only access to the sound buffer
///
////////////////////////////////////////////////////////////
const SoundBuffer& getBuffer() const;
protected:
////////////////////////////////////////////////////////////
/// \brief Start capturing audio data
///
/// \return True to start the capture, or false to abort it
///
////////////////////////////////////////////////////////////
virtual bool onStart();
////////////////////////////////////////////////////////////
/// \brief Process a new chunk of recorded samples
///
/// \param samples Pointer to the new chunk of recorded samples
/// \param sampleCount Number of samples pointed by \a samples
///
/// \return True to continue the capture, or false to stop it
///
////////////////////////////////////////////////////////////
virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount);
////////////////////////////////////////////////////////////
/// \brief Stop capturing audio data
///
////////////////////////////////////////////////////////////
virtual void onStop();
private :
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
std::vector<Int16> m_samples; ///< Temporary sample buffer to hold the recorded data
SoundBuffer m_buffer; ///< Sound buffer that will contain the recorded data
};
} // namespace sf
#endif // SFML_SOUNDBUFFERRECORDER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundBufferRecorder
/// \ingroup audio
///
/// sf::SoundBufferRecorder allows to access a recorded sound
/// through a sf::SoundBuffer, so that it can be played, saved
/// to a file, etc.
///
/// It has the same simple interface as its base class (start(), stop())
/// and adds a function to retrieve the recorded sound buffer
/// (getBuffer()).
///
/// As usual, don't forget to call the isAvailable() function
/// before using this class (see sf::SoundRecorder for more details
/// about this).
///
/// Usage example:
/// \code
/// if (sf::SoundBufferRecorder::isAvailable())
/// {
/// // Record some audio data
/// sf::SoundBufferRecorder recorder;
/// recorder.start();
/// ...
/// recorder.stop();
///
/// // Get the buffer containing the captured audio data
/// const sf::SoundBuffer& buffer = recorder.getBuffer();
///
/// // Save it to a file (for example...)
/// buffer.saveToFile("my_record.ogg");
/// }
/// \endcode
///
/// \see sf::SoundRecorder
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDBUFFERRECORDER_HPP
#define SFML_SOUNDBUFFERRECORDER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/Audio/SoundBuffer.hpp>
#include <SFML/Audio/SoundRecorder.hpp>
#include <vector>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Specialized SoundRecorder which stores the captured
/// audio data into a sound buffer
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundBufferRecorder : public SoundRecorder
{
public:
////////////////////////////////////////////////////////////
/// \brief Get the sound buffer containing the captured audio data
///
/// The sound buffer is valid only after the capture has ended.
/// This function provides a read-only access to the internal
/// sound buffer, but it can be copied if you need to
/// make any modification to it.
///
/// \return Read-only access to the sound buffer
///
////////////////////////////////////////////////////////////
const SoundBuffer& getBuffer() const;
protected:
////////////////////////////////////////////////////////////
/// \brief Start capturing audio data
///
/// \return True to start the capture, or false to abort it
///
////////////////////////////////////////////////////////////
virtual bool onStart();
////////////////////////////////////////////////////////////
/// \brief Process a new chunk of recorded samples
///
/// \param samples Pointer to the new chunk of recorded samples
/// \param sampleCount Number of samples pointed by \a samples
///
/// \return True to continue the capture, or false to stop it
///
////////////////////////////////////////////////////////////
virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount);
////////////////////////////////////////////////////////////
/// \brief Stop capturing audio data
///
////////////////////////////////////////////////////////////
virtual void onStop();
private:
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
std::vector<Int16> m_samples; ///< Temporary sample buffer to hold the recorded data
SoundBuffer m_buffer; ///< Sound buffer that will contain the recorded data
};
} // namespace sf
#endif // SFML_SOUNDBUFFERRECORDER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundBufferRecorder
/// \ingroup audio
///
/// sf::SoundBufferRecorder allows to access a recorded sound
/// through a sf::SoundBuffer, so that it can be played, saved
/// to a file, etc.
///
/// It has the same simple interface as its base class (start(), stop())
/// and adds a function to retrieve the recorded sound buffer
/// (getBuffer()).
///
/// As usual, don't forget to call the isAvailable() function
/// before using this class (see sf::SoundRecorder for more details
/// about this).
///
/// Usage example:
/// \code
/// if (sf::SoundBufferRecorder::isAvailable())
/// {
/// // Record some audio data
/// sf::SoundBufferRecorder recorder;
/// recorder.start();
/// ...
/// recorder.stop();
///
/// // Get the buffer containing the captured audio data
/// const sf::SoundBuffer& buffer = recorder.getBuffer();
///
/// // Save it to a file (for example...)
/// buffer.saveToFile("my_record.ogg");
/// }
/// \endcode
///
/// \see sf::SoundRecorder
///
////////////////////////////////////////////////////////////

726
include/SFML/Audio/SoundRecorder.hpp
View file

@ -1,363 +1,363 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDRECORDER_HPP
#define SFML_SOUNDRECORDER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Thread.hpp>
#include <SFML/System/Time.hpp>
#include <vector>
#include <string>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Abstract base class for capturing sound data
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundRecorder
{
public :
////////////////////////////////////////////////////////////
/// \brief destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundRecorder();
////////////////////////////////////////////////////////////
/// \brief Start the capture
///
/// The \a sampleRate parameter defines the number of audio samples
/// captured per second. The higher, the better the quality
/// (for example, 44100 samples/sec is CD quality).
/// This function uses its own thread so that it doesn't block
/// the rest of the program while the capture runs.
/// Please note that only one capture can happen at the same time.
/// You can select which capture device will be used, by passing
/// the name to the setDevice() method. If none was selected
/// before, the default capture device will be used. You can get a
/// list of the names of all available capture devices by calling
/// getAvailableDevices().
///
/// \param sampleRate Desired capture rate, in number of samples per second
///
/// \return True, if start of capture was successful
///
/// \see stop, getAvailableDevices
///
////////////////////////////////////////////////////////////
bool start(unsigned int sampleRate = 44100);
////////////////////////////////////////////////////////////
/// \brief Stop the capture
///
/// \see start
///
////////////////////////////////////////////////////////////
void stop();
////////////////////////////////////////////////////////////
/// \brief Get the sample rate
///
/// The sample rate defines the number of audio samples
/// captured per second. The higher, the better the quality
/// (for example, 44100 samples/sec is CD quality).
///
/// \return Sample rate, in samples per second
///
////////////////////////////////////////////////////////////
unsigned int getSampleRate() const;
////////////////////////////////////////////////////////////
/// \brief Get a list of the names of all availabe audio capture devices
///
/// This function returns a vector of strings, containing
/// the names of all availabe audio capture devices.
///
/// \return A vector of strings containing the names
///
////////////////////////////////////////////////////////////
static std::vector<std::string> getAvailableDevices();
////////////////////////////////////////////////////////////
/// \brief Get the name of the default audio capture device
///
/// This function returns the name of the default audio
/// capture device. If none is available, an empty string
/// is returned.
///
/// \return The name of the default audio capture device
///
////////////////////////////////////////////////////////////
static std::string getDefaultDevice();
////////////////////////////////////////////////////////////
/// \brief Set the audio capture device
///
/// This function sets the audio capture device to the device
/// with the given \a name. It can be called on the fly (i.e:
/// while recording). If you do so while recording and
/// opening the device fails, it stops the recording.
///
/// \param name The name of the audio capture device
///
/// \return True, if it was able to set the requested device
///
/// \see getAvailableDevices, getDefaultDevice
///
////////////////////////////////////////////////////////////
bool setDevice(const std::string& name);
////////////////////////////////////////////////////////////
/// \brief Get the name of the current audio capture device
///
/// \return The name of the current audio capture device
///
////////////////////////////////////////////////////////////
const std::string& getDevice() const;
////////////////////////////////////////////////////////////
/// \brief Check if the system supports audio capture
///
/// This function should always be called before using
/// the audio capture features. If it returns false, then
/// any attempt to use sf::SoundRecorder or one of its derived
/// classes will fail.
///
/// \return True if audio capture is supported, false otherwise
///
////////////////////////////////////////////////////////////
static bool isAvailable();
protected :
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
/// This constructor is only meant to be called by derived classes.
///
////////////////////////////////////////////////////////////
SoundRecorder();
////////////////////////////////////////////////////////////
/// \brief Set the processing interval
///
/// The processing interval controls the period
/// between calls to the onProcessSamples function. You may
/// want to use a small interval if you want to process the
/// recorded data in real time, for example.
///
/// Note: this is only a hint, the actual period may vary.
/// So don't rely on this parameter to implement precise timing.
///
/// The default processing interval is 100 ms.
///
/// \param interval Processing interval
///
////////////////////////////////////////////////////////////
void setProcessingInterval(sf::Time interval);
////////////////////////////////////////////////////////////
/// \brief Start capturing audio data
///
/// This virtual function may be overriden by a derived class
/// if something has to be done every time a new capture
/// starts. If not, this function can be ignored; the default
/// implementation does nothing.
///
/// \return True to start the capture, or false to abort it
///
////////////////////////////////////////////////////////////
virtual bool onStart();
////////////////////////////////////////////////////////////
/// \brief Process a new chunk of recorded samples
///
/// This virtual function is called every time a new chunk of
/// recorded data is available. The derived class can then do
/// whatever it wants with it (storing it, playing it, sending
/// it over the network, etc.).
///
/// \param samples Pointer to the new chunk of recorded samples
/// \param sampleCount Number of samples pointed by \a samples
///
/// \return True to continue the capture, or false to stop it
///
////////////////////////////////////////////////////////////
virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount) = 0;
////////////////////////////////////////////////////////////
/// \brief Stop capturing audio data
///
/// This virtual function may be overriden by a derived class
/// if something has to be done every time the capture
/// ends. If not, this function can be ignored; the default
/// implementation does nothing.
///
////////////////////////////////////////////////////////////
virtual void onStop();
private :
////////////////////////////////////////////////////////////
/// \brief Function called as the entry point of the thread
///
/// This function starts the recording loop, and returns
/// only when the capture is stopped.
///
////////////////////////////////////////////////////////////
void record();
////////////////////////////////////////////////////////////
/// \brief Get the new available audio samples and process them
///
/// This function is called continuously during the
/// capture loop. It retrieves the captured samples and
/// forwards them to the derived class.
///
////////////////////////////////////////////////////////////
void processCapturedSamples();
////////////////////////////////////////////////////////////
/// \brief Clean up the recorder's internal resources
///
/// This function is called when the capture stops.
///
////////////////////////////////////////////////////////////
void cleanup();
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
Thread m_thread; ///< Thread running the background recording task
std::vector<Int16> m_samples; ///< Buffer to store captured samples
unsigned int m_sampleRate; ///< Sample rate
sf::Time m_processingInterval; ///< Time period between calls to onProcessSamples
bool m_isCapturing; ///< Capturing state
std::string m_deviceName; ///< Name of the audio capture device
};
} // namespace sf
#endif // SFML_SOUNDRECORDER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundRecorder
/// \ingroup audio
///
/// sf::SoundBuffer provides a simple interface to access
/// the audio recording capabilities of the computer
/// (the microphone). As an abstract base class, it only cares
/// about capturing sound samples, the task of making something
/// useful with them is left to the derived class. Note that
/// SFML provides a built-in specialization for saving the
/// captured data to a sound buffer (see sf::SoundBufferRecorder).
///
/// A derived class has only one virtual function to override:
/// \li onProcessSamples provides the new chunks of audio samples while the capture happens
///
/// Moreover, two additionnal virtual functions can be overriden
/// as well if necessary:
/// \li onStart is called before the capture happens, to perform custom initializations
/// \li onStop is called after the capture ends, to perform custom cleanup
///
/// A derived class can also control the frequency of the onProcessSamples
/// calls, with the setProcessingInterval protected function. The default
/// interval is chosen so that recording thread doesn't consume too much
/// CPU, but it can be changed to a smaller value if you need to process
/// the recorded data in real time, for example.
///
/// The audio capture feature may not be supported or activated
/// on every platform, thus it is recommended to check its
/// availability with the isAvailable() function. If it returns
/// false, then any attempt to use an audio recorder will fail.
///
/// If you have multiple sound input devices connected to your
/// computer (for example: microphone, external soundcard, webcam mic, ...)
/// you can get a list of all available devices throught the
/// getAvailableDevices() function. You can then select a device
/// by calling setDevice() with the appropiate device. Otherwise
/// the default capturing device will be used.
///
/// It is important to note that the audio capture happens in a
/// separate thread, so that it doesn't block the rest of the
/// program. In particular, the onProcessSamples virtual function
/// (but not onStart and not onStop) will be called
/// from this separate thread. It is important to keep this in
/// mind, because you may have to take care of synchronization
/// issues if you share data between threads.
///
/// Usage example:
/// \code
/// class CustomRecorder : public sf::SoundRecorder
/// {
/// virtual bool onStart() // optional
/// {
/// // Initialize whatever has to be done before the capture starts
/// ...
///
/// // Return true to start playing
/// return true;
/// }
///
/// virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount)
/// {
/// // Do something with the new chunk of samples (store them, send them, ...)
/// ...
///
/// // Return true to continue playing
/// return true;
/// }
///
/// virtual void onStop() // optional
/// {
/// // Clean up whatever has to be done after the capture ends
/// ...
/// }
/// }
///
/// // Usage
/// if (CustomRecorder::isAvailable())
/// {
/// CustomRecorder recorder;
///
/// if (!recorder.start())
/// return -1;
///
/// ...
/// recorder.stop();
/// }
/// \endcode
///
/// \see sf::SoundBufferRecorder
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDRECORDER_HPP
#define SFML_SOUNDRECORDER_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Thread.hpp>
#include <SFML/System/Time.hpp>
#include <vector>
#include <string>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Abstract base class for capturing sound data
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundRecorder
{
public:
////////////////////////////////////////////////////////////
/// \brief destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundRecorder();
////////////////////////////////////////////////////////////
/// \brief Start the capture
///
/// The \a sampleRate parameter defines the number of audio samples
/// captured per second. The higher, the better the quality
/// (for example, 44100 samples/sec is CD quality).
/// This function uses its own thread so that it doesn't block
/// the rest of the program while the capture runs.
/// Please note that only one capture can happen at the same time.
/// You can select which capture device will be used, by passing
/// the name to the setDevice() method. If none was selected
/// before, the default capture device will be used. You can get a
/// list of the names of all available capture devices by calling
/// getAvailableDevices().
///
/// \param sampleRate Desired capture rate, in number of samples per second
///
/// \return True, if start of capture was successful
///
/// \see stop, getAvailableDevices
///
////////////////////////////////////////////////////////////
bool start(unsigned int sampleRate = 44100);
////////////////////////////////////////////////////////////
/// \brief Stop the capture
///
/// \see start
///
////////////////////////////////////////////////////////////
void stop();
////////////////////////////////////////////////////////////
/// \brief Get the sample rate
///
/// The sample rate defines the number of audio samples
/// captured per second. The higher, the better the quality
/// (for example, 44100 samples/sec is CD quality).
///
/// \return Sample rate, in samples per second
///
////////////////////////////////////////////////////////////
unsigned int getSampleRate() const;
////////////////////////////////////////////////////////////
/// \brief Get a list of the names of all availabe audio capture devices
///
/// This function returns a vector of strings, containing
/// the names of all availabe audio capture devices.
///
/// \return A vector of strings containing the names
///
////////////////////////////////////////////////////////////
static std::vector<std::string> getAvailableDevices();
////////////////////////////////////////////////////////////
/// \brief Get the name of the default audio capture device
///
/// This function returns the name of the default audio
/// capture device. If none is available, an empty string
/// is returned.
///
/// \return The name of the default audio capture device
///
////////////////////////////////////////////////////////////
static std::string getDefaultDevice();
////////////////////////////////////////////////////////////
/// \brief Set the audio capture device
///
/// This function sets the audio capture device to the device
/// with the given \a name. It can be called on the fly (i.e:
/// while recording). If you do so while recording and
/// opening the device fails, it stops the recording.
///
/// \param name The name of the audio capture device
///
/// \return True, if it was able to set the requested device
///
/// \see getAvailableDevices, getDefaultDevice
///
////////////////////////////////////////////////////////////
bool setDevice(const std::string& name);
////////////////////////////////////////////////////////////
/// \brief Get the name of the current audio capture device
///
/// \return The name of the current audio capture device
///
////////////////////////////////////////////////////////////
const std::string& getDevice() const;
////////////////////////////////////////////////////////////
/// \brief Check if the system supports audio capture
///
/// This function should always be called before using
/// the audio capture features. If it returns false, then
/// any attempt to use sf::SoundRecorder or one of its derived
/// classes will fail.
///
/// \return True if audio capture is supported, false otherwise
///
////////////////////////////////////////////////////////////
static bool isAvailable();
protected:
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
/// This constructor is only meant to be called by derived classes.
///
////////////////////////////////////////////////////////////
SoundRecorder();
////////////////////////////////////////////////////////////
/// \brief Set the processing interval
///
/// The processing interval controls the period
/// between calls to the onProcessSamples function. You may
/// want to use a small interval if you want to process the
/// recorded data in real time, for example.
///
/// Note: this is only a hint, the actual period may vary.
/// So don't rely on this parameter to implement precise timing.
///
/// The default processing interval is 100 ms.
///
/// \param interval Processing interval
///
////////////////////////////////////////////////////////////
void setProcessingInterval(sf::Time interval);
////////////////////////////////////////////////////////////
/// \brief Start capturing audio data
///
/// This virtual function may be overriden by a derived class
/// if something has to be done every time a new capture
/// starts. If not, this function can be ignored; the default
/// implementation does nothing.
///
/// \return True to start the capture, or false to abort it
///
////////////////////////////////////////////////////////////
virtual bool onStart();
////////////////////////////////////////////////////////////
/// \brief Process a new chunk of recorded samples
///
/// This virtual function is called every time a new chunk of
/// recorded data is available. The derived class can then do
/// whatever it wants with it (storing it, playing it, sending
/// it over the network, etc.).
///
/// \param samples Pointer to the new chunk of recorded samples
/// \param sampleCount Number of samples pointed by \a samples
///
/// \return True to continue the capture, or false to stop it
///
////////////////////////////////////////////////////////////
virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount) = 0;
////////////////////////////////////////////////////////////
/// \brief Stop capturing audio data
///
/// This virtual function may be overriden by a derived class
/// if something has to be done every time the capture
/// ends. If not, this function can be ignored; the default
/// implementation does nothing.
///
////////////////////////////////////////////////////////////
virtual void onStop();
private:
////////////////////////////////////////////////////////////
/// \brief Function called as the entry point of the thread
///
/// This function starts the recording loop, and returns
/// only when the capture is stopped.
///
////////////////////////////////////////////////////////////
void record();
////////////////////////////////////////////////////////////
/// \brief Get the new available audio samples and process them
///
/// This function is called continuously during the
/// capture loop. It retrieves the captured samples and
/// forwards them to the derived class.
///
////////////////////////////////////////////////////////////
void processCapturedSamples();
////////////////////////////////////////////////////////////
/// \brief Clean up the recorder's internal resources
///
/// This function is called when the capture stops.
///
////////////////////////////////////////////////////////////
void cleanup();
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
Thread m_thread; ///< Thread running the background recording task
std::vector<Int16> m_samples; ///< Buffer to store captured samples
unsigned int m_sampleRate; ///< Sample rate
sf::Time m_processingInterval; ///< Time period between calls to onProcessSamples
bool m_isCapturing; ///< Capturing state
std::string m_deviceName; ///< Name of the audio capture device
};
} // namespace sf
#endif // SFML_SOUNDRECORDER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundRecorder
/// \ingroup audio
///
/// sf::SoundBuffer provides a simple interface to access
/// the audio recording capabilities of the computer
/// (the microphone). As an abstract base class, it only cares
/// about capturing sound samples, the task of making something
/// useful with them is left to the derived class. Note that
/// SFML provides a built-in specialization for saving the
/// captured data to a sound buffer (see sf::SoundBufferRecorder).
///
/// A derived class has only one virtual function to override:
/// \li onProcessSamples provides the new chunks of audio samples while the capture happens
///
/// Moreover, two additionnal virtual functions can be overriden
/// as well if necessary:
/// \li onStart is called before the capture happens, to perform custom initializations
/// \li onStop is called after the capture ends, to perform custom cleanup
///
/// A derived class can also control the frequency of the onProcessSamples
/// calls, with the setProcessingInterval protected function. The default
/// interval is chosen so that recording thread doesn't consume too much
/// CPU, but it can be changed to a smaller value if you need to process
/// the recorded data in real time, for example.
///
/// The audio capture feature may not be supported or activated
/// on every platform, thus it is recommended to check its
/// availability with the isAvailable() function. If it returns
/// false, then any attempt to use an audio recorder will fail.
///
/// If you have multiple sound input devices connected to your
/// computer (for example: microphone, external soundcard, webcam mic, ...)
/// you can get a list of all available devices throught the
/// getAvailableDevices() function. You can then select a device
/// by calling setDevice() with the appropiate device. Otherwise
/// the default capturing device will be used.
///
/// It is important to note that the audio capture happens in a
/// separate thread, so that it doesn't block the rest of the
/// program. In particular, the onProcessSamples virtual function
/// (but not onStart and not onStop) will be called
/// from this separate thread. It is important to keep this in
/// mind, because you may have to take care of synchronization
/// issues if you share data between threads.
///
/// Usage example:
/// \code
/// class CustomRecorder : public sf::SoundRecorder
/// {
/// virtual bool onStart() // optional
/// {
/// // Initialize whatever has to be done before the capture starts
/// ...
///
/// // Return true to start playing
/// return true;
/// }
///
/// virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount)
/// {
/// // Do something with the new chunk of samples (store them, send them, ...)
/// ...
///
/// // Return true to continue playing
/// return true;
/// }
///
/// virtual void onStop() // optional
/// {
/// // Clean up whatever has to be done after the capture ends
/// ...
/// }
/// }
///
/// // Usage
/// if (CustomRecorder::isAvailable())
/// {
/// CustomRecorder recorder;
///
/// if (!recorder.start())
/// return -1;
///
/// ...
/// recorder.stop();
/// }
/// \endcode
///
/// \see sf::SoundBufferRecorder
///
////////////////////////////////////////////////////////////

572
include/SFML/Audio/SoundSource.hpp
View file

@ -1,286 +1,286 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDSOURCE_HPP
#define SFML_SOUNDSOURCE_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Vector3.hpp>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Base class defining a sound's properties
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundSource
{
public :
////////////////////////////////////////////////////////////
/// \brief Enumeration of the sound source states
///
////////////////////////////////////////////////////////////
enum Status
{
Stopped, ///< Sound is not playing
Paused, ///< Sound is paused
Playing ///< Sound is playing
};
////////////////////////////////////////////////////////////
/// \brief Copy constructor
///
/// \param copy Instance to copy
///
////////////////////////////////////////////////////////////
SoundSource(const SoundSource& copy);
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundSource();
////////////////////////////////////////////////////////////
/// \brief Set the pitch of the sound
///
/// The pitch represents the perceived fundamental frequency
/// of a sound; thus you can make a sound more acute or grave
/// by changing its pitch. A side effect of changing the pitch
/// is to modify the playing speed of the sound as well.
/// The default value for the pitch is 1.
///
/// \param pitch New pitch to apply to the sound
///
/// \see getPitch
///
////////////////////////////////////////////////////////////
void setPitch(float pitch);
////////////////////////////////////////////////////////////
/// \brief Set the volume of the sound
///
/// The volume is a value between 0 (mute) and 100 (full volume).
/// The default value for the volume is 100.
///
/// \param volume Volume of the sound
///
/// \see getVolume
///
////////////////////////////////////////////////////////////
void setVolume(float volume);
////////////////////////////////////////////////////////////
/// \brief Set the 3D position of the sound in the audio scene
///
/// Only sounds with one channel (mono sounds) can be
/// spatialized.
/// The default position of a sound is (0, 0, 0).
///
/// \param x X coordinate of the position of the sound in the scene
/// \param y Y coordinate of the position of the sound in the scene
/// \param z Z coordinate of the position of the sound in the scene
///
/// \see getPosition
///
////////////////////////////////////////////////////////////
void setPosition(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the 3D position of the sound in the audio scene
///
/// Only sounds with one channel (mono sounds) can be
/// spatialized.
/// The default position of a sound is (0, 0, 0).
///
/// \param position Position of the sound in the scene
///
/// \see getPosition
///
////////////////////////////////////////////////////////////
void setPosition(const Vector3f& position);
////////////////////////////////////////////////////////////
/// \brief Make the sound's position relative to the listener or absolute
///
/// Making a sound relative to the listener will ensure that it will always
/// be played the same way regardless the position of the listener.
/// This can be useful for non-spatialized sounds, sounds that are
/// produced by the listener, or sounds attached to it.
/// The default value is false (position is absolute).
///
/// \param relative True to set the position relative, false to set it absolute
///
/// \see isRelativeToListener
///
////////////////////////////////////////////////////////////
void setRelativeToListener(bool relative);
////////////////////////////////////////////////////////////
/// \brief Set the minimum distance of the sound
///
/// The "minimum distance" of a sound is the maximum
/// distance at which it is heard at its maximum volume. Further
/// than the minimum distance, it will start to fade out according
/// to its attenuation factor. A value of 0 ("inside the head
/// of the listener") is an invalid value and is forbidden.
/// The default value of the minimum distance is 1.
///
/// \param distance New minimum distance of the sound
///
/// \see getMinDistance, setAttenuation
///
////////////////////////////////////////////////////////////
void setMinDistance(float distance);
////////////////////////////////////////////////////////////
/// \brief Set the attenuation factor of the sound
///
/// The attenuation is a multiplicative factor which makes
/// the sound more or less loud according to its distance
/// from the listener. An attenuation of 0 will produce a
/// non-attenuated sound, i.e. its volume will always be the same
/// whether it is heard from near or from far. On the other hand,
/// an attenuation value such as 100 will make the sound fade out
/// very quickly as it gets further from the listener.
/// The default value of the attenuation is 1.
///
/// \param attenuation New attenuation factor of the sound
///
/// \see getAttenuation, setMinDistance
///
////////////////////////////////////////////////////////////
void setAttenuation(float attenuation);
////////////////////////////////////////////////////////////
/// \brief Get the pitch of the sound
///
/// \return Pitch of the sound
///
/// \see setPitch
///
////////////////////////////////////////////////////////////
float getPitch() const;
////////////////////////////////////////////////////////////
/// \brief Get the volume of the sound
///
/// \return Volume of the sound, in the range [0, 100]
///
/// \see setVolume
///
////////////////////////////////////////////////////////////
float getVolume() const;
////////////////////////////////////////////////////////////
/// \brief Get the 3D position of the sound in the audio scene
///
/// \return Position of the sound
///
/// \see setPosition
///
////////////////////////////////////////////////////////////
Vector3f getPosition() const;
////////////////////////////////////////////////////////////
/// \brief Tell whether the sound's position is relative to the
/// listener or is absolute
///
/// \return True if the position is relative, false if it's absolute
///
/// \see setRelativeToListener
///
////////////////////////////////////////////////////////////
bool isRelativeToListener() const;
////////////////////////////////////////////////////////////
/// \brief Get the minimum distance of the sound
///
/// \return Minimum distance of the sound
///
/// \see setMinDistance, getAttenuation
///
////////////////////////////////////////////////////////////
float getMinDistance() const;
////////////////////////////////////////////////////////////
/// \brief Get the attenuation factor of the sound
///
/// \return Attenuation factor of the sound
///
/// \see setAttenuation, getMinDistance
///
////////////////////////////////////////////////////////////
float getAttenuation() const;
protected :
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
/// This constructor is meant ot be called by derived classes only.
///
////////////////////////////////////////////////////////////
SoundSource();
////////////////////////////////////////////////////////////
/// \brief Get the current status of the sound (stopped, paused, playing)
///
/// \return Current status of the sound
///
////////////////////////////////////////////////////////////
Status getStatus() const;
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
unsigned int m_source; ///< OpenAL source identifier
};
} // namespace sf
#endif // SFML_SOUNDSOURCE_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundSource
/// \ingroup audio
///
/// sf::SoundSource is not meant to be used directly, it
/// only serves as a common base for all audio objects
/// that can live in the audio environment.
///
/// It defines several properties for the sound: pitch,
/// volume, position, attenuation, etc. All of them can be
/// changed at any time with no impact on performances.
///
/// \see sf::Sound, sf::SoundStream
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDSOURCE_HPP
#define SFML_SOUNDSOURCE_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/System/Vector3.hpp>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Base class defining a sound's properties
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundSource
{
public:
////////////////////////////////////////////////////////////
/// \brief Enumeration of the sound source states
///
////////////////////////////////////////////////////////////
enum Status
{
Stopped, ///< Sound is not playing
Paused, ///< Sound is paused
Playing ///< Sound is playing
};
////////////////////////////////////////////////////////////
/// \brief Copy constructor
///
/// \param copy Instance to copy
///
////////////////////////////////////////////////////////////
SoundSource(const SoundSource& copy);
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundSource();
////////////////////////////////////////////////////////////
/// \brief Set the pitch of the sound
///
/// The pitch represents the perceived fundamental frequency
/// of a sound; thus you can make a sound more acute or grave
/// by changing its pitch. A side effect of changing the pitch
/// is to modify the playing speed of the sound as well.
/// The default value for the pitch is 1.
///
/// \param pitch New pitch to apply to the sound
///
/// \see getPitch
///
////////////////////////////////////////////////////////////
void setPitch(float pitch);
////////////////////////////////////////////////////////////
/// \brief Set the volume of the sound
///
/// The volume is a value between 0 (mute) and 100 (full volume).
/// The default value for the volume is 100.
///
/// \param volume Volume of the sound
///
/// \see getVolume
///
////////////////////////////////////////////////////////////
void setVolume(float volume);
////////////////////////////////////////////////////////////
/// \brief Set the 3D position of the sound in the audio scene
///
/// Only sounds with one channel (mono sounds) can be
/// spatialized.
/// The default position of a sound is (0, 0, 0).
///
/// \param x X coordinate of the position of the sound in the scene
/// \param y Y coordinate of the position of the sound in the scene
/// \param z Z coordinate of the position of the sound in the scene
///
/// \see getPosition
///
////////////////////////////////////////////////////////////
void setPosition(float x, float y, float z);
////////////////////////////////////////////////////////////
/// \brief Set the 3D position of the sound in the audio scene
///
/// Only sounds with one channel (mono sounds) can be
/// spatialized.
/// The default position of a sound is (0, 0, 0).
///
/// \param position Position of the sound in the scene
///
/// \see getPosition
///
////////////////////////////////////////////////////////////
void setPosition(const Vector3f& position);
////////////////////////////////////////////////////////////
/// \brief Make the sound's position relative to the listener or absolute
///
/// Making a sound relative to the listener will ensure that it will always
/// be played the same way regardless the position of the listener.
/// This can be useful for non-spatialized sounds, sounds that are
/// produced by the listener, or sounds attached to it.
/// The default value is false (position is absolute).
///
/// \param relative True to set the position relative, false to set it absolute
///
/// \see isRelativeToListener
///
////////////////////////////////////////////////////////////
void setRelativeToListener(bool relative);
////////////////////////////////////////////////////////////
/// \brief Set the minimum distance of the sound
///
/// The "minimum distance" of a sound is the maximum
/// distance at which it is heard at its maximum volume. Further
/// than the minimum distance, it will start to fade out according
/// to its attenuation factor. A value of 0 ("inside the head
/// of the listener") is an invalid value and is forbidden.
/// The default value of the minimum distance is 1.
///
/// \param distance New minimum distance of the sound
///
/// \see getMinDistance, setAttenuation
///
////////////////////////////////////////////////////////////
void setMinDistance(float distance);
////////////////////////////////////////////////////////////
/// \brief Set the attenuation factor of the sound
///
/// The attenuation is a multiplicative factor which makes
/// the sound more or less loud according to its distance
/// from the listener. An attenuation of 0 will produce a
/// non-attenuated sound, i.e. its volume will always be the same
/// whether it is heard from near or from far. On the other hand,
/// an attenuation value such as 100 will make the sound fade out
/// very quickly as it gets further from the listener.
/// The default value of the attenuation is 1.
///
/// \param attenuation New attenuation factor of the sound
///
/// \see getAttenuation, setMinDistance
///
////////////////////////////////////////////////////////////
void setAttenuation(float attenuation);
////////////////////////////////////////////////////////////
/// \brief Get the pitch of the sound
///
/// \return Pitch of the sound
///
/// \see setPitch
///
////////////////////////////////////////////////////////////
float getPitch() const;
////////////////////////////////////////////////////////////
/// \brief Get the volume of the sound
///
/// \return Volume of the sound, in the range [0, 100]
///
/// \see setVolume
///
////////////////////////////////////////////////////////////
float getVolume() const;
////////////////////////////////////////////////////////////
/// \brief Get the 3D position of the sound in the audio scene
///
/// \return Position of the sound
///
/// \see setPosition
///
////////////////////////////////////////////////////////////
Vector3f getPosition() const;
////////////////////////////////////////////////////////////
/// \brief Tell whether the sound's position is relative to the
/// listener or is absolute
///
/// \return True if the position is relative, false if it's absolute
///
/// \see setRelativeToListener
///
////////////////////////////////////////////////////////////
bool isRelativeToListener() const;
////////////////////////////////////////////////////////////
/// \brief Get the minimum distance of the sound
///
/// \return Minimum distance of the sound
///
/// \see setMinDistance, getAttenuation
///
////////////////////////////////////////////////////////////
float getMinDistance() const;
////////////////////////////////////////////////////////////
/// \brief Get the attenuation factor of the sound
///
/// \return Attenuation factor of the sound
///
/// \see setAttenuation, getMinDistance
///
////////////////////////////////////////////////////////////
float getAttenuation() const;
protected:
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
/// This constructor is meant ot be called by derived classes only.
///
////////////////////////////////////////////////////////////
SoundSource();
////////////////////////////////////////////////////////////
/// \brief Get the current status of the sound (stopped, paused, playing)
///
/// \return Current status of the sound
///
////////////////////////////////////////////////////////////
Status getStatus() const;
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
unsigned int m_source; ///< OpenAL source identifier
};
} // namespace sf
#endif // SFML_SOUNDSOURCE_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundSource
/// \ingroup audio
///
/// sf::SoundSource is not meant to be used directly, it
/// only serves as a common base for all audio objects
/// that can live in the audio environment.
///
/// It defines several properties for the sound: pitch,
/// volume, position, attenuation, etc. All of them can be
/// changed at any time with no impact on performances.
///
/// \see sf::Sound, sf::SoundStream
///
////////////////////////////////////////////////////////////

772
include/SFML/Audio/SoundStream.hpp
View file

@ -1,386 +1,386 @@
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDSTREAM_HPP
#define SFML_SOUNDSTREAM_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/Audio/SoundSource.hpp>
#include <SFML/System/Thread.hpp>
#include <SFML/System/Time.hpp>
#include <SFML/System/Mutex.hpp>
#include <cstdlib>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Abstract base class for streamed audio sources
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundStream : public SoundSource
{
public :
////////////////////////////////////////////////////////////
/// \brief Structure defining a chunk of audio data to stream
///
////////////////////////////////////////////////////////////
struct Chunk
{
const Int16* samples; ///< Pointer to the audio samples
std::size_t sampleCount; ///< Number of samples pointed by Samples
};
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundStream();
////////////////////////////////////////////////////////////
/// \brief Start or resume playing the audio stream
///
/// This function starts the stream if it was stopped, resumes
/// it if it was paused, and restarts it from the beginning if
/// it was already playing.
/// This function uses its own thread so that it doesn't block
/// the rest of the program while the stream is played.
///
/// \see pause, stop
///
////////////////////////////////////////////////////////////
void play();
////////////////////////////////////////////////////////////
/// \brief Pause the audio stream
///
/// This function pauses the stream if it was playing,
/// otherwise (stream already paused or stopped) it has no effect.
///
/// \see play, stop
///
////////////////////////////////////////////////////////////
void pause();
////////////////////////////////////////////////////////////
/// \brief Stop playing the audio stream
///
/// This function stops the stream if it was playing or paused,
/// and does nothing if it was already stopped.
/// It also resets the playing position (unlike pause()).
///
/// \see play, pause
///
////////////////////////////////////////////////////////////
void stop();
////////////////////////////////////////////////////////////
/// \brief Return the number of channels of the stream
///
/// 1 channel means a mono sound, 2 means stereo, etc.
///
/// \return Number of channels
///
////////////////////////////////////////////////////////////
unsigned int getChannelCount() const;
////////////////////////////////////////////////////////////
/// \brief Get the stream sample rate of the stream
///
/// The sample rate is the number of audio samples played per
/// second. The higher, the better the quality.
///
/// \return Sample rate, in number of samples per second
///
////////////////////////////////////////////////////////////
unsigned int getSampleRate() const;
////////////////////////////////////////////////////////////
/// \brief Get the current status of the stream (stopped, paused, playing)
///
/// \return Current status
///
////////////////////////////////////////////////////////////
Status getStatus() const;
////////////////////////////////////////////////////////////
/// \brief Change the current playing position of the stream
///
/// The playing position can be changed when the stream is
/// either paused or playing. Changing the playing position
/// when the stream is stopped has no effect, since playing
/// the stream would reset its position.
///
/// \param timeOffset New playing position, from the beginning of the stream
///
/// \see getPlayingOffset
///
////////////////////////////////////////////////////////////
void setPlayingOffset(Time timeOffset);
////////////////////////////////////////////////////////////
/// \brief Get the current playing position of the stream
///
/// \return Current playing position, from the beginning of the stream
///
/// \see setPlayingOffset
///
////////////////////////////////////////////////////////////
Time getPlayingOffset() const;
////////////////////////////////////////////////////////////
/// \brief Set whether or not the stream should loop after reaching the end
///
/// If set, the stream will restart from beginning after
/// reaching the end and so on, until it is stopped or
/// setLoop(false) is called.
/// The default looping state for streams is false.
///
/// \param loop True to play in loop, false to play once
///
/// \see getLoop
///
////////////////////////////////////////////////////////////
void setLoop(bool loop);
////////////////////////////////////////////////////////////
/// \brief Tell whether or not the stream is in loop mode
///
/// \return True if the stream is looping, false otherwise
///
/// \see setLoop
///
////////////////////////////////////////////////////////////
bool getLoop() const;
protected :
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
/// This constructor is only meant to be called by derived classes.
///
////////////////////////////////////////////////////////////
SoundStream();
////////////////////////////////////////////////////////////
/// \brief Define the audio stream parameters
///
/// This function must be called by derived classes as soon
/// as they know the audio settings of the stream to play.
/// Any attempt to manipulate the stream (play(), ...) before
/// calling this function will fail.
/// It can be called multiple times if the settings of the
/// audio stream change, but only when the stream is stopped.
///
/// \param channelCount Number of channels of the stream
/// \param sampleRate Sample rate, in samples per second
///
////////////////////////////////////////////////////////////
void initialize(unsigned int channelCount, unsigned int sampleRate);
////////////////////////////////////////////////////////////
/// \brief Request a new chunk of audio samples from the stream source
///
/// This function must be overriden by derived classes to provide
/// the audio samples to play. It is called continuously by the
/// streaming loop, in a separate thread.
/// The source can choose to stop the streaming loop at any time, by
/// returning false to the caller.
/// If you return true (i.e. continue streaming) it is important that
/// the returned array of samples is not empty; this would stop the stream
/// due to an internal limitation.
///
/// \param data Chunk of data to fill
///
/// \return True to continue playback, false to stop
///
////////////////////////////////////////////////////////////
virtual bool onGetData(Chunk& data) = 0;
////////////////////////////////////////////////////////////
/// \brief Change the current playing position in the stream source
///
/// This function must be overriden by derived classes to
/// allow random seeking into the stream source.
///
/// \param timeOffset New playing position, relative to the beginning of the stream
///
////////////////////////////////////////////////////////////
virtual void onSeek(Time timeOffset) = 0;
private :
////////////////////////////////////////////////////////////
/// \brief Function called as the entry point of the thread
///
/// This function starts the streaming loop, and returns
/// only when the sound is stopped.
///
////////////////////////////////////////////////////////////
void streamData();
////////////////////////////////////////////////////////////
/// \brief Fill a new buffer with audio samples, and append
/// it to the playing queue
///
/// This function is called as soon as a buffer has been fully
/// consumed; it fills it again and inserts it back into the
/// playing queue.
///
/// \param bufferNum Number of the buffer to fill (in [0, BufferCount])
///
/// \return True if the stream source has requested to stop, false otherwise
///
////////////////////////////////////////////////////////////
bool fillAndPushBuffer(unsigned int bufferNum);
////////////////////////////////////////////////////////////
/// \brief Fill the audio buffers and put them all into the playing queue
///
/// This function is called when playing starts and the
/// playing queue is empty.
///
/// \return True if the derived class has requested to stop, false otherwise
///
////////////////////////////////////////////////////////////
bool fillQueue();
////////////////////////////////////////////////////////////
/// \brief Clear all the audio buffers and empty the playing queue
///
/// This function is called when the stream is stopped.
///
////////////////////////////////////////////////////////////
void clearQueue();
enum
{
BufferCount = 3 ///< Number of audio buffers used by the streaming loop
};
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
Thread m_thread; ///< Thread running the background tasks
mutable Mutex m_threadMutex; ///< Thread mutex
Status m_threadStartState; ///< State the thread starts in (Playing, Paused, Stopped)
bool m_isStreaming; ///< Streaming state (true = playing, false = stopped)
unsigned int m_buffers[BufferCount]; ///< Sound buffers used to store temporary audio data
unsigned int m_channelCount; ///< Number of channels (1 = mono, 2 = stereo, ...)
unsigned int m_sampleRate; ///< Frequency (samples / second)
Uint32 m_format; ///< Format of the internal sound buffers
bool m_loop; ///< Loop flag (true to loop, false to play once)
Uint64 m_samplesProcessed; ///< Number of buffers processed since beginning of the stream
bool m_endBuffers[BufferCount]; ///< Each buffer is marked as "end buffer" or not, for proper duration calculation
};
} // namespace sf
#endif // SFML_SOUNDSTREAM_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundStream
/// \ingroup audio
///
/// Unlike audio buffers (see sf::SoundBuffer), audio streams
/// are never completely loaded in memory. Instead, the audio
/// data is acquired continuously while the stream is playing.
/// This behaviour allows to play a sound with no loading delay,
/// and keeps the memory consumption very low.
///
/// Sound sources that need to be streamed are usually big files
/// (compressed audio musics that would eat hundreds of MB in memory)
/// or files that would take a lot of time to be received
/// (sounds played over the network).
///
/// sf::SoundStream is a base class that doesn't care about the
/// stream source, which is left to the derived class. SFML provides
/// a built-in specialization for big files (see sf::Music).
/// No network stream source is provided, but you can write your own
/// by combining this class with the network module.
///
/// A derived class has to override two virtual functions:
/// \li onGetData fills a new chunk of audio data to be played
/// \li onSeek changes the current playing position in the source
///
/// It is important to note that each SoundStream is played in its
/// own separate thread, so that the streaming loop doesn't block the
/// rest of the program. In particular, the OnGetData and OnSeek
/// virtual functions may sometimes be called from this separate thread.
/// It is important to keep this in mind, because you may have to take
/// care of synchronization issues if you share data between threads.
///
/// Usage example:
/// \code
/// class CustomStream : public sf::SoundStream
/// {
/// public :
///
/// bool open(const std::string& location)
/// {
/// // Open the source and get audio settings
/// ...
/// unsigned int channelCount = ...;
/// unsigned int sampleRate = ...;
///
/// // Initialize the stream -- important!
/// initialize(channelCount, sampleRate);
/// }
///
/// private :
///
/// virtual bool onGetData(Chunk& data)
/// {
/// // Fill the chunk with audio data from the stream source
/// // (note: must not be empty if you want to continue playing)
/// data.samples = ...;
/// data.sampleCount = ...;
///
/// // Return true to continue playing
/// return true;
/// }
///
/// virtual void onSeek(Uint32 timeOffset)
/// {
/// // Change the current position in the stream source
/// ...
/// }
/// }
///
/// // Usage
/// CustomStream stream;
/// stream.open("path/to/stream");
/// stream.play();
/// \endcode
///
/// \see sf::Music
///
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
//
// 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_SOUNDSTREAM_HPP
#define SFML_SOUNDSTREAM_HPP
////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////
#include <SFML/Audio/Export.hpp>
#include <SFML/Audio/SoundSource.hpp>
#include <SFML/System/Thread.hpp>
#include <SFML/System/Time.hpp>
#include <SFML/System/Mutex.hpp>
#include <cstdlib>
namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Abstract base class for streamed audio sources
///
////////////////////////////////////////////////////////////
class SFML_AUDIO_API SoundStream : public SoundSource
{
public:
////////////////////////////////////////////////////////////
/// \brief Structure defining a chunk of audio data to stream
///
////////////////////////////////////////////////////////////
struct Chunk
{
const Int16* samples; ///< Pointer to the audio samples
std::size_t sampleCount; ///< Number of samples pointed by Samples
};
////////////////////////////////////////////////////////////
/// \brief Destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundStream();
////////////////////////////////////////////////////////////
/// \brief Start or resume playing the audio stream
///
/// This function starts the stream if it was stopped, resumes
/// it if it was paused, and restarts it from the beginning if
/// it was already playing.
/// This function uses its own thread so that it doesn't block
/// the rest of the program while the stream is played.
///
/// \see pause, stop
///
////////////////////////////////////////////////////////////
void play();
////////////////////////////////////////////////////////////
/// \brief Pause the audio stream
///
/// This function pauses the stream if it was playing,
/// otherwise (stream already paused or stopped) it has no effect.
///
/// \see play, stop
///
////////////////////////////////////////////////////////////
void pause();
////////////////////////////////////////////////////////////
/// \brief Stop playing the audio stream
///
/// This function stops the stream if it was playing or paused,
/// and does nothing if it was already stopped.
/// It also resets the playing position (unlike pause()).
///
/// \see play, pause
///
////////////////////////////////////////////////////////////
void stop();
////////////////////////////////////////////////////////////
/// \brief Return the number of channels of the stream
///
/// 1 channel means a mono sound, 2 means stereo, etc.
///
/// \return Number of channels
///
////////////////////////////////////////////////////////////
unsigned int getChannelCount() const;
////////////////////////////////////////////////////////////
/// \brief Get the stream sample rate of the stream
///
/// The sample rate is the number of audio samples played per
/// second. The higher, the better the quality.
///
/// \return Sample rate, in number of samples per second
///
////////////////////////////////////////////////////////////
unsigned int getSampleRate() const;
////////////////////////////////////////////////////////////
/// \brief Get the current status of the stream (stopped, paused, playing)
///
/// \return Current status
///
////////////////////////////////////////////////////////////
Status getStatus() const;
////////////////////////////////////////////////////////////
/// \brief Change the current playing position of the stream
///
/// The playing position can be changed when the stream is
/// either paused or playing. Changing the playing position
/// when the stream is stopped has no effect, since playing
/// the stream would reset its position.
///
/// \param timeOffset New playing position, from the beginning of the stream
///
/// \see getPlayingOffset
///
////////////////////////////////////////////////////////////
void setPlayingOffset(Time timeOffset);
////////////////////////////////////////////////////////////
/// \brief Get the current playing position of the stream
///
/// \return Current playing position, from the beginning of the stream
///
/// \see setPlayingOffset
///
////////////////////////////////////////////////////////////
Time getPlayingOffset() const;
////////////////////////////////////////////////////////////
/// \brief Set whether or not the stream should loop after reaching the end
///
/// If set, the stream will restart from beginning after
/// reaching the end and so on, until it is stopped or
/// setLoop(false) is called.
/// The default looping state for streams is false.
///
/// \param loop True to play in loop, false to play once
///
/// \see getLoop
///
////////////////////////////////////////////////////////////
void setLoop(bool loop);
////////////////////////////////////////////////////////////
/// \brief Tell whether or not the stream is in loop mode
///
/// \return True if the stream is looping, false otherwise
///
/// \see setLoop
///
////////////////////////////////////////////////////////////
bool getLoop() const;
protected:
////////////////////////////////////////////////////////////
/// \brief Default constructor
///
/// This constructor is only meant to be called by derived classes.
///
////////////////////////////////////////////////////////////
SoundStream();
////////////////////////////////////////////////////////////
/// \brief Define the audio stream parameters
///
/// This function must be called by derived classes as soon
/// as they know the audio settings of the stream to play.
/// Any attempt to manipulate the stream (play(), ...) before
/// calling this function will fail.
/// It can be called multiple times if the settings of the
/// audio stream change, but only when the stream is stopped.
///
/// \param channelCount Number of channels of the stream
/// \param sampleRate Sample rate, in samples per second
///
////////////////////////////////////////////////////////////
void initialize(unsigned int channelCount, unsigned int sampleRate);
////////////////////////////////////////////////////////////
/// \brief Request a new chunk of audio samples from the stream source
///
/// This function must be overriden by derived classes to provide
/// the audio samples to play. It is called continuously by the
/// streaming loop, in a separate thread.
/// The source can choose to stop the streaming loop at any time, by
/// returning false to the caller.
/// If you return true (i.e. continue streaming) it is important that
/// the returned array of samples is not empty; this would stop the stream
/// due to an internal limitation.
///
/// \param data Chunk of data to fill
///
/// \return True to continue playback, false to stop
///
////////////////////////////////////////////////////////////
virtual bool onGetData(Chunk& data) = 0;
////////////////////////////////////////////////////////////
/// \brief Change the current playing position in the stream source
///
/// This function must be overriden by derived classes to
/// allow random seeking into the stream source.
///
/// \param timeOffset New playing position, relative to the beginning of the stream
///
////////////////////////////////////////////////////////////
virtual void onSeek(Time timeOffset) = 0;
private:
////////////////////////////////////////////////////////////
/// \brief Function called as the entry point of the thread
///
/// This function starts the streaming loop, and returns
/// only when the sound is stopped.
///
////////////////////////////////////////////////////////////
void streamData();
////////////////////////////////////////////////////////////
/// \brief Fill a new buffer with audio samples, and append
/// it to the playing queue
///
/// This function is called as soon as a buffer has been fully
/// consumed; it fills it again and inserts it back into the
/// playing queue.
///
/// \param bufferNum Number of the buffer to fill (in [0, BufferCount])
///
/// \return True if the stream source has requested to stop, false otherwise
///
////////////////////////////////////////////////////////////
bool fillAndPushBuffer(unsigned int bufferNum);
////////////////////////////////////////////////////////////
/// \brief Fill the audio buffers and put them all into the playing queue
///
/// This function is called when playing starts and the
/// playing queue is empty.
///
/// \return True if the derived class has requested to stop, false otherwise
///
////////////////////////////////////////////////////////////
bool fillQueue();
////////////////////////////////////////////////////////////
/// \brief Clear all the audio buffers and empty the playing queue
///
/// This function is called when the stream is stopped.
///
////////////////////////////////////////////////////////////
void clearQueue();
enum
{
BufferCount = 3 ///< Number of audio buffers used by the streaming loop
};
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
Thread m_thread; ///< Thread running the background tasks
mutable Mutex m_threadMutex; ///< Thread mutex
Status m_threadStartState; ///< State the thread starts in (Playing, Paused, Stopped)
bool m_isStreaming; ///< Streaming state (true = playing, false = stopped)
unsigned int m_buffers[BufferCount]; ///< Sound buffers used to store temporary audio data
unsigned int m_channelCount; ///< Number of channels (1 = mono, 2 = stereo, ...)
unsigned int m_sampleRate; ///< Frequency (samples / second)
Uint32 m_format; ///< Format of the internal sound buffers
bool m_loop; ///< Loop flag (true to loop, false to play once)
Uint64 m_samplesProcessed; ///< Number of buffers processed since beginning of the stream
bool m_endBuffers[BufferCount]; ///< Each buffer is marked as "end buffer" or not, for proper duration calculation
};
} // namespace sf
#endif // SFML_SOUNDSTREAM_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundStream
/// \ingroup audio
///
/// Unlike audio buffers (see sf::SoundBuffer), audio streams
/// are never completely loaded in memory. Instead, the audio
/// data is acquired continuously while the stream is playing.
/// This behaviour allows to play a sound with no loading delay,
/// and keeps the memory consumption very low.
///
/// Sound sources that need to be streamed are usually big files
/// (compressed audio musics that would eat hundreds of MB in memory)
/// or files that would take a lot of time to be received
/// (sounds played over the network).
///
/// sf::SoundStream is a base class that doesn't care about the
/// stream source, which is left to the derived class. SFML provides
/// a built-in specialization for big files (see sf::Music).
/// No network stream source is provided, but you can write your own
/// by combining this class with the network module.
///
/// A derived class has to override two virtual functions:
/// \li onGetData fills a new chunk of audio data to be played
/// \li onSeek changes the current playing position in the source
///
/// It is important to note that each SoundStream is played in its
/// own separate thread, so that the streaming loop doesn't block the
/// rest of the program. In particular, the OnGetData and OnSeek
/// virtual functions may sometimes be called from this separate thread.
/// It is important to keep this in mind, because you may have to take
/// care of synchronization issues if you share data between threads.
///
/// Usage example:
/// \code
/// class CustomStream : public sf::SoundStream
/// {
/// public:
///
/// bool open(const std::string& location)
/// {
/// // Open the source and get audio settings
/// ...
/// unsigned int channelCount = ...;
/// unsigned int sampleRate = ...;
///
/// // Initialize the stream -- important!
/// initialize(channelCount, sampleRate);
/// }
///
/// private:
///
/// virtual bool onGetData(Chunk& data)
/// {
/// // Fill the chunk with audio data from the stream source
/// // (note: must not be empty if you want to continue playing)
/// data.samples = ...;
/// data.sampleCount = ...;
///
/// // Return true to continue playing
/// return true;
/// }
///
/// virtual void onSeek(Uint32 timeOffset)
/// {
/// // Change the current position in the stream source
/// ...
/// }
/// }
///
/// // Usage
/// CustomStream stream;
/// stream.open("path/to/stream");
/// stream.play();
/// \endcode
///
/// \see sf::Music
///
////////////////////////////////////////////////////////////