Document CHROMIUM's OpenGL ES 2.0 extensions

TEST=NONE
BUG=NONE

Review URL: http://codereview.chromium.org/7493008

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@94883 0039d316-1c4b-4281-b951-d872f2087c98

gpu/GLES2/extensions/CHROMIUM/CHROMIUM_flipy.txt

@@ -0,0 +1,45 @@
+Name
+
+    CHROMIUM_flipy
+
+Name Strings
+
+    GL_CHROMIUM_flipy
+
+Version
+
+    Last Modifed Date: July 22, 2011
+
+Dependencies
+
+    OpenGL ES 2.0 is required.
+
+Overview
+
+    This extension adds the ability to vertically flip texture image data when
+    calling TexImage2D and TexSubImage2D.
+
+Issues
+
+
+New Tokens
+
+    Accepted by the <param> parameter of PixelStorei:
+
+        UNPACK_FLIP_Y_CHROMIUM              0x9240
+
+New Procedures and Functions
+
+    None.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    7/22/2011    Documented the extension

gpu/GLES2/extensions/CHROMIUM/CHROMIUM_get_multiple.txt

@@ -0,0 +1,109 @@
+Name
+
+    CHROMIUM_get_multiple
+
+Name Strings
+
+    GL_CHROMIUM_get_multiple
+
+Version
+
+    Last Modifed Date: July 22, 2011
+
+Dependencies
+
+    OpenGL ES 2.0 is required.
+
+Overview
+
+    This extension adds the ability to query multiple state and program
+    information in a single call.
+
+Issues
+
+
+New Tokens
+
+    None
+
+New Procedures and Functions
+
+    void GetMultipleIntegervCHROMIUM (const GLenum* pnames, GLuint count,
+                                      GLint* results, GLsizeiptr size)
+
+    <pnames> points to an array of state enums that would normally be queried by
+    GetIntegerv. <count> is the number of pnames. <results> points memory large
+    enough to contain all the state being queried. <size> is the size of the
+    buffer pointed to be <results>
+
+    Example: <pnames> points to an array with VIEWPORT and MAX_TEXTURE_SIZE.
+    VIEWPORT returns 4 values, MAX_TEXTURE_SIZE returns 1 value. Therefore
+    results must point to a buffer of size 5 * sizeof(GLint) and size must be at
+    least 5 * sizeof(GLint)
+
+    INVALID_ENUM is generated if any of the pnames are not valid for GetIntegerv
+
+    INVALID_VALUE is generated if <size> does not equal the size needed for the
+    query
+
+    INVALID_VALUE is generated if the memory pointed to be <results> has not
+    been zeroed out.
+
+    void GetProgrmaInfoCHROMIUM (GLuint program, GLsizei bufsize,
+                                 GLsizei* size, void* info)
+
+    <program> is the program to query. <bufsize> is the size of the buffer to
+    hold the results. <size> is a pointer to a GLsizei to store the size needed
+    to hold the results. <info> is a pointer to memory to store the result.
+
+    To query the space needed for the results set <info> to NULL.
+
+    The format of the data that will be stored in the memory pointed to by
+    <info> is as follows.
+
+        struct ProgramInfoHeader {
+          uint32 link_status;  // same as GetProgramiv called with LINK_STATUS
+          uint32 num_attribs;  // the number of active attributes
+          uint32 num_uniforms;  // the number of active uniforms
+          ProgramInput inputs[num_attribs + num_uniforms];
+        }
+
+        // The data for one attrib or uniform from GetProgramInfoCHROMIUM.
+        struct ProgramInput {
+          uint32 type;             // The type (GL_VEC3, GL_SAMPLER_2D, etc.
+          int32 size;              // The size (size of array for uniforms)
+          uint32 location_offset;  // offset from ProgramInfoHeader to 'size'
+                                   // locations for uniforms, 1 for attribs.
+          uint32 name_offset;      // offset from ProgrmaInfoHeader to start of
+                                   // name.
+          uint32 name_length;      // length of the name.
+        };
+
+    It is important to note that for attribs, size is the size of the attrib and
+    location_offset points to a single location. For uniforms, size is the
+    number of array elements and location_offset points to an array of size
+    locations, one of each element of the array.
+
+    INVALID_VALUE is generated if <bufsize> is less than 0
+
+    INVALID_VALUE is generated if <size> is NULL
+
+    INVALID_OPERATION is returned if <size> is less than the size needed to hold
+    all the results.
+
+
+    NOTE: This function is not intended to be used directly. Chromium uses it
+    internally to cache data.
+
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    7/22/2011    Documented the extension

gpu/GLES2/extensions/CHROMIUM/CHROMIUM_map_sub.txt

@@ -0,0 +1,148 @@
+Name
+
+    CHROMIUM_map_sub
+
+Name Strings
+
+    GL_CHROMIUM_map_sub
+
+Version
+
+    Last Modifed Date: July 22, 2011
+
+Dependencies
+
+    OpenGL ES 2.0 is required.
+
+Overview
+
+    This extension allows for more efficiently uploading of buffer or texture
+    data through Chromium's OpenGL ES 2.0 implementation.
+
+    For security reasons Chromium accesses the GPU from a separate process. User
+    processes are not allowed to access the GPU directly. This multi-process
+    architechure has the advantage that GPU operations can be secured and
+    pipelined but it has the disadvantage that all data that is going to be
+    passed to GPU must first be made available to the separate GPU process.
+
+    Chromium's OpenGL ES 2.0 implementation hides this issue when using the
+    standard OpenGL functions BufferData, BufferSubData, TexImage2D, and
+    TexSubImage2D by first copying the user's data to shared memory and then
+    telling the GPU process to use that shared memory to upload the data.
+
+    This extension helps avoid that extra copy from user memory to shared memory
+    in a safe and secure manner.
+
+Issues
+
+    This extension was designed for only 2 common use cases.
+
+    #1) Dynamic textures. A good example would be a video player that needs to
+    upload video into a texture.
+
+    #2) CPU based skinning.
+
+    The common feature of these 2 use cases is the size of the texture in the
+    first case and the size of the buffer in the second case do not change
+    often. The implemenation of this extension is currently designed to never
+    free shared memory and re-use previously allocated shared memory that is no
+    longer in use.
+
+    This design fits the 2 use cases above but it does not fit uploading lots of
+    arbitrarily sized pieces of data and so, at least in it's current
+    implemenation it should really be only used for cases similar to those
+    described above.
+
+New Tokens
+
+    None
+
+New Procedures and Functions
+
+    void* MapBufferSubDataCHROMIUM (GLuint target, GLintptr offset,
+                                    GLsizeiptr size, GLenum access)
+
+    Returns a pointer to shared memory of the requested <size> or NULL if the
+    request can not be honoured.
+
+    <target>, <offset> and <size> use the exact same parameters as
+    BufferSubData. <access> must be WRITE_ONLY.
+
+    INVALID_ENUM is generated if <access> is not WRITE_ONLY
+
+    INVALID_VALUE is generated if <offset> or <size> is negative
+
+    void  UnmapBufferSubDataCHROMIUM (const void* mem)
+
+    Calling this function effectively calls BufferSubData with the parameters
+    that were specified when originally calling MapBufferSubData. Note that
+    after calling UnmapBufferSubDataCHROMIUM the application should assume that
+    the memory pointed do by <mem> is off limits and is no longer writable by
+    the application. Writing to it after calling UnmapBufferSubDataCHROMIUM will
+    produce undefined results. No security issues exist because of this but
+    which data makes it to the GPU will be unknown from the point of view of
+    the user program.
+
+    <mem> is a pointer previously returned by calling MapBufferSubData and not
+    yet unmapped.
+
+    INVALID_VALUE is generated if <mem> is not a value previously returned by
+    MapBufferSubData or if it has already been passed to
+    UnmapBufferSubDataCHROMIUM.
+
+    Other errors are the same errors that would be returned by BufferSubData.
+
+    void* MapTexSubImage2DCHROMIUM (GLenum target, GLint level,
+                                    GLint xoffset, GLint yoffset,
+                                    GLsizei width, GLsizei height,
+                                    GLenum format, GLenum type, GLenum access)
+
+    Returns a pointer to shared memory that matches the image rectangle
+    described by <width>, <height>, <format>, <type> and the current PixelStorei
+    UNPACK_ALIGNMENT setting or NULL if the request can not be honoured.
+
+    So for example, a width 3, height 4, format RGB, type UNSIGNED_BYTE,
+    UNPACK_ALIGNMENT 4 would return a pointer to a piece of memory 45 bytes
+    in size. Width 3 at RGB is 9 bytes. Padded to an UNPACK_ALIGNMENT of 4 means
+    12 bytes per row. The last row is not padded.
+
+    <target>, <level>, <xoffset>, <yoffset>, <width>, <height>, <format>, and
+    <type> use the exact same parameters as TexSubImage2D. <access> must be
+    WRITE_ONLY.
+
+    INVALID_ENUM is generated if <access> is not WRITE_ONLY
+
+    INVALID_VALUE is generated if <xoffset>, <yoffset>, <width>, <height> or
+    <level> is negative
+
+    void  UnmapTexSubImage2DCHROMIUM (const void* mem)
+
+    Calling this function effectively calls TexSubImage2D with the parameters
+    that were specified when originally calling MapTexSubImage2D. Note that
+    after calling UnmapTexSubImage2DCHROMIUM the application should assume that
+    the memory pointed do by <mem> is off limits and is no longer writable by
+    the application. Writing to it after calling UnmapTexSubImage2DCHROMIUM will
+    produce undefined results. No security issues exist because of this but
+    which data makes it to the GPU will be unknown from the point of view of the
+    user program.
+
+    <mem> is a pointer previously returned by calling MapTexSubImage2D and not
+    yet unmapped.
+
+    INVALID_VALUE is generated if <mem> is not a value previously returned by
+    MapTexSubImage2D or if it has already been passed to
+    UnmapTexSubImage2DCHROMIUM.
+
+    Other errors are the same errors that would be returned by TexSubImage2D.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    7/22/2011    Documented the extension

gpu/GLES2/extensions/CHROMIUM/CHROMIUM_request_extension.txt

@@ -0,0 +1,66 @@
+Name
+
+    CHROMIUM_request_extension
+
+Name Strings
+
+    GL_CHROMIUM_request_extension
+
+Version
+
+    Last Modifed Date: July 22, 2011
+
+Dependencies
+
+    OpenGL ES 2.0 is required.
+
+Overview
+
+    This extension is for WebGL only. In some implemenations of OpenGL ES 2.0,
+    in particular the Chromium implementation, it is possible to create an
+    OpenGL context and request that most extensions be disabled. From that
+    point, this extension allows extensions to then be selectively enabled.
+
+    WebGL requires the base OpenGL ES 2.0 with NO extensions. So for example,
+    if an OpenGL ES 2.0 implemention exposed the extension OES_texture_npot, the
+    WebGL implementation would have to make it appear as though that extension
+    does not exist. For Chromium WebGL OpenGL contexts, Chromium requests a
+    context with no extensions. It then queries which extensions exist. If
+    OES_texture_npot does NOT exist then WebGL can decide to not do the extra
+    work required to emulate it not existing.
+
+    Subsequently, if the user calls
+    WebGLRenderingContext.getExtension("WEBGL_texture_npot"), assuming such an
+    extension exists, the WebGL implementation can call this extension to turn
+    on OES_texture_npot. After calling RequestExtensionCHROMIUM you must call
+    GetString(GL_EXTENSIONS) in order to find out if the extension was actually
+    enabled.
+
+    Note: This extension really has no meaning outside of WebGL. By default, all
+    supported extensions are enabled.
+
+Issues
+
+
+New Tokens
+
+    None
+
+New Procedures and Functions
+
+    RequestExtensionCHROMIUM(const GLchar *extension)
+
+    <extension> is a null terminated string of the extension you wish to enable.
+    For example "OES_texture_npot".
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    7/22/2011    Documented the extension