Glatter

Overview

Glatter is an OpenGL loading library, with support for GL, GLES, GLU, EGL, GLX, WGL. In addition to extension loading, it facilitates logging and error checking.

Usage

Glatter may be used either as a header-only library, or it could alternatively be compiled into the project. Header-only usage is only available in C++, and may be enabled by defining GLATTER_HEADER_ONLY. Alternatively, src/glatter.c may be compiled into the project.

Glatter requires that the main header glatter.h is included, wherever its functionality is meant to be used. As it pulls its own API headers, the system's API headers should not be included.

There are two Glatter headers files which may be modified by the user, to customize the behaviour of the library, if required:

• glatter_config.h: It contains a set of macro declarations, that mostly enable or disable parts of the library's functionality.
• glatter_platform_headers.h: This is where OpenGL platforms are defined and their corresponding headers included. Changing this file will require that the headers are re-generated, by running glatter.py.

Glatter does not require explicit loading or initialization calls, and its startup cost is minimal.

Checking for extensions

Support for extensions in the current context can be queried as follows:

.. code-block:: c

    if (glatter_GL_ARB_name_of_extension) {
        // do stuff...
    }

The first extension support query in the program, will trigger an initialization call, with negligible overhead.

Tracing calls, checking errors

For error checking, the extensions ARB_debug_output and KHR_debug offer similar functionality, when GL_DEBUG_OUTPUT_SYNCHRONOUS is enabled. However, besides implementation support, they require a debug context, i.e. {GLX|WGL}_CONTEXT_DEBUG_BIT would have to be specified in the attribute list when calling {GLX|WGL}_ARB_create_context.

Glatter on the other hand, performs this task by wrapping all library calls inside debug versions of each call. There are two modes of debug operation, which can be switched on and off independently:

1. Logging (tracing) every OpenGL call, which can be enabled by defining GLATTER_LOG_CALLS in the configuration header
2. Logging only the errors produced by API calls, which may be enabled by defining GLATTER_LOG_ERRORS. This is enabled by default, when NDEBUG is not defined.

Traces of calls with GLenum arguments, are shown with their arguments converted to readable strings.

Here is a pseudo-example, of legacy OpenGL code drawing something, traced with GLATTER_LOG_CALLS:

.. code-block:: c

GLboolean r = glIsEnabled(GL_COLOR_MATERIAL);
glBegin(GL_QUAD_STRIP);
// ...
glEnd();

For the above, Glatter could produce:

.. code::

GLATTER: in 'c:\repositories\glatter\example\glatter\wglgears.cpp'(133):
GLATTER: glIsEnabled(GL_COLOR_MATERIAL)
GLATTER: returned 0
GLATTER: in 'c:\repositories\glatter\example\glatter\wglgears.cpp'(134):
GLATTER: glBegin(GL_QUAD_STRIP)
GLATTER: in 'c:\repositories\glatter\example\glatter\wglgears.cpp'(145):
GLATTER: glEnd()

Let's now introduce an error, by passing an invalid enumerator in the glIsEnabled call:

.. code-block:: c

GLboolean r = glIsEnabled(GL_FRAMEBUFFER_RENDERABLE);

In this case, Glatter could produce:

.. code::

GLATTER: in 'c:\repositories\glatter\example\glatter\wglgears.cpp'(133):
GLATTER: glIsEnabled(GL_FRAMEBUFFER_RENDERABLE)
GLATTER: returned 0
GLATTER: in 'c:\repositories\glatter\example\glatter\wglgears.cpp'(133):
GLATTER: OpenGL call produced GL_INVALID_ENUM error.

Header generation

Glatter's headers work supplementary to the API headers they operate on. They are generated by a python script, which directly parses the API's headers, to produce its own. A standard set of pre-generated headers is already supplied, which can be used on a fairly broad set of platforms. If needed, new custom headers for additional platforms can be generated by the python script. This can be done by following the steps below:

• place the API's headers under include/glatter/headers
• define the corresponding platform header set in glatter_platform_headers.h.
• invoke the python script (include/glatter/glatter.py)

Its generated output headers will be written under include/glatter/platforms

License

The source code of the library is licensed under the Simplified BSD License.