Added documentation for GL_CHROMIUM_texture_mailbox GL extension.

gpu/GLES2/extensions/CHROMIUM/CHROMIUM_texture_mailbox.txt

+Name
+
+    CHROMIUM_texture_mailbox
+
+Name Strings
+
+    GL_CHROMIUM_texture_mailbox
+
+Version
+
+    Last Modifed Date: April 25, 2012
+
+Dependencies
+
+    OpenGL ES 2.0 is required.
+
+Overview
+
+    This extension defines a way of sharing texture image data between texture
+    objects in different contexts where the contexts need not normally share
+    texture resources. Three new functions are exported. glGenMailboxCHROMIUM
+    generates a name that can be used to identify texture image data outside
+    the scope of a context group. glProduceMailboxCHROMIUM moves texture image
+    data out of a texture object and into a mailbox. glConsumeMailboxCHROMIUM
+    moves texture image data out of a mailbox and into a texture object.
+

[Ken Russell (switch to Gerrit), 2012/04/26 00:37:19]

Should it be mentioned that there may be implementation-dependent restrictions
on which two contexts may reference the same mailbox? In our case, the contexts
have to be in the same renderer, which would be the same as having them in the
same process.

If you think this is implicit, then ignore this comment and the one at the
bottom about another possible error.

+New Procedures and Functions
+
+    void glGenMailboxCHROMIUM (char *mailbox)
+
+    Generates a unique name identifying a mailbox. The name is generated using
+    a cryptographic random number generator and is intended to be difficult to
+    guess.
+
+    <mailbox> returns a a 32 byte name
+
+
+    void glProduceTextureCHROMIUM (GLenum target, const char *mailbox)
+
+    Moves the image data of the currently bound texture object into the mailbox.
+    The texture object is redefined as though all its levels had been resized to
+    zero by zero and the texture object is therefore incomplete. If the mailbox
+    previously contained image data, the old image data is deleted. The state
+    of the bound texture object is not saved in the mailbox, only the image
+    data.
+
+    <target> uses the same parameters as TexImage2D.
+
+    <mailbox> identifies a 32 byte name returned by glGenMailboxCHROMIUM.
+
+    INVALID_OPERATION is generated if <target> is not a valid target.
+
+    INVALID_OPERATION is generated if the texture is attached to a framebuffer.
+
+    INVALID_OPERATION is generated if the texture is immutable.
+
+
+    void glConsumeTextureCHROMIUM (GLenum target, const char *mailbox)
+
+    <target> uses the same parameters as TexImage2D.
+
+    <mailbox> identifies a 32 byte name returned by glGenMailboxCHROMIUM.
+
+    Redefines the image data of the currently bound texture object with the
+    image data in the mailbox and empties the mailbox. The state of the
+    currently bound texture is not modified, only the image data. All levels
+    are redefined.
+
+    INVALID_OPERATION is generated if <target> is not a valid target.
+
+    INVALID_OPERATION is generated if <mailbox> is emopty.

[Ken Russell (switch to Gerrit), 2012/04/26 00:37:19]

typo: empty

+
+    INVALID_OPERATION is generated if the texture is attached to a framebuffer.
+
+    INVALID_OPERATION is generated if the texture is immutable.
+
+    INVALID_OPERATION is generated if the image data is invalid in the current
+    context.

[Ken Russell (switch to Gerrit), 2012/04/26 00:37:19]

Any error if the mailbox isn't referenceable from this context? See above.

+
+Errors
+
+    None.
+
+New Tokens
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    4/25/2011    Documented the extension