Fixed endless loop when creating an OpenGL 3.x context (bug introduced by the last modification)

Updated the API documentation of the graphics module

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

include/SFML/Graphics/Color.hpp

@@ -34,26 +34,29 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Color is an utility class for manipulating
+/// \brief Utility class for manpulating RGBA colors
-/// 32-bits 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 red   Red component (in the range [0, 255])
-    /// \param green : Green component (0 .. 255)
+    /// \param green Green component (in the range [0, 255])
-    /// \param blue :  Blue component  (0 .. 255)
+    /// \param blue  Blue component (in the range [0, 255])
-    /// \param alpha : Alpha (opacity) component (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
+/// This operator compares two colors and check if they are equal.
-/// \param right : Right operand
 ///
-/// \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
+/// This operator compares two colors and check if they are different.
-/// \param right : Right operand
 ///
-/// \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
+/// This operator returns the component-wise sum of two colors.
-/// \param right : Right 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 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
+/// This operator returns the component-wise multiplication
-/// \param right : Right operand
+/// (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
+/// This operator computes the component-wise sum of two colors,
-/// \param right : Right operand
+/// 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
+/// This operator returns the component-wise multiplication
-/// \param right : Right operand
+/// (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 *.
+///
+////////////////////////////////////////////////////////////

include/SFML/Graphics/RenderWindow.hpp

@@ -37,77 +37,122 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Simple wrapper for sf::Window that allows easy
+/// \brief Window that can serve as a target for 2D drawing
-/// 2D rendering
+///
 ////////////////////////////////////////////////////////////
 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
+    /// This constructor creates the window with the size and pixel
-    /// \param title :    Title of the window
+    /// depth defined in \a mode. An optional style can be passed to
-    /// \param style :    Window style
+    /// customize the look and behaviour of the window (borders,
-    /// \param settings : Additional settings for the underlying OpenGL context
+    /// 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
+    /// Use this constructor if you want to create an SFML
-    /// \param settings : Additional settings for the underlying OpenGL context (see default constructor for default values)
+    /// 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
+///
+////////////////////////////////////////////////////////////

include/SFML/Window/Window.hpp

@@ -60,10 +60,8 @@ public :
     ////////////////////////////////////////////////////////////
     /// \brief Default constructor
     ///
-    /// This default constructor doesn't create the window,
+    /// This constructor doesn't actually create the window,
-    /// you must call Create() to do so.
+    /// use the other constructors or call Create to do so.
-    /// If \a style contains Style::Fullscreen, then \a mode
-    /// must be a valid video mode.
     ///
     ////////////////////////////////////////////////////////////
     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
     ///

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)
 {

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()
 {

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<const GLubyte*>("glXCreateContextAttribsARB");
         PFNGLXCREATECONTEXTATTRIBSARBPROC glXCreateContextAttribsARB = reinterpret_cast<PFNGLXCREATECONTEXTATTRIBSARBPROC>(glXGetProcAddress(name));

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<PFNWGLCREATECONTEXTATTRIBSARBPROC>(wglGetProcAddress("wglCreateContextAttribsARB"));
         if (wglCreateContextAttribsARB)