| <refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreateImage"> |
| <info> |
| <copyright> |
| <year>2018</year> |
| <holder>The Khronos Group Inc.</holder> |
| </copyright> |
| </info> |
| <refmeta> |
| <refentrytitle>eglCreateImage</refentrytitle> |
| <manvolnum>3G</manvolnum> |
| </refmeta> |
| <refnamediv> |
| <refname>eglCreateImage</refname> |
| <refpurpose> |
| Create a new <type>EGLImage</type> object |
| </refpurpose> |
| </refnamediv> |
| <refsynopsisdiv> |
| <title>C Specification</title> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>EGLImage <function>eglCreateImage</function></funcdef> |
| <paramdef>(EGLDisplay <parameter>display</parameter></paramdef> |
| <paramdef>EGLContext <parameter>context</parameter></paramdef> |
| <paramdef>EGLenum <parameter>target</parameter></paramdef> |
| <paramdef>EGLClientBuffer <parameter>buffer</parameter></paramdef> |
| <paramdef>const EGLAttrib *<parameter>attrib_list</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| </refsynopsisdiv> |
| <refsect1 xml:id="parameters"><title>Parameters</title> |
| <variablelist> |
| <varlistentry> |
| <term><parameter>display</parameter></term> |
| <listitem><para> |
| Specifies the <acronym>EGL</acronym> display connection. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>context</parameter></term> |
| <listitem><para> |
| Specifies the client API context for which the image is |
| created. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>target</parameter></term> |
| <listitem><para> |
| Specifies the type of resource used as the image source. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>buffer</parameter></term> |
| <listitem><para> |
| Specifies the resource to be used as the image source. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>attrib_list</parameter></term> |
| <listitem><para> |
| Specifies attributes used to select sub-sections of the |
| resource to be used as the image source. |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| <refsect1 xml:id="description"><title>Description</title> |
| <para> |
| <function>eglCreateImage</function> is used to create an |
| <type>EGLImage</type> object from an existing image resource |
| <parameter>buffer</parameter>. <parameter>display</parameter> |
| specifies the EGL display used for this operation. |
| <parameter>context</parameter> specifies the EGL client API |
| context used for this operation, or |
| <constant>EGL_NO_CONTEXT</constant> if a client API context is |
| not required. <parameter>target</parameter> specifies the type |
| of resource being used as the <type>EGLImage</type> source |
| (examples include two-dimensional textures in OpenGL ES contexts |
| and <type>VGImage</type> objects in OpenVG contexts). |
| <parameter>buffer</parameter> is the name (or handle) of a |
| resource to be used as the <type>EGLImage</type> source, cast |
| into the type <type>EGLClientBuffer</type>. |
| <parameter>attrib_list</parameter> is a list of attribute-value |
| pairs which is used to select sub-sections of |
| <parameter>buffer</parameter> for use as the |
| <type>EGLImage</type> 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 |
| <parameter>attrib_list</parameter> is |
| non-<constant>NULL</constant>, the last attribute specified in |
| the list must be <constant>EGL_NONE</constant>. |
| </para> |
| <para> |
| The resource specified by <parameter>display</parameter>, |
| <parameter>context</parameter>, <parameter>target</parameter>, |
| <parameter>buffer</parameter>, and |
| <parameter>attrib_list</parameter> must not itself be an |
| <type>EGLImage</type> sibling, or bound to a pbuffer |
| <type>EGLSurface</type> resource |
| (<function>eglBindTexImage</function>, |
| <function>eglCreatePbufferFromClientBuffer</function>). |
| </para> |
| <para> |
| Values accepted for <parameter>target</parameter> are shown in |
| table <xref linkend="tab-imagetarget"/>. |
| </para> |
| <table frame="all" xml:id="tab-imagetarget"> |
| <title> |
| Legal values for <function>eglCreateImage</function> <parameter>target</parameter> |
| </title> |
| <tgroup cols="2" align="left" colsep="1" rowsep="1"> |
| <thead> |
| <row> |
| <entry><parameter>target</parameter></entry> |
| <entry>Notes</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_2D</constant></entry> |
| <entry>Used for GL 2D texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant></entry> |
| <entry>Used for the +X face of GL cubemap texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant></entry> |
| <entry>Used for the -X face of GL cubemap texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant></entry> |
| <entry>Used for the +Y face of GL cubemap texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant></entry> |
| <entry>Used for the -Y face of GL cubemap texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant></entry> |
| <entry>Used for the +Z face of GL cubemap texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant></entry> |
| <entry>Used for the -Z face of GL cubemap texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_3D</constant></entry> |
| <entry>Used for OpenGL and OpenGL ES 3D texture images</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_RENDERBUFFER</constant></entry> |
| <entry>Used for OpenGL and OpenGL ES renderbuffer images</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| <para> |
| Attribute names accepted in <parameter>attrib_list</parameter> |
| are shown in table <xref linkend="tab-imageattr"/>, together |
| with the <parameter>target</parameter> for which each attribute |
| name is valid, and the default value used for each attribute if |
| it is not included in <parameter>attrib_list</parameter>. |
| </para> |
| <table frame="all" xml:id="tab-imageattr"> |
| <title> |
| Legal attributes for <function>eglCreateImage</function> |
| <parameter>attrib_list</parameter> parameter |
| </title> |
| <tgroup cols="4" align="left" colsep="1" rowsep="1"> |
| <thead> |
| <row> |
| <entry><parameter>target</parameter></entry> |
| <entry>Notes</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>Attribute</entry> |
| <entry>Description</entry> |
| <entry>Valid <parameter>target</parameter>s</entry> |
| <entry>Default Value</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_NONE</constant></entry> |
| <entry>Marks the end of the attribute-value list</entry> |
| <entry>All</entry> |
| <entry>N/A</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_LEVEL</constant></entry> |
| <entry> |
| Specifies the mipmap level used as the |
| <type>EGLImage</type> source. Must be part of |
| the complete texture object |
| <parameter>buffer</parameter> |
| </entry> |
| <entry> |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, or |
| <constant>EGL_GL_TEXTURE_3D</constant> |
| </entry> |
| <entry>0</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_GL_TEXTURE_ZOFFSET</constant></entry> |
| <entry> |
| Specifies the depth offset of the image to use |
| as the <type>EGLImage</type> source. Must be |
| part of the complete texture object |
| <parameter>buffer</parameter> |
| </entry> |
| <entry><constant>EGL_GL_TEXTURE_3D</constant></entry> |
| <entry>0</entry> |
| </row> |
| <row> |
| <entry><constant>EGL_IMAGE_PRESERVED</constant></entry> |
| <entry>Whether to preserve pixel data</entry> |
| <entry>All</entry> |
| <entry><constant>EGL_FALSE</constant></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| <para> |
| <function>eglCreateImage</function> returns an |
| <type>EGLImage</type> object corresponding to the image data |
| specified by <parameter>display</parameter>, |
| <parameter>context</parameter>, <parameter>target</parameter>, |
| <parameter>buffer</parameter> and |
| <parameter>attrib_list</parameter> which may be referenced by |
| client API operations. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_3D</constant>, |
| <constant>EGL_GL_RENDERBUFFER</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, |
| <parameter>display</parameter> must be a valid |
| <type>EGLDisplay</type>, and <parameter>context</parameter> must |
| be a valid OpenGL or OpenGL ES API context on that display. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <parameter>buffer</parameter> must be the name of a nonzero, |
| <constant>GL_TEXTURE_2D</constant> target texture object, cast |
| into the type <type>EGLClientBuffer</type>. |
| </para> |
| <para> |
| If <parameter>target</parameter> is one of the |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> enumerants, |
| <parameter>buffer</parameter> must be the name of a nonzero, |
| <constant>GL_TEXTURE_CUBE_MAP</constant> (or equivalent in GL |
| extensions) target texture object, cast into the type |
| <type>EGLClientBuffer</type>. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_3D</constant>, |
| <parameter>buffer</parameter> must be the name of a nonzero, |
| <constant>GL_TEXTURE_3D</constant> (or equivalent in GL |
| extensions) target texture object, cast into the type |
| <type>EGLClientBuffer</type>. |
| </para> |
| <para> |
| <parameter>attrib_list</parameter> should specify the mipmap |
| level (<constant>EGL_GL_TEXTURE_LEVEL</constant>) and, where |
| applicable, z-offset |
| (<constant>EGL_GL_TEXTURE_ZOFFSET</constant>) which will be used |
| as the <type>EGLImage</type> source; If not specified, the |
| default values listed in table <xref linkend="tab-imageattr"/> |
| will be used instead. Additional values specified in are |
| ignored. |
| </para> |
| <para> |
| There must exist some levels <emphasis>x</emphasis> and |
| <emphasis>y</emphasis> such that the mipmap level requested lies |
| between <emphasis>x</emphasis> and <emphasis>y</emphasis> |
| (inclusive), the texture would be mipmap complete were |
| <emphasis>x</emphasis> substituted for the base level and |
| <emphasis>y</emphasis> substituted for the max level, and all |
| levels less than <emphasis>x</emphasis> or greater than |
| <emphasis>y</emphasis> are unspecified. For cubemaps a single |
| pair <emphasis>x</emphasis> and <emphasis>y</emphasis> must |
| apply to all faces. For three-dimensional textures, the |
| specified z-offset must be smaller than the depth of the |
| specified mipmap level. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_RENDERBUFFER</constant>, |
| <parameter>buffer</parameter> must be the name of a complete, |
| nonzero, non-multisampled <constant>GL_RENDERBUFFER</constant> |
| (or equivalent in extensions) target object, cast into the type |
| <type>EGLClientBuffer</type>. Values specified in |
| <parameter>attrib_list</parameter> are ignored. |
| </para> |
| <para> |
| If the value of attribute |
| <constant>EGL_IMAGE_PRESERVED</constant> is |
| <constant>EGL_FALSE</constant> (the default), then all pixel |
| data values associated with <parameter>buffer</parameter> will |
| be undefined after <function>eglCreateImage</function> returns. |
| </para> |
| <para> |
| If the value of attribute |
| <constant>EGL_IMAGE_PRESERVED</constant> is |
| <constant>EGL_TRUE</constant>, then all pixel data values |
| associated with <parameter>buffer</parameter> are preserved. |
| </para> |
| </refsect1> |
| <refsect1 xml:id="errors"><title>Errors</title> |
| <para> |
| <function>eglCreateImage</function> returns |
| <constant>EGL_NO_IMAGE</constant> on failure. The contents of |
| <parameter>buffer</parameter> will be unaffected. |
| </para> |
| <para> |
| If <parameter>display</parameter> is not the handle of a valid |
| <type>EGLDisplay</type> object, the error |
| <constant>EGL_BAD_DISPLAY</constant> is generated. |
| </para> |
| <para> |
| If <parameter>context</parameter> is neither the handle of a |
| valid <type>EGLContext</type> object on |
| <parameter>display</parameter> nor |
| <constant>EGL_NO_CONTEXT</constant>, the error |
| <constant>EGL_BAD_CONTEXT</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is not one of the values in |
| table <xref linkend="tab-imagetarget"/>, the error |
| <constant>EGL_BAD_PARAMETER</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, |
| <constant>EGL_GL_RENDERBUFFER</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant>, and |
| <parameter>display</parameter> is not a valid |
| <type>EGLDisplay</type>, the error |
| <constant>EGL_BAD_DISPLAY</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, |
| <constant>EGL_GL_RENDERBUFFER</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant>, and |
| <parameter>context</parameter> is not a valid |
| <type>EGLContext</type>, the error |
| <constant>EGL_BAD_CONTEXT</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, |
| <constant>EGL_GL_RENDERBUFFER</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant>, and |
| <parameter>context</parameter> is not a valid GL context, or |
| does not match the <parameter>display</parameter>, the error |
| <constant>EGL_BAD_MATCH</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant> and |
| <parameter>buffer</parameter> is not the name of a texture |
| object of type <parameter>target</parameter>, the error |
| <constant>EGL_BAD_PARAMETER</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_RENDERBUFFER</constant> and |
| <parameter>buffer</parameter> is not the name of a renderbuffer |
| object, or if <parameter>buffer</parameter> is the name of a |
| multisampled renderbuffer object, the error |
| <constant>EGL_BAD_PARAMETER</constant> is generated. |
| </para> |
| <para> |
| If <constant>EGL_GL_TEXTURE_LEVEL</constant> is nonzero, |
| <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant>, and |
| <parameter>buffer</parameter> is not the name of a complete GL |
| texture object, the error <constant>EGL_BAD_PARAMETER</constant> |
| is generated. |
| </para> |
| <para> |
| If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0, |
| <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant>, |
| <parameter>buffer</parameter> is the name of an incomplete GL |
| texture object, and any mipmap levels other than mipmap level 0 |
| are specified, the error <constant>EGL_BAD_PARAMETER</constant> |
| is generated. |
| </para> |
| <para> |
| If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0, |
| <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant>, |
| <parameter>buffer</parameter> is not the name of a complete GL |
| texture object, and mipmap level 0 is not specified, the error |
| <constant>EGL_BAD_PARAMETER</constant> is generated. |
| </para> |
| <para> |
| If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0, |
| <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, |
| <parameter>buffer</parameter> is not the name of a complete GL |
| texture object, and one or more faces do not have mipmap level 0 |
| specified, the error <constant>EGL_BAD_PARAMETER</constant> is |
| generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, |
| <constant>EGL_GL_RENDERBUFFER</constant> or |
| <constant>EGL_GL_TEXTURE_3D</constant> and |
| <parameter>buffer</parameter> refers to the default GL texture |
| object (0) for the corresponding GL target, the error |
| <constant>EGL_BAD_PARAMETER</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_2D</constant>, |
| <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, or |
| <constant>EGL_GL_TEXTURE_3D</constant>, and the value specified |
| in <parameter>attrib_list</parameter> for |
| <constant>EGL_GL_TEXTURE_LEVEL</constant> is not a valid mipmap |
| level for the specified GL texture object |
| <parameter>buffer</parameter>, the error |
| <constant>EGL_BAD_MATCH</constant> is generated. |
| </para> |
| <para> |
| If <parameter>target</parameter> is |
| <constant>EGL_GL_TEXTURE_3D</constant>, and the value specified |
| in <parameter>attrib_list</parameter> for |
| <constant>EGL_GL_TEXTURE_ZOFFSET</constant> exceeds the depth of |
| the specified mipmap level-of-detail in |
| <parameter>buffer</parameter>, the error |
| <constant>EGL_BAD_PARAMETER</constant> is generated. |
| </para> |
| <para> |
| If an attribute specified in <parameter>attrib_list</parameter> |
| is not one of the attributes shown in table <xref |
| linkend="tab-imageattr"/>, the error |
| <constant>EGL_BAD_PARAMETER</constant> is generated. |
| </para> |
| <para> |
| If an attribute specified in <parameter>attrib_list</parameter> |
| is not a valid attribute for <parameter>target</parameter>, as |
| shown in table <xref linkend="tab-imageattr"/>, the error |
| <constant>EGL_BAD_MATCH</constant> is generated. |
| </para> |
| <para> |
| If the resource specified by <parameter>display</parameter>, |
| <parameter>context</parameter>, <parameter>target</parameter>, |
| <parameter>buffer</parameter> and |
| <parameter>attrib_list</parameter> has an off-screen buffer |
| bound to it (e.g., by a previous call to |
| <function>eglBindTexImage</function>), the error |
| <constant>EGL_BAD_ACCESS</constant> is generated. |
| </para> |
| <para> |
| If the resource specified by <parameter>display</parameter>, |
| <parameter>context</parameter>, <parameter>target</parameter>, |
| <parameter>buffer</parameter> and |
| <parameter>attrib_list</parameter> is bound to an off-screen |
| buffer (e.g., by a previous call to |
| <function>eglCreatePbufferFromClientBuffer</function>), the |
| error <constant>EGL_BAD_ACCESS</constant> is generated. |
| </para> |
| <para> |
| If the resource specified by <parameter>display</parameter>, |
| <parameter>context</parameter>, <parameter>target</parameter>, |
| <parameter>buffer</parameter> and |
| <parameter>attrib_list</parameter> is itself an |
| <type>EGLImage</type> sibling, the error |
| <constant>EGL_BAD_ACCESS</constant> is generated. |
| </para> |
| <para> |
| If insufficient memory is available to complete the specified |
| operation, the error <constant>EGL_BAD_ALLOC</constant> is |
| generated. |
| </para> |
| <para> |
| If the value specified in <parameter>attrib_list</parameter> for |
| <constant>EGL_IMAGE_PRESERVED</constant> is |
| <constant>EGL_TRUE</constant>, and an <type>EGLImage</type> |
| handle cannot be created from the specified resource such that |
| the pixel data values in <parameter>buffer</parameter> are |
| preserved, the error <constant>EGL_BAD_ACCESS</constant> is |
| generated. |
| </para> |
| <para> |
| Note that the success or failure of |
| <function>eglCreateImage</function> should not affect the |
| ability to use <parameter>buffer</parameter> 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 |
| <constant>EGL_IMAGE_PRESERVED</constant> is not |
| <constant>EGL_TRUE</constant>). |
| </para> |
| </refsect1> |
| <refsect1 xml:id="lifetime"><title>Lifetime and Usage of <type>EGLImage</type>s</title> |
| <para> |
| Once an <type>EGLImage</type> is created from an |
| <type>EGLImage</type> source, the memory associated with the |
| <type>EGLImage</type> source will remain allocated (and all |
| <type>EGLImage</type> siblings in all client API contexts will |
| be useable) as long as either of the following conditions is |
| true: |
| </para> |
| <para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| Any <type>EGLImage</type> siblings exist in any client |
| API context |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The <type>EGLImage</type> object exists inside EGL |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| <para> |
| The semantics for specifying, deleting and using |
| <type>EGLImage</type> siblings are client API-specific, and are |
| described in the appropriate API specifications. |
| </para> |
| <para> |
| If an application specifies an <type>EGLImage</type> sibling as |
| the destination for rendering and/or pixel download operations |
| (e.g., as an OpenGL or OpenGL ES framebuffer object, |
| <function>glTexSubImage2D</function>, etc.), the modified image |
| results will be observed by all <type>EGLImage</type> siblings |
| in all client API contexts. If multiple client API contexts |
| access <type>EGLImage</type> sibling resources simultaneously, |
| with one or more context modifying the image data, rendering |
| results in all contexts accessing <type>EGLImage</type> siblings |
| are undefined. |
| </para> |
| <para> |
| Respecification and/or deletion of any <type>EGLImage</type> |
| sibling (i.e., both <type>EGLImage</type> source and |
| <type>EGLImage</type> target resources) inside a client API |
| context (by issuing a subsequent call to commands such as |
| <function>glTexImage*</function> or |
| <function>glDeleteTextures</function>, with the |
| <type>EGLImage</type> 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 |
| <firstterm>orphaning</firstterm> of the <type>EGLImage</type>, |
| and may also include allocation of additional memory for the |
| respecified resource and/or copying of the <type>EGLImage</type> |
| pixel data. |
| </para> |
| <para> |
| Note: Behavior of other types of client APIs generally follows |
| the OpenGL and OpenGL ES behavior described here, although this |
| is not mandated yet. |
| </para> |
| <para> |
| Operations inside EGL or any client API context which may affect |
| the lifetime of an <type>EGLImage</type> (or the memory |
| allocated for the <type>EGLImage</type>), such as respecifying |
| and/or deleting an <type>EGLImage</type> sibling inside a client |
| API context, must be atomic. |
| </para> |
| <para> |
| Applications may create client API resources from an |
| <type>EGLImage</type> using client API extensions outside the |
| scope of this document (such as |
| <constant>GL_OES_EGL_image</constant>, which creates OpenGL ES |
| texture and renderbuffer objects). If the <type>EGLImage</type> |
| used to create the client resource was created with the |
| <constant>EGL_IMAGE_PRESERVED</constant> attribute set to |
| <constant>EGL_TRUE</constant>, 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 <type>EGLImage</type> was created with the |
| <constant>EGL_IMAGE_PRESERVED</constant> attribute set to |
| <constant>EGL_TRUE</constant>, 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. |
| </para> |
| </refsect1> |
| <refsect1 xml:id="notes"><title>Notes</title> |
| <para> |
| <function>eglCreateImage</function> is available only if the EGL |
| version is 1.5 or greater. |
| </para> |
| </refsect1> |
| <refsect1 xml:id="seealso"><title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>eglBindTexImage</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>eglCreatePbufferFromClientBuffer</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>eglDestroyImage</refentrytitle></citerefentry>, |
| <function>glDeleteTextures</function>, |
| <function>glTexImage*</function>, |
| <function>glTexSubImage2D</function> |
| </para> |
| </refsect1> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> |
| </refentry> |
