| <?xml version="1.0" encoding="UTF-8" standalone="no"?> | |
| <!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> | |
| <head> | |
| <title xmlns:xlink="http://www.w3.org/1999/xlink">eglCreateImage - EGL Reference Pages</title> | |
| <link rel="stylesheet" type="text/css" href="khronos-man.css"/> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/> | |
| </head> | |
| <body> | |
| <header/> | |
| <div class="refentry" id="eglCreateImage"> | |
| <div class="titlepage"/> | |
| <div class="refnamediv"> | |
| <h2>Name</h2> | |
| <p>eglCreateImage — | |
| Create a new <span class="type">EGLImage</span> object | |
| </p> | |
| </div> | |
| <div class="refsynopsisdiv"> | |
| <h2>C Specification</h2> | |
| <div class="funcsynopsis"> | |
| <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> | |
| <tr> | |
| <td> | |
| <code class="funcdef">EGLImage <strong class="fsfunc">eglCreateImage</strong>(</code> | |
| </td> | |
| <td>(EGLDisplay <var class="pdparam">display</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>EGLContext <var class="pdparam">context</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>EGLenum <var class="pdparam">target</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>EGLClientBuffer <var class="pdparam">buffer</var>, </td> | |
| </tr> | |
| <tr> | |
| <td> </td> | |
| <td>const EGLAttrib *<var class="pdparam">attrib_list</var><code>)</code>;</td> | |
| </tr> | |
| </table> | |
| <div class="funcprototype-spacer"> </div> | |
| </div> | |
| </div> | |
| <div class="refsect1" id="parameters"> | |
| <h2>Parameters</h2> | |
| <div class="variablelist"> | |
| <dl class="variablelist"> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>display</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the <abbr class="acronym">EGL</abbr> display connection. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>context</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the client API context for which the image is | |
| created. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>target</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the type of resource used as the image source. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>buffer</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the resource to be used as the image source. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <em class="parameter"> | |
| <code>attrib_list</code> | |
| </em> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies attributes used to select sub-sections of the | |
| resource to be used as the image source. | |
| </p> | |
| </dd> | |
| </dl> | |
| </div> | |
| </div> | |
| <div class="refsect1" id="description"> | |
| <h2>Description</h2> | |
| <p> | |
| <code class="function">eglCreateImage</code> is used to create an | |
| <span class="type">EGLImage</span> object from an existing image resource | |
| <em class="parameter"><code>buffer</code></em>. <em class="parameter"><code>display</code></em> | |
| specifies the EGL display used for this operation. | |
| <em class="parameter"><code>context</code></em> specifies the EGL client API | |
| context used for this operation, or | |
| <code class="constant">EGL_NO_CONTEXT</code> if a client API context is | |
| not required. <em class="parameter"><code>target</code></em> specifies the type | |
| of resource being used as the <span class="type">EGLImage</span> source | |
| (examples include two-dimensional textures in OpenGL ES contexts | |
| and <span class="type">VGImage</span> objects in OpenVG contexts). | |
| <em class="parameter"><code>buffer</code></em> is the name (or handle) of a | |
| resource to be used as the <span class="type">EGLImage</span> source, cast | |
| into the type <span class="type">EGLClientBuffer</span>. | |
| <em class="parameter"><code>attrib_list</code></em> is a list of attribute-value | |
| pairs which is used to select sub-sections of | |
| <em class="parameter"><code>buffer</code></em> for use as the | |
| <span class="type">EGLImage</span> source, such as mipmap levels for OpenGL | |
| ES texture map resources, as well as behavioral options, such as | |
| whether to preserve pixel data during creation. If | |
| <em class="parameter"><code>attrib_list</code></em> is | |
| non-<code class="constant">NULL</code>, the last attribute specified in | |
| the list must be <code class="constant">EGL_NONE</code>. | |
| </p> | |
| <p> | |
| The resource specified by <em class="parameter"><code>display</code></em>, | |
| <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, | |
| <em class="parameter"><code>buffer</code></em>, and | |
| <em class="parameter"><code>attrib_list</code></em> must not itself be an | |
| <span class="type">EGLImage</span> sibling, or bound to a pbuffer | |
| <span class="type">EGLSurface</span> resource | |
| (<code class="function">eglBindTexImage</code>, | |
| <code class="function">eglCreatePbufferFromClientBuffer</code>). | |
| </p> | |
| <p> | |
| Values accepted for <em class="parameter"><code>target</code></em> are shown in | |
| table <a class="xref" href="#tab-imagetarget" title="Table 1. Legal values for eglCreateImage target">Table 1, “ | |
| Legal values for <code class="function">eglCreateImage</code> <em class="parameter"><code>target</code></em> | |
| ”</a>. | |
| </p> | |
| <div class="table" id="tab-imagetarget"> | |
| <div class="table-title">Table 1. | |
| Legal values for <code class="function">eglCreateImage</code> <em class="parameter"><code>target</code></em> | |
| </div> | |
| <div class="table-contents"> | |
| <table style="border-collapse: collapse; border-top: 2px solid ; border-bottom: 2px solid ; border-left: 2px solid ; border-right: 2px solid ; "> | |
| <colgroup> | |
| <col/> | |
| <col/> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <em class="parameter"> | |
| <code>target</code> | |
| </em> | |
| </th> | |
| <th style="text-align: left; border-bottom: 2px solid ; ">Notes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_2D</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for GL 2D texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for the +X face of GL cubemap texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for the -X face of GL cubemap texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for the +Y face of GL cubemap texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for the -Y face of GL cubemap texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for the +Z face of GL cubemap texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for the -Z face of GL cubemap texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_3D</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Used for OpenGL and OpenGL ES 3D texture images</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; "> | |
| <code class="constant">EGL_GL_RENDERBUFFER</code> | |
| </td> | |
| <td style="text-align: left; ">Used for OpenGL and OpenGL ES renderbuffer images</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| </div> | |
| <br class="table-break"/> | |
| <p> | |
| Attribute names accepted in <em class="parameter"><code>attrib_list</code></em> | |
| are shown in table <a class="xref" href="#tab-imageattr" title="Table 2. Legal attributes for eglCreateImage attrib_list parameter">Table 2, “ | |
| Legal attributes for <code class="function">eglCreateImage</code> | |
| <em class="parameter"><code>attrib_list</code></em> parameter | |
| ”</a>, together | |
| with the <em class="parameter"><code>target</code></em> for which each attribute | |
| name is valid, and the default value used for each attribute if | |
| it is not included in <em class="parameter"><code>attrib_list</code></em>. | |
| </p> | |
| <div class="table" id="tab-imageattr"> | |
| <div class="table-title">Table 2. | |
| Legal attributes for <code class="function">eglCreateImage</code> | |
| <em class="parameter"><code>attrib_list</code></em> parameter | |
| </div> | |
| <div class="table-contents"> | |
| <table style="border-collapse: collapse; border-top: 2px solid ; border-bottom: 2px solid ; border-left: 2px solid ; border-right: 2px solid ; "> | |
| <colgroup> | |
| <col/> | |
| <col/> | |
| <col/> | |
| <col/> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <em class="parameter"> | |
| <code>target</code> | |
| </em> | |
| </th> | |
| <th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Notes</th> | |
| <td style="border-right: 2px solid ; border-bottom: 2px solid ; " class="auto-generated"> </td> | |
| <td style="border-bottom: 2px solid ; " class="auto-generated"> </td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Attribute</td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Description</td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Valid <em class="parameter"><code>target</code></em>s</td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">Default Value</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_NONE</code> | |
| </td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">Marks the end of the attribute-value list</td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">All</td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">N/A</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_LEVEL</code> | |
| </td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| Specifies the mipmap level used as the | |
| <span class="type">EGLImage</span> source. Must be part of | |
| the complete texture object | |
| <em class="parameter"><code>buffer</code></em> | |
| </td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">0</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_ZOFFSET</code> | |
| </td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| Specifies the depth offset of the image to use | |
| as the <span class="type">EGLImage</span> source. Must be | |
| part of the complete texture object | |
| <em class="parameter"><code>buffer</code></em> | |
| </td> | |
| <td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; "> | |
| <code class="constant">EGL_GL_TEXTURE_3D</code> | |
| </td> | |
| <td style="text-align: left; border-bottom: 2px solid ; ">0</td> | |
| </tr> | |
| <tr> | |
| <td style="text-align: left; border-right: 2px solid ; "> | |
| <code class="constant">EGL_IMAGE_PRESERVED</code> | |
| </td> | |
| <td style="text-align: left; border-right: 2px solid ; ">Whether to preserve pixel data</td> | |
| <td style="text-align: left; border-right: 2px solid ; ">All</td> | |
| <td style="text-align: left; "> | |
| <code class="constant">EGL_FALSE</code> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| </div> | |
| <br class="table-break"/> | |
| <p> | |
| <code class="function">eglCreateImage</code> returns an | |
| <span class="type">EGLImage</span> object corresponding to the image data | |
| specified by <em class="parameter"><code>display</code></em>, | |
| <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, | |
| <em class="parameter"><code>buffer</code></em> and | |
| <em class="parameter"><code>attrib_list</code></em> which may be referenced by | |
| client API operations. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, | |
| <code class="constant">EGL_GL_RENDERBUFFER</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</code>, or | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</code>, | |
| <em class="parameter"><code>display</code></em> must be a valid | |
| <span class="type">EGLDisplay</span>, and <em class="parameter"><code>context</code></em> must | |
| be a valid OpenGL or OpenGL ES API context on that display. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <em class="parameter"><code>buffer</code></em> must be the name of a nonzero, | |
| <code class="constant">GL_TEXTURE_2D</code> target texture object, cast | |
| into the type <span class="type">EGLClientBuffer</span>. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is one of the | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> enumerants, | |
| <em class="parameter"><code>buffer</code></em> must be the name of a nonzero, | |
| <code class="constant">GL_TEXTURE_CUBE_MAP</code> (or equivalent in GL | |
| extensions) target texture object, cast into the type | |
| <span class="type">EGLClientBuffer</span>. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, | |
| <em class="parameter"><code>buffer</code></em> must be the name of a nonzero, | |
| <code class="constant">GL_TEXTURE_3D</code> (or equivalent in GL | |
| extensions) target texture object, cast into the type | |
| <span class="type">EGLClientBuffer</span>. | |
| </p> | |
| <p> | |
| <em class="parameter"><code>attrib_list</code></em> should specify the mipmap | |
| level (<code class="constant">EGL_GL_TEXTURE_LEVEL</code>) and, where | |
| applicable, z-offset | |
| (<code class="constant">EGL_GL_TEXTURE_ZOFFSET</code>) which will be used | |
| as the <span class="type">EGLImage</span> source; If not specified, the | |
| default values listed in table <a class="xref" href="#tab-imageattr" title="Table 2. Legal attributes for eglCreateImage attrib_list parameter">Table 2, “ | |
| Legal attributes for <code class="function">eglCreateImage</code> | |
| <em class="parameter"><code>attrib_list</code></em> parameter | |
| ”</a> | |
| will be used instead. Additional values specified in are | |
| ignored. | |
| </p> | |
| <p> | |
| There must exist some levels <span class="emphasis"><em>x</em></span> and | |
| <span class="emphasis"><em>y</em></span> such that the mipmap level requested lies | |
| between <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>y</em></span> | |
| (inclusive), the texture would be mipmap complete were | |
| <span class="emphasis"><em>x</em></span> substituted for the base level and | |
| <span class="emphasis"><em>y</em></span> substituted for the max level, and all | |
| levels less than <span class="emphasis"><em>x</em></span> or greater than | |
| <span class="emphasis"><em>y</em></span> are unspecified. For cubemaps a single | |
| pair <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>y</em></span> must | |
| apply to all faces. For three-dimensional textures, the | |
| specified z-offset must be smaller than the depth of the | |
| specified mipmap level. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_RENDERBUFFER</code>, | |
| <em class="parameter"><code>buffer</code></em> must be the name of a complete, | |
| nonzero, non-multisampled <code class="constant">GL_RENDERBUFFER</code> | |
| (or equivalent in extensions) target object, cast into the type | |
| <span class="type">EGLClientBuffer</span>. Values specified in | |
| <em class="parameter"><code>attrib_list</code></em> are ignored. | |
| </p> | |
| <p> | |
| If the value of attribute | |
| <code class="constant">EGL_IMAGE_PRESERVED</code> is | |
| <code class="constant">EGL_FALSE</code> (the default), then all pixel | |
| data values associated with <em class="parameter"><code>buffer</code></em> will | |
| be undefined after <code class="function">eglCreateImage</code> returns. | |
| </p> | |
| <p> | |
| If the value of attribute | |
| <code class="constant">EGL_IMAGE_PRESERVED</code> is | |
| <code class="constant">EGL_TRUE</code>, then all pixel data values | |
| associated with <em class="parameter"><code>buffer</code></em> are preserved. | |
| </p> | |
| </div> | |
| <div class="refsect1" id="errors"> | |
| <h2>Errors</h2> | |
| <p> | |
| <code class="function">eglCreateImage</code> returns | |
| <code class="constant">EGL_NO_IMAGE</code> on failure. The contents of | |
| <em class="parameter"><code>buffer</code></em> will be unaffected. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>display</code></em> is not the handle of a valid | |
| <span class="type">EGLDisplay</span> object, the error | |
| <code class="constant">EGL_BAD_DISPLAY</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>context</code></em> is neither the handle of a | |
| valid <span class="type">EGLContext</span> object on | |
| <em class="parameter"><code>display</code></em> nor | |
| <code class="constant">EGL_NO_CONTEXT</code>, the error | |
| <code class="constant">EGL_BAD_CONTEXT</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is not one of the values in | |
| table <a class="xref" href="#tab-imagetarget" title="Table 1. Legal values for eglCreateImage target">Table 1, “ | |
| Legal values for <code class="function">eglCreateImage</code> <em class="parameter"><code>target</code></em> | |
| ”</a>, the error | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, | |
| <code class="constant">EGL_GL_RENDERBUFFER</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, and | |
| <em class="parameter"><code>display</code></em> is not a valid | |
| <span class="type">EGLDisplay</span>, the error | |
| <code class="constant">EGL_BAD_DISPLAY</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, | |
| <code class="constant">EGL_GL_RENDERBUFFER</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, and | |
| <em class="parameter"><code>context</code></em> is not a valid | |
| <span class="type">EGLContext</span>, the error | |
| <code class="constant">EGL_BAD_CONTEXT</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, | |
| <code class="constant">EGL_GL_RENDERBUFFER</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, and | |
| <em class="parameter"><code>context</code></em> is not a valid GL context, or | |
| does not match the <em class="parameter"><code>display</code></em>, the error | |
| <code class="constant">EGL_BAD_MATCH</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code> and | |
| <em class="parameter"><code>buffer</code></em> is not the name of a texture | |
| object of type <em class="parameter"><code>target</code></em>, the error | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_RENDERBUFFER</code> and | |
| <em class="parameter"><code>buffer</code></em> is not the name of a renderbuffer | |
| object, or if <em class="parameter"><code>buffer</code></em> is the name of a | |
| multisampled renderbuffer object, the error | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated. | |
| </p> | |
| <p> | |
| If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is nonzero, | |
| <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, and | |
| <em class="parameter"><code>buffer</code></em> is not the name of a complete GL | |
| texture object, the error <code class="constant">EGL_BAD_PARAMETER</code> | |
| is generated. | |
| </p> | |
| <p> | |
| If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is 0, | |
| <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, | |
| <em class="parameter"><code>buffer</code></em> is the name of an incomplete GL | |
| texture object, and any mipmap levels other than mipmap level 0 | |
| are specified, the error <code class="constant">EGL_BAD_PARAMETER</code> | |
| is generated. | |
| </p> | |
| <p> | |
| If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is 0, | |
| <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, | |
| <em class="parameter"><code>buffer</code></em> is not the name of a complete GL | |
| texture object, and mipmap level 0 is not specified, the error | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated. | |
| </p> | |
| <p> | |
| If <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is 0, | |
| <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, | |
| <em class="parameter"><code>buffer</code></em> is not the name of a complete GL | |
| texture object, and one or more faces do not have mipmap level 0 | |
| specified, the error <code class="constant">EGL_BAD_PARAMETER</code> is | |
| generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, | |
| <code class="constant">EGL_GL_RENDERBUFFER</code> or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code> and | |
| <em class="parameter"><code>buffer</code></em> refers to the default GL texture | |
| object (0) for the corresponding GL target, the error | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_2D</code>, | |
| <code class="constant">EGL_GL_TEXTURE_CUBE_MAP_*</code>, or | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, and the value specified | |
| in <em class="parameter"><code>attrib_list</code></em> for | |
| <code class="constant">EGL_GL_TEXTURE_LEVEL</code> is not a valid mipmap | |
| level for the specified GL texture object | |
| <em class="parameter"><code>buffer</code></em>, the error | |
| <code class="constant">EGL_BAD_MATCH</code> is generated. | |
| </p> | |
| <p> | |
| If <em class="parameter"><code>target</code></em> is | |
| <code class="constant">EGL_GL_TEXTURE_3D</code>, and the value specified | |
| in <em class="parameter"><code>attrib_list</code></em> for | |
| <code class="constant">EGL_GL_TEXTURE_ZOFFSET</code> exceeds the depth of | |
| the specified mipmap level-of-detail in | |
| <em class="parameter"><code>buffer</code></em>, the error | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated. | |
| </p> | |
| <p> | |
| If an attribute specified in <em class="parameter"><code>attrib_list</code></em> | |
| 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, “ | |
| Legal attributes for <code class="function">eglCreateImage</code> | |
| <em class="parameter"><code>attrib_list</code></em> parameter | |
| ”</a>, the error | |
| <code class="constant">EGL_BAD_PARAMETER</code> is generated. | |
| </p> | |
| <p> | |
| If an attribute specified in <em class="parameter"><code>attrib_list</code></em> | |
| is not a valid attribute for <em class="parameter"><code>target</code></em>, as | |
| shown in table <a class="xref" href="#tab-imageattr" title="Table 2. Legal attributes for eglCreateImage attrib_list parameter">Table 2, “ | |
| Legal attributes for <code class="function">eglCreateImage</code> | |
| <em class="parameter"><code>attrib_list</code></em> parameter | |
| ”</a>, the error | |
| <code class="constant">EGL_BAD_MATCH</code> is generated. | |
| </p> | |
| <p> | |
| If the resource specified by <em class="parameter"><code>display</code></em>, | |
| <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, | |
| <em class="parameter"><code>buffer</code></em> and | |
| <em class="parameter"><code>attrib_list</code></em> has an off-screen buffer | |
| bound to it (e.g., by a previous call to | |
| <code class="function">eglBindTexImage</code>), the error | |
| <code class="constant">EGL_BAD_ACCESS</code> is generated. | |
| </p> | |
| <p> | |
| If the resource specified by <em class="parameter"><code>display</code></em>, | |
| <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, | |
| <em class="parameter"><code>buffer</code></em> and | |
| <em class="parameter"><code>attrib_list</code></em> is bound to an off-screen | |
| buffer (e.g., by a previous call to | |
| <code class="function">eglCreatePbufferFromClientBuffer</code>), the | |
| error <code class="constant">EGL_BAD_ACCESS</code> is generated. | |
| </p> | |
| <p> | |
| If the resource specified by <em class="parameter"><code>display</code></em>, | |
| <em class="parameter"><code>context</code></em>, <em class="parameter"><code>target</code></em>, | |
| <em class="parameter"><code>buffer</code></em> and | |
| <em class="parameter"><code>attrib_list</code></em> is itself an | |
| <span class="type">EGLImage</span> sibling, the error | |
| <code class="constant">EGL_BAD_ACCESS</code> is generated. | |
| </p> | |
| <p> | |
| If insufficient memory is available to complete the specified | |
| operation, the error <code class="constant">EGL_BAD_ALLOC</code> is | |
| generated. | |
| </p> | |
| <p> | |
| If the value specified in <em class="parameter"><code>attrib_list</code></em> for | |
| <code class="constant">EGL_IMAGE_PRESERVED</code> is | |
| <code class="constant">EGL_TRUE</code>, and an <span class="type">EGLImage</span> | |
| handle cannot be created from the specified resource such that | |
| the pixel data values in <em class="parameter"><code>buffer</code></em> are | |
| preserved, the error <code class="constant">EGL_BAD_ACCESS</code> is | |
| generated. | |
| </p> | |
| <p> | |
| Note that the success or failure of | |
| <code class="function">eglCreateImage</code> should not affect the | |
| ability to use <em class="parameter"><code>buffer</code></em> in its original API | |
| context (or context share group) (although the pixel data values | |
| will be undefined if the command succeeds and the value of | |
| <code class="constant">EGL_IMAGE_PRESERVED</code> is not | |
| <code class="constant">EGL_TRUE</code>). | |
| </p> | |
| </div> | |
| <div class="refsect1" id="lifetime"> | |
| <h2>Lifetime and Usage of <span class="type">EGLImage</span>s</h2> | |
| <p> | |
| Once an <span class="type">EGLImage</span> is created from an | |
| <span class="type">EGLImage</span> source, the memory associated with the | |
| <span class="type">EGLImage</span> source will remain allocated (and all | |
| <span class="type">EGLImage</span> siblings in all client API contexts will | |
| be useable) as long as either of the following conditions is | |
| true: | |
| </p> | |
| <p> | |
| </p> | |
| <div class="itemizedlist"> | |
| <ul class="itemizedlist" style="list-style-type: disc; "> | |
| <li class="listitem"> | |
| <p> | |
| Any <span class="type">EGLImage</span> siblings exist in any client | |
| API context | |
| </p> | |
| </li> | |
| <li class="listitem"> | |
| <p> | |
| The <span class="type">EGLImage</span> object exists inside EGL | |
| </p> | |
| </li> | |
| </ul> | |
| </div> | |
| <p> | |
| </p> | |
| <p> | |
| The semantics for specifying, deleting and using | |
| <span class="type">EGLImage</span> siblings are client API-specific, and are | |
| described in the appropriate API specifications. | |
| </p> | |
| <p> | |
| If an application specifies an <span class="type">EGLImage</span> sibling as | |
| the destination for rendering and/or pixel download operations | |
| (e.g., as an OpenGL or OpenGL ES framebuffer object, | |
| <code class="function">glTexSubImage2D</code>, etc.), the modified image | |
| results will be observed by all <span class="type">EGLImage</span> siblings | |
| in all client API contexts. If multiple client API contexts | |
| access <span class="type">EGLImage</span> sibling resources simultaneously, | |
| with one or more context modifying the image data, rendering | |
| results in all contexts accessing <span class="type">EGLImage</span> siblings | |
| are undefined. | |
| </p> | |
| <p> | |
| Respecification and/or deletion of any <span class="type">EGLImage</span> | |
| sibling (i.e., both <span class="type">EGLImage</span> source and | |
| <span class="type">EGLImage</span> target resources) inside a client API | |
| context (by issuing a subsequent call to commands such as | |
| <code class="function">glTexImage*</code> or | |
| <code class="function">glDeleteTextures</code>, with the | |
| <span class="type">EGLImage</span> sibling resource as the target of the | |
| operation) affects only that client API context and other | |
| contexts within its share group. For an OpenGL or OpenGL ES | |
| context, respecification always results in | |
| <em class="firstterm">orphaning</em> of the <span class="type">EGLImage</span>, | |
| and may also include allocation of additional memory for the | |
| respecified resource and/or copying of the <span class="type">EGLImage</span> | |
| pixel data. | |
| </p> | |
| <p> | |
| Note: Behavior of other types of client APIs generally follows | |
| the OpenGL and OpenGL ES behavior described here, although this | |
| is not mandated yet. | |
| </p> | |
| <p> | |
| Operations inside EGL or any client API context which may affect | |
| the lifetime of an <span class="type">EGLImage</span> (or the memory | |
| allocated for the <span class="type">EGLImage</span>), such as respecifying | |
| and/or deleting an <span class="type">EGLImage</span> sibling inside a client | |
| API context, must be atomic. | |
| </p> | |
| <p> | |
| Applications may create client API resources from an | |
| <span class="type">EGLImage</span> using client API extensions outside the | |
| scope of this document (such as | |
| <code class="constant">GL_OES_EGL_image</code>, which creates OpenGL ES | |
| texture and renderbuffer objects). If the <span class="type">EGLImage</span> | |
| used to create the client resource was created with the | |
| <code class="constant">EGL_IMAGE_PRESERVED</code> attribute set to | |
| <code class="constant">EGL_TRUE</code>, then the pixel data values | |
| associated with the image will be preserved after creating the | |
| client resource; otherwise, the pixel data values will be | |
| undefined. If the <span class="type">EGLImage</span> was created with the | |
| <code class="constant">EGL_IMAGE_PRESERVED</code> attribute set to | |
| <code class="constant">EGL_TRUE</code>, and EGL is unable to create the | |
| client resource without modifying the pixel values, then | |
| creation will fail and the pixel data values will be preserved. | |
| </p> | |
| </div> | |
| <div class="refsect1" id="notes"> | |
| <h2>Notes</h2> | |
| <p> | |
| <code class="function">eglCreateImage</code> is available only if the EGL | |
| version is 1.5 or greater. | |
| </p> | |
| </div> | |
| <div class="refsect1" id="seealso"> | |
| <h2>See Also</h2> | |
| <p> | |
| <a class="citerefentry" href="eglBindTexImage.xhtml"><span class="citerefentry"><span class="refentrytitle">eglBindTexImage</span></span></a>, | |
| <a class="citerefentry" href="eglCreatePbufferFromClientBuffer.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePbufferFromClientBuffer</span></span></a>, | |
| <a class="citerefentry" href="eglDestroyImage.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroyImage</span></span></a>, | |
| <code class="function">glDeleteTextures</code>, | |
| <code class="function">glTexImage*</code>, | |
| <code class="function">glTexSubImage2D</code> | |
| </p> | |
| </div> | |
| <p> | |
| </p> | |
| <div class="refsect3" id="copyright"> | |
| <img src="KhronosLogo.jpg"/> | |
| <p> | |
| Copyright © 2003-2014 The Khronos Group Inc. | |
| Permission is hereby granted, free of charge, to any person obtaining a | |
| copy of this software and/or associated documentation files (the | |
| "Materials"), to deal in the Materials without restriction, including | |
| without limitation the rights to use, copy, modify, merge, publish, | |
| distribute, sublicense, and/or sell copies of the Materials, and to | |
| permit persons to whom the Materials are furnished to do so, subject to | |
| the condition that this copyright notice and permission notice shall be included | |
| in all copies or substantial portions of the Materials. | |
| </p> | |
| </div> | |
| <p> | |
| </p> | |
| </div> | |
| <footer/> | |
| </body> | |
| </html> |