Clarify QOpenGLContext::format() docs

Avoid unrealistic expectations where applications would assume that
requestedFormat() == format().

Change-Id: I12dcfda3d86ce26f1cae9771b1fe2203291864db
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

1 files changed, 14 insertions, 0 deletions

diff --git a/src/gui/kernel/qopenglcontext.cpp b/src/gui/kernel/qopenglcontext.cpp
index f68915edeb..74771d6826 100644
--- a/src/gui/kernel/qopenglcontext.cpp
+++ b/src/gui/kernel/qopenglcontext.cpp
@@ -885,6 +885,20 @@ QFunctionPointer QOpenGLContext::getProcAddress(const QByteArray &procName) cons
     Returns the format of the underlying platform context, if create() has been called.
 
     Otherwise, returns the requested format.
+
+    The requested and the actual format may differ. Requesting a given OpenGL version does
+    not mean the resulting context will target exactly the requested version. It is only
+    guaranteed that the version/profile/options combination for the created context is
+    compatible with the request, as long as the driver is able to provide such a context.
+
+    For example, requesting an OpenGL version 3.x core profile context may result in an
+    OpenGL 4.x core profile context. Similarly, a request for OpenGL 2.1 may result in an
+    OpenGL 3.0 context with deprecated functions enabled. Finally, depending on the
+    driver, unsupported versions may result in either a context creation failure or in a
+    context for the highest supported version.
+
+    Similar differences are possible in the buffer sizes, for example, the resulting
+    context may have a larger depth buffer than requested. This is perfectly normal.
 */
 QSurfaceFormat QOpenGLContext::format() const
 {