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 pixel buffer surface attributes. May be NULL or empty (first attribute is EGL_NONE).

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.

Surface attributes are specified as a list of attribute-value pairs, terminated with EGL_NONE. Accepted attributes are:

EGL_GL_COLORSPACE

Specifies the color space used by OpenGL and OpenGL ES when rendering to the surface. If its value is EGL_GL_COLORSPACE_SRGB, then a non-linear, perceptually uniform color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_SRGB. If its value is EGL_GL_COLORSPACE_LINEAR, then a linear color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR. The default value of EGL_GL_COLORSPACE is EGL_GL_COLORSPACE_LINEAR.

Note that the EGL_GL_COLORSPACE attribute is used only by OpenGL and OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not distinguish multiple colorspace models. Refer to the ``sRGB Conversion'' sections of the OpenGL 4.6 and OpenGL ES 3.2 Specifications for more information.

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

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_VG_ALPHA_FORMAT

Specifies how alpha values are interpreted by OpenVG when rendering to the surface. If its value is EGL_VG_ALPHA_FORMAT_NONPRE, then alpha values are not premultipled. If its value is EGL_VG_ALPHA_FORMAT_PRE, then alpha values are premultiplied. The default value of EGL_VG_ALPHA_FORMAT is EGL_VG_ALPHA_FORMAT_NONPRE.

EGL_VG_COLORSPACE

Specifies the color space used by OpenVG when rendering to the surface. If its value is EGL_VG_COLORSPACE_sRGB, then a non-linear, perceptually uniform color space is assumed, with a corresponding VGImageFormat of form VG_s*. If its value is EGL_VG_COLORSPACE_LINEAR, then a linear color space is assumed, with a corresponding VGImageFormat of form VG_l*. The default value of EGL_VG_COLORSPACE is EGL_VG_COLORSPACE_sRGB.

EGL_WIDTH

Specifies the required width of the pixel buffer surface. The default value is 0.

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.

Notes

Attribute EGL_GL_COLORSPACE, and the EGL_OPENGL_ES3_BIT bit value for attribute EGL_RENDERABLE_TYPE, are supported only if the EGL version is 1.5 or greater.

Attributes EGL_RENDERABLE_TYPE, EGL_VG_ALPHA_FORMAT, and EGL_VG_COLORSPACE, and the corresponding attribute values, are supported only if the EGL version is 1.2 or greater.

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_ATTRIBUTE is generated if attrib_list contains any of the attributes EGL_MIPMAP_TEXTURE, EGL_TEXTURE_FORMAT, or EGL_TEXTURE_TARGET, and config does not support OpenGL ES rendering (e.g. the EGL version is 1.2 or later, and the EGL_RENDERABLE_TYPE attribute of config does not include at least one of EGL_OPENGL_ES_BIT, EGL_OPENGL_ES2_BIT, or EGL_OPENGL_ES3_BIT),

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_MATCH 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_MATCH is 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.

EGL_BAD_MATCH is generated if config does not support the specified OpenVG alpha format attribute (the value of EGL_VG_ALPHA_FORMAT is EGL_VG_ALPHA_FORMAT_PRE and the EGL_VG_ALPHA_FORMAT_PRE_BIT is not set in the EGL_SURFACE_TYPE attribute of config) or colorspace attribute (the value of EGL_VG_COLORSPACE is EGL_VG_COLORSPACE_LINEAR and the EGL_VG_COLORSPACE_LINEAR_IT is not set in the EGL_SURFACE_TYPE attribute of config).