GPU client side changes for GpuMemoryBuffers

gpu/GLES2/extensions/CHROMIUM/CHROMIUM_map_image.txt

+Name
+
+    CHROMIUM_map_image
+
+Name Strings
+
+    GL_CHROMIUM_map_image
+
+Version
+
+    Last Modifed Date: May 9, 2013
+
+Dependencies
+
+    OpenGL ES 2.0 is required.
+
+Overview
+
+    This extension allows for more efficiently uploading of buffer or texture

[no sievers, 2013/05/10 01:21:51]

nit: more efficient uploading.

buffer data too? Doesn't this only support textures/images?

[kaanb, 2013/05/13 23:00:36]

Done.

+    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.

[no sievers, 2013/05/10 01:21:51]

nit: I'm not sure if I'd detour so much here. 

And maybe also not say what copies exactly are avoided? Because it depends a bit
on the platform and implementation. You could just say 'it allows for the direct
manipulation of texture memory' or something like that.

[kaanb, 2013/05/13 23:00:36]

Done.

+
+    This extension helps avoid that extra copy from user memory to shared memory
+    in a safe and secure manner by allowing the application to directly allocate
+    and access GPU memory. After allocating the memory the client of this
+    interface can map the GPU buffer into the user memory and modify the pixels.
+
+Issues
+
+    The initial use of this extension was designed for the single process
+    mode of Chromium where OpenGL ES 2.0 and GPU implementations share the
+    same process. Some additions may be required to support the case where
+    OpenGL ES 2.0 and GPU implementations live in different processes.

[no sievers, 2013/05/10 01:21:51]

nit: Maybe also leave this out. Where the extension is not available it is
simply not advertised.

[kaanb, 2013/05/13 23:00:36]

Done.

+
+New Tokens
+
+    None
+
+New Procedures and Functions
+
+    GLuint CreateImageCHROMIUM (GLsizei width, GLsizei height)

[greggman, 2013/05/10 00:12:22]

no format? How do you know the format of the image

[kaanb, 2013/05/13 23:00:36]

Done.

+
+    Allocates GPU memory with width equal to <width> and height equal

[no sievers, 2013/05/10 01:21:51]

nit: 'allocates an image'?

[kaanb, 2013/05/13 23:00:36]

Done.

+    to <height>.
+
+    Returns a unique identifier for the allocated buffer that could be used

[no sievers, 2013/05/10 01:21:51]

nit: 'for the allocated image'

[kaanb, 2013/05/13 23:00:36]

Done.

+    in subsequent operations.
+
+    INVALID_VALUE is generated if <width> or <height> is nonpositive.
+
+    void DestroyImageCHROMIUM (GLuint image_id)
+
+    Frees GPU memory previously allocated by a call to CreateImageCHROMIUM.

[no sievers, 2013/05/10 01:21:51]

nit: 'Free the image'

[kaanb, 2013/05/13 23:00:36]

Done.

+
+    INVALID_OPERATION is generated if <image_id> is not a valid image id.
+
+    void* MapImageCHROMIUM (GLuint image_id, GLenum access)
+
+    Returns a pointer to in the user memory for the application to access

[no sievers, 2013/05/10 01:21:51]

nit: I find that sentence a bit hard to read :)

[kaanb, 2013/05/13 23:00:36]

Done.

+    the image in an access mode specified by <access>.
+
+    INVALID_OPERATION is generated if <image_id> is not a valid image id.
+
+    INVALID_OPERATION is generated if the image was already mapped by a previous
+    call to this method.
+
+    INVALID_ENUM is generated if <access> is not WRITE_ONLY and not READ_ONLY.

[no sievers, 2013/05/10 01:21:51]

What about READ_WRITE?

[kaanb, 2013/05/13 23:00:36]

Done.

+
+    GLboolean UnmapImageCHROMIUM (GLuint image_id)
+
+    Makes the changes made to the image after calling MapImageCHROMIUM
+    permanent. Returns true iff the operation was successful.

[greggman, 2013/05/10 00:12:22]

s/iff/if/

[no sievers, 2013/05/10 01:21:51]

Hmm, does it really make anything permanent? There is no implicit
synchronization, so the changes possibly take effect when you touch the memory
already. It really just removes the mapping, right?
Might give people the wrong impression about synchronization otherwise.

[kaanb, 2013/05/13 23:00:36]

Done.

[kaanb, 2013/05/13 23:00:36]

Done.

+
+    Note that after calling UnmapImageCHROMIUM the application should assume
+    that the memory returned by MapImageCHROMIUM is off limits and is no longer
+    accessible by the application. Accessing it after calling
+    UnmapImageCHROMIUM will produce undefined results.
+
+    INVALID_OPERATION is generated if <image_id> is not a valid image id.
+
+    INVALID_OPERATION is generated if the image was not already mapped by a
+    previous call to MapImageCHROMIUM.
+
+    void GetImageParameterivCHROMIUM(GLuint image_id, GLenum pname,
+                                     GLint* params)
+
+    Sets <params> to the integer value of the parameter specified by <pname>
+    for the image specified by <image_id>. <params> is expected to be
+    suitably initialized before calling this method.

[no sievers, 2013/05/10 01:21:51]

nit: suitably initialized? maybe you are trying to indicate that *params will
not be set if image_id or pname was invalid?

[kaanb, 2013/05/13 23:00:36]

Done.

+
+    INVALID_OPERATION is generated if <image_id> is not a valid image id.
+
+    INVALID_ENUM is generated if <pname> is not IMAGE_ROWBYTES.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    5/9/2013    Documented the extension