+ +

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

+ 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 or + EGL_OPENGL_ES2_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). +

+ +