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

Improved the API documentation in the audio module

Browse source 
git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1251 4e206d99-4929-0410-ac5d-dfc041789085
This commit is contained in:
LaurentGom 2009-10-29 09:32:17 +00:00
parent 6df95868d0
commit 33f54ad6cd
30 changed files with 759 additions and 410 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -35,81 +35,112 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Listener is a global interface for defining the audio
/// listener properties ; the audio listener is the point in
/// the scene from where all the sounds are heard
/// \brief The audio listener is the point in the scene
/// from where all the sounds are heard
///
////////////////////////////////////////////////////////////
class SFML_API Listener
{
public :
////////////////////////////////////////////////////////////
/// Change the global volume of all the sounds.
/// The default volume is 100
/// \brief Change the global volume of all the sounds and musics
///
/// \param volume : New global volume, in the range [0, 100]
/// 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);
////////////////////////////////////////////////////////////
/// Get the current value of the global volume of all the sounds
/// \brief Get the current value of the global volume
///
/// \return Current global volume, in the range [0, 100]
///
/// \see SetGlobalVolume
///
////////////////////////////////////////////////////////////
static float GetGlobalVolume();
////////////////////////////////////////////////////////////
/// Change the position of the listener (take 3 values).
/// The default position is (0, 0, 0)
/// \brief Set the position of the listener in the scene
///
/// \param x, y, z : Position of the listener in the world
/// 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);
////////////////////////////////////////////////////////////
/// Change the position of the listener (take a 3D vector).
/// The default position is (0, 0, 0)
/// \brief Set the position of the listener in the scene
///
/// \param position : Position of the listener in the world
/// The default listener's position is (0, 0, 0).
///
/// \param position New listener's position
///
/// \see GetPosition, SetDirection
///
////////////////////////////////////////////////////////////
static void SetPosition(const Vector3f& position);
////////////////////////////////////////////////////////////
/// Get the current position of the listener
/// \brief Get the current position of the listener in the scene
///
/// \return Position of the listener in the world
/// \return Listener's position
///
/// \see SetPosition
///
////////////////////////////////////////////////////////////
static Vector3f GetPosition();
////////////////////////////////////////////////////////////
/// Change the orientation of the listener (take 3 values);
/// the direction does not need to be normalized.
/// The default direction is (0, 0, -1)
/// \brief Set the orientation of the listener in the scene
///
/// \param x, y, z : Orientation of the listener
/// The orientation defines the 3D axes of the listener
/// (left, up, front) in the scene. The orientation vector
/// doesn't have to be normalized.
/// The default listener's orientation is (0, 0, -1).
///
/// \param x X coordinate of the listener's orientation
/// \param y Y coordinate of the listener's orientation
/// \param z Z coordinate of the listener's orientation
///
/// \see GetDirection, SetPosition
///
////////////////////////////////////////////////////////////
static void SetDirection(float x, float y, float z);
////////////////////////////////////////////////////////////
/// Change the orientation of the listener (take a 3D vector);
/// the direction does not need to be normalized.
/// The default direction is (0, 0, -1)
/// \brief Set the orientation of the listener in the scene
///
/// \param direction : Orientation of the listener
/// The orientation defines the 3D axes of the listener
/// (left, up, front) in the scene. The orientation vector
/// doesn't have to be normalized.
/// The default listener's orientation is (0, 0, -1).
///
/// \param direction New listener's orientation
///
/// \see GetDirection, SetPosition
///
////////////////////////////////////////////////////////////
static void SetDirection(const Vector3f& direction);
////////////////////////////////////////////////////////////
/// Get the current orientation of the listener.
/// \brief Get the current orientation of the listener in the scene
///
/// \return Current direction of the listener
/// \return Listener's orientation
///
/// \see SetDirection
///
////////////////////////////////////////////////////////////
static Vector3f GetDirection();
@ -119,3 +150,34 @@ public :
#endif // SFML_LISTENER_HPP
////////////////////////////////////////////////////////////
/// \class sf::Listener
///
/// 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 and direction),
/// 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 instanciated.
///
/// 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
///
////////////////////////////////////////////////////////////

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

@ -36,17 +36,23 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Specialized SoundRecorder which saves the captured
/// audio data into a sound buffer
/// \brief Specialized SoundRecorder which stores the captured
/// audio data into a sound buffer
///
////////////////////////////////////////////////////////////
class SFML_API SoundBufferRecorder : public SoundRecorder
{
public :
////////////////////////////////////////////////////////////
/// Get the sound buffer containing the captured audio data
/// \brief Get the sound buffer containing the captured audio data
///
/// \return Constant reference to the sound buffer
/// 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;
@ -54,19 +60,26 @@ public :
private :
////////////////////////////////////////////////////////////
/// /see SoundBuffer::OnStart
/// \brief Start capturing audio data
///
/// \return True to start the capture, or false to abort it
///
////////////////////////////////////////////////////////////
virtual bool OnStart();
////////////////////////////////////////////////////////////
/// /see SoundBuffer::OnProcessSamples
/// \brief Process a new chunk of recorded samples
///
/// \param samples Pointer to the new chunk of recorded samples
/// \param samplesCount 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 samplesCount);
////////////////////////////////////////////////////////////
/// /see SoundBuffer::OnStop
/// \brief Stop capturing audio data
///
////////////////////////////////////////////////////////////
virtual void OnStop();
@ -81,3 +94,41 @@ private :
} // namespace sf
#endif // SFML_SOUNDBUFFERRECORDER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundBufferRecorder
///
/// 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 CanCapture() function
/// before using this class (see sf::SoundRecorder for more details
/// about this).
///
/// Usage example:
/// \code
/// if (SoundBufferRecorder::CanCapture())
/// {
/// // Record some audio data
/// 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
///
////////////////////////////////////////////////////////////

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

@ -35,48 +35,65 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// SoundRecorder is an interface for capturing sound data,
/// it is meant to be used as a base class
/// \brief Abstract base class for capturing sound data
///
////////////////////////////////////////////////////////////
class SFML_API SoundRecorder : private Thread
{
public :
////////////////////////////////////////////////////////////
/// Virtual destructor
/// \brief destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundRecorder();
////////////////////////////////////////////////////////////
/// Start the capture.
/// Warning : only one capture can happen at the same time
/// \brief Start the capture
///
/// \param sampleRate : Sound frequency (the more samples, the higher the quality)
/// (44100 by default = CD quality)
/// 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.
///
/// \param sampleRate Desired capture rate, in number of samples per second
///
/// \see Stop
///
////////////////////////////////////////////////////////////
void Start(unsigned int sampleRate = 44100);
////////////////////////////////////////////////////////////
/// Stop the capture
/// \brief Stop the capture
///
/// \see Start
///
////////////////////////////////////////////////////////////
void Stop();
////////////////////////////////////////////////////////////
/// Get the sample rate
/// \brief Get the sample rate
///
/// \return Frequency, in samples per second
/// 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;
////////////////////////////////////////////////////////////
/// Tell if the system supports sound capture.
/// If not, this class won't be usable
/// \brief Check if the system supports audio capture
///
/// \return True if audio capture is supported
/// 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 CanCapture();
@ -84,7 +101,9 @@ public :
protected :
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
/// This constructor is only meant to be called by derived classes.
///
////////////////////////////////////////////////////////////
SoundRecorder();
@ -92,44 +111,68 @@ protected :
private :
////////////////////////////////////////////////////////////
/// Start recording audio data
/// \brief Start capturing audio data
///
/// \return False to abort recording audio data, true to start
/// 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();
////////////////////////////////////////////////////////////
/// Process a new chunk of recorded samples
/// \brief Process a new chunk of recorded samples
///
/// \param samples : Pointer to the new chunk of recorded samples
/// \param samplesCount : Number of samples pointed by 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.).
///
/// \return False to stop recording audio data, true to continue
/// \param samples Pointer to the new chunk of recorded samples
/// \param samplesCount 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 samplesCount) = 0;
////////////////////////////////////////////////////////////
/// Stop recording audio data
/// \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();
////////////////////////////////////////////////////////////
/// /see Thread::Run
/// \brief Function called as the entry point of the thread
///
/// This function starts the recording loop, and returns
/// only when the capture is stopped.
///
////////////////////////////////////////////////////////////
virtual void Run();
////////////////////////////////////////////////////////////
/// Get the available captured samples and process them
/// \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();
////////////////////////////////////////////////////////////
/// Clean up the recorder internal resources
/// \brief Clean up the recorder's internal resources
///
/// This function is called when the capture stops.
///
////////////////////////////////////////////////////////////
void CleanUp();
@ -146,3 +189,79 @@ private :
#endif // SFML_SOUNDRECORDER_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundRecorder
///
/// 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
///
/// The audio capture feature may not be supported or activated
/// on every platform, thus it is recommended to check its
/// availability with the CanCapture() function. If it returns
/// false, then any attempt to use an audio recorder will fail.
///
/// 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 and OnStop
/// virtual functions (but not OnStart) 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 samplesCount)
/// {
/// // 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::CanCapture())
/// {
/// CustomRecorder recorder;
/// recorder.Start();
/// ...
/// recorder.Stop();
/// }
/// \endcode
///
/// \see sf::SoundBufferRecorder
///
////////////////////////////////////////////////////////////

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

@ -36,10 +36,8 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// SoundStream is a streamed sound, ie samples are acquired
/// while the sound is playing. Use it for big sounds that would
/// require hundreds of MB in memory (see Music),
/// or for streaming sound from the network
/// \brief Abstract base class for streamed audio sources
///
////////////////////////////////////////////////////////////
class SFML_API SoundStream : private Thread, private Sound
{
@ -64,7 +62,8 @@ public :
using Sound::GetAttenuation;
////////////////////////////////////////////////////////////
/// Structure defining a chunk of audio data to stream
/// \brief Structure defining a chunk of audio data to stream
///
////////////////////////////////////////////////////////////
struct Chunk
{
@ -73,25 +72,40 @@ public :
};
////////////////////////////////////////////////////////////
/// Virtual destructor
/// \brief Destructor
///
////////////////////////////////////////////////////////////
virtual ~SoundStream();
////////////////////////////////////////////////////////////
/// Start playing the audio stream
/// \brief Start or resume playing the audio stream
///
/// This function starts the stream if it was stopped, resumes
/// it if it was paused, and does nothing it is it 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();
////////////////////////////////////////////////////////////
/// Stop playing the audio stream
/// \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();
////////////////////////////////////////////////////////////
/// Return the number of channels (1 = mono, 2 = stereo)
/// \brief Return the number of channels of the stream
///
/// 1 channel means a mono sound, 2 means stereo, etc.
///
/// \return Number of channels
///
@ -99,67 +113,94 @@ public :
unsigned int GetChannelsCount() const;
////////////////////////////////////////////////////////////
/// Get the stream sample rate
/// \brief Get the stream sample rate of the stream
///
/// \return Stream frequency (number of samples per second)
/// 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;
////////////////////////////////////////////////////////////
/// Get the status of the stream (stopped, paused, playing)
/// \brief Get the current status of the stream (stopped, paused, playing)
///
/// \return Current status of the sound
/// \return Current status
///
////////////////////////////////////////////////////////////
Status GetStatus() const;
////////////////////////////////////////////////////////////
/// Set the current playing position of the stream
/// \brief Change the current playing position of the stream
///
/// \param timeOffset : New playing position, expressed in seconds
/// The playing position can be changed when the stream is
/// either paused or playing.
///
/// \param timeOffset New playing position, in seconds
///
/// \see GetPlayingOffset
///
////////////////////////////////////////////////////////////
void SetPlayingOffset(float timeOffset);
////////////////////////////////////////////////////////////
/// Get the current playing position of the stream
/// \brief Get the current playing position of the stream
///
/// \return Current playing position, expressed in seconds
/// \return Current playing position, in seconds
///
/// \see SetPlayingOffset
///
////////////////////////////////////////////////////////////
float GetPlayingOffset() const;
////////////////////////////////////////////////////////////
/// Set the stream loop state.
/// This parameter is disabled by default
/// \brief Set whether or not the stream should loop after reaching the end
///
/// \param loop : True to play in loop, false to play once
/// 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);
////////////////////////////////////////////////////////////
/// Tell whether or not the stream is looping
/// \brief Tell whether or not the stream is in loop mode
///
/// \return True if the music is looping, false otherwise
///
/// \see SetLoop
///
////////////////////////////////////////////////////////////
bool GetLoop() const;
protected :
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
/// This constructor is only meant to be called by derived classes.
///
////////////////////////////////////////////////////////////
SoundStream();
////////////////////////////////////////////////////////////
/// Set the audio stream parameters, you must call it before Play()
/// \brief Define the audio stream parameters
///
/// \param channelsCount : Number of channels
/// \param sampleRate : Sample rate
/// 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 channelsCount Number of channels of the stream
/// \param sampleRate Sample rate, in samples per second
///
////////////////////////////////////////////////////////////
void Initialize(unsigned int channelsCount, unsigned int sampleRate);
@ -167,15 +208,24 @@ protected :
private :
////////////////////////////////////////////////////////////
/// /see Thread::Run
/// \brief Function called as the entry point of the thread
///
/// This function starts the streaming loop, and returns
/// only when the sound is stopped.
///
////////////////////////////////////////////////////////////
virtual void Run();
////////////////////////////////////////////////////////////
/// Called each time new audio data is needed to feed the stream
/// \brief Request a new chunk of audio samples from the stream source
///
/// \param data : New chunk of data to stream
/// 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.
///
/// \param data Chunk of data to fill
///
/// \return True to continue playback, false to stop
///
@ -183,39 +233,54 @@ private :
virtual bool OnGetData(Chunk& data) = 0;
////////////////////////////////////////////////////////////
/// Called to move the current reading position
/// \brief Change the current playing position in the stream source
///
/// \param timeOffset : New read position, expressed in seconds
/// This function must be overriden by derived classes to
/// allow random seeking into the stream source.
///
/// \param timeOffset New playing position, in seconds
///
////////////////////////////////////////////////////////////
virtual void OnSeek(float timeOffset) = 0;
////////////////////////////////////////////////////////////
/// Fill a new buffer with audio data, and push it to the
/// playing queue
/// \brief Fill a new buffer with audio samples, and append
/// it to the playing queue
///
/// \param buffer : Buffer to fill
/// 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.
///
/// \return True if the derived class has requested to stop
/// \param buffer Handle of the buffer to fill
///
/// \return True if the stream source has requested to stop, false otherwise
///
////////////////////////////////////////////////////////////
bool FillAndPushBuffer(unsigned int buffer);
////////////////////////////////////////////////////////////
/// Fill the buffers queue with all available buffers
/// \brief Fill the audio buffers and put them all into the playing queue
///
/// \return True if the derived class has requested to stop
/// 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();
////////////////////////////////////////////////////////////
/// Clear the queue of any remaining buffers
/// \brief Clear all the audio buffers and empty the playing queue
///
/// This function is called when the stream is stopped.
///
////////////////////////////////////////////////////////////
void ClearQueue();
enum {BuffersCount = 3};
enum
{
BuffersCount = 3 ///< Number of audio buffers used by the streaming loop
};
////////////////////////////////////////////////////////////
// Member data
@ -233,3 +298,81 @@ private :
#endif // SFML_SOUNDSTREAM_HPP
////////////////////////////////////////////////////////////
/// \class sf::SoundStream
///
/// 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 channelsCount = ...;
/// unsigned int sampleRate = ...;
///
/// // Initialize the stream -- important!
/// Initialize(channelsCount, sampleRate);
/// }
///
/// private :
///
/// virtual bool OnGetData(Chunk& data)
/// {
/// // Fill the chunk with audio data from the stream source
/// data.Samples = ...;
/// data.NbSamples = ...;
///
/// // Return true to continue playing
/// return true;
/// }
///
/// virtual void OnSeek(float timeOffset)
/// {
/// // Change the current position in the stream source
/// ...
/// }
/// }
///
/// // Usage
/// CustomStream stream;
/// stream.Open("path/to/stream");
/// stream.Play();
/// \endcode
///
/// \see sf::Music
///
////////////////////////////////////////////////////////////