mirror of
https://github.com/openharmony/third_party_egl.git
synced 2026-07-20 01:23:34 -04:00
lizheng
625 lines
30 KiB
XML
625 lines
30 KiB
XML
<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>
|