diff --git a/include/SFML/Graphics/Color.hpp b/include/SFML/Graphics/Color.hpp index cd743d97..61e43fb8 100644 --- a/include/SFML/Graphics/Color.hpp +++ b/include/SFML/Graphics/Color.hpp @@ -34,26 +34,29 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Color is an utility class for manipulating -/// 32-bits RGBA colors +/// \brief Utility class for manpulating RGBA colors +/// //////////////////////////////////////////////////////////// class SFML_API Color { public : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor + /// + /// Constructs an opaque black color. It is equivalent to + /// sf::Color(0, 0, 0, 255). /// //////////////////////////////////////////////////////////// Color(); //////////////////////////////////////////////////////////// - /// Construct the color from its 4 RGBA components + /// \brief Construct the color from its 4 RGBA components /// - /// \param red : Red component (0 .. 255) - /// \param green : Green component (0 .. 255) - /// \param blue : Blue component (0 .. 255) - /// \param alpha : Alpha (opacity) component (0 .. 255) + /// \param red Red component (in the range [0, 255]) + /// \param green Green component (in the range [0, 255]) + /// \param blue Blue component (in the range [0, 255]) + /// \param alpha Alpha (opacity) component (in the range [0, 255]) /// //////////////////////////////////////////////////////////// Color(Uint8 red, Uint8 green, Uint8 blue, Uint8 alpha = 255); @@ -76,71 +79,93 @@ public : Uint8 r; ///< Red component Uint8 g; ///< Green component Uint8 b; ///< Blue component - Uint8 a; ///< Alpha (transparency) component + Uint8 a; ///< Alpha (opacity) component }; //////////////////////////////////////////////////////////// -/// Compare two colors (for equality) +/// \brief Overload of the == operator /// -/// \param left : Left operand -/// \param right : Right operand +/// This operator compares two colors and check if they are equal. /// -/// \return True if colors are equal +/// \param left Left operand +/// \param right Right operand +/// +/// \return True if colors are equal, false if they are different /// //////////////////////////////////////////////////////////// SFML_API bool operator ==(const Color& left, const Color& right); //////////////////////////////////////////////////////////// -/// Compare two colors (for difference) +/// \brief Overload of the != operator /// -/// \param left : Left operand -/// \param right : Right operand +/// This operator compares two colors and check if they are different. /// -/// \return True if colors are different +/// \param left Left operand +/// \param right Right operand +/// +/// \return True if colors are different, false if they are equal /// //////////////////////////////////////////////////////////// SFML_API bool operator !=(const Color& left, const Color& right); //////////////////////////////////////////////////////////// -/// Operator + overload to add two colors +/// \brief Overload of the binary + operator /// -/// \param left : Left operand -/// \param right : Right operand +/// This operator returns the component-wise sum of two colors. +/// Components that exceed 255 are clamped to 255. /// -/// \return Component-wise saturated addition of the two colors +/// \param left Left operand +/// \param right Right operand +/// +/// \return Result of \a left + \a right /// //////////////////////////////////////////////////////////// SFML_API Color operator +(const Color& left, const Color& right); //////////////////////////////////////////////////////////// -/// Operator * overload to modulate two colors +/// \brief Overload of the binary * operator /// -/// \param left : Left operand -/// \param right : Right operand +/// This operator returns the component-wise multiplication +/// (also called "modulation") of two colors. +/// Components are then divided by 255 so that the result is +/// still in the range [0, 255]. /// -/// \return Component-wise multiplication of the two colors +/// \param left Left operand +/// \param right Right operand +/// +/// \return Result of \a left * \a right /// //////////////////////////////////////////////////////////// SFML_API Color operator *(const Color& left, const Color& right); //////////////////////////////////////////////////////////// -/// Operator += overload to add a color +/// \brief Overload of the binary += operator /// -/// \param left : Left operand -/// \param right : Right operand +/// This operator computes the component-wise sum of two colors, +/// and assigns the result to the left operand. +/// Components that exceed 255 are clamped to 255. /// -/// \return Component-wise saturated addition of the two colors +/// \param left Left operand +/// \param right Right operand +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// SFML_API Color& operator +=(Color& left, const Color& right); //////////////////////////////////////////////////////////// -/// Operator *= overload to modulate a color +/// \brief Overload of the binary *= operator /// -/// \param left : Left operand -/// \param right : Right operand +/// This operator returns the component-wise multiplication +/// (also called "modulation") of two colors, and assigns +/// the result to the left operand. +/// Components are then divided by 255 so that the result is +/// still in the range [0, 255]. /// -/// \return Component-wise multiplication of the two colors +/// \param left Left operand +/// \param right Right operand +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// SFML_API Color& operator *=(Color& left, const Color& right); @@ -149,3 +174,46 @@ SFML_API Color& operator *=(Color& left, const Color& right); #endif // SFML_COLOR_HPP + + +//////////////////////////////////////////////////////////// +/// \class sf::Color +/// +/// sf::Color is a simple color class composed of 4 components: +/// \li Red +/// \li Green +/// \li Blue +/// \li Alpha (opacity) +/// +/// Each component is a public member, an unsigned integer in +/// the range [0, 255]. Thus, colors can be constructed and +/// manipulated very easily: +/// +/// \code +/// sf::Color c1(255, 0, 0); // red +/// c1.red = 0; // make it black +/// c1.blue = 128; // make it dark blue +/// \endcode +/// +/// The fourth component of colors, named "alpha", represents +/// the opacity of the color. A color with an alpha value of +/// 255 will be fully opaque, while an alpha value of 0 will +/// make a color fully transparent, whatever the value of the +/// other components. +/// +/// The most common colors are already defined as static variables: +/// \code +/// sf::Color black = sf::Color::Black; +/// sf::Color white = sf::Color::White; +/// sf::Color red = sf::Color::Red; +/// sf::Color green = sf::Color::Green; +/// sf::Color blue = sf::Color::Blue; +/// sf::Color yellow = sf::Color::Yellow; +/// sf::Color magenta = sf::Color::Magenta; +/// sf::Color cyan = sf::Color::Cyan; +/// \endcode +/// +/// Colors can also be added and modulated (multiplied) using the +/// overloaded operators + and *. +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/Graphics/RenderWindow.hpp b/include/SFML/Graphics/RenderWindow.hpp index f495bf88..4d95e0a1 100644 --- a/include/SFML/Graphics/RenderWindow.hpp +++ b/include/SFML/Graphics/RenderWindow.hpp @@ -37,77 +37,122 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Simple wrapper for sf::Window that allows easy -/// 2D rendering +/// \brief Window that can serve as a target for 2D drawing +/// //////////////////////////////////////////////////////////// class SFML_API RenderWindow : public Window, public RenderTarget { public : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor + /// + /// This constructor doesn't actually create the window, + /// use the other constructors or call Create to do so. /// //////////////////////////////////////////////////////////// RenderWindow(); //////////////////////////////////////////////////////////// - /// Construct the window + /// \brief Construct a new window /// - /// \param mode : Video mode to use - /// \param title : Title of the window - /// \param style : Window style - /// \param settings : Additional settings for the underlying OpenGL context + /// This constructor 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, ...). + /// + /// The fourth parameter is an optional structure specifying + /// advanced OpenGL context settings such as antialiasing, + /// depth-buffer bits, etc. You shouldn't care about these + /// parameters for a regular usage of the graphics module. + /// + /// \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 /// //////////////////////////////////////////////////////////// RenderWindow(VideoMode mode, const std::string& title, unsigned long style = Style::Resize | Style::Close, const ContextSettings& settings = ContextSettings()); //////////////////////////////////////////////////////////// - /// Construct the window from an existing control + /// \brief Construct the window from an existing control /// - /// \param handle : Platform-specific handle of the control - /// \param settings : Additional settings for the underlying OpenGL context (see default constructor for default values) + /// Use this constructor if you want to create an SFML + /// rendering area into an already existing control. + /// + /// The fourth parameter is an optional structure specifying + /// advanced OpenGL context settings such as antialiasing, + /// depth-buffer bits, etc. You shouldn't care about these + /// parameters for a regular usage of the graphics module. + /// + /// \param handle Platform-specific handle of the control + /// \param settings Additional settings for the underlying OpenGL context /// //////////////////////////////////////////////////////////// RenderWindow(WindowHandle handle, const ContextSettings& settings = ContextSettings()); //////////////////////////////////////////////////////////// - /// Destructor + /// \brief Destructor + /// + /// Closes the window and free all the resources attached to it. /// //////////////////////////////////////////////////////////// virtual ~RenderWindow(); //////////////////////////////////////////////////////////// - /// Get the width of the rendering region of the window + /// \brief Get the width of the rendering region of the window + /// + /// The width doesn't include the titlebar and borders + /// of the window. /// /// \return Width in pixels /// + /// \see GetHeight + /// //////////////////////////////////////////////////////////// virtual unsigned int GetWidth() const; //////////////////////////////////////////////////////////// /// Get the height of the rendering region of the window /// + /// The height doesn't include the titlebar and borders + /// of the window. + /// /// \return Height in pixels /// + /// \see GetWidth + /// //////////////////////////////////////////////////////////// virtual unsigned int GetHeight() const; private : //////////////////////////////////////////////////////////// - /// /see Window::OnCreate + /// \brief Function called after the window has been created + /// + /// This function is called so that derived classes can + /// perform their own specific initialization as soon as + /// the window is created. /// //////////////////////////////////////////////////////////// virtual void OnCreate(); //////////////////////////////////////////////////////////// - /// /see Window::OnDisplay + /// \brief Function called before the window is displayed + /// + /// This function is called so that derived classes can + /// perform their own specific tasks right before the + /// rendered contents are displayed on screen. /// //////////////////////////////////////////////////////////// virtual void OnDisplay(); //////////////////////////////////////////////////////////// - /// /see RenderTarget::Activate + /// \brief Activate the target for rendering + /// + /// \param active True to activate rendering, false to deactivate + /// + /// \return True if activation succeeded /// //////////////////////////////////////////////////////////// virtual bool Activate(bool active); @@ -117,3 +162,115 @@ private : #endif // SFML_RENDERWINDOW_HPP + + +//////////////////////////////////////////////////////////// +/// \class sf::RenderWindow +/// +/// sf::RenderWindow is the main class of the Graphics module. +/// It defines an OS window that can be painted using the other +/// classes of the graphics module. +/// +/// sf::RenderWindow is derived from sf::Window, thus it inherits +/// all its features: mouse/keyboard/joystick input, events, window +/// handling, OpenGL rendering, etc. See the documentation of +/// sf::Window for a more complete description of all these features +/// and code samples. +/// +/// On top of that, sf::RenderWindow adds more features related to +/// 2D drawing with the graphics module, so that you don't need +/// to use OpenGL to draw things. You can clear the window, and draw +/// sprites, shapes or text. Here is a typical rendering / event loop +/// with a sf::RenderWindow: +/// +/// \code +/// // Declare and create a new render-window +/// sf::RenderWindow window(sf::VideoMode(800, 600), "SFML window"); +/// +/// // Limit the framerate to 60 frames per second (this step is optional) +/// window.SetFramerateLimit(60); +/// +/// // The main loop - ends as soon as the window is closed +/// while (window.IsOpened()) +/// { +/// // Event processing +/// sf::Event event; +/// while (window.GetEvent(event)) +/// { +/// // Request for closing the window +/// if (event.Type == sf::Event::Closed) +/// window.Close(); +/// } +/// +/// // Clear the whole window before rendering a new frame +/// window.Clear(); +/// +/// // Draw some sprites / shapes / texts +/// window.Draw(sprite); // sprite is a sf::Sprite +/// window.Draw(shape); // shape is a sf::Shape +/// window.Draw(text); // text is a sf::Text +/// +/// // End the current frame and display its contents on screen +/// window.Display(); +/// } +/// \endcode +/// +/// A sf::RenderWindow is also able to use views (sf::View), +/// which are a kind of 2D cameras. With views you can scroll, +/// rotate or zoom everything that is drawn to the window globally, +/// without having to transform every single entity. See the +/// documentation of sf::View for more details and sample pieces of +/// code about this class. +/// +/// Like sf::Window, sf::RenderWindow is still able to render direct +/// OpenGL stuff. It is even possible to mix together OpenGL calls +/// and regular SFML drawing commands. No particular setup is required, +/// all you have to do is to call Flush() whenever you want to make +/// sure that your SFML entities (sprites, shapes or texts) are +/// actually drawn to the window, so that your OpenGL commands will draw +/// on top of them (otherwise the rendering may be delayed internally by SFML, +/// and probably happen *after* your OpenGL calls). +/// +/// \code +/// // Create the render window +/// sf::RenderWindow window(sf::VideoMode(800, 600), "SFML OpenGL"); +/// +/// // Create a sprite and a text to display +/// sf::Sprite sprite; +/// sf::Text text; +/// ... +/// +/// // Perform OpenGL initializations +/// glMatrixMode(GL_PROJECTION); +/// ... +/// +/// // Start the rendering loop +/// while (window.IsOpened()) +/// { +/// // Process events +/// ... +/// +/// // Draw a background sprite +/// window.Draw(sprite); +/// +/// // Flush the window, to make sure that the OpenGL object +/// // will be rendered on top of the background sprite +/// window.Flush(); +/// +/// // Draw a 3D object using OpenGL +/// glBegin(GL_QUADS); +/// glVertex3f(...); +/// ... +/// glEnd(); +/// +/// // Draw text on top of the 3D object +/// window.Draw(text); +/// +/// // Finally, display the rendered frame on screen +/// window.Display(); +/// } +/// \endcode +/// +/// \see sf::Window, sf::RenderTarget, sf::RenderImage, sf::View +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/Window/Window.hpp b/include/SFML/Window/Window.hpp index baf4bd3e..d65c3453 100644 --- a/include/SFML/Window/Window.hpp +++ b/include/SFML/Window/Window.hpp @@ -60,10 +60,8 @@ public : //////////////////////////////////////////////////////////// /// \brief Default constructor /// - /// This default constructor doesn't create the window, - /// you must call Create() to do so. - /// If \a style contains Style::Fullscreen, then \a mode - /// must be a valid video mode. + /// This constructor doesn't actually create the window, + /// use the other constructors or call Create to do so. /// //////////////////////////////////////////////////////////// Window(); @@ -71,6 +69,17 @@ public : //////////////////////////////////////////////////////////// /// \brief Construct a new window /// + /// This constructor 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 + /// Style::Fullscreen, then \a mode must be a valid video mode. + /// + /// The fourth parameter is an optional structure specifying + /// advanced OpenGL context settings such as antialiasing, + /// depth-buffer bits, etc. You shouldn't care about these + /// parameters for a regular usage of the graphics module. + /// /// \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 @@ -85,6 +94,11 @@ public : /// Use this constructor if you want to create an OpenGL /// rendering area into an already existing control. /// + /// The fourth parameter is an optional structure specifying + /// advanced OpenGL context settings such as antialiasing, + /// depth-buffer bits, etc. You shouldn't care about these + /// parameters for a regular usage of the graphics module. + /// /// \param handle Platform-specific handle of the control /// \param settings Additional settings for the underlying OpenGL context /// diff --git a/src/SFML/Graphics/Color.cpp b/src/SFML/Graphics/Color.cpp index 2cb5ec2d..0c6fccf0 100644 --- a/src/SFML/Graphics/Color.cpp +++ b/src/SFML/Graphics/Color.cpp @@ -44,8 +44,6 @@ const Color Color::Magenta(255, 0, 255); const Color Color::Cyan(0, 255, 255); -//////////////////////////////////////////////////////////// -/// Default constructor //////////////////////////////////////////////////////////// Color::Color() : r(0), @@ -57,8 +55,6 @@ a(255) } -//////////////////////////////////////////////////////////// -/// Construct the color from its 4 RGBA components //////////////////////////////////////////////////////////// Color::Color(Uint8 red, Uint8 green, Uint8 blue, Uint8 alpha) : r(red), @@ -70,8 +66,6 @@ a(alpha) } -//////////////////////////////////////////////////////////// -/// Compare two colors (for equality) //////////////////////////////////////////////////////////// bool operator ==(const Color& left, const Color& right) { @@ -82,8 +76,6 @@ bool operator ==(const Color& left, const Color& right) } -//////////////////////////////////////////////////////////// -/// Compare two colors (for difference) //////////////////////////////////////////////////////////// bool operator !=(const Color& left, const Color& right) { @@ -91,8 +83,6 @@ bool operator !=(const Color& left, const Color& right) } -//////////////////////////////////////////////////////////// -/// Operator + overload to add two colors //////////////////////////////////////////////////////////// Color operator +(const Color& left, const Color& right) { @@ -103,8 +93,6 @@ Color operator +(const Color& left, const Color& right) } -//////////////////////////////////////////////////////////// -/// Operator * overload to modulate two colors //////////////////////////////////////////////////////////// Color operator *(const Color& left, const Color& right) { @@ -115,8 +103,6 @@ Color operator *(const Color& left, const Color& right) } -//////////////////////////////////////////////////////////// -/// Operator += overload to add a color //////////////////////////////////////////////////////////// Color& operator +=(Color& left, const Color& right) { @@ -124,8 +110,6 @@ Color& operator +=(Color& left, const Color& right) } -//////////////////////////////////////////////////////////// -/// Operator *= overload to modulate a color //////////////////////////////////////////////////////////// Color& operator *=(Color& left, const Color& right) { diff --git a/src/SFML/Graphics/RenderWindow.cpp b/src/SFML/Graphics/RenderWindow.cpp index 03ba4594..10e645c6 100644 --- a/src/SFML/Graphics/RenderWindow.cpp +++ b/src/SFML/Graphics/RenderWindow.cpp @@ -35,16 +35,12 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// RenderWindow::RenderWindow() { // Nothing to do } -//////////////////////////////////////////////////////////// -/// Construct the window //////////////////////////////////////////////////////////// RenderWindow::RenderWindow(VideoMode mode, const std::string& title, unsigned long style, const ContextSettings& settings) { @@ -53,8 +49,6 @@ RenderWindow::RenderWindow(VideoMode mode, const std::string& title, unsigned lo } -//////////////////////////////////////////////////////////// -/// Construct the window from an existing control //////////////////////////////////////////////////////////// RenderWindow::RenderWindow(WindowHandle handle, const ContextSettings& settings) { @@ -63,8 +57,6 @@ RenderWindow::RenderWindow(WindowHandle handle, const ContextSettings& settings) } -//////////////////////////////////////////////////////////// -/// Destructor //////////////////////////////////////////////////////////// RenderWindow::~RenderWindow() { @@ -72,8 +64,6 @@ RenderWindow::~RenderWindow() } -//////////////////////////////////////////////////////////// -/// /see RenderTarget::Activate //////////////////////////////////////////////////////////// bool RenderWindow::Activate(bool active) { @@ -82,8 +72,6 @@ bool RenderWindow::Activate(bool active) } -//////////////////////////////////////////////////////////// -/// Get the width of the rendering region of the window //////////////////////////////////////////////////////////// unsigned int RenderWindow::GetWidth() const { @@ -91,8 +79,6 @@ unsigned int RenderWindow::GetWidth() const } -//////////////////////////////////////////////////////////// -/// Get the height of the rendering region of the window //////////////////////////////////////////////////////////// unsigned int RenderWindow::GetHeight() const { @@ -100,8 +86,6 @@ unsigned int RenderWindow::GetHeight() const } -//////////////////////////////////////////////////////////// -/// Called after the window has been created //////////////////////////////////////////////////////////// void RenderWindow::OnCreate() { @@ -110,8 +94,6 @@ void RenderWindow::OnCreate() } -//////////////////////////////////////////////////////////// -/// Called before the window has been displayed //////////////////////////////////////////////////////////// void RenderWindow::OnDisplay() { diff --git a/src/SFML/Window/Linux/ContextGLX.cpp b/src/SFML/Window/Linux/ContextGLX.cpp index 97ed03eb..37732376 100644 --- a/src/SFML/Window/Linux/ContextGLX.cpp +++ b/src/SFML/Window/Linux/ContextGLX.cpp @@ -247,7 +247,7 @@ void ContextGLX::CreateContext(ContextGLX* shared, unsigned int bitsPerPixel, co GLXContext toShare = shared ? shared->myContext : NULL; // Create the OpenGL context -- first try an OpenGL 3.0 context if it is requested - while (mySettings.MajorVersion >= 3) + while (!myContext && (mySettings.MajorVersion >= 3)) { const GLubyte* name = reinterpret_cast("glXCreateContextAttribsARB"); PFNGLXCREATECONTEXTATTRIBSARBPROC glXCreateContextAttribsARB = reinterpret_cast(glXGetProcAddress(name)); diff --git a/src/SFML/Window/Win32/ContextWGL.cpp b/src/SFML/Window/Win32/ContextWGL.cpp index 68486c0d..5a902282 100644 --- a/src/SFML/Window/Win32/ContextWGL.cpp +++ b/src/SFML/Window/Win32/ContextWGL.cpp @@ -270,7 +270,7 @@ void ContextWGL::CreateContext(ContextWGL* shared, unsigned int bitsPerPixel, co HGLRC sharedContext = shared ? shared->myContext : NULL; // Create the OpenGL context -- first try an OpenGL 3.0 context if it is requested - while (mySettings.MajorVersion >= 3) + while (!myContext && (mySettings.MajorVersion >= 3)) { PFNWGLCREATECONTEXTATTRIBSARBPROC wglCreateContextAttribsARB = reinterpret_cast(wglGetProcAddress("wglCreateContextAttribsARB")); if (wglCreateContextAttribsARB)