1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreateImage"> 2 <info> 3 <copyright> 4 <year>2018</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglCreateImage</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglCreateImage</refname> 14 <refpurpose> 15 Create a new <type>EGLImage</type> object 16 </refpurpose> 17 </refnamediv> 18 <refsynopsisdiv> 19 <title>C Specification</title> 20 <funcsynopsis> 21 <funcprototype> 22 <funcdef>EGLImage <function>eglCreateImage</function></funcdef> 23 <paramdef>(EGLDisplay <parameter>display</parameter></paramdef> 24 <paramdef>EGLContext <parameter>context</parameter></paramdef> 25 <paramdef>EGLenum <parameter>target</parameter></paramdef> 26 <paramdef>EGLClientBuffer <parameter>buffer</parameter></paramdef> 27 <paramdef>const EGLAttrib *<parameter>attrib_list</parameter></paramdef> 28 </funcprototype> 29 </funcsynopsis> 30 </refsynopsisdiv> 31 <refsect1 xml:id="parameters"><title>Parameters</title> 32 <variablelist> 33 <varlistentry> 34 <term><parameter>display</parameter></term> 35 <listitem><para> 36 Specifies the <acronym>EGL</acronym> display connection. 37 </para></listitem> 38 </varlistentry> 39 <varlistentry> 40 <term><parameter>context</parameter></term> 41 <listitem><para> 42 Specifies the client API context for which the image is 43 created. 44 </para></listitem> 45 </varlistentry> 46 <varlistentry> 47 <term><parameter>target</parameter></term> 48 <listitem><para> 49 Specifies the type of resource used as the image source. 50 </para></listitem> 51 </varlistentry> 52 <varlistentry> 53 <term><parameter>buffer</parameter></term> 54 <listitem><para> 55 Specifies the resource to be used as the image source. 56 </para></listitem> 57 </varlistentry> 58 <varlistentry> 59 <term><parameter>attrib_list</parameter></term> 60 <listitem><para> 61 Specifies attributes used to select sub-sections of the 62 resource to be used as the image source. 63 </para></listitem> 64 </varlistentry> 65 </variablelist> 66 </refsect1> 67 <refsect1 xml:id="description"><title>Description</title> 68 <para> 69 <function>eglCreateImage</function> is used to create an 70 <type>EGLImage</type> object from an existing image resource 71 <parameter>buffer</parameter>. <parameter>display</parameter> 72 specifies the EGL display used for this operation. 73 <parameter>context</parameter> specifies the EGL client API 74 context used for this operation, or 75 <constant>EGL_NO_CONTEXT</constant> if a client API context is 76 not required. <parameter>target</parameter> specifies the type 77 of resource being used as the <type>EGLImage</type> source 78 (examples include two-dimensional textures in OpenGL ES contexts 79 and <type>VGImage</type> objects in OpenVG contexts). 80 <parameter>buffer</parameter> is the name (or handle) of a 81 resource to be used as the <type>EGLImage</type> source, cast 82 into the type <type>EGLClientBuffer</type>. 83 <parameter>attrib_list</parameter> is a list of attribute-value 84 pairs which is used to select sub-sections of 85 <parameter>buffer</parameter> for use as the 86 <type>EGLImage</type> source, such as mipmap levels for OpenGL 87 ES texture map resources, as well as behavioral options, such as 88 whether to preserve pixel data during creation. If 89 <parameter>attrib_list</parameter> is 90 non-<constant>NULL</constant>, the last attribute specified in 91 the list must be <constant>EGL_NONE</constant>. 92 </para> 93 <para> 94 The resource specified by <parameter>display</parameter>, 95 <parameter>context</parameter>, <parameter>target</parameter>, 96 <parameter>buffer</parameter>, and 97 <parameter>attrib_list</parameter> must not itself be an 98 <type>EGLImage</type> sibling, or bound to a pbuffer 99 <type>EGLSurface</type> resource 100 (<function>eglBindTexImage</function>, 101 <function>eglCreatePbufferFromClientBuffer</function>). 102 </para> 103 <para> 104 Values accepted for <parameter>target</parameter> are shown in 105 table <xref linkend="tab-imagetarget"/>. 106 </para> 107 <table frame="all" xml:id="tab-imagetarget"> 108 <title> 109 Legal values for <function>eglCreateImage</function> <parameter>target</parameter> 110 </title> 111 <tgroup cols="2" align="left" colsep="1" rowsep="1"> 112 <thead> 113 <row> 114 <entry><parameter>target</parameter></entry> 115 <entry>Notes</entry> 116 </row> 117 </thead> 118 <tbody> 119 <row> 120 <entry><constant>EGL_GL_TEXTURE_2D</constant></entry> 121 <entry>Used for GL 2D texture images</entry> 122 </row> 123 <row> 124 <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant></entry> 125 <entry>Used for the +X face of GL cubemap texture images</entry> 126 </row> 127 <row> 128 <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant></entry> 129 <entry>Used for the -X face of GL cubemap texture images</entry> 130 </row> 131 <row> 132 <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant></entry> 133 <entry>Used for the +Y face of GL cubemap texture images</entry> 134 </row> 135 <row> 136 <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant></entry> 137 <entry>Used for the -Y face of GL cubemap texture images</entry> 138 </row> 139 <row> 140 <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant></entry> 141 <entry>Used for the +Z face of GL cubemap texture images</entry> 142 </row> 143 <row> 144 <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant></entry> 145 <entry>Used for the -Z face of GL cubemap texture images</entry> 146 </row> 147 <row> 148 <entry><constant>EGL_GL_TEXTURE_3D</constant></entry> 149 <entry>Used for OpenGL and OpenGL ES 3D texture images</entry> 150 </row> 151 <row> 152 <entry><constant>EGL_GL_RENDERBUFFER</constant></entry> 153 <entry>Used for OpenGL and OpenGL ES renderbuffer images</entry> 154 </row> 155 </tbody> 156 </tgroup> 157 </table> 158 <para> 159 Attribute names accepted in <parameter>attrib_list</parameter> 160 are shown in table <xref linkend="tab-imageattr"/>, together 161 with the <parameter>target</parameter> for which each attribute 162 name is valid, and the default value used for each attribute if 163 it is not included in <parameter>attrib_list</parameter>. 164 </para> 165 <table frame="all" xml:id="tab-imageattr"> 166 <title> 167 Legal attributes for <function>eglCreateImage</function> 168 <parameter>attrib_list</parameter> parameter 169 </title> 170 <tgroup cols="4" align="left" colsep="1" rowsep="1"> 171 <thead> 172 <row> 173 <entry><parameter>target</parameter></entry> 174 <entry>Notes</entry> 175 </row> 176 </thead> 177 <tbody> 178 <row> 179 <entry>Attribute</entry> 180 <entry>Description</entry> 181 <entry>Valid <parameter>target</parameter>s</entry> 182 <entry>Default Value</entry> 183 </row> 184 <row> 185 <entry><constant>EGL_NONE</constant></entry> 186 <entry>Marks the end of the attribute-value list</entry> 187 <entry>All</entry> 188 <entry>N/A</entry> 189 </row> 190 <row> 191 <entry><constant>EGL_GL_TEXTURE_LEVEL</constant></entry> 192 <entry> 193 Specifies the mipmap level used as the 194 <type>EGLImage</type> source. Must be part of 195 the complete texture object 196 <parameter>buffer</parameter> 197 </entry> 198 <entry> 199 <constant>EGL_GL_TEXTURE_2D</constant>, 200 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, or 201 <constant>EGL_GL_TEXTURE_3D</constant> 202 </entry> 203 <entry>0</entry> 204 </row> 205 <row> 206 <entry><constant>EGL_GL_TEXTURE_ZOFFSET</constant></entry> 207 <entry> 208 Specifies the depth offset of the image to use 209 as the <type>EGLImage</type> source. Must be 210 part of the complete texture object 211 <parameter>buffer</parameter> 212 </entry> 213 <entry><constant>EGL_GL_TEXTURE_3D</constant></entry> 214 <entry>0</entry> 215 </row> 216 <row> 217 <entry><constant>EGL_IMAGE_PRESERVED</constant></entry> 218 <entry>Whether to preserve pixel data</entry> 219 <entry>All</entry> 220 <entry><constant>EGL_FALSE</constant></entry> 221 </row> 222 </tbody> 223 </tgroup> 224 </table> 225 <para> 226 <function>eglCreateImage</function> returns an 227 <type>EGLImage</type> object corresponding to the image data 228 specified by <parameter>display</parameter>, 229 <parameter>context</parameter>, <parameter>target</parameter>, 230 <parameter>buffer</parameter> and 231 <parameter>attrib_list</parameter> which may be referenced by 232 client API operations. 233 </para> 234 <para> 235 If <parameter>target</parameter> is 236 <constant>EGL_GL_TEXTURE_2D</constant>, 237 <constant>EGL_GL_TEXTURE_3D</constant>, 238 <constant>EGL_GL_RENDERBUFFER</constant>, 239 <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>, 240 <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>, 241 <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>, 242 <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>, 243 <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or 244 <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, 245 <parameter>display</parameter> must be a valid 246 <type>EGLDisplay</type>, and <parameter>context</parameter> must 247 be a valid OpenGL or OpenGL ES API context on that display. 248 </para> 249 <para> 250 If <parameter>target</parameter> is 251 <constant>EGL_GL_TEXTURE_2D</constant>, 252 <parameter>buffer</parameter> must be the name of a nonzero, 253 <constant>GL_TEXTURE_2D</constant> target texture object, cast 254 into the type <type>EGLClientBuffer</type>. 255 </para> 256 <para> 257 If <parameter>target</parameter> is one of the 258 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> enumerants, 259 <parameter>buffer</parameter> must be the name of a nonzero, 260 <constant>GL_TEXTURE_CUBE_MAP</constant> (or equivalent in GL 261 extensions) target texture object, cast into the type 262 <type>EGLClientBuffer</type>. 263 </para> 264 <para> 265 If <parameter>target</parameter> is 266 <constant>EGL_GL_TEXTURE_3D</constant>, 267 <parameter>buffer</parameter> must be the name of a nonzero, 268 <constant>GL_TEXTURE_3D</constant> (or equivalent in GL 269 extensions) target texture object, cast into the type 270 <type>EGLClientBuffer</type>. 271 </para> 272 <para> 273 <parameter>attrib_list</parameter> should specify the mipmap 274 level (<constant>EGL_GL_TEXTURE_LEVEL</constant>) and, where 275 applicable, z-offset 276 (<constant>EGL_GL_TEXTURE_ZOFFSET</constant>) which will be used 277 as the <type>EGLImage</type> source; If not specified, the 278 default values listed in table <xref linkend="tab-imageattr"/> 279 will be used instead. Additional values specified in are 280 ignored. 281 </para> 282 <para> 283 There must exist some levels <emphasis>x</emphasis> and 284 <emphasis>y</emphasis> such that the mipmap level requested lies 285 between <emphasis>x</emphasis> and <emphasis>y</emphasis> 286 (inclusive), the texture would be mipmap complete were 287 <emphasis>x</emphasis> substituted for the base level and 288 <emphasis>y</emphasis> substituted for the max level, and all 289 levels less than <emphasis>x</emphasis> or greater than 290 <emphasis>y</emphasis> are unspecified. For cubemaps a single 291 pair <emphasis>x</emphasis> and <emphasis>y</emphasis> must 292 apply to all faces. For three-dimensional textures, the 293 specified z-offset must be smaller than the depth of the 294 specified mipmap level. 295 </para> 296 <para> 297 If <parameter>target</parameter> is 298 <constant>EGL_GL_RENDERBUFFER</constant>, 299 <parameter>buffer</parameter> must be the name of a complete, 300 nonzero, non-multisampled <constant>GL_RENDERBUFFER</constant> 301 (or equivalent in extensions) target object, cast into the type 302 <type>EGLClientBuffer</type>. Values specified in 303 <parameter>attrib_list</parameter> are ignored. 304 </para> 305 <para> 306 If the value of attribute 307 <constant>EGL_IMAGE_PRESERVED</constant> is 308 <constant>EGL_FALSE</constant> (the default), then all pixel 309 data values associated with <parameter>buffer</parameter> will 310 be undefined after <function>eglCreateImage</function> returns. 311 </para> 312 <para> 313 If the value of attribute 314 <constant>EGL_IMAGE_PRESERVED</constant> is 315 <constant>EGL_TRUE</constant>, then all pixel data values 316 associated with <parameter>buffer</parameter> are preserved. 317 </para> 318 </refsect1> 319 <refsect1 xml:id="errors"><title>Errors</title> 320 <para> 321 <function>eglCreateImage</function> returns 322 <constant>EGL_NO_IMAGE</constant> on failure. The contents of 323 <parameter>buffer</parameter> will be unaffected. 324 </para> 325 <para> 326 If <parameter>display</parameter> is not the handle of a valid 327 <type>EGLDisplay</type> object, the error 328 <constant>EGL_BAD_DISPLAY</constant> is generated. 329 </para> 330 <para> 331 If <parameter>context</parameter> is neither the handle of a 332 valid <type>EGLContext</type> object on 333 <parameter>display</parameter> nor 334 <constant>EGL_NO_CONTEXT</constant>, the error 335 <constant>EGL_BAD_CONTEXT</constant> is generated. 336 </para> 337 <para> 338 If <parameter>target</parameter> is not one of the values in 339 table <xref linkend="tab-imagetarget"/>, the error 340 <constant>EGL_BAD_PARAMETER</constant> is generated. 341 </para> 342 <para> 343 If <parameter>target</parameter> is 344 <constant>EGL_GL_TEXTURE_2D</constant>, 345 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, 346 <constant>EGL_GL_RENDERBUFFER</constant> or 347 <constant>EGL_GL_TEXTURE_3D</constant>, and 348 <parameter>display</parameter> is not a valid 349 <type>EGLDisplay</type>, the error 350 <constant>EGL_BAD_DISPLAY</constant> is generated. 351 </para> 352 <para> 353 If <parameter>target</parameter> is 354 <constant>EGL_GL_TEXTURE_2D</constant>, 355 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, 356 <constant>EGL_GL_RENDERBUFFER</constant> or 357 <constant>EGL_GL_TEXTURE_3D</constant>, and 358 <parameter>context</parameter> is not a valid 359 <type>EGLContext</type>, the error 360 <constant>EGL_BAD_CONTEXT</constant> is generated. 361 </para> 362 <para> 363 If <parameter>target</parameter> is 364 <constant>EGL_GL_TEXTURE_2D</constant>, 365 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, 366 <constant>EGL_GL_RENDERBUFFER</constant> or 367 <constant>EGL_GL_TEXTURE_3D</constant>, and 368 <parameter>context</parameter> is not a valid GL context, or 369 does not match the <parameter>display</parameter>, the error 370 <constant>EGL_BAD_MATCH</constant> is generated. 371 </para> 372 <para> 373 If <parameter>target</parameter> is 374 <constant>EGL_GL_TEXTURE_2D</constant>, 375 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or 376 <constant>EGL_GL_TEXTURE_3D</constant> and 377 <parameter>buffer</parameter> is not the name of a texture 378 object of type <parameter>target</parameter>, the error 379 <constant>EGL_BAD_PARAMETER</constant> is generated. 380 </para> 381 <para> 382 If <parameter>target</parameter> is 383 <constant>EGL_GL_RENDERBUFFER</constant> and 384 <parameter>buffer</parameter> is not the name of a renderbuffer 385 object, or if <parameter>buffer</parameter> is the name of a 386 multisampled renderbuffer object, the error 387 <constant>EGL_BAD_PARAMETER</constant> is generated. 388 </para> 389 <para> 390 If <constant>EGL_GL_TEXTURE_LEVEL</constant> is nonzero, 391 <parameter>target</parameter> is 392 <constant>EGL_GL_TEXTURE_2D</constant>, 393 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or 394 <constant>EGL_GL_TEXTURE_3D</constant>, and 395 <parameter>buffer</parameter> is not the name of a complete GL 396 texture object, the error <constant>EGL_BAD_PARAMETER</constant> 397 is generated. 398 </para> 399 <para> 400 If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0, 401 <parameter>target</parameter> is 402 <constant>EGL_GL_TEXTURE_2D</constant>, 403 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or 404 <constant>EGL_GL_TEXTURE_3D</constant>, 405 <parameter>buffer</parameter> is the name of an incomplete GL 406 texture object, and any mipmap levels other than mipmap level 0 407 are specified, the error <constant>EGL_BAD_PARAMETER</constant> 408 is generated. 409 </para> 410 <para> 411 If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0, 412 <parameter>target</parameter> is 413 <constant>EGL_GL_TEXTURE_2D</constant> or 414 <constant>EGL_GL_TEXTURE_3D</constant>, 415 <parameter>buffer</parameter> is not the name of a complete GL 416 texture object, and mipmap level 0 is not specified, the error 417 <constant>EGL_BAD_PARAMETER</constant> is generated. 418 </para> 419 <para> 420 If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0, 421 <parameter>target</parameter> is 422 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, 423 <parameter>buffer</parameter> is not the name of a complete GL 424 texture object, and one or more faces do not have mipmap level 0 425 specified, the error <constant>EGL_BAD_PARAMETER</constant> is 426 generated. 427 </para> 428 <para> 429 If <parameter>target</parameter> is 430 <constant>EGL_GL_TEXTURE_2D</constant>, 431 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, 432 <constant>EGL_GL_RENDERBUFFER</constant> or 433 <constant>EGL_GL_TEXTURE_3D</constant> and 434 <parameter>buffer</parameter> refers to the default GL texture 435 object (0) for the corresponding GL target, the error 436 <constant>EGL_BAD_PARAMETER</constant> is generated. 437 </para> 438 <para> 439 If <parameter>target</parameter> is 440 <constant>EGL_GL_TEXTURE_2D</constant>, 441 <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, or 442 <constant>EGL_GL_TEXTURE_3D</constant>, and the value specified 443 in <parameter>attrib_list</parameter> for 444 <constant>EGL_GL_TEXTURE_LEVEL</constant> is not a valid mipmap 445 level for the specified GL texture object 446 <parameter>buffer</parameter>, the error 447 <constant>EGL_BAD_MATCH</constant> is generated. 448 </para> 449 <para> 450 If <parameter>target</parameter> is 451 <constant>EGL_GL_TEXTURE_3D</constant>, and the value specified 452 in <parameter>attrib_list</parameter> for 453 <constant>EGL_GL_TEXTURE_ZOFFSET</constant> exceeds the depth of 454 the specified mipmap level-of-detail in 455 <parameter>buffer</parameter>, the error 456 <constant>EGL_BAD_PARAMETER</constant> is generated. 457 </para> 458 <para> 459 If an attribute specified in <parameter>attrib_list</parameter> 460 is not one of the attributes shown in table <xref 461 linkend="tab-imageattr"/>, the error 462 <constant>EGL_BAD_PARAMETER</constant> is generated. 463 </para> 464 <para> 465 If an attribute specified in <parameter>attrib_list</parameter> 466 is not a valid attribute for <parameter>target</parameter>, as 467 shown in table <xref linkend="tab-imageattr"/>, the error 468 <constant>EGL_BAD_MATCH</constant> is generated. 469 </para> 470 <para> 471 If the resource specified by <parameter>display</parameter>, 472 <parameter>context</parameter>, <parameter>target</parameter>, 473 <parameter>buffer</parameter> and 474 <parameter>attrib_list</parameter> has an off-screen buffer 475 bound to it (e.g., by a previous call to 476 <function>eglBindTexImage</function>), the error 477 <constant>EGL_BAD_ACCESS</constant> is generated. 478 </para> 479 <para> 480 If the resource specified by <parameter>display</parameter>, 481 <parameter>context</parameter>, <parameter>target</parameter>, 482 <parameter>buffer</parameter> and 483 <parameter>attrib_list</parameter> is bound to an off-screen 484 buffer (e.g., by a previous call to 485 <function>eglCreatePbufferFromClientBuffer</function>), the 486 error <constant>EGL_BAD_ACCESS</constant> is generated. 487 </para> 488 <para> 489 If the resource specified by <parameter>display</parameter>, 490 <parameter>context</parameter>, <parameter>target</parameter>, 491 <parameter>buffer</parameter> and 492 <parameter>attrib_list</parameter> is itself an 493 <type>EGLImage</type> sibling, the error 494 <constant>EGL_BAD_ACCESS</constant> is generated. 495 </para> 496 <para> 497 If insufficient memory is available to complete the specified 498 operation, the error <constant>EGL_BAD_ALLOC</constant> is 499 generated. 500 </para> 501 <para> 502 If the value specified in <parameter>attrib_list</parameter> for 503 <constant>EGL_IMAGE_PRESERVED</constant> is 504 <constant>EGL_TRUE</constant>, and an <type>EGLImage</type> 505 handle cannot be created from the specified resource such that 506 the pixel data values in <parameter>buffer</parameter> are 507 preserved, the error <constant>EGL_BAD_ACCESS</constant> is 508 generated. 509 </para> 510 <para> 511 Note that the success or failure of 512 <function>eglCreateImage</function> should not affect the 513 ability to use <parameter>buffer</parameter> in its original API 514 context (or context share group) (although the pixel data values 515 will be undefined if the command succeeds and the value of 516 <constant>EGL_IMAGE_PRESERVED</constant> is not 517 <constant>EGL_TRUE</constant>). 518 </para> 519 </refsect1> 520 <refsect1 xml:id="lifetime"><title>Lifetime and Usage of <type>EGLImage</type>s</title> 521 <para> 522 Once an <type>EGLImage</type> is created from an 523 <type>EGLImage</type> source, the memory associated with the 524 <type>EGLImage</type> source will remain allocated (and all 525 <type>EGLImage</type> siblings in all client API contexts will 526 be useable) as long as either of the following conditions is 527 true: 528 </para> 529 <para> 530 <itemizedlist> 531 <listitem> 532 <para> 533 Any <type>EGLImage</type> siblings exist in any client 534 API context 535 </para> 536 </listitem> 537 <listitem> 538 <para> 539 The <type>EGLImage</type> object exists inside EGL 540 </para> 541 </listitem> 542 </itemizedlist> 543 </para> 544 <para> 545 The semantics for specifying, deleting and using 546 <type>EGLImage</type> siblings are client API-specific, and are 547 described in the appropriate API specifications. 548 </para> 549 <para> 550 If an application specifies an <type>EGLImage</type> sibling as 551 the destination for rendering and/or pixel download operations 552 (e.g., as an OpenGL or OpenGL ES framebuffer object, 553 <function>glTexSubImage2D</function>, etc.), the modified image 554 results will be observed by all <type>EGLImage</type> siblings 555 in all client API contexts. If multiple client API contexts 556 access <type>EGLImage</type> sibling resources simultaneously, 557 with one or more context modifying the image data, rendering 558 results in all contexts accessing <type>EGLImage</type> siblings 559 are undefined. 560 </para> 561 <para> 562 Respecification and/or deletion of any <type>EGLImage</type> 563 sibling (i.e., both <type>EGLImage</type> source and 564 <type>EGLImage</type> target resources) inside a client API 565 context (by issuing a subsequent call to commands such as 566 <function>glTexImage*</function> or 567 <function>glDeleteTextures</function>, with the 568 <type>EGLImage</type> sibling resource as the target of the 569 operation) affects only that client API context and other 570 contexts within its share group. For an OpenGL or OpenGL ES 571 context, respecification always results in 572 <firstterm>orphaning</firstterm> of the <type>EGLImage</type>, 573 and may also include allocation of additional memory for the 574 respecified resource and/or copying of the <type>EGLImage</type> 575 pixel data. 576 </para> 577 <para> 578 Note: Behavior of other types of client APIs generally follows 579 the OpenGL and OpenGL ES behavior described here, although this 580 is not mandated yet. 581 </para> 582 <para> 583 Operations inside EGL or any client API context which may affect 584 the lifetime of an <type>EGLImage</type> (or the memory 585 allocated for the <type>EGLImage</type>), such as respecifying 586 and/or deleting an <type>EGLImage</type> sibling inside a client 587 API context, must be atomic. 588 </para> 589 <para> 590 Applications may create client API resources from an 591 <type>EGLImage</type> using client API extensions outside the 592 scope of this document (such as 593 <constant>GL_OES_EGL_image</constant>, which creates OpenGL ES 594 texture and renderbuffer objects). If the <type>EGLImage</type> 595 used to create the client resource was created with the 596 <constant>EGL_IMAGE_PRESERVED</constant> attribute set to 597 <constant>EGL_TRUE</constant>, then the pixel data values 598 associated with the image will be preserved after creating the 599 client resource; otherwise, the pixel data values will be 600 undefined. If the <type>EGLImage</type> was created with the 601 <constant>EGL_IMAGE_PRESERVED</constant> attribute set to 602 <constant>EGL_TRUE</constant>, and EGL is unable to create the 603 client resource without modifying the pixel values, then 604 creation will fail and the pixel data values will be preserved. 605 </para> 606 </refsect1> 607 <refsect1 xml:id="notes"><title>Notes</title> 608 <para> 609 <function>eglCreateImage</function> is available only if the EGL 610 version is 1.5 or greater. 611 </para> 612 </refsect1> 613 <refsect1 xml:id="seealso"><title>See Also</title> 614 <para> 615 <citerefentry><refentrytitle>eglBindTexImage</refentrytitle></citerefentry>, 616 <citerefentry><refentrytitle>eglCreatePbufferFromClientBuffer</refentrytitle></citerefentry>, 617 <citerefentry><refentrytitle>eglDestroyImage</refentrytitle></citerefentry>, 618 <function>glDeleteTextures</function>, 619 <function>glTexImage*</function>, 620 <function>glTexSubImage2D</function> 621 </para> 622 </refsect1> 623 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 624</refentry> 625