Name

eglCreatePbufferSurface - create a new EGL pixel buffer surface

C Specification

EGLSurface eglCreatePbufferSurface(EGLDisplay display,
    EGLConfig config,
    EGLint const * attrib_list)

Parameters

display

Specifies the EGL display connection.

config

Specifies 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.

Description

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.

Notes

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).

Errors

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

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/.

See Also

eglDestroySurface, eglChooseConfig, eglGetConfigs, eglMakeCurrent, eglQuerySurface