Finished to write the API documentation of the graphics classes

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1524 4e206d99-4929-0410-ac5d-dfc041789085

include/SFML/Graphics/Shader.hpp

@@ -416,6 +416,20 @@ private :
 /// with sf::Shape is even more limited, as shapes don't use
 /// any texture.
 ///
+/// Shaders can also be used to apply global post-effects to the
+/// current contents of the target (like the old sf::PostFx class
+/// in SFML 1). This can be done in two different ways:
+/// \li draw everything to a sf::RenderImage, then draw it to
+///     the main target using the shader
+/// \li draw everything directly to the main target, then use
+///     sf::Image::CopyScreen to copy its contents to an image and
+///     draw it to the main target using the shader
+///
+/// The first technique is more optimized because it doesn't involve
+/// retrieving the target's pixels to system memory, but the
+/// second one doesn't impact the rendering process and can be
+/// easily inserted anywhere.
+///
 /// Like sf::Image that can be used as a raw OpenGL texture,
 /// sf::Shader can also be used directly as a raw fragment
 /// shader for custom OpenGL geometry.

include/SFML/Graphics/Shape.hpp

@@ -429,3 +429,80 @@ private :
 
 
 #endif // SFML_SHAPE_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Shape
+///
+/// sf::Shape is a drawable class that allows to define and
+/// display a custom convex shape on a render target.
+///
+/// It is important to keep in mind that shapes must always be
+/// convex, otherwise they may not be drawn correctly. Moreover,
+/// the points must be added in the right order; using a random
+/// order would also result in an incorrect shape.
+///
+/// A shape is made of points that have their own individual
+/// attributes:
+/// \li position (relative to the origin of the shape)
+/// \li color
+/// \li outline color
+///
+/// Shapes have an outline that can be enabled or not. You can
+/// control the thickness of the outline with the SetOutlineWidth
+/// function.
+///
+/// They also inherits all the functions from sf::Drawable:
+/// position, rotation, scale, origin, global color and blend
+/// mode.
+///
+/// Some static functions are provided to directly create common
+/// shapes such as lines, rectangles and circles:
+/// \code
+/// sf::Shape line = sf::Shape::Line(start, end, thickness, color);
+/// sf::Shape rectangle = sf::Shape::Rectangle(rect, thickness);
+/// sf::Shape circle = sf::Shape::Circle(center, radius, color);
+/// \endcode
+///
+/// A common mistake is to mix the individual points
+/// positions / colors and the global position / color of the shape.
+/// They are completely separate attributes that are combined
+/// when the shape is drawn (positions are added, colors are multiplied).
+/// \code
+/// sf::Shape line = sf::Shape::Line(sf::Vector2f(100, 100), sf::Vector2f(200, 200), 10, sf::Color::Red);
+///
+/// // --> line.GetPosition() is (0, 0), *not* (100, 100)
+/// // --> line.GetColor() is white, *not* red
+/// \endcode
+/// So if you plan to change the position / color of your shape
+/// after it is created, you'd better create the points around
+/// the origin and with white color, and use only the global
+/// position / color (SetPosition, SetColor).
+///
+/// Usage example:
+/// \code
+/// // Create a shape
+/// sf::Shape shape;
+///
+/// // Define its points
+/// shape.AddPoint(10, 10, sf::Color::White, sf::Color::Red);
+/// shape.AddPoint(50, 10, sf::Color::White, sf::Color::Green);
+/// shape.AddPoint(10, 50, sf::Color::White, sf::Color::Blue);
+///
+/// // Enable outline only
+/// shape.EnableFill(false);
+/// shape.EnableOutline(true);
+/// shape.SetOutlineWidth(10);
+///
+/// // Display it
+/// window.Draw(shape); // window is a sf::RenderWindow
+///
+/// // Display static shapes
+/// window.Draw(sf::Shape::Line(0, 0, 10, 20, sf::Color::Red));
+/// window.Draw(sf::Shape::Rectangle(100, 1000, 50, 20, sf::Color::Green));
+/// window.Draw(sf::Shape::Circle(500, 500, 20, sf::Color::Blue, 5, sf::Color::Black));
+/// \endcode
+///
+/// \see sf::Image
+///
+////////////////////////////////////////////////////////////

include/SFML/Graphics/Sprite.hpp

@@ -244,7 +244,30 @@ private :
 ////////////////////////////////////////////////////////////
 /// \class sf::Sprite
 ///
-/// ...
+/// sf::Sprite is a drawable class that allows to easily display
+/// an image (or a part of it) on a render target.
+///
+/// It inherits all the functions from sf::Drawable:
+/// position, rotation, scale, origin, global color and blend
+/// mode. It also adds sprite-specific properties such as the
+/// image to use, the part of it to display, and some convenience
+/// functions to flip or resize the sprite.
+///
+/// sf::Sprite works in combination with the sf::Image class, which
+/// loads and provides the pixel data of a given image.
+///
+/// The separation of sf::Sprite and sf::Image allows more flexibility
+/// and better performances: indeed a sf::Image is a heavy resource,
+/// and any operation on it is slow (often too slow for real-time
+/// applications). On the other side, a sf::Sprite is a lightweight
+/// object which can use the pixel data of a sf::Image and draw
+/// it with its own transformation / color / blending attributes.
+///
+/// It is important to note that the sf::Sprite instance doesn't
+/// copy the image that it uses, it only keeps a reference to it.
+/// Thus, a sf::Image must not be destructed while it is
+/// used by a sf::Sprite (i.e. never write a function that
+/// uses a local sf::Image instance for creating a sprite).
 ///
 /// Usage example:
 /// \code

include/SFML/Network/TcpSocket.hpp

@@ -241,7 +241,6 @@ public :
 /// std::size_t received = 0;
 /// socket.Receive(buffer, sizeof(buffer), received);
 /// std::cout << "The server said: " << buffer << std::endl;
-/// }
 ///
 /// // ----- The server -----
 ///
@@ -263,7 +262,6 @@ public :
 /// // Send an answer
 /// std::string message = "Welcome, client";
 /// socket.Send(message.c_str(), message.size() + 1);
-/// }
 /// \endcode
 ///
 /// \see sf::Socket, sf::UdpSocket, sf::Packet

include/SFML/Network/UdpSocket.hpp

@@ -238,7 +238,6 @@ public :
 /// unsigned short port;
 /// socket.Receive(buffer, sizeof(buffer), received, sender, port);
 /// std::cout << sender.ToString() << " said: " << buffer << std::endl;
-/// }
 ///
 /// // ----- The server -----
 ///
@@ -257,7 +256,6 @@ public :
 /// // Send an answer
 /// std::string message = "Welcome " + sender.ToString();
 /// socket.Send(message.c_str(), message.size() + 1, sender, port);
-/// }
 /// \endcode
 ///
 /// \see sf::Socket, sf::TcpSocket, sf::Packet

include/SFML/Window/Window.hpp

@@ -423,7 +423,7 @@ public :
     ////////////////////////////////////////////////////////////
     /// \brief Change the joystick threshold
     ///
-    /// Ths joystick threshold is the value below which
+    /// The joystick threshold is the value below which
     /// no JoyMoved event will be generated.
     ///
     /// The threshold value is 0.1 by default.