Improve new wxGLCanvas compatibility with old hardware and code

Combined patch with the following changes:
- Don't add wxGLAttributes::Defaults() when the attributes-list is NULL.
- Add display default attributes used in wx versions before 3.1 when the
  attributes-list is NULL. These attributes are different for each platform.
- Fix wxMSW PixelFormatDescriptor initialization.
- Don't set color buffers when RGBA() is used.
- Fix setting colour sizes in OS X and a few other fixes.
- Make documentation more clear about these subjects.

Closes #17425.

interface/wx/glcanvas.h

@@ -130,6 +130,7 @@ public:
     @note Not all of platform-dependant available attributes are implemented in
           wxWidgets. You can set other attributes by using AddAttribute() and
           AddAttribBits() functions inherited from the base wxGLAttribsBase class.
+          While WGL_/GLX_/NS attributes can be added, PFD_ (for MSW) can not.
 
     @since 3.1.0
 
@@ -142,13 +143,14 @@ class wxGLAttributes : public wxGLAttribsBase
 {
 public:
     /**
-        Use true color (8 bits for each color plus 8 bits for alpha channel).
+        Use true colour instead of colour index rendering for each pixel.
+        It makes no effect for OS X.
     */
     wxGLAttributes& RGBA();
 
     /**
-        Specifies the number of bits for buffer when it isn't a RGBA buffer.
-        It makes no effect for OS X.
+        Specifies the number of bits for colour buffer. For RGBA it's
+        normally the sum of the bits per each component.
 
         @param val
         The number of bits.
@@ -164,12 +166,12 @@ public:
     wxGLAttributes& Level(int val);
 
     /**
-        Requests using double buffering if present.
+        Requests using double buffering.
     */
     wxGLAttributes& DoubleBuffer();
 
     /**
-        Use stereoscopic display if present.
+        Use stereoscopic display.
     */
     wxGLAttributes& Stereo();
 
@@ -182,7 +184,8 @@ public:
     wxGLAttributes& AuxBuffers(int val);
 
     /**
-        Specifies the minimal number of bits for colour buffers.
+        Specifies the minimal number of bits for each colour and alpha.
+        On MSW and OSX this function also sets the size of the colour buffer.
 
         @param mRed
         The minimal number of bits for colour red.
@@ -212,7 +215,8 @@ public:
     wxGLAttributes& Stencil(int val);
 
     /**
-        Specifies the minimal number of bits for the accumulation buffer.
+        Specifies the minimal number of bits for each accumulator channel.
+        On MSW and OSX this function also sets the size of the accumulation buffer.
 
         @param mRed
         The minimal number of bits for red accumulator.
@@ -552,7 +556,7 @@ enum
     /// do not use a palette.
     WX_GL_RGBA = 1,
 
-    /// (F) Specifies the number of bits for buffer if not WX_GL_RGBA.
+    /// (F) Specifies the number of bits for colour buffer.
     WX_GL_BUFFER_SIZE,
 
     /// (F) 0 for main buffer, >0 for overlay, <0 for underlay.
@@ -816,7 +820,8 @@ public:
         This constructor is still available only for compatibility reasons.
         Please use the constructor with wxGLAttributes instead.
 
-        If @a attribList is not specified, wxGLAttributes::Defaults() is used.
+        If @a attribList is not specified, wxGLAttributes::PlatformDefaults()
+        is used, plus some other attributes (see below).
 
         @param attribList
             Array of integers. With this parameter you can set the device
@@ -871,10 +876,10 @@ public:
     static bool IsDisplaySupported(const int* attribList);
 
     /**
-        Returns true if the extension with given name is supported
+        Returns true if the extension with given name is supported.
 
         Notice that while this function is implemented for all of GLX, WGL and
-        AGL the extensions names are usually not the same for different
+        NSOpenGL the extensions names are usually not the same for different
         platforms and so the code using it still usually uses conditional
         compilation.
     */