| <?xml version="1.0" encoding="UTF-8" standalone="no"?> | |
| <!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> | |
| <head> | |
| <title xmlns:xlink="http://www.w3.org/1999/xlink">eglCreatePbufferFromClientBuffer - EGL Reference Pages</title> | |
| <link rel="stylesheet" type="text/css" href="khronos-man.css"/> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/> | |
| </head> | |
| <body> | |
| <header/> | |
| <div class="refentry" id="eglCreatePbufferFromClientBuffer"> | |
| <div class="titlepage"/> | |
| <div class="refnamediv"> | |
| <h2>Name</h2> | |
| <p>eglCreatePbufferFromClientBuffer — | |
| create a new <abbr class="acronym">EGL</abbr> pixel buffer surface | |
| bound to an OpenVG image | |
| </p> | |
| </div> | |
| <div class="refsynopsisdiv"> | |
| <h2>C Specification</h2> | |
| <div class="funcsynopsis"> | |
| <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> | |
| <tr> | |
| <td> | |
| <code class="funcdef">EGLSurface <strong class="fsfunc">eglCreatePbufferFromClientBuffer</strong>(</code> | |
| </td> | |
| <td>EGLDisplay <var class="pdparam">display</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>EGLenum <var class="pdparam">buftype</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>EGLClientBuffer <var class="pdparam">buffer</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>EGLConfig <var class="pdparam">config</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>EGLint const * <var class="pdparam">attrib_list</var><code>)</code>;</td> | |
| </tr> | |
| </table> | |
| <div class="funcprototype-spacer"> </div> | |
| </div> | |
| </div> | |
| <div class="refsect1" id="parameters"> | |
| <h2>Parameters</h2> | |
| <div class="variablelist"> | |
| <dl class="variablelist"> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>display</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p>Specifies the EGL display connection.</p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>buftype</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the type of client API buffer to be bound. | |
| Must be <code class="constant">EGL_OPENVG_IMAGE</code>, | |
| corresponding to an OpenVG <span class="type">VGImage</span> | |
| buffer. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>buffer</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the OpenVG <span class="type">VGImage</span> handle of | |
| the buffer to be bound. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>config</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the EGL frame buffer configuration that defines the | |
| frame buffer resource available to the surface. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>attrib_list</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies pixel buffer surface attributes. | |
| May be <code class="constant">NULL</code> or empty | |
| (first attribute is <code class="constant">EGL_NONE</code>). | |
| </p> | |
| </dd> | |
| </dl> | |
| </div> | |
| </div> | |
| <div class="refsect1" id="description"> | |
| <h2>Description</h2> | |
| <p> | |
| <code class="function">eglCreatePbufferFromClientBuffer</code> creates an | |
| off-screen pixel buffer surface and returns its handle. If | |
| <code class="function">eglCreatePbufferFromClientBuffer</code> fails to create | |
| a pixel buffer surface, <code class="constant">EGL_NO_SURFACE</code> | |
| is returned. | |
| </p> | |
| <p> | |
| The new pixel buffer surface is similar to a pixel buffer | |
| created with | |
| <a class="citerefentry" href="eglCreatePbufferSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePbufferSurface</span></span></a>, | |
| but storage for the color buffer is provided by a client API | |
| buffer. Other buffer required by | |
| <em class="parameter"><code>config</code></em>, such as depth, stencil, and | |
| alpha mask, are allocated by EGL. | |
| </p> | |
| <p> | |
| <em class="parameter"><code>buftype</code></em> must be | |
| <code class="constant">EGL_OPENVG_IMAGE</code>, corresponding to an | |
| OpenVG <span class="type">VGImage</span> buffer. | |
| <em class="parameter"><code>buffer</code></em> must be a valid | |
| <span class="type">VGImage</span> handle in the current OpenVG context, | |
| cast into the type <span class="type">EGLClientBuffer</span>. | |
| </p> | |
| <p> | |
| The height, width,, OpenVG alpha format, and OpenVG | |
| colorspace (surface attributes | |
| <code class="constant">EGL_HEIGHT</code>, | |
| <code class="constant">EGL_WIDTH</code>, | |
| <code class="constant">EGL_VG_ALPHA_FORMAT</code>, and | |
| <code class="constant">EGL_VG_COLORSPACE</code>, respectively) of the | |
| resulting surface are determined by the size and format of | |
| <em class="parameter"><code>buffer</code></em>. | |
| </p> | |
| <p> | |
| Surface attributes are specified as a list of | |
| attribute-value pairs, terminated with | |
| <code class="constant">EGL_NONE</code>. Accepted attributes are: | |
| </p> | |
| <div class="variablelist"> | |
| <dl class="variablelist"> | |
| <dt> | |
| <span class="term"> | |
| <code class="constant">EGL_MIPMAP_TEXTURE</code> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies whether storage for mipmaps should be | |
| allocated. Space for mipmaps will be set aside if | |
| the attribute value is <code class="constant">EGL_TRUE</code> | |
| and <code class="constant">EGL_TEXTURE_FORMAT</code> is not | |
| <code class="constant">EGL_NO_TEXTURE</code>. The default | |
| value is <code class="constant">EGL_FALSE</code>. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <code class="constant">EGL_TEXTURE_FORMAT</code> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the format of the texture that will be | |
| created when a pbuffer is bound to a texture map. | |
| Possible values are | |
| <code class="constant">EGL_NO_TEXTURE</code>, | |
| <code class="constant">EGL_TEXTURE_RGB</code>, and | |
| <code class="constant">EGL_TEXTURE_RGBA</code>. The default | |
| value is <code class="constant">EGL_NO_TEXTURE</code>. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <code class="constant">EGL_TEXTURE_TARGET</code> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the target for the texture that will be | |
| created when the pbuffer is created with a texture | |
| format of <code class="constant">EGL_TEXTURE_RGB</code> or | |
| <code class="constant">EGL_TEXTURE_RGBA</code>. Possible | |
| values are <code class="constant">EGL_NO_TEXTURE</code>, or | |
| <code class="constant">EGL_TEXTURE_2D</code>. The default | |
| value is <code class="constant">EGL_NO_TEXTURE</code>. | |
| </p> | |
| </dd> | |
| </dl> | |
| </div> | |
| <p> | |
| Any EGL rendering context that was created with respect to | |
| <em class="parameter"><code>config</code></em> can be used to render into the | |
| surface. Use | |
| <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a> | |
| to attach an EGL rendering context to the surface. | |
| </p> | |
| <p> | |
| Use | |
| <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> | |
| to retrieve the dimensions of the allocated pixel buffer | |
| surface or the ID of <em class="parameter"><code>config</code></em>. | |
| </p> | |
| <p> | |
| Use <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a> | |
| to destroy the surface. | |
| </p> | |
| </div> | |
| <div class="refsect1" id="notes"> | |
| <h2>Notes</h2> | |
| <p> | |
| <code class="function">eglCreatePbufferFromClientBuffer</code> is | |
| supported only if the EGL version is 1.2 or greater, and if | |
| the EGL implementation supports the OpenVG client API. | |
| </p> | |
| <p> | |
| Currently | |
| <code class="function">eglCreatePbufferFromClientBuffer</code> only | |
| supports binding OpenVG <span class="type">VGImage</span> 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 <span class="type">EGLImageKHR</span> | |
| images, are a more flexible and general framework to satisfy | |
| most of the same needs. | |
| </p> | |
| <p> | |
| If the value of <em class="parameter"><code>config</code></em> attribute | |
| <code class="constant">EGL_TEXTURE_FORMAT</code> is not | |
| <code class="constant">EGL_NO_TEXTURE</code>, then the pbuffer width | |
| and height specify the size of the level zero texture image | |
| </p> | |
| <p> | |
| If <code class="constant">EGL_LARGEST_PBUFFER</code> is specified and | |
| if the pbuffer will be used as a texture (i.e. the value of | |
| <code class="constant">EGL_TEXTURE_TARGET</code> is | |
| <code class="constant">EGL_TEXTURE_2D</code>, and the value of | |
| <code class="constant">EGL_TEXTURE FORMAT</code> is | |
| <code class="constant">EGL_TEXTURE_RGB</code> or | |
| <code class="constant">EGL_TEXTURE_RGBA</code>), 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). | |
| </p> | |
| <p> | |
| 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). | |
| </p> | |
| <p> | |
| 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: | |
| </p> | |
| <div class="orderedlist"> | |
| <ol class="orderedlist" type="1"> | |
| <li class="listitem"> | |
| <p> | |
| Bound buffers may be used exclusively by either EGL, | |
| or the client API that originally created them. For | |
| example, if a <span class="type">VGImage</span> is bound to a | |
| pbuffer, and that pbuffer is bound to any client API | |
| rendering context, then the <span class="type">VGImage</span> 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 <span class="type">VGImage</span> is in use by | |
| OpenVG, the pbuffer it is bound to may not be made | |
| current to any client API context using | |
| <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>. | |
| </p> | |
| </li> | |
| <li class="listitem"> | |
| <p> | |
| Binding a buffer creates an additional reference to | |
| it, and implementations must respect outstanding | |
| references when destroying objects. For example, if | |
| a <span class="type">VGImage</span> is bound to a pbuffer, | |
| destroying the image with | |
| <code class="function">vgDestroyImage</code> will not free | |
| the underlying buffer, because it is still in use by | |
| EGL. However, following | |
| <code class="function">vgDestroyImage</code> 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 | |
| <code class="function">eglDestroySurface</code> will not free | |
| the underlying buffer, because it is still in use by | |
| OpenVG . However, following | |
| <code class="function">eglDestroySurface</code> the buffer | |
| may only be referred to via the OpenVG | |
| <span class="type">VGImage</span> handle, since the EGL pbuffer | |
| handle no longer exists. | |
| </p> | |
| </li> | |
| </ol> | |
| </div> | |
| <p> | |
| </p> | |
| </div> | |
| <div class="refsect1" id="errors"> | |
| <h2>Errors</h2> | |
| <p> | |
| <code class="constant">EGL_NO_SURFACE</code> is returned if creation of | |
| the context fails. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_DISPLAY</code> is generated if | |
| <em class="parameter"><code>display</code></em> is not an EGL display connection. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_NOT_INITIALIZED</code> is generated if | |
| <em class="parameter"><code>display</code></em> has not been initialized. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_CONFIG</code> is generated if | |
| <em class="parameter"><code>config</code></em> is not an EGL frame buffer configuration. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated if | |
| <em class="parameter"><code>buftype</code></em> is not | |
| <code class="constant">EGL_OPENVG_IMAGE</code>, or if | |
| <em class="parameter"><code>buffer</code></em> is not a valid handle to a | |
| <span class="type">VGImage</span> object in the currently bound OpenVG | |
| context. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_ACCESS</code> is generated if there is | |
| no current OpenVG context, or if | |
| <em class="parameter"><code>buffer</code></em> is already bound to another | |
| pixel buffer or in use by OpenVG as discussed in the Notes | |
| section above. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_ACCESS</code> is generated if the buffers | |
| contained in <em class="parameter"><code>buffer</code></em> consist of any | |
| <span class="type">EGLImage</span> siblings. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_ALLOC</code> is generated if there are not | |
| enough resources to allocate the new surface. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if | |
| <em class="parameter"><code>attrib_list</code></em> contains an invalid pixel | |
| buffer attribute or if an attribute value is not recognized | |
| or out of range. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if | |
| <em class="parameter"><code>attrib_list</code></em> contains any of the | |
| attributes <code class="constant">EGL_MIPMAP_TEXTURE</code>, | |
| <code class="constant">EGL_TEXTURE_FORMAT</code>, or | |
| <code class="constant">EGL_TEXTURE_TARGET</code>, and | |
| <em class="parameter"><code>config</code></em> does not support OpenGL ES | |
| rendering (e.g. the EGL version is 1.2 or later, and the | |
| <code class="constant">EGL_RENDERABLE_TYPE</code> attribute of | |
| <em class="parameter"><code>config</code></em> does not include at least one | |
| of <code class="constant">EGL_OPENGL_ES_BIT</code> or | |
| <code class="constant">EGL_OPENGL_ES2_BIT</code>). | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_MATCH</code> is generated if | |
| <em class="parameter"><code>config</code></em> does not support rendering to | |
| pixel buffers (the <code class="constant">EGL_SURFACE_TYPE</code> | |
| attribute does not contain | |
| <code class="constant">EGL_PBUFFER_BIT</code>). | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_MATCH</code> is generated if the | |
| buffers contained in <em class="parameter"><code>buffer</code></em> do not | |
| match the bit depths for those buffers specified by | |
| <em class="parameter"><code>config</code></em>. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_MATCH</code> is generated if the | |
| <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is not | |
| <code class="constant">EGL_NO_TEXTURE</code>, and | |
| <code class="constant">EGL_WIDTH</code> and/or | |
| <code class="constant">EGL_HEIGHT</code> 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). | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_MATCH</code> is generated if | |
| the <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is | |
| <code class="constant">EGL_NO_TEXTURE</code>, and | |
| <code class="constant">EGL_TEXTURE_TARGET</code> is something other | |
| than <code class="constant">EGL_NO_TEXTURE</code>; or, | |
| <code class="constant">EGL_TEXTURE_FORMAT</code> is something other | |
| than <code class="constant">EGL_NO_TEXTURE</code>, and | |
| <code class="constant">EGL_TEXTURE_TARGET</code> is | |
| <code class="constant">EGL_NO_TEXTURE</code>. | |
| </p> | |
| <p> | |
| <code class="constant">EGL_BAD_MATCH</code> 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 <span class="type">VGImage</span> being bound to a | |
| pixel buffer which will be used as a mipmapped OpenGL ES | |
| texture (e.g. whose <code class="constant">EGL_MIPMAP_TEXTURE</code> | |
| attribute is <code class="constant">TRUE</code>). Any such | |
| constraints should be documented by the implementation | |
| release notes. | |
| </p> | |
| </div> | |
| <div class="refsect1" id="seealso"> | |
| <h2>See Also</h2> | |
| <p> | |
| <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a>, | |
| <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a>, | |
| <a class="citerefentry" href="eglCreatePbufferSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePbufferSurface</span></span></a>, | |
| <a class="citerefentry" href="eglGetConfigs.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetConfigs</span></span></a>, | |
| <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>, | |
| <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> | |
| </p> | |
| </div> | |
| <p> | |
| </p> | |
| <div class="refsect3" id="copyright"> | |
| <img src="KhronosLogo.jpg"/> | |
| <p> | |
| 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. | |
| </p> | |
| </div> | |
| <p> | |
| </p> | |
| </div> | |
| <footer/> | |
| </body> | |
| </html> |