Overview ======== This is the glgen application used to generate OpenGL related classes from the official Khronos OpenGL specification and typemap files. To run this application download the gl.spec and gl.tm files from: http://www.opengl.org/registry/api/gl.spec http://www.opengl.org/registry/api/gl.tm and place them into the application directory. These files are not stored in the Qt Project's git repo or downloaded automatically to a) avoid copyright issues b) make sure the version of OpenGL used is controlled by a human The glgen application parses these files and generates: 1) A set of public classes, one for each combination of OpenGL version and profile. 2) A set of backend helper classes that contain the actual function pointers 3) A factory class for the classes in 1) 4) A set of classes, one for each OpenGL extension which introduces new entry points We will now describe each of these categories. OpenGL Version and Profile Classes ================================== The base class of this set is QAbstractOpenGLFunctions. From this we inherit one class for each OpenGL version and if supported, profile. The Core profile contains only the non-deprecated functionality. The Compatibility profile also includes all functionality that was removed in OpenGL 3.1. Therefore, for OpenGL 3.2 onwards we have two classes for each version. All of these classes are named with the following convention: QOpenGLFunctions_<MAJOR>_<MINOR>[_PROFILE] For example QOpenGLFunctions_2_1, QOpenGLFunctions_4_3_Core The source and header files for these classes take the form qopenglfunction_<MAJOR>_<MINOR>[_PROFILE].cpp qopenglfunction_<MAJOR>_<MINOR>[_PROFILE].h and should be moved to $QTBASE/src/gui/opengl/ and forms part of the public QtGui library API. Backend Helper Classes ====================== Every OpenGL function is categorised by which version it was introduced with and whether it is part of the Core Profile and is deemed part of the core specification or whther it is only part of the Compatibility profile and has been marked as deprecated. Glgen creates a backend helper class containing function pointers to match each possible case. E.g. QOpenGLFunctions_1_5_CoreBackend contains functions introduced in OpenGL 1.5 which are still core (not deprecated). The public frontend classes described above contain pointers to the set of backend objects necessary to implement the functions for their version and profile. Creating new instances of these backend objects for each public version functions object would be wasteful in terms of memory (repeated function pointers) and CPU time (no need to keep re-solving the same functions). We cannot share the backend objects globally as OpenGL entry point addresses are specific to the OpenGL context. They cannot even be reliably shared between a context group. This is not surprising if you consider the case of contexts in a share group where the contexts have different versions or even profiles. We therefore share the backend instances at the QOpenGLContext level using a simple reference counting scheme. When the frontend version functions objects are intialized they check to see if the associated context already has suitable backend objects available. If so they use them, otherwise they will create backend objects and associate them with the context. The backend classes are in qopenglversionfunctions.h qopenglversionfunctions.cpp and should also be moved to $QTBASE/src/gui/opengl/ OpenGL Version and Profile Factory ================================== Instances of the OpenGL version and profile classes described above can be obtained from QOpenGLContext by means of the versionFunctions() member. The OpenGLContext retains ownership of the QOpenGLFunctions_* object. If a suitable object does not already exist it is created by the factory class generated by glgen. It is possible to request version functions objects for any version/profile combination from a context. However not all requests can be serviced. For example consider the case of an OpenGL 3.3 Core profile context. In this case: * Requesting a 3.3 core profile functions object would succeed. * Requesting a 3.3 compatibility profile functions object would fail. We would fail to resolve the deprecated functions. * Requesting a 4.3 core profile functions object would fail. We would fail to resolve the new core functions introduced in versions 4.0-4.3. * Requesting a 3.1 functions object would succeed. There is nothing in 3.1 that is not also in 3.3 core. If a request is not able to be serviced the factory, and hence QOpenGLContext::versionFunctions() will return a null pointer that can be checked for. The source and header file for this class should be moved to $QTBASE/src/gui/opengl/ and forms part of the QtGui library. If a user instantiates a version functions object directly (i.e. not via QOpenGLContext) then it bypasses the above checks. However, the same checks are applied in the initializeOpenGLFunctions() method and the result can once again be checked. This approach allows maximum flexibility but ensure's safety in that once the user posesses a functions object that has been successfully initialized they can rely upon its member functions being successfully resolved. OpenGL Extension Classes ======================== In addition, glgen also creates one class for each OpenGL extension that introduces new entry points. These classes are named with the convention QOpenGLExtension_<name-of-extension> The usage pattern for OpenGL extensions is to just use a small number of extensions out of the large number of those available. Rather than bloat QtGui with all possible extensions, a new static library will be introduced to hold these classes. That way users will only link in the code for the extensions that they actually use. The source and header file for these classes should be moved to $QTBASE/src/openglextensions/