Extensions
Prev | Chapter 3. User's Guide | Next

## Extensions

PyOpenGL includes support for many GL, GLU and WGL extensions. These extensions are implemented as sub-modules of the `GL`, `GLU` or `WGL` package. For example, the `GL_ARB_multitexture` extension would be implemented in the module `GL.ARB.multitexture`. For every extension that PyOpenGL supports the corresponding module will exist regardless of whether or not that extension is implemented by the user's OpenGL library. A placeholder module will also exist even if the extension defines no new tokens or functions. If the extension is not supported by the current context than any attempt to use that extension will throw a `GLerror` exception with a code of `GL_INVALID_OPERATION`.

Each OpenGL implementation has its' own method for linking to OpenGL extensions. These methods vary from dynamic linking to static linking and even some dynamic/static combinations. Regardless of which case applies to a specific implementation of OpenGL, one still needs to verify that a particular extension is supported before attempting to use any functions or tokens that it declares. This is usually done by calling `glGetString(GL_EXTENSIONS)` and looking for extension name in the returned string.

Extensions are potentially context dependent, which means that an extension supported by one OpenGL context may not be supported by another. This means that verification that extension is supported and loading of the extension procedure addresses (if the OpenGL extension mechanism is dynamic) needs to be done for each context that intends to use a particular extension. PyOpenGL simplifies this somewhat by providing a single initialization function for each extension which does the following:

1. verify the extension is supported by the current context
2. load all procedure addresses for extension if needed
3. return a boolean indicating success of the previous steps

The naming scheme of the this initialization is designed to be consistent with the naming scheme used with OpenGL extensions. For instance, here is a function which takes an extension name and returns the initialization function name:

    def init_name(extension_name):
        parts = string.split(extension_name, '_')
        return string.join([string.lower(parts[0]), 'Init'] +
                           map(string.capitalize, parts[2:]) +
                           [parts[1]], '')

    >>> init_name('GL_ARB_multitexture')
    'glInitMultitextureARB'

    >>> init_name('GLU_SGI_filter4_parameters')
    'gluInitFilter4ParametersSGI'

As an example of extension usage, here is a GLUT program that needs the GL_ARB_multitexture extension:

    from OpenGL.GLUT import *
    from OpenGL.GL.ARB.multitexture import *
    import sys

    # initialize GLUT
    argv = glutInit(sys.argv)

    # create a window, needs to be done before glInitMultitextureARB
    glutCreateWindow('foo')

    # see if GL_ARB_multitexture is supported
    if not glInitMultitextureARB():
        # it's not supported...panic!
        print "Help, I'm lost without GL_ARB_multitexture!"
        sys.exit(1)

    # do something with it...

It is important to note that the initialization function for an extension must be called by each context that intends to use that extension. Failure to do so will result in a `GL.GLerror` with a code of `GL_INVALID_OPERATION` even if the extension is actually supported by that context.

Prev | Home | Next
`GLE` | Up | Writing Portable Code