gpu/GLES2/extensions/CHROMIUM/CHROMIUM_texture_mailbox.txt

   1 Name
   2
   3     CHROMIUM_texture_mailbox
   4
   5 Name Strings
   6
   7     GL_CHROMIUM_texture_mailbox
   8
   9 Version
  10
  11     Last Modifed Date: June 2, 2014
  12
  13 Dependencies
  14
  15     OpenGL ES 2.0 is required.
  16
  17 Overview
  18
  19     This extension defines a way of sharing texture image data between texture
  20     objects in different contexts where the contexts would not normally share
  21     texture resources. Five new functions are exported. glGenMailboxCHROMIUM
  22     generates a name that can be used to identify texture image data outside
  23     the scope of a context group. glProduceMailboxCHROMIUM and
  24     glProduceTextureDirectCHROMIUM associate a texture object with a global
  25     mailbox name. glConsumeMailboxCHROMIUM and glCreateAndConsumeTextureCHROMIUM
  26     associate the texture object referenced by a mailbox name to a texture name.
  27
  28 New Procedures and Functions
  29
  30     void glGenMailboxCHROMIUM (GLbyte *mailbox)
  31
  32     Generates a unique name identifying a mailbox. The name is generated using
  33     a cryptographic random number generator and is intended to be difficult to
  34     guess. The scope of the name is implementation specific, for example it
  35     might not span multiple displays.
  36
  37     <mailbox> returns a GL_MAILBOX_SIZE_CHROMIUM byte sized name
  38
  39
  40     void glProduceTextureCHROMIUM (GLenum target, const GLbyte *mailbox)
  41
  42     Associates the currently bound texture object with the mailbox name. A
  43     given texture object can be associated with several mailbox names. If a
  44     mailbox name was previously associated with a texture object, that
  45     previous association is broken. The currently bound texture object is not
  46     modified by the operation.
  47
  48     If glProduceTextureCHROMIUM generates an error, the mailbox name keeps its
  49     current association, if any.
  50
  51     The mailbox does not keep a reference to the texture object. When the
  52     texture object is destroyed (deleted from all context groups, and unbound
  53     from all texture units and framebuffer attachments), the mailbox is
  54     disassociated from the texture object.
  55
  56     <target> uses the same parameters as TexImage2D.
  57
  58     <mailbox> identifies a GL_MAILBOX_SIZE_CHROMIUM byte sized name returned by
  59     glGenMailboxCHROMIUM.
  60
  61     INVALID_OPERATION is generated if <target> is not a valid target.
  62
  63     INVALID_OPERATION is generated if <mailbox> is invalid.
  64
  65
  66     void glProduceTextureDirectCHROMIUM (GLuint texture, GLenum target,
  67         const GLbyte *mailbox)
  68
  69     Associates the specified texture object with the mailbox name. Performs
  70     identically to glProduceTextureCHROMIUM except that the texture specified by
  71     <texture> is used instead of the currently bound texture. This operation
  72     does not change the texture bindings or alter the bound texture in any way.
  73
  74     <texture> Specifies the name of a texture.
  75
  76
  77     void glConsumeTextureCHROMIUM (GLenum target, const GLbyte *mailbox)
  78
  79     <target> uses the same parameters as TexImage2D.
  80
  81     <mailbox> identifies a GL_MAILBOX_SIZE_CHROMIUM byte sized name returned by
  82     glGenMailboxCHROMIUM.
  83
  84     Deletes the currently bound texture object, and redefines its texture name
  85     to point to the texture object associated with the mailbox name. All the
  86     contexts that have consumed the texture object, as well as produced it share
  87     the texture object, as if the contexts were part of the share group. The
  88     texture object is deleted once all contexts have deleted the texture name
  89     associated with the texture object, and detached it from all framebuffer
  90     objects as well as texture unit bindings. See Appendix C of the OpenGL ES
  91     2.0 specification for details relative to visibility in one context of
  92     changes to the shared texture object in another context.
  93
  94     If glConsumeTextureCHROMIUM generates an error, the currently bound texture
  95     object is preserved.
  96
  97     INVALID_OPERATION is generated if <target> is not a valid target.
  98
  99     INVALID_OPERATION is generated if <mailbox> is invalid.
 100
 101     INVALID_OPERATION is generated if <mailbox> is not associated with a texture
 102     object.
 103
 104     INVALID_OPERATION is generated if the texture object associated with
 105     <mailbox> has a different target than <target>.
 106
 107     INVALID_OPERATION is generated if the currently bound texture was previously
 108     deleted (for example in another context), hence doesn't have a name.
 109
 110
 111     GLuint glCreateAndConsumeTextureCHROMIUM (GLenum target,
 112         const GLbyte *mailbox)
 113
 114     Returns a new texture name associated with the given target pointing to the
 115     texture object associated with the mailbox name. Does not alter the texture
 116     bindings or alter the currently bound texture in any way. Otherwise performs
 117     identically to glConsumeTextureCHROMIUM.
 118
 119 New Tokens
 120
 121     The size of a mailbox name in bytes.
 122
 123         GL_MAILBOX_SIZE_CHROMIUM                             64
 124
 125 Errors
 126
 127     None.
 128
 129 New Tokens
 130
 131     None.
 132
 133 New State
 134
 135     None.
 136
 137 Revision History
 138
 139     4/25/2011    Documented the extension
 140     5/23/2013    Major revision in Produce/Consume semantics, introducing
 141                  sharing.
 142     6/02/2014    Added glProduceTextureDirectCHROMIUM and
 143                  glCreateAndConsumeTextureCHROMIUM definitions.