# Chromium Extensions to OpenGL

Chromium defines several extensions to the OpenGL API to provide special features. This section documents those extensions.

All Chromium extensions to OpenGL are identified by CR in the same way that SGI is used to identify SGI's OpenGL extensions.

At compile time the application should use `#ifdef extension_name / #endif` around Chromium-related code so that it'll compile when the extension is not defined.

At runtime the application should call `glGetString(GL_EXTENSIONS)` to see if the particular extension is supported. Then the application should use `wglGetProcAddress()` or `glXGetProcAddress()` to obtain a pointer to any extension functions that are needed.

The following extensions are available.

- GL_CR_state_parameter
- GL_CR_cursor_position
- GL_CR_bounding_box
- GL_CR_print_string
- GL_CR_tilesort_info
- GL_CR_window_size
- GL_CR_readback_barrier_size
- GL_CR_tile_info
- GL_CR_synchronization
- GL_CR_server_id_sharing
- GL_CR_server_matrix

## GL_CR_state_parameter

This extension adds three new functions to OpenGL. By itself, this extension provides no new features. Instead, other Chromium extensions are layered on top of this one.

glChromiumParameteriCR(GLenum target, GLint value)
  Set a Chromium parameter to an integer value.
  `target` specifies the parameter being set.
  `value` is the integer value.
  The error `GL_INVALID_ENUM` will be recorded if `target` is not a recognized value.
glChromiumParameterfCR(GLenum target, GLfloat value)
  Set a Chromium parameter to a floating point value.
  `target` specifies the parameter being set.
  `value` is the floating point value.
  The error `GL_INVALID_ENUM` will be recorded if `target` is not a recognized value.
glChromiumParametervCR(GLenum target, GLenum type, GLsizei count, const GLvoid *values)
  Specifies a vector of parameters to Chromium.
  `target` specifies the parameter being set.
  `type` specifies the datatype of the value(s) and may be `GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT or GL_DOUBLE`.
  `count` specifies the number of values in the vector and must be greater than or equal to one.
  `values` points to the beginning of the values vector.
  The error `GL_INVALID_ENUM` will be recorded if `target` or `type` is not a recognized value. The error `GL_INVALID_VALUE` will be recorded if `count` is less than one.
glGetChromiumParametervCR(GLenum target, GLuint index,GLenum type, GLsizei count, GLvoid *values)
  Queries Chromium state.
  `target` specifies the parameter to query.
  `index` specifies the element in an array of target values, if applicable.
  `type` specifies the datatype of the return value(s) and may be `GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT or GL_DOUBLE`.
  `count` specifies the number of values in the return values vector and must be greater than or equal to one.
  `values` points to the beginning of the return values vector.
  The error `GL_INVALID_ENUM` will be recorded if `target` or `type` is not a recognized value. The error `GL_INVALID_VALUE` will be recorded if `count` is less than one.

## GL_CR_cursor_position

This extension is used internally to Chromium to specify the position of the virtual cursor.

This extension requires the GL_CR_state_parameter extension.

The new token `CR_CURSOR_POSITION_CR` may be specified as the `target` parameter to `glChromiumParametervCR`. The `type` parameter must be `GL_INTEGER` and `count` must be 2. The `values` parameter points to an array of two integers with represents the cursor's (x,y) position.

## GL_CR_bounding_box

This extension is used to inform Chromium that subsequent geometry is bounded by a specific bounding box. This information can be used to improve the performance of the tile-sort, readback and binaryswap SPUs.

This extension requires the GL_CR_state_parameter extension.

New tokens accepted by the `target` parameter to `glChromiumParametervCR`:

GL_DEFAULT_BBOX_CR
  This turns off bounding box tracking. The `count` parameter should be zero. The `type` parameter value is not significant.
GL_SCREEN_BBOX_CR
  Specifies that subsequent OpenGL primitives will lie within a particular region of the window. `count` should be 8. `type` should be GL_FLOAT. `values` is an array of eight floating point values specifying the window-space bounding box: `[xmin, ymin, zmin, wmin, xmax, ymax, zmax, wmax]`.
GL_OBJECT_BBOX_CR
  Specifies that subsequent OpenGL primitives will lie within a particular object-space bounding box. `count` should be 6. `type` should be GL_FLOAT. `values` is an array of six floating point values specifying the object-space bounding box: `[xmin, ymin, zmin, xmax, ymax, zmax]`.

## GL_CR_print_string

This extension is allows the application to insert its own text into the output produced by the printSPU.

This extension requires the GL_CR_state_parameter extension.

The print SPU can emit user text by calling `glChromiumParametervCR(GL_PRINT_STRING_CR, GL_BYTE, count, string)` where `count` is the length of the text and `string` is the text.

XXX what about printing integers and floats?

XXX should we rely on count specifying the string length, or assume that it's a null-terminated string?

## GL_CR_tilesort_info

This extension is allows the application to query and set parameters of the tilesort SPU, if present.

This extension requires the GL_CR_state_parameter extension.

The query targets currently supported with the `glGetChromiumParametervCR` function are:

GL_MURAL_SIZE_CR
  Returns the width and height of the mural.
  `index` is ignored.
  `type` must be `GL_INT`.
  `count` must be 2.
  `values[0]` will return the width
  `values[1]` will return the height.
GL_NUM_SERVERS_CR
  Returns the number of tilesort servers.
  `index` is ignored.
  `type` must be `GL_INT`.
  `count` must be 1.
  `values[0]` will return the number of servers.
GL_VERTEX_COUNTS_CR
  Returns the number of vertices that have been sent to each of the tilesort servers.
  `index` is ignored.
  `type` must be `GL_INT`.
  `count` should be N, where N is the number of servers returned by querying `GL_NUM_SERVERS_CR`.
  `values[i]` will return the number of vertices sent to server i where 0 <= i < N.
GL_NUM_TILES_CR
  Returns the number of tils on a particular server.
  `index` specifies the server number.
  `type` must be `GL_INT`.
  `count` must be 1.
  `values[0]` will return the number of tiles on the given server.
GL_TILE_BOUNDS_CR
  Returns the bounds of a tile on a server.
  `index` encodes both the server number and tile number: index = server * 65536 + tile. Alternately, index = (server << 16) | tile.
  `type` must be `GL_INT`.
  `count` must be 4.
  `values[0]` will return x1 (left).
  `values[1]` will return y1 (bottom).
  `values[2]` will return x2 (right).
  `values[3]` will return y2 (top).

The vertex counters which are queried with `GL_VERTEX_COUNTS_CR` may be reset to zero with either of the following commands:

- `glChromiumParameteriCR(GL_RESET_VERTEX_COUNTERS_CR, 0);`
- `glChromiumParameterfCR(GL_RESET_VERTEX_COUNTERS_CR, 0.0);`

## GL_CR_window_size

This extension allows you to query the size of the currently bound rendering window. This extension requires the GL_CR_state_parameter extension.

New tokens accepted by the `target` parameter to `glGetChromiumParametervCR`:

GL_WINDOW_SIZE_CR
  The `count` parameter should be 2. The `type` parameter should be GL_INT. `values[0]` will be the window width. `values[1]` will be the window height.

## GL_CR_readback_barrier_size

This extension allows you to specify the number of clients which should synchronize on barriers within the readback SPU. This does not set the barrier size for the application's barriers. This extension requires the GL_CR_state_parameter extension.

See the threadtest.c file for an example.

New tokens accepted by the `target` parameter to `glChromiumParameteriCR`:

GL_WINDOW_SIZE_CR
  The `value` parameter indicates the barrier size.

## GL_CR_tile_info

This extension allows you to specify the tilesort parameters (number of tiles and their sizes) to the tilesort SPU and servers. This extension requires the GL_CR_state_parameter extension.

New tokens accepted by the `target` parameter to `glChromiumParametervCR`:

GL_TILE_INFO_CR
  The `count` parameter indicates the number of tile parameters, defined below.
The `type` parameter should be GL_INT. The `values` parameter defines an array of values as follows:

         values[0] = the server number
         values[1] = the overall mural width
         values[2] = the overall mural height
         values[3] = number of tiles
         values[4] = first tile x pos
         values[5] = first tile y pos
         values[6] = first tile width
         values[7] = first tile height
         values[8] = second tile x pos
         values[9] = second tile y pos
         values[10] = second tile width
         ...

  `count` should be 4 + 4 * (number of tiles).

## GL_CR_synchronization

This extension defines semaphore and barrier functions for synchronization.

glBarrierCreateCR(GLuint name, GLuint count)
  Create a barrier with the given name and count. The count indicates how many clients must meet at the barrier before it is released. If count is zero, the crserver will automatically set count to the number of clients currently connected to the server.
glBarrierDestroyCR(GLuint name)
  Destroys the named barrier.
glBarrierExecCR(GLuint name)
  Causes the caller to wait on the barrier until all peers meet the barrier.
glSemaphoreCreateCR(GLuint name, GLuint value)
  Creates a semaphore with the given name and value. Value indicates the initial semaphore value.
glSemaphoreDestroyCR(GLuint name)
  Destroys the named semaphore.
glSemaphorePCR(GLuint name)
  Decrements the named semaphore. This is the wait operation.
glSemaphoreVCR(GLuint name)
  Increments the named semaphore. This is the signal operation.

See the Writing a parallel application section for more information.

## GL_CR_server_id_sharing

This extension allows control over display list, texture object and vertex program ID management in network/server nodes. This is useful for parallel applications.

Specifically, it allows a program to set the values for the server configuration options: shared_display_lists, shared_texture_objects and shared_programs at runtime.

New tokens accepted by the `target` parameter to `glChromiumParameteriCR`:

GL_SHARED_DISPLAY_LISTS_CR
  The `value` parameter may be GL_TRUE or GL_FALSE to indicate whether display list IDs should be shared or unshared by all clients, respectively. This corresponds to the shared_display_lists network node configuration option. The default value is GL_TRUE.
GL_SHARED_TEXTURE_OBJECTS_CR
  The `value` parameter may be GL_TRUE or GL_FALSE to indicate whether texture object IDs should be shared or unshared by all clients, respectively. This corresponds to the shared_texture_objects network node configuration option. The default value is GL_TRUE.
GL_SHARED_PROGRAMS_CR
  The `value` parameter may be GL_TRUE or GL_FALSE to indicate whether vertex/fragment program IDs should be shared or unshared by all clients, respectively. This corresponds to the shared_programs network node configuration option. The default value is GL_TRUE.

In general, only parallel applications need to be concerned with these parameters. For example, if each of N instances of a parallel application create a display list named K and each application puts different OpenGL commands into the N instances of K, then GL_SHARED_DISPLAY_LISTS_CR should be set to GL_FALSE. The server will then distinguish between the N different lists named K.

## GL_CR_server_matrix

This extension allows an application to specify unique projection and viewing matrices for each server in a tilesort configuration. This is typically used to support a non-planar rendering environment, such as a CAVE. See the Non-planer tilesort section for details.

Three new tokens for `glChromiumParametervCR` are introduced:

- GL_SERVER_VIEW_MATRIX_CR
- GL_SERVER_PROJECTION_MATRIX_CR
- GL_SERVER_FRUSTUM_CR

To set the per-server view matrix, call:

       glChromiumParameterv(GL_SERVER_VIEW_MATRIX_CR, GL_FLOAT, 17, m)

where m[0] is the server index, starting at zero and m[1] through m[16] specify the sixteen elements of the view matrix.

To set the per-server projection matrix, call:

       glChromiumParametervCR(GL_SERVER_PROJECTION_MATRIX_CR, GL_FLOAT, 17, m)

where m[0] is the server index, starting at zero and m[1] through m[16] specify the sixteen elements of the projection matrix.

Alternately, the per-server projection matrix may be set by calling:

       glChromiumParametervCR(GL_SERVER_FRUSTUM_CR, GL_FLOAT, 7, m)

where m[0] is the server index, starting at zero and m[1] through m[7] are the left, right, bottom, top, near and far frustum parameters.

Note that these functions are meant to be used by applications which are running with a tilesort SPU.

Also note that if the application sets the view or projection matrices then the Python configuration file should not set the matrices via configuration options. I.e. either set the matrices in the configuration file or the application, but not both places.