From d734c9df5ccdfb597df824969167bac95f191b52 Mon Sep 17 00:00:00 2001 From: Laurent Gomila Date: Fri, 2 Sep 2011 18:42:25 +0200 Subject: [PATCH] Improved API documentation (copied from SFML) --- include/SFML/Audio/Listener.h | 49 +++-- include/SFML/Audio/Music.h | 235 +++++++++++++------- include/SFML/Audio/Sound.h | 210 +++++++++++------- include/SFML/Audio/SoundBuffer.h | 108 +++++++--- include/SFML/Audio/SoundBufferRecorder.h | 46 ++-- include/SFML/Audio/SoundRecorder.h | 52 +++-- include/SFML/Audio/SoundStatus.h | 4 + include/SFML/Audio/SoundStream.h | 220 ++++++++++++------- include/SFML/Network/Ftp.h | 250 +++++++++++++-------- include/SFML/Network/Http.h | 175 +++++++++------ include/SFML/Network/IpAddress.h | 94 +++++--- include/SFML/Network/Packet.h | 72 ++++--- include/SFML/Network/SocketSelector.h | 70 +++--- include/SFML/Network/SocketStatus.h | 12 +- include/SFML/Network/TcpListener.h | 79 ++++--- include/SFML/Network/TcpSocket.h | 124 +++++++---- include/SFML/Network/UdpSocket.h | 145 ++++++++----- include/SFML/System/Clock.h | 28 ++- include/SFML/System/Mutex.h | 14 +- include/SFML/System/Sleep.h | 7 +- include/SFML/System/Thread.h | 51 +++-- include/SFML/Window/Context.h | 16 +- include/SFML/Window/Event.h | 33 ++- include/SFML/Window/VideoMode.h | 33 ++- include/SFML/Window/Window.h | 264 ++++++++++++++++------- src/SFML/Audio/Listener.cpp | 12 -- src/SFML/Audio/Music.cpp | 61 ------ src/SFML/Audio/Sound.cpp | 57 ----- src/SFML/Audio/SoundBuffer.cpp | 41 ++-- src/SFML/Audio/SoundBufferRecorder.cpp | 14 -- src/SFML/Audio/SoundRecorder.cpp | 15 -- src/SFML/Audio/SoundStream.cpp | 56 ----- src/SFML/Network/Ftp.cpp | 68 ------ src/SFML/Network/Http.cpp | 48 ----- src/SFML/Network/IpAddress.cpp | 33 +-- src/SFML/Network/Packet.cpp | 38 +--- src/SFML/Network/SocketSelector.cpp | 18 -- src/SFML/Network/TcpListener.cpp | 48 ++--- src/SFML/Network/TcpSocket.cpp | 27 --- src/SFML/Network/UdpSocket.cpp | 34 +-- src/SFML/System/Clock.cpp | 10 - src/SFML/System/Mutex.cpp | 8 - src/SFML/System/Sleep.cpp | 2 - src/SFML/System/Thread.cpp | 13 -- src/SFML/Window/Context.cpp | 6 - src/SFML/Window/Joystick.cpp | 12 -- src/SFML/Window/Keyboard.cpp | 2 - src/SFML/Window/Mouse.cpp | 6 - src/SFML/Window/VideoMode.cpp | 13 +- src/SFML/Window/Window.cpp | 51 ----- 50 files changed, 1606 insertions(+), 1478 deletions(-) diff --git a/include/SFML/Audio/Listener.h b/include/SFML/Audio/Listener.h index ee85653..3390db1 100644 --- a/include/SFML/Audio/Listener.h +++ b/include/SFML/Audio/Listener.h @@ -32,15 +32,19 @@ //////////////////////////////////////////////////////////// -/// Change the global volume of all the sounds +/// \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] /// //////////////////////////////////////////////////////////// CSFML_API void sfListener_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] /// @@ -48,41 +52,48 @@ CSFML_API void sfListener_SetGlobalVolume(float volume); CSFML_API float sfListener_GetGlobalVolume(void); //////////////////////////////////////////////////////////// -/// Change the position of the listener +/// \brief Set the position of the listener in the scene /// -/// \param x : X position of the listener in the world -/// \param y : Y position of the listener in the world -/// \param z : 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 /// //////////////////////////////////////////////////////////// CSFML_API void sfListener_SetPosition(float x, float y, float z); //////////////////////////////////////////////////////////// -/// Get the current position of the listener +/// \brief Get the current position of the listener in the scene /// -/// \param x : X position of the listener in the world -/// \param y : Y position of the listener in the world -/// \param z : Z position of the listener in the world +/// \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 /// //////////////////////////////////////////////////////////// CSFML_API void sfListener_GetPosition(float* x, float* y, float* z); //////////////////////////////////////////////////////////// -/// Change the orientation of the listener +/// \brief Set the orientation of the listener in the scene /// -/// \param x : X component of the listener's direction -/// \param y : Y component of the listener's direction -/// \param z : Z component of the listener's direction +/// 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 /// //////////////////////////////////////////////////////////// CSFML_API void sfListener_SetDirection(float x, float y, float z); //////////////////////////////////////////////////////////// -/// Get the current orientation of the listener +/// \brief Get the current orientation of the listener in the scene /// -/// \param x : X component of the listener's direction -/// \param y : Y component of the listener's direction -/// \param z : Z component of the listener's direction +/// \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 /// //////////////////////////////////////////////////////////// CSFML_API void sfListener_GetDirection(float* x, float* y, float* z); diff --git a/include/SFML/Audio/Music.h b/include/SFML/Audio/Music.h index 4d78495..3e03593 100644 --- a/include/SFML/Audio/Music.h +++ b/include/SFML/Audio/Music.h @@ -36,9 +36,15 @@ //////////////////////////////////////////////////////////// -/// Create a new music and load it from a file +/// \brief Create a new music and load it from a file /// -/// \param filename : Path of the music file to open +/// This function doesn't start playing the music (call +/// sfMusic_Play to do so). +/// Here is a complete list of all the supported audio formats: +/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, +/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64. +/// +/// \param filename Path of the music file to open /// /// \return A new sfMusic object (NULL if failed) /// @@ -46,10 +52,16 @@ CSFML_API sfMusic* sfMusic_CreateFromFile(const char* filename); //////////////////////////////////////////////////////////// -/// Create a new music and load it from a file in memory +/// \brief Create a new music and load it from a file in memory /// -/// \param data : Pointer to the file data in memory -/// \param sizeInBytes : Size of the data to load, in bytes +/// This function doesn't start playing the music (call +/// sfMusic_Play to do so). +/// Here is a complete list of all the supported audio formats: +/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, +/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64. +/// +/// \param data Pointer to the file data in memory +/// \param sizeInBytes Size of the data to load, in bytes /// /// \return A new sfMusic object (NULL if failed) /// @@ -57,9 +69,15 @@ CSFML_API sfMusic* sfMusic_CreateFromFile(const char* filename); CSFML_API sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes); //////////////////////////////////////////////////////////// -/// Create a new music and load it from a custom stream +/// \brief Create a new music and load it from a custom stream /// -/// \param stream : Source stream to read from +/// This function doesn't start playing the music (call +/// sfMusic_Play to do so). +/// Here is a complete list of all the supported audio formats: +/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, +/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64. +/// +/// \param stream Source stream to read from /// /// \return A new sfMusic object (NULL if failed) /// @@ -67,26 +85,31 @@ CSFML_API sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes CSFML_API sfMusic* sfMusic_CreateFromStream(sfInputStream* stream); //////////////////////////////////////////////////////////// -/// Destroy an existing music +/// \brief Destroy a music /// -/// \param music : Music to delete +/// \param music Music to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_Destroy(sfMusic* music); //////////////////////////////////////////////////////////// -/// Set a music loop state +/// \brief Set whether or not a music should loop after reaching the end /// -/// \param music : Music to set the loop state -/// \param loop : sfTrue to play in loop, sfFalse to play once +/// If set, the music will restart from beginning after +/// reaching the end and so on, until it is stopped or +/// sfMusic_SetLoop(music, sfFalse) is called. +/// The default looping state for musics is false. +/// +/// \param music Music object +/// \param loop sfTrue to play in loop, sfFalse to play once /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetLoop(sfMusic* music, sfBool loop); //////////////////////////////////////////////////////////// -/// Tell whether or not a music is looping +/// \brief Tell whether or not a music is in loop mode /// -/// \param music : Music to get the loop state from +/// \param music Music object /// /// \return sfTrue if the music is looping, sfFalse otherwise /// @@ -94,9 +117,9 @@ CSFML_API void sfMusic_SetLoop(sfMusic* music, sfBool loop); CSFML_API sfBool sfMusic_GetLoop(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get a music duration +/// \brief Get the total duration of a music /// -/// \param music : Music to get the duration from +/// \param music Music object /// /// \return Music duration, in milliseconds /// @@ -104,33 +127,48 @@ CSFML_API sfBool sfMusic_GetLoop(const sfMusic* music); CSFML_API sfUint32 sfMusic_GetDuration(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Start playing a music +/// \brief Start or resume playing a music /// -/// \param music : Music to play +/// This function starts the music if it was stopped, resumes +/// it if it was paused, and restarts it from beginning if it +/// was it already playing. +/// This function uses its own thread so that it doesn't block +/// the rest of the program while the music is played. +/// +/// \param music Music object /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_Play(sfMusic* music); //////////////////////////////////////////////////////////// -/// Pause a music +/// \brief Pause a music /// -/// \param music : Music to pause +/// This function pauses the music if it was playing, +/// otherwise (music already paused or stopped) it has no effect. +/// +/// \param music Music object /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_Pause(sfMusic* music); //////////////////////////////////////////////////////////// -/// Stop playing a music +/// \brief Stop playing a music /// -/// \param music : Music to stop +/// This function stops the music if it was playing or paused, +/// and does nothing if it was already stopped. +/// It also resets the playing position (unlike sfMusic_Pause). +/// +/// \param music Music object /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_Stop(sfMusic* music); //////////////////////////////////////////////////////////// -/// Return the number of channels of a music (1 = mono, 2 = stereo) +/// \brief Return the number of channels of a music /// -/// \param music : Music to get the channels count from +/// 1 channel means a mono sound, 2 means stereo, etc. +/// +/// \param music Music object /// /// \return Number of channels /// @@ -138,29 +176,32 @@ CSFML_API void sfMusic_Stop(sfMusic* music); CSFML_API unsigned int sfMusic_GetChannelsCount(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get the stream sample rate of a music +/// \brief Get the sample rate of a music /// -/// \param music : Music to get the sample rate from +/// The sample rate is the number of audio samples played per +/// second. The higher, the better the quality. /// -/// \return Stream frequency (number of samples per second) +/// \param music Music object +/// +/// \return Sample rate, in number of samples per second /// //////////////////////////////////////////////////////////// CSFML_API unsigned int sfMusic_GetSampleRate(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get the status of a music (stopped, paused, playing) +/// \brief Get the current status of a music (stopped, paused, playing) /// -/// \param music : Music to get the status from +/// \param music Music object /// -/// \return Current status of the sound +/// \return Current status /// //////////////////////////////////////////////////////////// CSFML_API sfSoundStatus sfMusic_GetStatus(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get the current playing position of a music +/// \brief Get the current playing position of a music /// -/// \param music : Music to get the position from +/// \param music Music object /// /// \return Current playing position, in milliseconds /// @@ -168,112 +209,144 @@ CSFML_API sfSoundStatus sfMusic_GetStatus(const sfMusic* music); CSFML_API sfUint32 sfMusic_GetPlayingOffset(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Set the pitch of a music +/// \brief Set the pitch of a music /// -/// \param music : Music to modify -/// \param pitch : New pitch +/// The pitch represents the perceived fundamental frequency +/// of a sound; thus you can make a music more acute or grave +/// by changing its pitch. A side effect of changing the pitch +/// is to modify the playing speed of the music as well. +/// The default value for the pitch is 1. +/// +/// \param music Music object +/// \param pitch New pitch to apply to the music /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetPitch(sfMusic* music, float pitch); //////////////////////////////////////////////////////////// -/// Set the volume of a music +/// \brief Set the volume of a music /// -/// \param music : Music to modify -/// \param volume : Volume (in range [0, 100]) +/// The volume is a value between 0 (mute) and 100 (full volume). +/// The default value for the volume is 100. +/// +/// \param music Music object +/// \param volume Volume of the music /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetVolume(sfMusic* music, float volume); //////////////////////////////////////////////////////////// -/// Set the position of a music +/// \brief Set the 3D position of a music in the audio scene /// -/// \param music : Music to modify -/// \param x : X position of the sound in the world -/// \param y : Y position of the sound in the world -/// \param z : Z position of the sound in the world +/// Only musics with one channel (mono musics) can be +/// spatialized. +/// The default position of a music is (0, 0, 0). +/// +/// \param music Music object +/// \param x X coordinate of the position of the music in the scene +/// \param y Y coordinate of the position of the music in the scene +/// \param z Z coordinate of the position of the music in the scene /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetPosition(sfMusic* music, float x, float y, float z); //////////////////////////////////////////////////////////// -/// Make the music's position relative to the listener's -/// position, or absolute. -/// The default value is false (absolute) +/// \brief Make a musics's position relative to the listener or absolute /// -/// \param music : Music to modify -/// \param relative : True to set the position relative, false to set it absolute +/// Making a music relative to the listener will ensure that it will always +/// be played the same way regardless the position of the listener. +/// This can be useful for non-spatialized musics, musics that are +/// produced by the listener, or musics attached to it. +/// The default value is false (position is absolute). +/// +/// \param music Music object +/// \param relative sfTrue to set the position relative, sfFalse to set it absolute /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetRelativeToListener(sfMusic* music, sfBool relative); //////////////////////////////////////////////////////////// -/// Set the minimum distance - closer than this distance, -/// the listener will hear the music at its maximum volume. -/// The default minimum distance is 1.0 +/// \brief Set the minimum distance of a music /// -/// \param music : Music to modify -/// \param distance : New minimum distance for the music +/// The "minimum distance" of a music is the maximum +/// distance at which it is heard at its maximum volume. Further +/// than the minimum distance, it will start to fade out according +/// to its attenuation factor. A value of 0 ("inside the head +/// of the listener") is an invalid value and is forbidden. +/// The default value of the minimum distance is 1. +/// +/// \param music Music object +/// \param distance New minimum distance of the music /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetMinDistance(sfMusic* music, float distance); //////////////////////////////////////////////////////////// -/// Set the attenuation factor - the higher the attenuation, the -/// more the sound will be attenuated with distance from listener. -/// The default attenuation factor 1.0 +/// \brief Set the attenuation factor of a music /// -/// \param music : Music to modify -/// \param attenuation : New attenuation factor for the sound +/// The attenuation is a multiplicative factor which makes +/// the music more or less loud according to its distance +/// from the listener. An attenuation of 0 will produce a +/// non-attenuated music, i.e. its volume will always be the same +/// whether it is heard from near or from far. On the other hand, +/// an attenuation value such as 100 will make the music fade out +/// very quickly as it gets further from the listener. +/// The default value of the attenuation is 1. +/// +/// \param music Music object +/// \param attenuation New attenuation factor of the music /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetAttenuation(sfMusic* music, float attenuation); //////////////////////////////////////////////////////////// -/// Set the current playing position of a music +/// \brief Change the current playing position of a music /// -/// \param music : Music to modify -/// \param timeOffset : New playing position, in milliseconds +/// The playing position can be changed when the music is +/// either paused or playing. +/// +/// \param music Music object +/// \param timeOffset New playing position, in milliseconds /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_SetPlayingOffset(sfMusic* music, sfUint32 timeOffset); //////////////////////////////////////////////////////////// -/// Get the pitch of a music +/// \brief Get the pitch of a music /// -/// \param music : Music to get the pitch from +/// \param music Music object /// -/// \return Pitch value +/// \return Pitch of the music /// //////////////////////////////////////////////////////////// CSFML_API float sfMusic_GetPitch(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get the volume of a music +/// \brief Get the volume of a music /// -/// \param music : Music to get the volume from +/// \param music Music object /// -/// \return Volume value (in range [1, 100]) +/// \return Volume of the music, in the range [0, 100] /// //////////////////////////////////////////////////////////// CSFML_API float sfMusic_GetVolume(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get the position of a music +/// \brief Get the 3D position of a music in the audio scene /// -/// \param music : Music to get the position from -/// \param x : X position of the sound in the world -/// \param y : Y position of the sound in the world -/// \param z : Z position of the sound in the world +/// \param music Music object +/// \param x X position of the music in the world +/// \param y Y position of the music in the world +/// \param z Z position of the music in the world /// //////////////////////////////////////////////////////////// CSFML_API void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, float* z); //////////////////////////////////////////////////////////// -/// Tell if the music's position is relative to the listener's -/// position, or if it's absolute +/// \brief Tell whether a music's position is relative to the +/// listener or is absolute /// -/// \param music : Music to check +/// \param music Music object /// /// \return sfTrue if the position is relative, sfFalse if it's absolute /// @@ -281,21 +354,21 @@ CSFML_API void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, flo CSFML_API sfBool sfMusic_IsRelativeToListener(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get the minimum distance of a music +/// \brief Get the minimum distance of a music /// -/// \param music : Music to get the minimum distance from +/// \param music Music object /// -/// \return Minimum distance for the music +/// \return Minimum distance of the music /// //////////////////////////////////////////////////////////// CSFML_API float sfMusic_GetMinDistance(const sfMusic* music); //////////////////////////////////////////////////////////// -/// Get the attenuation factor of a music +/// \brief Get the attenuation factor of a music /// -/// \param music : Music to get the attenuation factor from +/// \param music Music object /// -/// \return Attenuation factor for the a music +/// \return Attenuation factor of the music /// //////////////////////////////////////////////////////////// CSFML_API float sfMusic_GetAttenuation(const sfMusic* music); diff --git a/include/SFML/Audio/Sound.h b/include/SFML/Audio/Sound.h index ba0ae3d..17fce00 100644 --- a/include/SFML/Audio/Sound.h +++ b/include/SFML/Audio/Sound.h @@ -34,87 +34,109 @@ //////////////////////////////////////////////////////////// -/// Construct a new sound +/// \brief Create a new sound /// -/// \return A new sfSound object (NULL if failed) +/// \return A new sfSound object /// //////////////////////////////////////////////////////////// CSFML_API sfSound* sfSound_Create(void); //////////////////////////////////////////////////////////// -/// Copy an existing sound +/// \brief Create a new sound by copying an existing one /// -/// \param sound : Sound to copy +/// \param sound Sound to copy /// -/// \return Copied object +/// \return A new sfSound object which is a copy of \a sound /// //////////////////////////////////////////////////////////// CSFML_API sfSound* sfSound_Copy(sfSound* sound); //////////////////////////////////////////////////////////// -/// Destroy an existing sound +/// \brief Destroy a sound /// -/// \param sound : Sound to delete +/// \param sound Sound to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_Destroy(sfSound* sound); //////////////////////////////////////////////////////////// -/// Start playing a sound +/// \brief Start or resume playing a sound /// -/// \param sound : Sound to play +/// This function starts the sound if it was stopped, resumes +/// it if it was paused, and restarts it from beginning if it +/// was it already playing. +/// This function uses its own thread so that it doesn't block +/// the rest of the program while the sound is played. +/// +/// \param sound Sound object /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_Play(sfSound* sound); //////////////////////////////////////////////////////////// -/// Pause a sound +/// \brief Pause a sound /// -/// \param sound : Sound to pause +/// This function pauses the sound if it was playing, +/// otherwise (sound already paused or stopped) it has no effect. +/// +/// \param sound Sound object /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_Pause(sfSound* sound); //////////////////////////////////////////////////////////// -/// Stop playing a sound +/// \brief Stop playing a sound /// -/// \param sound : Sound to stop +/// This function stops the sound if it was playing or paused, +/// and does nothing if it was already stopped. +/// It also resets the playing position (unlike sfSound_Pause). +/// +/// \param sound Sound object /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_Stop(sfSound* sound); //////////////////////////////////////////////////////////// -/// Bind a sound buffer to a sound +/// \brief Set the source buffer containing the audio data to play /// -/// \param sound : Sound to set the loop state -/// \param buffer : Buffer to bind +/// It is important to note that the sound buffer is not copied, +/// thus the sfSoundBuffer object must remain alive as long +/// as it is attached to the sound. +/// +/// \param sound Sound object +/// \param buffer Sound buffer to attach to the sound /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetBuffer(sfSound* sound, const sfSoundBuffer* buffer); //////////////////////////////////////////////////////////// -/// Get the sound buffer bound to a sound +/// \brief Get the audio buffer attached to a sound /// -/// \param sound : Sound to get the buffer from +/// \param sound Sound object /// -/// \return Pointer to the sound's buffer +/// \return Sound buffer attached to the sound (can be NULL) /// //////////////////////////////////////////////////////////// CSFML_API const sfSoundBuffer* sfSound_GetBuffer(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Set a sound loop state +/// \brief Set whether or not a sound should loop after reaching the end /// -/// \param sound : Sound to set the loop state -/// \param loop : sfTrue to play in loop, sfFalse to play once +/// If set, the sound will restart from beginning after +/// reaching the end and so on, until it is stopped or +/// sfSound_SetLoop(sound, sfFalse) is called. +/// The default looping state for sounds is false. +/// +/// \param sound Sound object +/// \param loop sfTrue to play in loop, sfFalse to play once /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetLoop(sfSound* sound, sfBool loop); //////////////////////////////////////////////////////////// -/// Tell whether or not a sound is looping +/// \brief Tell whether or not a soud is in loop mode /// -/// \param sound : Sound to get the loop state from +/// \param sound Sound object /// /// \return sfTrue if the sound is looping, sfFalse otherwise /// @@ -122,122 +144,154 @@ CSFML_API void sfSound_SetLoop(sfSound* sound, sfBool loop); CSFML_API sfBool sfSound_GetLoop(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Get the status of a sound (stopped, paused, playing) +/// \brief Get the current status of a sound (stopped, paused, playing) /// -/// \param sound : Sound to get the status from +/// \param sound Sound object /// -/// \return Current status of the sound +/// \return Current status /// //////////////////////////////////////////////////////////// CSFML_API sfSoundStatus sfSound_GetStatus(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Set the pitch of a sound +/// \brief Set the pitch of a sound /// -/// \param sound : Sound to modify -/// \param pitch : New pitch +/// The pitch represents the perceived fundamental frequency +/// of a sound; thus you can make a sound more acute or grave +/// by changing its pitch. A side effect of changing the pitch +/// is to modify the playing speed of the sound as well. +/// The default value for the pitch is 1. +/// +/// \param sound Sound object +/// \param pitch New pitch to apply to the sound /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetPitch(sfSound* sound, float pitch); //////////////////////////////////////////////////////////// -/// Set the volume of a sound +/// \brief Set the volume of a sound /// -/// \param sound : Sound to modify -/// \param volume : Volume (in range [0, 100]) +/// The volume is a value between 0 (mute) and 100 (full volume). +/// The default value for the volume is 100. +/// +/// \param sound Sound object +/// \param volume Volume of the sound /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetVolume(sfSound* sound, float volume); //////////////////////////////////////////////////////////// -/// Set the position of a sound +/// \brief Set the 3D position of a sound in the audio scene /// -/// \param sound : Sound to modify -/// \param x : X position of the sound in the world -/// \param y : Y position of the sound in the world -/// \param z : Z position of the sound in the world +/// Only sounds with one channel (mono sounds) can be +/// spatialized. +/// The default position of a sound is (0, 0, 0). +/// +/// \param sound Sound object +/// \param x X coordinate of the position of the sound in the scene +/// \param y Y coordinate of the position of the sound in the scene +/// \param z Z coordinate of the position of the sound in the scene /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetPosition(sfSound* sound, float x, float y, float z); //////////////////////////////////////////////////////////// -/// Make the sound's position relative to the listener's -/// position, or absolute. -/// The default value is false (absolute) +/// \brief Make the sound's position relative to the listener or absolute /// -/// \param sound : Sound to modify -/// \param relative : True to set the position relative, false to set it absolute +/// Making a sound relative to the listener will ensure that it will always +/// be played the same way regardless the position of the listener. +/// This can be useful for non-spatialized sounds, sounds that are +/// produced by the listener, or sounds attached to it. +/// The default value is false (position is absolute). +/// +/// \param sound Sound object +/// \param relative sfTrue to set the position relative, sfFalse to set it absolute /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetRelativeToListener(sfSound* sound, sfBool relative); //////////////////////////////////////////////////////////// -/// Set the minimum distance - closer than this distance, -/// the listener will hear the sound at its maximum volume. -/// The default minimum distance is 1.0 +/// \brief Set the minimum distance of a sound /// -/// \param sound : Sound to modify -/// \param distance : New minimum distance for the sound +/// The "minimum distance" of a sound is the maximum +/// distance at which it is heard at its maximum volume. Further +/// than the minimum distance, it will start to fade out according +/// to its attenuation factor. A value of 0 ("inside the head +/// of the listener") is an invalid value and is forbidden. +/// The default value of the minimum distance is 1. +/// +/// \param sound Sound object +/// \param distance New minimum distance of the sound /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetMinDistance(sfSound* sound, float distance); //////////////////////////////////////////////////////////// -/// Set the attenuation factor - the higher the attenuation, the -/// more the sound will be attenuated with distance from listener. -/// The default attenuation factor is 1.0 +/// \brief Set the attenuation factor of a sound /// -/// \param sound : Sound to modify -/// \param attenuation : New attenuation factor for the sound +/// The attenuation is a multiplicative factor which makes +/// the sound more or less loud according to its distance +/// from the listener. An attenuation of 0 will produce a +/// non-attenuated sound, i.e. its volume will always be the same +/// whether it is heard from near or from far. On the other hand, +/// an attenuation value such as 100 will make the sound fade out +/// very quickly as it gets further from the listener. +/// The default value of the attenuation is 1. +/// +/// \param sound Sound object +/// \param attenuation New attenuation factor of the sound /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetAttenuation(sfSound* sound, float attenuation); //////////////////////////////////////////////////////////// -/// Set the current playing position of a sound +/// \brief Change the current playing position of a sound /// -/// \param sound : Sound to modify -/// \param timeOffset : New playing position, in milliseconds +/// The playing position can be changed when the sound is +/// either paused or playing. +/// +/// \param sound Sound object +/// \param timeOffset New playing position, in milliseconds /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_SetPlayingOffset(sfSound* sound, sfUint32 timeOffset); //////////////////////////////////////////////////////////// -/// Get the pitch of a sound +/// \brief Get the pitch of a sound /// -/// \param sound : Sound to get the pitch from +/// \param sound Sound object /// -/// \return Pitch value +/// \return Pitch of the sound /// //////////////////////////////////////////////////////////// CSFML_API float sfSound_GetPitch(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Get the volume of a sound +/// \brief Get the volume of a sound /// -/// \param sound : Sound to get the volume from +/// \param sound Sound object /// -/// \return Volume value (in range [1, 100]) +/// \return Volume of the sound, in the range [0, 100] /// //////////////////////////////////////////////////////////// CSFML_API float sfSound_GetVolume(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Get the position of a sound +/// \brief Get the 3D position of a sound in the audio scene /// -/// \param sound : Sound to get the position from -/// \param x : X position of the sound in the world -/// \param y : Y position of the sound in the world -/// \param z : Z position of the sound in the world +/// \param sound Sound object +/// \param x X position of the sound in the world +/// \param y Y position of the sound in the world +/// \param z Z position of the sound in the world /// //////////////////////////////////////////////////////////// CSFML_API void sfSound_GetPosition(const sfSound* sound, float* x, float* y, float* z); //////////////////////////////////////////////////////////// -/// Tell if the sound's position is relative to the listener's -/// position, or if it's absolute +/// \brief Tell whether a sound's position is relative to the +/// listener or is absolute /// -/// \param sound : Sound to check +/// \param sound Sound object /// /// \return sfTrue if the position is relative, sfFalse if it's absolute /// @@ -245,29 +299,29 @@ CSFML_API void sfSound_GetPosition(const sfSound* sound, float* x, float* y, flo CSFML_API sfBool sfSound_IsRelativeToListener(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Get the minimum distance of a sound +/// \brief Get the minimum distance of a sound /// -/// \param sound : Sound to get the minimum distance from +/// \param sound Sound object /// -/// \return Minimum distance for the sound +/// \return Minimum distance of the sound /// //////////////////////////////////////////////////////////// CSFML_API float sfSound_GetMinDistance(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Get the attenuation factor of a sound +/// \brief Get the attenuation factor of a sound /// -/// \param sound : Sound to get the attenuation factor from +/// \param sound Sound object /// -/// \return Attenuation factor for the sound +/// \return Attenuation factor of the sound /// //////////////////////////////////////////////////////////// CSFML_API float sfSound_GetAttenuation(const sfSound* sound); //////////////////////////////////////////////////////////// -/// Get the current playing position of a sound +/// \brief Get the current playing position of a sound /// -/// \param sound : Sound to get the position from +/// \param sound Sound object /// /// \return Current playing position, in milliseconds /// diff --git a/include/SFML/Audio/SoundBuffer.h b/include/SFML/Audio/SoundBuffer.h index b6db777..c2a57be 100644 --- a/include/SFML/Audio/SoundBuffer.h +++ b/include/SFML/Audio/SoundBuffer.h @@ -30,13 +30,18 @@ //////////////////////////////////////////////////////////// #include #include +#include #include //////////////////////////////////////////////////////////// -/// Create a new sound buffer and load it from a file +/// \brief Create a new sound buffer and load it from a file /// -/// \param filename : Path of the music file to open +/// Here is a complete list of all the supported audio formats: +/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, +/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64. +/// +/// \param filename Path of the sound file to load /// /// \return A new sfSoundBuffer object (NULL if failed) /// @@ -44,10 +49,14 @@ CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename); //////////////////////////////////////////////////////////// -/// Create a new sound buffer and load it from a file in memory +/// \brief Create a new sound buffer and load it from a file in memory /// -/// \param data : Pointer to the file data in memory -/// \param sizeInBytes : Size of the data to load, in bytes +/// Here is a complete list of all the supported audio formats: +/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, +/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64. +/// +/// \param data Pointer to the file data in memory +/// \param sizeInBytes Size of the data to load, in bytes /// /// \return A new sfSoundBuffer object (NULL if failed) /// @@ -55,14 +64,29 @@ CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename); CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t sizeInBytes); //////////////////////////////////////////////////////////// -/// Create a new sound buffer and load it from an array of -/// samples in memory - assumed format for samples is -/// 16 bits signed integer +/// \brief Create a new sound buffer and load it from a custom stream /// -/// \param samples : Pointer to the samples in memory -/// \param samplesCount : Number of samples pointed by Samples -/// \param channelsCount : Number of channels (1 = mono, 2 = stereo, ...) -/// \param sampleRate : Frequency (number of samples to play per second) +/// Here is a complete list of all the supported audio formats: +/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, +/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64. +/// +/// \param stream Source stream to read from +/// +/// \return A new sfSoundBuffer object (NULL if failed) +/// +//////////////////////////////////////////////////////////// +CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromStream(sfInputStream* stream); + +//////////////////////////////////////////////////////////// +/// \brief Create a new sound buffer and load it from an array of samples in memory +/// +/// The assumed format of the audio samples is 16 bits signed integer +/// (sfInt16). +/// +/// \param samples Pointer to the array of samples in memory +/// \param samplesCount Number of samples in the array +/// \param channelsCount Number of channels (1 = mono, 2 = stereo, ...) +/// \param sampleRate Sample rate (number of samples to play per second) /// /// \return A new sfSoundBuffer object (NULL if failed) /// @@ -70,48 +94,59 @@ CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromSamples(const sfInt16* samples, size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate); //////////////////////////////////////////////////////////// -/// Copy an existing sound buffer +/// \brief Create a new sound buffer by copying an existing one /// -/// \param soundBuffer : Sound buffer to copy +/// \param soundBuffer Sound buffer to copy /// -/// \return Copied object +/// \return A new sfSoundBuffer object which is a copy of \a soundBuffer /// //////////////////////////////////////////////////////////// CSFML_API sfSoundBuffer* sfSoundBuffer_Copy(sfSoundBuffer* soundBuffer); //////////////////////////////////////////////////////////// -/// Destroy an existing sound buffer +/// \brief Destroy a sound buffer /// -/// \param soundBuffer : Sound buffer to delete +/// \param soundBuffer Sound buffer to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundBuffer_Destroy(sfSoundBuffer* soundBuffer); //////////////////////////////////////////////////////////// -/// Save a sound buffer to a file +/// \brief Save a sound buffer to an audio file /// -/// \param soundBuffer : Sound buffer to save -/// \param filename : Path of the sound file to write +/// Here is a complete list of all the supported audio formats: +/// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, +/// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64. /// -/// \return sfTrue if saving has been successful +/// \param soundBuffer Sound buffer object +/// \param filename Path of the sound file to write +/// +/// \return sfTrue if saving succeeded, sfFalse if it failed /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfSoundBuffer_SaveToFile(const sfSoundBuffer* soundBuffer, const char* filename); //////////////////////////////////////////////////////////// -/// Return the samples contained in a sound buffer +/// \brief Get the array of audio samples stored in a sound buffer /// -/// \param soundBuffer : Sound buffer to get samples from +/// The format of the returned samples is 16 bits signed integer +/// (sfInt16). The total number of samples in this array +/// is given by the sfSoundBuffer_GetSamplesCount function. /// -/// \return Pointer to the array of sound samples, in 16 bits signed integer format +/// \param soundBuffer Sound buffer object +/// +/// \return Read-only pointer to the array of sound samples /// //////////////////////////////////////////////////////////// CSFML_API const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuffer); //////////////////////////////////////////////////////////// -/// Return the number of samples contained in a sound buffer +/// \brief Get the number of samples stored in a sound buffer /// -/// \param soundBuffer : Sound buffer to get samples count from +/// The array of samples can be accessed with the +/// sfSoundBuffer_GetSamples function. +/// +/// \param soundBuffer Sound buffer object /// /// \return Number of samples /// @@ -119,19 +154,26 @@ CSFML_API const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuff CSFML_API size_t sfSoundBuffer_GetSamplesCount(const sfSoundBuffer* soundBuffer); //////////////////////////////////////////////////////////// -/// Get the sample rate of a sound buffer +/// \brief Get the sample rate of a sound buffer /// -/// \param soundBuffer : Sound buffer to get sample rate from +/// The sample rate is the number of samples played per second. +/// The higher, the better the quality (for example, 44100 +/// samples/s is CD quality). /// -/// \return Sound frequency (number of samples per second) +/// \param soundBuffer Sound buffer object +/// +/// \return Sample rate (number of samples per second) /// //////////////////////////////////////////////////////////// CSFML_API unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuffer); //////////////////////////////////////////////////////////// -/// Return the number of channels of a sound buffer (1 = mono, 2 = stereo, ...) +/// \brief Get the number of channels used by a sound buffer /// -/// \param soundBuffer : Sound buffer to get channels count from +/// If the sound is mono then the number of channels will +/// be 1, 2 for stereo, etc. +/// +/// \param soundBuffer Sound buffer object /// /// \return Number of channels /// @@ -139,9 +181,9 @@ CSFML_API unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuf CSFML_API unsigned int sfSoundBuffer_GetChannelsCount(const sfSoundBuffer* soundBuffer); //////////////////////////////////////////////////////////// -/// Get the duration of a sound buffer +/// \brief Get the total duration of a sound buffer /// -/// \param soundBuffer : Sound buffer to get duration from +/// \param soundBuffer Sound buffer object /// /// \return Sound duration, in milliseconds /// diff --git a/include/SFML/Audio/SoundBufferRecorder.h b/include/SFML/Audio/SoundBufferRecorder.h index df03672..49b9d8f 100644 --- a/include/SFML/Audio/SoundBufferRecorder.h +++ b/include/SFML/Audio/SoundBufferRecorder.h @@ -33,7 +33,7 @@ //////////////////////////////////////////////////////////// -/// Construct a new sound buffer recorder +/// \brief Create a new sound buffer recorder /// /// \return A new sfSoundBufferRecorder object (NULL if failed) /// @@ -41,48 +41,62 @@ CSFML_API sfSoundBufferRecorder* sfSoundBufferRecorder_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing sound buffer recorder +/// \brief Destroy a sound buffer recorder /// -/// \param soundBufferRecorder : Sound buffer recorder to delete +/// \param soundBufferRecorder Sound buffer recorder to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundBufferRecorder_Destroy(sfSoundBufferRecorder* soundBufferRecorder); //////////////////////////////////////////////////////////// -/// Start the capture. -/// Warning : only one capture can happen at the same time +/// \brief Start the capture of a sound recorder recorder /// -/// \param soundBufferRecorder : Sound buffer recorder to start -/// \param sampleRate : Sound frequency (the more samples, the higher the 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 soundBufferRecorder Sound buffer recorder object +/// \param sampleRate Desired capture rate, in number of samples per second /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundBufferRecorder_Start(sfSoundBufferRecorder* soundBufferRecorder, unsigned int sampleRate); //////////////////////////////////////////////////////////// -/// Stop the capture +/// \brief Stop the capture of a sound recorder /// -/// \param soundBufferRecorder : Sound buffer recorder to stop +/// \param soundBufferRecorder Sound buffer recorder object /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundBufferRecorder_Stop(sfSoundBufferRecorder* soundBufferRecorder); //////////////////////////////////////////////////////////// -/// Get the sample rate of a sound buffer recorder +/// \brief Get the sample rate of a sound buffer recorder /// -/// \param soundBufferRecorder : Sound buffer recorder to get sample rate from +/// 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 Frequency, in samples per second +/// \param soundBufferRecorder Sound buffer recorder object +/// +/// \return Sample rate, in samples per second /// //////////////////////////////////////////////////////////// CSFML_API unsigned int sfSoundBufferRecorder_GetSampleRate(const sfSoundBufferRecorder* soundBufferRecorder); //////////////////////////////////////////////////////////// -/// Get the sound buffer containing the captured audio data -/// of a sound buffer recorder +/// \brief Get the sound buffer containing the captured audio data /// -/// \param soundBufferRecorder : Sound buffer recorder to get the sound buffer from +/// 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 Pointer to the sound buffer (you don't need to destroy it after use) +/// \param soundBufferRecorder Sound buffer recorder object +/// +/// \return Read-only access to the sound buffer /// //////////////////////////////////////////////////////////// CSFML_API const sfSoundBuffer* sfSoundBufferRecorder_GetBuffer(const sfSoundBufferRecorder* soundBufferRecorder); diff --git a/include/SFML/Audio/SoundRecorder.h b/include/SFML/Audio/SoundRecorder.h index ad57d9d..203eedb 100644 --- a/include/SFML/Audio/SoundRecorder.h +++ b/include/SFML/Audio/SoundRecorder.h @@ -39,13 +39,12 @@ typedef void (*sfSoundRecorderStopCallback)(void*); //////////////////////////////////////////////////////////// -/// Construct a new sound recorder with callback functions -/// for processing captured samples +/// \brief Construct a new sound recorder from callback functions /// -/// \param onStart : Callback function which will be called when a new capture starts (can be NULL) -/// \param onProcess : Callback function which will be called each time there's audio data to process -/// \param onStop : Callback function which will be called when the current capture stops (can be NULL) -/// \param userData : Data to pass to the callback function (can be NULL) +/// \param onStart Callback function which will be called when a new capture starts (can be NULL) +/// \param onProcess Callback function which will be called each time there's audio data to process +/// \param onStop Callback function which will be called when the current capture stops (can be NULL) +/// \param userData Data to pass to the callback function (can be NULL) /// /// \return A new sfSoundRecorder object (NULL if failed) /// @@ -56,46 +55,59 @@ CSFML_API sfSoundRecorder* sfSoundRecorder_Create(sfSoundRecorderStartCallback void* userData); //////////////////////////////////////////////////////////// -/// Destroy an existing sound recorder +/// \brief Destroy a sound recorder /// -/// \param soundRecorder : Sound recorder to delete +/// \param soundRecorder Sound recorder to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundRecorder_Destroy(sfSoundRecorder* soundRecorder); //////////////////////////////////////////////////////////// -/// Start the capture. -/// Warning : only one capture can happen at the same time +/// \brief Start the capture of a sound recorder /// -/// \param soundRecorder : Sound recorder to start -/// \param sampleRate : Sound frequency (the more samples, the higher the 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 soundRecorder Sound recorder object +/// \param sampleRate Desired capture rate, in number of samples per second /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundRecorder_Start(sfSoundRecorder* soundRecorder, unsigned int sampleRate); //////////////////////////////////////////////////////////// -/// Stop the capture +/// \brief Stop the capture of a sound recorder /// -/// \param soundRecorder : Sound recorder to stop +/// \param soundRecorder Sound recorder object /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundRecorder_Stop(sfSoundRecorder* soundRecorder); //////////////////////////////////////////////////////////// -/// Get the sample rate of a sound recorder +/// \brief Get the sample rate of a sound recorder /// -/// \param soundRecorder : Sound recorder to get sample rate from +/// 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 Frequency, in samples per second +/// \param soundRecorder Sound recorder object +/// +/// \return Sample rate, in samples per second /// //////////////////////////////////////////////////////////// CSFML_API unsigned int sfSoundRecorder_GetSampleRate(const sfSoundRecorder* soundRecorder); //////////////////////////////////////////////////////////// -/// Tell if the system supports sound capture. -/// If not, this class won't be usable +/// \brief Check if the system supports audio capture /// -/// \return sfTrue 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 sfSoundRecorder will fail. +/// +/// \return sfTrue if audio capture is supported, sfFalse otherwise /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfSoundRecorder_IsAvailable(void); diff --git a/include/SFML/Audio/SoundStatus.h b/include/SFML/Audio/SoundStatus.h index 18cbf28..3930cc1 100644 --- a/include/SFML/Audio/SoundStatus.h +++ b/include/SFML/Audio/SoundStatus.h @@ -31,6 +31,10 @@ #include +//////////////////////////////////////////////////////////// +/// \brief Enumeration of statuses for sounds and musics +/// +//////////////////////////////////////////////////////////// typedef enum { sfStopped, ///< Sound / music is not playing diff --git a/include/SFML/Audio/SoundStream.h b/include/SFML/Audio/SoundStream.h index a1c199e..4228c9a 100644 --- a/include/SFML/Audio/SoundStream.h +++ b/include/SFML/Audio/SoundStream.h @@ -34,8 +34,8 @@ //////////////////////////////////////////////////////////// -/// sfSoundStreamChunk defines the data to fill by the -/// OnGetData callback +/// \brief defines the data to fill by the OnGetData callback +/// //////////////////////////////////////////////////////////// typedef struct { @@ -48,15 +48,15 @@ typedef void (*sfSoundStreamSeekCallback)(sfUint32, void*); ///< //////////////////////////////////////////////////////////// -/// Construct a new sound stream +/// \brief Create a new sound stream /// -/// \param onGetData : Function called when the stream needs more data (can't be NULL) -/// \param onSeek : Function called when the stream seeks (can't be NULL) -/// \param channelsCount : Number of channels to use (1 = mono, 2 = stereo) -/// \param sampleRate : Sample rate of the sound (44100 = CD quality) -/// \param userData : Data to pass to the callback functions +/// \param onGetData Function called when the stream needs more data (can't be NULL) +/// \param onSeek Function called when the stream seeks (can't be NULL) +/// \param channelsCount Number of channels to use (1 = mono, 2 = stereo) +/// \param sampleRate Sample rate of the sound (44100 = CD quality) +/// \param userData Data to pass to the callback functions /// -/// \return A new sfSoundStream object (NULL if failed) +/// \return A new sfSoundStream object /// //////////////////////////////////////////////////////////// CSFML_API sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGetData, @@ -66,52 +66,66 @@ CSFML_API sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGet void* userData); //////////////////////////////////////////////////////////// -/// Destroy an existing sound stream +/// \brief Destroy a sound stream /// -/// \param soundStream : Sound stream to delete +/// \param soundStream Sound stream to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_Destroy(sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Start playing a sound stream +/// \brief Start or resume playing a sound stream /// -/// \param soundStream : Sound stream to play +/// This function starts the stream if it was stopped, resumes +/// it if it was paused, and restarts it from beginning if it +/// was it already playing. +/// This function uses its own thread so that it doesn't block +/// the rest of the program while the music is played. +/// +/// \param soundStream Sound stream object /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_Play(sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Pause a sound stream +/// \brief Pause a sound stream /// -/// \param soundStream : Sound stream to pause +/// This function pauses the stream if it was playing, +/// otherwise (stream already paused or stopped) it has no effect. +/// +/// \param soundStream Sound stream object /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_Pause(sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Stop playing a sound stream +/// \brief Stop playing a sound stream /// -/// \param soundStream : Sound stream to stop +/// 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 sfSoundStream_Pause). +/// +/// \param soundStream Sound stream object /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_Stop(sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Get the status of a sound stream (stopped, paused, playing) +/// \brief Get the current status of a sound stream (stopped, paused, playing) /// -/// \param soundStream : Sound stream to get the status from +/// \param soundStream Sound stream object /// -/// \return Current status of the sound stream +/// \return Current status /// //////////////////////////////////////////////////////////// CSFML_API sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Return the number of channels of a sound stream -/// (1 = mono, 2 = stereo) +/// \brief Return the number of channels of a sound stream /// -/// \param soundStream : Sound stream to get the channels count from +/// 1 channel means a mono sound, 2 means stereo, etc. +/// +/// \param soundStream Sound stream object /// /// \return Number of channels /// @@ -119,131 +133,171 @@ CSFML_API sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream CSFML_API unsigned int sfSoundStream_GetChannelsCount(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Get the sample rate of a sound stream +/// \brief Get the sample rate of a sound stream /// -/// \param soundStream : Sound stream to get the sample rate from +/// The sample rate is the number of audio samples played per +/// second. The higher, the better the quality. /// -/// \return Stream frequency (number of samples per second) +/// \param soundStream Sound stream object +/// +/// \return Sample rate, in number of samples per second /// //////////////////////////////////////////////////////////// CSFML_API unsigned int sfSoundStream_GetSampleRate(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Set the pitch of a sound stream +/// \brief Set the pitch of a sound stream /// -/// \param soundStream : Sound stream to modify -/// \param pitch : New pitch +/// The pitch represents the perceived fundamental frequency +/// of a sound; thus you can make a stream more acute or grave +/// by changing its pitch. A side effect of changing the pitch +/// is to modify the playing speed of the stream as well. +/// The default value for the pitch is 1. +/// +/// \param soundStream Sound stream object +/// \param pitch New pitch to apply to the stream /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetPitch(sfSoundStream* soundStream, float pitch); //////////////////////////////////////////////////////////// -/// Set the volume of a sound stream +/// \brief Set the volume of a sound stream /// -/// \param soundStream : Sound stream to modify -/// \param volume : Volume (in range [0, 100]) +/// The volume is a value between 0 (mute) and 100 (full volume). +/// The default value for the volume is 100. +/// +/// \param soundStream Sound stream object +/// \param volume Volume of the stream /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetVolume(sfSoundStream* soundStream, float volume); //////////////////////////////////////////////////////////// -/// Set the position of a sound stream +/// \brief Set the 3D position of a sound stream in the audio scene /// -/// \param soundStream : Sound stream to modify -/// \param x : X position of the sound stream in the world -/// \param y : Y position of the sound stream in the world -/// \param z : Z position of the sound stream in the world +/// Only streams with one channel (mono streams) can be +/// spatialized. +/// The default position of a stream is (0, 0, 0). +/// +/// \param soundStream Sound stream object +/// \param x X coordinate of the position of the stream in the scene +/// \param y Y coordinate of the position of the stream in the scene +/// \param z Z coordinate of the position of the stream in the scene /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetPosition(sfSoundStream* soundStream, float x, float y, float z); //////////////////////////////////////////////////////////// -/// Make the sound stream's position relative to the listener's -/// position, or absolute. -/// The default value is false (absolute) +/// \brief Make a sound stream's position relative to the listener or absolute /// -/// \param soundStream : Sound stream to modify -/// \param relative : True to set the position relative, false to set it absolute +/// Making a stream relative to the listener will ensure that it will always +/// be played the same way regardless the position of the listener. +/// This can be useful for non-spatialized streams, streams that are +/// produced by the listener, or streams attached to it. +/// The default value is false (position is absolute). +/// +/// \param soundStream Sound stream object +/// \param relative sfTrue to set the position relative, sfFalse to set it absolute /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetRelativeToListener(sfSoundStream* soundStream, sfBool relative); //////////////////////////////////////////////////////////// -/// Set the minimum distance - closer than this distance, -/// the listener will hear the sound stream at its maximum volume. -/// The default minimum distance is 1.0 +/// \brief Set the minimum distance of a sound stream /// -/// \param soundStream : Sound stream to modify -/// \param distance : New minimum distance for the sound stream +/// The "minimum distance" of a stream is the maximum +/// distance at which it is heard at its maximum volume. Further +/// than the minimum distance, it will start to fade out according +/// to its attenuation factor. A value of 0 ("inside the head +/// of the listener") is an invalid value and is forbidden. +/// The default value of the minimum distance is 1. +/// +/// \param soundStream Sound stream object +/// \param distance New minimum distance of the stream /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetMinDistance(sfSoundStream* soundStream, float distance); //////////////////////////////////////////////////////////// -/// Set the attenuation factor - the higher the attenuation, the -/// more the sound stream will be attenuated with distance from listener. -/// The default attenuation factor 1.0 +/// \brief Set the attenuation factor of a sound stream /// -/// \param soundStream : Sound stream to modify -/// \param attenuation : New attenuation factor for the sound stream +/// The attenuation is a multiplicative factor which makes +/// the stream more or less loud according to its distance +/// from the listener. An attenuation of 0 will produce a +/// non-attenuated stream, i.e. its volume will always be the same +/// whether it is heard from near or from far. On the other hand, +/// an attenuation value such as 100 will make the stream fade out +/// very quickly as it gets further from the listener. +/// The default value of the attenuation is 1. +/// +/// \param soundStream Sound stream object +/// \param attenuation New attenuation factor of the stream /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetAttenuation(sfSoundStream* soundStream, float attenuation); //////////////////////////////////////////////////////////// -/// Set the current playing position of a stream +/// \brief Change the current playing position of a sound stream /// -/// \param soundStream : Sound stream to modify -/// \param timeOffset : New playing position, in milliseconds +/// The playing position can be changed when the stream is +/// either paused or playing. +/// +/// \param soundStream Sound stream object +/// \param timeOffset New playing position, in milliseconds /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetPlayingOffset(sfSoundStream* soundStream, sfUint32 timeOffset); //////////////////////////////////////////////////////////// -/// Set a stream loop state +/// \brief Set whether or not a sound stream should loop after reaching the end /// -/// \param soundStream : Stream to set the loop state -/// \param loop : sfTrue to play in loop, sfFalse to play once +/// If set, the stream will restart from beginning after +/// reaching the end and so on, until it is stopped or +/// sfSoundStream_SetLoop(stream, sfFalse) is called. +/// The default looping state for sound streams is false. +/// +/// \param soundStream Sound stream object +/// \param loop sfTrue to play in loop, sfFalse to play once /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_SetLoop(sfSoundStream* soundStream, sfBool loop); //////////////////////////////////////////////////////////// -/// Get the pitch of a sound stream +/// \brief Get the pitch of a sound stream /// -/// \param soundStream : Sound stream to get the pitch from +/// \param soundStream Sound stream object /// -/// \return Pitch value +/// \return Pitch of the stream /// //////////////////////////////////////////////////////////// CSFML_API float sfSoundStream_GetPitch(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Get the volume of a sound stream +/// \brief Get the volume of a sound stream /// -/// \param soundStream : Sound stream to get the volume from +/// \param soundStream Sound stream object /// -/// \return Volume value (in range [1, 100]) +/// \return Volume of the stream, in the range [0, 100] /// //////////////////////////////////////////////////////////// CSFML_API float sfSoundStream_GetVolume(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Get the position of a sound stream +/// \brief Get the 3D position of a sound stream in the audio scene /// -/// \param soundStream : Sound stream to get the position from -/// \param x : X position of the sound stream in the world -/// \param y : Y position of the sound stream in the world -/// \param z : Z position of the sound stream in the world +/// \param soundStream Sound stream object +/// \param x X position of the stream in the world +/// \param y Y position of the stream in the world +/// \param z Z position of the stream in the world /// //////////////////////////////////////////////////////////// CSFML_API void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float* x, float* y, float* z); //////////////////////////////////////////////////////////// -/// Tell if the sound stream's position is relative to the listener's -/// position, or if it's absolute +/// \brief Tell whether a sound stream's position is relative to the +/// listener or is absolute /// -/// \param soundStream : Sound stream to check +/// \param soundStream Sound stream object /// /// \return sfTrue if the position is relative, sfFalse if it's absolute /// @@ -251,39 +305,39 @@ CSFML_API void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float CSFML_API sfBool sfSoundStream_IsRelativeToListener(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Get the minimum distance of a sound stream +/// \brief Get the minimum distance of a sound stream /// -/// \param soundStream : Sound stream to get the minimum distance from +/// \param soundStream Sound stream object /// -/// \return Minimum distance for the sound stream +/// \return Minimum distance of the stream /// //////////////////////////////////////////////////////////// CSFML_API float sfSoundStream_GetMinDistance(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Get the attenuation factor of a sound stream +/// \brief Get the attenuation factor of a sound stream /// -/// \param soundStream : Sound stream to get the attenuation factor from +/// \param soundStream Sound stream object /// -/// \return Attenuation factor for the sound stream +/// \return Attenuation factor of the stream /// //////////////////////////////////////////////////////////// CSFML_API float sfSoundStream_GetAttenuation(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Tell whether or not a stream is looping +/// \brief Tell whether or not a sound stream is in loop mode /// -/// \param soundStream : Soundstream to get the loop state from +/// \param soundStream Sound stream object /// -/// \return sfTrue if the stream is looping, sfFalse otherwise +/// \return sfTrue if the music is looping, sfFalse otherwise /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfSoundStream_GetLoop(const sfSoundStream* soundStream); //////////////////////////////////////////////////////////// -/// Get the current playing position of a sound stream +/// \brief Get the current playing position of a sound stream /// -/// \param soundStream : Sound stream to get the position from +/// \param soundStream Sound stream object /// /// \return Current playing position, in milliseconds /// diff --git a/include/SFML/Network/Ftp.h b/include/SFML/Network/Ftp.h index 54c2b24..f2754e1 100644 --- a/include/SFML/Network/Ftp.h +++ b/include/SFML/Network/Ftp.h @@ -35,7 +35,8 @@ //////////////////////////////////////////////////////////// -/// Enumerate all the FTP file transfer modes +/// \brief Enumeration of transfer modes +/// //////////////////////////////////////////////////////////// enum sfFtpTransferMode { @@ -46,8 +47,8 @@ enum sfFtpTransferMode //////////////////////////////////////////////////////////// -/// Enumerate all the valid status codes returned in -/// a FTP response +/// \brief Status codes possibly returned by a FTP response +/// //////////////////////////////////////////////////////////// enum sfFtpStatus { @@ -113,28 +114,30 @@ enum sfFtpStatus //////////////////////////////////////////////////////////// -/// Destroy an existing Ftp listing response +/// \brief Destroy a FTP listing response /// -/// \param ftpListingResponse : Ftp listing response to destroy +/// \param ftpListingResponse Ftp listing response to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfFtpListingResponse_Destroy(sfFtpListingResponse* ftpListingResponse); //////////////////////////////////////////////////////////// -/// Convenience function to check if the response status code -/// means a success +/// \brief Check if a FTP listing response status code means a success /// -/// \param ftpListingResponse : Ftp listing response +/// This function is defined for convenience, it is +/// equivalent to testing if the status code is < 400. /// -/// \return sfTrue if status is success (code < 400) +/// \param ftpListingResponse Ftp listing response +/// +/// \return sfTrue if the status is a success, sfFalse if it is a failure /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListingResponse); //////////////////////////////////////////////////////////// -/// Get the response status code +/// \brief Get the status code of a FTP listing response /// -/// \param ftpListingResponse : Ftp listing response +/// \param ftpListingResponse Ftp listing response /// /// \return Status code /// @@ -142,9 +145,9 @@ CSFML_API sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListin CSFML_API sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* ftpListingResponse); //////////////////////////////////////////////////////////// -/// Get the full message contained in the response +/// \brief Get the full message contained in a FTP listing response /// -/// \param ftpListingResponse : Ftp listing response +/// \param ftpListingResponse Ftp listing response /// /// \return The response message /// @@ -152,49 +155,51 @@ CSFML_API sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* CSFML_API const char* sfFtpListingResponse_GetMessage(const sfFtpListingResponse* ftpListingResponse); //////////////////////////////////////////////////////////// -/// Get the number of filenames in the listing +/// \brief Return the number of filenames contained in a FTP listing response /// -/// \param ftpListingResponse : Ftp listing response +/// \param ftpListingResponse Ftp listing response /// -/// \return Total number of filenames +/// \return Total number of filenames available /// //////////////////////////////////////////////////////////// CSFML_API size_t sfFtpListingResponse_GetCount(const sfFtpListingResponse* ftpListingResponse); //////////////////////////////////////////////////////////// -/// Get the Index-th filename in the directory +/// \brief Return a filename contained in a FTP listing response /// -/// \param ftpListingResponse : Ftp listing response -/// \param index : Index of the filename to get +/// \param ftpListingResponse Ftp listing response +/// \param index Index of the filename to get (in range [0 .. GetCount]) /// -/// \return Index-th filename +/// \return Array containing the requested filenames /// //////////////////////////////////////////////////////////// CSFML_API const char* sfFtpListingResponse_GetFilename(const sfFtpListingResponse* ftpListingResponse, size_t index); //////////////////////////////////////////////////////////// -/// Destroy an existing Ftp directory response +/// \brief Destroy a FTP directory response /// -/// \param ftpDirectoryResponse : Ftp directory response to destroy +/// \param ftpDirectoryResponse Ftp directory response to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfFtpDirectoryResponse_Destroy(sfFtpDirectoryResponse* ftpDirectoryResponse); //////////////////////////////////////////////////////////// -/// Convenience function to check if the response status code -/// means a success +/// \brief Check if a FTP directory response status code means a success /// -/// \param ftpDirectoryResponse : Ftp directory response +/// This function is defined for convenience, it is +/// equivalent to testing if the status code is < 400. /// -/// \return sfTrue if status is success (code < 400) +/// \param ftpDirectoryResponse Ftp directory response +/// +/// \return sfTrue if the status is a success, sfFalse if it is a failure /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDirectoryResponse); //////////////////////////////////////////////////////////// -/// Get the response status code +/// \brief Get the status code of a FTP directory response /// -/// \param ftpDirectoryResponse : Ftp directory response +/// \param ftpDirectoryResponse Ftp directory response /// /// \return Status code /// @@ -202,9 +207,9 @@ CSFML_API sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDi CSFML_API sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryResponse* ftpDirectoryResponse); //////////////////////////////////////////////////////////// -/// Get the full message contained in the response +/// \brief Get the full message contained in a FTP directory response /// -/// \param ftpDirectoryResponse : Ftp directory response +/// \param ftpDirectoryResponse Ftp directory response /// /// \return The response message /// @@ -212,9 +217,9 @@ CSFML_API sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryRespo CSFML_API const char* sfFtpDirectoryResponse_GetMessage(const sfFtpDirectoryResponse* ftpDirectoryResponse); //////////////////////////////////////////////////////////// -/// Get the directory returned in the response +/// \brief Get the directory returned in a FTP directory response /// -/// \param ftpDirectoryResponse : Ftp directory response +/// \param ftpDirectoryResponse Ftp directory response /// /// \return Directory name /// @@ -223,28 +228,30 @@ CSFML_API const char* sfFtpDirectoryResponse_GetDirectory(const sfFtpDirectoryRe //////////////////////////////////////////////////////////// -/// Destroy an existing Ftp response +/// \brief Destroy a FTP response /// -/// \param ftpResponse : Ftp response to destroy +/// \param ftpResponse Ftp response to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfFtpResponse_Destroy(sfFtpResponse* ftpResponse); //////////////////////////////////////////////////////////// -/// Convenience function to check if the response status code -/// means a success +/// \brief Check if a FTP response status code means a success /// -/// \param ftpResponse : Ftp response +/// This function is defined for convenience, it is +/// equivalent to testing if the status code is < 400. /// -/// \return sfTrue if status is success (code < 400) +/// \param ftpResponse Ftp response object +/// +/// \return sfTrue if the status is a success, sfFalse if it is a failure /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse); //////////////////////////////////////////////////////////// -/// Get the response status code +/// \brief Get the status code of a FTP response /// -/// \param ftpResponse : Ftp response +/// \param ftpResponse Ftp response object /// /// \return Status code /// @@ -252,9 +259,9 @@ CSFML_API sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse); CSFML_API sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse); //////////////////////////////////////////////////////////// -/// Get the full message contained in the response +/// \brief Get the full message contained in a FTP response /// -/// \param ftpResponse : Ftp response +/// \param ftpResponse Ftp response object /// /// \return The response message /// @@ -262,28 +269,37 @@ CSFML_API sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse); CSFML_API const char* sfFtpResponse_GetMessage(const sfFtpResponse* ftpResponse); //////////////////////////////////////////////////////////// -/// Construct a new Ftp +/// \brief Create a new Ftp object /// -/// \return Pointer to the new Ftp +/// \return A new sfFtp object /// //////////////////////////////////////////////////////////// CSFML_API sfFtp* sfFtp_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing Ftp +/// \brief Destroy a Ftp object /// -/// \param ftp : Ftp to destroy +/// \param ftp Ftp object to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfFtp_Destroy(sfFtp* ftp); //////////////////////////////////////////////////////////// -/// Connect to the specified FTP server +/// \brief Connect to the specified FTP server /// -/// \param ftp : Ftp instance -/// \param server : FTP server to connect to -/// \param port : Port used for connection (21 by default, standard FTP port) -/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout) +/// The port should be 21, which is the standard +/// port used by the FTP protocol. You shouldn't use a different +/// value, unless you really know what you do. +/// This function tries to connect to the server so it may take +/// a while to complete, especially if the server is not +/// reachable. To avoid blocking your application for too long, +/// you can use a timeout. Using 0 means that the +/// system timeout will be used (which is usually pretty long). +/// +/// \param ftp Ftp object +/// \param server Name or address of the FTP server to connect to +/// \param port Port used for the connection +/// \param timeout Maximum time to wait, in milliseconds /// /// \return Server response to the request /// @@ -291,9 +307,12 @@ CSFML_API void sfFtp_Destroy(sfFtp* ftp); CSFML_API sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned short port, sfUint32 timeout); //////////////////////////////////////////////////////////// -/// Log in using anonymous account +/// \brief Log in using an anonymous account /// -/// \param ftp : Ftp instance +/// Logging in is mandatory after connecting to the server. +/// Users that are not logged in cannot perform any operation. +/// +/// \param ftp Ftp object /// /// \return Server response to the request /// @@ -301,11 +320,14 @@ CSFML_API sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned CSFML_API sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp); //////////////////////////////////////////////////////////// -/// Log in using a username and a password +/// \brief Log in using a username and a password /// -/// \param ftp : Ftp instance -/// \param userName : User name -/// \param password : Password +/// Logging in is mandatory after connecting to the server. +/// Users that are not logged in cannot perform any operation. +/// +/// \param ftp Ftp object +/// \param name User name +/// \param password Password /// /// \return Server response to the request /// @@ -313,9 +335,9 @@ CSFML_API sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp); CSFML_API sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const char* password); //////////////////////////////////////////////////////////// -/// Close the connection with FTP server +/// \brief Close the connection with the server /// -/// \param ftp : Ftp instance +/// \param ftp Ftp object /// /// \return Server response to the request /// @@ -323,9 +345,12 @@ CSFML_API sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const cha CSFML_API sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp); //////////////////////////////////////////////////////////// -/// Send a null command just to prevent from being disconnected +/// \brief Send a null command to keep the connection alive /// -/// \param ftp : Ftp instance +/// This command is useful because the server may close the +/// connection automatically if no command is sent. +/// +/// \param ftp Ftp object /// /// \return Server response to the request /// @@ -333,9 +358,12 @@ CSFML_API sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp); CSFML_API sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp); //////////////////////////////////////////////////////////// -/// Get the current working directory +/// \brief Get the current working directory /// -/// \param ftp : Ftp instance +/// The working directory is the root path for subsequent +/// operations involving directories and/or filenames. +/// +/// \param ftp Ftp object /// /// \return Server response to the request /// @@ -343,11 +371,15 @@ CSFML_API sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp); CSFML_API sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp); //////////////////////////////////////////////////////////// -/// Get the contents of the given directory -/// (subdirectories and files) +/// \brief Get the contents of the given directory /// -/// \param ftp : Ftp instance -/// \param directory : Directory to list ("" by default, the current one) +/// This function retrieves the sub-directories and files +/// contained in the given directory. It is not recursive. +/// The \a directory parameter is relative to the current +/// working directory. +/// +/// \param ftp Ftp object +/// \param directory Directory to list /// /// \return Server response to the request /// @@ -355,10 +387,12 @@ CSFML_API sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp); CSFML_API sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char* directory); //////////////////////////////////////////////////////////// -/// Change the current working directory +/// \brief Change the current working directory /// -/// \param ftp : Ftp instance -/// \param directory : New directory, relative to the current one +/// The new directory must be relative to the current one. +/// +/// \param ftp Ftp object +/// \param directory New working directory /// /// \return Server response to the request /// @@ -366,9 +400,9 @@ CSFML_API sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char CSFML_API sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory); //////////////////////////////////////////////////////////// -/// Go to the parent directory of the current one +/// \brief Go to the parent directory of the current one /// -/// \param ftp : Ftp instance +/// \param ftp Ftp object /// /// \return Server response to the request /// @@ -376,10 +410,13 @@ CSFML_API sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory CSFML_API sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp); //////////////////////////////////////////////////////////// -/// Create a new directory +/// \brief Create a new directory /// -/// \param ftp : Ftp instance -/// \param name : Name of the directory to create +/// The new directory is created as a child of the current +/// working directory. +/// +/// \param ftp Ftp object +/// \param name Name of the directory to create /// /// \return Server response to the request /// @@ -387,10 +424,15 @@ CSFML_API sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp); CSFML_API sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name); //////////////////////////////////////////////////////////// -/// Remove an existing directory +/// \brief Remove an existing directory /// -/// \param ftp : Ftp instance -/// \param name : Name of the directory to remove +/// The directory to remove must be relative to the +/// current working directory. +/// Use this function with caution, the directory will +/// be removed permanently! +/// +/// \param ftp Ftp object +/// \param name Name of the directory to remove /// /// \return Server response to the request /// @@ -398,11 +440,14 @@ CSFML_API sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name); CSFML_API sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name); //////////////////////////////////////////////////////////// -/// Rename a file +/// \brief Rename an existing file /// -/// \param ftp : Ftp instance -/// \param file : File to rename -/// \param newName : New name +/// The filenames must be relative to the current working +/// directory. +/// +/// \param ftp Ftp object +/// \param file File to rename +/// \param newName New name of the file /// /// \return Server response to the request /// @@ -410,10 +455,15 @@ CSFML_API sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name); CSFML_API sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const char* newName); //////////////////////////////////////////////////////////// -/// Remove an existing file +/// \brief Remove an existing file /// -/// \param ftp : Ftp instance -/// \param name : File to remove +/// The file name must be relative to the current working +/// directory. +/// Use this function with caution, the file will be +/// removed permanently! +/// +/// \param ftp Ftp object +/// \param name File to remove /// /// \return Server response to the request /// @@ -421,12 +471,17 @@ CSFML_API sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const ch CSFML_API sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name); //////////////////////////////////////////////////////////// -/// Download a file from the server +/// \brief Download a file from a FTP server /// -/// \param ftp : Ftp instance -/// \param distantFile : Path of the distant file to download -/// \param destPath : Where to put to file on the local computer -/// \param mode : Transfer mode (binary by default) +/// The filename of the distant file is relative to the +/// current working directory of the server, and the local +/// destination path is relative to the current directory +/// of your application. +/// +/// \param ftp Ftp object +/// \param remoteFile Filename of the distant file to download +/// \param localPath Where to put to file on the local computer +/// \param mode Transfer mode /// /// \return Server response to the request /// @@ -434,12 +489,17 @@ CSFML_API sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name); CSFML_API sfFtpResponse* sfFtp_Download(sfFtp* ftp, const char* distantFile, const char* destPath, sfFtpTransferMode mode); //////////////////////////////////////////////////////////// -/// Upload a file to the server +/// \brief Upload a file to a FTP server /// -/// \param ftp : Ftp instance -/// \param localFile : Path of the local file to upload -/// \param destPath : Where to put to file on the server -/// \param mode : Transfer mode (binary by default) +/// The name of the local file is relative to the current +/// working directory of your application, and the +/// remote path is relative to the current directory of the +/// FTP server. +/// +/// \param ftp Ftp object +/// \param localFile Path of the local file to upload +/// \param remotePath Where to put to file on the server +/// \param mode Transfer mode /// /// \return Server response to the request /// diff --git a/include/SFML/Network/Http.h b/include/SFML/Network/Http.h index 2cb8468..e75f1e5 100644 --- a/include/SFML/Network/Http.h +++ b/include/SFML/Network/Http.h @@ -33,7 +33,8 @@ //////////////////////////////////////////////////////////// -/// Enumerate the available HTTP methods for a request +/// \brief Enumerate the available HTTP methods for a request +/// //////////////////////////////////////////////////////////// enum sfHttpMethod { @@ -44,8 +45,8 @@ enum sfHttpMethod //////////////////////////////////////////////////////////// -/// Enumerate all the valid status codes returned in -/// a HTTP response +/// \brief Enumerate all the valid status codes for a response +/// //////////////////////////////////////////////////////////// enum sfHttpStatus { @@ -80,175 +81,213 @@ enum sfHttpStatus //////////////////////////////////////////////////////////// -/// Construct a new Http request +/// \brief Create a new HTTP request /// -/// \return Pointer to the new Http request +/// \return A new sfHttpRequest object /// //////////////////////////////////////////////////////////// CSFML_API sfHttpRequest* sfHttpRequest_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing Http request +/// \brief Destroy a HTTP request /// -/// \param httpRequest : Http request to destroy +/// \param httpRequest HTTP request to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfHttpRequest_Destroy(sfHttpRequest* httpRequest); //////////////////////////////////////////////////////////// -/// Set the value of a field; the field is added if it doesn't exist +/// \brief Set the value of a header field of a HTTP request /// -/// \param httpRequest : Http request to modify -/// \param field : Name of the field to set (case-insensitive) -/// \param value : Value of the field +/// The field is created if it doesn't exist. The name of +/// the field is case insensitive. +/// By default, a request doesn't contain any field (but the +/// mandatory fields are added later by the HTTP client when +/// sending the request). +/// +/// \param httpRequest HTTP request +/// \param field Name of the field to set +/// \param value Value of the field /// //////////////////////////////////////////////////////////// CSFML_API void sfHttpRequest_SetField(sfHttpRequest* httpRequest, const char* field, const char* value); //////////////////////////////////////////////////////////// -/// Set the request method. -/// This parameter is sfHttpGet by default +/// \brief Set a HTTP request method /// -/// \param httpRequest : Http request to modify -/// \param method : Method to use for the request +/// See the sfHttpMethod enumeration for a complete list of all +/// the availale methods. +/// The method is sfHttpGet by default. +/// +/// \param httpRequest HTTP request +/// \param method Method to use for the request /// //////////////////////////////////////////////////////////// CSFML_API void sfHttpRequest_SetMethod(sfHttpRequest* httpRequest, sfHttpMethod method); //////////////////////////////////////////////////////////// -/// Set the target URI of the request. -/// This parameter is "/" by default +/// \brief Set a HTTP request URI /// -/// \param httpRequest : Http request to modify -/// \param URI : URI to request, local to the host +/// The URI is the resource (usually a web page or a file) +/// that you want to get or post. +/// The URI is "/" (the root page) by default. +/// +/// \param httpRequest HTTP request +/// \param uri URI to request, relative to the host /// //////////////////////////////////////////////////////////// CSFML_API void sfHttpRequest_SetUri(sfHttpRequest* httpRequest, const char* uri); //////////////////////////////////////////////////////////// -/// Set the HTTP version of the request. -/// This parameter is 1.0 by default +/// \brief Set the HTTP version of a HTTP request /// -/// \param httpRequest : Http request to modify -/// \param major : Major version number -/// \param minor : Minor version number +/// The HTTP version is 1.0 by default. +/// +/// \param httpRequest HTTP request +/// \param major Major HTTP version number +/// \param minor Minor HTTP version number /// //////////////////////////////////////////////////////////// CSFML_API void sfHttpRequest_SetHttpVersion(sfHttpRequest* httpRequest, unsigned int major, unsigned int minor); //////////////////////////////////////////////////////////// -/// Set the body of the request. This parameter is optional and -/// makes sense only for POST requests. -/// This parameter is empty by default +/// \brief Set the body of a HTTP request /// -/// \param httpRequest : Http request to modify -/// \param body : Content of the request body +/// The body of a request is optional and only makes sense +/// for POST requests. It is ignored for all other methods. +/// The body is empty by default. +/// +/// \param httpRequest HTTP request +/// \param body Content of the body /// //////////////////////////////////////////////////////////// CSFML_API void sfHttpRequest_SetBody(sfHttpRequest* httpRequest, const char* body); //////////////////////////////////////////////////////////// -/// Destroy an existing Http response +/// \brief Destroy a HTTP response /// -/// \param httpResponse : Http response to destroy +/// \param httpResponse HTTP response to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfHttpResponse_Destroy(sfHttpResponse* httpResponse); //////////////////////////////////////////////////////////// -/// Get the value of a field; returns NULL if the field doesn't exist +/// \brief Get the value of a field of a HTTP response /// -/// \param httpResponse : Http response -/// \param field : Field to get +/// If the field \a field is not found in the response header, +/// the empty string is returned. This function uses +/// case-insensitive comparisons. /// -/// \return Value of the field (NULL if it doesn't exist) +/// \param httpResponse HTTP response +/// \param field Name of the field to get +/// +/// \return Value of the field, or empty string if not found /// //////////////////////////////////////////////////////////// CSFML_API const char* sfHttpResponse_GetField(const sfHttpResponse* httpResponse, const char* field); //////////////////////////////////////////////////////////// -/// Get the status of a response +/// \brief Get the status code of a HTTP reponse /// -/// \param httpResponse : Http response +/// The status code should be the first thing to be checked +/// after receiving a response, it defines whether it is a +/// success, a failure or anything else (see the sfHttpStatus +/// enumeration). /// -/// \return Status of the response +/// \param httpResponse HTTP response +/// +/// \return Status code of the response /// //////////////////////////////////////////////////////////// CSFML_API sfHttpStatus sfHttpResponse_GetStatus(const sfHttpResponse* httpResponse); //////////////////////////////////////////////////////////// -/// Get the major HTTP version of a response +/// \brief Get the major HTTP version number of a HTTP response /// -/// \param httpResponse : Http response +/// \param httpResponse HTTP response /// -/// \return HTTP major version of the response +/// \return Major HTTP version number /// //////////////////////////////////////////////////////////// CSFML_API unsigned int sfHttpResponse_GetMajorVersion(const sfHttpResponse* httpResponse); //////////////////////////////////////////////////////////// -/// Get the minor HTTP version of a response +/// \brief Get the minor HTTP version number of a HTTP response /// -/// \param httpResponse : Http response +/// \param httpResponse HTTP response /// -/// \return HTTP minor version of the response +/// \return Minor HTTP version number /// //////////////////////////////////////////////////////////// CSFML_API unsigned int sfHttpResponse_GetMinorVersion(const sfHttpResponse* httpResponse); //////////////////////////////////////////////////////////// -/// Get the body of the response. The body can contain : -/// - the requested page (for GET requests) -/// - a response from the server (for POST requests) -/// - nothing (for HEAD requests) -/// - an error message (in case of an error) +/// \brief Get the body of a HTTP response /// -/// \param httpResponse : Http response +/// The body of a response may contain: +/// \li the requested page (for GET requests) +/// \li a response from the server (for POST requests) +/// \li nothing (for HEAD requests) +/// \li an error message (in case of an error) /// -/// \return Body of the response (empty string if no body) +/// \param httpResponse HTTP response +/// +/// \return The response body /// //////////////////////////////////////////////////////////// CSFML_API const char* sfHttpResponse_GetBody(const sfHttpResponse* httpResponse); //////////////////////////////////////////////////////////// -/// Construct a new Http object +/// \brief Create a new Http object /// -/// \return Pointer to the new Http +/// \return A new sfHttp object /// //////////////////////////////////////////////////////////// CSFML_API sfHttp* sfHttp_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing Http object +/// \brief Destroy a Http object /// -/// \param Http : Http to destroy +/// \param http Http object to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfHttp_Destroy(sfHttp* http); //////////////////////////////////////////////////////////// -/// Set the target host of a Http server +/// \brief Set the target host of a HTTP object /// -/// \param http : Http object -/// \param host : Web server to connect to -/// \param port : Port to use for connection (0 to use the standard port of the protocol used) +/// This function just stores the host address and port, it +/// doesn't actually connect to it until you send a request. +/// If the port is 0, it means that the HTTP client will use +/// the right port according to the protocol used +/// (80 for HTTP, 443 for HTTPS). You should +/// leave it like this unless you really need a port other +/// than the standard one, or use an unknown protocol. +/// +/// \param http Http object +/// \param host Web server to connect to +/// \param port Port to use for connection /// //////////////////////////////////////////////////////////// CSFML_API void sfHttp_SetHost(sfHttp* http, const char* host, unsigned short port); //////////////////////////////////////////////////////////// -/// Send a HTTP request and return the server's response. -/// You must be connected to a host before sending requests. -/// Any missing mandatory header field will be added with an appropriate value. -/// Warning : this function waits for the server's response and may +/// \brief Send a HTTP request and return the server's response. +/// +/// You must have a valid host before sending a request (see sfHttp_SetHost). +/// Any missing mandatory header field in the request will be added +/// with an appropriate value. +/// Warning: this function waits for the server's response and may /// not return instantly; use a thread if you don't want to block your -/// application. +/// application, or use a timeout to limit the time to wait. A value +/// of 0 means that the client will use the system defaut timeout +/// (which is usually pretty long). /// -/// \param http : Http object -/// \param request : Request to send -/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout) +/// \param http Http object +/// \param request Request to send +/// \param timeout Maximum time to wait, in milliseconds /// -/// \return Server's response, or NULL if request is invalid +/// \return Server's response /// //////////////////////////////////////////////////////////// CSFML_API sfHttpResponse* sfHttp_SendRequest(sfHttp* http, const sfHttpRequest* request, sfUint32 timeout); diff --git a/include/SFML/Network/IpAddress.h b/include/SFML/Network/IpAddress.h index 5571a22..c38beaa 100644 --- a/include/SFML/Network/IpAddress.h +++ b/include/SFML/Network/IpAddress.h @@ -32,7 +32,8 @@ //////////////////////////////////////////////////////////// -/// sfIpAddress provides easy manipulation of IP v4 addresses +/// \brief Encapsulate an IPv4 network address +/// //////////////////////////////////////////////////////////// typedef struct { @@ -41,22 +42,30 @@ typedef struct //////////////////////////////////////////////////////////// -/// Construct an address from a string +/// \brief Create an address from a string /// -/// \param string : IP address ("xxx.xxx.xxx.xxx") or network name +/// Here \a address can be either a decimal address +/// (ex: "192.168.1.56") or a network name (ex: "localhost"). +/// +/// \param address IP address or network name /// /// \return Resulting address /// //////////////////////////////////////////////////////////// -CSFML_API sfIpAddress sfIpAddress_FromString(const char* string); +CSFML_API sfIpAddress sfIpAddress_FromString(const char* address); //////////////////////////////////////////////////////////// -/// Construct an address from 4 bytes +/// \brief Create an address from 4 bytes /// -/// \param byte0 : First byte of the address -/// \param byte1 : Second byte of the address -/// \param byte2 : Third byte of the address -/// \param byte3 : Fourth byte of the address +/// Calling sfIpAddress_FromBytes(a, b, c, d) is equivalent +/// to calling sfIpAddress_FromString("a.b.c.d"), but safer +/// as it doesn't have to parse a string to get the address +/// components. +/// +/// \param byte0 First byte of the address +/// \param byte1 Second byte of the address +/// \param byte2 Third byte of the address +/// \param byte3 Fourth byte of the address /// /// \return Resulting address /// @@ -64,55 +73,88 @@ CSFML_API sfIpAddress sfIpAddress_FromString(const char* string); CSFML_API sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, sfUint8 byte3); //////////////////////////////////////////////////////////// -/// Construct the address from a 32-bits integer +/// \brief Construct an address from a 32-bits integer /// -/// \param address : 4 bytes of the address packed into a 32-bits integer +/// This function uses the internal representation of +/// the address directly. It should be used for optimization +/// purposes, and only if you got that representation from +/// sfIpAddress_ToInteger. +/// +/// \param address 4 bytes of the address packed into a 32-bits integer +/// +/// \return Resulting address /// //////////////////////////////////////////////////////////// CSFML_API sfIpAddress sfIpAddress_FromInteger(sfUint32 address); //////////////////////////////////////////////////////////// -/// Get a string representation of an address +/// \brief Get a string representation of an address /// -/// \param address : Address to convert -/// \param string : Char array to fill (size must be >= 16) +/// The returned string is the decimal representation of the +/// IP address (like "192.168.1.56"), even if it was constructed +/// from a host name. +/// +/// \param address Address object +/// +/// \return String representation of the address /// //////////////////////////////////////////////////////////// CSFML_API void sfIpAddress_ToString(sfIpAddress address, char* string); //////////////////////////////////////////////////////////// -/// Get an integer representation of the address +/// \brief Get an integer representation of the address /// -/// \param address : Address to convert +/// The returned number is the internal representation of the +/// address, and should be used for optimization purposes only +/// (like sending the address through a socket). +/// The integer produced by this function can then be converted +/// back to a sfIpAddress with sfIpAddress_FromInteger. /// -/// \return 32-bits integer containing the 4 bytes of the address, in system endianness +/// \param address Address object +/// +/// \return 32-bits unsigned integer representation of the address /// //////////////////////////////////////////////////////////// CSFML_API sfUint32 sfIpAddress_ToInteger(sfIpAddress address); //////////////////////////////////////////////////////////// -/// Get the computer's local IP address (from the LAN point of view) +/// \brief Get the computer's local address /// -/// \return Local IP address +/// The local address is the address of the computer from the +/// LAN point of view, i.e. something like 192.168.1.56. It is +/// meaningful only for communications over the local network. +/// Unlike sfIpAddress_GetPublicAddress, this function is fast +/// and may be used safely anywhere. +/// +/// \return Local IP address of the computer /// //////////////////////////////////////////////////////////// CSFML_API sfIpAddress sfIpAddress_GetLocalAddress(void); //////////////////////////////////////////////////////////// -/// Get the computer's public IP address (from the web point of view). +/// \brief Get the computer's public address +/// +/// The public address is the address of the computer from the +/// internet point of view, i.e. something like 89.54.1.169. +/// It is necessary for communications over the world wide web. /// The only way to get a public address is to ask it to a -/// distant website ; as a consequence, this function may be -/// very slow -- use it as few as possible ! +/// distant website; as a consequence, this function depends on +/// both your network connection and the server, and may be +/// very slow. You should use it as few as possible. Because +/// this function depends on the network connection and on a distant +/// server, you may use a time limit if you don't want your program +/// to be possibly stuck waiting in case there is a problem; use +/// 0 to deactivate this limit. /// -/// \param timeout : Maximum time to wait, in milliseconds (use 0 for no timeout) +/// \param timeout Maximum time to wait, in milliseconds /// -/// \return Public IP address +/// \return Public IP address of the computer /// //////////////////////////////////////////////////////////// CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout); //////////////////////////////////////////////////////////// -/// Get the computer's loopback address +/// \brief Get the computer's loopback address /// /// \return Local host IP address (127.0.0.1, or "localhost") /// @@ -120,7 +162,7 @@ CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout); CSFML_API sfIpAddress sfIpAddress_LocalHost(void); //////////////////////////////////////////////////////////// -/// Get the empty/invalid address +/// \brief Get the empty/invalid address /// /// \return Empty object that represents invalid addresses /// diff --git a/include/SFML/Network/Packet.h b/include/SFML/Network/Packet.h index 01b548d..c2b0357 100644 --- a/include/SFML/Network/Packet.h +++ b/include/SFML/Network/Packet.h @@ -34,7 +34,7 @@ //////////////////////////////////////////////////////////// -/// Create a new empty packet +/// \brief Create a new packet /// /// \return A new sfPacket object /// @@ -42,47 +42,52 @@ CSFML_API sfPacket* sfPacket_Create(void); //////////////////////////////////////////////////////////// -/// Copy an existing packet +/// \brief Create a new packet by copying an existing one /// -/// \param packet : Packet to copy +/// \param packet Packet to copy /// -/// \return Copied object +/// \return A new sfPacket object which is a copy of \a packet /// //////////////////////////////////////////////////////////// CSFML_API sfPacket* sfPacket_Copy(sfPacket* packet); //////////////////////////////////////////////////////////// -/// Destroy an existing packet +/// \brief Destroy a packet /// -/// \param packet : Packet to delete +/// \param packet Packet to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfPacket_Destroy(sfPacket* packet); //////////////////////////////////////////////////////////// -/// Append data to the end of a packet +/// \brief Append data to the end of a packet /// -/// \param packet : Packet to fill -/// \param data : Pointer to the bytes to append -/// \param sizeInBytes : Number of bytes to append +/// \param packet Packet object +/// \param data Pointer to the sequence of bytes to append +/// \param sizeInBytes Number of bytes to append /// //////////////////////////////////////////////////////////// CSFML_API void sfPacket_Append(sfPacket* packet, const void* data, size_t sizeInBytes); //////////////////////////////////////////////////////////// -/// Clear all the data of a packet +/// \brief Clear a packet /// -/// \param packet : Packet to clear +/// After calling Clear, the packet is empty. +/// +/// \param packet Packet object /// /////////////////////////////////////////////////////////// CSFML_API void sfPacket_Clear(sfPacket* packet); //////////////////////////////////////////////////////////// -/// Get a pointer to the data contained in a packet -/// Warning : the returned pointer may be invalid after you -/// append data to the packet +/// \brief Get a pointer to the data contained in a packet /// -/// \param packet : Packet to get data from +/// Warning: the returned pointer may become invalid after +/// you append data to the packet, therefore it should never +/// be stored. +/// The return pointer is NULL if the packet is empty. +/// +/// \param packet Packet object /// /// \return Pointer to the data /// @@ -90,9 +95,12 @@ CSFML_API void sfPacket_Clear(sfPacket* packet); CSFML_API const char* sfPacket_GetData(const sfPacket* packet); //////////////////////////////////////////////////////////// -/// Get the size of the data contained in a packet +/// \brief Get the size of the data contained in a packet /// -/// \param packet : Packet to get data size from +/// This function returns the number of bytes pointed to by +/// what sfPacket_GetData returns. +/// +/// \param packet Packet object /// /// \return Data size, in bytes /// @@ -100,19 +108,29 @@ CSFML_API const char* sfPacket_GetData(const sfPacket* packet); CSFML_API size_t sfPacket_GetDataSize(const sfPacket* packet); //////////////////////////////////////////////////////////// -/// Tell if the reading position has reached the end of the packet +/// \brief Tell if the reading position has reached the +/// end of a packet /// -/// \param packet : Packet to check +/// This function is useful to know if there is some data +/// left to be read, without actually reading it. /// -/// \return sfTrue if all data have been read into the packet +/// \param packet Packet object +/// +/// \return sfTrue if all data was read, sfFalse otherwise /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfPacket_EndOfPacket(const sfPacket* packet); //////////////////////////////////////////////////////////// -/// Return the validity of packet +/// \brief Test the validity of a packet, for reading /// -/// \param packet : Packet to check +/// This function allows to test the packet, to check if +/// a reading operation was successful. +/// +/// A packet will be in an invalid state if it has no more +/// data to read. +/// +/// \param packet Packet object /// /// \return sfTrue if last data extraction from packet was successful /// @@ -120,9 +138,9 @@ CSFML_API sfBool sfPacket_EndOfPacket(const sfPacket* packet); CSFML_API sfBool sfPacket_CanRead(const sfPacket* packet); //////////////////////////////////////////////////////////// -/// Functions to extract data from a packet +/// \brief Functions to extract data from a packet /// -/// \param packet : Packet to read +/// \param packet Packet object /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfPacket_ReadBool(sfPacket* packet); @@ -138,9 +156,9 @@ CSFML_API void sfPacket_ReadString(sfPacket* packet, char* string); CSFML_API void sfPacket_ReadWideString(sfPacket* packet, wchar_t* string); //////////////////////////////////////////////////////////// -/// Functions to insert data into a packet +/// \brief Functions to insert data into a packet /// -/// \param packet : Packet to write +/// \param packet Packet object /// //////////////////////////////////////////////////////////// CSFML_API void sfPacket_WriteBool(sfPacket* packet, sfBool); diff --git a/include/SFML/Network/SocketSelector.h b/include/SFML/Network/SocketSelector.h index 10fe73f..c941185 100644 --- a/include/SFML/Network/SocketSelector.h +++ b/include/SFML/Network/SocketSelector.h @@ -33,36 +33,40 @@ //////////////////////////////////////////////////////////// -/// Create a new selector +/// \brief Create a new selector /// -/// \return A new sfSelector object +/// \return A new sfSocketSelector object /// //////////////////////////////////////////////////////////// CSFML_API sfSocketSelector* sfSocketSelector_Create(void); //////////////////////////////////////////////////////////// -/// Copy an existing selector +/// \brief Create a new socket selector by copying an existing one /// -/// \param selector : Selector to copy +/// \param selector Socket selector to copy /// -/// \return Copied object +/// \return A new sfSocketSelector object which is a copy of \a selector /// //////////////////////////////////////////////////////////// CSFML_API sfSocketSelector* sfSocketSelector_Copy(sfSocketSelector* selector); //////////////////////////////////////////////////////////// -/// Destroy an existing selector +/// \brief Destroy a socket selector /// -/// \param selector : Selector to delete +/// \param selector Socket selector to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfSocketSelector_Destroy(sfSocketSelector* selector); //////////////////////////////////////////////////////////// -/// Add a socket to watch to a selector +/// \brief Add a new socket to a socket selector /// -/// \param selector : Selector to add the socket to -/// \param socket : Socket to add +/// This function keeps a weak pointer to the socket, +/// so you have to make sure that the socket is not destroyed +/// while it is stored in the selector. +/// +/// \param selector Socket selector object +/// \param socket Pointer to the socket to add /// //////////////////////////////////////////////////////////// CSFML_API void sfSocketSelector_AddTcpListener(sfSocketSelector* selector, sfTcpListener* socket); @@ -70,10 +74,13 @@ CSFML_API void sfSocketSelector_AddTcpSocket(sfSocketSelector* selector, sfTcpSo CSFML_API void sfSocketSelector_AddUdpSocket(sfSocketSelector* selector, sfUdpSocket* socket); //////////////////////////////////////////////////////////// -/// Remove a socket from a selector +/// \brief Remove a socket from a socket selector /// -/// \param selector : Selector to remove the socket from -/// \param socket : Socket to remove +/// This function doesn't destroy the socket, it simply +/// removes the pointer that the selector has to it. +/// +/// \param selector Socket selector object +/// \param socket POointer to the socket to remove /// //////////////////////////////////////////////////////////// CSFML_API void sfSocketSelector_RemoveTcpListener(sfSocketSelector* selector, sfTcpListener* socket); @@ -81,20 +88,28 @@ CSFML_API void sfSocketSelector_RemoveTcpSocket(sfSocketSelector* selector, sfTc CSFML_API void sfSocketSelector_RemoveUdpSocket(sfSocketSelector* selector, sfUdpSocket* socket); //////////////////////////////////////////////////////////// -/// Remove all sockets from a selector +/// \brief Remove all the sockets stored in a selector /// -/// \param selector : Selector to remove the socket from +/// This function doesn't destroy any instance, it simply +/// removes all the pointers that the selector has to +/// external sockets. +/// +/// \param selector Socket selector object /// //////////////////////////////////////////////////////////// CSFML_API void sfSocketSelector_Clear(sfSocketSelector* selector); //////////////////////////////////////////////////////////// -/// Wait and collect sockets which are ready for reading. -/// This functions will return either when at least one socket -/// is ready, or when the given timeout is over +/// \brief Wait until one or more sockets are ready to receive /// -/// \param selector : Selector to check -/// \param timeout : Maximum time to wait, in milliseconds (0 to disable timeout) +/// This function returns as soon as at least one socket has +/// some data available to be received. To know which sockets are +/// ready, use the sfSocketSelector_IsXxxReady functions. +/// If you use a timeout and no socket is ready before the timeout +/// is over, the function returns sfFalse. +/// +/// \param selector Socket selector object +/// \param timeout Maximum time to wait, in milliseconds (use 0 for infinity) /// /// \return sfTrue if there are sockets ready, sfFalse otherwise /// @@ -102,12 +117,19 @@ CSFML_API void sfSocketSelector_Clear(sfSocketSelector* selector); CSFML_API sfBool sfSocketSelector_Wait(sfSocketSelector* selector, sfUint32 timeout); //////////////////////////////////////////////////////////// -/// Test a socket to know if it is ready to receive data +/// \brief Test a socket to know if it is ready to receive data /// -/// \param selector : Selector to check -/// \param socket : Socket to test +/// This function must be used after a call to +/// sfSocketSelector_Wait, to know which sockets are ready to +/// receive data. If a socket is ready, a call to Receive will +/// never block because we know that there is data available to read. +/// Note that if this function returns sfTrue for a sfTcpListener, +/// this means that it is ready to accept a new connection. /// -/// \return sfTrue if the socket is ready to receive data +/// \param selector Socket selector object +/// \param socket Socket to test +/// +/// \return sfTrue if the socket is ready to read, sfFalse otherwise /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfSocketSelector_IsTcpListenerReady(const sfSocketSelector* selector, sfTcpListener* socket); diff --git a/include/SFML/Network/SocketStatus.h b/include/SFML/Network/SocketStatus.h index b810148..7acdf20 100644 --- a/include/SFML/Network/SocketStatus.h +++ b/include/SFML/Network/SocketStatus.h @@ -27,15 +27,15 @@ //////////////////////////////////////////////////////////// -/// Define the status that can be returned by the socket -/// functions +/// \brief Define the status that can be returned by the socket functions +/// //////////////////////////////////////////////////////////// typedef enum { - sfSocketDone, - sfSocketNotReady, - sfSocketDisconnected, - sfSocketError + sfSocketDone, ///< The socket has sent / received the data + sfSocketNotReady, ///< The socket is not ready to send / receive data yet + sfSocketDisconnected, ///< The TCP socket has been disconnected + sfSocketError ///< An unexpected error happened } sfSocketStatus; diff --git a/include/SFML/Network/TcpListener.h b/include/SFML/Network/TcpListener.h index 5af2a87..e4c7582 100644 --- a/include/SFML/Network/TcpListener.h +++ b/include/SFML/Network/TcpListener.h @@ -34,64 +34,91 @@ //////////////////////////////////////////////////////////// -/// Construct a new TCP socket +/// \brief Create a new TCP listener /// -/// \return Pointer to the new socket +/// \return A new sfTcpListener object /// //////////////////////////////////////////////////////////// CSFML_API sfTcpListener* sfTcpListener_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing TCP socket +/// \brief Destroy a TCP listener /// -/// \param socket : Socket to destroy +/// \param listener TCP listener to destroy /// //////////////////////////////////////////////////////////// -CSFML_API void sfTcpListener_Destroy(sfTcpListener* socket); +CSFML_API void sfTcpListener_Destroy(sfTcpListener* listener); //////////////////////////////////////////////////////////// -/// Change the blocking state of a TCP socket. -/// The default behaviour of a socket is blocking +/// \brief Set the blocking state of a TCP listener /// -/// \param socket : Socket to modify -/// \param blocking : Pass sfTrue to set the socket as blocking, or sfFalse for non-blocking +/// In blocking mode, calls will not return until they have +/// completed their task. For example, a call to +/// sfTcpListener_Accept in blocking mode won't return until +/// a new connection was actually received. +/// In non-blocking mode, calls will always return immediately, +/// using the return code to signal whether there was data +/// available or not. +/// By default, all sockets are blocking. +/// +/// \param listener TCP listener object +/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking /// //////////////////////////////////////////////////////////// -CSFML_API void sfTcpListener_SetBlocking(sfTcpListener* socket, sfBool blocking); +CSFML_API void sfTcpListener_SetBlocking(sfTcpListener* listener, sfBool blocking); //////////////////////////////////////////////////////////// -/// Get the blocking state of the socket +/// \brief Tell whether a TCP listener is in blocking or non-blocking mode /// -/// \param socket : Socket to read +/// \param listener TCP listener object /// -/// \Return sfTrue if the socket is blocking, sfFalse otherwise +/// \return sfTrue if the socket is blocking, sfFalse otherwise /// //////////////////////////////////////////////////////////// -CSFML_API sfBool sfTcpListener_IsBlocking(const sfTcpListener* socket); +CSFML_API sfBool sfTcpListener_IsBlocking(const sfTcpListener* listener); //////////////////////////////////////////////////////////// -/// Listen to a specified port for incoming data or connections +/// \brief Get the port to which a TCP listener is bound locally /// -/// \param socket : Socket to use for listening -/// \param port : Port to listen to +/// If the socket is not listening to a port, this function +/// returns 0. /// -/// \return Socket status +/// \param listener TCP listener object +/// +/// \return Port to which the TCP listener is bound /// //////////////////////////////////////////////////////////// -CSFML_API sfSocketStatus sfTcpListener_Listen(sfTcpListener* socket, unsigned short port); +CSFML_API unsigned short sfTcpListener_GetLocalPort(const sfTcpListener* listener); //////////////////////////////////////////////////////////// -/// Wait for a connection (must be listening to a port). -/// This function is blocking, ie. it won't return before -/// a connection has been accepted +/// \brief Start listening for connections /// -/// \param socket : Socket to use for accepting -/// \param connected : Pointer to a socket pointer that will be filled with the connected client +/// This functions makes the socket listen to the specified +/// port, waiting for new connections. +/// If the socket was previously listening to another port, +/// it will be stopped first and bound to the new port. /// -/// \return Socket status +/// \param listener TCP listener object +/// \param port Port to listen for new connections +/// +/// \return Status code /// //////////////////////////////////////////////////////////// -CSFML_API sfSocketStatus sfTcpListener_Accept(sfTcpListener* socket, sfTcpSocket** connected); +CSFML_API sfSocketStatus sfTcpListener_Listen(sfTcpListener* listener, unsigned short port); + +//////////////////////////////////////////////////////////// +/// \brief Accept a new connection +/// +/// If the socket is in blocking mode, this function will +/// not return until a connection is actually received. +/// +/// \param listener TCP listener object +/// \param connected Socket that will hold the new connection +/// +/// \return Status code +/// +//////////////////////////////////////////////////////////// +CSFML_API sfSocketStatus sfTcpListener_Accept(sfTcpListener* listener, sfTcpSocket** connected); #endif // SFML_TCPLISTENER_H diff --git a/include/SFML/Network/TcpSocket.h b/include/SFML/Network/TcpSocket.h index be7bbd8..af606c8 100644 --- a/include/SFML/Network/TcpSocket.h +++ b/include/SFML/Network/TcpSocket.h @@ -36,45 +36,55 @@ //////////////////////////////////////////////////////////// -/// Construct a new TCP socket +/// \brief Create a new TCP socket /// -/// \return Pointer to the new socket +/// \return A new sfTcpSocket object /// //////////////////////////////////////////////////////////// CSFML_API sfTcpSocket* sfTcpSocket_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing TCP socket +/// \brief Destroy a TCP socket /// -/// \param socket : Socket to destroy +/// \param socket TCP socket to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfTcpSocket_Destroy(sfTcpSocket* socket); //////////////////////////////////////////////////////////// -/// Change the blocking state of a TCP socket. -/// The default behaviour of a socket is blocking +/// \brief Set the blocking state of a TCP listener /// -/// \param socket : Socket to modify -/// \param blocking : Pass sfTrue to set the socket as blocking, or false for non-blocking +/// In blocking mode, calls will not return until they have +/// completed their task. For example, a call to +/// sfTcpSocket_Receive in blocking mode won't return until +/// new data was actually received. +/// In non-blocking mode, calls will always return immediately, +/// using the return code to signal whether there was data +/// available or not. +/// By default, all sockets are blocking. +/// +/// \param socket TCP socket object +/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking /// //////////////////////////////////////////////////////////// CSFML_API void sfTcpSocket_SetBlocking(sfTcpSocket* socket, sfBool blocking); //////////////////////////////////////////////////////////// -/// Get the blocking state of the socket +/// \brief Tell whether a TCP socket is in blocking or non-blocking mode /// -/// \param socket : Socket to read +/// \param socket TCP socket object /// -/// \Return sfTrue if the socket is blocking, sfFalse otherwise +/// \return sfTrue if the socket is blocking, sfFalse otherwise /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket); //////////////////////////////////////////////////////////// -/// Get the port to which a socket is bound locally +/// \brief Get the port to which a TCP socket is bound locally /// -/// \param socket : Socket to read +/// If the socket is not connected, this function returns 0. +/// +/// \param socket TCP socket object /// /// \return Port to which the socket is bound /// @@ -82,9 +92,12 @@ CSFML_API sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket); CSFML_API unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket); //////////////////////////////////////////////////////////// -/// Get the address of the connected peer of a socket +/// \brief Get the address of the connected peer of a TCP socket /// -/// \param socket : Socket to read +/// It the socket is not connected, this function returns +/// sfIpAddress_None(). +/// +/// \param socket TCP socket object /// /// \return Address of the remote peer /// @@ -92,9 +105,12 @@ CSFML_API unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket); CSFML_API sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket); //////////////////////////////////////////////////////////// -/// Get the port of the connected peer to which a socket is connected +/// \brief Get the port of the connected peer to which +/// a TCP socket is connected /// -/// \param socket : Socket to read +/// If the socket is not connected, this function returns 0. +/// +/// \param socket TCP socket object /// /// \return Remote port to which the socket is connected /// @@ -102,69 +118,89 @@ CSFML_API sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket); CSFML_API unsigned short sfTcpSocket_GetRemotePort(const sfTcpSocket* socket); //////////////////////////////////////////////////////////// -/// Connect a TCP socket to another computer on a specified port +/// \brief Connect a TCP socket to a remote peer /// -/// \param socket : Socket to connect -/// \param host : IP Address of the host to connect to -/// \param port : Port to use for transfers (warning : ports < 1024 are reserved) -/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout) +/// In blocking mode, this function may take a while, especially +/// if the remote peer is not reachable. The last parameter allows +/// you to stop trying to connect after a given timeout. +/// If the socket was previously connected, it is first disconnected. /// -/// \return sfTrue if operation has been successful +/// \param socket TCP socket object +/// \param remoteAddress Address of the remote peer +/// \param remotePort Port of the remote peer +/// \param timeout Maximum time to wait, in milliseconds +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfTcpSocket_Connect(sfTcpSocket* socket, sfIpAddress host, unsigned short port, sfUint32 timeout); //////////////////////////////////////////////////////////// -/// Disconnect a connect from its remote peer +/// \brief Disconnect a TCP socket from its remote peer /// -/// \param socket : Socket to disconnect +/// This function gracefully closes the connection. If the +/// socket is not connected, this function has no effect. +/// +/// \param socket TCP socket object /// //////////////////////////////////////////////////////////// CSFML_API void sfTcpSocket_Disconnect(sfTcpSocket* socket); //////////////////////////////////////////////////////////// -/// Send an array of bytes to the host (must be connected first) +/// \brief Send raw data to the remote peer of a TCP socket /// -/// \param socket : Socket to use for sending -/// \param data : Pointer to the bytes to send -/// \param size : Number of bytes to send +/// This function will fail if the socket is not connected. /// -/// \return Socket status +/// \param socket TCP socket object +/// \param data Pointer to the sequence of bytes to send +/// \param size Number of bytes to send +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfTcpSocket_Send(sfTcpSocket* socket, const char* data, size_t size); //////////////////////////////////////////////////////////// -/// Receive an array of bytes from the host (must be connected first) +/// \brief Receive raw data from the remote peer of a TCP socket /// -/// \param socket : Socket to use for receiving -/// \param data : Pointer to a byte array to fill (make sure it is big enough) -/// \param maxSize : Maximum number of bytes to read -/// \param sizeReceived : Number of bytes received +/// In blocking mode, this function will wait until some +/// bytes are actually received. +/// This function will fail if the socket is not connected. /// -/// \return Socket status +/// \param socket TCP socket object +/// \param data Pointer to the array to fill with the received bytes +/// \param size Maximum number of bytes that can be received +/// \param received This variable is filled with the actual number of bytes received +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfTcpSocket_Receive(sfTcpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived); //////////////////////////////////////////////////////////// -/// Send a packet of data to the host (must be connected first) +/// \brief Send a formatted packet of data to the remote peer of a TCP socket /// -/// \param socket : Socket to use for sending -/// \param packet : Packet to send +/// This function will fail if the socket is not connected. /// -/// \return Socket status +/// \param socket TCP socket object +/// \param packet Packet to send +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfTcpSocket_SendPacket(sfTcpSocket* socket, sfPacket* packet); //////////////////////////////////////////////////////////// -/// Receive a packet from the host (must be connected first) +/// \brief Receive a formatted packet of data from the remote peer /// -/// \param socket : Socket to use for receiving -/// \param packet : Packet to fill with received data +/// In blocking mode, this function will wait until the whole packet +/// has been received. +/// This function will fail if the socket is not connected. /// -/// \return Socket status +/// \param socket TCP socket object +/// \param packet Packet to fill with the received data +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfTcpSocket_ReceivePacket(sfTcpSocket* socket, sfPacket* packet); diff --git a/include/SFML/Network/UdpSocket.h b/include/SFML/Network/UdpSocket.h index 26f40c1..1f7540a 100644 --- a/include/SFML/Network/UdpSocket.h +++ b/include/SFML/Network/UdpSocket.h @@ -36,45 +36,56 @@ //////////////////////////////////////////////////////////// -/// Construct a new UDP socket +/// \brief Create a new UDP socket /// -/// \return Pointer to the new socket +/// \return A new sfUdpSocket object /// //////////////////////////////////////////////////////////// CSFML_API sfUdpSocket* sfUdpSocket_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing UDP socket +/// \brief Destroy a UDP socket /// -/// \param socket : Socket to destroy +/// \param socket UDP socket to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfUdpSocket_Destroy(sfUdpSocket* socket); //////////////////////////////////////////////////////////// -/// Change the blocking state of a UDP socket. -/// The default behaviour of a socket is blocking +/// \brief Set the blocking state of a UDP listener /// -/// \param socket : Socket to modify -/// \param blocking : Pass sfTrue to set the socket as blocking, or false for non-blocking +/// In blocking mode, calls will not return until they have +/// completed their task. For example, a call to +/// sfUDPSocket_Receive in blocking mode won't return until +/// new data was actually received. +/// In non-blocking mode, calls will always return immediately, +/// using the return code to signal whether there was data +/// available or not. +/// By default, all sockets are blocking. +/// +/// \param socket UDP socket object +/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking /// //////////////////////////////////////////////////////////// CSFML_API void sfUdpSocket_SetBlocking(sfUdpSocket* socket, sfBool blocking); //////////////////////////////////////////////////////////// -/// Get the blocking state of the socket +/// \brief Tell whether a UDP socket is in blocking or non-blocking mode /// -/// \param socket : Socket to read +/// \param socket UDP socket object /// -/// \Return sfTrue if the socket is blocking, sfFalse otherwise +/// \return sfTrue if the socket is blocking, sfFalse otherwise /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket); //////////////////////////////////////////////////////////// -/// Get the port to which a socket is bound locally +/// \brief Get the port to which a UDP socket is bound locally /// -/// \param socket : Socket to read +/// If the socket is not bound to a port, this function +/// returns 0. +/// +/// \param socket UDP socket object /// /// \return Port to which the socket is bound /// @@ -82,82 +93,116 @@ CSFML_API sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket); CSFML_API unsigned short sfUdpSocket_GetLocalPort(const sfUdpSocket* socket); //////////////////////////////////////////////////////////// -/// Bind a socket to a specific port +/// \brief Bind a UDP socket to a specific port /// -/// \param socket : Socket to bind -/// \param port : Port to bind the socket to +/// Binding the socket to a port is necessary for being +/// able to receive data on that port. +/// You can use the special value 0 to tell the +/// system to automatically pick an available port, and then +/// call sfUdpSocket_GetLocalPort to retrieve the chosen port. /// -/// \return Socket status +/// \param socket UDP socket object +/// \param port Port to bind the socket to +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfUdpSocket_Bind(sfUdpSocket* socket, unsigned short port); //////////////////////////////////////////////////////////// -/// Unbind a socket from its previous port, if any +/// \brief Unbind a UDP socket from the local port to which it is bound /// -/// \param socket : Socket to unbind +/// The port that the socket was previously using is immediately +/// available after this function is called. If the +/// socket is not bound to a port, this function has no effect. +/// +/// \param socket UDP socket object /// //////////////////////////////////////////////////////////// CSFML_API void sfUdpSocket_Unbind(sfUdpSocket* socket); //////////////////////////////////////////////////////////// -/// Send an array of bytes +/// \brief Send raw data to a remote peer with a UDP socket /// -/// \param socket : Socket to use for sending -/// \param data : Pointer to the bytes to send -/// \param size : Number of bytes to send -/// \param address : Address of the computer to send the packet to -/// \param port : Port to use for communication +/// Make sure that \a size is not greater than +/// sfUdpSocket_MaxDatagramSize(), otherwise this function will +/// fail and no data will be sent. /// -/// \return Socket status +/// \param socket UDP socket object +/// \param data Pointer to the sequence of bytes to send +/// \param size Number of bytes to send +/// \param remoteAddress Address of the receiver +/// \param remotePort Port of the receiver to send the data to +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfUdpSocket_Send(sfUdpSocket* socket, const char* data, size_t size, sfIpAddress address, unsigned short port); //////////////////////////////////////////////////////////// -/// Receive an array of bytes. -/// This function is blocking, ie. it won't return before some -/// bytes have been received +/// \brief Receive raw data from a remote peer with a UDP socket /// -/// \param socket : Socket to use for receiving -/// \param data : Pointer to a byte array to fill (make sure it is big enough) -/// \param maxSize : Maximum number of bytes to read -/// \param sizeReceived : Number of bytes received -/// \param address : Address of the computer which sent the data -/// \param port : Port on which the remote computer sent the data +/// In blocking mode, this function will wait until some +/// bytes are actually received. +/// Be careful to use a buffer which is large enough for +/// the data that you intend to receive, if it is too small +/// then an error will be returned and *all* the data will +/// be lost. /// -/// \return Socket status +/// \param socket UDP socket object +/// \param data Pointer to the array to fill with the received bytes +/// \param size Maximum number of bytes that can be received +/// \param received This variable is filled with the actual number of bytes received +/// \param remoteAddress Address of the peer that sent the data +/// \param remotePort Port of the peer that sent the data +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfUdpSocket_Receive(sfUdpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived, sfIpAddress* address, unsigned short* port); //////////////////////////////////////////////////////////// -/// Send a packet of data +/// \brief Send a formatted packet of data to a remote peer with a UDP socket /// -/// \param socket : Socket to use for sending -/// \param packet : Packet to send -/// \param address : Address of the computer to send the packet to -/// \param port : Port to use for communication +/// Make sure that the packet size is not greater than +/// sfUdpSocket_MaxDatagramSize(), otherwise this function will +/// fail and no data will be sent. /// -/// \return Socket status +/// \param socket UDP socket object +/// \param packet Packet to send +/// \param remoteAddress Address of the receiver +/// \param remotePort Port of the receiver to send the data to +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfUdpSocket_SendPacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress address, unsigned short port); //////////////////////////////////////////////////////////// -/// Receive a packet. -/// This function is blocking, ie. it won't return before a -/// packet is received +/// \brief Receive a formatted packet of data from a remote peer with a UDP socket /// -/// \param socket : Socket to use for receiving -/// \param packet : Packet to fill with received data -/// \param address : Address of the computer which sent the packet -/// \param port : Port on which the remote computer sent the data +/// In blocking mode, this function will wait until the whole packet +/// has been received. +/// Warning: this functon doesn't properly handle mixed data +/// received from multiple peers. /// -/// \return Socket status +/// \param packet Packet to fill with the received data +/// \param remoteAddress Address of the peer that sent the data +/// \param remotePort Port of the peer that sent the data +/// +/// \return Status code /// //////////////////////////////////////////////////////////// CSFML_API sfSocketStatus sfUdpSocket_ReceivePacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress* address, unsigned short* port); +//////////////////////////////////////////////////////////// +/// \brief Return the maximum number of bytes that can be +/// sent in a single UDP datagram +/// +/// \return The maximum size of a UDP datagram (message) +/// +//////////////////////////////////////////////////////////// +CSFML_API unsigned int sfUdpSocket_MaxDatagramSize(); + #endif // SFML_UDPSOCKET_H diff --git a/include/SFML/System/Clock.h b/include/SFML/System/Clock.h index 2c45fa6..eae171c 100644 --- a/include/SFML/System/Clock.h +++ b/include/SFML/System/Clock.h @@ -33,7 +33,7 @@ //////////////////////////////////////////////////////////// -/// Create a new clock and start it +/// \brief Create a new clock and start it /// /// \return A new sfClock object /// @@ -41,37 +41,43 @@ CSFML_API sfClock* sfClock_Create(void); //////////////////////////////////////////////////////////// -/// Copy an existing clock +/// \brief Create a new clock by copying an existing one /// -/// \param clock : Clock to copy +/// \param clock Clock to copy /// -/// \return Copied object +/// \return A new sfClock object which is a copy of \a clock /// //////////////////////////////////////////////////////////// CSFML_API sfClock* sfClock_Copy(sfClock* clock); //////////////////////////////////////////////////////////// -/// Destroy an existing clock +/// \brief Destroy a clock /// -/// \param clock : Clock to delete +/// \param clock Clock to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfClock_Destroy(sfClock* clock); //////////////////////////////////////////////////////////// -/// Get the time elapsed for a clock +/// \brief Get the time elapsed in a clock /// -/// \param clock : Clock to get time from +/// This function returns the time elapsed since the last call +/// to sfClock_Reset (or the construction of the object if +/// sfClock_Reset has not been called). /// -/// \return Elapsed time, in milliseconds +/// \param clock Clock object +/// +/// \return Time elapsed, in milliseconds /// //////////////////////////////////////////////////////////// CSFML_API sfUint32 sfClock_GetTime(const sfClock* clock); //////////////////////////////////////////////////////////// -/// Restart a clock +/// \brief Restart a clock /// -/// \param clock : Clock to restart +/// This function puts the time counter back to zero. +/// +/// \param clock Clock object /// //////////////////////////////////////////////////////////// CSFML_API void sfClock_Reset(sfClock* clock); diff --git a/include/SFML/System/Mutex.h b/include/SFML/System/Mutex.h index 1b316d4..2e3f6c7 100644 --- a/include/SFML/System/Mutex.h +++ b/include/SFML/System/Mutex.h @@ -33,7 +33,7 @@ //////////////////////////////////////////////////////////// -/// Create a new mutex +/// \brief Create a new mutex /// /// \return A new sfMutex object /// @@ -41,25 +41,25 @@ CSFML_API sfMutex* sfMutex_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing mutex +/// \brief Destroy a mutex /// -/// \param mutex : Mutex to delete +/// \param mutex Mutex to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfMutex_Destroy(sfMutex* mutex); //////////////////////////////////////////////////////////// -/// Lock a mutex +/// \brief Lock a mutex /// -/// \param mutex : Mutex to lock +/// \param mutex Mutex object /// //////////////////////////////////////////////////////////// CSFML_API void sfMutex_Lock(sfMutex* mutex); //////////////////////////////////////////////////////////// -/// Unlock a mutex +/// \brief Unlock a mutex /// -/// \param mutex : Mutex to unlock +/// \param mutex Mutex object /// //////////////////////////////////////////////////////////// CSFML_API void sfMutex_Unlock(sfMutex* mutex); diff --git a/include/SFML/System/Sleep.h b/include/SFML/System/Sleep.h index e79649e..1c5d8ab 100644 --- a/include/SFML/System/Sleep.h +++ b/include/SFML/System/Sleep.h @@ -32,9 +32,12 @@ //////////////////////////////////////////////////////////// -/// Make the current thread sleep for a given duration +/// \brief Make the current thread sleep for a given duration /// -/// \param duration : Time to sleep, in milliseconds +/// sfSleep is the best way to block a program or one of its +/// threads, as it doesn't consume any CPU power. +/// +/// \param duration Time to sleep, in milliseconds /// //////////////////////////////////////////////////////////// CSFML_API void sfSleep(sfUint32 duration); diff --git a/include/SFML/System/Thread.h b/include/SFML/System/Thread.h index 9d8cf26..0dfd899 100644 --- a/include/SFML/System/Thread.h +++ b/include/SFML/System/Thread.h @@ -33,45 +33,68 @@ //////////////////////////////////////////////////////////// -/// Construct a new thread from a function pointer +/// \brief Create a new thread from a function pointer /// -/// \param function : Entry point of the thread -/// \param userData : Data to pass to the thread function +/// Note: this does *not* run the thread, use sfThread_Launch. +/// +/// \param function Entry point of the thread +/// \param userData Custom data to pass to the thread function +/// +/// \return A new sfThread object /// //////////////////////////////////////////////////////////// CSFML_API sfThread* sfThread_Create(void (*function)(void*), void* userData); //////////////////////////////////////////////////////////// -/// Destroy an existing thread +/// \brief Destroy a thread /// -/// \param thread : Thread to delete +/// This function calls sfThread_Wait, so that the internal thread +/// cannot survive after the sfThread object is destroyed. +/// +/// \param thread Thread to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfThread_Destroy(sfThread* thread); //////////////////////////////////////////////////////////// -/// Run a thread +/// \brief Run a thread /// -/// \param thread : Thread to launch +/// This function starts the entry point passed to the +/// thread's constructor, and returns immediately. +/// After this function returns, the thread's function is +/// running in parallel to the calling code. +/// +/// \param thread Thread object /// //////////////////////////////////////////////////////////// CSFML_API void sfThread_Launch(sfThread* thread); //////////////////////////////////////////////////////////// -/// Wait until a thread finishes +/// \brief Wait until a thread finishes /// -/// \param thread : Thread to wait for +/// This function will block the execution until the +/// thread's function ends. +/// Warning: if the thread function never ends, the calling +/// thread will block forever. +/// If this function is called from its owner thread, it +/// returns without doing anything. +/// +/// \param thread Thread object /// //////////////////////////////////////////////////////////// CSFML_API void sfThread_Wait(sfThread* thread); //////////////////////////////////////////////////////////// -/// Terminate a thread -/// Terminating a thread with this function is not safe, -/// you should rather try to make the thread function -/// terminate by itself +/// \brief Terminate a thread /// -/// \param thread : Thread to terminate +/// This function immediately stops the thread, without waiting +/// for its function to finish. +/// Terminating a thread with this function is not safe, +/// and can lead to local variables not being destroyed +/// on some operating systems. You should rather try to make +/// the thread function terminate by itself. +/// +/// \param thread Thread object /// //////////////////////////////////////////////////////////// CSFML_API void sfThread_Terminate(sfThread* thread); diff --git a/include/SFML/Window/Context.h b/include/SFML/Window/Context.h index b5617f2..c1ea417 100644 --- a/include/SFML/Window/Context.h +++ b/include/SFML/Window/Context.h @@ -33,26 +33,28 @@ //////////////////////////////////////////////////////////// -/// Construct a new context +/// \brief Create a new context /// -/// \return New context +/// This function activates the new context. +/// +/// \return New sfContext object /// //////////////////////////////////////////////////////////// CSFML_API sfContext* sfContext_Create(void); //////////////////////////////////////////////////////////// -/// Destroy an existing context +/// \brief Destroy a context /// -/// \param context : Context to destroy +/// \param context Context to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfContext_Destroy(sfContext* context); //////////////////////////////////////////////////////////// -/// Activate or deactivate a context +/// \brief Activate or deactivate explicitely a context /// -/// \param context : Context to activate or deactivate -/// \param active : sfTrue to activate, sfFalse to deactivate +/// \param context Context object +/// \param active sfTrue to activate, sfFalse to deactivate /// //////////////////////////////////////////////////////////// CSFML_API void sfContext_SetActive(sfContext* context, sfBool active); diff --git a/include/SFML/Window/Event.h b/include/SFML/Window/Event.h index df97f8a..b9a47a1 100644 --- a/include/SFML/Window/Event.h +++ b/include/SFML/Window/Event.h @@ -34,7 +34,8 @@ //////////////////////////////////////////////////////////// -/// Definition of all the event types +/// \brief Definition of all the event types +/// //////////////////////////////////////////////////////////// typedef enum { @@ -60,7 +61,8 @@ typedef enum //////////////////////////////////////////////////////////// -/// Keyboard event parameters +/// \brief Keyboard event parameters +/// //////////////////////////////////////////////////////////// struct sfKeyEvent { @@ -73,7 +75,8 @@ struct sfKeyEvent }; //////////////////////////////////////////////////////////// -/// Text event parameters +/// \brief Text event parameters +/// //////////////////////////////////////////////////////////// struct sfTextEvent { @@ -82,7 +85,8 @@ struct sfTextEvent }; //////////////////////////////////////////////////////////// -/// Mouse move event parameters +/// \brief Mouse move event parameters +/// //////////////////////////////////////////////////////////// struct sfMouseMoveEvent { @@ -92,7 +96,8 @@ struct sfMouseMoveEvent }; //////////////////////////////////////////////////////////// -/// Mouse buttons events parameters +/// \brief Mouse buttons events parameters +/// //////////////////////////////////////////////////////////// struct sfMouseButtonEvent { @@ -103,7 +108,8 @@ struct sfMouseButtonEvent }; //////////////////////////////////////////////////////////// -/// Mouse wheel events parameters +/// \brief Mouse wheel events parameters +/// //////////////////////////////////////////////////////////// struct sfMouseWheelEvent { @@ -114,7 +120,8 @@ struct sfMouseWheelEvent }; //////////////////////////////////////////////////////////// -/// Joystick axis move event parameters +/// \brief Joystick axis move event parameters +/// //////////////////////////////////////////////////////////// struct sfJoystickMoveEvent { @@ -125,7 +132,8 @@ struct sfJoystickMoveEvent }; //////////////////////////////////////////////////////////// -/// Joystick buttons events parameters +/// \brief Joystick buttons events parameters +/// //////////////////////////////////////////////////////////// struct sfJoystickButtonEvent { @@ -135,7 +143,8 @@ struct sfJoystickButtonEvent }; //////////////////////////////////////////////////////////// -/// Joystick connection/disconnection event parameters +/// \brief Joystick connection/disconnection event parameters +/// //////////////////////////////////////////////////////////// struct sfJoystickConnectEvent { @@ -144,7 +153,8 @@ struct sfJoystickConnectEvent }; //////////////////////////////////////////////////////////// -/// Size events parameters +/// \brief Size events parameters +/// //////////////////////////////////////////////////////////// struct sfSizeEvent { @@ -155,7 +165,8 @@ struct sfSizeEvent //////////////////////////////////////////////////////////// -/// sfEvent defines a system event and its parameters +/// \brief sfEvent defines a system event and its parameters +/// //////////////////////////////////////////////////////////// typedef union { diff --git a/include/SFML/Window/VideoMode.h b/include/SFML/Window/VideoMode.h index d2f479b..20dadde 100644 --- a/include/SFML/Window/VideoMode.h +++ b/include/SFML/Window/VideoMode.h @@ -32,9 +32,10 @@ //////////////////////////////////////////////////////////// -/// sfVideoMode defines a video mode (width, height, bpp, frequency) -/// and provides functions for getting modes supported -/// by the display device +/// \brief sfVideoMode defines a video mode (width, height, bpp, frequency) +/// and provides functions for getting modes supported +/// by the display device +/// //////////////////////////////////////////////////////////// typedef struct { @@ -45,7 +46,7 @@ typedef struct //////////////////////////////////////////////////////////// -/// Get the current desktop video mode +/// \brief Get the current desktop video mode /// /// \return Current desktop video mode /// @@ -53,23 +54,33 @@ typedef struct CSFML_API sfVideoMode sfVideoMode_GetDesktopMode(void); //////////////////////////////////////////////////////////// -/// Get all the supported video modes for fullscreen mode. -/// Modes are sorted from best to worst. +/// \brief Retrieve all the video modes supported in fullscreen mode /// -/// \param Count : Variable that will be filled with the number of modes +/// When creating a fullscreen window, the video mode is restricted +/// to be compatible with what the graphics driver and monitor +/// support. This function returns the complete list of all video +/// modes that can be used in fullscreen mode. +/// The returned array is sorted from best to worst, so that +/// the first element will always give the best mode (higher +/// width, height and bits-per-pixel). /// -/// \return Pointer to an array of \a count video modes +/// \param count Pointer to a variable that will be filled with the number of modes in the array +/// +/// \return Pointer to an array containing all the supported fullscreen modes /// //////////////////////////////////////////////////////////// CSFML_API const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* Count); //////////////////////////////////////////////////////////// -/// Tell whether or not a video mode is supported +/// \brief Tell whether or not a video mode is valid /// -/// \param mode : Video mode to check +/// The validity of video modes is only relevant when using +/// fullscreen windows; otherwise any video mode can be used +/// with no restriction. /// +/// \param mode Video mode /// -/// \return True if video mode is supported, false otherwise +/// \return sfTrue if the video mode is valid for fullscreen mode /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfVideoMode_IsValid(sfVideoMode mode); diff --git a/include/SFML/Window/Window.h b/include/SFML/Window/Window.h index 9bc6d98..ecc2d36 100644 --- a/include/SFML/Window/Window.h +++ b/include/SFML/Window/Window.h @@ -36,7 +36,7 @@ //////////////////////////////////////////////////////////// -/// Enumeration of window creation styles +/// \brief Enumeration of window creation styles /// //////////////////////////////////////////////////////////// enum @@ -51,7 +51,8 @@ enum //////////////////////////////////////////////////////////// -/// Structure defining the window's creation settings +/// \brief Structure defining the window's creation settings +/// //////////////////////////////////////////////////////////// typedef struct { @@ -64,53 +65,89 @@ typedef struct //////////////////////////////////////////////////////////// -/// Construct a new window +/// \brief Construct a new window /// -/// \param mode : Video mode to use -/// \param title : Title of the window -/// \param style : Window style -/// \param settings : Creation settings (pass NULL to use default values) +/// This function creates the window with the size and pixel +/// depth defined in \a mode. An optional style can be passed to +/// customize the look and behaviour of the window (borders, +/// title bar, resizable, closable, ...). If \a style contains +/// sfFullscreen, then \a mode must be a valid video mode. +/// +/// The fourth parameter is a pointer to a structure specifying +/// advanced OpenGL context settings such as antialiasing, +/// depth-buffer bits, etc. +/// +/// \param mode Video mode to use (defines the width, height and depth of the rendering area of the window) +/// \param title Title of the window +/// \param style Window style +/// \param settings Additional settings for the underlying OpenGL context +/// +/// \return A new sfWindow object /// //////////////////////////////////////////////////////////// CSFML_API sfWindow* sfWindow_Create(sfVideoMode mode, const char* title, unsigned long style, const sfContextSettings* settings); //////////////////////////////////////////////////////////// -/// Construct a window from an existing control +/// \brief Construct a window from an existing control /// -/// \param handle : Platform-specific handle of the control -/// \param settings : Creation settings (pass NULL to use default values) +/// Use this constructor if you want to create an OpenGL +/// rendering area into an already existing control. +/// +/// The second parameter is a pointer to a structure specifying +/// advanced OpenGL context settings such as antialiasing, +/// depth-buffer bits, etc. +/// +/// \param handle Platform-specific handle of the control +/// \param settings Additional settings for the underlying OpenGL context +/// +/// \return A new sfWindow object /// //////////////////////////////////////////////////////////// CSFML_API sfWindow* sfWindow_CreateFromHandle(sfWindowHandle handle, const sfContextSettings* settings); //////////////////////////////////////////////////////////// -/// Destroy an existing window +/// \brief Destroy a window /// -/// \param window : Window to destroy +/// \param window Window to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_Destroy(sfWindow* window); //////////////////////////////////////////////////////////// -/// Close a window (but doesn't destroy the internal data) +/// \brief Close a window and destroy all the attached resources /// -/// \param window : Window to close +/// After calling this function, the sfWindow object remains +/// valid, you must call sfWindow_Destroy to actually delete it. +/// All other functions such as sfWindow_PollEvent or sfWindow_Display +/// will still work (i.e. you don't have to test sfWindow_IsOpened +/// every time), and will have no effect on closed windows. +/// +/// \param window Window object /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_Close(sfWindow* window); //////////////////////////////////////////////////////////// -/// Tell whether or not a window is opened +/// \brief Tell whether or not a window is opened /// -/// \param window : Window object +/// This function returns whether or not the window exists. +/// Note that a hidden window (sfWindow_Show(sfFalse)) will return +/// sfTrue. +/// +/// \param window Window object +/// +/// \return sfTrue if the window is opened, sfFalse if it has been closed /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfWindow_IsOpened(const sfWindow* window); //////////////////////////////////////////////////////////// -/// Get the width of the rendering region of a window +/// \brief Get the width of the rendering region of a window /// -/// \param window : Window object +/// The width doesn't include the titlebar and borders +/// of the window. +/// +/// \param window Window object /// /// \return Width in pixels /// @@ -118,9 +155,12 @@ CSFML_API sfBool sfWindow_IsOpened(const sfWindow* window); CSFML_API unsigned int sfWindow_GetWidth(const sfWindow* window); //////////////////////////////////////////////////////////// -/// Get the height of the rendering region of a window +/// \brief Get the height of the rendering region of a window /// -/// \param window : Window object +/// The height doesn't include the titlebar and borders +/// of the window. +/// +/// \param window Window object /// /// \return Height in pixels /// @@ -128,169 +168,233 @@ CSFML_API unsigned int sfWindow_GetWidth(const sfWindow* window); CSFML_API unsigned int sfWindow_GetHeight(const sfWindow* window); //////////////////////////////////////////////////////////// -/// Get the creation settings of a window +/// \brief Get the settings of the OpenGL context of a window /// -/// \param window : Window object +/// Note that these settings may be different from what was +/// passed to the sfWindow_Create function, +/// if one or more settings were not supported. In this case, +/// SFML chose the closest match. /// -/// \return Settings used to create the window +/// \param window Window object +/// +/// \return Structure containing the OpenGL context settings /// //////////////////////////////////////////////////////////// CSFML_API sfContextSettings sfWindow_GetSettings(const sfWindow* window); //////////////////////////////////////////////////////////// -/// Get the event on top of events stack of a window, if any, and pop it +/// \brief Pop the event on top of events stack, if any, and return it /// -/// \param window : Window object -/// \param event : Event to fill, if any +/// This function is not blocking: if there's no pending event then +/// it will return false and leave \a event unmodified. +/// Note that more than one event may be present in the events stack, +/// thus you should always call this function in a loop +/// to make sure that you process every pending event. /// -/// \return sfTrue if an event was returned, sfFalse if events stack was empty +/// \param window Window object +/// \param event Event to be returned +/// +/// \return sfTrue if an event was returned, or sfFalse if the events stack was empty /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfWindow_PollEvent(sfWindow* window, sfEvent* event); //////////////////////////////////////////////////////////// -/// Wait for an event and return it +/// \brief Wait for an event and return it /// -/// \param window : Window object -/// \param event : Event to fill +/// This function is blocking: if there's no pending event then +/// it will wait until an event is received. +/// After this function returns (and no error occured), +/// the \a event object is always valid and filled properly. +/// This function is typically used when you have a thread that +/// is dedicated to events handling: you want to make this thread +/// sleep as long as no new event is received. /// -/// \return sfFalse if an error occured +/// \param window Window object +/// \param event Event to be returned +/// +/// \return sfFalse if any error occured /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfWindow_WaitEvent(sfWindow* window, sfEvent* event); //////////////////////////////////////////////////////////// -/// Enable / disable vertical synchronization on a window +/// \brief Enable or disable vertical synchronization /// -/// \param window : Window object -/// \param enabled : sfTrue to enable v-sync, sfFalse to deactivate +/// Activating vertical synchronization will limit the number +/// of frames displayed to the refresh rate of the monitor. +/// This can avoid some visual artifacts, and limit the framerate +/// to a good value (but not constant across different computers). +/// +/// \param window Window object +/// \param enabled sfTrue to enable v-sync, sfFalse to deactivate /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_EnableVerticalSync(sfWindow* window, sfBool enabled); //////////////////////////////////////////////////////////// -/// Show or hide the mouse cursor on a window +/// \brief Show or hide the mouse cursor /// -/// \param window : Window object -/// \param show : sfTrue to show, sfFalse to hide +/// \param window Window object +/// \param show sfTrue to show, sfFalse to hide /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_ShowMouseCursor(sfWindow* window, sfBool show); //////////////////////////////////////////////////////////// -/// Change the position of a window on screen. -/// Only works for top-level windows +/// \brief Change the position of a window on screen /// -/// \param window : Window object -/// \param left : Left position -/// \param top : Top position +/// This function only works for top-level windows +/// (i.e. it will be ignored for windows created from +/// the handle of a child window/control). +/// +/// \param window Window object +/// \param x Left position +/// \param y Top position /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_SetPosition(sfWindow* window, int left, int top); //////////////////////////////////////////////////////////// -/// Change the size of the rendering region of a window +/// \brief Change the size of the rendering region of a window /// -/// \param window : Window object -/// \param width : New Width -/// \param height : New Height +/// \param window Window object +/// \param width New width, in pixels +/// \param height New height, in pixels /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_SetSize(sfWindow* window, unsigned int width, unsigned int height); //////////////////////////////////////////////////////////// -/// Change the title of a window +/// \brief Change the title of a window /// -/// \param window : Window object -/// \param title : New title +/// \param window Window object +/// \param title New title /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_SetTitle(sfWindow* window, const char* title); //////////////////////////////////////////////////////////// -/// Show or hide a window +/// \brief Show or hide a window /// -/// \param window : Window object -/// \param show : sfTrue to show, sfFalse to hide +/// \param window Window object +/// \param show sfTrue to show, sfFalse to hide /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_Show(sfWindow* window, sfBool show); //////////////////////////////////////////////////////////// -/// Enable or disable automatic key-repeat for keydown events. -/// Automatic key-repeat is enabled by default +/// \brief Enable or disable automatic key-repeat /// -/// \param window : Window object -/// \param enabled : sfTrue to enable, sfFalse to disable +/// If key repeat is enabled, you will receive repeated +/// KeyPress events while keeping a key pressed. If it is disabled, +/// you will only get a single event when the key is pressed. +/// +/// Key repeat is enabled by default. +/// +/// \param window Window object +/// \param enabled sfTrue to enable, sfFalse to disable /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_EnableKeyRepeat(sfWindow* window, sfBool enabled); //////////////////////////////////////////////////////////// -/// Change the window's icon +/// \brief Change a window's icon /// -/// \param window : Window object -/// \param width : Icon's width, in pixels -/// \param height : Icon's height, in pixels -/// \param pixels : Pointer to the pixels in memory, format must be RGBA 32 bits +/// \a pixels must be an array of \a width x \a height pixels +/// in 32-bits RGBA format. +/// +/// \param window Window object +/// \param width Icon's width, in pixels +/// \param height Icon's height, in pixels +/// \param pixels Pointer to the array of pixels in memory /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_SetIcon(sfWindow* window, unsigned int width, unsigned int height, const sfUint8* pixels); //////////////////////////////////////////////////////////// -/// Activate or deactivate a window as the current target for rendering +/// \brief Activate or deactivate a window as the current target +/// for OpenGL rendering /// -/// \param window : Window object -/// \param active : sfTrue to activate, sfFalse to deactivate +/// A window is active only on the current thread, if you want to +/// make it active on another thread you have to deactivate it +/// on the previous thread first if it was active. +/// Only one window can be active on a thread at a time, thus +/// the window previously active (if any) automatically gets deactivated. /// -/// \return True if operation was successful, false otherwise +/// \param window Window object +/// \param active sfTrue to activate, sfFalse to deactivate +/// +/// \return sfTrue if operation was successful, sfFalse otherwise /// //////////////////////////////////////////////////////////// CSFML_API sfBool sfWindow_SetActive(sfWindow* window, sfBool active); //////////////////////////////////////////////////////////// -/// Display a window on screen +/// \brief Display on screen what has been rendered to the +/// window so far /// -/// \param window : Window object +/// This function is typically called after all OpenGL rendering +/// has been done for the current frame, in order to show +/// it on screen. +/// +/// \param window Window object /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_Display(sfWindow* window); //////////////////////////////////////////////////////////// -/// Limit the framerate to a maximum fixed frequency for a window +/// \brief Limit the framerate to a maximum fixed frequency /// -/// \param window : Window object -/// \param limit : Framerate limit, in frames per seconds (use 0 to disable limit) +/// If a limit is set, the window will use a small delay after +/// each call to sfWindow_Display to ensure that the current frame +/// lasted long enough to match the framerate limit. +/// +/// \param window Window object +/// \param limit Framerate limit, in frames per seconds (use 0 to disable limit) /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_SetFramerateLimit(sfWindow* window, unsigned int limit); //////////////////////////////////////////////////////////// -/// Get time elapsed since last frame of a window +/// \brief Get the duration of the last frame /// -/// \param window : Window object +/// This function returns the time elapsed between the last +/// two calls to sfWindow_Display. +/// This can be useful for calculating the framerate, or for +/// updating the application's objects. /// -/// \return Time elapsed, in milliseconds +/// \param window Window object +/// +/// \return Time elapsed in last frame, in milliseconds /// //////////////////////////////////////////////////////////// CSFML_API sfUint32 sfWindow_GetFrameTime(const sfWindow* window); //////////////////////////////////////////////////////////// -/// Change the joystick threshold, ie. the value below which -/// no move event will be generated +/// \brief Change the joystick threshold /// -/// \param window : Window object -/// \param threshold : New threshold, in range [0, 100] +/// The joystick threshold is the value below which +/// no JoyMoved event will be generated. +/// +/// \param window Window object +/// \param threshold New threshold, in the range [0, 100] /// //////////////////////////////////////////////////////////// CSFML_API void sfWindow_SetJoystickThreshold(sfWindow* window, float threshold); //////////////////////////////////////////////////////////// -/// Retrieve the Os-specific handle of a window +/// \brief Get the OS-specific handle of the window /// -/// \param window : Window object +/// The type of the returned handle is sfWindowHandle, +/// which is a typedef to the handle type defined by the OS. +/// You shouldn't need to use this function, unless you have +/// very specific stuff to implement that SFML doesn't support, +/// or implement a temporary workaround until a bug is fixed. /// -/// \return Window handle +/// \param window Window object +/// +/// \return System handle of the window /// //////////////////////////////////////////////////////////// CSFML_API sfWindowHandle sfWindow_GetSystemHandle(const sfWindow* window); diff --git a/src/SFML/Audio/Listener.cpp b/src/SFML/Audio/Listener.cpp index 953142d..180aa49 100644 --- a/src/SFML/Audio/Listener.cpp +++ b/src/SFML/Audio/Listener.cpp @@ -30,8 +30,6 @@ -//////////////////////////////////////////////////////////// -/// Change the global volume of all the sounds //////////////////////////////////////////////////////////// void sfListener_SetGlobalVolume(float volume) { @@ -39,8 +37,6 @@ void sfListener_SetGlobalVolume(float volume) } -//////////////////////////////////////////////////////////// -/// Get the current value of the global volume of all the sounds //////////////////////////////////////////////////////////// float sfListener_GetGlobalVolume(void) { @@ -48,8 +44,6 @@ float sfListener_GetGlobalVolume(void) } -//////////////////////////////////////////////////////////// -/// Change the position of the listener //////////////////////////////////////////////////////////// void sfListener_SetPosition(float x, float y, float z) { @@ -57,8 +51,6 @@ void sfListener_SetPosition(float x, float y, float z) } -//////////////////////////////////////////////////////////// -/// Get the current position of the listener //////////////////////////////////////////////////////////// void sfListener_GetPosition(float* x, float* y, float* z) { @@ -72,8 +64,6 @@ void sfListener_GetPosition(float* x, float* y, float* z) } -//////////////////////////////////////////////////////////// -/// Change the orientation of the listener //////////////////////////////////////////////////////////// void sfListener_SetDirection(float x, float y, float z) { @@ -81,8 +71,6 @@ void sfListener_SetDirection(float x, float y, float z) } -//////////////////////////////////////////////////////////// -/// Get the current orientation of the listener //////////////////////////////////////////////////////////// void sfListener_GetDirection(float* x, float* y, float* z) { diff --git a/src/SFML/Audio/Music.cpp b/src/SFML/Audio/Music.cpp index 1b52e1b..07c6883 100644 --- a/src/SFML/Audio/Music.cpp +++ b/src/SFML/Audio/Music.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Create a new music and load it from a file //////////////////////////////////////////////////////////// sfMusic* sfMusic_CreateFromFile(const char* filename) { @@ -46,8 +44,6 @@ sfMusic* sfMusic_CreateFromFile(const char* filename) } -//////////////////////////////////////////////////////////// -/// Create a new music and load it from a file in memory //////////////////////////////////////////////////////////// sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes) { @@ -62,8 +58,6 @@ sfMusic* sfMusic_CreateFromMemory(const void* data, size_t sizeInBytes) } -//////////////////////////////////////////////////////////// -/// Create a new music and load it from a custom stream //////////////////////////////////////////////////////////// sfMusic* sfMusic_CreateFromStream(sfInputStream* stream) { @@ -81,8 +75,6 @@ sfMusic* sfMusic_CreateFromStream(sfInputStream* stream) } -//////////////////////////////////////////////////////////// -/// Destroy an existing music //////////////////////////////////////////////////////////// void sfMusic_Destroy(sfMusic* music) { @@ -90,8 +82,6 @@ void sfMusic_Destroy(sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Set a music loop state //////////////////////////////////////////////////////////// void sfMusic_SetLoop(sfMusic* music, sfBool loop) { @@ -99,8 +89,6 @@ void sfMusic_SetLoop(sfMusic* music, sfBool loop) } -//////////////////////////////////////////////////////////// -/// Tell whether or not a music is looping //////////////////////////////////////////////////////////// sfBool sfMusic_GetLoop(const sfMusic* music) { @@ -108,8 +96,6 @@ sfBool sfMusic_GetLoop(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get a music duration //////////////////////////////////////////////////////////// sfUint32 sfMusic_GetDuration(const sfMusic* music) { @@ -117,8 +103,6 @@ sfUint32 sfMusic_GetDuration(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Start playing a music //////////////////////////////////////////////////////////// void sfMusic_Play(sfMusic* music) { @@ -126,8 +110,6 @@ void sfMusic_Play(sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Pause a music //////////////////////////////////////////////////////////// void sfMusic_Pause(sfMusic* music) { @@ -135,8 +117,6 @@ void sfMusic_Pause(sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Stop playing a music //////////////////////////////////////////////////////////// void sfMusic_Stop(sfMusic* music) { @@ -144,8 +124,6 @@ void sfMusic_Stop(sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Return the number of channels of a music (1 = mono, 2 = stereo) //////////////////////////////////////////////////////////// unsigned int sfMusic_GetChannelsCount(const sfMusic* music) { @@ -153,8 +131,6 @@ unsigned int sfMusic_GetChannelsCount(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get the stream sample rate of a music //////////////////////////////////////////////////////////// unsigned int sfMusic_GetSampleRate(const sfMusic* music) { @@ -162,8 +138,6 @@ unsigned int sfMusic_GetSampleRate(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get the status of a music (stopped, paused, playing) //////////////////////////////////////////////////////////// sfSoundStatus sfMusic_GetStatus(const sfMusic* music) { @@ -173,8 +147,6 @@ sfSoundStatus sfMusic_GetStatus(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get the current playing position of a music //////////////////////////////////////////////////////////// sfUint32 sfMusic_GetPlayingOffset(const sfMusic* music) { @@ -182,8 +154,6 @@ sfUint32 sfMusic_GetPlayingOffset(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Set the pitch of a music //////////////////////////////////////////////////////////// void sfMusic_SetPitch(sfMusic* music, float pitch) { @@ -191,8 +161,6 @@ void sfMusic_SetPitch(sfMusic* music, float pitch) } -//////////////////////////////////////////////////////////// -/// Set the volume of a music //////////////////////////////////////////////////////////// void sfMusic_SetVolume(sfMusic* music, float volume) { @@ -200,8 +168,6 @@ void sfMusic_SetVolume(sfMusic* music, float volume) } -//////////////////////////////////////////////////////////// -/// Set the position of a music //////////////////////////////////////////////////////////// void sfMusic_SetPosition(sfMusic* music, float x, float y, float z) { @@ -209,10 +175,6 @@ void sfMusic_SetPosition(sfMusic* music, float x, float y, float z) } -//////////////////////////////////////////////////////////// -/// Make the music's position relative to the listener's -/// position, or absolute. -/// The default value is false (absolute) //////////////////////////////////////////////////////////// void sfMusic_SetRelativeToListener(sfMusic* music, sfBool relative) { @@ -220,10 +182,6 @@ void sfMusic_SetRelativeToListener(sfMusic* music, sfBool relative) } -//////////////////////////////////////////////////////////// -/// Set the minimum distance - closer than this distance, -/// the listener will hear the music at its maximum volume. -/// The default minimum distance is 1.0 //////////////////////////////////////////////////////////// void sfMusic_SetMinDistance(sfMusic* music, float distance) { @@ -231,10 +189,6 @@ void sfMusic_SetMinDistance(sfMusic* music, float distance) } -//////////////////////////////////////////////////////////// -/// Set the attenuation factor - the higher the attenuation, the -/// more the sound will be attenuated with distance from listener. -/// The default attenuation factor 1.0 //////////////////////////////////////////////////////////// void sfMusic_SetAttenuation(sfMusic* music, float attenuation) { @@ -242,8 +196,6 @@ void sfMusic_SetAttenuation(sfMusic* music, float attenuation) } -//////////////////////////////////////////////////////////// -/// Set the current playing position of a stream //////////////////////////////////////////////////////////// void sfMusic_SetPlayingOffset(sfMusic* music, sfUint32 timeOffset) { @@ -251,8 +203,6 @@ void sfMusic_SetPlayingOffset(sfMusic* music, sfUint32 timeOffset) } -//////////////////////////////////////////////////////////// -/// Get the pitch of a music //////////////////////////////////////////////////////////// float sfMusic_GetPitch(const sfMusic* music) { @@ -260,8 +210,6 @@ float sfMusic_GetPitch(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get the volume of a music //////////////////////////////////////////////////////////// float sfMusic_GetVolume(const sfMusic* music) { @@ -269,8 +217,6 @@ float sfMusic_GetVolume(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get the position of a music //////////////////////////////////////////////////////////// void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, float* z) { @@ -286,9 +232,6 @@ void sfMusic_GetPosition(const sfMusic* music, float* x, float* y, float* z) } -//////////////////////////////////////////////////////////// -/// Tell if the music's position is relative to the listener's -/// position, or if it's absolute //////////////////////////////////////////////////////////// CSFML_API sfBool sfMusic_IsRelativeToListener(const sfMusic* music) { @@ -296,8 +239,6 @@ CSFML_API sfBool sfMusic_IsRelativeToListener(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get the minimum distance of a music //////////////////////////////////////////////////////////// float sfMusic_GetMinDistance(const sfMusic* music) { @@ -305,8 +246,6 @@ float sfMusic_GetMinDistance(const sfMusic* music) } -//////////////////////////////////////////////////////////// -/// Get the attenuation factor of a music //////////////////////////////////////////////////////////// float sfMusic_GetAttenuation(const sfMusic* music) { diff --git a/src/SFML/Audio/Sound.cpp b/src/SFML/Audio/Sound.cpp index cfd0aa3..a951f36 100644 --- a/src/SFML/Audio/Sound.cpp +++ b/src/SFML/Audio/Sound.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new sound //////////////////////////////////////////////////////////// sfSound* sfSound_Create(void) { @@ -39,8 +37,6 @@ sfSound* sfSound_Create(void) } -//////////////////////////////////////////////////////////// -/// Copy an existing sound //////////////////////////////////////////////////////////// sfSound* sfSound_Copy(sfSound* sound) { @@ -50,8 +46,6 @@ sfSound* sfSound_Copy(sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Destroy an existing sound //////////////////////////////////////////////////////////// void sfSound_Destroy(sfSound* sound) { @@ -59,8 +53,6 @@ void sfSound_Destroy(sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Start playing a sound //////////////////////////////////////////////////////////// void sfSound_Play(sfSound* sound) { @@ -68,8 +60,6 @@ void sfSound_Play(sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Pause a sound //////////////////////////////////////////////////////////// void sfSound_Pause(sfSound* sound) { @@ -77,8 +67,6 @@ void sfSound_Pause(sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Stop playing a sound //////////////////////////////////////////////////////////// void sfSound_Stop(sfSound* sound) { @@ -86,8 +74,6 @@ void sfSound_Stop(sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Bind a sound buffer to a sound //////////////////////////////////////////////////////////// void sfSound_SetBuffer(sfSound* sound, const sfSoundBuffer* buffer) { @@ -99,8 +85,6 @@ void sfSound_SetBuffer(sfSound* sound, const sfSoundBuffer* buffer) } -//////////////////////////////////////////////////////////// -/// Get the sound buffer bound to a sound //////////////////////////////////////////////////////////// const sfSoundBuffer* sfSound_GetBuffer(const sfSound* sound) { @@ -110,8 +94,6 @@ const sfSoundBuffer* sfSound_GetBuffer(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Set a sound loop state //////////////////////////////////////////////////////////// void sfSound_SetLoop(sfSound* sound, sfBool loop) { @@ -119,8 +101,6 @@ void sfSound_SetLoop(sfSound* sound, sfBool loop) } -//////////////////////////////////////////////////////////// -/// Tell whether or not a sound is looping //////////////////////////////////////////////////////////// sfBool sfSound_GetLoop(const sfSound* sound) { @@ -128,8 +108,6 @@ sfBool sfSound_GetLoop(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Get the status of a sound (stopped, paused, playing) //////////////////////////////////////////////////////////// sfSoundStatus sfSound_GetStatus(const sfSound* sound) { @@ -139,8 +117,6 @@ sfSoundStatus sfSound_GetStatus(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Set the pitch of a sound //////////////////////////////////////////////////////////// void sfSound_SetPitch(sfSound* sound, float pitch) { @@ -148,8 +124,6 @@ void sfSound_SetPitch(sfSound* sound, float pitch) } -//////////////////////////////////////////////////////////// -/// Set the volume of a sound //////////////////////////////////////////////////////////// void sfSound_SetVolume(sfSound* sound, float volume) { @@ -157,8 +131,6 @@ void sfSound_SetVolume(sfSound* sound, float volume) } -//////////////////////////////////////////////////////////// -/// Set the position of a sound //////////////////////////////////////////////////////////// void sfSound_SetPosition(sfSound* sound, float x, float y, float z) { @@ -166,10 +138,6 @@ void sfSound_SetPosition(sfSound* sound, float x, float y, float z) } -//////////////////////////////////////////////////////////// -/// Make the sound's position relative to the listener's -/// position, or absolute. -/// The default value is false (absolute) //////////////////////////////////////////////////////////// void sfSound_SetRelativeToListener(sfSound* sound, sfBool relative) { @@ -177,10 +145,6 @@ void sfSound_SetRelativeToListener(sfSound* sound, sfBool relative) } -//////////////////////////////////////////////////////////// -/// Set the minimum distance - closer than this distance, -/// the listener will hear the sound at its maximum volume. -/// The default minimum distance is 1.0 //////////////////////////////////////////////////////////// void sfSound_SetMinDistance(sfSound* sound, float distance) { @@ -188,10 +152,6 @@ void sfSound_SetMinDistance(sfSound* sound, float distance) } -//////////////////////////////////////////////////////////// -/// Set the attenuation factor - the higher the attenuation, the -/// more the sound will be attenuated with distance from listener. -/// The default attenuation factor is 1.0 //////////////////////////////////////////////////////////// void sfSound_SetAttenuation(sfSound* sound, float attenuation) { @@ -199,8 +159,6 @@ void sfSound_SetAttenuation(sfSound* sound, float attenuation) } -//////////////////////////////////////////////////////////// -/// Set the current playing position of a sound //////////////////////////////////////////////////////////// void sfSound_SetPlayingOffset(sfSound* sound, sfUint32 timeOffset) { @@ -208,8 +166,6 @@ void sfSound_SetPlayingOffset(sfSound* sound, sfUint32 timeOffset) } -//////////////////////////////////////////////////////////// -/// Get the pitch of a sound //////////////////////////////////////////////////////////// float sfSound_GetPitch(const sfSound* sound) { @@ -217,8 +173,6 @@ float sfSound_GetPitch(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Get the volume of a sound //////////////////////////////////////////////////////////// float sfSound_GetVolume(const sfSound* sound) { @@ -226,8 +180,6 @@ float sfSound_GetVolume(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Get the position of a sound //////////////////////////////////////////////////////////// void sfSound_GetPosition(const sfSound* sound, float* x, float* y, float* z) { @@ -240,9 +192,6 @@ void sfSound_GetPosition(const sfSound* sound, float* x, float* y, float* z) } -//////////////////////////////////////////////////////////// -/// Tell if the sound's position is relative to the listener's -/// position, or if it's absolute //////////////////////////////////////////////////////////// CSFML_API sfBool sfSound_IsRelativeToListener(const sfSound* sound) { @@ -250,8 +199,6 @@ CSFML_API sfBool sfSound_IsRelativeToListener(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Get the minimum distance of a sound //////////////////////////////////////////////////////////// float sfSound_GetMinDistance(const sfSound* sound) { @@ -259,8 +206,6 @@ float sfSound_GetMinDistance(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Get the attenuation factor of a sound //////////////////////////////////////////////////////////// float sfSound_GetAttenuation(const sfSound* sound) { @@ -268,8 +213,6 @@ float sfSound_GetAttenuation(const sfSound* sound) } -//////////////////////////////////////////////////////////// -/// Get the current playing position of a sound //////////////////////////////////////////////////////////// sfUint32 sfSound_GetPlayingOffset(const sfSound* sound) { diff --git a/src/SFML/Audio/SoundBuffer.cpp b/src/SFML/Audio/SoundBuffer.cpp index eb0040f..de43ac4 100644 --- a/src/SFML/Audio/SoundBuffer.cpp +++ b/src/SFML/Audio/SoundBuffer.cpp @@ -27,11 +27,10 @@ //////////////////////////////////////////////////////////// #include #include +#include #include -//////////////////////////////////////////////////////////// -/// Create a new sound buffer and load it from a file //////////////////////////////////////////////////////////// sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename) { @@ -47,8 +46,6 @@ sfSoundBuffer* sfSoundBuffer_CreateFromFile(const char* filename) } -//////////////////////////////////////////////////////////// -/// Create a new sound buffer and load it from a file in memory //////////////////////////////////////////////////////////// sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t sizeInBytes) { @@ -64,10 +61,24 @@ sfSoundBuffer* sfSoundBuffer_CreateFromMemory(const void* data, size_t sizeInByt } + //////////////////////////////////////////////////////////// -/// Create a new sound buffer and load it from an array of -/// samples in memory - assumed format for samples is -/// 16 bits signed integer +CSFML_API sfSoundBuffer* sfSoundBuffer_CreateFromStream(sfInputStream* stream) +{ + CSFML_CHECK_RETURN(stream, NULL); + + sfSoundBuffer* buffer = new sfSoundBuffer; + CallbackStream sfmlStream(stream); + if (!buffer->This.LoadFromStream(sfmlStream)) + { + delete buffer; + buffer = NULL; + } + + return buffer; +} + + //////////////////////////////////////////////////////////// sfSoundBuffer* sfSoundBuffer_CreateFromSamples(const sfInt16* samples, size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate) { @@ -83,8 +94,6 @@ sfSoundBuffer* sfSoundBuffer_CreateFromSamples(const sfInt16* samples, size_t sa } -//////////////////////////////////////////////////////////// -/// Copy an existing sound buffer //////////////////////////////////////////////////////////// sfSoundBuffer* sfSoundBuffer_Copy(sfSoundBuffer* soundBuffer) { @@ -94,8 +103,6 @@ sfSoundBuffer* sfSoundBuffer_Copy(sfSoundBuffer* soundBuffer) } -//////////////////////////////////////////////////////////// -/// Destroy an existing sound buffer //////////////////////////////////////////////////////////// void sfSoundBuffer_Destroy(sfSoundBuffer* soundBuffer) { @@ -103,8 +110,6 @@ void sfSoundBuffer_Destroy(sfSoundBuffer* soundBuffer) } -//////////////////////////////////////////////////////////// -/// Save a sound buffer to a file //////////////////////////////////////////////////////////// sfBool sfSoundBuffer_SaveToFile(const sfSoundBuffer* soundBuffer, const char* filename) { @@ -112,8 +117,6 @@ sfBool sfSoundBuffer_SaveToFile(const sfSoundBuffer* soundBuffer, const char* fi } -//////////////////////////////////////////////////////////// -/// Return the samples contained in a sound buffer //////////////////////////////////////////////////////////// const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuffer) { @@ -121,8 +124,6 @@ const sfInt16* sfSoundBuffer_GetSamples(const sfSoundBuffer* soundBuffer) } -//////////////////////////////////////////////////////////// -/// Return the number of samples contained in a sound buffer //////////////////////////////////////////////////////////// size_t sfSoundBuffer_GetSamplesCount(const sfSoundBuffer* soundBuffer) { @@ -130,8 +131,6 @@ size_t sfSoundBuffer_GetSamplesCount(const sfSoundBuffer* soundBuffer) } -//////////////////////////////////////////////////////////// -/// Get the sample rate of a sound buffer //////////////////////////////////////////////////////////// unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuffer) { @@ -139,8 +138,6 @@ unsigned int sfSoundBuffer_GetSampleRate(const sfSoundBuffer* soundBuffer) } -//////////////////////////////////////////////////////////// -/// Return the number of channels of a sound buffer (1 = mono, 2 = stereo, ...) //////////////////////////////////////////////////////////// unsigned int sfSoundBuffer_GetChannelsCount(const sfSoundBuffer* soundBuffer) { @@ -148,8 +145,6 @@ unsigned int sfSoundBuffer_GetChannelsCount(const sfSoundBuffer* soundBuffer) } -//////////////////////////////////////////////////////////// -/// Get the duration of a sound buffer //////////////////////////////////////////////////////////// sfUint32 sfSoundBuffer_GetDuration(const sfSoundBuffer* soundBuffer) { diff --git a/src/SFML/Audio/SoundBufferRecorder.cpp b/src/SFML/Audio/SoundBufferRecorder.cpp index 04d8fc3..cbd5a01 100644 --- a/src/SFML/Audio/SoundBufferRecorder.cpp +++ b/src/SFML/Audio/SoundBufferRecorder.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new sound buffer recorder //////////////////////////////////////////////////////////// sfSoundBufferRecorder* sfSoundBufferRecorder_Create(void) { @@ -39,8 +37,6 @@ sfSoundBufferRecorder* sfSoundBufferRecorder_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing sound buffer recorder //////////////////////////////////////////////////////////// void sfSoundBufferRecorder_Destroy(sfSoundBufferRecorder* soundBufferRecorder) { @@ -48,9 +44,6 @@ void sfSoundBufferRecorder_Destroy(sfSoundBufferRecorder* soundBufferRecorder) } -//////////////////////////////////////////////////////////// -/// Start the capture. -/// Warning : only one capture can happen at the same time //////////////////////////////////////////////////////////// void sfSoundBufferRecorder_Start(sfSoundBufferRecorder* soundBufferRecorder, unsigned int sampleRate) { @@ -58,8 +51,6 @@ void sfSoundBufferRecorder_Start(sfSoundBufferRecorder* soundBufferRecorder, uns } -//////////////////////////////////////////////////////////// -/// Stop the capture //////////////////////////////////////////////////////////// void sfSoundBufferRecorder_Stop(sfSoundBufferRecorder* soundBufferRecorder) { @@ -67,8 +58,6 @@ void sfSoundBufferRecorder_Stop(sfSoundBufferRecorder* soundBufferRecorder) } -//////////////////////////////////////////////////////////// -/// Get the sample rate of a sound buffer recorder //////////////////////////////////////////////////////////// unsigned int sfSoundBufferRecorder_GetSampleRate(const sfSoundBufferRecorder* soundBufferRecorder) { @@ -76,9 +65,6 @@ unsigned int sfSoundBufferRecorder_GetSampleRate(const sfSoundBufferRecorder* so } -//////////////////////////////////////////////////////////// -/// Get the sound buffer containing the captured audio data -/// of a sound buffer recorder //////////////////////////////////////////////////////////// const sfSoundBuffer* sfSoundBufferRecorder_GetBuffer(const sfSoundBufferRecorder* soundBufferRecorder) { diff --git a/src/SFML/Audio/SoundRecorder.cpp b/src/SFML/Audio/SoundRecorder.cpp index a925cf9..337e362 100644 --- a/src/SFML/Audio/SoundRecorder.cpp +++ b/src/SFML/Audio/SoundRecorder.cpp @@ -30,9 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new sound recorder with callback functions -/// for processing captured samples //////////////////////////////////////////////////////////// sfSoundRecorder* sfSoundRecorder_Create(sfSoundRecorderStartCallback onStart, sfSoundRecorderProcessCallback onProcess, @@ -43,8 +40,6 @@ sfSoundRecorder* sfSoundRecorder_Create(sfSoundRecorderStartCallback onStart, } -//////////////////////////////////////////////////////////// -/// Destroy an existing sound recorder //////////////////////////////////////////////////////////// void sfSoundRecorder_Destroy(sfSoundRecorder* soundRecorder) { @@ -52,9 +47,6 @@ void sfSoundRecorder_Destroy(sfSoundRecorder* soundRecorder) } -//////////////////////////////////////////////////////////// -/// Start the capture. -/// Warning : only one capture can happen at the same time //////////////////////////////////////////////////////////// void sfSoundRecorder_Start(sfSoundRecorder* soundRecorder, unsigned int sampleRate) { @@ -62,8 +54,6 @@ void sfSoundRecorder_Start(sfSoundRecorder* soundRecorder, unsigned int sampleRa } -//////////////////////////////////////////////////////////// -/// Stop the capture //////////////////////////////////////////////////////////// void sfSoundRecorder_Stop(sfSoundRecorder* soundRecorder) { @@ -71,8 +61,6 @@ void sfSoundRecorder_Stop(sfSoundRecorder* soundRecorder) } -//////////////////////////////////////////////////////////// -/// Get the sample rate of a sound recorder //////////////////////////////////////////////////////////// unsigned int sfSoundRecorder_GetSampleRate(const sfSoundRecorder* soundRecorder) { @@ -80,9 +68,6 @@ unsigned int sfSoundRecorder_GetSampleRate(const sfSoundRecorder* soundRecorder) } -//////////////////////////////////////////////////////////// -/// Tell if the system supports sound capture. -/// If not, this class won't be usable //////////////////////////////////////////////////////////// sfBool sfSoundRecorder_IsAvailable(void) { diff --git a/src/SFML/Audio/SoundStream.cpp b/src/SFML/Audio/SoundStream.cpp index da3d36c..932867e 100644 --- a/src/SFML/Audio/SoundStream.cpp +++ b/src/SFML/Audio/SoundStream.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new sound stream //////////////////////////////////////////////////////////// sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGetData, sfSoundStreamSeekCallback onSeek, @@ -43,8 +41,6 @@ sfSoundStream* sfSoundStream_Create(sfSoundStreamGetDataCallback onGetData, } -//////////////////////////////////////////////////////////// -/// Destroy an existing sound stream //////////////////////////////////////////////////////////// void sfSoundStream_Destroy(sfSoundStream* soundStream) { @@ -52,8 +48,6 @@ void sfSoundStream_Destroy(sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Start playing a sound stream //////////////////////////////////////////////////////////// void sfSoundStream_Play(sfSoundStream* soundStream) { @@ -61,8 +55,6 @@ void sfSoundStream_Play(sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Pause a sound stream //////////////////////////////////////////////////////////// void sfSoundStream_Pause(sfSoundStream* soundStream) { @@ -70,8 +62,6 @@ void sfSoundStream_Pause(sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Stop playing a sound stream //////////////////////////////////////////////////////////// void sfSoundStream_Stop(sfSoundStream* soundStream) { @@ -79,8 +69,6 @@ void sfSoundStream_Stop(sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Get the status of a sound stream (stopped, paused, playing) //////////////////////////////////////////////////////////// sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream) { @@ -90,9 +78,6 @@ sfSoundStatus sfSoundStream_GetStatus(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Return the number of channels of a sound stream -/// (1 = mono, 2 = stereo) //////////////////////////////////////////////////////////// unsigned int sfSoundStream_GetChannelsCount(const sfSoundStream* soundStream) { @@ -100,8 +85,6 @@ unsigned int sfSoundStream_GetChannelsCount(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Get the sample rate of a sound stream //////////////////////////////////////////////////////////// unsigned int sfSoundStream_GetSampleRate(const sfSoundStream* soundStream) { @@ -109,8 +92,6 @@ unsigned int sfSoundStream_GetSampleRate(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Set the pitch of a sound stream //////////////////////////////////////////////////////////// void sfSoundStream_SetPitch(sfSoundStream* soundStream, float pitch) { @@ -118,8 +99,6 @@ void sfSoundStream_SetPitch(sfSoundStream* soundStream, float pitch) } -//////////////////////////////////////////////////////////// -/// Set the volume of a sound stream //////////////////////////////////////////////////////////// void sfSoundStream_SetVolume(sfSoundStream* soundStream, float volume) { @@ -127,8 +106,6 @@ void sfSoundStream_SetVolume(sfSoundStream* soundStream, float volume) } -//////////////////////////////////////////////////////////// -/// Set the position of a sound stream //////////////////////////////////////////////////////////// void sfSoundStream_SetPosition(sfSoundStream* soundStream, float x, float y, float z) { @@ -136,10 +113,6 @@ void sfSoundStream_SetPosition(sfSoundStream* soundStream, float x, float y, flo } -//////////////////////////////////////////////////////////// -/// Make the sound stream's position relative to the listener's -/// position, or absolute. -/// The default value is false (absolute) //////////////////////////////////////////////////////////// void sfSoundStream_SetRelativeToListener(sfSoundStream* soundStream, sfBool relative) { @@ -147,10 +120,6 @@ void sfSoundStream_SetRelativeToListener(sfSoundStream* soundStream, sfBool rela } -//////////////////////////////////////////////////////////// -/// Set the minimum distance - closer than this distance, -/// the listener will hear the sound stream at its maximum volume. -/// The default minimum distance is 1.0 //////////////////////////////////////////////////////////// void sfSoundStream_SetMinDistance(sfSoundStream* soundStream, float distance) { @@ -158,10 +127,6 @@ void sfSoundStream_SetMinDistance(sfSoundStream* soundStream, float distance) } -//////////////////////////////////////////////////////////// -/// Set the attenuation factor - the higher the attenuation, the -/// more the sound stream will be attenuated with distance from listener. -/// The default attenuation factor 1.0 //////////////////////////////////////////////////////////// void sfSoundStream_SetAttenuation(sfSoundStream* soundStream, float attenuation) { @@ -169,8 +134,6 @@ void sfSoundStream_SetAttenuation(sfSoundStream* soundStream, float attenuation) } -//////////////////////////////////////////////////////////// -/// Set the current playing position of a stream //////////////////////////////////////////////////////////// void sfSoundStream_SetPlayingOffset(sfSoundStream* soundStream, sfUint32 timeOffset) { @@ -178,8 +141,6 @@ void sfSoundStream_SetPlayingOffset(sfSoundStream* soundStream, sfUint32 timeOff } -//////////////////////////////////////////////////////////// -/// Set a stream loop state //////////////////////////////////////////////////////////// void sfSoundStream_SetLoop(sfSoundStream* soundStream, sfBool loop) { @@ -187,8 +148,6 @@ void sfSoundStream_SetLoop(sfSoundStream* soundStream, sfBool loop) } -//////////////////////////////////////////////////////////// -/// Get the pitch of a sound stream //////////////////////////////////////////////////////////// float sfSoundStream_GetPitch(const sfSoundStream* soundStream) { @@ -196,8 +155,6 @@ float sfSoundStream_GetPitch(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Get the volume of a sound stream //////////////////////////////////////////////////////////// float sfSoundStream_GetVolume(const sfSoundStream* soundStream) { @@ -205,8 +162,6 @@ float sfSoundStream_GetVolume(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Get the position of a sound stream //////////////////////////////////////////////////////////// void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float* x, float* y, float* z) { @@ -219,9 +174,6 @@ void sfSoundStream_GetPosition(const sfSoundStream* soundStream, float* x, float } -//////////////////////////////////////////////////////////// -/// Tell if the sound stream's position is relative to the listener's -/// position, or if it's absolute //////////////////////////////////////////////////////////// CSFML_API sfBool sfSoundStream_IsRelativeToListener(const sfSoundStream* soundStream) { @@ -229,8 +181,6 @@ CSFML_API sfBool sfSoundStream_IsRelativeToListener(const sfSoundStream* soundSt } -//////////////////////////////////////////////////////////// -/// Get the minimum distance of a sound stream //////////////////////////////////////////////////////////// float sfSoundStream_GetMinDistance(const sfSoundStream* soundStream) { @@ -238,8 +188,6 @@ float sfSoundStream_GetMinDistance(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Get the attenuation factor of a sound stream //////////////////////////////////////////////////////////// float sfSoundStream_GetAttenuation(const sfSoundStream* soundStream) { @@ -247,8 +195,6 @@ float sfSoundStream_GetAttenuation(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Tell whether or not a stream is looping //////////////////////////////////////////////////////////// sfBool sfSoundStream_GetLoop(const sfSoundStream* soundStream) { @@ -256,8 +202,6 @@ sfBool sfSoundStream_GetLoop(const sfSoundStream* soundStream) } -//////////////////////////////////////////////////////////// -/// Get the current playing position of a sound stream //////////////////////////////////////////////////////////// sfUint32 sfSoundStream_GetPlayingOffset(const sfSoundStream* soundStream) { diff --git a/src/SFML/Network/Ftp.cpp b/src/SFML/Network/Ftp.cpp index da144c6..f9eaab6 100644 --- a/src/SFML/Network/Ftp.cpp +++ b/src/SFML/Network/Ftp.cpp @@ -31,8 +31,6 @@ #include -//////////////////////////////////////////////////////////// -/// Destroy an existing Ftp directory response //////////////////////////////////////////////////////////// void sfFtpListingResponse_Destroy(sfFtpListingResponse* ftpListingResponse) { @@ -40,9 +38,6 @@ void sfFtpListingResponse_Destroy(sfFtpListingResponse* ftpListingResponse) } -//////////////////////////////////////////////////////////// -/// Convenience function to check if the response status code -/// means a success //////////////////////////////////////////////////////////// sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListingResponse) { @@ -50,8 +45,6 @@ sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListingResponse) } -//////////////////////////////////////////////////////////// -/// Get the response status code //////////////////////////////////////////////////////////// sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* ftpListingResponse) { @@ -61,8 +54,6 @@ sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* ftpListin } -//////////////////////////////////////////////////////////// -/// Get the full message contained in the response //////////////////////////////////////////////////////////// const char* sfFtpListingResponse_GetMessage(const sfFtpListingResponse* ftpListingResponse) { @@ -72,8 +63,6 @@ const char* sfFtpListingResponse_GetMessage(const sfFtpListingResponse* ftpListi } -//////////////////////////////////////////////////////////// -/// Get the number of filenames in the listing //////////////////////////////////////////////////////////// size_t sfFtpListingResponse_GetCount(const sfFtpListingResponse* ftpListingResponse) { @@ -83,8 +72,6 @@ size_t sfFtpListingResponse_GetCount(const sfFtpListingResponse* ftpListingRespo } -//////////////////////////////////////////////////////////// -/// Get the Index-th filename in the directory //////////////////////////////////////////////////////////// const char* sfFtpListingResponse_GetFilename(const sfFtpListingResponse* ftpListingResponse, size_t index) { @@ -94,8 +81,6 @@ const char* sfFtpListingResponse_GetFilename(const sfFtpListingResponse* ftpList } -//////////////////////////////////////////////////////////// -/// Destroy an existing Ftp directory response //////////////////////////////////////////////////////////// void sfFtpDirectoryResponse_Destroy(sfFtpDirectoryResponse* ftpDirectoryResponse) { @@ -103,9 +88,6 @@ void sfFtpDirectoryResponse_Destroy(sfFtpDirectoryResponse* ftpDirectoryResponse } -//////////////////////////////////////////////////////////// -/// Convenience function to check if the response status code -/// means a success //////////////////////////////////////////////////////////// sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDirectoryResponse) { @@ -113,8 +95,6 @@ sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDirectoryRes } -//////////////////////////////////////////////////////////// -/// Get the response status code //////////////////////////////////////////////////////////// sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryResponse* ftpDirectoryResponse) { @@ -124,8 +104,6 @@ sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryResponse* ftpDi } -//////////////////////////////////////////////////////////// -/// Get the full message contained in the response //////////////////////////////////////////////////////////// const char* sfFtpDirectoryResponse_GetMessage(const sfFtpDirectoryResponse* ftpDirectoryResponse) { @@ -135,8 +113,6 @@ const char* sfFtpDirectoryResponse_GetMessage(const sfFtpDirectoryResponse* ftpD } -//////////////////////////////////////////////////////////// -/// Get the directory returned in the response //////////////////////////////////////////////////////////// const char* sfFtpDirectoryResponse_GetDirectory(const sfFtpDirectoryResponse* ftpDirectoryResponse) { @@ -146,8 +122,6 @@ const char* sfFtpDirectoryResponse_GetDirectory(const sfFtpDirectoryResponse* ft } -//////////////////////////////////////////////////////////// -/// Destroy an existing Ftp response //////////////////////////////////////////////////////////// void sfFtpResponse_Destroy(sfFtpResponse* ftpResponse) { @@ -155,9 +129,6 @@ void sfFtpResponse_Destroy(sfFtpResponse* ftpResponse) } -//////////////////////////////////////////////////////////// -/// Convenience function to check if the response status code -/// means a success //////////////////////////////////////////////////////////// sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse) { @@ -165,8 +136,6 @@ sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse) } -//////////////////////////////////////////////////////////// -/// Get the response status code //////////////////////////////////////////////////////////// sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse) { @@ -176,8 +145,6 @@ sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse) } -//////////////////////////////////////////////////////////// -/// Get the full message contained in the response //////////////////////////////////////////////////////////// const char* sfFtpResponse_GetMessage(const sfFtpResponse* ftpResponse) { @@ -187,8 +154,6 @@ const char* sfFtpResponse_GetMessage(const sfFtpResponse* ftpResponse) } -//////////////////////////////////////////////////////////// -/// Construct a new Ftp //////////////////////////////////////////////////////////// sfFtp* sfFtp_Create(void) { @@ -196,8 +161,6 @@ sfFtp* sfFtp_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing Ftp //////////////////////////////////////////////////////////// void sfFtp_Destroy(sfFtp* ftp) { @@ -205,8 +168,6 @@ void sfFtp_Destroy(sfFtp* ftp) } -//////////////////////////////////////////////////////////// -/// Connect to the specified FTP server //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned short port, sfUint32 timeout) { @@ -218,8 +179,6 @@ sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned short port } -//////////////////////////////////////////////////////////// -/// Log in using anonymous account //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp) { @@ -229,8 +188,6 @@ sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp) } -//////////////////////////////////////////////////////////// -/// Log in using a username and a password //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const char* password) { @@ -240,8 +197,6 @@ sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const char* passwor } -//////////////////////////////////////////////////////////// -/// Close the connection with FTP server //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp) { @@ -251,8 +206,6 @@ sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp) } -//////////////////////////////////////////////////////////// -/// Send a null command just to prevent from being disconnected //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp) { @@ -262,8 +215,6 @@ sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp) } -//////////////////////////////////////////////////////////// -/// Get the current working directory //////////////////////////////////////////////////////////// sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp) { @@ -273,9 +224,6 @@ sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp) } -//////////////////////////////////////////////////////////// -/// Get the contents of the given directory -/// (subdirectories and files) //////////////////////////////////////////////////////////// sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char* directory) { @@ -285,8 +233,6 @@ sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char* director } -//////////////////////////////////////////////////////////// -/// Change the current working directory //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory) { @@ -296,8 +242,6 @@ sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory) } -//////////////////////////////////////////////////////////// -/// Go to the parent directory of the current one //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp) { @@ -307,8 +251,6 @@ sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp) } -//////////////////////////////////////////////////////////// -/// Create a new directory //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name) { @@ -318,8 +260,6 @@ sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name) } -//////////////////////////////////////////////////////////// -/// Remove an existing directory //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name) { @@ -329,8 +269,6 @@ sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name) } -//////////////////////////////////////////////////////////// -/// Rename a file //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const char* newName) { @@ -340,8 +278,6 @@ sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const char* newNam } -//////////////////////////////////////////////////////////// -/// Remove an existing file //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name) { @@ -351,8 +287,6 @@ sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name) } -//////////////////////////////////////////////////////////// -/// Download a file from the server //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_Download(sfFtp* ftp, const char* distantFile, const char* destPath, sfFtpTransferMode mode) { @@ -364,8 +298,6 @@ sfFtpResponse* sfFtp_Download(sfFtp* ftp, const char* distantFile, const char* d } -//////////////////////////////////////////////////////////// -/// Upload a file to the server //////////////////////////////////////////////////////////// sfFtpResponse* sfFtp_Upload(sfFtp* ftp, const char* localFile, const char* destPath, sfFtpTransferMode mode) { diff --git a/src/SFML/Network/Http.cpp b/src/SFML/Network/Http.cpp index 21f32f4..31751b0 100644 --- a/src/SFML/Network/Http.cpp +++ b/src/SFML/Network/Http.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new Http request //////////////////////////////////////////////////////////// sfHttpRequest* sfHttpRequest_Create(void) { @@ -39,8 +37,6 @@ sfHttpRequest* sfHttpRequest_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing Http request //////////////////////////////////////////////////////////// void sfHttpRequest_Destroy(sfHttpRequest* httpRequest) { @@ -48,8 +44,6 @@ void sfHttpRequest_Destroy(sfHttpRequest* httpRequest) } -//////////////////////////////////////////////////////////// -/// Set the value of a field; the field is added if it doesn't exist //////////////////////////////////////////////////////////// void sfHttpRequest_SetField(sfHttpRequest* httpRequest, const char* field, const char* value) { @@ -59,9 +53,6 @@ void sfHttpRequest_SetField(sfHttpRequest* httpRequest, const char* field, const } -//////////////////////////////////////////////////////////// -/// Set the request method. -/// This parameter is sfHttpGet by default //////////////////////////////////////////////////////////// void sfHttpRequest_SetMethod(sfHttpRequest* httpRequest, sfHttpMethod method) { @@ -69,9 +60,6 @@ void sfHttpRequest_SetMethod(sfHttpRequest* httpRequest, sfHttpMethod method) } -//////////////////////////////////////////////////////////// -/// Set the target URI of the request. -/// This parameter is "/" by default //////////////////////////////////////////////////////////// void sfHttpRequest_SetUri(sfHttpRequest* httpRequest, const char* uri) { @@ -79,9 +67,6 @@ void sfHttpRequest_SetUri(sfHttpRequest* httpRequest, const char* uri) } -//////////////////////////////////////////////////////////// -/// Set the HTTP version of the request. -/// This parameter is 1.0 by default //////////////////////////////////////////////////////////// void sfHttpRequest_SetHttpVersion(sfHttpRequest* httpRequest, unsigned int major, unsigned int minor) { @@ -89,10 +74,6 @@ void sfHttpRequest_SetHttpVersion(sfHttpRequest* httpRequest, unsigned int major } -//////////////////////////////////////////////////////////// -/// Set the body of the request. This parameter is optional and -/// makes sense only for POST requests. -/// This parameter is empty by default //////////////////////////////////////////////////////////// void sfHttpRequest_SetBody(sfHttpRequest* httpRequest, const char* body) { @@ -100,8 +81,6 @@ void sfHttpRequest_SetBody(sfHttpRequest* httpRequest, const char* body) } -//////////////////////////////////////////////////////////// -/// Destroy an existing Http response //////////////////////////////////////////////////////////// void sfHttpResponse_Destroy(sfHttpResponse* httpResponse) { @@ -109,8 +88,6 @@ void sfHttpResponse_Destroy(sfHttpResponse* httpResponse) } -//////////////////////////////////////////////////////////// -/// Get the value of a field; returns NULL if the field doesn't exist //////////////////////////////////////////////////////////// const char* sfHttpResponse_GetField(const sfHttpResponse* httpResponse, const char* field) { @@ -122,8 +99,6 @@ const char* sfHttpResponse_GetField(const sfHttpResponse* httpResponse, const ch } -//////////////////////////////////////////////////////////// -/// Get the status of a response //////////////////////////////////////////////////////////// sfHttpStatus sfHttpResponse_GetStatus(const sfHttpResponse* httpResponse) { @@ -133,8 +108,6 @@ sfHttpStatus sfHttpResponse_GetStatus(const sfHttpResponse* httpResponse) } -//////////////////////////////////////////////////////////// -/// Get the major HTTP version of a response //////////////////////////////////////////////////////////// unsigned int sfHttpResponse_GetMajorVersion(const sfHttpResponse* httpResponse) { @@ -142,8 +115,6 @@ unsigned int sfHttpResponse_GetMajorVersion(const sfHttpResponse* httpResponse) } -//////////////////////////////////////////////////////////// -/// Get the minor HTTP version of a response //////////////////////////////////////////////////////////// unsigned int sfHttpResponse_GetMinorVersion(const sfHttpResponse* httpResponse) { @@ -151,12 +122,6 @@ unsigned int sfHttpResponse_GetMinorVersion(const sfHttpResponse* httpResponse) } -//////////////////////////////////////////////////////////// -/// Get the body of the response. The body can contain : -/// - the requested page (for GET requests) -/// - a response from the server (for POST requests) -/// - nothing (for HEAD requests) -/// - an error message (in case of an error) //////////////////////////////////////////////////////////// const char* sfHttpResponse_GetBody(const sfHttpResponse* httpResponse) { @@ -166,8 +131,6 @@ const char* sfHttpResponse_GetBody(const sfHttpResponse* httpResponse) } -//////////////////////////////////////////////////////////// -/// Construct a new Http object //////////////////////////////////////////////////////////// sfHttp* sfHttp_Create(void) { @@ -175,8 +138,6 @@ sfHttp* sfHttp_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing Http object //////////////////////////////////////////////////////////// void sfHttp_Destroy(sfHttp* http) { @@ -184,8 +145,6 @@ void sfHttp_Destroy(sfHttp* http) } -//////////////////////////////////////////////////////////// -/// Set the target host of a Http server //////////////////////////////////////////////////////////// void sfHttp_SetHost(sfHttp* http, const char* host, unsigned short port) { @@ -193,13 +152,6 @@ void sfHttp_SetHost(sfHttp* http, const char* host, unsigned short port) } -//////////////////////////////////////////////////////////// -/// Send a HTTP request and return the server's response. -/// You must be connected to a host before sending requests. -/// Any missing mandatory header field will be added with an appropriate value. -/// Warning : this function waits for the server's response and may -/// not return instantly; use a thread if you don't want to block your -/// application. //////////////////////////////////////////////////////////// sfHttpResponse* sfHttp_SendRequest(sfHttp* http, const sfHttpRequest* request, sfUint32 timeout) { diff --git a/src/SFML/Network/IpAddress.cpp b/src/SFML/Network/IpAddress.cpp index fb0c482..555156c 100644 --- a/src/SFML/Network/IpAddress.cpp +++ b/src/SFML/Network/IpAddress.cpp @@ -32,9 +32,7 @@ namespace { - //////////////////////////////////////////////////////////// - /// Helper function for converting a SFML address to a CSFML one - //////////////////////////////////////////////////////////// + // Helper function for converting a SFML address to a CSFML one sfIpAddress FromSFMLAddress(sf::IpAddress address) { sfIpAddress result; @@ -43,9 +41,7 @@ namespace return result; } - //////////////////////////////////////////////////////////// - /// Helper function for converting a CSFML address to a SFML one - //////////////////////////////////////////////////////////// + // Helper function for converting a CSFML address to a SFML one sf::IpAddress ToSFMLAddress(sfIpAddress address) { return sf::IpAddress(address.Address); @@ -54,16 +50,12 @@ namespace //////////////////////////////////////////////////////////// -/// Construct an address from a string -//////////////////////////////////////////////////////////// -sfIpAddress sfIpAddress_FromString(const char* string) +sfIpAddress sfIpAddress_FromString(const char* address) { - return FromSFMLAddress(sf::IpAddress(string)); + return FromSFMLAddress(sf::IpAddress(address)); } -//////////////////////////////////////////////////////////// -/// Construct an address from 4 bytes //////////////////////////////////////////////////////////// sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, sfUint8 byte3) { @@ -71,8 +63,6 @@ sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, s } -//////////////////////////////////////////////////////////// -/// Construct the address from a 32-bits integer //////////////////////////////////////////////////////////// sfIpAddress sfIpAddress_FromInteger(sfUint32 address) { @@ -80,8 +70,6 @@ sfIpAddress sfIpAddress_FromInteger(sfUint32 address) } -//////////////////////////////////////////////////////////// -/// Get a string representation of an address //////////////////////////////////////////////////////////// void sfIpAddress_ToString(sfIpAddress address, char* string) { @@ -90,8 +78,6 @@ void sfIpAddress_ToString(sfIpAddress address, char* string) } -//////////////////////////////////////////////////////////// -/// Get an integer representation of the address //////////////////////////////////////////////////////////// sfUint32 sfIpAddress_ToInteger(sfIpAddress address) { @@ -99,8 +85,6 @@ sfUint32 sfIpAddress_ToInteger(sfIpAddress address) } -//////////////////////////////////////////////////////////// -/// Get the computer's local IP address (from the LAN point of view) //////////////////////////////////////////////////////////// sfIpAddress sfIpAddress_GetLocalAddress(void) { @@ -108,11 +92,6 @@ sfIpAddress sfIpAddress_GetLocalAddress(void) } -//////////////////////////////////////////////////////////// -/// Get the computer's public IP address (from the web point of view). -/// The only way to get a public address is to ask it to a -/// distant website ; as a consequence, this function may be -/// very slow -- use it as few as possible ! //////////////////////////////////////////////////////////// sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout) { @@ -120,16 +99,12 @@ sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout) } -//////////////////////////////////////////////////////////// -/// Get the computer's loopback address //////////////////////////////////////////////////////////// sfIpAddress sfIpAddress_LocalHost(void) { return FromSFMLAddress(sf::IpAddress::LocalHost); } -//////////////////////////////////////////////////////////// -/// Get the empty/invalid address //////////////////////////////////////////////////////////// sfIpAddress sfIpAddress_None(void) { diff --git a/src/SFML/Network/Packet.cpp b/src/SFML/Network/Packet.cpp index 6317f72..c122dd3 100644 --- a/src/SFML/Network/Packet.cpp +++ b/src/SFML/Network/Packet.cpp @@ -32,9 +32,7 @@ namespace { - //////////////////////////////////////////////////////////// - /// Helper function to read a variable from a packet - //////////////////////////////////////////////////////////// + // Helper function to read a variable from a packet template T PacketRead(sfPacket* packet) { @@ -45,9 +43,7 @@ namespace return value; } - //////////////////////////////////////////////////////////// - /// Helper function to write a variable to a packet - //////////////////////////////////////////////////////////// + // Helper function to write a variable to a packet template void PacketWrite(sfPacket* packet, T value) { @@ -58,8 +54,6 @@ namespace } -//////////////////////////////////////////////////////////// -/// Create a new empty packet //////////////////////////////////////////////////////////// sfPacket* sfPacket_Create(void) { @@ -67,8 +61,6 @@ sfPacket* sfPacket_Create(void) } -//////////////////////////////////////////////////////////// -/// Copy an existing packet //////////////////////////////////////////////////////////// sfPacket* sfPacket_Copy(sfPacket* packet) { @@ -78,8 +70,6 @@ sfPacket* sfPacket_Copy(sfPacket* packet) } -//////////////////////////////////////////////////////////// -/// Destroy an existing packet //////////////////////////////////////////////////////////// void sfPacket_Destroy(sfPacket* packet) { @@ -87,8 +77,6 @@ void sfPacket_Destroy(sfPacket* packet) } -//////////////////////////////////////////////////////////// -/// Append data to the end of a packet //////////////////////////////////////////////////////////// void sfPacket_Append(sfPacket* packet, const void* data, size_t sizeInBytes) { @@ -97,18 +85,12 @@ void sfPacket_Append(sfPacket* packet, const void* data, size_t sizeInBytes) //////////////////////////////////////////////////////////// -/// Clear all the data of a packet -/////////////////////////////////////////////////////////// void sfPacket_Clear(sfPacket* packet) { CSFML_CALL(packet, Clear()); } -//////////////////////////////////////////////////////////// -/// Get a pointer to the data contained in a packet -/// Warning : the returned pointer may be invalid after you -/// append data to the packet //////////////////////////////////////////////////////////// const char* sfPacket_GetData(const sfPacket* packet) { @@ -116,8 +98,6 @@ const char* sfPacket_GetData(const sfPacket* packet) } -//////////////////////////////////////////////////////////// -/// Get the size of the data contained in a packet //////////////////////////////////////////////////////////// size_t sfPacket_GetDataSize(const sfPacket* packet) { @@ -125,8 +105,6 @@ size_t sfPacket_GetDataSize(const sfPacket* packet) } -//////////////////////////////////////////////////////////// -/// Tell if the reading position has reached the end of the packet //////////////////////////////////////////////////////////// sfBool sfPacket_EndOfPacket(const sfPacket* packet) { @@ -134,8 +112,6 @@ sfBool sfPacket_EndOfPacket(const sfPacket* packet) } -//////////////////////////////////////////////////////////// -/// Check if a packet is in a valid reading state //////////////////////////////////////////////////////////// sfBool sfPacket_CanRead(const sfPacket* packet) { @@ -144,11 +120,6 @@ sfBool sfPacket_CanRead(const sfPacket* packet) } -//////////////////////////////////////////////////////////// -/// Functions to extract data from a packet -/// -/// \param Packet : Packet to read -/// //////////////////////////////////////////////////////////// sfBool sfPacket_ReadBool(sfPacket* packet) {return PacketRead(packet);} sfInt8 sfPacket_ReadInt8(sfPacket* packet) {return PacketRead(packet);} @@ -177,11 +148,6 @@ void sfPacket_ReadWideString(sfPacket* packet, wchar_t* string) } -//////////////////////////////////////////////////////////// -/// Functions to insert data into a packet -/// -/// \param Packet : Packet to write -/// //////////////////////////////////////////////////////////// void sfPacket_WriteBool(sfPacket* packet, sfBool value) {PacketWrite(packet, static_cast(value));} void sfPacket_WriteInt8(sfPacket* packet, sfInt8 value) {PacketWrite(packet, value);} diff --git a/src/SFML/Network/SocketSelector.cpp b/src/SFML/Network/SocketSelector.cpp index 8132127..2f8137b 100644 --- a/src/SFML/Network/SocketSelector.cpp +++ b/src/SFML/Network/SocketSelector.cpp @@ -33,8 +33,6 @@ #include -//////////////////////////////////////////////////////////// -/// Create a new selector //////////////////////////////////////////////////////////// sfSocketSelector* sfSocketSelector_Create(void) { @@ -42,8 +40,6 @@ sfSocketSelector* sfSocketSelector_Create(void) } -//////////////////////////////////////////////////////////// -/// Copy an existing selector //////////////////////////////////////////////////////////// sfSocketSelector* sfSocketSelector_Copy(sfSocketSelector* selector) { @@ -53,8 +49,6 @@ sfSocketSelector* sfSocketSelector_Copy(sfSocketSelector* selector) } -//////////////////////////////////////////////////////////// -/// Destroy an existing selector //////////////////////////////////////////////////////////// void sfSocketSelector_Destroy(sfSocketSelector* selector) { @@ -62,8 +56,6 @@ void sfSocketSelector_Destroy(sfSocketSelector* selector) } -//////////////////////////////////////////////////////////// -/// Add a socket to watch to a selector //////////////////////////////////////////////////////////// void sfSocketSelector_AddTcpListener(sfSocketSelector* selector, sfTcpListener* socket) { @@ -82,8 +74,6 @@ void sfSocketSelector_AddUdpSocket(sfSocketSelector* selector, sfUdpSocket* sock } -//////////////////////////////////////////////////////////// -/// Remove a socket from a selector //////////////////////////////////////////////////////////// void sfSocketSelector_RemoveTcpListener(sfSocketSelector* selector, sfTcpListener* socket) { @@ -102,8 +92,6 @@ void sfSocketSelector_RemoveUdpSocket(sfSocketSelector* selector, sfUdpSocket* s } -//////////////////////////////////////////////////////////// -/// Remove all sockets from a selector //////////////////////////////////////////////////////////// void sfSocketSelector_Clear(sfSocketSelector* selector) { @@ -111,10 +99,6 @@ void sfSocketSelector_Clear(sfSocketSelector* selector) } -//////////////////////////////////////////////////////////// -/// Wait and collect sockets which are ready for reading. -/// This functions will return either when at least one socket -/// is ready, or when the given timeout is over //////////////////////////////////////////////////////////// sfBool sfSocketSelector_Wait(sfSocketSelector* selector, sfUint32 timeout) { @@ -122,8 +106,6 @@ sfBool sfSocketSelector_Wait(sfSocketSelector* selector, sfUint32 timeout) } -//////////////////////////////////////////////////////////// -/// Test a socket to know if it is ready to receive data //////////////////////////////////////////////////////////// sfBool sfSocketSelector_IsTcpListenerReady(const sfSocketSelector* selector, sfTcpListener* socket) { diff --git a/src/SFML/Network/TcpListener.cpp b/src/SFML/Network/TcpListener.cpp index a0f4ffb..5579b03 100644 --- a/src/SFML/Network/TcpListener.cpp +++ b/src/SFML/Network/TcpListener.cpp @@ -31,8 +31,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new TCP socket //////////////////////////////////////////////////////////// sfTcpListener* sfTcpListener_Create(void) { @@ -41,54 +39,48 @@ sfTcpListener* sfTcpListener_Create(void) //////////////////////////////////////////////////////////// -/// Destroy an existing TCP socket -//////////////////////////////////////////////////////////// -void sfTcpListener_Destroy(sfTcpListener* socket) +void sfTcpListener_Destroy(sfTcpListener* listener) { - delete socket; + delete listener; } //////////////////////////////////////////////////////////// -/// Change the blocking state of a TCP socket. -/// The default behaviour of a socket is blocking -//////////////////////////////////////////////////////////// -void sfTcpListener_SetBlocking(sfTcpListener* socket, sfBool blocking) +void sfTcpListener_SetBlocking(sfTcpListener* listener, sfBool blocking) { - CSFML_CALL(socket, SetBlocking(blocking == sfTrue)); + CSFML_CALL(listener, SetBlocking(blocking == sfTrue)); } //////////////////////////////////////////////////////////// -/// Get the blocking state of the socket -//////////////////////////////////////////////////////////// -sfBool sfTcpListener_IsBlocking(const sfTcpListener* socket) +sfBool sfTcpListener_IsBlocking(const sfTcpListener* listener) { - CSFML_CALL_RETURN(socket, IsBlocking(), sfFalse); + CSFML_CALL_RETURN(listener, IsBlocking(), sfFalse); } //////////////////////////////////////////////////////////// -/// Listen to a specified port for incoming data or connections -//////////////////////////////////////////////////////////// -sfSocketStatus sfTcpListener_Listen(sfTcpListener* socket, unsigned short port) +unsigned short sfTcpListener_GetLocalPort(const sfTcpListener* listener) { - CSFML_CHECK_RETURN(socket, sfSocketError); - - return static_cast(socket->This.Listen(port)); + CSFML_CALL_RETURN(listener, GetLocalPort(), 0); } //////////////////////////////////////////////////////////// -/// Wait for a connection (must be listening to a port). -/// This function is blocking, ie. it won't return before -/// a connection has been accepted -//////////////////////////////////////////////////////////// -sfSocketStatus sfTcpListener_Accept(sfTcpListener* socket, sfTcpSocket** connected) +sfSocketStatus sfTcpListener_Listen(sfTcpListener* listener, unsigned short port) { - CSFML_CHECK_RETURN(socket, sfSocketError); + CSFML_CHECK_RETURN(listener, sfSocketError); + + return static_cast(listener->This.Listen(port)); +} + + +//////////////////////////////////////////////////////////// +sfSocketStatus sfTcpListener_Accept(sfTcpListener* listener, sfTcpSocket** connected) +{ + CSFML_CHECK_RETURN(listener, sfSocketError); CSFML_CHECK_RETURN(connected, sfSocketError); *connected = new sfTcpSocket; - return static_cast(socket->This.Accept((*connected)->This)); + return static_cast(listener->This.Accept((*connected)->This)); } diff --git a/src/SFML/Network/TcpSocket.cpp b/src/SFML/Network/TcpSocket.cpp index ad4adde..3fcb7fc 100644 --- a/src/SFML/Network/TcpSocket.cpp +++ b/src/SFML/Network/TcpSocket.cpp @@ -33,8 +33,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new TCP socket //////////////////////////////////////////////////////////// sfTcpSocket* sfTcpSocket_Create(void) { @@ -42,8 +40,6 @@ sfTcpSocket* sfTcpSocket_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing TCP socket //////////////////////////////////////////////////////////// void sfTcpSocket_Destroy(sfTcpSocket* socket) { @@ -51,9 +47,6 @@ void sfTcpSocket_Destroy(sfTcpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Change the blocking state of a TCP socket. -/// The default behaviour of a socket is blocking //////////////////////////////////////////////////////////// void sfTcpSocket_SetBlocking(sfTcpSocket* socket, sfBool blocking) { @@ -61,8 +54,6 @@ void sfTcpSocket_SetBlocking(sfTcpSocket* socket, sfBool blocking) } -//////////////////////////////////////////////////////////// -/// Get the blocking state of the socket //////////////////////////////////////////////////////////// sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket) { @@ -70,8 +61,6 @@ sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Get the port to which a socket is bound locally //////////////////////////////////////////////////////////// unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket) { @@ -79,8 +68,6 @@ unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Get the address of the connected peer of a socket //////////////////////////////////////////////////////////// sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket) { @@ -94,8 +81,6 @@ sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Get the port of the connected peer to which a socket is connected //////////////////////////////////////////////////////////// unsigned short sfTcpSocket_GetRemotePort(const sfTcpSocket* socket) { @@ -103,8 +88,6 @@ unsigned short sfTcpSocket_GetRemotePort(const sfTcpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Connect a TCP socket to another computer on a specified port //////////////////////////////////////////////////////////// sfSocketStatus sfTcpSocket_Connect(sfTcpSocket* socket, sfIpAddress host, unsigned short port, sfUint32 timeout) { @@ -116,8 +99,6 @@ sfSocketStatus sfTcpSocket_Connect(sfTcpSocket* socket, sfIpAddress host, unsign } -//////////////////////////////////////////////////////////// -/// Disconnect a connect from its remote peer //////////////////////////////////////////////////////////// void sfTcpSocket_Disconnect(sfTcpSocket* socket) { @@ -125,8 +106,6 @@ void sfTcpSocket_Disconnect(sfTcpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Send an array of bytes to the host (must be connected first) //////////////////////////////////////////////////////////// sfSocketStatus sfTcpSocket_Send(sfTcpSocket* socket, const char* data, size_t size) { @@ -136,8 +115,6 @@ sfSocketStatus sfTcpSocket_Send(sfTcpSocket* socket, const char* data, size_t si } -//////////////////////////////////////////////////////////// -/// Receive an array of bytes from the host (must be connected first) //////////////////////////////////////////////////////////// sfSocketStatus sfTcpSocket_Receive(sfTcpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived) { @@ -155,8 +132,6 @@ sfSocketStatus sfTcpSocket_Receive(sfTcpSocket* socket, char* data, size_t maxSi } -//////////////////////////////////////////////////////////// -/// Send a packet of data to the host (must be connected first) //////////////////////////////////////////////////////////// sfSocketStatus sfTcpSocket_SendPacket(sfTcpSocket* socket, sfPacket* packet) { @@ -167,8 +142,6 @@ sfSocketStatus sfTcpSocket_SendPacket(sfTcpSocket* socket, sfPacket* packet) } -//////////////////////////////////////////////////////////// -/// Receive a packet from the host (must be connected first) //////////////////////////////////////////////////////////// sfSocketStatus sfTcpSocket_ReceivePacket(sfTcpSocket* socket, sfPacket* packet) { diff --git a/src/SFML/Network/UdpSocket.cpp b/src/SFML/Network/UdpSocket.cpp index 1b14f7e..a5ceebb 100644 --- a/src/SFML/Network/UdpSocket.cpp +++ b/src/SFML/Network/UdpSocket.cpp @@ -33,8 +33,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new UDP socket //////////////////////////////////////////////////////////// sfUdpSocket* sfUdpSocket_Create(void) { @@ -42,8 +40,6 @@ sfUdpSocket* sfUdpSocket_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing UDP socket //////////////////////////////////////////////////////////// void sfUdpSocket_Destroy(sfUdpSocket* socket) { @@ -51,17 +47,12 @@ void sfUdpSocket_Destroy(sfUdpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Change the blocking state of a UDP socket. -/// The default behaviour of a socket is blocking //////////////////////////////////////////////////////////// void sfUdpSocket_SetBlocking(sfUdpSocket* socket, sfBool blocking) { CSFML_CALL(socket, SetBlocking(blocking == sfTrue)); } -//////////////////////////////////////////////////////////// -/// Get the blocking state of the socket //////////////////////////////////////////////////////////// sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket) { @@ -69,8 +60,6 @@ sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Get the port to which the socket is bound locally //////////////////////////////////////////////////////////// unsigned short sfUdpSocket_GetLocalPort(const sfUdpSocket* socket) { @@ -78,8 +67,6 @@ unsigned short sfUdpSocket_GetLocalPort(const sfUdpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Bind a socket to a specific port //////////////////////////////////////////////////////////// sfSocketStatus sfUdpSocket_Bind(sfUdpSocket* socket, unsigned short port) { @@ -89,8 +76,6 @@ sfSocketStatus sfUdpSocket_Bind(sfUdpSocket* socket, unsigned short port) } -//////////////////////////////////////////////////////////// -/// Unbind a socket from its previous port, if any //////////////////////////////////////////////////////////// void sfUdpSocket_Unbind(sfUdpSocket* socket) { @@ -98,8 +83,6 @@ void sfUdpSocket_Unbind(sfUdpSocket* socket) } -//////////////////////////////////////////////////////////// -/// Send an array of bytes //////////////////////////////////////////////////////////// sfSocketStatus sfUdpSocket_Send(sfUdpSocket* socket, const char* data, size_t size, sfIpAddress address, unsigned short port) { @@ -112,10 +95,6 @@ sfSocketStatus sfUdpSocket_Send(sfUdpSocket* socket, const char* data, size_t si } -//////////////////////////////////////////////////////////// -/// Receive an array of bytes. -/// This function is blocking, ie. it won't return before some -/// bytes have been received //////////////////////////////////////////////////////////// sfSocketStatus sfUdpSocket_Receive(sfUdpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived, sfIpAddress* address, unsigned short* port) { @@ -143,8 +122,6 @@ sfSocketStatus sfUdpSocket_Receive(sfUdpSocket* socket, char* data, size_t maxSi } -//////////////////////////////////////////////////////////// -/// Send a packet of data //////////////////////////////////////////////////////////// sfSocketStatus sfUdpSocket_SendPacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress address, unsigned short port) { @@ -158,10 +135,6 @@ sfSocketStatus sfUdpSocket_SendPacket(sfUdpSocket* socket, sfPacket* packet, sfI } -//////////////////////////////////////////////////////////// -/// Receive a packet. -/// This function is blocking, ie. it won't return before a -/// packet is received //////////////////////////////////////////////////////////// sfSocketStatus sfUdpSocket_ReceivePacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress* address, unsigned short* port) { @@ -182,3 +155,10 @@ sfSocketStatus sfUdpSocket_ReceivePacket(sfUdpSocket* socket, sfPacket* packet, return sfSocketDone; } + + +//////////////////////////////////////////////////////////// +unsigned int sfUdpSocket_MaxDatagramSize() +{ + return sf::UdpSocket::MaxDatagramSize; +} diff --git a/src/SFML/System/Clock.cpp b/src/SFML/System/Clock.cpp index 9761e00..ce56ef6 100644 --- a/src/SFML/System/Clock.cpp +++ b/src/SFML/System/Clock.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Create a new clock and start it //////////////////////////////////////////////////////////// sfClock* sfClock_Create(void) { @@ -39,8 +37,6 @@ sfClock* sfClock_Create(void) } -//////////////////////////////////////////////////////////// -/// Copy an existing clock //////////////////////////////////////////////////////////// sfClock* sfClock_Copy(sfClock* clock) { @@ -50,8 +46,6 @@ sfClock* sfClock_Copy(sfClock* clock) } -//////////////////////////////////////////////////////////// -/// Destroy an existing clock //////////////////////////////////////////////////////////// void sfClock_Destroy(sfClock* clock) { @@ -59,8 +53,6 @@ void sfClock_Destroy(sfClock* clock) } -//////////////////////////////////////////////////////////// -/// Get the time elapsed for a clock //////////////////////////////////////////////////////////// sfUint32 sfClock_GetTime(const sfClock* clock) { @@ -68,8 +60,6 @@ sfUint32 sfClock_GetTime(const sfClock* clock) } -//////////////////////////////////////////////////////////// -/// Restart a clock //////////////////////////////////////////////////////////// void sfClock_Reset(sfClock* clock) { diff --git a/src/SFML/System/Mutex.cpp b/src/SFML/System/Mutex.cpp index 1bfbf1b..7783e84 100644 --- a/src/SFML/System/Mutex.cpp +++ b/src/SFML/System/Mutex.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Create a new mutex //////////////////////////////////////////////////////////// sfMutex* sfMutex_Create(void) { @@ -39,8 +37,6 @@ sfMutex* sfMutex_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing mutex //////////////////////////////////////////////////////////// void sfMutex_Destroy(sfMutex* mutex) { @@ -48,8 +44,6 @@ void sfMutex_Destroy(sfMutex* mutex) } -//////////////////////////////////////////////////////////// -/// Lock a mutex //////////////////////////////////////////////////////////// void sfMutex_Lock(sfMutex* mutex) { @@ -57,8 +51,6 @@ void sfMutex_Lock(sfMutex* mutex) } -//////////////////////////////////////////////////////////// -/// Unlock a mutex //////////////////////////////////////////////////////////// void sfMutex_Unlock(sfMutex* mutex) { diff --git a/src/SFML/System/Sleep.cpp b/src/SFML/System/Sleep.cpp index 79cfcc7..24dd4f7 100644 --- a/src/SFML/System/Sleep.cpp +++ b/src/SFML/System/Sleep.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Make the current thread sleep for a given duration //////////////////////////////////////////////////////////// void sfSleep(sfUint32 Duration) { diff --git a/src/SFML/System/Thread.cpp b/src/SFML/System/Thread.cpp index 678bea5..5e18ee5 100644 --- a/src/SFML/System/Thread.cpp +++ b/src/SFML/System/Thread.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new thread from a function pointer //////////////////////////////////////////////////////////// sfThread* sfThread_Create(void (*function)(void*), void* userData) { @@ -39,8 +37,6 @@ sfThread* sfThread_Create(void (*function)(void*), void* userData) } -//////////////////////////////////////////////////////////// -/// Destroy an existing thread //////////////////////////////////////////////////////////// void sfThread_Destroy(sfThread* thread) { @@ -48,8 +44,6 @@ void sfThread_Destroy(sfThread* thread) } -//////////////////////////////////////////////////////////// -/// Run a thread //////////////////////////////////////////////////////////// void sfThread_Launch(sfThread* thread) { @@ -57,8 +51,6 @@ void sfThread_Launch(sfThread* thread) } -//////////////////////////////////////////////////////////// -/// Wait until a thread finishes //////////////////////////////////////////////////////////// void sfThread_Wait(sfThread* thread) { @@ -66,11 +58,6 @@ void sfThread_Wait(sfThread* thread) } -//////////////////////////////////////////////////////////// -/// Terminate a thread -/// Terminating a thread with this function is not safe, -/// you should rather try to make the thread function -/// terminate by itself //////////////////////////////////////////////////////////// void sfThread_Terminate(sfThread* thread) { diff --git a/src/SFML/Window/Context.cpp b/src/SFML/Window/Context.cpp index 27e5841..694f570 100644 --- a/src/SFML/Window/Context.cpp +++ b/src/SFML/Window/Context.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new context //////////////////////////////////////////////////////////// sfContext* sfContext_Create(void) { @@ -39,8 +37,6 @@ sfContext* sfContext_Create(void) } -//////////////////////////////////////////////////////////// -/// Destroy an existing context //////////////////////////////////////////////////////////// void sfContext_Destroy(sfContext* context) { @@ -48,8 +44,6 @@ void sfContext_Destroy(sfContext* context) } -//////////////////////////////////////////////////////////// -/// Activate or deactivate a context //////////////////////////////////////////////////////////// void sfContext_SetActive(sfContext* context, sfBool active) { diff --git a/src/SFML/Window/Joystick.cpp b/src/SFML/Window/Joystick.cpp index cc60c4c..f774e2d 100644 --- a/src/SFML/Window/Joystick.cpp +++ b/src/SFML/Window/Joystick.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Check if a joystick is connected //////////////////////////////////////////////////////////// sfBool sfJoystick_IsConnected(unsigned int joystick) { @@ -39,8 +37,6 @@ sfBool sfJoystick_IsConnected(unsigned int joystick) } -//////////////////////////////////////////////////////////// -/// Return the number of buttons supported by a joystick //////////////////////////////////////////////////////////// unsigned int sfJoystick_GetButtonCount(unsigned int joystick) { @@ -48,8 +44,6 @@ unsigned int sfJoystick_GetButtonCount(unsigned int joystick) } -//////////////////////////////////////////////////////////// -/// Check if a joystick supports a given axis //////////////////////////////////////////////////////////// sfBool sfJoystick_HasAxis(unsigned int joystick, sfJoystickAxis axis) { @@ -57,8 +51,6 @@ sfBool sfJoystick_HasAxis(unsigned int joystick, sfJoystickAxis axis) } -//////////////////////////////////////////////////////////// -/// Check if a joystick button is pressed //////////////////////////////////////////////////////////// sfBool sfJoystick_IsButtonPressed(unsigned int joystick, unsigned int button) { @@ -66,8 +58,6 @@ sfBool sfJoystick_IsButtonPressed(unsigned int joystick, unsigned int button) } -//////////////////////////////////////////////////////////// -/// Get the current position of a joystick axis //////////////////////////////////////////////////////////// float sfJoystick_GetAxisPosition(unsigned int joystick, sfJoystickAxis axis) { @@ -75,8 +65,6 @@ float sfJoystick_GetAxisPosition(unsigned int joystick, sfJoystickAxis axis) } -//////////////////////////////////////////////////////////// -/// Update the states of all joysticks //////////////////////////////////////////////////////////// void sfJoystick_Update(void) { diff --git a/src/SFML/Window/Keyboard.cpp b/src/SFML/Window/Keyboard.cpp index 190c118..fb11a54 100644 --- a/src/SFML/Window/Keyboard.cpp +++ b/src/SFML/Window/Keyboard.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Check if a key is pressed //////////////////////////////////////////////////////////// sfBool sfKeyboard_IsKeyPressed(sfKeyCode key) { diff --git a/src/SFML/Window/Mouse.cpp b/src/SFML/Window/Mouse.cpp index c972796..4c51e6f 100644 --- a/src/SFML/Window/Mouse.cpp +++ b/src/SFML/Window/Mouse.cpp @@ -31,8 +31,6 @@ #include -//////////////////////////////////////////////////////////// -/// Check if a mouse button is pressed //////////////////////////////////////////////////////////// sfBool sfMouse_IsButtonPressed(sfMouseButton button) { @@ -40,8 +38,6 @@ sfBool sfMouse_IsButtonPressed(sfMouseButton button) } -//////////////////////////////////////////////////////////// -/// Get the current position of the mouse //////////////////////////////////////////////////////////// void sfMouse_GetPosition(int* x, int* y, const sfWindow* relativeTo) { @@ -58,8 +54,6 @@ void sfMouse_GetPosition(int* x, int* y, const sfWindow* relativeTo) } -//////////////////////////////////////////////////////////// -/// Get the current position of the mouse //////////////////////////////////////////////////////////// void sfMouse_SetPosition(int x, int y, const sfWindow* relativeTo) { diff --git a/src/SFML/Window/VideoMode.cpp b/src/SFML/Window/VideoMode.cpp index a213a94..894c415 100644 --- a/src/SFML/Window/VideoMode.cpp +++ b/src/SFML/Window/VideoMode.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Get the current desktop video mode //////////////////////////////////////////////////////////// sfVideoMode sfVideoMode_GetDesktopMode(void) { @@ -46,10 +44,7 @@ sfVideoMode sfVideoMode_GetDesktopMode(void) //////////////////////////////////////////////////////////// -/// Get all the supported video modes for fullscreen mode. -/// Modes are sorted from best to worst. -//////////////////////////////////////////////////////////// -const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* Count) +const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* count) { static std::vector modes; @@ -67,15 +62,13 @@ const sfVideoMode* sfVideoMode_GetFullscreenModes(size_t* Count) } } - if (Count) - *Count = modes.size(); + if (count) + *count = modes.size(); return !modes.empty() ? &modes[0] : NULL; } -//////////////////////////////////////////////////////////// -/// Tell whether or not a video mode is supported //////////////////////////////////////////////////////////// sfBool sfVideoMode_IsValid(sfVideoMode mode) { diff --git a/src/SFML/Window/Window.cpp b/src/SFML/Window/Window.cpp index 0a1206e..ec028d9 100644 --- a/src/SFML/Window/Window.cpp +++ b/src/SFML/Window/Window.cpp @@ -31,8 +31,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a new window //////////////////////////////////////////////////////////// sfWindow* sfWindow_Create(sfVideoMode mode, const char* title, unsigned long style, const sfContextSettings* settings) { @@ -58,8 +56,6 @@ sfWindow* sfWindow_Create(sfVideoMode mode, const char* title, unsigned long sty } -//////////////////////////////////////////////////////////// -/// Construct a window from an existing control //////////////////////////////////////////////////////////// sfWindow* sfWindow_CreateFromHandle(sfWindowHandle handle, const sfContextSettings* settings) { @@ -82,16 +78,12 @@ sfWindow* sfWindow_CreateFromHandle(sfWindowHandle handle, const sfContextSettin } -//////////////////////////////////////////////////////////// -/// Destroy an existing window //////////////////////////////////////////////////////////// void sfWindow_Destroy(sfWindow* window) { delete window; } -//////////////////////////////////////////////////////////// -/// Close a window (but doesn't destroy the internal data) //////////////////////////////////////////////////////////// void sfWindow_Close(sfWindow* window) { @@ -99,8 +91,6 @@ void sfWindow_Close(sfWindow* window) } -//////////////////////////////////////////////////////////// -/// Tell whether or not a window is opened //////////////////////////////////////////////////////////// sfBool sfWindow_IsOpened(const sfWindow* window) { @@ -108,8 +98,6 @@ sfBool sfWindow_IsOpened(const sfWindow* window) } -//////////////////////////////////////////////////////////// -/// Get the width of the rendering region of a window //////////////////////////////////////////////////////////// unsigned int sfWindow_GetWidth(const sfWindow* window) { @@ -117,8 +105,6 @@ unsigned int sfWindow_GetWidth(const sfWindow* window) } -//////////////////////////////////////////////////////////// -/// Get the height of the rendering region of a window //////////////////////////////////////////////////////////// unsigned int sfWindow_GetHeight(const sfWindow* window) { @@ -126,8 +112,6 @@ unsigned int sfWindow_GetHeight(const sfWindow* window) } -//////////////////////////////////////////////////////////// -/// Get the creation settings of a window //////////////////////////////////////////////////////////// sfContextSettings sfWindow_GetSettings(const sfWindow* window) { @@ -145,8 +129,6 @@ sfContextSettings sfWindow_GetSettings(const sfWindow* window) } -//////////////////////////////////////////////////////////// -/// Get the event on top of events stack of a window, if any, and pop it //////////////////////////////////////////////////////////// sfBool sfWindow_PollEvent(sfWindow* window, sfEvent* event) { @@ -168,8 +150,6 @@ sfBool sfWindow_PollEvent(sfWindow* window, sfEvent* event) } -//////////////////////////////////////////////////////////// -/// Wait for an event and return it //////////////////////////////////////////////////////////// sfBool sfWindow_WaitEvent(sfWindow* window, sfEvent* event) { @@ -191,8 +171,6 @@ sfBool sfWindow_WaitEvent(sfWindow* window, sfEvent* event) } -//////////////////////////////////////////////////////////// -/// Enable / disable vertical synchronization on a window //////////////////////////////////////////////////////////// void sfWindow_EnableVerticalSync(sfWindow* window, sfBool enabled) { @@ -200,8 +178,6 @@ void sfWindow_EnableVerticalSync(sfWindow* window, sfBool enabled) } -//////////////////////////////////////////////////////////// -/// Show or hide the mouse cursor on a window //////////////////////////////////////////////////////////// void sfWindow_ShowMouseCursor(sfWindow* window, sfBool show) { @@ -209,9 +185,6 @@ void sfWindow_ShowMouseCursor(sfWindow* window, sfBool show) } -//////////////////////////////////////////////////////////// -/// Change the position of a window on screen. -/// Only works for top-level windows //////////////////////////////////////////////////////////// void sfWindow_SetPosition(sfWindow* window, int left, int top) { @@ -219,8 +192,6 @@ void sfWindow_SetPosition(sfWindow* window, int left, int top) } -//////////////////////////////////////////////////////////// -/// Change the size of the rendering region of a window //////////////////////////////////////////////////////////// void sfWindow_SetSize(sfWindow* window, unsigned int width, unsigned int height) { @@ -228,8 +199,6 @@ void sfWindow_SetSize(sfWindow* window, unsigned int width, unsigned int height) } -//////////////////////////////////////////////////////////// -/// Change the title of a window //////////////////////////////////////////////////////////// void sfWindow_SetTitle(sfWindow* window, const char* title) { @@ -237,8 +206,6 @@ void sfWindow_SetTitle(sfWindow* window, const char* title) } -//////////////////////////////////////////////////////////// -/// Show or hide a window //////////////////////////////////////////////////////////// void sfWindow_Show(sfWindow* window, sfBool show) { @@ -246,9 +213,6 @@ void sfWindow_Show(sfWindow* window, sfBool show) } -//////////////////////////////////////////////////////////// -/// Enable or disable automatic key-repeat for keydown events. -/// Automatic key-repeat is enabled by default //////////////////////////////////////////////////////////// void sfWindow_EnableKeyRepeat(sfWindow* window, sfBool enabled) { @@ -256,8 +220,6 @@ void sfWindow_EnableKeyRepeat(sfWindow* window, sfBool enabled) } -//////////////////////////////////////////////////////////// -/// Change the window's icon //////////////////////////////////////////////////////////// void sfWindow_SetIcon(sfWindow* window, unsigned int width, unsigned int height, const sfUint8* pixels) { @@ -265,8 +227,6 @@ void sfWindow_SetIcon(sfWindow* window, unsigned int width, unsigned int height, } -//////////////////////////////////////////////////////////// -/// Activate or deactivate a window as the current target for rendering //////////////////////////////////////////////////////////// sfBool sfWindow_SetActive(sfWindow* window, sfBool active) { @@ -274,8 +234,6 @@ sfBool sfWindow_SetActive(sfWindow* window, sfBool active) } -//////////////////////////////////////////////////////////// -/// Display a window on screen //////////////////////////////////////////////////////////// void sfWindow_Display(sfWindow* window) { @@ -283,8 +241,6 @@ void sfWindow_Display(sfWindow* window) } -//////////////////////////////////////////////////////////// -/// Limit the framerate to a maximum fixed frequency for a window //////////////////////////////////////////////////////////// void sfWindow_SetFramerateLimit(sfWindow* window, unsigned int limit) { @@ -292,8 +248,6 @@ void sfWindow_SetFramerateLimit(sfWindow* window, unsigned int limit) } -//////////////////////////////////////////////////////////// -/// Get time elapsed since last frame of a window //////////////////////////////////////////////////////////// sfUint32 sfWindow_GetFrameTime(const sfWindow* window) { @@ -301,9 +255,6 @@ sfUint32 sfWindow_GetFrameTime(const sfWindow* window) } -//////////////////////////////////////////////////////////// -/// Change the joystick threshold, ie. the value below which -/// no move event will be generated //////////////////////////////////////////////////////////// void sfWindow_SetJoystickThreshold(sfWindow* window, float threshold) { @@ -311,8 +262,6 @@ void sfWindow_SetJoystickThreshold(sfWindow* window, float threshold) } -//////////////////////////////////////////////////////////// -/// Retrieve the Os-specific handle of a window //////////////////////////////////////////////////////////// sfWindowHandle sfWindow_GetSystemHandle(const sfWindow* window) {