Improved the API documentation of sf::View

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

include/SFML/Graphics/View.hpp

@@ -37,186 +37,236 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// This class defines a 2D view. A view is like a camera,
+/// \brief 2D camera that defines what region is shown on screen
-/// which defines what part of the scene is shown and
+///
-/// where it is shown.
-/// A sf::View is defined by the following components:
-/// its source rectangle in the scene, an optional rotation
-/// to apply to the source rectangle, and the destination
-/// rectangle where it will be displayed, in the render target
-/// that it is attached to.
 ////////////////////////////////////////////////////////////
 class SFML_API View
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
-    /// Constructs a default view of (0, 0, 1000, 1000)
+    ///
+    /// This constructor creates a default view of (0, 0, 1000, 1000)
     ///
     ////////////////////////////////////////////////////////////
     View();
 
     ////////////////////////////////////////////////////////////
-    /// Construct the view from a rectangle
+    /// \brief Construct the view from a rectangle
     ///
-    /// \param rectangle : Rectangle defining the view
+    /// \param rectangle Rectangle defining the zone to display
     ///
     ////////////////////////////////////////////////////////////
     explicit View(const FloatRect& rectangle);
 
     ////////////////////////////////////////////////////////////
-    /// Construct the view from its center and size
+    /// \brief Construct the view from its center and size
     ///
-    /// \param center : Center of the view
+    /// \param center Center of the zone to display
-    /// \param size :   Size of the view
+    /// \param size   Size of zone to display
     ///
     ////////////////////////////////////////////////////////////
     View(const Vector2f& center, const Vector2f& size);
 
     ////////////////////////////////////////////////////////////
-    /// Change the center of the view
+    /// \brief Set the center of the view
     ///
-    /// \param x : X coordinate of the new center
+    /// \param x X coordinate of the new center
-    /// \param y : Y coordinate of the new center
+    /// \param y Y coordinate of the new center
+    ///
+    /// \see SetSize, GetCenter
     ///
     ////////////////////////////////////////////////////////////
     void SetCenter(float x, float y);
 
     ////////////////////////////////////////////////////////////
-    /// Change the center of the view
+    /// \brief Set the center of the view
     ///
-    /// \param center : New center
+    /// \param center New center
+    ///
+    /// \see SetSize, GetCenter
     ///
     ////////////////////////////////////////////////////////////
     void SetCenter(const Vector2f& center);
 
     ////////////////////////////////////////////////////////////
-    /// Change the size of the view
+    /// \brief Set the size of the view
     ///
-    /// \param width :  New width
+    /// \param width  New width of the view
-    /// \param height : New height
+    /// \param height New height of the view
+    ///
+    /// \see SetCenter, GetCenter
     ///
     ////////////////////////////////////////////////////////////
     void SetSize(float width, float height);
 
     ////////////////////////////////////////////////////////////
-    /// Change the size of the view
+    /// \brief Set the size of the view
     ///
-    /// \param size : New size
+    /// \param size New size
+    ///
+    /// \see SetCenter, GetCenter
     ///
     ////////////////////////////////////////////////////////////
     void SetSize(const Vector2f& size);
 
     ////////////////////////////////////////////////////////////
-    /// Set the angle of rotation of the view
+    /// \brief Set the orientation of the view
     ///
-    /// \param angle : New angle, in degrees
+    /// The default rotation of a view is 0 degree.
+    ///
+    /// \param angle New angle, in degrees
+    ///
+    /// \see GetRotation
     ///
     ////////////////////////////////////////////////////////////
     void SetRotation(float angle);
 
     ////////////////////////////////////////////////////////////
-    /// Set the target viewport
+    /// \brief Set the target viewport
     ///
     /// The viewport is the rectangle into which the contents of the
     /// view are displayed, expressed as a factor (between 0 and 1)
     /// of the size of the RenderTarget to which the view is applied.
-    ///
     /// For example, a view which takes the left side of the target would
     /// be defined with View.SetViewport(sf::FloatRect(0, 0, 0.5, 1)).
+    /// By default, a view has a viewport which covers the entire target.
     ///
-    /// \param viewport : New viewport
+    /// \param viewport New viewport rectangle
+    ///
+    /// \see GetViewport
     ///
     ////////////////////////////////////////////////////////////
     void SetViewport(const FloatRect& viewport);
 
     ////////////////////////////////////////////////////////////
-    /// Reset the view to the given rectangle.
+    /// \brief Reset the view to the given rectangle
-    /// Note: this function resets the rotation angle to 0.
     ///
-    /// \param rectangle : Rectangle defining the view
+    /// Note that this function resets the rotation angle to 0.
+    /// It is a function provided for convenience, equivalent to the
+    /// following calls:
+    /// \code
+    /// view.SetCenter(rectangle.GetCenter());
+    /// view.SetSize(rectangle.GetSize());
+    /// view.SetRotation(0);
+    /// \endcode
+    ///
+    /// \param rectangle Rectangle defining the zone to display
+    ///
+    /// \see SetCenter, SetSize, SetRotation
     ///
     ////////////////////////////////////////////////////////////
     void Reset(const FloatRect& rectangle);
 
     ////////////////////////////////////////////////////////////
-    /// Get the center of the view
+    /// \brief Get the center of the view
     ///
     /// \return Center of the view
     ///
+    /// \see GetSize, SetCenter
+    ///
     ////////////////////////////////////////////////////////////
     const Vector2f& GetCenter() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the size of the view
+    /// \brief Get the size of the view
     ///
     /// \return Size of the view
     ///
+    /// \see GetCenter, SetSize
+    ///
     ////////////////////////////////////////////////////////////
     const Vector2f& GetSize() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the current rotation
+    /// \brief Get the current orientation of the view
     ///
-    /// \return Rotation of the view, in degrees
+    /// \return Rotation angle of the view, in degrees
+    ///
+    /// \see SetRotation
     ///
     ////////////////////////////////////////////////////////////
     float GetRotation() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the target viewport
+    /// \brief Get the target viewport rectangle of the view
     ///
     /// \return Viewport rectangle, expressed as a factor of the target size
     ///
+    /// \see SetViewport
+    ///
     ////////////////////////////////////////////////////////////
     const FloatRect& GetViewport() const;
 
     ////////////////////////////////////////////////////////////
-    /// Move the view
+    /// \brief Move the view relatively to its current position
     ///
-    /// \param offsetX : Offset to move the view, on X axis
+    /// \param offsetX X coordinate of the move offset
-    /// \param offsetY : Offset to move the view, on Y axis
+    /// \param offsetY Y coordinate of the move offset
+    ///
+    /// \see SetCenter, Rotate, Zoom
     ///
     ////////////////////////////////////////////////////////////
     void Move(float offsetX, float offsetY);
 
     ////////////////////////////////////////////////////////////
-    /// Move the view
+    /// \brief Move the view relatively to its current position
     ///
-    /// \param offset : Offset to move the view
+    /// \param offset Move offset
+    ///
+    /// \see SetCenter, Rotate, Zoom
     ///
     ////////////////////////////////////////////////////////////
     void Move(const Vector2f& offset);
 
     ////////////////////////////////////////////////////////////
-    /// Rotate the view
+    /// \brief Rotate the view relatively to its current orientation
     ///
-    /// \param angle : Angle to rotate, in degrees
+    /// \param angle Angle to rotate, in degrees
+    ///
+    /// \see SetRotation, Move, Zoom
     ///
     ////////////////////////////////////////////////////////////
     void Rotate(float angle);
 
     ////////////////////////////////////////////////////////////
-    /// Resize the view rectangle to simulate a zoom / unzoom effect
+    /// \brief Resize the view rectangle relatively to its current size
     ///
-    /// \param factor : Zoom factor to apply, relative to the current size
+    /// Resizing the view simulates a zoom, as the zone displayed on
+    /// screen grows or shrinks.
+    /// \a factor is a multiplier:
+    /// \li 1 keeps the size unchanged
+    /// \li > 1 makes the view bigger (objects appear smaller)
+    /// \li < 1 makes the view smaller (objects appear bigger)
+    ///
+    /// \param factor Zoom factor to apply
+    ///
+    /// \see SetSize, Move, Rotate
     ///
     ////////////////////////////////////////////////////////////
     void Zoom(float factor);
 
     ////////////////////////////////////////////////////////////
-    /// Get the projection matrix of the view
+    /// \brief Get the projection matrix of the view
     ///
-    /// \return Projection matrix
+    /// This functions is meant for internal use only.
+    ///
+    /// \return Projection matrix defining the view
+    ///
+    /// \see GetInverseMatrix
     ///
     ////////////////////////////////////////////////////////////
     const Matrix3& GetMatrix() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the inverse projection matrix of the view
+    /// \brief Get the inverse projection matrix of the view
     ///
-    /// \return Inverse projection matrix
+    /// This functions is meant for internal use only.
+    ///
+    /// \return Inverse of the projection matrix defining the view
+    ///
+    /// \see GetMatrix
     ///
     ////////////////////////////////////////////////////////////
     const Matrix3& GetInverseMatrix() const;
@@ -240,3 +290,58 @@ private :
 
 
 #endif // SFML_VIEW_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::View
+///
+/// sf::View defines a camera in the 2D scene. This is a
+/// very powerful concept: you can scroll, rotate or zoom
+/// the entire scene without altering the way that your
+/// drawable objects are drawn.
+///
+/// A view is composed of a source rectangle, which defines
+/// what part of the 2D scene is shown, and a target viewport,
+/// which defines where the contents of the source rectangle
+/// will be displayed on the render target (window or render-image).
+///
+/// The viewport allows to map the scene to a custom part
+/// of the render target, and can be used for split-screen
+/// or for displaying a minimap, for example. If the source
+/// rectangle has not the same size as the viewport, its
+/// contents will be stretched to fit in.
+///
+/// To apply a view, you have to assign it to the render target.
+/// Then, every objects drawn in this render target will be
+/// affected by the view until you use another view.
+///
+/// Usage example:
+/// \code
+/// sf::RenderWindow window;
+/// sf::View view;
+/// 
+/// // Initialize the view to a rectangle going from (100, 100) to (500, 300)
+/// view.Reset(sf::FloatRect(100, 100, 500, 300));
+///
+/// // Rotate it by 45 degrees
+/// view.Rotate(45);
+///
+/// // Set its target viewport to be half of the window
+/// view.SetViewport(sf::FloatRect(0.f, 0.f, 0.5f, 1.f));
+///
+/// // Apply it
+/// window.SetView(view);
+///
+/// // Render stuff
+/// window.Draw(someSprite);
+///
+/// // Set the default view back
+/// window.SetView(window.GetDefaultView());
+///
+/// // Render stuff not affected by the view
+/// window.Draw(someText);
+/// \endcode
+///
+/// \see RenderWindow, RenderImage
+///
+////////////////////////////////////////////////////////////

samples/opengl/OpenGL.cpp

@@ -15,12 +15,9 @@
 ////////////////////////////////////////////////////////////
 int main()
 {
-    // Create the main window and activate it
+    // Create the main window
     sf::RenderWindow window(sf::VideoMode(800, 600), "SFML OpenGL");
 
-    // Activate it as the target for OpenGL calls
-    window.SetActive();
-
     // Create a sprite for the background
     sf::Image backgroundImage;
     if (!backgroundImage.LoadFromFile("datas/opengl/background.jpg"))
@@ -77,10 +74,7 @@ int main()
 
             // Adjust the viewport when the window is resized
             if (event.Type == sf::Event::Resized)
-            {
-                window.SetActive();
                 glViewport(0, 0, event.Size.Width, event.Size.Height);
-            }
         }
 
         // Draw the background
@@ -90,7 +84,9 @@ int main()
         // will be rendered on top of the background sprite
         window.Flush();
 
-        // Activate the window
+        // Activate the window before using OpenGL commands.
+        // This is useless here because we have only one window which is
+        // always the active one, but don't forget it if you use multiple windows
         window.SetActive();
 
         // Clear the depth buffer

src/SFML/Graphics/View.cpp

@@ -31,9 +31,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-/// Constructs a default view of (0, 0, 1000, 1000)
-////////////////////////////////////////////////////////////
 View::View() :
 myCenter       (),
 mySize         (),
@@ -46,8 +43,6 @@ myNeedInvUpdate(true)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct the view from a rectangle
 ////////////////////////////////////////////////////////////
 View::View(const FloatRect& rectangle) :
 myCenter       (),
@@ -61,8 +56,6 @@ myNeedInvUpdate(true)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct the view from its center and size
 ////////////////////////////////////////////////////////////
 View::View(const Vector2f& center, const Vector2f& size) :
 myCenter       (center),
@@ -75,8 +68,6 @@ myNeedInvUpdate(true)
 
 }
 
-////////////////////////////////////////////////////////////
-/// Change the center of the view
 ////////////////////////////////////////////////////////////
 void View::SetCenter(float x, float y)
 {
@@ -87,8 +78,6 @@ void View::SetCenter(float x, float y)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the center of the view
 ////////////////////////////////////////////////////////////
 void View::SetCenter(const Vector2f& center)
 {
@@ -96,8 +85,6 @@ void View::SetCenter(const Vector2f& center)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the size of the view
 ////////////////////////////////////////////////////////////
 void View::SetSize(float width, float height)
 {
@@ -108,8 +95,6 @@ void View::SetSize(float width, float height)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the size of the view
 ////////////////////////////////////////////////////////////
 void View::SetSize(const Vector2f& size)
 {
@@ -117,8 +102,6 @@ void View::SetSize(const Vector2f& size)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the angle of rotation of the view
 ////////////////////////////////////////////////////////////
 void View::SetRotation(float angle)
 {
@@ -130,8 +113,6 @@ void View::SetRotation(float angle)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the target viewport
 ////////////////////////////////////////////////////////////
 void View::SetViewport(const FloatRect& viewport)
 {
@@ -139,20 +120,17 @@ void View::SetViewport(const FloatRect& viewport)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Reset the view to the given rectangle
 ////////////////////////////////////////////////////////////
 void View::Reset(const FloatRect& rectangle)
 {
     myCenter        = rectangle.GetCenter();
     mySize          = rectangle.GetSize();
+    myRotation      = 0;
     myNeedUpdate    = true;
     myNeedInvUpdate = true;
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the center of the view
 ////////////////////////////////////////////////////////////
 const Vector2f& View::GetCenter() const
 {
@@ -160,8 +138,6 @@ const Vector2f& View::GetCenter() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the size of the view
 ////////////////////////////////////////////////////////////
 const Vector2f& View::GetSize() const
 {
@@ -169,8 +145,6 @@ const Vector2f& View::GetSize() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the current rotation
 ////////////////////////////////////////////////////////////
 float View::GetRotation() const
 {
@@ -178,8 +152,6 @@ float View::GetRotation() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the target viewport
 ////////////////////////////////////////////////////////////
 const FloatRect& View::GetViewport() const
 {
@@ -187,8 +159,6 @@ const FloatRect& View::GetViewport() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Move the view
 ////////////////////////////////////////////////////////////
 void View::Move(float offsetX, float offsetY)
 {
@@ -196,8 +166,6 @@ void View::Move(float offsetX, float offsetY)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Move the view
 ////////////////////////////////////////////////////////////
 void View::Move(const Vector2f& offset)
 {
@@ -205,8 +173,6 @@ void View::Move(const Vector2f& offset)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Rotate the view
 ////////////////////////////////////////////////////////////
 void View::Rotate(float angle)
 {
@@ -214,8 +180,6 @@ void View::Rotate(float angle)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Resize the view rectangle to simulate a zoom / unzoom effect
 ////////////////////////////////////////////////////////////
 void View::Zoom(float factor)
 {
@@ -223,8 +187,6 @@ void View::Zoom(float factor)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the projection matrix of the view
 ////////////////////////////////////////////////////////////
 const Matrix3& View::GetMatrix() const
 {
@@ -239,8 +201,6 @@ const Matrix3& View::GetMatrix() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the inverse projection matrix of the view
 ////////////////////////////////////////////////////////////
 const Matrix3& View::GetInverseMatrix() const
 {