eglCreatePbufferSurface — create a new EGL pixel buffer surface
EGLSurface eglCreatePbufferSurface( | EGLDisplay display, |
| EGLConfig config, | |
EGLint const * attrib_list); |
displaySpecifies the EGL display connection.
configSpecifies the EGL frame buffer configuration that defines the frame buffer resource available to the surface.
attrib_list
Specifies the pixel buffer surface attributes.
May be NULL or empty
(first attribute is EGL_NONE).
Accepted attributes are
EGL_WIDTH,
EGL_HEIGHT, and
EGL_LARGEST_PBUFFER.
eglCreatePbufferSurface creates an
off-screen pixel buffer surface and returns its handle.
If eglCreatePbufferSurface fails to create a
pixel buffer surface, EGL_NO_SURFACE is returned.
Any EGL rendering context that was created with respect to
config can be used to render into the surface.
Use eglMakeCurrent
to attach an EGL rendering context to the surface.
Use
eglQuerySurface
to retrieve the dimensions of the allocated pixel buffer surface or
the ID of config.
Use eglDestroySurface to destroy the surface.
The pixel buffer surface attributes are specified as a list of
attribute value pairs, terminated with EGL_NONE.
The accepted attributes for an EGL pixel buffer surface are:
EGL_WIDTH
Specifies the required width of the pixel buffer surface.
The default value is 0.
EGL_HEIGHT
Specifies the required height of the pixel buffer surface.
The default value is 0.
EGL_LARGEST_PBUFFER
Requests the largest available pixel buffer surface when the allocation would otherwise fail.
Use eglQuerySurface
to retrieve the dimensions of the allocated pixel buffer.
The default value is EGL_FALSE.
EGL_TEXTURE_FORMAT
Specifies the format of the texture that will be created when a pbuffer is bound to a texture map.
Possible values are
EGL_NO_TEXTURE,
EGL_TEXTURE_RGB, and
EGL_TEXTURE_RGBA.
The default value is EGL_NO_TEXTURE.
EGL_TEXTURE_TARGET
Specifies the target for the texture that will be created when the pbuffer is created
with a texture format of EGL_TEXTURE_RGB or EGL_TEXTURE_RGBA.
Possible values are
EGL_NO_TEXTURE, or
EGL_TEXTURE_2D.
The default value is EGL_NO_TEXTURE.
EGL_MIPMAP_TEXTURE
Specifies whether storage for mipmaps should be allocated.
Space for mipmaps will be set aside if the attribute value is EGL_TRUE
and EGL_TEXTURE_FORMAT is not EGL_NO_TEXTURE.
The default value is EGL_FALSE.
If the value of config attribute EGL_TEXTURE_FORMAT is not EGL_NO_TEXTURE,
then the pbuffer width and height specify the size of the level zero texture image
If EGL_LARGEST_PBUFFER is specified and if the pbuffer will be used as a texture
(i.e. the value of EGL_TEXTURE_TARGET is EGL_TEXTURE_2D,
and the value of EGL_TEXTURE FORMAT is EGL_TEXTURE_RGB
or EGL_TEXTURE_RGBA), then the aspect ratio will be preserved and the new width
and height will be valid sizes for the texture target (e.g. if the underlying OpenGL ES implementation
does not support non-power-of-two textures, both the width and height will be a power of 2).
The contents of the depth and stencil buffers may not be preserved when rendering a texture to the pbuffer and switching which image of the texture is rendered to (e.g., switching from rendering one mipmap level to rendering another).
EGL_NO_SURFACE is returned if creation of
the context fails.
EGL_BAD_DISPLAY is generated if
display is not an EGL display connection.
EGL_NOT_INITIALIZED is generated if
display has not been initialized.
EGL_BAD_CONFIG is generated if
config is not an EGL frame buffer configuration.
EGL_BAD_ATTRIBUTE is generated if
attrib_list contains an invalid pixel buffer
attribute or if an attribute value is not recognized or out of range.
EGL_BAD_ALLOC is generated if there are not
enough resources to allocate the new surface.
EGL_BAD_MATCH is generated if
config does not support rendering to pixel buffers
(the EGL_SURFACE_TYPE attribute does not contain
EGL_PBUFFER_BIT).
EGL_BAD_VALUE is generated if
The EGL_TEXTURE_FORMAT attribute is not EGL_NO_TEXTURE, and
EGL_WIDTH and/or EGL_HEIGHT specify an invalid size
(e.g., the texture size is not a power of 2, and the underlying OpenGL ES
implementation does not support non-power-of-two textures).
EGL_BAD_VALUE can also be generated if
The EGL_TEXTURE_FORMAT attribute
is EGL_NO_TEXTURE, and EGL_TEXTURE_TARGET is something other
than EGL_NO_TEXTURE; or, EGL_TEXTURE_FORMAT is something other than
EGL_NO_TEXTURE, and EGL_TEXTURE_TARGET is EGL_NO_TEXTURE.
Copyright © 2003-2004 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.