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