# Adding OpenGL Extensions to Chromium

In order to use particular OpenGL extensions in your OpenGL application, Chromium must also implement those extensions. This page describes how OpenGL extensions are implemented in Chromium and how to add new ones.

## Compile-time extension support

The include/cr_versions.h file defines a preprocessor token for each extension Chromium supports. For example:

#define CR_ARB_multitexture 1
#define CR_ARB_texture_cube_map 1
#define CR_EXT_blend_color 1
#define CR_EXT_blend_minmax 1
#define CR_EXT_blend_subtract 1

Most Chromium client programs are ordinary OpenGL applications and should use the `GL_`-prefixed tokens to test for extensions. However, Chromium-specific applications may use these tokens if needed.

Internally, Chromium uses these tokens to determine which OpenGL extensions should be enabled. If one wants to disable a particular extension in Chromium you can simply comment-out the appropriate `#define`.

When adding a new extension to chromium you should surround all the new code for that extension with `#ifdef CR_(extension name)` and `#endif`.

## Run-time extension support

At runtime, Chromium clients should use `glGetString(GL_EXTENSIONS)` to determine if extensions are supported.

Internally, Chromium will compute the extension string by examining the extensions supported by each back-end OpenGL implementation, finding the intersection, and propogating the list up through the SPU DAG to be sure the extensions are supported by all the Chromium SPUs.

Extension strings and OpenGL limits like maximum texture size and number of light sources for each SPU are stored in the mothership. When each SPU is initialized it reports its OpenGL extensions and limits to the mothership. Some SPUs, like the tilesort SPU, will query the mothership for its children/server SPU limits in order to determine its own limits.

## Adding new extensions

Here are the steps for adding a new extension to Chromium:

1. Add a new `CR_`* token to include/cr_versions.h.
2. Add a new GLboolean field to the `CRExtensionState` structure in the include/state/cr_limits.h file.
3. Add new code in `crStateExtensionsInit` in spu/state_tracker/state_limits.c to initialize the new boolean. Update the extension strings in state_tracker/state_limits.c as well.
4. Implement the new code for the extension as needed throughout Chromium. Specifically, the packer, unpacker and state tracker are the major modules which need updating. The best advice here is to look at existing extensions for ideas.
5. Extensions which only add new tokens to existing functions are easiest to implement. Often, only the state tracker needs to be updated.
6. Extensions which add new OpenGL functions are more work. The file glapi_parser/APIspec.txt defines all the OpenGL API functions (entry points). New extension functions should be added to this file, following the example of others. Read the information at the top of the file first.
7. The code for new extensions should be surrounded by `#ifdef CR_(extension_name)` and `#endif` so that it can be disabled if desired. See the `GL_TEXTURE_CUBE_MAP_ARB` clause in `__enableSet()` in spu/state_tracker/state_enable.c for an example.

## Application-only extensions

A short-cut to adding new extensions is to implment them for the application-side only. This means that the extension can only be used by SPUs running on the application node (such as the render SPU or readback SPU when using a sort-last configuration). An examples of an application-only extension is GL_NV_fence.

Basically, only the OpenGL API dispatcher needs to be updated. The extension should be added to the `__stateAppOnlyExtensions` string in state_tracker/state_limits.c.