From 5d778b2bc4b420124a8c510424275d8dbbf25f6e Mon Sep 17 00:00:00 2001 From: LaurentGom Date: Wed, 4 Nov 2009 16:04:18 +0000 Subject: [PATCH] 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 | 207 +++++++++++++++++++++++++-------- samples/opengl/OpenGL.cpp | 12 +- src/SFML/Graphics/View.cpp | 42 +------ 3 files changed, 161 insertions(+), 100 deletions(-) diff --git a/include/SFML/Graphics/View.hpp b/include/SFML/Graphics/View.hpp index 961c88d7..b7592a58 100644 --- a/include/SFML/Graphics/View.hpp +++ b/include/SFML/Graphics/View.hpp @@ -37,186 +37,236 @@ namespace sf { //////////////////////////////////////////////////////////// -/// This class defines a 2D view. A view is like a camera, -/// 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. +/// \brief 2D camera that defines what region is shown on screen +/// //////////////////////////////////////////////////////////// class SFML_API View { public : //////////////////////////////////////////////////////////// - /// Default constructor - /// Constructs a default view of (0, 0, 1000, 1000) + /// \brief Default constructor + /// + /// 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 size : Size of the view + /// \param center Center of the zone to display + /// \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 y : Y coordinate of the new center + /// \param x X 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 height : New height + /// \param width New width of the view + /// \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. - /// Note: this function resets the rotation angle to 0. + /// \brief Reset the view to the given rectangle /// - /// \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 offsetY : Offset to move the view, on Y axis + /// \param offsetX X coordinate of the move offset + /// \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 +/// +//////////////////////////////////////////////////////////// diff --git a/samples/opengl/OpenGL.cpp b/samples/opengl/OpenGL.cpp index b397db8a..35e982e2 100644 --- a/samples/opengl/OpenGL.cpp +++ b/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 diff --git a/src/SFML/Graphics/View.cpp b/src/SFML/Graphics/View.cpp index 25211a48..efdfddad 100644 --- a/src/SFML/Graphics/View.cpp +++ b/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 {