| <?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> |
