eglCreatePbufferFromClientBuffer - EGL Reference Pages

Name

eglCreatePbufferFromClientBuffer — + create a new EGL pixel buffer surface + bound to an OpenVG image +

C Specification

+ + + + + + + + + + + + + + + + + + + + + +

+ `EGLSurface eglCreatePbufferFromClientBuffer(` +	EGLDisplay `display`,
	EGLenum `buftype`,
	EGLClientBuffer `buffer`,
	EGLConfig `config`,
	EGLint const * `attrib_list)`;

Parameters

+ + + display + + +: +
Specifies the EGL display connection.
+
+ + + buftype + + +: +
+ Specifies the type of client API buffer to be bound. + Must be EGL_OPENVG_IMAGE, + corresponding to an OpenVG VGImage + buffer. +
+
+ + + buffer + + +: +
+ Specifies the OpenVG VGImage handle of + the buffer to be bound. +
+
+ + + 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

+ eglCreatePbufferFromClientBuffer creates an + off-screen pixel buffer surface and returns its handle. If + eglCreatePbufferFromClientBuffer fails to create + a pixel buffer surface, EGL_NO_SURFACE + is returned. +

+ The new pixel buffer surface is similar to a pixel buffer + created with + eglCreatePbufferSurface, + but storage for the color buffer is provided by a client API + buffer. Other buffer required by + config, such as depth, stencil, and + alpha mask, are allocated by EGL. +

+ buftype must be + EGL_OPENVG_IMAGE, corresponding to an + OpenVG VGImage buffer. + buffer must be a valid + VGImage handle in the current OpenVG context, + cast into the type EGLClientBuffer. +

+ The height, width,, OpenVG alpha format, and OpenVG + colorspace (surface attributes + EGL_HEIGHT, + EGL_WIDTH, + EGL_VG_ALPHA_FORMAT, and + EGL_VG_COLORSPACE, respectively) of the + resulting surface are determined by the size and format of + buffer. +

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

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

+ 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

+ eglCreatePbufferFromClientBuffer is + supported only if the EGL version is 1.2 or greater, and if + the EGL implementation supports the OpenVG client API. +

+ Currently + eglCreatePbufferFromClientBuffer only + supports binding OpenVG VGImage buffers to + pixel buffers. While other client API resources could be + supported in the future, mechanisms such as OpenGL ES + framebuffer objects, and the family of EGL and client API + extensions for defining and using EGLImageKHR + images, are a more flexible and general framework to satisfy + most of the same needs. +

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

+ Binding client API buffers to EGL pbuffers create the + possibility of race conditions, and of buffers being deleted + through one API while still in use in another API. To avoid + these problems, a number of constraints apply to bound + client API buffers: +

+
+ Bound buffers may be used exclusively by either EGL, + or the client API that originally created them. For + example, if a VGImage is bound to a + pbuffer, and that pbuffer is bound to any client API + rendering context, then the VGImage may + not be used as the explicit source or destination of + any OpenVG operation. Errors resulting from such use + are described in client API specifications. + Similarly, while a VGImage is in use by + OpenVG, the pbuffer it is bound to may not be made + current to any client API context using + eglMakeCurrent. +
+
+
+ Binding a buffer creates an additional reference to + it, and implementations must respect outstanding + references when destroying objects. For example, if + a VGImage is bound to a pbuffer, + destroying the image with + vgDestroyImage will not free + the underlying buffer, because it is still in use by + EGL. However, following + vgDestroyImage the buffer may + only be referred to via the EGL pbuffer handle, + since the OpenVG handle to that buffer no longer + exists. Similarly, destroying the pbuffer with + eglDestroySurface will not free + the underlying buffer, because it is still in use by + OpenVG . However, following + eglDestroySurface the buffer + may only be referred to via the OpenVG + VGImage handle, since the EGL pbuffer + handle no longer exists. +
+

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_PARAMETER is generated if + buftype is not + EGL_OPENVG_IMAGE, or if + buffer is not a valid handle to a + VGImage object in the currently bound OpenVG + context. +

+ EGL_BAD_ACCESS is generated if there is + no current OpenVG context, or if + buffer is already bound to another + pixel buffer or in use by OpenVG as discussed in the Notes + section above. +

+ EGL_BAD_ACCESS is generated if the buffers + contained in buffer consist of any + EGLImage siblings. +

+ EGL_BAD_ALLOC is generated if there are not + enough resources to allocate the new surface. +

+ 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_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 + buffers contained in buffer do not + match the bit depths for those buffers specified by + config. +

+ 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 the + implementation has additional constraints on which types of + client API buffers may be bound to pixel buffer surfaces. + For example, it is possible that the OpenVG implementation + might not support a VGImage being bound to a + pixel buffer which will be used as a mipmapped OpenGL ES + texture (e.g. whose EGL_MIPMAP_TEXTURE + attribute is TRUE). Any such + constraints should be documented by the implementation + release notes. +