1Name 2 3 NOK_texture_from_pixmap 4 5Name Strings 6 7 EGL_NOK_texture_from_pixmap 8 9Notice 10 11 Copyright Nokia, 2009. 12 13Contributors 14 15 16Contact 17 18 Roland Scheidegger, Tungsten Graphics, sroland@tungstengraphics.com 19 20Status 21 22 Shipping on N900 23 24Version 25 26 0.2 (13 Nov 2009) 27 28Number 29 30 EGL Extension #14 31 32Dependencies 33 34 EGL 1.1 is required. 35 Written against wording of EGL 1.4 specification. 36 OpenGL ES 2.0 is required. 37 GL_OES_texture_npot affects the definition of this extension. 38 39Overview 40 41 This extension allows a color buffer to be used for both rendering and 42 texturing. 43 44 EGL allows the use of color buffers of pbuffer drawables for texturing, 45 this extension extends this to allow the use of color buffers of pixmaps 46 too. 47 Other types of drawables could be supported by future extensions layered 48 on top of this extension, though only windows are really left which 49 are problematic. 50 51 The functionality of this extension is similar to WGL_ARB_render_texture 52 which was incorporated into EGL 1.1. 53 However, the purpose of this extension is not to provide 54 "render to texture" like functionality but rather the ability to bind 55 existing native drawables (for instance X pixmaps) to a texture. Though, 56 there is nothing that prohibits it from being used for "render to 57 texture". 58 59 - Windows are problematic as they can change size and therefore are not 60 supported by this extension. 61 62 - Only a color buffer of a EGL pixmap created using an EGLConfig with 63 attribute EGL_BIND_TO_TEXTURE_RGB or EGL_BIND_TO_TEXTURE_RGBA 64 set to TRUE can be bound as a texture. 65 66 - The texture internal format is determined when the color buffer 67 is associated with the texture, guaranteeing that the color 68 buffer format is equivalent to the texture internal format. 69 70 - A client can create a complete set of mipmap images. 71 72 73IP Status 74 75 There are no known IP issues. 76 77Issues 78 79 1. What should this extension be called? 80 81 EGL_EXT_texture_from_pixmap seemed most appropriate, but eventually 82 was changed to EGL_NOK_texture_from_pixmap since it's unknown if other 83 vendors are interested in implementing this. Even though it builds 84 on top of the EGL render_to_texture functionality and thus the 85 specifiation wording is quite different to the GLX version, keep the 86 name from the GLX version (except the vendor prefix) since the intention 87 is the same. Layering of future extensions on top of this extension for 88 using other type of drawables as textures follows the same conventions 89 as vertex/pixel buffer objects and vertex/fragment programs. 90 91 92 2. What should the default value for EGL_TEXTURE_TARGET be? Should 93 users be required to set this value if EGL_TEXTURE_FORMAT is not 94 EGL_TEXTURE_FORMAT_NONE ? 95 96 Unlike in OpenGL, in OES there is no difference between pot and npot 97 sized textures as far as the texture target is concerned, so 98 for all sizes EGL_TEXTURE_2D will be used for all pixmap sizes. 99 npot texture sizes (with reduced functionality) are only available 100 in OES 2.0 hence this version is required. While in theory it would be 101 possible to support this in OES 1.0 if pixmaps are restricted to power 102 of two sizes, it seems for all practical uses of this extension pixmap 103 sizes will be arbitrary. 104 105 106 3. Should users be required to re-bind the drawable to a texture after 107 the drawable has been rendered to? 108 109 It is difficult to define what the contents of the texture would be if 110 we don't require this. Also, requiring this would allow implementations 111 to perform an implicit copy at this point if they could not support 112 texturing directly out of renderable memory. 113 114 The problem with defining the contents of the texture after rendering 115 has occured to the associated drawable is that there is no way to 116 synchronize the use of the buffer as a source and as a destination. 117 Direct OpenGL rendering is not necessarily done in the same command 118 stream as X rendering. At the time the pixmap is used as the source 119 for a texturing operation, it could be in a state halfway through a 120 copyarea operation in which half of it is say, white, and half is the 121 result of the copyarea operation. How is this defined? Worse, some 122 other OpenGL application could be halfway through a frame of rendering 123 when the composite manager sources from it. The buffer might just 124 contain the results of a "glClear" operation at that point. 125 126 To gurantee tear-free rendering, a composite manager (in this case 127 using X) would run as follows: 128 129 -receive request for compositing: 130 XGrabServer() 131 eglWaitNative() or XSync() 132 eglBindTexImage() 133 134 <Do rendering/compositing> 135 136 eglReleaseTexImage() 137 XUngrabServer() 138 139 Apps that don't synchronize like this would get what's available, 140 and that may or may not be what they expect. 141 142 143 4. Rendering done by the window system may be y-inverted compared 144 to the standard OpenGL texture representation. More specifically: 145 the X Window system uses a coordinate system where the origin is in 146 the upper left; however, the GL uses a coordinate system where the 147 origin is in the lower left. Should we define the contents of the 148 texture as the y-inverted contents of the drawable? 149 150 X implementations may represent their drawables differently internally, 151 so y-inversion should be exposed as an EGLConfig attribute. 152 Applications will need to query this attribute and adjust their rendering 153 appropriately. 154 155 If a drawable is y-inverted and is bound to a texture, the contents of the 156 texture will be y-inverted with respect to the standard GL memory layout. 157 This means the contents of a pixmap of size (width, height) at pixmap 158 coordinate (x, y) will be at location (x, height-y-1) in the texture. 159 Applications will need to adjust their texture coordinates accordingly to 160 avoid drawing the texture contents upside down. 161 162 163 164 165New Procedures and Functions 166 167 None 168 169New Tokens 170 171 Accepted by the <Attribute> parameter of eglGetConfigAttrib and 172 the <attrib_list> parameter of eglChooseConfig: 173 174 EGL_Y_INVERTED_NOK 0x307F 175 176 177Additions to the OpenGL ES 2.0 Specification 178 179 None. 180 181 182Additions to the EGL Specification 183 184 Add to table 3.1, EGLConfig Attributes: 185 186 Attribute Type Notes 187 ------------------------------- ------- ----------------------------------- 188 EGL_Y_INVERTED_NOK boolean True if the drawable's framebuffer 189 is y-inverted. This can be used to 190 determine if y-inverted texture 191 coordinates need to be used when 192 texturing from this drawable when 193 it is bound to a texture target. 194 195 Additions to table 3.4, Default values and match criteria for EGLConfig attributes: 196 197 Attribute Default Selection Criteria Priority 198 ------------------------------- -------------------- ------------------ --------- 199 EGL_Y_INVERTED_NOK EGL_DONT_CARE Exact 200 201 Modifications to 3.4, "Configuration Management" 202 203 Modify 3rd last paragraph ("EGL BIND TO TEXTURE RGB and..."): 204 205 EGL BIND TO TEXTURE RGB and EGL BIND TO TEXTURE RGBA are booleans 206 indicating whether the color buffers of a pbuffer or a pixmap created with 207 the EGLConfig can be bound to a OpenGL ES RGB or RGBA texture respectively. 208 Currently only pbuffers or pixmaps can be bound as textures, so these 209 attributes may only be EGL TRUE if the value of the EGL SURFACE TYPE 210 attribute includes EGL PBUFFER BIT or EGL_PIXMAP_BIT. It is possible to 211 bind a RGBA visual to a RGB texture, in which case the values in the alpha 212 component of the visual are ignored when the color buffer is used as a RGB 213 texture. 214 215 Add after this: 216 217 EGL_Y_INVERTED_NOK is a boolean describing the memory layout used for 218 drawables created with the EGLConfig. The attribute is True if the 219 drawable's framebuffer will be y-inverted. This can be used to determine 220 if y-inverted texture coordinates need to be used when texturing from this 221 drawable when it is bound to a texture target. 222 223 Modifications to 3.5.4, "Creating Native Pixmap Rendering Surfaces" 224 225 Modify paragraph 4 of the description of eglCreatePixmapSurface: 226 227 <attrib_list> specifies a list of attributes for the pixmap. The list has 228 the same structure as described for eglChooseConfig. Attributes that can 229 be specified in <attrib_list> include EGL_TEXTURE_FORMAT, 230 EGL_TEXTURE_TARGET, EGL_MIPMAP_TEXTURE, EGL_VG_COLORSPACE and 231 EGL_VG_ALPHA_FORMAT. 232 EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET and EGL_MIPMAP_TEXTURE have the same 233 meaning and default values as when used with eglCreatePbufferSurface. 234 235 236 Modifications to section 3.6.1, "Binding a Surface to a OpenGL ES Texture" 237 238 Modify paragraph 2 of the description of eglBindTexImage: 239 240 The texture target, the texture format and the size of the texture 241 components are derived from attributes of the specified <surface>, which 242 must be a pbuffer or pixmap supporting one of the EGL_BIND_TO_TEXTURE_RGB 243 or EGL_BIND_TO_TEXTURE_RGBA attributes. 244 245 Modify paragraph 6 of the description of eglBindTexImage: 246 247 ...as though glFinish were called on the last context to which that surface 248 were bound. If <surface> is a pixmap, it also waits for all effects of 249 native drawing to complete. 250 251 Modify paragraph 7 of the description of eglBindTexImage: 252 253 After eglBindTexImage is called, the specified <surface> is no longer 254 available for reading or writing by client APIs. Any read operation, 255 such as glReadPixels or eglCopyBuffers, which reads values from any of the 256 surface’s color buffers or ancillary buffers will produce indeterminate 257 results. In addition, draw operations that are done to the surface before 258 its color buffer is released from the texture produce indeterminate 259 results. Specifically, if the surface is current to a context 260 and thread then rendering commands will be processed and the context state 261 will be updated, but the surface may or may not be written. 262 If the surface is a pixmap, it can still be accessed for reading or 263 writing by native rendering calls, however reading and writing will produce 264 indeterminate results and will leave the texture in an undefined state. It 265 is up to the application to implement any synchronization required. 266 eglSwapBuffers has no effect if it is called on a bound surface. 267 268 Modify paragraph 10 of the description of eglBindTexImage: 269 270 Texture mipmap levels are automatically generated when all of the following 271 conditions are met while calling eglBindTexImage: 272 273 - The EGL_MIPMAP_TEXTURE attribute of the pbuffer or pixmap being bound 274 is EGL_TRUE. 275 - The OpenGL ES texture parameter GL_GENERATE_MIPMAP is GL_TRUE for the 276 currently bound texture. 277 - The value of the EGL_MIPMAP_LEVEL attribute of the pbuffer or pixmap 278 being bound is equal to the value of the texture parameter 279 GL_TEXTURE_BASE_LEVEL. 280 281 282 Modifications to section 3.6.2, "Releasing a Surface from an OpenGL ES Texture" 283 284 Modify paragraph 1 of the description of eglReleaseTexImage: 285 286 ...The specified color buffer is released back to the surface. The surface 287 is made avalaible for reading and writing by client APIs when it no longer 288 has any color buffers bound as textures. 289 290 Modify paragraph 2 of the description of eglReleaseTexImage: 291 292 If the surface is a pixmap, the contents of the color buffer are 293 unaffected by eglReleaseTexImage. If the surface is a pbuffer, 294 the contents of the color buffer are undefined when it is first 295 released, in particular there is no guarantee that the texture 296 image is still present. In all cases, the contents of other 297 color buffers are unaffected by this call. ... 298 299 Modify paragraph 5 of the description of eglReleaseTexImage: 300 301 ...If <surface> is not a valid EGLSurface, or is not a bound pbuffer or 302 pixmap surface, then an EGL_BAD_SURFACE error is returned. 303 304 305 306Usage Examples 307 308(skipped for now) 309 310 311 312Version History 313 314 0. 12 Aug 2008 - RS 315 Initial version derived from GLX_EXT_texture_from_pixmap and EGL. 316 0.1 30 Sept 2008 - RS 317 Changed name from EXT to NOKIA. 318 Clarified / fixed wording wrt differences to pbuffers. 319 0.2 13 Nov 2009 - Sami Kyöstilä <sami.kyostila@nokia.com> 320 Changed extension and token names to comply with Nokia extension naming 321 scheme. Clarified interaction with native rendering. Formatting. 322