diff options
Diffstat (limited to 'util/glgen/README.txt')
-rw-r--r-- | util/glgen/README.txt | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/util/glgen/README.txt b/util/glgen/README.txt new file mode 100644 index 0000000000..ea2411f619 --- /dev/null +++ b/util/glgen/README.txt @@ -0,0 +1,151 @@ +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/
\ No newline at end of file |