1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <title xmlns:xlink="http://www.w3.org/1999/xlink">eglCreatePbufferFromClientBuffer - EGL Reference Pages</title> 5 <link rel="stylesheet" type="text/css" href="khronos-man.css"/> 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/> 7 </head> 8 <body> 9 <header/> 10 <div class="refentry" id="eglCreatePbufferFromClientBuffer"> 11 <div class="titlepage"/> 12 <div class="refnamediv"> 13 <h2>Name</h2> 14 <p>eglCreatePbufferFromClientBuffer — 15 create a new <abbr class="acronym">EGL</abbr> pixel buffer surface 16 bound to an OpenVG image 17 </p> 18 </div> 19 <div class="refsynopsisdiv"> 20 <h2>C Specification</h2> 21 <div class="funcsynopsis"> 22 <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> 23 <tr> 24 <td> 25 <code class="funcdef">EGLSurface <strong class="fsfunc">eglCreatePbufferFromClientBuffer</strong>(</code> 26 </td> 27 <td>EGLDisplay <var class="pdparam">display</var>, </td> 28 </tr> 29 <tr> 30 <td> </td> 31 <td>EGLenum <var class="pdparam">buftype</var>, </td> 32 </tr> 33 <tr> 34 <td> </td> 35 <td>EGLClientBuffer <var class="pdparam">buffer</var>, </td> 36 </tr> 37 <tr> 38 <td> </td> 39 <td>EGLConfig <var class="pdparam">config</var>, </td> 40 </tr> 41 <tr> 42 <td> </td> 43 <td>EGLint const * <var class="pdparam">attrib_list</var><code>)</code>;</td> 44 </tr> 45 </table> 46 <div class="funcprototype-spacer"> </div> 47 </div> 48 </div> 49 <div class="refsect1" id="parameters"> 50 <h2>Parameters</h2> 51 <div class="variablelist"> 52 <dl class="variablelist"> 53 <dt> 54 <span class="term"> 55 <em class="parameter"> 56 <code>display</code> 57 </em> 58 </span> 59 </dt> 60 <dd> 61 <p>Specifies the EGL display connection.</p> 62 </dd> 63 <dt> 64 <span class="term"> 65 <em class="parameter"> 66 <code>buftype</code> 67 </em> 68 </span> 69 </dt> 70 <dd> 71 <p> 72 Specifies the type of client API buffer to be bound. 73 Must be <code class="constant">EGL_OPENVG_IMAGE</code>, 74 corresponding to an OpenVG <span class="type">VGImage</span> 75 buffer. 76 </p> 77 </dd> 78 <dt> 79 <span class="term"> 80 <em class="parameter"> 81 <code>buffer</code> 82 </em> 83 </span> 84 </dt> 85 <dd> 86 <p> 87 Specifies the OpenVG <span class="type">VGImage</span> handle of 88 the buffer to be bound. 89 </p> 90 </dd> 91 <dt> 92 <span class="term"> 93 <em class="parameter"> 94 <code>config</code> 95 </em> 96 </span> 97 </dt> 98 <dd> 99 <p> 100 Specifies the EGL frame buffer configuration that defines the 101 frame buffer resource available to the surface. 102 </p> 103 </dd> 104 <dt> 105 <span class="term"> 106 <em class="parameter"> 107 <code>attrib_list</code> 108 </em> 109 </span> 110 </dt> 111 <dd> 112 <p> 113 Specifies pixel buffer surface attributes. 114 May be <code class="constant">NULL</code> or empty 115 (first attribute is <code class="constant">EGL_NONE</code>). 116 </p> 117 </dd> 118 </dl> 119 </div> 120 </div> 121 <div class="refsect1" id="description"> 122 <h2>Description</h2> 123 <p> 124 <code class="function">eglCreatePbufferFromClientBuffer</code> creates an 125 off-screen pixel buffer surface and returns its handle. If 126 <code class="function">eglCreatePbufferFromClientBuffer</code> fails to create 127 a pixel buffer surface, <code class="constant">EGL_NO_SURFACE</code> 128 is returned. 129 </p> 130 <p> 131 The new pixel buffer surface is similar to a pixel buffer 132 created with 133 <a class="citerefentry" href="eglCreatePbufferSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePbufferSurface</span></span></a>, 134 but storage for the color buffer is provided by a client API 135 buffer. Other buffer required by 136 <em class="parameter"><code>config</code></em>, such as depth, stencil, and 137 alpha mask, are allocated by EGL. 138 </p> 139 <p> 140 <em class="parameter"><code>buftype</code></em> must be 141 <code class="constant">EGL_OPENVG_IMAGE</code>, corresponding to an 142 OpenVG <span class="type">VGImage</span> buffer. 143 <em class="parameter"><code>buffer</code></em> must be a valid 144 <span class="type">VGImage</span> handle in the current OpenVG context, 145 cast into the type <span class="type">EGLClientBuffer</span>. 146 </p> 147 <p> 148 The height, width,, OpenVG alpha format, and OpenVG 149 colorspace (surface attributes 150 <code class="constant">EGL_HEIGHT</code>, 151 <code class="constant">EGL_WIDTH</code>, 152 <code class="constant">EGL_VG_ALPHA_FORMAT</code>, and 153 <code class="constant">EGL_VG_COLORSPACE</code>, respectively) of the 154 resulting surface are determined by the size and format of 155 <em class="parameter"><code>buffer</code></em>. 156 </p> 157 <p> 158 Surface attributes are specified as a list of 159 attribute-value pairs, terminated with 160 <code class="constant">EGL_NONE</code>. Accepted attributes are: 161 </p> 162 <div class="variablelist"> 163 <dl class="variablelist"> 164 <dt> 165 <span class="term"> 166 <code class="constant">EGL_MIPMAP_TEXTURE</code> 167 </span> 168 </dt> 169 <dd> 170 <p> 171 Specifies whether storage for mipmaps should be 172 allocated. Space for mipmaps will be set aside if 173 the attribute value is <code class="constant">EGL_TRUE</code> 174 and <code class="constant">EGL_TEXTURE_FORMAT</code> is not 175 <code class="constant">EGL_NO_TEXTURE</code>. The default 176 value is <code class="constant">EGL_FALSE</code>. 177 </p> 178 </dd> 179 <dt> 180 <span class="term"> 181 <code class="constant">EGL_TEXTURE_FORMAT</code> 182 </span> 183 </dt> 184 <dd> 185 <p> 186 Specifies the format of the texture that will be 187 created when a pbuffer is bound to a texture map. 188 Possible values are 189 <code class="constant">EGL_NO_TEXTURE</code>, 190 <code class="constant">EGL_TEXTURE_RGB</code>, and 191 <code class="constant">EGL_TEXTURE_RGBA</code>. The default 192 value is <code class="constant">EGL_NO_TEXTURE</code>. 193 </p> 194 </dd> 195 <dt> 196 <span class="term"> 197 <code class="constant">EGL_TEXTURE_TARGET</code> 198 </span> 199 </dt> 200 <dd> 201 <p> 202 Specifies the target for the texture that will be 203 created when the pbuffer is created with a texture 204 format of <code class="constant">EGL_TEXTURE_RGB</code> or 205 <code class="constant">EGL_TEXTURE_RGBA</code>. Possible 206 values are <code class="constant">EGL_NO_TEXTURE</code>, or 207 <code class="constant">EGL_TEXTURE_2D</code>. The default 208 value is <code class="constant">EGL_NO_TEXTURE</code>. 209 </p> 210 </dd> 211 </dl> 212 </div> 213 <p> 214 Any EGL rendering context that was created with respect to 215 <em class="parameter"><code>config</code></em> can be used to render into the 216 surface. Use 217 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a> 218 to attach an EGL rendering context to the surface. 219 </p> 220 <p> 221 Use 222 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 223 to retrieve the dimensions of the allocated pixel buffer 224 surface or the ID of <em class="parameter"><code>config</code></em>. 225 </p> 226 <p> 227 Use <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a> 228 to destroy the surface. 229 </p> 230 </div> 231 <div class="refsect1" id="notes"> 232 <h2>Notes</h2> 233 <p> 234 <code class="function">eglCreatePbufferFromClientBuffer</code> is 235 supported only if the EGL version is 1.2 or greater, and if 236 the EGL implementation supports the OpenVG client API. 237 </p> 238 <p> 239 Currently 240 <code class="function">eglCreatePbufferFromClientBuffer</code> only 241 supports binding OpenVG <span class="type">VGImage</span> buffers to 242 pixel buffers. While other client API resources could be 243 supported in the future, mechanisms such as OpenGL ES 244 framebuffer objects, and the family of EGL and client API 245 extensions for defining and using <span class="type">EGLImageKHR</span> 246 images, are a more flexible and general framework to satisfy 247 most of the same needs. 248 </p> 249 <p> 250 If the value of <em class="parameter"><code>config</code></em> attribute 251 <code class="constant">EGL_TEXTURE_FORMAT</code> is not 252 <code class="constant">EGL_NO_TEXTURE</code>, then the pbuffer width 253 and height specify the size of the level zero texture image 254 </p> 255 <p> 256 If <code class="constant">EGL_LARGEST_PBUFFER</code> is specified and 257 if the pbuffer will be used as a texture (i.e. the value of 258 <code class="constant">EGL_TEXTURE_TARGET</code> is 259 <code class="constant">EGL_TEXTURE_2D</code>, and the value of 260 <code class="constant">EGL_TEXTURE FORMAT</code> is 261 <code class="constant">EGL_TEXTURE_RGB</code> or 262 <code class="constant">EGL_TEXTURE_RGBA</code>), then the aspect 263 ratio will be preserved and the new width and height will be 264 valid sizes for the texture target (e.g. if the underlying 265 OpenGL ES implementation does not support non-power-of-two 266 textures, both the width and height will be a power of 2). 267 </p> 268 <p> 269 The contents of the depth and stencil buffers may not be 270 preserved when rendering a texture to the pbuffer and 271 switching which image of the texture is rendered to (e.g., 272 switching from rendering one mipmap level to rendering 273 another). 274 </p> 275 <p> 276 Binding client API buffers to EGL pbuffers create the 277 possibility of race conditions, and of buffers being deleted 278 through one API while still in use in another API. To avoid 279 these problems, a number of constraints apply to bound 280 client API buffers: 281 </p> 282 <div class="orderedlist"> 283 <ol class="orderedlist" type="1"> 284 <li class="listitem"> 285 <p> 286 Bound buffers may be used exclusively by either EGL, 287 or the client API that originally created them. For 288 example, if a <span class="type">VGImage</span> is bound to a 289 pbuffer, and that pbuffer is bound to any client API 290 rendering context, then the <span class="type">VGImage</span> may 291 not be used as the explicit source or destination of 292 any OpenVG operation. Errors resulting from such use 293 are described in client API specifications. 294 Similarly, while a <span class="type">VGImage</span> is in use by 295 OpenVG, the pbuffer it is bound to may not be made 296 current to any client API context using 297 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>. 298 </p> 299 </li> 300 <li class="listitem"> 301 <p> 302 Binding a buffer creates an additional reference to 303 it, and implementations must respect outstanding 304 references when destroying objects. For example, if 305 a <span class="type">VGImage</span> is bound to a pbuffer, 306 destroying the image with 307 <code class="function">vgDestroyImage</code> will not free 308 the underlying buffer, because it is still in use by 309 EGL. However, following 310 <code class="function">vgDestroyImage</code> the buffer may 311 only be referred to via the EGL pbuffer handle, 312 since the OpenVG handle to that buffer no longer 313 exists. Similarly, destroying the pbuffer with 314 <code class="function">eglDestroySurface</code> will not free 315 the underlying buffer, because it is still in use by 316 OpenVG . However, following 317 <code class="function">eglDestroySurface</code> the buffer 318 may only be referred to via the OpenVG 319 <span class="type">VGImage</span> handle, since the EGL pbuffer 320 handle no longer exists. 321 </p> 322 </li> 323 </ol> 324 </div> 325 <p> 326 </p> 327 </div> 328 <div class="refsect1" id="errors"> 329 <h2>Errors</h2> 330 <p> 331 <code class="constant">EGL_NO_SURFACE</code> is returned if creation of 332 the context fails. 333 </p> 334 <p> 335 <code class="constant">EGL_BAD_DISPLAY</code> is generated if 336 <em class="parameter"><code>display</code></em> is not an EGL display connection. 337 </p> 338 <p> 339 <code class="constant">EGL_NOT_INITIALIZED</code> is generated if 340 <em class="parameter"><code>display</code></em> has not been initialized. 341 </p> 342 <p> 343 <code class="constant">EGL_BAD_CONFIG</code> is generated if 344 <em class="parameter"><code>config</code></em> is not an EGL frame buffer configuration. 345 </p> 346 <p> 347 <code class="constant">EGL_BAD_PARAMETER</code> is generated if 348 <em class="parameter"><code>buftype</code></em> is not 349 <code class="constant">EGL_OPENVG_IMAGE</code>, or if 350 <em class="parameter"><code>buffer</code></em> is not a valid handle to a 351 <span class="type">VGImage</span> object in the currently bound OpenVG 352 context. 353 </p> 354 <p> 355 <code class="constant">EGL_BAD_ACCESS</code> is generated if there is 356 no current OpenVG context, or if 357 <em class="parameter"><code>buffer</code></em> is already bound to another 358 pixel buffer or in use by OpenVG as discussed in the Notes 359 section above. 360 </p> 361 <p> 362 <code class="constant">EGL_BAD_ACCESS</code> is generated if the buffers 363 contained in <em class="parameter"><code>buffer</code></em> consist of any 364 <span class="type">EGLImage</span> siblings. 365 </p> 366 <p> 367 <code class="constant">EGL_BAD_ALLOC</code> is generated if there are not 368 enough resources to allocate the new surface. 369 </p> 370 <p> 371 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 372 <em class="parameter"><code>attrib_list</code></em> contains an invalid pixel 373 buffer attribute or if an attribute value is not recognized 374 or out of range. 375 </p> 376 <p> 377 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 378 <em class="parameter"><code>attrib_list</code></em> contains any of the 379 attributes <code class="constant">EGL_MIPMAP_TEXTURE</code>, 380 <code class="constant">EGL_TEXTURE_FORMAT</code>, or 381 <code class="constant">EGL_TEXTURE_TARGET</code>, and 382 <em class="parameter"><code>config</code></em> does not support OpenGL ES 383 rendering (e.g. the EGL version is 1.2 or later, and the 384 <code class="constant">EGL_RENDERABLE_TYPE</code> attribute of 385 <em class="parameter"><code>config</code></em> does not include at least one 386 of <code class="constant">EGL_OPENGL_ES_BIT</code> or 387 <code class="constant">EGL_OPENGL_ES2_BIT</code>). 388 </p> 389 <p> 390 <code class="constant">EGL_BAD_MATCH</code> is generated if 391 <em class="parameter"><code>config</code></em> does not support rendering to 392 pixel buffers (the <code class="constant">EGL_SURFACE_TYPE</code> 393 attribute does not contain 394 <code class="constant">EGL_PBUFFER_BIT</code>). 395 </p> 396 <p> 397 <code class="constant">EGL_BAD_MATCH</code> is generated if the 398 buffers contained in <em class="parameter"><code>buffer</code></em> do not 399 match the bit depths for those buffers specified by 400 <em class="parameter"><code>config</code></em>. 401 </p> 402 <p> 403 <code class="constant">EGL_BAD_MATCH</code> is generated if the 404 <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is not 405 <code class="constant">EGL_NO_TEXTURE</code>, and 406 <code class="constant">EGL_WIDTH</code> and/or 407 <code class="constant">EGL_HEIGHT</code> specify an invalid size 408 (e.g., the texture size is not a power of 2, and the 409 underlying OpenGL ES implementation does not support 410 non-power-of-two textures). 411 </p> 412 <p> 413 <code class="constant">EGL_BAD_MATCH</code> is generated if 414 the <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is 415 <code class="constant">EGL_NO_TEXTURE</code>, and 416 <code class="constant">EGL_TEXTURE_TARGET</code> is something other 417 than <code class="constant">EGL_NO_TEXTURE</code>; or, 418 <code class="constant">EGL_TEXTURE_FORMAT</code> is something other 419 than <code class="constant">EGL_NO_TEXTURE</code>, and 420 <code class="constant">EGL_TEXTURE_TARGET</code> is 421 <code class="constant">EGL_NO_TEXTURE</code>. 422 </p> 423 <p> 424 <code class="constant">EGL_BAD_MATCH</code> is generated if the 425 implementation has additional constraints on which types of 426 client API buffers may be bound to pixel buffer surfaces. 427 For example, it is possible that the OpenVG implementation 428 might not support a <span class="type">VGImage</span> being bound to a 429 pixel buffer which will be used as a mipmapped OpenGL ES 430 texture (e.g. whose <code class="constant">EGL_MIPMAP_TEXTURE</code> 431 attribute is <code class="constant">TRUE</code>). Any such 432 constraints should be documented by the implementation 433 release notes. 434 </p> 435 </div> 436 <div class="refsect1" id="seealso"> 437 <h2>See Also</h2> 438 <p> 439 <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a>, 440 <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a>, 441 <a class="citerefentry" href="eglCreatePbufferSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePbufferSurface</span></span></a>, 442 <a class="citerefentry" href="eglGetConfigs.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetConfigs</span></span></a>, 443 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>, 444 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 445 </p> 446 </div> 447 <p> 448 </p> 449 <div class="refsect3" id="copyright"> 450 <img src="KhronosLogo.jpg"/> 451 <p> 452 Copyright © 2003-2014 The Khronos Group Inc. 453 Permission is hereby granted, free of charge, to any person obtaining a 454 copy of this software and/or associated documentation files (the 455 "Materials"), to deal in the Materials without restriction, including 456 without limitation the rights to use, copy, modify, merge, publish, 457 distribute, sublicense, and/or sell copies of the Materials, and to 458 permit persons to whom the Materials are furnished to do so, subject to 459 the condition that this copyright notice and permission notice shall be included 460 in all copies or substantial portions of the Materials. 461 </p> 462 </div> 463 <p> 464</p> 465 </div> 466 <footer/> 467 </body> 468</html> 469
