blob: fe0f7aa7e31423a35ff1ba48e497858ea88eb694 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
<holder>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.</holder>
<!-- ================================ SYNOPSIS -->
<refnamediv id="clCreateFromEGLImageKHR">
Creates an EGLImage target from an EGLImage source.
<refsynopsisdiv xmlns:xlink=""><title></title>
<funcdef><link xlink:href="abstractDataTypes.html">cl_mem</link>
<paramdef><link xlink:href="abstractDataTypes.html">cl_context</link><parameter>context</parameter></paramdef>
<paramdef><link xlink:href="enums.html#cl_mem_flags">cl_mem_flags</link><parameter>flags</parameter></paramdef>
<paramdef>const cl_egl_image_properties_khr<parameter>* properties</parameter></paramdef>
<paramdef><link xlink:href="scalarDataTypes.html">cl_int</link><parameter>* errcode_ret</parameter></paramdef>
<!-- ================================ PARAMETERS -->
<refsect1 id="parameters">
<term> <varname>context</varname> </term>
<para> <!-- parameter description -->
<term> <varname>display</varname> </term>
Should be of type <type>EGLDisplay</type>, cast into the type <type>CLeglDisplayKHR</type>.
<term> <varname>image</varname> </term>
Should be of type <type>EGLImageKHR</type>, cast into
the type <type>CLeglImageKHR</type>. Assuming no
errors are generated in this function, the resulting
image object will be an EGLImage target of
the specified EGLImage <varname>image</varname>. The resulting
<type>cl_mem</type> is an image object which may be used
normally by all OpenCL operations. This maps to an
<type>image2d_t</type> type in OpenCL kernel code.
<term> <varname> flags </varname> </term>
A bit-field that is used to specify usage
information about the memory object being created.
The possible values for <varname>flags</varname> are:
<constant>CL_MEM_WRITE_ONLY</constant> and
For OpenCL 1.2 <varname>flags</varname> also accepts:
<constant>CL_MEM_HOST_READ_ONLY</constant> or
This extension only requires support for
and for OpenCL 1.2
For OpenCL 1.1, a
will be returned
for images which do not support host mapping.
If the value passed in <varname>flags</varname> is not
supported by the OpenCL implementation it will return
<errorname>CL_INVALID_VALUE</errorname>. The
accepted <varname>flags</varname> may be dependent upon
the texture format used.
<term> <varname>properties</varname> </term>
Specifies a list of property names and their
corresponding values. Each property name
is immediately followed by the corresponding
desired value. The list is terminated with 0. No
properties are currently supported with this
version of the extension.
<varname>properties</varname> can be NULL.
<term> <varname> errcode_ret </varname> </term>
<!-- ================================ DESCRIPTION -->
<refsect1 id="description"><title>Description</title>
<function>clCreateFromEGLImageKHR</function> creates an
EGLImage target of type <type>cl_mem</type> from the
EGLImage source provided as <varname>image</varname>.
<bridgehead>Lifetime of Shared Objects</bridgehead>
An OpenCL memory object created from an EGL image
remains valid according to the lifetime
behaviour as described in EGL_KHR_image_base.
"Any EGLImage siblings exist in any client API context"
For OpenCL this means that while the application
retains a reference on the <type>cl_mem</type> (EGL
sibling) the image remains valid.
<bridgehead>Synchronizing OpenCL and EGL Access to Shared Objects</bridgehead>
In order to ensure data integrity, the application is responsible for synchronizing access to shared
CL/EGL objects by their respective APIs. Failure to provide such synchronization may result in
race conditions and other undefined behavior including non-portability between
Prior to calling
the application must ensure that any
pending operations which access the objects specified in
<varname>mem_objects</varname> have completed. This may
be accomplished in a portable way by ceasing all client
operations on the resource, and issuing
and waiting for completion of a <function>glFinish</function>
command on all GL contexts with pending references to
these objects. Implementations may offer more efficient
synchronization methods, such as
synchronisation primitives or fence operations.
<!-- [sic] the spec, ver 2.0, rev. 19, refers to non-existent clEnqueueReleaseEGLImageObjects() -->
Similarly, after calling
the application is responsible for
ensuring that any pending OpenCL operations which access
the objects specified in <varname>mem_objects</varname>
have completed prior to executing subsequent
commands in other APIs which reference these
objects. This may be accomplished in a portable way by calling
with the event
object returned by
<citerefentry><refentrytitle>clEnqueueReleaseGLObjects</refentrytitle></citerefentry> ,
or by calling
As above, some
implementations may offer more efficient methods.
Attempting to access the data store of an EGLImage object after it has been acquired by OpenCL
and before it has been released will result in undefined behavior. Similarly, attempting to access
a shared EGLImage object from OpenCL before it has been acquired by the OpenCL command
queue or after it has been released, will result in undefined behavior.
<!-- ================================ ERRORS -->
<refsect1 id="errors"><title>Errors</title>
<itemizedlist mark="disc">
<errorname>CL_INVALID_CONTEXT</errorname> if <varname>context</varname> is not
a valid OpenCL context.
<errorname>CL_INVALID_VALUE</errorname> if <varname>properties</varname>
contains invalid values, if <varname>display</varname> is not a valid
display object or if <varname>flags</varname> are
not in the set defined above.
<errorname>CL_INVALID_EGL_OBJECT_KHR</errorname> if <varname>image</varname>
is not a valid EGLImage object.
if the OpenCL implementation is not able to
create a <type>cl_mem</type> compatible with the provided
<type>CLeglImageKHR</type> for an implementation-dependent
reason (this could be caused by, but not limited to, reasons such as
unsupported texture formats, etc).
<errorname>CL_INVALID_OPERATION</errorname> if there are
no devices in <varname>context</varname> that support images (i.e.
<constant>CL_DEVICE_IMAGE_SUPPORT</constant> specified in
table 4.3 (see <citerefentry><refentrytitle>clGetDeviceInfo</refentrytitle></citerefentry>) is
<constant>CL_FALSE</constant>) or if the
flags passed are not supported for that image type.
<errorname>CL_OUT_OF_RESOURCES</errorname> if there is a failure to allocate
resources required by the OpenCL implementation on the device.
<errorname>CL_OUT_OF_HOST_MEMORY</errorname> if there is a failure to allocate
resources required by the OpenCL implementation on the host.
<!-- ================================ EXAMPLE -->
<refsect2 id="example1">
<informaltable frame="none">
<tgroup cols="1" align="left" colsep="0" rowsep="0">
<colspec colname="col1" colnum="1" />
Example goes here - it will be set in "code" type with white space preserved.
<!-- ================================ SPECIFICATION -->
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
<refsect1 id="specification"><title>Specification</title>
<imagedata fileref="pdficon_small1.gif" format="gif" />
<olink uri="clCreateFromEGLImageKHR">OpenCL Specification</olink>
<!-- ================================ ALSO SEE -->
<refsect1 id="seealso"><title>Also see</title>
<!-- ============================== COPYRIGHT -->
<!-- Content included from -->
<refsect3 id="Copyright"><title></title>
<imagedata fileref="KhronosLogo.jpg" format="jpg" />
<para />
<!-- 23-Dec-2013, rev. 19 -->