Name NOK_texture_from_pixmap Name Strings EGL_NOK_texture_from_pixmap Notice Copyright Nokia, 2009. Contributors Contact Roland Scheidegger, Tungsten Graphics, sroland@tungstengraphics.com Status Shipping on N900 Version 0.2 (13 Nov 2009) Number EGL Extension #14 Dependencies EGL 1.1 is required. Written against wording of EGL 1.4 specification. OpenGL ES 2.0 is required. GL_OES_texture_npot affects the definition of this extension. Overview This extension allows a color buffer to be used for both rendering and texturing. EGL allows the use of color buffers of pbuffer drawables for texturing, this extension extends this to allow the use of color buffers of pixmaps too. Other types of drawables could be supported by future extensions layered on top of this extension, though only windows are really left which are problematic. The functionality of this extension is similar to WGL_ARB_render_texture which was incorporated into EGL 1.1. However, the purpose of this extension is not to provide "render to texture" like functionality but rather the ability to bind existing native drawables (for instance X pixmaps) to a texture. Though, there is nothing that prohibits it from being used for "render to texture". - Windows are problematic as they can change size and therefore are not supported by this extension. - Only a color buffer of a EGL pixmap created using an EGLConfig with attribute EGL_BIND_TO_TEXTURE_RGB or EGL_BIND_TO_TEXTURE_RGBA set to TRUE can be bound as a texture. - The texture internal format is determined when the color buffer is associated with the texture, guaranteeing that the color buffer format is equivalent to the texture internal format. - A client can create a complete set of mipmap images. IP Status There are no known IP issues. Issues 1. What should this extension be called? EGL_EXT_texture_from_pixmap seemed most appropriate, but eventually was changed to EGL_NOK_texture_from_pixmap since it's unknown if other vendors are interested in implementing this. Even though it builds on top of the EGL render_to_texture functionality and thus the specifiation wording is quite different to the GLX version, keep the name from the GLX version (except the vendor prefix) since the intention is the same. Layering of future extensions on top of this extension for using other type of drawables as textures follows the same conventions as vertex/pixel buffer objects and vertex/fragment programs. 2. What should the default value for EGL_TEXTURE_TARGET be? Should users be required to set this value if EGL_TEXTURE_FORMAT is not EGL_TEXTURE_FORMAT_NONE ? Unlike in OpenGL, in OES there is no difference between pot and npot sized textures as far as the texture target is concerned, so for all sizes EGL_TEXTURE_2D will be used for all pixmap sizes. npot texture sizes (with reduced functionality) are only available in OES 2.0 hence this version is required. While in theory it would be possible to support this in OES 1.0 if pixmaps are restricted to power of two sizes, it seems for all practical uses of this extension pixmap sizes will be arbitrary. 3. Should users be required to re-bind the drawable to a texture after the drawable has been rendered to? It is difficult to define what the contents of the texture would be if we don't require this. Also, requiring this would allow implementations to perform an implicit copy at this point if they could not support texturing directly out of renderable memory. The problem with defining the contents of the texture after rendering has occured to the associated drawable is that there is no way to synchronize the use of the buffer as a source and as a destination. Direct OpenGL rendering is not necessarily done in the same command stream as X rendering. At the time the pixmap is used as the source for a texturing operation, it could be in a state halfway through a copyarea operation in which half of it is say, white, and half is the result of the copyarea operation. How is this defined? Worse, some other OpenGL application could be halfway through a frame of rendering when the composite manager sources from it. The buffer might just contain the results of a "glClear" operation at that point. To gurantee tear-free rendering, a composite manager (in this case using X) would run as follows: -receive request for compositing: XGrabServer() eglWaitNative() or XSync() eglBindTexImage() eglReleaseTexImage() XUngrabServer() Apps that don't synchronize like this would get what's available, and that may or may not be what they expect. 4. Rendering done by the window system may be y-inverted compared to the standard OpenGL texture representation. More specifically: the X Window system uses a coordinate system where the origin is in the upper left; however, the GL uses a coordinate system where the origin is in the lower left. Should we define the contents of the texture as the y-inverted contents of the drawable? X implementations may represent their drawables differently internally, so y-inversion should be exposed as an EGLConfig attribute. Applications will need to query this attribute and adjust their rendering appropriately. If a drawable is y-inverted and is bound to a texture, the contents of the texture will be y-inverted with respect to the standard GL memory layout. This means the contents of a pixmap of size (width, height) at pixmap coordinate (x, y) will be at location (x, height-y-1) in the texture. Applications will need to adjust their texture coordinates accordingly to avoid drawing the texture contents upside down. New Procedures and Functions None New Tokens Accepted by the parameter of eglGetConfigAttrib and the parameter of eglChooseConfig: EGL_Y_INVERTED_NOK 0x307F Additions to the OpenGL ES 2.0 Specification None. Additions to the EGL Specification Add to table 3.1, EGLConfig Attributes: Attribute Type Notes ------------------------------- ------- ----------------------------------- EGL_Y_INVERTED_NOK boolean True if the drawable's framebuffer is y-inverted. This can be used to determine if y-inverted texture coordinates need to be used when texturing from this drawable when it is bound to a texture target. Additions to table 3.4, Default values and match criteria for EGLConfig attributes: Attribute Default Selection Criteria Priority ------------------------------- -------------------- ------------------ --------- EGL_Y_INVERTED_NOK EGL_DONT_CARE Exact Modifications to 3.4, "Configuration Management" Modify 3rd last paragraph ("EGL BIND TO TEXTURE RGB and..."): EGL BIND TO TEXTURE RGB and EGL BIND TO TEXTURE RGBA are booleans indicating whether the color buffers of a pbuffer or a pixmap created with the EGLConfig can be bound to a OpenGL ES RGB or RGBA texture respectively. Currently only pbuffers or pixmaps can be bound as textures, so these attributes may only be EGL TRUE if the value of the EGL SURFACE TYPE attribute includes EGL PBUFFER BIT or EGL_PIXMAP_BIT. It is possible to bind a RGBA visual to a RGB texture, in which case the values in the alpha component of the visual are ignored when the color buffer is used as a RGB texture. Add after this: EGL_Y_INVERTED_NOK is a boolean describing the memory layout used for drawables created with the EGLConfig. The attribute is True if the drawable's framebuffer will be y-inverted. This can be used to determine if y-inverted texture coordinates need to be used when texturing from this drawable when it is bound to a texture target. Modifications to 3.5.4, "Creating Native Pixmap Rendering Surfaces" Modify paragraph 4 of the description of eglCreatePixmapSurface: specifies a list of attributes for the pixmap. The list has the same structure as described for eglChooseConfig. Attributes that can be specified in include EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET, EGL_MIPMAP_TEXTURE, EGL_VG_COLORSPACE and EGL_VG_ALPHA_FORMAT. EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET and EGL_MIPMAP_TEXTURE have the same meaning and default values as when used with eglCreatePbufferSurface. Modifications to section 3.6.1, "Binding a Surface to a OpenGL ES Texture" Modify paragraph 2 of the description of eglBindTexImage: The texture target, the texture format and the size of the texture components are derived from attributes of the specified , which must be a pbuffer or pixmap supporting one of the EGL_BIND_TO_TEXTURE_RGB or EGL_BIND_TO_TEXTURE_RGBA attributes. Modify paragraph 6 of the description of eglBindTexImage: ...as though glFinish were called on the last context to which that surface were bound. If is a pixmap, it also waits for all effects of native drawing to complete. Modify paragraph 7 of the description of eglBindTexImage: After eglBindTexImage is called, the specified is no longer available for reading or writing by client APIs. Any read operation, such as glReadPixels or eglCopyBuffers, which reads values from any of the surface’s color buffers or ancillary buffers will produce indeterminate results. In addition, draw operations that are done to the surface before its color buffer is released from the texture produce indeterminate results. Specifically, if the surface is current to a context and thread then rendering commands will be processed and the context state will be updated, but the surface may or may not be written. If the surface is a pixmap, it can still be accessed for reading or writing by native rendering calls, however reading and writing will produce indeterminate results and will leave the texture in an undefined state. It is up to the application to implement any synchronization required. eglSwapBuffers has no effect if it is called on a bound surface. Modify paragraph 10 of the description of eglBindTexImage: Texture mipmap levels are automatically generated when all of the following conditions are met while calling eglBindTexImage: - The EGL_MIPMAP_TEXTURE attribute of the pbuffer or pixmap being bound is EGL_TRUE. - The OpenGL ES texture parameter GL_GENERATE_MIPMAP is GL_TRUE for the currently bound texture. - The value of the EGL_MIPMAP_LEVEL attribute of the pbuffer or pixmap being bound is equal to the value of the texture parameter GL_TEXTURE_BASE_LEVEL. Modifications to section 3.6.2, "Releasing a Surface from an OpenGL ES Texture" Modify paragraph 1 of the description of eglReleaseTexImage: ...The specified color buffer is released back to the surface. The surface is made avalaible for reading and writing by client APIs when it no longer has any color buffers bound as textures. Modify paragraph 2 of the description of eglReleaseTexImage: If the surface is a pixmap, the contents of the color buffer are unaffected by eglReleaseTexImage. If the surface is a pbuffer, the contents of the color buffer are undefined when it is first released, in particular there is no guarantee that the texture image is still present. In all cases, the contents of other color buffers are unaffected by this call. ... Modify paragraph 5 of the description of eglReleaseTexImage: ...If is not a valid EGLSurface, or is not a bound pbuffer or pixmap surface, then an EGL_BAD_SURFACE error is returned. Usage Examples (skipped for now) Version History 0. 12 Aug 2008 - RS Initial version derived from GLX_EXT_texture_from_pixmap and EGL. 0.1 30 Sept 2008 - RS Changed name from EXT to NOKIA. Clarified / fixed wording wrt differences to pbuffers. 0.2 13 Nov 2009 - Sami Kyöstilä Changed extension and token names to comply with Nokia extension naming scheme. Clarified interaction with native rendering. Formatting.