1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreatePbufferFromClientBuffer"> 2 <info> 3 <copyright> 4 <year>2003-2014</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglCreatePbufferFromClientBuffer</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglCreatePbufferFromClientBuffer</refname> 14 <refpurpose> 15 create a new <acronym>EGL</acronym> pixel buffer surface 16 bound to an OpenVG image 17 </refpurpose> 18 </refnamediv> 19 <refsynopsisdiv> 20 <title>C Specification</title> 21 <funcsynopsis> 22 <funcprototype> 23 <funcdef>EGLSurface <function>eglCreatePbufferFromClientBuffer</function></funcdef> 24 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 25 <paramdef>EGLenum <parameter>buftype</parameter></paramdef> 26 <paramdef>EGLClientBuffer <parameter>buffer</parameter></paramdef> 27 <paramdef>EGLConfig <parameter>config</parameter></paramdef> 28 <paramdef>EGLint const * <parameter>attrib_list</parameter></paramdef> 29 </funcprototype> 30 </funcsynopsis> 31 </refsynopsisdiv> 32 <refsect1 xml:id="parameters"><title>Parameters</title> 33 <variablelist> 34 <varlistentry> 35 <term><parameter>display</parameter></term> 36 <listitem><para>Specifies the EGL display connection.</para></listitem> 37 </varlistentry> 38 <varlistentry> 39 <term><parameter>buftype</parameter></term> 40 <listitem> 41 <para> 42 Specifies the type of client API buffer to be bound. 43 Must be <constant>EGL_OPENVG_IMAGE</constant>, 44 corresponding to an OpenVG <type>VGImage</type> 45 buffer. 46 </para> 47 </listitem> 48 </varlistentry> 49 <varlistentry> 50 <term><parameter>buffer</parameter></term> 51 <listitem> 52 <para> 53 Specifies the OpenVG <type>VGImage</type> handle of 54 the buffer to be bound. 55 </para> 56 </listitem> 57 </varlistentry> 58 <varlistentry> 59 <term><parameter>config</parameter></term> 60 <listitem><para> 61 Specifies the EGL frame buffer configuration that defines the 62 frame buffer resource available to the surface. 63 </para></listitem> 64 </varlistentry> 65 <varlistentry> 66 <term><parameter>attrib_list</parameter></term> 67 <listitem><para> 68 Specifies pixel buffer surface attributes. 69 May be <constant>NULL</constant> or empty 70 (first attribute is <constant>EGL_NONE</constant>). 71 </para></listitem> 72 </varlistentry> 73 </variablelist> 74 </refsect1> 75 <refsect1 xml:id="description"><title>Description</title> 76 <para> 77 <function>eglCreatePbufferFromClientBuffer</function> creates an 78 off-screen pixel buffer surface and returns its handle. If 79 <function>eglCreatePbufferFromClientBuffer</function> fails to create 80 a pixel buffer surface, <constant>EGL_NO_SURFACE</constant> 81 is returned. 82 </para> 83 <para> 84 The new pixel buffer surface is similar to a pixel buffer 85 created with 86 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 87 but storage for the color buffer is provided by a client API 88 buffer. Other buffer required by 89 <parameter>config</parameter>, such as depth, stencil, and 90 alpha mask, are allocated by EGL. 91 </para> 92 <para> 93 <parameter>buftype</parameter> must be 94 <constant>EGL_OPENVG_IMAGE</constant>, corresponding to an 95 OpenVG <type>VGImage</type> buffer. 96 <parameter>buffer</parameter> must be a valid 97 <type>VGImage</type> handle in the current OpenVG context, 98 cast into the type <type>EGLClientBuffer</type>. 99 </para> 100 <para> 101 The height, width,, OpenVG alpha format, and OpenVG 102 colorspace (surface attributes 103 <constant>EGL_HEIGHT</constant>, 104 <constant>EGL_WIDTH</constant>, 105 <constant>EGL_VG_ALPHA_FORMAT</constant>, and 106 <constant>EGL_VG_COLORSPACE</constant>, respectively) of the 107 resulting surface are determined by the size and format of 108 <parameter>buffer</parameter>. 109 </para> 110 <para> 111 Surface attributes are specified as a list of 112 attribute-value pairs, terminated with 113 <constant>EGL_NONE</constant>. Accepted attributes are: 114 </para> 115 <variablelist> 116 <varlistentry> 117 <term><constant>EGL_MIPMAP_TEXTURE</constant></term> 118 <listitem> 119 <para> 120 Specifies whether storage for mipmaps should be 121 allocated. Space for mipmaps will be set aside if 122 the attribute value is <constant>EGL_TRUE</constant> 123 and <constant>EGL_TEXTURE_FORMAT</constant> is not 124 <constant>EGL_NO_TEXTURE</constant>. The default 125 value is <constant>EGL_FALSE</constant>. 126 </para> 127 </listitem> 128 </varlistentry> 129 <varlistentry> 130 <term><constant>EGL_TEXTURE_FORMAT</constant></term> 131 <listitem> 132 <para> 133 Specifies the format of the texture that will be 134 created when a pbuffer is bound to a texture map. 135 Possible values are 136 <constant>EGL_NO_TEXTURE</constant>, 137 <constant>EGL_TEXTURE_RGB</constant>, and 138 <constant>EGL_TEXTURE_RGBA</constant>. The default 139 value is <constant>EGL_NO_TEXTURE</constant>. 140 </para> 141 </listitem> 142 </varlistentry> 143 <varlistentry> 144 <term><constant>EGL_TEXTURE_TARGET</constant></term> 145 <listitem> 146 <para> 147 Specifies the target for the texture that will be 148 created when the pbuffer is created with a texture 149 format of <constant>EGL_TEXTURE_RGB</constant> or 150 <constant>EGL_TEXTURE_RGBA</constant>. Possible 151 values are <constant>EGL_NO_TEXTURE</constant>, or 152 <constant>EGL_TEXTURE_2D</constant>. The default 153 value is <constant>EGL_NO_TEXTURE</constant>. 154 </para> 155 </listitem> 156 </varlistentry> 157 </variablelist> 158 <para> 159 Any EGL rendering context that was created with respect to 160 <parameter>config</parameter> can be used to render into the 161 surface. Use 162 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry> 163 to attach an EGL rendering context to the surface. 164 </para> 165 <para> 166 Use 167 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 168 to retrieve the dimensions of the allocated pixel buffer 169 surface or the ID of <parameter>config</parameter>. 170 </para> 171 <para> 172 Use <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry> 173 to destroy the surface. 174 </para> 175 </refsect1> 176 <refsect1 xml:id="notes"><title>Notes</title> 177 <para> 178 <function>eglCreatePbufferFromClientBuffer</function> is 179 supported only if the EGL version is 1.2 or greater, and if 180 the EGL implementation supports the OpenVG client API. 181 </para> 182 <para> 183 Currently 184 <function>eglCreatePbufferFromClientBuffer</function> only 185 supports binding OpenVG <type>VGImage</type> buffers to 186 pixel buffers. While other client API resources could be 187 supported in the future, mechanisms such as OpenGL ES 188 framebuffer objects, and the family of EGL and client API 189 extensions for defining and using <type>EGLImageKHR</type> 190 images, are a more flexible and general framework to satisfy 191 most of the same needs. 192 </para> 193 <para> 194 If the value of <parameter>config</parameter> attribute 195 <constant>EGL_TEXTURE_FORMAT</constant> is not 196 <constant>EGL_NO_TEXTURE</constant>, then the pbuffer width 197 and height specify the size of the level zero texture image 198 </para> 199 <para> 200 If <constant>EGL_LARGEST_PBUFFER</constant> is specified and 201 if the pbuffer will be used as a texture (i.e. the value of 202 <constant>EGL_TEXTURE_TARGET</constant> is 203 <constant>EGL_TEXTURE_2D</constant>, and the value of 204 <constant>EGL_TEXTURE FORMAT</constant> is 205 <constant>EGL_TEXTURE_RGB</constant> or 206 <constant>EGL_TEXTURE_RGBA</constant>), then the aspect 207 ratio will be preserved and the new width and height will be 208 valid sizes for the texture target (e.g. if the underlying 209 OpenGL ES implementation does not support non-power-of-two 210 textures, both the width and height will be a power of 2). 211 </para> 212 <para> 213 The contents of the depth and stencil buffers may not be 214 preserved when rendering a texture to the pbuffer and 215 switching which image of the texture is rendered to (e.g., 216 switching from rendering one mipmap level to rendering 217 another). 218 </para> 219 <para> 220 Binding client API buffers to EGL pbuffers create the 221 possibility of race conditions, and of buffers being deleted 222 through one API while still in use in another API. To avoid 223 these problems, a number of constraints apply to bound 224 client API buffers: 225 <orderedlist> 226 <listitem> 227 <para> 228 Bound buffers may be used exclusively by either EGL, 229 or the client API that originally created them. For 230 example, if a <type>VGImage</type> is bound to a 231 pbuffer, and that pbuffer is bound to any client API 232 rendering context, then the <type>VGImage</type> may 233 not be used as the explicit source or destination of 234 any OpenVG operation. Errors resulting from such use 235 are described in client API specifications. 236 Similarly, while a <type>VGImage</type> is in use by 237 OpenVG, the pbuffer it is bound to may not be made 238 current to any client API context using 239 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>. 240 </para> 241 </listitem> 242 <listitem> 243 <para> 244 Binding a buffer creates an additional reference to 245 it, and implementations must respect outstanding 246 references when destroying objects. For example, if 247 a <type>VGImage</type> is bound to a pbuffer, 248 destroying the image with 249 <function>vgDestroyImage</function> will not free 250 the underlying buffer, because it is still in use by 251 EGL. However, following 252 <function>vgDestroyImage</function> the buffer may 253 only be referred to via the EGL pbuffer handle, 254 since the OpenVG handle to that buffer no longer 255 exists. Similarly, destroying the pbuffer with 256 <function>eglDestroySurface</function> will not free 257 the underlying buffer, because it is still in use by 258 OpenVG . However, following 259 <function>eglDestroySurface</function> the buffer 260 may only be referred to via the OpenVG 261 <type>VGImage</type> handle, since the EGL pbuffer 262 handle no longer exists. 263 </para> 264 </listitem> 265 </orderedlist> 266 </para> 267 </refsect1> 268 <refsect1 xml:id="errors"><title>Errors</title> 269 <para> 270 <constant>EGL_NO_SURFACE</constant> is returned if creation of 271 the context fails. 272 </para> 273 <para> 274 <constant>EGL_BAD_DISPLAY</constant> is generated if 275 <parameter>display</parameter> is not an EGL display connection. 276 </para> 277 <para> 278 <constant>EGL_NOT_INITIALIZED</constant> is generated if 279 <parameter>display</parameter> has not been initialized. 280 </para> 281 <para> 282 <constant>EGL_BAD_CONFIG</constant> is generated if 283 <parameter>config</parameter> is not an EGL frame buffer configuration. 284 </para> 285 <para> 286 <constant>EGL_BAD_PARAMETER</constant> is generated if 287 <parameter>buftype</parameter> is not 288 <constant>EGL_OPENVG_IMAGE</constant>, or if 289 <parameter>buffer</parameter> is not a valid handle to a 290 <type>VGImage</type> object in the currently bound OpenVG 291 context. 292 </para> 293 <para> 294 <constant>EGL_BAD_ACCESS</constant> is generated if there is 295 no current OpenVG context, or if 296 <parameter>buffer</parameter> is already bound to another 297 pixel buffer or in use by OpenVG as discussed in the Notes 298 section above. 299 </para> 300 <para> 301 <constant>EGL_BAD_ACCESS</constant> is generated if the buffers 302 contained in <parameter>buffer</parameter> consist of any 303 <type>EGLImage</type> siblings. 304 </para> 305 <para> 306 <constant>EGL_BAD_ALLOC</constant> is generated if there are not 307 enough resources to allocate the new surface. 308 </para> 309 <para> 310 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 311 <parameter>attrib_list</parameter> contains an invalid pixel 312 buffer attribute or if an attribute value is not recognized 313 or out of range. 314 </para> 315 <para> 316 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 317 <parameter>attrib_list</parameter> contains any of the 318 attributes <constant>EGL_MIPMAP_TEXTURE</constant>, 319 <constant>EGL_TEXTURE_FORMAT</constant>, or 320 <constant>EGL_TEXTURE_TARGET</constant>, and 321 <parameter>config</parameter> does not support OpenGL ES 322 rendering (e.g. the EGL version is 1.2 or later, and the 323 <constant>EGL_RENDERABLE_TYPE</constant> attribute of 324 <parameter>config</parameter> does not include at least one 325 of <constant>EGL_OPENGL_ES_BIT</constant> or 326 <constant>EGL_OPENGL_ES2_BIT</constant>). 327 </para> 328 <para> 329 <constant>EGL_BAD_MATCH</constant> is generated if 330 <parameter>config</parameter> does not support rendering to 331 pixel buffers (the <constant>EGL_SURFACE_TYPE</constant> 332 attribute does not contain 333 <constant>EGL_PBUFFER_BIT</constant>). 334 </para> 335 <para> 336 <constant>EGL_BAD_MATCH</constant> is generated if the 337 buffers contained in <parameter>buffer</parameter> do not 338 match the bit depths for those buffers specified by 339 <parameter>config</parameter>. 340 </para> 341 <para> 342 <constant>EGL_BAD_MATCH</constant> is generated if the 343 <constant>EGL_TEXTURE_FORMAT</constant> attribute is not 344 <constant>EGL_NO_TEXTURE</constant>, and 345 <constant>EGL_WIDTH</constant> and/or 346 <constant>EGL_HEIGHT</constant> specify an invalid size 347 (e.g., the texture size is not a power of 2, and the 348 underlying OpenGL ES implementation does not support 349 non-power-of-two textures). 350 </para> 351 <para> 352 <constant>EGL_BAD_MATCH</constant> is generated if 353 the <constant>EGL_TEXTURE_FORMAT</constant> attribute is 354 <constant>EGL_NO_TEXTURE</constant>, and 355 <constant>EGL_TEXTURE_TARGET</constant> is something other 356 than <constant>EGL_NO_TEXTURE</constant>; or, 357 <constant>EGL_TEXTURE_FORMAT</constant> is something other 358 than <constant>EGL_NO_TEXTURE</constant>, and 359 <constant>EGL_TEXTURE_TARGET</constant> is 360 <constant>EGL_NO_TEXTURE</constant>. 361 </para> 362 <para> 363 <constant>EGL_BAD_MATCH</constant> is generated if the 364 implementation has additional constraints on which types of 365 client API buffers may be bound to pixel buffer surfaces. 366 For example, it is possible that the OpenVG implementation 367 might not support a <type>VGImage</type> being bound to a 368 pixel buffer which will be used as a mipmapped OpenGL ES 369 texture (e.g. whose <constant>EGL_MIPMAP_TEXTURE</constant> 370 attribute is <constant>TRUE</constant>). Any such 371 constraints should be documented by the implementation 372 release notes. 373 </para> 374 </refsect1> 375 <refsect1 xml:id="seealso"><title>See Also</title> 376 <para> 377 <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>, 378 <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>, 379 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 380 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>, 381 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>, 382 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 383 </para> 384 </refsect1> 385 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 386</refentry> 387