diff --git a/build/codeblocks/sfml-audio.cbp b/build/codeblocks/sfml-audio.cbp index bf25563d..dfc62821 100644 --- a/build/codeblocks/sfml-audio.cbp +++ b/build/codeblocks/sfml-audio.cbp @@ -117,11 +117,12 @@ + + - diff --git a/build/vc2005/sfml-audio.vcproj b/build/vc2005/sfml-audio.vcproj index 9ccb65e5..cc292f9c 100644 --- a/build/vc2005/sfml-audio.vcproj +++ b/build/vc2005/sfml-audio.vcproj @@ -343,6 +343,14 @@ + + + + @@ -367,10 +375,6 @@ RelativePath="..\..\include\SFML\Audio\Music.hpp" > - - diff --git a/build/vc2008/sfml-audio.vcproj b/build/vc2008/sfml-audio.vcproj index bbae08b9..b666b50a 100644 --- a/build/vc2008/sfml-audio.vcproj +++ b/build/vc2008/sfml-audio.vcproj @@ -343,6 +343,14 @@ + + + + @@ -367,10 +375,6 @@ RelativePath="..\..\include\SFML\Audio\Music.hpp" > - - diff --git a/include/SFML/Audio/Listener.hpp b/include/SFML/Audio/Listener.hpp index ceabcf22..c34ac164 100644 --- a/include/SFML/Audio/Listener.hpp +++ b/include/SFML/Audio/Listener.hpp @@ -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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/Audio/SoundBufferRecorder.hpp b/include/SFML/Audio/SoundBufferRecorder.hpp index 14353b25..29f6f655 100644 --- a/include/SFML/Audio/SoundBufferRecorder.hpp +++ b/include/SFML/Audio/SoundBufferRecorder.hpp @@ -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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/Audio/SoundRecorder.hpp b/include/SFML/Audio/SoundRecorder.hpp index c7260f9a..e4ff99af 100644 --- a/include/SFML/Audio/SoundRecorder.hpp +++ b/include/SFML/Audio/SoundRecorder.hpp @@ -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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/Audio/SoundStream.hpp b/include/SFML/Audio/SoundStream.hpp index 4cb83916..9f01f0e0 100644 --- a/include/SFML/Audio/SoundStream.hpp +++ b/include/SFML/Audio/SoundStream.hpp @@ -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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/Network/Http.hpp b/include/SFML/Network/Http.hpp index 3ccf42dd..d6d34d4c 100644 --- a/include/SFML/Network/Http.hpp +++ b/include/SFML/Network/Http.hpp @@ -176,10 +176,12 @@ public : enum Status { // 2xx: success - Ok = 200, ///< Most common code returned when operation was successful - Created = 201, ///< The resource has successfully been created - Accepted = 202, ///< The request has been accepted, but will be processed later by the server - NoContent = 204, ///< Sent when the server didn't send any data in return + Ok = 200, ///< Most common code returned when operation was successful + Created = 201, ///< The resource has successfully been created + Accepted = 202, ///< The request has been accepted, but will be processed later by the server + NoContent = 204, ///< The server didn't send any data in return + ResetContent = 205, ///< The server informs the client that it should clear the view (form) that caused the request to be sent + PartialContent = 206, ///< The server has sent a part of the resource, as a response to a partial GET request // 3xx: redirection MultipleChoices = 300, ///< The requested page can be accessed from several locations @@ -188,16 +190,19 @@ public : NotModified = 304, ///< For conditionnal requests, means the requested page hasn't changed and doesn't need to be refreshed // 4xx: client error - BadRequest = 400, ///< The server couldn't understand the request (syntax error) - Unauthorized = 401, ///< The requested page needs an authentification to be accessed - Forbidden = 403, ///< The requested page cannot be accessed at all, even with authentification - NotFound = 404, ///< The requested page doesn't exist + BadRequest = 400, ///< The server couldn't understand the request (syntax error) + Unauthorized = 401, ///< The requested page needs an authentification to be accessed + Forbidden = 403, ///< The requested page cannot be accessed at all, even with authentification + NotFound = 404, ///< The requested page doesn't exist + RangeNotSatisfiable = 407, ///< The server can't satisfy the partial GET request (with a "Range" header field) // 5xx: server error InternalServerError = 500, ///< The server encountered an unexpected error NotImplemented = 501, ///< The server doesn't implement a requested feature BadGateway = 502, ///< The gateway server has received an error from the source server ServiceNotAvailable = 503, ///< The server is temporarily unavailable (overloaded, in maintenance, ...) + GatewayTimeout = 504, ///< The gateway server couldn't receive a response from the source server + VersionNotSupported = 505, ///< The server doesn't support the requested HTTP version // 10xx: SFML custom codes InvalidResponse = 1000, ///< Response is not a valid HTTP one diff --git a/include/SFML/Window/Window.hpp b/include/SFML/Window/Window.hpp index 9f2713a0..baf4bd3e 100644 --- a/include/SFML/Window/Window.hpp +++ b/include/SFML/Window/Window.hpp @@ -209,6 +209,8 @@ public : /// /// \return True if an event was returned, or false if the events stack was empty /// + /// \see WaitEvent + /// //////////////////////////////////////////////////////////// bool GetEvent(Event& event); @@ -234,6 +236,8 @@ public : /// /// \return False if any error occured /// + /// \see GetEvent + /// //////////////////////////////////////////////////////////// bool WaitEvent(Event& event); diff --git a/src/SFML/Audio/OpenAL.hpp b/src/SFML/Audio/ALCheck.cpp similarity index 76% rename from src/SFML/Audio/OpenAL.hpp rename to src/SFML/Audio/ALCheck.cpp index 913c0e24..03520950 100644 --- a/src/SFML/Audio/OpenAL.hpp +++ b/src/SFML/Audio/ALCheck.cpp @@ -22,23 +22,10 @@ // //////////////////////////////////////////////////////////// -#ifndef SFML_OPENAL_HPP -#define SFML_OPENAL_HPP - //////////////////////////////////////////////////////////// // Headers //////////////////////////////////////////////////////////// -#include -#include -#include - -#if defined(SFML_SYSTEM_MACOS) - #include - #include -#else - #include - #include -#endif +#include namespace sf @@ -46,28 +33,7 @@ namespace sf namespace priv { //////////////////////////////////////////////////////////// -/// Let's define a macro to quickly check every OpenAL -/// API calls -/// -//////////////////////////////////////////////////////////// -#ifdef SFML_DEBUG - - // If in debug mode, perform a test on every call - #define ALCheck(Func) ((Func), priv::ALCheckError(__FILE__, __LINE__)) - -#else - - // Else, we don't add any overhead - #define ALCheck(Func) (Func) - -#endif - - -//////////////////////////////////////////////////////////// -/// Check last OpenAL error -/// -//////////////////////////////////////////////////////////// -inline void ALCheckError(const std::string& file, unsigned int line) +void ALCheckError(const std::string& file, unsigned int line) { // Get the last error ALenum errorCode = alGetError(); @@ -126,6 +92,3 @@ inline void ALCheckError(const std::string& file, unsigned int line) } // namespace priv } // namespace sf - - -#endif // SFML_OPENAL_HPP diff --git a/src/SFML/Audio/ALCheck.hpp b/src/SFML/Audio/ALCheck.hpp new file mode 100644 index 00000000..7832845d --- /dev/null +++ b/src/SFML/Audio/ALCheck.hpp @@ -0,0 +1,79 @@ +//////////////////////////////////////////////////////////// +// +// SFML - Simple and Fast Multimedia Library +// Copyright (C) 2007-2009 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_ALCHECK_HPP +#define SFML_ALCHECK_HPP + +//////////////////////////////////////////////////////////// +// Headers +//////////////////////////////////////////////////////////// +#include +#include +#include + +#if defined(SFML_SYSTEM_MACOS) + #include + #include +#else + #include + #include +#endif + + +namespace sf +{ +namespace priv +{ +//////////////////////////////////////////////////////////// +/// Let's define a macro to quickly check every OpenAL +/// API calls +//////////////////////////////////////////////////////////// +#ifdef SFML_DEBUG + + // If in debug mode, perform a test on every call + #define ALCheck(Func) ((Func), priv::ALCheckError(__FILE__, __LINE__)) + +#else + + // Else, we don't add any overhead + #define ALCheck(Func) (Func) + +#endif + + +//////////////////////////////////////////////////////////// +/// Check the last OpenAL error +/// +/// \param file Source file where the call is located +/// \param line Line number of the source file where the call is located +/// +//////////////////////////////////////////////////////////// +void ALCheckError(const std::string& file, unsigned int line); + +} // namespace priv + +} // namespace sf + + +#endif // SFML_ALCHECK_HPP diff --git a/src/SFML/Audio/AudioDevice.hpp b/src/SFML/Audio/AudioDevice.hpp index 38d5a429..18a47832 100644 --- a/src/SFML/Audio/AudioDevice.hpp +++ b/src/SFML/Audio/AudioDevice.hpp @@ -28,7 +28,7 @@ //////////////////////////////////////////////////////////// // Headers //////////////////////////////////////////////////////////// -#include +#include #include #include diff --git a/src/SFML/Audio/Listener.cpp b/src/SFML/Audio/Listener.cpp index 8f29411c..c9bac558 100644 --- a/src/SFML/Audio/Listener.cpp +++ b/src/SFML/Audio/Listener.cpp @@ -26,22 +26,18 @@ // Headers //////////////////////////////////////////////////////////// #include -#include +#include namespace sf { //////////////////////////////////////////////////////////// -/// Change the global volume of all the sounds -//////////////////////////////////////////////////////////// void Listener::SetGlobalVolume(float volume) { ALCheck(alListenerf(AL_GAIN, volume * 0.01f)); } -//////////////////////////////////////////////////////////// -/// Get the current value of the global volume of all the sounds //////////////////////////////////////////////////////////// float Listener::GetGlobalVolume() { @@ -52,8 +48,6 @@ float Listener::GetGlobalVolume() } -//////////////////////////////////////////////////////////// -/// Change the position of the listener (take 3 values) //////////////////////////////////////////////////////////// void Listener::SetPosition(float x, float y, float z) { @@ -61,8 +55,6 @@ void Listener::SetPosition(float x, float y, float z) } -//////////////////////////////////////////////////////////// -/// Change the position of the listener (take a 3D vector) //////////////////////////////////////////////////////////// void Listener::SetPosition(const Vector3f& position) { @@ -70,8 +62,6 @@ void Listener::SetPosition(const Vector3f& position) } -//////////////////////////////////////////////////////////// -/// Get the current position of the listener //////////////////////////////////////////////////////////// Vector3f Listener::GetPosition() { @@ -82,8 +72,6 @@ Vector3f Listener::GetPosition() } -//////////////////////////////////////////////////////////// -/// Change the orientation of the listener (take 3 values) //////////////////////////////////////////////////////////// void Listener::SetDirection(float x, float y, float z) { @@ -92,8 +80,6 @@ void Listener::SetDirection(float x, float y, float z) } -//////////////////////////////////////////////////////////// -/// Change the orientation of the listener (take a 3D vector) //////////////////////////////////////////////////////////// void Listener::SetDirection(const Vector3f& direction) { @@ -101,8 +87,6 @@ void Listener::SetDirection(const Vector3f& direction) } -//////////////////////////////////////////////////////////// - /// Get the current orientation of the listener. //////////////////////////////////////////////////////////// Vector3f Listener::GetDirection() { diff --git a/src/SFML/Audio/Music.cpp b/src/SFML/Audio/Music.cpp index 42370cc1..87f7afe4 100644 --- a/src/SFML/Audio/Music.cpp +++ b/src/SFML/Audio/Music.cpp @@ -26,7 +26,7 @@ // Headers //////////////////////////////////////////////////////////// #include -#include +#include #include #include #include diff --git a/src/SFML/Audio/Sound.cpp b/src/SFML/Audio/Sound.cpp index 157dd9fd..9071b943 100644 --- a/src/SFML/Audio/Sound.cpp +++ b/src/SFML/Audio/Sound.cpp @@ -27,7 +27,7 @@ //////////////////////////////////////////////////////////// #include #include -#include +#include namespace sf diff --git a/src/SFML/Audio/SoundBuffer.cpp b/src/SFML/Audio/SoundBuffer.cpp index 12bc4406..ce9b14d9 100644 --- a/src/SFML/Audio/SoundBuffer.cpp +++ b/src/SFML/Audio/SoundBuffer.cpp @@ -28,7 +28,7 @@ #include #include #include -#include +#include #include #include diff --git a/src/SFML/Audio/SoundBufferRecorder.cpp b/src/SFML/Audio/SoundBufferRecorder.cpp index aefa1664..d9ee9598 100644 --- a/src/SFML/Audio/SoundBufferRecorder.cpp +++ b/src/SFML/Audio/SoundBufferRecorder.cpp @@ -33,18 +33,15 @@ namespace sf { //////////////////////////////////////////////////////////// -/// /see SoundBuffer::OnStart -//////////////////////////////////////////////////////////// bool SoundBufferRecorder::OnStart() { mySamples.clear(); + myBuffer = SoundBuffer(); return true; } -//////////////////////////////////////////////////////////// -/// /see SoundBuffer::OnProcessSamples //////////////////////////////////////////////////////////// bool SoundBufferRecorder::OnProcessSamples(const Int16* samples, std::size_t samplesCount) { @@ -54,8 +51,6 @@ bool SoundBufferRecorder::OnProcessSamples(const Int16* samples, std::size_t sam } -//////////////////////////////////////////////////////////// -/// /see SoundBuffer::OnStop //////////////////////////////////////////////////////////// void SoundBufferRecorder::OnStop() { @@ -64,8 +59,6 @@ void SoundBufferRecorder::OnStop() } -//////////////////////////////////////////////////////////// -/// Get the sound buffer containing the captured audio data //////////////////////////////////////////////////////////// const SoundBuffer& SoundBufferRecorder::GetBuffer() const { diff --git a/src/SFML/Audio/SoundFile.cpp b/src/SFML/Audio/SoundFile.cpp index c907808a..7271460c 100644 --- a/src/SFML/Audio/SoundFile.cpp +++ b/src/SFML/Audio/SoundFile.cpp @@ -35,8 +35,6 @@ namespace sf namespace priv { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// SoundFile::SoundFile() : myFile (NULL), myNbSamples (0), @@ -47,8 +45,6 @@ mySampleRate (0) } -//////////////////////////////////////////////////////////// -/// Destructor //////////////////////////////////////////////////////////// SoundFile::~SoundFile() { @@ -57,8 +53,6 @@ SoundFile::~SoundFile() } -//////////////////////////////////////////////////////////// -/// Get the total number of samples in the file //////////////////////////////////////////////////////////// std::size_t SoundFile::GetSamplesCount() const { @@ -66,8 +60,6 @@ std::size_t SoundFile::GetSamplesCount() const } -//////////////////////////////////////////////////////////// -/// Get the number of channels used by the sound //////////////////////////////////////////////////////////// unsigned int SoundFile::GetChannelsCount() const { @@ -75,8 +67,6 @@ unsigned int SoundFile::GetChannelsCount() const } -//////////////////////////////////////////////////////////// -/// Get the sample rate of the sound //////////////////////////////////////////////////////////// unsigned int SoundFile::GetSampleRate() const { @@ -84,8 +74,6 @@ unsigned int SoundFile::GetSampleRate() const } -//////////////////////////////////////////////////////////// -/// Open the sound file for reading //////////////////////////////////////////////////////////// bool SoundFile::OpenRead(const std::string& filename) { @@ -111,8 +99,6 @@ bool SoundFile::OpenRead(const std::string& filename) } -//////////////////////////////////////////////////////////// -/// Open the sound file in memory for reading //////////////////////////////////////////////////////////// bool SoundFile::OpenRead(const char* data, std::size_t sizeInBytes) { @@ -120,22 +106,12 @@ bool SoundFile::OpenRead(const char* data, std::size_t sizeInBytes) if (myFile) sf_close(myFile); - // Define the I/O custom functions for reading from memory - SF_VIRTUAL_IO io; - io.get_filelen = &SoundFile::MemoryGetLength; - io.read = &SoundFile::MemoryRead; - io.seek = &SoundFile::MemorySeek; - io.tell = &SoundFile::MemoryTell; - io.write = &SoundFile::MemoryWrite; - - // Initialize the memory data - myMemory.DataStart = data; - myMemory.DataPtr = data; - myMemory.TotalSize = sizeInBytes; + // Prepare the memory I/O structure + SF_VIRTUAL_IO io = myMemoryIO.Prepare(data, sizeInBytes); // Open the sound file SF_INFO fileInfos; - myFile = sf_open_virtual(&io, SFM_READ, &fileInfos, &myMemory); + myFile = sf_open_virtual(&io, SFM_READ, &fileInfos, &myMemoryIO); if (!myFile) { std::cerr << "Failed to read sound file from memory (" << sf_strerror(myFile) << ")" << std::endl; @@ -151,8 +127,6 @@ bool SoundFile::OpenRead(const char* data, std::size_t sizeInBytes) } -//////////////////////////////////////////////////////////// -/// Open the sound file for writing //////////////////////////////////////////////////////////// bool SoundFile::OpenWrite(const std::string& filename, unsigned int channelsCount, unsigned int sampleRate) { @@ -192,8 +166,6 @@ bool SoundFile::OpenWrite(const std::string& filename, unsigned int channelsCoun } -//////////////////////////////////////////////////////////// -/// Read samples from the loaded sound //////////////////////////////////////////////////////////// std::size_t SoundFile::Read(Int16* data, std::size_t nbSamples) { @@ -204,8 +176,6 @@ std::size_t SoundFile::Read(Int16* data, std::size_t nbSamples) } -//////////////////////////////////////////////////////////// -/// Write samples to the file //////////////////////////////////////////////////////////// void SoundFile::Write(const Int16* data, std::size_t nbSamples) { @@ -224,8 +194,6 @@ void SoundFile::Write(const Int16* data, std::size_t nbSamples) } -//////////////////////////////////////////////////////////// -/// Move the current reading position in the file //////////////////////////////////////////////////////////// void SoundFile::Seek(float timeOffset) { @@ -237,9 +205,6 @@ void SoundFile::Seek(float timeOffset) } -//////////////////////////////////////////////////////////// -/// Get the internal format of an audio file according to -/// its filename extension //////////////////////////////////////////////////////////// int SoundFile::GetFormatFromFilename(const std::string& filename) { @@ -281,65 +246,87 @@ int SoundFile::GetFormatFromFilename(const std::string& filename) //////////////////////////////////////////////////////////// -/// Functions for implementing custom read and write to memory files -//////////////////////////////////////////////////////////// -sf_count_t SoundFile::MemoryGetLength(void* userData) +SF_VIRTUAL_IO SoundFile::MemoryIO::Prepare(const char* data, std::size_t sizeInBytes) { - MemoryInfos* memory = static_cast(userData); + // Setup the I/O functions + SF_VIRTUAL_IO io; + io.get_filelen = &SoundFile::MemoryIO::GetLength; + io.read = &SoundFile::MemoryIO::Read; + io.seek = &SoundFile::MemoryIO::Seek; + io.tell = &SoundFile::MemoryIO::Tell; + io.write = &SoundFile::MemoryIO::Write; - return memory->TotalSize; + // Initialize the memory data + myDataStart = data; + myDataPtr = data; + myTotalSize = sizeInBytes; + + return io; } -sf_count_t SoundFile::MemoryRead(void* ptr, sf_count_t count, void* userData) + + +//////////////////////////////////////////////////////////// +sf_count_t SoundFile::MemoryIO::GetLength(void* userData) { - MemoryInfos* memory = static_cast(userData); + MemoryIO* self = static_cast(userData); - sf_count_t position = memory->DataPtr - memory->DataStart; - if (position + count >= memory->TotalSize) - count = memory->TotalSize - position; + return self->myTotalSize; +} - memcpy(ptr, memory->DataPtr, static_cast(count)); - memory->DataPtr += count; +//////////////////////////////////////////////////////////// +sf_count_t SoundFile::MemoryIO::Read(void* ptr, sf_count_t count, void* userData) +{ + MemoryIO* self = static_cast(userData); + + sf_count_t position = self->myDataPtr - self->myDataStart; + if (position + count >= self->myTotalSize) + count = self->myTotalSize - position; + + memcpy(ptr, self->myDataPtr, static_cast(count)); + + self->myDataPtr += count; return count; } -sf_count_t SoundFile::MemorySeek(sf_count_t offset, int whence, void* userData) + + +//////////////////////////////////////////////////////////// +sf_count_t SoundFile::MemoryIO::Seek(sf_count_t offset, int whence, void* userData) { - MemoryInfos* memory = static_cast(userData); + MemoryIO* self = static_cast(userData); sf_count_t position = 0; switch (whence) { - case SEEK_SET : - position = offset; - break; - case SEEK_CUR : - position = memory->DataPtr - memory->DataStart + offset; - break; - case SEEK_END : - position = memory->TotalSize - offset; - break; - default : - position = 0; - break; + case SEEK_SET : position = offset; break; + case SEEK_CUR : position = self->myDataPtr - self->myDataStart + offset; break; + case SEEK_END : position = self->myTotalSize - offset; break; + default : position = 0; break; } - if (position >= memory->TotalSize) - position = memory->TotalSize - 1; + if (position >= self->myTotalSize) + position = self->myTotalSize - 1; else if (position < 0) position = 0; - memory->DataPtr = memory->DataStart + position; + self->myDataPtr = self->myDataStart + position; return position; } -sf_count_t SoundFile::MemoryTell(void* userData) -{ - MemoryInfos* memory = static_cast(userData); - return memory->DataPtr - memory->DataStart; + +//////////////////////////////////////////////////////////// +sf_count_t SoundFile::MemoryIO::Tell(void* userData) +{ + MemoryIO* self = static_cast(userData); + + return self->myDataPtr - self->myDataStart; } -sf_count_t SoundFile::MemoryWrite(const void*, sf_count_t, void*) + + +//////////////////////////////////////////////////////////// +sf_count_t SoundFile::MemoryIO::Write(const void*, sf_count_t, void*) { return 0; } diff --git a/src/SFML/Audio/SoundFile.hpp b/src/SFML/Audio/SoundFile.hpp index dd7d9f99..55529547 100644 --- a/src/SFML/Audio/SoundFile.hpp +++ b/src/SFML/Audio/SoundFile.hpp @@ -38,27 +38,27 @@ namespace sf namespace priv { //////////////////////////////////////////////////////////// -/// SoundFile is used to load and save various sampled -/// sound file formats +/// \brief Provide read and write access to sound files +/// //////////////////////////////////////////////////////////// class SoundFile : NonCopyable { public : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor /// //////////////////////////////////////////////////////////// SoundFile(); //////////////////////////////////////////////////////////// - /// Destructor + /// \brief Destructor /// //////////////////////////////////////////////////////////// ~SoundFile(); //////////////////////////////////////////////////////////// - /// Get the total number of samples in the file + /// \brief Get the total number of audio samples in the file /// /// \return Number of samples /// @@ -66,7 +66,7 @@ public : std::size_t GetSamplesCount() const; //////////////////////////////////////////////////////////// - /// Get the number of channels used by the sound + /// \brief Get the number of channels used by the sound /// /// \return Number of channels (1 = mono, 2 = stereo) /// @@ -74,17 +74,17 @@ public : unsigned int GetChannelsCount() const; //////////////////////////////////////////////////////////// - /// Get the sample rate of the sound + /// \brief Get the sample rate of the sound /// - /// \return Sample rate, in samples / sec + /// \return Sample rate, in samples per second /// //////////////////////////////////////////////////////////// unsigned int GetSampleRate() const; //////////////////////////////////////////////////////////// - /// Open the sound file for reading + /// \brief Open a sound file for reading /// - /// \param filename : Path of sound file to load + /// \param filename Path of the sound file to load /// /// \return True if the file was successfully opened /// @@ -92,10 +92,10 @@ public : bool OpenRead(const std::string& filename); //////////////////////////////////////////////////////////// - /// Open the sound file in memory for reading + /// \brief Open a sound file in memory for reading /// - /// \param data : Pointer to the file data in memory - /// \param sizeInBytes : Size of the data to load, in bytes + /// \param data Pointer to the file data in memory + /// \param sizeInBytes Size of the data to load, in bytes /// /// \return True if the file was successfully opened /// @@ -103,11 +103,11 @@ public : bool OpenRead(const char* data, std::size_t sizeInBytes); //////////////////////////////////////////////////////////// - /// Open the sound file for writing + /// \brief a the sound file for writing /// - /// \param filename : Path of sound file to write - /// \param channelsCount : Number of channels in the sound - /// \param sampleRate : Sample rate of the sound + /// \param filename Path of the sound file to write + /// \param channelsCount Number of channels in the sound + /// \param sampleRate Sample rate of the sound /// /// \return True if the file was successfully opened /// @@ -115,29 +115,29 @@ public : bool OpenWrite(const std::string& filename, unsigned int channelsCount, unsigned int sampleRate); //////////////////////////////////////////////////////////// - /// Read samples from the loaded sound + /// \brief Read audio samples from the loaded sound /// - /// \param data : Pointer to the samples array to fill - /// \param nbSamples : Number of samples to read + /// \param data Pointer to the samples array to fill + /// \param nbSamples Number of samples to read /// - /// \return Number of samples read + /// \return Number of samples actually read (may be less than \a nbSamples) /// //////////////////////////////////////////////////////////// std::size_t Read(Int16* data, std::size_t nbSamples); //////////////////////////////////////////////////////////// - /// Write samples to the file + /// \brief Write audio samples to the file /// - /// \param data : Pointer to the samples array to write - /// \param nbSamples : Number of samples to write + /// \param data Pointer to the samples array to write + /// \param nbSamples Number of samples to write /// //////////////////////////////////////////////////////////// void Write(const Int16* data, std::size_t nbSamples); //////////////////////////////////////////////////////////// - /// Move the current reading position in the file + /// \brief Change the current read position in the file /// - /// \param timeOffset : New position, expressed in seconds + /// \param timeOffset New read position, in seconds /// //////////////////////////////////////////////////////////// void Seek(float timeOffset); @@ -145,10 +145,10 @@ public : private : //////////////////////////////////////////////////////////// - /// Get the internal format of an audio file according to - /// its filename extension + /// \brief Get the internal format of an audio file according to + /// its filename extension /// - /// \param filename : Filename to check + /// \param filename Filename to check /// /// \return Internal format matching the filename (-1 if no match) /// @@ -156,30 +156,33 @@ private : static int GetFormatFromFilename(const std::string& filename); //////////////////////////////////////////////////////////// - /// Functions for implementing custom read and write to memory files + /// \brief Provide I/O functions for manipulating files in memory /// //////////////////////////////////////////////////////////// - static sf_count_t MemoryGetLength(void* UserData); - static sf_count_t MemoryRead(void* Ptr, sf_count_t Count, void* UserData); - static sf_count_t MemorySeek(sf_count_t Offset, int Whence, void* UserData); - static sf_count_t MemoryTell(void* UserData); - static sf_count_t MemoryWrite(const void* Ptr, sf_count_t Count, void* UserData); - - //////////////////////////////////////////////////////////// - /// Structure holding data related to memory operations - //////////////////////////////////////////////////////////// - struct MemoryInfos + class MemoryIO { - const char* DataStart; ///< Pointer to the begining of the data - const char* DataPtr; ///< Pointer to the current read / write position - sf_count_t TotalSize; ///< Total size of the data, in bytes + public : + + SF_VIRTUAL_IO Prepare(const char* data, std::size_t sizeInBytes); + + private : + + static sf_count_t GetLength(void* UserData); + static sf_count_t Read(void* Ptr, sf_count_t Count, void* UserData); + static sf_count_t Seek(sf_count_t Offset, int Whence, void* UserData); + static sf_count_t Tell(void* UserData); + static sf_count_t Write(const void* Ptr, sf_count_t Count, void* UserData); + + const char* myDataStart; + const char* myDataPtr; + sf_count_t myTotalSize; }; //////////////////////////////////////////////////////////// // Member data //////////////////////////////////////////////////////////// SNDFILE* myFile; ///< File descriptor - MemoryInfos myMemory; ///< Memory read / write data + MemoryIO myMemoryIO; ///< Memory read / write data std::size_t myNbSamples; ///< Total number of samples in the file unsigned int myChannelsCount; ///< Number of channels used by the sound unsigned int mySampleRate; ///< Number of samples per second diff --git a/src/SFML/Audio/SoundRecorder.cpp b/src/SFML/Audio/SoundRecorder.cpp index 5389ec1a..134c4a3c 100644 --- a/src/SFML/Audio/SoundRecorder.cpp +++ b/src/SFML/Audio/SoundRecorder.cpp @@ -27,7 +27,7 @@ //////////////////////////////////////////////////////////// #include #include -#include +#include #include #include @@ -43,8 +43,6 @@ namespace namespace sf { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// SoundRecorder::SoundRecorder() : mySampleRate (0), myIsCapturing(false) @@ -53,8 +51,6 @@ myIsCapturing(false) } -//////////////////////////////////////////////////////////// -/// Virtual destructor //////////////////////////////////////////////////////////// SoundRecorder::~SoundRecorder() { @@ -62,9 +58,6 @@ SoundRecorder::~SoundRecorder() } -//////////////////////////////////////////////////////////// -/// Start the capture. -/// Warning : only one capture can happen at the same time //////////////////////////////////////////////////////////// void SoundRecorder::Start(unsigned int sampleRate) { @@ -109,8 +102,6 @@ void SoundRecorder::Start(unsigned int sampleRate) } -//////////////////////////////////////////////////////////// -/// Stop the capture //////////////////////////////////////////////////////////// void SoundRecorder::Stop() { @@ -120,8 +111,6 @@ void SoundRecorder::Stop() } -//////////////////////////////////////////////////////////// -/// Get the sample rate //////////////////////////////////////////////////////////// unsigned int SoundRecorder::GetSampleRate() const { @@ -129,9 +118,6 @@ unsigned int SoundRecorder::GetSampleRate() const } -//////////////////////////////////////////////////////////// -/// Tell if the system supports sound capture. -/// If not, this class won't be usable //////////////////////////////////////////////////////////// bool SoundRecorder::CanCapture() { @@ -141,8 +127,6 @@ bool SoundRecorder::CanCapture() } -//////////////////////////////////////////////////////////// -/// Start recording audio data //////////////////////////////////////////////////////////// bool SoundRecorder::OnStart() { @@ -151,8 +135,6 @@ bool SoundRecorder::OnStart() } -//////////////////////////////////////////////////////////// -/// Stop recording audio data //////////////////////////////////////////////////////////// void SoundRecorder::OnStop() { @@ -160,8 +142,6 @@ void SoundRecorder::OnStop() } -//////////////////////////////////////////////////////////// -/// /see Thread::Run //////////////////////////////////////////////////////////// void SoundRecorder::Run() { @@ -182,8 +162,6 @@ void SoundRecorder::Run() } -//////////////////////////////////////////////////////////// -/// Get available captured samples and process them //////////////////////////////////////////////////////////// void SoundRecorder::ProcessCapturedSamples() { @@ -207,8 +185,6 @@ void SoundRecorder::ProcessCapturedSamples() } -//////////////////////////////////////////////////////////// -/// Clean up recorder internal resources //////////////////////////////////////////////////////////// void SoundRecorder::CleanUp() { diff --git a/src/SFML/Audio/SoundStream.cpp b/src/SFML/Audio/SoundStream.cpp index a7300ff5..b968192f 100644 --- a/src/SFML/Audio/SoundStream.cpp +++ b/src/SFML/Audio/SoundStream.cpp @@ -27,15 +27,13 @@ //////////////////////////////////////////////////////////// #include #include -#include +#include #include namespace sf { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// SoundStream::SoundStream() : myIsStreaming (false), myChannelsCount (0), @@ -48,8 +46,6 @@ mySamplesProcessed(0) } -//////////////////////////////////////////////////////////// -/// Virtual destructor //////////////////////////////////////////////////////////// SoundStream::~SoundStream() { @@ -58,8 +54,6 @@ SoundStream::~SoundStream() } -//////////////////////////////////////////////////////////// -/// Set the audio stream parameters, you must call it before Play() //////////////////////////////////////////////////////////// void SoundStream::Initialize(unsigned int channelsCount, unsigned int sampleRate) { @@ -79,8 +73,6 @@ void SoundStream::Initialize(unsigned int channelsCount, unsigned int sampleRate } -//////////////////////////////////////////////////////////// -/// Start playing the audio stream //////////////////////////////////////////////////////////// void SoundStream::Play() { @@ -108,8 +100,6 @@ void SoundStream::Play() } -//////////////////////////////////////////////////////////// -/// Stop playing the audio stream //////////////////////////////////////////////////////////// void SoundStream::Stop() { @@ -119,8 +109,6 @@ void SoundStream::Stop() } -//////////////////////////////////////////////////////////// -/// Return the number of channels (1 = mono, 2 = stereo, ...) //////////////////////////////////////////////////////////// unsigned int SoundStream::GetChannelsCount() const { @@ -128,8 +116,6 @@ unsigned int SoundStream::GetChannelsCount() const } -//////////////////////////////////////////////////////////// -/// Get the sound frequency (sample rate) //////////////////////////////////////////////////////////// unsigned int SoundStream::GetSampleRate() const { @@ -137,8 +123,6 @@ unsigned int SoundStream::GetSampleRate() const } -//////////////////////////////////////////////////////////// -/// Get the status of the sound (stopped, paused, playing) //////////////////////////////////////////////////////////// Sound::Status SoundStream::GetStatus() const { @@ -152,8 +136,6 @@ Sound::Status SoundStream::GetStatus() const } -//////////////////////////////////////////////////////////// -/// Set the current playing position of the stream //////////////////////////////////////////////////////////// void SoundStream::SetPlayingOffset(float timeOffset) { @@ -170,11 +152,6 @@ void SoundStream::SetPlayingOffset(float timeOffset) } -//////////////////////////////////////////////////////////// -/// Get the current playing position of the stream -/// -/// \return Current playing position, expressed in seconds -/// //////////////////////////////////////////////////////////// float SoundStream::GetPlayingOffset() const { @@ -182,8 +159,6 @@ float SoundStream::GetPlayingOffset() const } -//////////////////////////////////////////////////////////// -/// Set the music loop state //////////////////////////////////////////////////////////// void SoundStream::SetLoop(bool loop) { @@ -191,8 +166,6 @@ void SoundStream::SetLoop(bool loop) } -//////////////////////////////////////////////////////////// -/// Tell whether or not the music is looping //////////////////////////////////////////////////////////// bool SoundStream::GetLoop() const { @@ -200,8 +173,6 @@ bool SoundStream::GetLoop() const } -//////////////////////////////////////////////////////////// -/// /see Thread::Run //////////////////////////////////////////////////////////// void SoundStream::Run() { @@ -295,9 +266,6 @@ void SoundStream::Run() } -//////////////////////////////////////////////////////////// -/// Fill a new buffer with audio data, and push it to the -/// playing queue //////////////////////////////////////////////////////////// bool SoundStream::FillAndPushBuffer(unsigned int buffer) { @@ -323,8 +291,6 @@ bool SoundStream::FillAndPushBuffer(unsigned int buffer) } -//////////////////////////////////////////////////////////// -/// Fill the buffers queue with all available buffers //////////////////////////////////////////////////////////// bool SoundStream::FillQueue() { @@ -340,8 +306,6 @@ bool SoundStream::FillQueue() } -//////////////////////////////////////////////////////////// -/// Clear the queue of any remaining buffers //////////////////////////////////////////////////////////// void SoundStream::ClearQueue() { diff --git a/src/SFML/Graphics/GLCheck.cpp b/src/SFML/Graphics/GLCheck.cpp index 96fb5654..db3fa328 100644 --- a/src/SFML/Graphics/GLCheck.cpp +++ b/src/SFML/Graphics/GLCheck.cpp @@ -31,6 +31,8 @@ namespace sf { +namespace priv +{ //////////////////////////////////////////////////////////// /// Check the last OpenGL error //////////////////////////////////////////////////////////// @@ -119,4 +121,6 @@ void EnsureGlewInit() } } +} // namespace priv + } // namespace sf diff --git a/src/SFML/Graphics/GLCheck.hpp b/src/SFML/Graphics/GLCheck.hpp index 16142d41..312ac52c 100644 --- a/src/SFML/Graphics/GLCheck.hpp +++ b/src/SFML/Graphics/GLCheck.hpp @@ -35,6 +35,8 @@ namespace sf { +namespace priv +{ //////////////////////////////////////////////////////////// /// Let's define a macro to quickly check every OpenGL /// API calls @@ -42,7 +44,7 @@ namespace sf #ifdef SFML_DEBUG // In debug mode, perform a test on every OpenGL call - #define GLCheck(call) ((call), GLCheckError(__FILE__, __LINE__)) + #define GLCheck(call) ((call), priv::GLCheckError(__FILE__, __LINE__)) #else @@ -51,7 +53,6 @@ namespace sf #endif - //////////////////////////////////////////////////////////// /// Check the last OpenGL error /// @@ -67,6 +68,8 @@ void GLCheckError(const std::string& file, unsigned int line); //////////////////////////////////////////////////////////// void EnsureGlewInit(); +} // namespace priv + } // namespace sf diff --git a/src/SFML/Graphics/GeometryRendererVA.cpp b/src/SFML/Graphics/GeometryRendererVA.cpp index 50a5ec3d..4325a23a 100644 --- a/src/SFML/Graphics/GeometryRendererVA.cpp +++ b/src/SFML/Graphics/GeometryRendererVA.cpp @@ -36,7 +36,7 @@ namespace priv //////////////////////////////////////////////////////////// bool GeometryRendererVA::IsSupported() { - EnsureGlewInit(); + priv::EnsureGlewInit(); return glewIsSupported("GL_EXT_vertex_array") != 0; } @@ -46,7 +46,7 @@ bool GeometryRendererVA::IsSupported() GeometryRendererVA::GeometryRendererVA() : myIndices(NULL) { - EnsureGlewInit(); + priv::EnsureGlewInit(); myCanLock = glewIsSupported("GL_EXT_compiled_vertex_array") != 0; } diff --git a/src/SFML/Graphics/GeometryRendererVBO.cpp b/src/SFML/Graphics/GeometryRendererVBO.cpp index a1058db1..412932bd 100644 --- a/src/SFML/Graphics/GeometryRendererVBO.cpp +++ b/src/SFML/Graphics/GeometryRendererVBO.cpp @@ -35,7 +35,7 @@ namespace priv //////////////////////////////////////////////////////////// bool GeometryRendererVBO::IsSupported() { - EnsureGlewInit(); + priv::EnsureGlewInit(); return glewIsSupported("GL_ARB_vertex_buffer_object") != 0; } @@ -46,7 +46,7 @@ GeometryRendererVBO::GeometryRendererVBO() : myVertexBufferSize(0), myIndexBufferSize (0) { - EnsureGlewInit(); + priv::EnsureGlewInit(); // Create the buffers GLCheck(glGenBuffersARB(1, &myVertexBuffer)); diff --git a/src/SFML/Graphics/Image.cpp b/src/SFML/Graphics/Image.cpp index 1a067b14..5d584dd7 100644 --- a/src/SFML/Graphics/Image.cpp +++ b/src/SFML/Graphics/Image.cpp @@ -582,7 +582,7 @@ FloatRect Image::GetTexCoords(const IntRect& rect) const unsigned int Image::GetValidTextureSize(unsigned int size) { // Make sure that GLEW is initialized - EnsureGlewInit(); + priv::EnsureGlewInit(); if (glewIsSupported("GL_ARB_texture_non_power_of_two") != 0) { @@ -740,7 +740,7 @@ void Image::EnsureArrayUpdate() GLCheck(glBindTexture(GL_TEXTURE_2D, myTexture)); GLCheck(glGetTexImage(GL_TEXTURE_2D, 0, GL_RGBA, GL_UNSIGNED_BYTE, &allPixels[0])); - // The we copy the useful pixels from the temporary array to the final one + // Then we copy the useful pixels from the temporary array to the final one const Color* src = &allPixels[0]; Color* dst = &myPixels[0]; int srcPitch = myTextureWidth; diff --git a/src/SFML/Graphics/PostFX.cpp b/src/SFML/Graphics/PostFX.cpp index cb2151cd..f35e250e 100644 --- a/src/SFML/Graphics/PostFX.cpp +++ b/src/SFML/Graphics/PostFX.cpp @@ -44,7 +44,7 @@ PostFX::PostFX() : myShaderProgram(0) { // Make sure that GLEW is initialized - EnsureGlewInit(); + priv::EnsureGlewInit(); // No filtering on frame buffer myFrameBuffer.SetSmooth(false); @@ -263,7 +263,7 @@ PostFX& PostFX::operator =(const PostFX& other) bool PostFX::CanUsePostFX() { // Make sure that GLEW is initialized - EnsureGlewInit(); + priv::EnsureGlewInit(); return glewIsSupported("GL_ARB_shading_language_100") != 0 && glewIsSupported("GL_ARB_shader_objects") != 0 && diff --git a/src/SFML/Graphics/RenderImageImplFBO.cpp b/src/SFML/Graphics/RenderImageImplFBO.cpp index 07af9a7e..75358738 100644 --- a/src/SFML/Graphics/RenderImageImplFBO.cpp +++ b/src/SFML/Graphics/RenderImageImplFBO.cpp @@ -73,7 +73,7 @@ RenderImageImplFBO::~RenderImageImplFBO() bool RenderImageImplFBO::IsSupported() { // Make sure that GLEW is initialized - EnsureGlewInit(); + priv::EnsureGlewInit(); return glewIsSupported("GL_EXT_framebuffer_object") != 0; } diff --git a/src/SFML/Graphics/Win32/RenderImageImplPBuffer.cpp b/src/SFML/Graphics/Win32/RenderImageImplPBuffer.cpp index d0e8489c..52a5b1e6 100644 --- a/src/SFML/Graphics/Win32/RenderImageImplPBuffer.cpp +++ b/src/SFML/Graphics/Win32/RenderImageImplPBuffer.cpp @@ -77,7 +77,7 @@ RenderImageImplPBuffer::~RenderImageImplPBuffer() bool RenderImageImplPBuffer::IsSupported() { // Make sure that GLEW is initialized - EnsureGlewInit(); + priv::EnsureGlewInit(); return wglewIsSupported("WGL_ARB_pbuffer") && wglewIsSupported("WGL_ARB_pixel_format"); diff --git a/src/SFML/Network/Http.cpp b/src/SFML/Network/Http.cpp index 49d2a17d..1e5660f0 100644 --- a/src/SFML/Network/Http.cpp +++ b/src/SFML/Network/Http.cpp @@ -313,43 +313,43 @@ myPort(0) //////////////////////////////////////////////////////////// /// Construct the Http instance with the target host //////////////////////////////////////////////////////////// -Http::Http(const std::string& Host, unsigned short Port) +Http::Http(const std::string& host, unsigned short port) { - SetHost(Host, Port); + SetHost(host, port); } //////////////////////////////////////////////////////////// /// Set the target host //////////////////////////////////////////////////////////// -void Http::SetHost(const std::string& Host, unsigned short Port) +void Http::SetHost(const std::string& host, unsigned short port) { // Detect the protocol used - std::string Protocol = ToLower(Host.substr(0, 8)); - if (Protocol.substr(0, 7) == "http://") + std::string protocol = ToLower(host.substr(0, 8)); + if (protocol.substr(0, 7) == "http://") { // HTTP protocol - myHostName = Host.substr(7); - myPort = (Port != 0 ? Port : 80); + myHostName = host.substr(7); + myPort = (port != 0 ? port : 80); } - else if (Protocol == "https://") + else if (protocol == "https://") { // HTTPS protocol - myHostName = Host.substr(8); - myPort = (Port != 0 ? Port : 443); + myHostName = host.substr(8); + myPort = (port != 0 ? port : 443); } else { // Undefined protocol - use HTTP - myHostName = Host; - myPort = (Port != 0 ? Port : 80); + myHostName = host; + myPort = (port != 0 ? port : 80); } // Remove any trailing '/' from the host name if (!myHostName.empty() && (*myHostName.rbegin() == '/')) myHostName.erase(myHostName.size() - 1); - myHost = sf::IPAddress(myHostName); + myHost = IPAddress(myHostName); } @@ -361,62 +361,62 @@ void Http::SetHost(const std::string& Host, unsigned short Port) /// not return instantly; use a thread if you don't want to block your /// application. //////////////////////////////////////////////////////////// -Http::Response Http::SendRequest(const Http::Request& Req, float Timeout) +Http::Response Http::SendRequest(const Http::Request& request, float timeout) { // First make sure the request is valid -- add missing mandatory fields - Request ToSend(Req); - if (!ToSend.HasField("From")) + Request toSend(request); + if (!toSend.HasField("From")) { - ToSend.SetField("From", "user@sfml-dev.org"); + toSend.SetField("From", "user@sfml-dev.org"); } - if (!ToSend.HasField("User-Agent")) + if (!toSend.HasField("User-Agent")) { - ToSend.SetField("User-Agent", "libsfml-network/1.x"); + toSend.SetField("User-Agent", "libsfml-network/2.x"); } - if (!ToSend.HasField("Host")) + if (!toSend.HasField("Host")) { - ToSend.SetField("Host", myHostName); + toSend.SetField("Host", myHostName); } - if (!ToSend.HasField("Content-Length")) + if (!toSend.HasField("Content-Length")) { - std::ostringstream Out; - Out << ToSend.myBody.size(); - ToSend.SetField("Content-Length", Out.str()); + std::ostringstream out; + out << toSend.myBody.size(); + toSend.SetField("Content-Length", out.str()); } - if ((ToSend.myMethod == Request::Post) && !ToSend.HasField("Content-Type")) + if ((toSend.myMethod == Request::Post) && !toSend.HasField("Content-Type")) { - ToSend.SetField("Content-Type", "application/x-www-form-urlencoded"); + toSend.SetField("Content-Type", "application/x-www-form-urlencoded"); } - if ((ToSend.myMajorVersion * 10 + ToSend.myMinorVersion >= 11) && !ToSend.HasField("Connection")) + if ((toSend.myMajorVersion * 10 + toSend.myMinorVersion >= 11) && !toSend.HasField("Connection")) { - ToSend.SetField("Connection", "close"); + toSend.SetField("Connection", "close"); } // Prepare the response - Response Received; + Response received; // Connect the socket to the host - if (myConnection.Connect(myPort, myHost, Timeout) == Socket::Done) + if (myConnection.Connect(myPort, myHost, timeout) == Socket::Done) { // Convert the request to string and send it through the connected socket - std::string RequestStr = ToSend.ToString(); + std::string requestStr = toSend.ToString(); - if (!RequestStr.empty()) + if (!requestStr.empty()) { // Send it through the socket - if (myConnection.Send(RequestStr.c_str(), RequestStr.size()) == sf::Socket::Done) + if (myConnection.Send(requestStr.c_str(), requestStr.size()) == sf::Socket::Done) { // Wait for the server's response - std::string ReceivedStr; - std::size_t Size = 0; - char Buffer[1024]; - while (myConnection.Receive(Buffer, sizeof(Buffer), Size) == sf::Socket::Done) + std::string receivedStr; + std::size_t size = 0; + char buffer[1024]; + while (myConnection.Receive(buffer, sizeof(buffer), size) == sf::Socket::Done) { - ReceivedStr.append(Buffer, Buffer + Size); + receivedStr.append(buffer, buffer + size); } // Build the Response object from the received data - Received.FromString(ReceivedStr); + received.FromString(receivedStr); } } @@ -424,7 +424,7 @@ Http::Response Http::SendRequest(const Http::Request& Req, float Timeout) myConnection.Close(); } - return Received; + return received; } } // namespace sf