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:

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

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

## See Also

eglDestroySurface, eglChooseConfig, eglCreatePbufferSurface, eglGetConfigs, eglMakeCurrent, eglQuerySurface

Copyright © 2003-2014 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.