gpu/GLES2/extensions/CHROMIUM/CHROMIUM_map_sub.txt

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