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">eglCreateImage - 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="eglCreateImage"> 11 <div class="titlepage"/> 12 <div class="refnamediv"> 13 <h2>Name</h2> 14 <p>eglCreateImage — 15 Create a new <span class="type">EGLImage</span> object 16 </p> 17 </div> 18 <div class="refsynopsisdiv"> 19 <h2>C Specification</h2> 20 <div class="funcsynopsis"> 21 <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> 22 <tr> 23 <td> 24 <code class="funcdef">EGLImage <strong class="fsfunc">eglCreateImage</strong>(</code> 25 </td> 26 <td>(EGLDisplay <var class="pdparam">display</var>, </td> 27 </tr> 28 <tr> 29 <td> </td> 30 <td>EGLContext <var class="pdparam">context</var>, </td> 31 </tr> 32 <tr> 33 <td> </td> 34 <td>EGLenum <var class="pdparam">target</var>, </td> 35 </tr> 36 <tr> 37 <td> </td> 38 <td>EGLClientBuffer <var class="pdparam">buffer</var>, </td> 39 </tr> 40 <tr> 41 <td> </td> 42 <td>const EGLAttrib *<var class="pdparam">attrib_list</var><code>)</code>;</td> 43 </tr> 44 </table> 45 <div class="funcprototype-spacer"> </div> 46 </div> 47 </div> 48 <div class="refsect1" id="parameters"> 49 <h2>Parameters</h2> 50 <div class="variablelist"> 51 <dl class="variablelist"> 52 <dt> 53 <span class="term"> 54 <em class="parameter"> 55 <code>display</code> 56 </em> 57 </span> 58 </dt> 59 <dd> 60 <p> 61 Specifies the <abbr class="acronym">EGL</abbr> display connection. 62 </p> 63 </dd> 64 <dt> 65 <span class="term"> 66 <em class="parameter"> 67 <code>context</code> 68 </em> 69 </span> 70 </dt> 71 <dd> 72 <p> 73 Specifies the client API context for which the image is 74 created. 75 </p> 76 </dd> 77 <dt> 78 <span class="term"> 79 <em class="parameter"> 80 <code>target</code> 81 </em> 82 </span> 83 </dt> 84 <dd> 85 <p> 86 Specifies the type of resource used as the image source. 87 </p> 88 </dd> 89 <dt> 90 <span class="term"> 91 <em class="parameter"> 92 <code>buffer</code> 93 </em> 94 </span> 95 </dt> 96 <dd> 97 <p> 98 Specifies the resource to be used as the image source. 99 </p> 100 </dd> 101 <dt> 102 <span class="term"> 103 <em class="parameter"> 104 <code>attrib_list</code> 105 </em> 106 </span> 107 </dt> 108 <dd> 109 <p> 110 Specifies attributes used to select sub-sections of the 111 resource to be used as the image source. 112 </p> 113 </dd> 114 </dl> 115 </div> 116 </div> 117 <div class="refsect1" id="description"> 118 <h2>Description</h2> 119 <p> 120 <code class="function">eglCreateImage</code> is used to create an 121 <span class="type">EGLImage</span> object from an existing image resource 122 <em class="parameter"><code>buffer</code></em>. <em class="parameter"><code>display</code></em> 123 specifies the EGL display used for this operation. 124 <em class="parameter"><code>context</code></em> specifies the EGL client API 125 context used for this operation, or 126 <code class="constant">EGL_NO_CONTEXT</code> if a client API context is 127 not required. <em class="parameter"><code>target</code></em> specifies the type 128 of resource being used as the <span class="type">EGLImage</span> source 129 (examples include two-dimensional textures in OpenGL ES contexts 130 and <span class="type">VGImage</span> objects in OpenVG contexts). 131 <em class="parameter"><code>buffer</code></em> is the name (or handle) of a 132 resource to be used as the <span class="type">EGLImage</span> source, cast 133 into the type <span class="type">EGLClientBuffer</span>. 134 <em class="parameter"><code>attrib_list</code></em> is a list of attribute-value 135 pairs which is used to select sub-sections of 136 <em class="parameter"><code>buffer</code></em> for use as the 137 <span class="type">EGLImage</span> source, such as mipmap levels for OpenGL 138 ES texture map resources, as well as behavioral options, such as 139 whether to preserve pixel data during creation. If 140 <em class="parameter"><code>attrib_list</code></em> is 141 non-<code class="constant">NULL</code>, the last attribute specified in 142 the list must be <code class="constant">EGL_NONE</code>. 143 </p> 144 <p> 145 The resource specified by <em class="parameter"><code>display</code></em>, 146 <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, 147 <em class="parameter"><code>buffer</code></em>, and 148 <em class="parameter"><code>attrib_list</code></em> must not itself be an 149 <span class="type">EGLImage</span> sibling, or bound to a pbuffer 150 <span class="type">EGLSurface</span> resource 151 (<code class="function">eglBindTexImage</code>, 152 <code class="function">eglCreatePbufferFromClientBuffer</code>). 153 </p> 154 <p> 155 Values accepted for <em class="parameter"><code>target</code></em> are shown in 156 table <a class="xref" href="#tab-imagetarget" title="Table 1. Legal values for eglCreateImage target">Table 1, “ 157 Legal values for <code class="function">eglCreateImage</code> <em class="parameter"><code>target</code></em> 158 ”</a>. 159 </p> 160 <div class="table" id="tab-imagetarget"> 161 <div class="table-title">Table 1. 162 Legal values for <code class="function">eglCreateImage</code> <em class="parameter"><code>target</code></em> 163 </div> 164 <div class="table-contents"> 165 <table style="border-collapse: collapse; border-top: 2px solid ; border-bottom: 2px solid ; border-left: 2px solid ; border-right: 2px solid ; "> 166 <colgroup> 167 <col/> 168 <col/> 169 </colgroup> 170 <thead> 171 <tr> 172 <th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 173 <em class="parameter"> 174 <code>target</code> 175 </em> 176 </th> 177 <th style="text-align: left; border-bottom: 2px solid ; ">Notes</th> 178 </tr> 179 </thead> 180 <tbody> 181 <tr> 182 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 183 <code class="constant">EGL_GL_TEXTURE_2D</code> 184 </td> 185 <td style="text-align: left; border-bottom: 2px solid ; ">Used for GL 2D texture images</td> 186 </tr> 187 <tr> 188 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 189 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</code> 190 </td> 191 <td style="text-align: left; border-bottom: 2px solid ; ">Used for the +X face of GL cubemap texture images</td> 192 </tr> 193 <tr> 194 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 195 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</code> 196 </td> 197 <td style="text-align: left; border-bottom: 2px solid ; ">Used for the -X face of GL cubemap texture images</td> 198 </tr> 199 <tr> 200 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 201 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</code> 202 </td> 203 <td style="text-align: left; border-bottom: 2px solid ; ">Used for the +Y face of GL cubemap texture images</td> 204 </tr> 205 <tr> 206 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 207 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</code> 208 </td> 209 <td style="text-align: left; border-bottom: 2px solid ; ">Used for the -Y face of GL cubemap texture images</td> 210 </tr> 211 <tr> 212 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 213 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</code> 214 </td> 215 <td style="text-align: left; border-bottom: 2px solid ; ">Used for the +Z face of GL cubemap texture images</td> 216 </tr> 217 <tr> 218 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 219 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</code> 220 </td> 221 <td style="text-align: left; border-bottom: 2px solid ; ">Used for the -Z face of GL cubemap texture images</td> 222 </tr> 223 <tr> 224 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 225 <code class="constant">EGL_GL_TEXTURE_3D</code> 226 </td> 227 <td style="text-align: left; border-bottom: 2px solid ; ">Used for OpenGL and OpenGL ES 3D texture images</td> 228 </tr> 229 <tr> 230 <td style="text-align: left; border-right: 2px solid ; "> 231 <code class="constant">EGL_GL_RENDERBUFFER</code> 232 </td> 233 <td style="text-align: left; ">Used for OpenGL and OpenGL ES renderbuffer images</td> 234 </tr> 235 </tbody> 236 </table> 237 </div> 238 </div> 239 <br class="table-break"/> 240 <p> 241 Attribute names accepted in <em class="parameter"><code>attrib_list</code></em> 242 are shown in table <a class="xref" href="#tab-imageattr" title="Table 2. Legal attributes for eglCreateImage attrib_list parameter">Table 2, “ 243 Legal attributes for <code class="function">eglCreateImage</code> 244 <em class="parameter"><code>attrib_list</code></em> parameter 245 ”</a>, together 246 with the <em class="parameter"><code>target</code></em> for which each attribute 247 name is valid, and the default value used for each attribute if 248 it is not included in <em class="parameter"><code>attrib_list</code></em>. 249 </p> 250 <div class="table" id="tab-imageattr"> 251 <div class="table-title">Table 2. 252 Legal attributes for <code class="function">eglCreateImage</code> 253 <em class="parameter"><code>attrib_list</code></em> parameter 254 </div> 255 <div class="table-contents"> 256 <table style="border-collapse: collapse; border-top: 2px solid ; border-bottom: 2px solid ; border-left: 2px solid ; border-right: 2px solid ; "> 257 <colgroup> 258 <col/> 259 <col/> 260 <col/> 261 <col/> 262 </colgroup> 263 <thead> 264 <tr> 265 <th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 266 <em class="parameter"> 267 <code>target</code> 268 </em> 269 </th> 270 <th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Notes</th> 271 <td style="border-right: 2px solid ; border-bottom: 2px solid ; " class="auto-generated"> </td> 272 <td style="border-bottom: 2px solid ; " class="auto-generated"> </td> 273 </tr> 274 </thead> 275 <tbody> 276 <tr> 277 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Attribute</td> 278 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Description</td> 279 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Valid <em class="parameter"><code>target</code></em>s</td> 280 <td style="text-align: left; border-bottom: 2px solid ; ">Default Value</td> 281 </tr> 282 <tr> 283 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 284 <code class="constant">EGL_NONE</code> 285 </td> 286 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Marks the end of the attribute-value list</td> 287 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">All</td> 288 <td style="text-align: left; border-bottom: 2px solid ; ">N/A</td> 289 </tr> 290 <tr> 291 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 292 <code class="constant">EGL_GL_TEXTURE_LEVEL</code> 293 </td> 294 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 295 Specifies the mipmap level used as the 296 <span class="type">EGLImage</span> source. Must be part of 297 the complete texture object 298 <em class="parameter"><code>buffer</code></em> 299 </td> 300 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 301 <code class="constant">EGL_GL_TEXTURE_2D</code>, 302 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, or 303 <code class="constant">EGL_GL_TEXTURE_3D</code> 304 </td> 305 <td style="text-align: left; border-bottom: 2px solid ; ">0</td> 306 </tr> 307 <tr> 308 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 309 <code class="constant">EGL_GL_TEXTURE_ZOFFSET</code> 310 </td> 311 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 312 Specifies the depth offset of the image to use 313 as the <span class="type">EGLImage</span> source. Must be 314 part of the complete texture object 315 <em class="parameter"><code>buffer</code></em> 316 </td> 317 <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> 318 <code class="constant">EGL_GL_TEXTURE_3D</code> 319 </td> 320 <td style="text-align: left; border-bottom: 2px solid ; ">0</td> 321 </tr> 322 <tr> 323 <td style="text-align: left; border-right: 2px solid ; "> 324 <code class="constant">EGL_IMAGE_PRESERVED</code> 325 </td> 326 <td style="text-align: left; border-right: 2px solid ; ">Whether to preserve pixel data</td> 327 <td style="text-align: left; border-right: 2px solid ; ">All</td> 328 <td style="text-align: left; "> 329 <code class="constant">EGL_FALSE</code> 330 </td> 331 </tr> 332 </tbody> 333 </table> 334 </div> 335 </div> 336 <br class="table-break"/> 337 <p> 338 <code class="function">eglCreateImage</code> returns an 339 <span class="type">EGLImage</span> object corresponding to the image data 340 specified by <em class="parameter"><code>display</code></em>, 341 <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, 342 <em class="parameter"><code>buffer</code></em> and 343 <em class="parameter"><code>attrib_list</code></em> which may be referenced by 344 client API operations. 345 </p> 346 <p> 347 If <em class="parameter"><code>target</code></em> is 348 <code class="constant">EGL_GL_TEXTURE_2D</code>, 349 <code class="constant">EGL_GL_TEXTURE_3D</code>, 350 <code class="constant">EGL_GL_RENDERBUFFER</code>, 351 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</code>, 352 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</code>, 353 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</code>, 354 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</code>, 355 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</code>, or 356 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</code>, 357 <em class="parameter"><code>display</code></em> must be a valid 358 <span class="type">EGLDisplay</span>, and <em class="parameter"><code>context</code></em> must 359 be a valid OpenGL or OpenGL ES API context on that display. 360 </p> 361 <p> 362 If <em class="parameter"><code>target</code></em> is 363 <code class="constant">EGL_GL_TEXTURE_2D</code>, 364 <em class="parameter"><code>buffer</code></em> must be the name of a nonzero, 365 <code class="constant">GL_TEXTURE_2D</code> target texture object, cast 366 into the type <span class="type">EGLClientBuffer</span>. 367 </p> 368 <p> 369 If <em class="parameter"><code>target</code></em> is one of the 370 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> enumerants, 371 <em class="parameter"><code>buffer</code></em> must be the name of a nonzero, 372 <code class="constant">GL_TEXTURE_CUBE_MAP</code> (or equivalent in GL 373 extensions) target texture object, cast into the type 374 <span class="type">EGLClientBuffer</span>. 375 </p> 376 <p> 377 If <em class="parameter"><code>target</code></em> is 378 <code class="constant">EGL_GL_TEXTURE_3D</code>, 379 <em class="parameter"><code>buffer</code></em> must be the name of a nonzero, 380 <code class="constant">GL_TEXTURE_3D</code> (or equivalent in GL 381 extensions) target texture object, cast into the type 382 <span class="type">EGLClientBuffer</span>. 383 </p> 384 <p> 385 <em class="parameter"><code>attrib_list</code></em> should specify the mipmap 386 level (<code class="constant">EGL_GL_TEXTURE_LEVEL</code>) and, where 387 applicable, z-offset 388 (<code class="constant">EGL_GL_TEXTURE_ZOFFSET</code>) which will be used 389 as the <span class="type">EGLImage</span> source; If not specified, the 390 default values listed in table <a class="xref" href="#tab-imageattr" title="Table 2. Legal attributes for eglCreateImage attrib_list parameter">Table 2, “ 391 Legal attributes for <code class="function">eglCreateImage</code> 392 <em class="parameter"><code>attrib_list</code></em> parameter 393 ”</a> 394 will be used instead. Additional values specified in are 395 ignored. 396 </p> 397 <p> 398 There must exist some levels <span class="emphasis"><em>x</em></span> and 399 <span class="emphasis"><em>y</em></span> such that the mipmap level requested lies 400 between <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>y</em></span> 401 (inclusive), the texture would be mipmap complete were 402 <span class="emphasis"><em>x</em></span> substituted for the base level and 403 <span class="emphasis"><em>y</em></span> substituted for the max level, and all 404 levels less than <span class="emphasis"><em>x</em></span> or greater than 405 <span class="emphasis"><em>y</em></span> are unspecified. For cubemaps a single 406 pair <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>y</em></span> must 407 apply to all faces. For three-dimensional textures, the 408 specified z-offset must be smaller than the depth of the 409 specified mipmap level. 410 </p> 411 <p> 412 If <em class="parameter"><code>target</code></em> is 413 <code class="constant">EGL_GL_RENDERBUFFER</code>, 414 <em class="parameter"><code>buffer</code></em> must be the name of a complete, 415 nonzero, non-multisampled <code class="constant">GL_RENDERBUFFER</code> 416 (or equivalent in extensions) target object, cast into the type 417 <span class="type">EGLClientBuffer</span>. Values specified in 418 <em class="parameter"><code>attrib_list</code></em> are ignored. 419 </p> 420 <p> 421 If the value of attribute 422 <code class="constant">EGL_IMAGE_PRESERVED</code> is 423 <code class="constant">EGL_FALSE</code> (the default), then all pixel 424 data values associated with <em class="parameter"><code>buffer</code></em> will 425 be undefined after <code class="function">eglCreateImage</code> returns. 426 </p> 427 <p> 428 If the value of attribute 429 <code class="constant">EGL_IMAGE_PRESERVED</code> is 430 <code class="constant">EGL_TRUE</code>, then all pixel data values 431 associated with <em class="parameter"><code>buffer</code></em> are preserved. 432 </p> 433 </div> 434 <div class="refsect1" id="errors"> 435 <h2>Errors</h2> 436 <p> 437 <code class="function">eglCreateImage</code> returns 438 <code class="constant">EGL_NO_IMAGE</code> on failure. The contents of 439 <em class="parameter"><code>buffer</code></em> will be unaffected. 440 </p> 441 <p> 442 If <em class="parameter"><code>display</code></em> is not the handle of a valid 443 <span class="type">EGLDisplay</span> object, the error 444 <code class="constant">EGL_BAD_DISPLAY</code> is generated. 445 </p> 446 <p> 447 If <em class="parameter"><code>context</code></em> is neither the handle of a 448 valid <span class="type">EGLContext</span> object on 449 <em class="parameter"><code>display</code></em> nor 450 <code class="constant">EGL_NO_CONTEXT</code>, the error 451 <code class="constant">EGL_BAD_CONTEXT</code> is generated. 452 </p> 453 <p> 454 If <em class="parameter"><code>target</code></em> is not one of the values in 455 table <a class="xref" href="#tab-imagetarget" title="Table 1. Legal values for eglCreateImage target">Table 1, “ 456 Legal values for <code class="function">eglCreateImage</code> <em class="parameter"><code>target</code></em> 457 ”</a>, the error 458 <code class="constant">EGL_BAD_PARAMETER</code> is generated. 459 </p> 460 <p> 461 If <em class="parameter"><code>target</code></em> is 462 <code class="constant">EGL_GL_TEXTURE_2D</code>, 463 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, 464 <code class="constant">EGL_GL_RENDERBUFFER</code> or 465 <code class="constant">EGL_GL_TEXTURE_3D</code>, and 466 <em class="parameter"><code>display</code></em> is not a valid 467 <span class="type">EGLDisplay</span>, the error 468 <code class="constant">EGL_BAD_DISPLAY</code> is generated. 469 </p> 470 <p> 471 If <em class="parameter"><code>target</code></em> is 472 <code class="constant">EGL_GL_TEXTURE_2D</code>, 473 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, 474 <code class="constant">EGL_GL_RENDERBUFFER</code> or 475 <code class="constant">EGL_GL_TEXTURE_3D</code>, and 476 <em class="parameter"><code>context</code></em> is not a valid 477 <span class="type">EGLContext</span>, the error 478 <code class="constant">EGL_BAD_CONTEXT</code> is generated. 479 </p> 480 <p> 481 If <em class="parameter"><code>target</code></em> is 482 <code class="constant">EGL_GL_TEXTURE_2D</code>, 483 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, 484 <code class="constant">EGL_GL_RENDERBUFFER</code> or 485 <code class="constant">EGL_GL_TEXTURE_3D</code>, and 486 <em class="parameter"><code>context</code></em> is not a valid GL context, or 487 does not match the <em class="parameter"><code>display</code></em>, the error 488 <code class="constant">EGL_BAD_MATCH</code> is generated. 489 </p> 490 <p> 491 If <em class="parameter"><code>target</code></em> is 492 <code class="constant">EGL_GL_TEXTURE_2D</code>, 493 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> or 494 <code class="constant">EGL_GL_TEXTURE_3D</code> and 495 <em class="parameter"><code>buffer</code></em> is not the name of a texture 496 object of type <em class="parameter"><code>target</code></em>, the error 497 <code class="constant">EGL_BAD_PARAMETER</code> is generated. 498 </p> 499 <p> 500 If <em class="parameter"><code>target</code></em> is 501 <code class="constant">EGL_GL_RENDERBUFFER</code> and 502 <em class="parameter"><code>buffer</code></em> is not the name of a renderbuffer 503 object, or if <em class="parameter"><code>buffer</code></em> is the name of a 504 multisampled renderbuffer object, the error 505 <code class="constant">EGL_BAD_PARAMETER</code> is generated. 506 </p> 507 <p> 508 If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is nonzero, 509 <em class="parameter"><code>target</code></em> is 510 <code class="constant">EGL_GL_TEXTURE_2D</code>, 511 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> or 512 <code class="constant">EGL_GL_TEXTURE_3D</code>, and 513 <em class="parameter"><code>buffer</code></em> is not the name of a complete GL 514 texture object, the error <code class="constant">EGL_BAD_PARAMETER</code> 515 is generated. 516 </p> 517 <p> 518 If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is 0, 519 <em class="parameter"><code>target</code></em> is 520 <code class="constant">EGL_GL_TEXTURE_2D</code>, 521 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> or 522 <code class="constant">EGL_GL_TEXTURE_3D</code>, 523 <em class="parameter"><code>buffer</code></em> is the name of an incomplete GL 524 texture object, and any mipmap levels other than mipmap level 0 525 are specified, the error <code class="constant">EGL_BAD_PARAMETER</code> 526 is generated. 527 </p> 528 <p> 529 If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is 0, 530 <em class="parameter"><code>target</code></em> is 531 <code class="constant">EGL_GL_TEXTURE_2D</code> or 532 <code class="constant">EGL_GL_TEXTURE_3D</code>, 533 <em class="parameter"><code>buffer</code></em> is not the name of a complete GL 534 texture object, and mipmap level 0 is not specified, the error 535 <code class="constant">EGL_BAD_PARAMETER</code> is generated. 536 </p> 537 <p> 538 If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is 0, 539 <em class="parameter"><code>target</code></em> is 540 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, 541 <em class="parameter"><code>buffer</code></em> is not the name of a complete GL 542 texture object, and one or more faces do not have mipmap level 0 543 specified, the error <code class="constant">EGL_BAD_PARAMETER</code> is 544 generated. 545 </p> 546 <p> 547 If <em class="parameter"><code>target</code></em> is 548 <code class="constant">EGL_GL_TEXTURE_2D</code>, 549 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, 550 <code class="constant">EGL_GL_RENDERBUFFER</code> or 551 <code class="constant">EGL_GL_TEXTURE_3D</code> and 552 <em class="parameter"><code>buffer</code></em> refers to the default GL texture 553 object (0) for the corresponding GL target, the error 554 <code class="constant">EGL_BAD_PARAMETER</code> is generated. 555 </p> 556 <p> 557 If <em class="parameter"><code>target</code></em> is 558 <code class="constant">EGL_GL_TEXTURE_2D</code>, 559 <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, or 560 <code class="constant">EGL_GL_TEXTURE_3D</code>, and the value specified 561 in <em class="parameter"><code>attrib_list</code></em> for 562 <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is not a valid mipmap 563 level for the specified GL texture object 564 <em class="parameter"><code>buffer</code></em>, the error 565 <code class="constant">EGL_BAD_MATCH</code> is generated. 566 </p> 567 <p> 568 If <em class="parameter"><code>target</code></em> is 569 <code class="constant">EGL_GL_TEXTURE_3D</code>, and the value specified 570 in <em class="parameter"><code>attrib_list</code></em> for 571 <code class="constant">EGL_GL_TEXTURE_ZOFFSET</code> exceeds the depth of 572 the specified mipmap level-of-detail in 573 <em class="parameter"><code>buffer</code></em>, the error 574 <code class="constant">EGL_BAD_PARAMETER</code> is generated. 575 </p> 576 <p> 577 If an attribute specified in <em class="parameter"><code>attrib_list</code></em> 578 is not one of the attributes shown in table <a class="xref" href="#tab-imageattr" title="Table 2. Legal attributes for eglCreateImage attrib_list parameter">Table 2, “ 579 Legal attributes for <code class="function">eglCreateImage</code> 580 <em class="parameter"><code>attrib_list</code></em> parameter 581 ”</a>, the error 582 <code class="constant">EGL_BAD_PARAMETER</code> is generated. 583 </p> 584 <p> 585 If an attribute specified in <em class="parameter"><code>attrib_list</code></em> 586 is not a valid attribute for <em class="parameter"><code>target</code></em>, as 587 shown in table <a class="xref" href="#tab-imageattr" title="Table 2. Legal attributes for eglCreateImage attrib_list parameter">Table 2, “ 588 Legal attributes for <code class="function">eglCreateImage</code> 589 <em class="parameter"><code>attrib_list</code></em> parameter 590 ”</a>, the error 591 <code class="constant">EGL_BAD_MATCH</code> is generated. 592 </p> 593 <p> 594 If the resource specified by <em class="parameter"><code>display</code></em>, 595 <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, 596 <em class="parameter"><code>buffer</code></em> and 597 <em class="parameter"><code>attrib_list</code></em> has an off-screen buffer 598 bound to it (e.g., by a previous call to 599 <code class="function">eglBindTexImage</code>), the error 600 <code class="constant">EGL_BAD_ACCESS</code> is generated. 601 </p> 602 <p> 603 If the resource specified by <em class="parameter"><code>display</code></em>, 604 <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, 605 <em class="parameter"><code>buffer</code></em> and 606 <em class="parameter"><code>attrib_list</code></em> is bound to an off-screen 607 buffer (e.g., by a previous call to 608 <code class="function">eglCreatePbufferFromClientBuffer</code>), the 609 error <code class="constant">EGL_BAD_ACCESS</code> is generated. 610 </p> 611 <p> 612 If the resource specified by <em class="parameter"><code>display</code></em>, 613 <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, 614 <em class="parameter"><code>buffer</code></em> and 615 <em class="parameter"><code>attrib_list</code></em> is itself an 616 <span class="type">EGLImage</span> sibling, the error 617 <code class="constant">EGL_BAD_ACCESS</code> is generated. 618 </p> 619 <p> 620 If insufficient memory is available to complete the specified 621 operation, the error <code class="constant">EGL_BAD_ALLOC</code> is 622 generated. 623 </p> 624 <p> 625 If the value specified in <em class="parameter"><code>attrib_list</code></em> for 626 <code class="constant">EGL_IMAGE_PRESERVED</code> is 627 <code class="constant">EGL_TRUE</code>, and an <span class="type">EGLImage</span> 628 handle cannot be created from the specified resource such that 629 the pixel data values in <em class="parameter"><code>buffer</code></em> are 630 preserved, the error <code class="constant">EGL_BAD_ACCESS</code> is 631 generated. 632 </p> 633 <p> 634 Note that the success or failure of 635 <code class="function">eglCreateImage</code> should not affect the 636 ability to use <em class="parameter"><code>buffer</code></em> in its original API 637 context (or context share group) (although the pixel data values 638 will be undefined if the command succeeds and the value of 639 <code class="constant">EGL_IMAGE_PRESERVED</code> is not 640 <code class="constant">EGL_TRUE</code>). 641 </p> 642 </div> 643 <div class="refsect1" id="lifetime"> 644 <h2>Lifetime and Usage of <span class="type">EGLImage</span>s</h2> 645 <p> 646 Once an <span class="type">EGLImage</span> is created from an 647 <span class="type">EGLImage</span> source, the memory associated with the 648 <span class="type">EGLImage</span> source will remain allocated (and all 649 <span class="type">EGLImage</span> siblings in all client API contexts will 650 be useable) as long as either of the following conditions is 651 true: 652 </p> 653 <p> 654 </p> 655 <div class="itemizedlist"> 656 <ul class="itemizedlist" style="list-style-type: disc; "> 657 <li class="listitem"> 658 <p> 659 Any <span class="type">EGLImage</span> siblings exist in any client 660 API context 661 </p> 662 </li> 663 <li class="listitem"> 664 <p> 665 The <span class="type">EGLImage</span> object exists inside EGL 666 </p> 667 </li> 668 </ul> 669 </div> 670 <p> 671 </p> 672 <p> 673 The semantics for specifying, deleting and using 674 <span class="type">EGLImage</span> siblings are client API-specific, and are 675 described in the appropriate API specifications. 676 </p> 677 <p> 678 If an application specifies an <span class="type">EGLImage</span> sibling as 679 the destination for rendering and/or pixel download operations 680 (e.g., as an OpenGL or OpenGL ES framebuffer object, 681 <code class="function">glTexSubImage2D</code>, etc.), the modified image 682 results will be observed by all <span class="type">EGLImage</span> siblings 683 in all client API contexts. If multiple client API contexts 684 access <span class="type">EGLImage</span> sibling resources simultaneously, 685 with one or more context modifying the image data, rendering 686 results in all contexts accessing <span class="type">EGLImage</span> siblings 687 are undefined. 688 </p> 689 <p> 690 Respecification and/or deletion of any <span class="type">EGLImage</span> 691 sibling (i.e., both <span class="type">EGLImage</span> source and 692 <span class="type">EGLImage</span> target resources) inside a client API 693 context (by issuing a subsequent call to commands such as 694 <code class="function">glTexImage*</code> or 695 <code class="function">glDeleteTextures</code>, with the 696 <span class="type">EGLImage</span> sibling resource as the target of the 697 operation) affects only that client API context and other 698 contexts within its share group. For an OpenGL or OpenGL ES 699 context, respecification always results in 700 <em class="firstterm">orphaning</em> of the <span class="type">EGLImage</span>, 701 and may also include allocation of additional memory for the 702 respecified resource and/or copying of the <span class="type">EGLImage</span> 703 pixel data. 704 </p> 705 <p> 706 Note: Behavior of other types of client APIs generally follows 707 the OpenGL and OpenGL ES behavior described here, although this 708 is not mandated yet. 709 </p> 710 <p> 711 Operations inside EGL or any client API context which may affect 712 the lifetime of an <span class="type">EGLImage</span> (or the memory 713 allocated for the <span class="type">EGLImage</span>), such as respecifying 714 and/or deleting an <span class="type">EGLImage</span> sibling inside a client 715 API context, must be atomic. 716 </p> 717 <p> 718 Applications may create client API resources from an 719 <span class="type">EGLImage</span> using client API extensions outside the 720 scope of this document (such as 721 <code class="constant">GL_OES_EGL_image</code>, which creates OpenGL ES 722 texture and renderbuffer objects). If the <span class="type">EGLImage</span> 723 used to create the client resource was created with the 724 <code class="constant">EGL_IMAGE_PRESERVED</code> attribute set to 725 <code class="constant">EGL_TRUE</code>, then the pixel data values 726 associated with the image will be preserved after creating the 727 client resource; otherwise, the pixel data values will be 728 undefined. If the <span class="type">EGLImage</span> was created with the 729 <code class="constant">EGL_IMAGE_PRESERVED</code> attribute set to 730 <code class="constant">EGL_TRUE</code>, and EGL is unable to create the 731 client resource without modifying the pixel values, then 732 creation will fail and the pixel data values will be preserved. 733 </p> 734 </div> 735 <div class="refsect1" id="notes"> 736 <h2>Notes</h2> 737 <p> 738 <code class="function">eglCreateImage</code> is available only if the EGL 739 version is 1.5 or greater. 740 </p> 741 </div> 742 <div class="refsect1" id="seealso"> 743 <h2>See Also</h2> 744 <p> 745 <a class="citerefentry" href="eglBindTexImage.xhtml"><span class="citerefentry"><span class="refentrytitle">eglBindTexImage</span></span></a>, 746 <a class="citerefentry" href="eglCreatePbufferFromClientBuffer.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePbufferFromClientBuffer</span></span></a>, 747 <a class="citerefentry" href="eglDestroyImage.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroyImage</span></span></a>, 748 <code class="function">glDeleteTextures</code>, 749 <code class="function">glTexImage*</code>, 750 <code class="function">glTexSubImage2D</code> 751 </p> 752 </div> 753 <p> 754 </p> 755 <div class="refsect3" id="copyright"> 756 <img src="KhronosLogo.jpg"/> 757 <p> 758 Copyright © 2003-2014 The Khronos Group Inc. 759 Permission is hereby granted, free of charge, to any person obtaining a 760 copy of this software and/or associated documentation files (the 761 "Materials"), to deal in the Materials without restriction, including 762 without limitation the rights to use, copy, modify, merge, publish, 763 distribute, sublicense, and/or sell copies of the Materials, and to 764 permit persons to whom the Materials are furnished to do so, subject to 765 the condition that this copyright notice and permission notice shall be included 766 in all copies or substantial portions of the Materials. 767 </p> 768 </div> 769 <p> 770</p> 771 </div> 772 <footer/> 773 </body> 774</html> 775
