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

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:

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:

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.