blob: 739ea2fbad88cc573a5b88d8244db00a07b5838f [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style xmlns="" type="text/css">
/* This style sets a margin around the entire page */
html, body {
margin: 10px;
}
p {
font: normal 16px verdana, sans-serif;
margin: 0;
padding-bottom:12px;
}
h1 {
font: bold 25px verdana, sans-serif;
margin-top: 0;
margin-bottom: 3px;
padding-top: 0;
padding-bottom: 0;
}
h2 {
font: bold 19px verdana, sans-serif;
margin-top: 28px;
margin-bottom: 3px;
padding-top: 0;
padding-bottom: 0;
}
h3 {
font: bold 19px verdana, sans-serif !important;
margin-top: 28px;
margin-bottom: 3px;
padding-top: 0;
padding-bottom: 0;
}
li {
font: normal 16px verdana, sans-serif;
margin-top: 0;
margin-bottom: 18px;
padding-top: 0;
padding-bottom: 0;
}
.pdparam {
font: italic 16px verdana, sans-serif;
}
.term {
font: italic 16px verdana, sans-serif;
font-weight: normal;
}
.type {
font: normal 16px verdana, sans-serif !important;
}
.parameter {
font-style: italic;
}
a:link, a:visited {
color: blue;
text-decoration: none;
font: normal 16px;
}
a:hover {
background-color: #FFFF99;
font: normal 16px;
}
div.funcsynopsis {
text-align: left;
background-color: #e6e6e6;
font: normal 16px verdana, sans-serif;
padding-top: 10px;
padding-bottom: 10px;
}
div.funcsynopsis table {
border-collapse: separate;
font: normal 16px verdana, sans-serif;
}
div.funcsynopsis td {
background-color: #e6e6e6;
border: 0 solid #000;
padding: 1px;
font: normal 16px verdana, sans-serif;
}
div.refsect1 {
font-family: verdana, sans-serif;
font-size: 16px;
}
code.constant {
font: normal 16px courier new, monospace !important;
}
span.errorname {
font: normal 16px verdana, sans-serif !important;
}
code.function {
font: bold 16px verdana, sans-serif !important;
}
b.fsfunc {
font: bold 16px verdana, sans-serif !important;
}
code.varname {
font: italic 16px verdana, sans-serif;
}
code.replaceable {
font: italic 16px courier new, monospace;
}
code.funcdef {
font: normal 16px verdana, sans-serif !important;
}
.citerefentry {
font: normal 16px verdana, sans-serif !important;
}
.parameter {
font-style: italic;
}
code.fsfunc {
font: normal 16px verdana, sans-serif !important;
}
/* PARAMETER: This style controls spacing between the terms in Parameter section */
dt {
margin-top: 15px;
}
/* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */
div.refsect1 table {
width: 100%;
margin-top: 10px;
background-color: #FFF;
border-collapse: collapse;
border-color: #000;
border-width: 1px;
font: normal 16px verdana, sans-serif;
}
div.refsect1 th {
border-collapse: collapse;
border-color: #000;
border-width: 1px;
font: bold 16px verdana, sans-serif;
}
div.refsect1 td {
background-color: #FFF;
padding: 5px;
vertical-align: text-top;
border-collapse: collapse;
border-color: #000;
border-width: 1px;
font: normal 16px verdana, sans-serif;
}
div.refsect1 p{
font: normal 16px verdana, sans-serif;
margin-top: 8px;
margin-bottom: 8px;
padding-top: 0;
padding-bottom: 0;
}
/* EXAMPLE: These styles apply only to the Example section */
div.refsect2 {
font: normal 16px courier new, monospace !important;
}
div.refsect2 table {
margin-top: 0;
background-color: #e6e6e6;
width: 100%;
border: 0 solid #000;
padding: 2px;
font: normal 16px courier new, monospace !important;
}
div.refsect2 td {
background-color: #e6e6e6;
font: normal 16px courier new, monospace !important;
white-space:pre;
}
/* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */
div.refsect3 {
font: normal 11px verdana, sans-serif;
margin-top: 50px;
margin-bottom: 20px;
padding-top: 0;
padding-bottom: 0;
}
</style>
<title>clCreateFromEGLImageKHR</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1" />
<meta name="keywords" content="clCreateFromEGLImageKHR" />
</head>
<body>
<div class="refentry">
<a id="id-1"></a>
<div class="titlepage"></div>
<div xmlns="" class="refnamediv">
<a xmlns="http://www.w3.org/1999/xhtml" id="clCreateFromEGLImageKHR"></a>
<h1>clCreateFromEGLImageKHR</h1>
<p>
Creates an EGLImage target from an EGLImage source.
</p>
</div>
<div class="refsynopsisdiv">
<h2></h2>
<div class="funcsynopsis">
<table xmlns="" border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
<tr valign="bottom">
<td>
<code xmlns="http://www.w3.org/1999/xhtml" class="funcdef"><a class="link" href="abstractDataTypes.html" target="pagedisplay">cl_mem</a>
<strong class="fsfunc">
clCreateFromEGLImageKHR
</strong>
(</code>
<td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="abstractDataTypes.html" target="pagedisplay">cl_context</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">context</var>, </td>
</td>
</tr>
<tr valign="top">
<td> </td>
<td>CLeglDisplayKHR <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">display</var>, </td>
</tr>
<tr valign="top">
<td> </td>
<td>CLeglImageKHR <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">image</var>, </td>
</tr>
<tr valign="top">
<td> </td>
<td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="enums.html#cl_mem_flags" target="pagedisplay">cl_mem_flags</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">flags</var>, </td>
</tr>
<tr valign="top">
<td> </td>
<td>const cl_egl_image_properties_khr <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">* properties</var>, </td>
</tr>
<tr valign="top">
<td> </td>
<td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">cl_int</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">* errcode_ret</var><code>)</code></td>
</tr>
</table>
</div>
</div>
<div class="refsect1">
<a id="parameters"></a>
<h2>Parameters</h2>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term"> <code class="varname">context</code> </span>
</dt>
<dd>
<p>
</p>
</dd>
<dt>
<span class="term"> <code class="varname">display</code> </span>
</dt>
<dd>
<p>
Should be of type <span class="type">EGLDisplay</span>, cast into the type <span class="type">CLeglDisplayKHR</span>.
</p>
</dd>
<dt>
<span class="term"> <code class="varname">image</code> </span>
</dt>
<dd>
<p>
Should be of type <span class="type">EGLImageKHR</span>, cast into
the type <span class="type">CLeglImageKHR</span>. Assuming no
errors are generated in this function, the resulting
image object will be an EGLImage target of
the specified EGLImage <code class="varname">image</code>. The resulting
<span class="type">cl_mem</span> is an image object which may be used
normally by all OpenCL operations. This maps to an
<span class="type">image2d_t</span> type in OpenCL kernel code.
</p>
</dd>
<dt>
<span class="term"> <code class="varname"> flags </code> </span>
</dt>
<dd>
<p>
A bit-field that is used to specify usage
information about the memory object being created.
The possible values for <code class="varname">flags</code> are:
<code class="constant">CL_MEM_READ_ONLY</code>,
<code class="constant">CL_MEM_WRITE_ONLY</code> and
<code class="constant">CL_MEM_READ_WRITE</code>.
</p>
<p>
For OpenCL 1.2 <code class="varname">flags</code> also accepts:
<code class="constant">CL_MEM_HOST_WRITE_ONLY</code>,
<code class="constant">CL_MEM_HOST_READ_ONLY</code> or
<code class="constant">CL_MEM_HOST_NO_ACCESS</code>.
</p>
<p>
This extension only requires support for
<code class="constant">CL_MEM_READ_ONLY</code>,
and for OpenCL 1.2
<code class="constant">CL_MEM_HOST_NO_ACCESS</code>.
For OpenCL 1.1, a
<span class="errorname">CL_INVALID_OPERATION</span>
will be returned
for images which do not support host mapping.
</p>
<p>
If the value passed in <code class="varname">flags</code> is not
supported by the OpenCL implementation it will return
<span class="errorname">CL_INVALID_VALUE</span>. The
accepted <code class="varname">flags</code> may be dependent upon
the texture format used.
</p>
</dd>
<dt>
<span class="term"> <code class="varname">properties</code> </span>
</dt>
<dd>
<p>
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.
<code class="varname">properties</code> can be NULL.
</p>
</dd>
<dt>
<span class="term"> <code class="varname"> errcode_ret </code> </span>
</dt>
<dd>
<p>
</p>
</dd>
</dl>
</div>
</div>
<div class="refsect1">
<a id="description"></a>
<h2>Description</h2>
<p>
<code class="function">clCreateFromEGLImageKHR</code> creates an
EGLImage target of type <span class="type">cl_mem</span> from the
EGLImage source provided as <code class="varname">image</code>.
</p>
<h4><a id="id-1.6.3"></a>Lifetime of Shared Objects</h4>
<p>
An OpenCL memory object created from an EGL image
remains valid according to the lifetime
behaviour as described in EGL_KHR_image_base.
</p>
<p>
"Any EGLImage siblings exist in any client API context"
</p>
<p>
For OpenCL this means that while the application
retains a reference on the <span class="type">cl_mem</span> (EGL
sibling) the image remains valid.
</p>
<h4><a id="id-1.6.7"></a>Synchronizing OpenCL and EGL Access to Shared Objects</h4>
<p>
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
implementations.
</p>
<p>
Prior to calling
<a class="citerefentry" href="clEnqueueAcquireEGLObjectsKHR.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueAcquireEGLObjectsKHR</span></span></a>,
the application must ensure that any
pending operations which access the objects specified in
<code class="varname">mem_objects</code> 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 <code class="function">glFinish</code>
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.
</p>
<p>
Similarly, after calling
<code class="function">clEnqueueReleaseEGLImageObjects</code>,
the application is responsible for
ensuring that any pending OpenCL operations which access
the objects specified in <code class="varname">mem_objects</code>
have completed prior to executing subsequent
commands in other APIs which reference these
objects. This may be accomplished in a portable way by calling
<a class="citerefentry" href="clWaitForEvents.html"><span class="citerefentry"><span class="refentrytitle">clWaitForEvents</span></span></a>
with the event
object returned by
<a class="citerefentry" href="clEnqueueReleaseGLObjects.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueReleaseGLObjects</span></span></a> ,
or by calling
<a class="citerefentry" href="clFinish.html"><span class="citerefentry"><span class="refentrytitle">clFinish</span></span></a>.
As above, some
implementations may offer more efficient methods.
</p>
<p>
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.
</p>
</div>
<div class="refsect1">
<a id="errors"></a>
<h2>Errors</h2>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_CONTEXT</span> if <code class="varname">context</code> is not
a valid OpenCL context.
</li>
<li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_VALUE</span> if <code class="varname">properties</code>
contains invalid values, if <code class="varname">display</code> is not a valid
display object or if <code class="varname">flags</code> are
not in the set defined above.
</li>
<li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_EGL_OBJECT_KHR</span> if <code class="varname">image</code>
is not a valid EGLImage object.
</li>
<li class="listitem" style="list-style-type: disc"><span class="errorname">CL_IMAGE_FORMAT_NOT_SUPPORTED</span>
if the OpenCL implementation is not able to
create a <span class="type">cl_mem</span> compatible with the provided
<span class="type">CLeglImageKHR</span> for an implementation-dependent
reason (this could be caused by, but not limited to, reasons such as
unsupported texture formats, etc).
</li>
<li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_OPERATION</span> if there are
no devices in <code class="varname">context</code> that support images (i.e.
<code class="constant">CL_DEVICE_IMAGE_SUPPORT</code> specified in
table 4.3 (see <a class="citerefentry" href="clGetDeviceInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetDeviceInfo</span></span></a>) is
<code class="constant">CL_FALSE</code>) or if the
flags passed are not supported for that image type.
</li>
<li class="listitem" style="list-style-type: disc"><span class="errorname">CL_OUT_OF_RESOURCES</span> if there is a failure to allocate
resources required by the OpenCL implementation on the device.
</li>
<li class="listitem" style="list-style-type: disc"><span class="errorname">CL_OUT_OF_HOST_MEMORY</span> if there is a failure to allocate
resources required by the OpenCL implementation on the host.
</li>
</ul>
</div>
</div>
<div class="refsect1">
<a id="specification"></a>
<h2>Specification</h2>
<p>
<img src="pdficon_small1.gif" />
<a href="https://www.khronos.org/registry/cl/specs/opencl-2.1-extensions.pdf#page=167" target="OpenCL Spec">OpenCL Specification</a>
</p>
</div>
<div class="refsect1">
<a id="seealso"></a>
<h2>Also see</h2>
<p>
<a class="citerefentry" href="cl_khr_egl_image.html"><span class="citerefentry"><span class="refentrytitle">cl_khr_egl_image</span></span></a>,
<a class="citerefentry" href="cl_khr_egl_event.html"><span class="citerefentry"><span class="refentrytitle">cl_khr_egl_event</span></span></a>
</p>
</div>
<div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4><img xmlns="http://www.w3.org/1999/xhtml" src="KhronosLogo.jpg" /><p xmlns="http://www.w3.org/1999/xhtml"></p>Copyright © 2007-2015 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.
</div>
</div>
</body>
</html>