From 1ee996505902d168400ddba2f804343300e14da5 Mon Sep 17 00:00:00 2001 From: LaurentGom Date: Fri, 11 Jun 2010 21:38:56 +0000 Subject: [PATCH] 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 | 14 ++++++ include/SFML/Graphics/Shape.hpp | 77 ++++++++++++++++++++++++++++++ include/SFML/Graphics/Sprite.hpp | 25 +++++++++- include/SFML/Network/TcpSocket.hpp | 2 - include/SFML/Network/UdpSocket.hpp | 2 - include/SFML/Window/Window.hpp | 2 +- 6 files changed, 116 insertions(+), 6 deletions(-) diff --git a/include/SFML/Graphics/Shader.hpp b/include/SFML/Graphics/Shader.hpp index fe0396455..6cd3c8418 100644 --- a/include/SFML/Graphics/Shader.hpp +++ b/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. diff --git a/include/SFML/Graphics/Shape.hpp b/include/SFML/Graphics/Shape.hpp index a06e8fc47..aa30ae396 100644 --- a/include/SFML/Graphics/Shape.hpp +++ b/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 +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/Graphics/Sprite.hpp b/include/SFML/Graphics/Sprite.hpp index 100f832f6..de0c65919 100644 --- a/include/SFML/Graphics/Sprite.hpp +++ b/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 diff --git a/include/SFML/Network/TcpSocket.hpp b/include/SFML/Network/TcpSocket.hpp index a938ca2ac..c83b69786 100644 --- a/include/SFML/Network/TcpSocket.hpp +++ b/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 diff --git a/include/SFML/Network/UdpSocket.hpp b/include/SFML/Network/UdpSocket.hpp index 9f93dd4d9..2782b1dab 100644 --- a/include/SFML/Network/UdpSocket.hpp +++ b/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 diff --git a/include/SFML/Window/Window.hpp b/include/SFML/Window/Window.hpp index 49786b06e..b2a6ad0b6 100644 --- a/include/SFML/Window/Window.hpp +++ b/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.