Deprecated and unsupported functions
Old functionality and classes are normally not removed instantly, but marked as deprecated or unsupported. You need to define ACGL_INCLUDE_DEPRECATED or ACGL_INCLUDE_UNSUPPORTED to still use them.
- ACGL_INCLUDE_DEPRECATED : These functions are marked for removal in a later version. If you need them and see a benefit in them over the newer functions, inform Robert. If there are good arguments for keeping them, they might loose there deprecated status.
- ACGL_INCLUDE_UNSUPPORTED : Functionality that is incomplete, undocumented or was included by persons who are not present anymore to give support. These functions might get removed if they are not used, but they could as well be "resurrected" if needed and someone invests the effort in completing and/or documenting them. In case you need them, inform Robert - maybe you want to support them?
Setting the OpenGL version
We have to distinguish three OpenGL versions:
- The maximal supported version of the OS & GPU
- The version available at runtime
- The version the application was developed for
Not all GPUs can run all versions of OpenGL and even if they could, the driver and OS might limit the version further (I'm looking at you, MacOS!). The version available at runtime (== the version of the OpenGL context) can be lower than the maximal supported version of the OS. Most of the time the application gets the highest possible version unless asked explicitly for a lower version (there are exceptions - I'm looking at you, MacOS!). The version at runtime can't get changed from OpenGL itself, but it can get queried and tested against the version the developer intended. That version can be set with the define:
(replace 32 by the version you expect the runtime to provide at least (without the dot, so OpenGL 4.1 -> 41)). A core profile can be enforced by ACGL_OPENGL_PROFILE_CORE . If no defines are set, OpenGL 3.2 will be the default. The OpenGL define will influence two things:
- ACGL will check the available version at runtime against the defined by the user and give an error if the runtime has an older version.
- ACGL will only provide and load the function pointers and defines for the specified OpenGL version - this way you can't use OpenGL functions more recent than the defined version as the compiler would fail with undefined functions.
The second point only applies in case the internal OpenGL function loader is used (in contrast to a user-provided GLEW).
To just get the latest OpenGL version define ACGL_OPENGL_INCLUDE_LATEST_GL instead of a specific version.
ACGL for OpenGL ES
if ACGL_OPENGLES_VERSION_20 or ACGL_OPENGLES_VERSION_30 is defined, ACGL will build for OpenGL ES. Note that ES support is not complete yet. A lot is based on VAOs which are only present in ES 3.0 and on some Android devices with ES 2.0 as extensions as well as most iOS devices (but support for these extensions is missing). Better support is planned and adjusting ACGL should be simple.
Use GLEW instead of our own loader
Every OpenGL application has to load the function pointers for OpenGL on its own. Often this is done with GLEW but that has some drawback with core profiles or MacOS. So ACGL provides its own loader which is based on glLoadGen. It is used automatically unless ACGL_USE_GLEW is defined by the build system. If not (just do nothing) ACGL will load the functions on its own an will define ACGL_EXTENSION_LOADER_GLLOADGEN (the application can check these defines to use GLEW/glLoadGen functions for extension testing, but note that ACGL provides some wrappers for this already in ACGL/OpenGL/glloaders/extensions.hh !). Also note that the loading of the function pointers is done in ACGL::init(), even if the user wants to use GLEW! The GLEW header will also get included by GL.hh.
OpenGL error checks
Note: The below functionality is still present for programs that use the error checks in there own code but is not used inside of ACGL anymore. Use callbacks to get errors as soon as they occur using glDebugMessageCallback() from KHR_debug. Using the internal function loader of ACGL, this extension is always present (simulated if needed) even on systems without native support (e.g. MacOS).
Define one of the following:
- ACGL_ERROR_LEVEL_EC0 no error checks are performed. Use this for maximal performance in bug-free programs.
- ACGL_ERROR_LEVEL_EC1 only check for a few very critical errors like out-of-memory problems
- ACGL_ERROR_LEVEL_EC2 normal error checking, tests shader compiles etc. Should be enough in most cases.
- ACGL_ERROR_LEVEL_EC3 Check a lot. Good for debugging.
If none of these are defined, ACGL will set ACGL_ERROR_LEVEL_EC1 in release and ACGL_ERROR_LEVEL_EC3 in debug build (as long as the build system sets the DEBUG define or the ACGL cmake files are used with cmake set to debug).
The application can also add OpenGL error checks that use this system:
- openGLCheckError() Will always call glGetError() and print the error if there was one
- openGLErrorOccured() Same as openGLCheckError() but will return a bool that's true iff there was an error
- openGLCriticalError() Checks for errors only if build with ACGL_ERROR_LEVEL_EC1, ACGL_ERROR_LEVEL_EC2 or ACGL_ERROR_LEVEL_EC3
- openGLCommonError() Checks for errors only if build with ACGL_ERROR_LEVEL_EC2 or ACGL_ERROR_LEVEL_EC3
- openGLRareError() Checks for errors only if build with ACGL_ERROR_LEVEL_EC3
For the last three there is also a variant like openGLCriticalErrorOccured() that does the same but returns a bool.
If an application for QT gets developed, you can define ACGL_COMPILE_WITH_QT and ACGL will use QT to support loading of more image formats.
Define ACGL_SPACE_NAVIGATOR_SUPPORT to add support for the SpaceNavigator. See ACGL/HardwareSupport/SpaceNavPollInterface.hh for details of what extra work has to be done to compile ACGL with support for the SpaceNavigator.
Define ACGL_COMPILE_WITH_GLFW to support joysticks. Without this define the Joystick classes will be compiled but will never return a button press.
To sum up: If nothing is set, ACGL will assume a OpenGL 3.2 core profile and some error checks in release / a lot of error checks in debug builds.