src/gpu/GLES2/extensions/CHROMIUM/CHROMIUM_map_sub.txt

   1 Name
   2
   3     CHROMIUM_map_sub
   4
   5 Name Strings
   6
   7     GL_CHROMIUM_map_sub
   8
   9 Version
  10
  11     Last Modifed Date: July 22, 2011
  12
  13 Dependencies
  14
  15     OpenGL ES 2.0 is required.
  16
  17 Overview
  18
  19     This extension allows for more efficiently uploading of buffer or texture
  20     data through Chromium's OpenGL ES 2.0 implementation.
  21
  22     For security reasons Chromium accesses the GPU from a separate process. User
  23     processes are not allowed to access the GPU directly. This multi-process
  24     architechure has the advantage that GPU operations can be secured and
  25     pipelined but it has the disadvantage that all data that is going to be
  26     passed to GPU must first be made available to the separate GPU process.
  27
  28     Chromium's OpenGL ES 2.0 implementation hides this issue when using the
  29     standard OpenGL functions BufferData, BufferSubData, TexImage2D, and
  30     TexSubImage2D by first copying the user's data to shared memory and then
  31     telling the GPU process to use that shared memory to upload the data.
  32
  33     This extension helps avoid that extra copy from user memory to shared memory
  34     in a safe and secure manner.
  35
  36 Issues
  37
  38     This extension was designed for only 2 common use cases.
  39
  40     #1) Dynamic textures. A good example would be a video player that needs to
  41     upload video into a texture.
  42
  43     #2) CPU based skinning.
  44
  45     The common feature of these 2 use cases is the size of the texture in the
  46     first case and the size of the buffer in the second case do not change
  47     often. The implemenation of this extension is currently designed to never
  48     free shared memory and re-use previously allocated shared memory that is no
  49     longer in use.
  50
  51     This design fits the 2 use cases above but it does not fit uploading lots of
  52     arbitrarily sized pieces of data and so, at least in it's current
  53     implemenation it should really be only used for cases similar to those
  54     described above.
  55
  56 New Tokens
  57
  58     None
  59
  60 New Procedures and Functions
  61
  62     void* MapBufferSubDataCHROMIUM (GLuint target, GLintptr offset,
  63                                     GLsizeiptr size, GLenum access)
  64
  65     Returns a pointer to shared memory of the requested <size> or NULL if the
  66     request can not be honoured.
  67
  68     <target>, <offset> and <size> use the exact same parameters as
  69     BufferSubData. <access> must be WRITE_ONLY.
  70
  71     INVALID_ENUM is generated if <access> is not WRITE_ONLY
  72
  73     INVALID_VALUE is generated if <offset> or <size> is negative
  74
  75     void  UnmapBufferSubDataCHROMIUM (const void* mem)
  76
  77     Calling this function effectively calls BufferSubData with the parameters
  78     that were specified when originally calling MapBufferSubData. Note that
  79     after calling UnmapBufferSubDataCHROMIUM the application should assume that
  80     the memory pointed do by <mem> is off limits and is no longer writable by
  81     the application. Writing to it after calling UnmapBufferSubDataCHROMIUM will
  82     produce undefined results. No security issues exist because of this but
  83     which data makes it to the GPU will be unknown from the point of view of
  84     the user program.
  85
  86     <mem> is a pointer previously returned by calling MapBufferSubData and not
  87     yet unmapped.
  88
  89     INVALID_VALUE is generated if <mem> is not a value previously returned by
  90     MapBufferSubData or if it has already been passed to
  91     UnmapBufferSubDataCHROMIUM.
  92
  93     Other errors are the same errors that would be returned by BufferSubData.
  94
  95     void* MapTexSubImage2DCHROMIUM (GLenum target, GLint level,
  96                                     GLint xoffset, GLint yoffset,
  97                                     GLsizei width, GLsizei height,
  98                                     GLenum format, GLenum type, GLenum access)
  99
 100     Returns a pointer to shared memory that matches the image rectangle
 101     described by <width>, <height>, <format>, <type> and the current PixelStorei
 102     UNPACK_ALIGNMENT setting or NULL if the request can not be honoured.
 103
 104     So for example, a width 3, height 4, format RGB, type UNSIGNED_BYTE,
 105     UNPACK_ALIGNMENT 4 would return a pointer to a piece of memory 45 bytes
 106     in size. Width 3 at RGB is 9 bytes. Padded to an UNPACK_ALIGNMENT of 4 means
 107     12 bytes per row. The last row is not padded.
 108
 109     <target>, <level>, <xoffset>, <yoffset>, <width>, <height>, <format>, and
 110     <type> use the exact same parameters as TexSubImage2D. <access> must be
 111     WRITE_ONLY.
 112
 113     INVALID_ENUM is generated if <access> is not WRITE_ONLY
 114
 115     INVALID_VALUE is generated if <xoffset>, <yoffset>, <width>, <height> or
 116     <level> is negative
 117
 118     void  UnmapTexSubImage2DCHROMIUM (const void* mem)
 119
 120     Calling this function effectively calls TexSubImage2D with the parameters
 121     that were specified when originally calling MapTexSubImage2D. Note that
 122     after calling UnmapTexSubImage2DCHROMIUM the application should assume that
 123     the memory pointed do by <mem> is off limits and is no longer writable by
 124     the application. Writing to it after calling UnmapTexSubImage2DCHROMIUM will
 125     produce undefined results. No security issues exist because of this but
 126     which data makes it to the GPU will be unknown from the point of view of the
 127     user program.
 128
 129     <mem> is a pointer previously returned by calling MapTexSubImage2D and not
 130     yet unmapped.
 131
 132     INVALID_VALUE is generated if <mem> is not a value previously returned by
 133     MapTexSubImage2D or if it has already been passed to
 134     UnmapTexSubImage2DCHROMIUM.
 135
 136     Other errors are the same errors that would be returned by TexSubImage2D.
 137
 138 Errors
 139
 140     None.
 141
 142 New State
 143
 144     None.
 145
 146 Revision History
 147
 148     7/22/2011    Documented the extension