blob: ebc4ee06beec6b3f020cfc85e9c187890a663488 [file] [log] [blame]
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()
<Do rendering/compositing>
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 <Attribute> parameter of eglGetConfigAttrib and
the <attrib_list> 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:
<attrib_list> specifies a list of attributes for the pixmap. The list has
the same structure as described for eglChooseConfig. Attributes that can
be specified in <attrib_list> 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 <surface>, 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 <surface> 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 <surface> 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
surfaces 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 <surface> 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ä <sami.kyostila@nokia.com>
Changed extension and token names to comply with Nokia extension naming
scheme. Clarified interaction with native rendering. Formatting.