Release OpenCL 2.2-11 maintenance revision (#68)
* Release OpenCL 2.2-11 maintenance revision
* Update spec release dates on registry index page
diff --git a/index.php b/index.php
index c28aef2..5646be7 100644
--- a/index.php
+++ b/index.php
@@ -35,27 +35,27 @@
<li> OpenCL 2.2 API Specification
(<a href="specs/2.2/html/OpenCL_API.html">HTML</a>)
(<a href="specs/2.2/pdf/OpenCL_API.pdf">PDF</a>)
- (February 5, 2019). </li>
+ (July 19, 2019). </li>
<li> OpenCL Extension Specification
(<a href="specs/2.2/html/OpenCL_Ext.html">HTML</a>)
(<a href="specs/2.2/pdf/OpenCL_Ext.pdf">PDF</a>)
- (February 5, 2019). </li>
+ (July 19, 2019). </li>
<li> OpenCL SPIR-V Environment Specification
(<a href="specs/2.2/html/OpenCL_Env.html">HTML</a>)
(<a href="specs/2.2/pdf/OpenCL_Env.pdf">PDF</a>)
- (February 5, 2019). </li>
+ (July 19, 2019). </li>
<li> OpenCL C Language Specification
(<a href="specs/2.2/html/OpenCL_C.html">HTML</a>)
(<a href="specs/2.2/pdf/OpenCL_C.pdf">PDF</a>)
- (February 5, 2019). </li>
+ (July 19, 2019). </li>
<li> OpenCL C++ Language Specification
(<a href="specs/2.2/html/OpenCL_Cxx.html">HTML</a>)
(<a href="specs/2.2/pdf/OpenCL_Cxx.pdf">PDF</a>)
- (February 5, 2019). </li>
+ (July 19, 2019). </li>
<li> OpenCL ICD Installation Guide Specification
(<a href="specs/2.2/html/OpenCL_ICD_Installation.html">HTML</a>)
(<a href="specs/2.2/pdf/OpenCL_ICD_Installation.pdf">PDF</a>)
- (February 5, 2019). </li>
+ (July 19, 2019). </li>
<li> The <a href="https://www.khronos.org/registry/spir-v/"> OpenCL Extended
Instruction Set for SPIR-V</a> is included as part of the SPIR-V
registry.
diff --git a/specs/2.2/html/OpenCL_API.html b/specs/2.2/html/OpenCL_API.html
index 17a77c5..63c3b31 100644
--- a/specs/2.2/html/OpenCL_API.html
+++ b/specs/2.2/html/OpenCL_API.html
@@ -841,9 +841,9 @@
<h1>The OpenCL<sup>™</sup> Specification</h1>
<div class="details">
<span id="author" class="author">Khronos<sup>®</sup> OpenCL Working Group</span><br>
-<span id="revnumber">version v2.2-10,</span>
-<span id="revdate">Tue, 05 Feb 2019 21:16:07 +0000</span>
-<br><span id="revremark">from git branch: commit: 00422daf5dc013f21ab633479577c7cc225150e2</span>
+<span id="revnumber">version V2.2-11,</span>
+<span id="revdate">Fri, 19 Jul 2019 14:08:01 +0000</span>
+<br><span id="revremark">from git branch: master commit: 2aaf7b58ead9567d8799b22ecc748b4892a1e04e</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
@@ -907,7 +907,7 @@
<li><a href="#_portability">Appendix B: Portability</a></li>
<li><a href="#data-types">Appendix C: Application Data Types</a>
<ul class="sectlevel2">
-<li><a href="#scalar-data-types">Shared Application Scalar Data Types</a></li>
+<li><a href="#scalar-data-types">Supported Application Scalar Data Types</a></li>
<li><a href="#vector-data-types">Supported Application Vector Data Types</a></li>
<li><a href="#alignment-app-data-types">Alignment of Application Data Types</a></li>
<li><a href="#_vector_literals">Vector Literals</a></li>
@@ -918,16 +918,18 @@
<li><a href="#_application_constant_definitions">Application constant definitions</a></li>
</ul>
</li>
-<li><a href="#check-copy-overlap">Appendix D: CL_MEM_COPY_OVERLAP</a></li>
-<li><a href="#_changes">Appendix E: Changes</a>
+<li><a href="#check-copy-overlap">Appendix D: Checking for Memory Copy Overlap</a></li>
+<li><a href="#changes_to_opencl">Appendix E: Changes to OpenCL</a>
<ul class="sectlevel2">
-<li><a href="#_summary_of_changes_from_opencl_1_0">Summary of changes from OpenCL 1.0</a></li>
-<li><a href="#_summary_of_changes_from_opencl_1_1">Summary of changes from OpenCL 1.1</a></li>
-<li><a href="#_summary_of_changes_from_opencl_1_2">Summary of changes from OpenCL 1.2</a></li>
-<li><a href="#_summary_of_changes_from_opencl_2_0">Summary of changes from OpenCL 2.0</a></li>
-<li><a href="#_summary_of_changes_from_opencl_2_1">Summary of changes from OpenCL 2.1</a></li>
+<li><a href="#_summary_of_changes_from_opencl_1_0_to_opencl_1_1">Summary of changes from OpenCL 1.0 to OpenCL 1.1</a></li>
+<li><a href="#_summary_of_changes_from_opencl_1_1_to_opencl_1_2">Summary of changes from OpenCL 1.1 to OpenCL 1.2</a></li>
+<li><a href="#_summary_of_changes_from_opencl_1_2_to_opencl_2_0">Summary of changes from OpenCL 1.2 to OpenCL 2.0</a></li>
+<li><a href="#_summary_of_changes_from_opencl_2_0_to_opencl_2_1">Summary of changes from OpenCL 2.0 to OpenCL 2.1</a></li>
+<li><a href="#_summary_of_changes_from_opencl_2_1_to_opencl_2_2">Summary of changes from OpenCL 2.1 to OpenCL 2.2</a></li>
</ul>
</li>
+<li><a href="#error_codes">Appendix F: Error Codes</a></li>
+<li><a href="#_acknowledgements">Acknowledgements</a></li>
</ul>
</div>
</div>
@@ -978,183 +980,6 @@
respective owners.</p>
</div>
<div style="page-break-after: always;"></div>
-<div class="paragraph">
-<p><strong>Acknowledgements</strong></p>
-</div>
-<div class="paragraph">
-<p>The OpenCL specification is the result of the contributions of many people,
-representing a cross section of the desktop, hand-held, and embedded
-computer industry.
-Following is a partial list of the contributors, including the company that
-they represented at the time of their contribution:</p>
-</div>
-<div class="paragraph">
-<p>Chuck Rose, Adobe<br>
-Eric Berdahl, Adobe<br>
-Shivani Gupta, Adobe<br>
-Bill Licea Kane, AMD<br>
-Ed Buckingham, AMD<br>
-Jan Civlin, AMD<br>
-Laurent Morichetti, AMD<br>
-Mark Fowler, AMD<br>
-Marty Johnson, AMD<br>
-Michael Mantor, AMD<br>
-Norm Rubin, AMD<br>
-Ofer Rosenberg, AMD<br>
-Brian Sumner, AMD<br>
-Victor Odintsov, AMD<br>
-Aaftab Munshi, Apple<br>
-Abe Stephens, Apple<br>
-Alexandre Namaan, Apple<br>
-Anna Tikhonova, Apple<br>
-Chendi Zhang, Apple<br>
-Eric Bainville, Apple<br>
-David Hayward, Apple<br>
-Giridhar Murthy, Apple<br>
-Ian Ollmann, Apple<br>
-Inam Rahman, Apple<br>
-James Shearer, Apple<br>
-MonPing Wang, Apple<br>
-Tanya Lattner, Apple<br>
-Mikael Bourges-Sevenier, Aptina<br>
-Anton Lokhmotov, ARM<br>
-Dave Shreiner, ARM<br>
-Hedley Francis, ARM<br>
-Robert Elliott, ARM<br>
-Scott Moyers, ARM<br>
-Tom Olson, ARM<br>
-Anastasia Stulova, ARM<br>
-Christopher Thompson-Walsh, Broadcom<br>
-Holger Waechtler, Broadcom<br>
-Norman Rink, Broadcom<br>
-Andrew Richards, Codeplay<br>
-Maria Rovatsou, Codeplay<br>
-Alistair Donaldson, Codeplay<br>
-Alastair Murray, Codeplay<br>
-Stephen Frye, Electronic Arts<br>
-Eric Schenk, Electronic Arts<br>
-Daniel Laroche, Freescale<br>
-David Neto, Google<br>
-Robin Grosman, Huawei<br>
-Craig Davies, Huawei<br>
-Brian Horton, IBM<br>
-Brian Watt, IBM<br>
-Gordon Fossum, IBM<br>
-Greg Bellows, IBM<br>
-Joaquin Madruga, IBM<br>
-Mark Nutter, IBM<br>
-Mike Perks, IBM<br>
-Sean Wagner, IBM<br>
-Jon Parr, Imagination Technologies<br>
-Robert Quill, Imagination Technologies<br>
-James McCarthy, Imagination Technologie<br>
-Jon Leech, Independent<br>
-Aaron Kunze, Intel<br>
-Aaron Lefohn, Intel<br>
-Adam Lake, Intel<br>
-Alexey Bader, Intel<br>
-Allen Hux, Intel<br>
-Andrew Brownsword, Intel<br>
-Andrew Lauritzen, Intel<br>
-Bartosz Sochacki, Intel<br>
-Ben Ashbaugh, Intel<br>
-Brian Lewis, Intel<br>
-Geoff Berry, Intel<br>
-Hong Jiang, Intel<br>
-Jayanth Rao, Intel<br>
-Josh Fryman, Intel<br>
-Larry Seiler, Intel<br>
-Mike MacPherson, Intel<br>
-Murali Sundaresan, Intel<br>
-Paul Lalonde, Intel<br>
-Raun Krisch, Intel<br>
-Stephen Junkins, Intel<br>
-Tim Foley, Intel<br>
-Timothy Mattson, Intel<br>
-Yariv Aridor, Intel<br>
-Michael Kinsner, Intel<br>
-Kevin Stevens, Intel<br>
-Benjamin Bergen, Los Alamos National Laboratory<br>
-Roy Ju, Mediatek<br>
-Bor-Sung Liang, Mediatek<br>
-Rahul Agarwal, Mediatek<br>
-Michal Witaszek, Mobica<br>
-JenqKuen Lee, NTHU<br>
-Amit Rao, NVIDIA<br>
-Ashish Srivastava, NVIDIA<br>
-Bastiaan Aarts, NVIDIA<br>
-Chris Cameron, NVIDIA<br>
-Christopher Lamb, NVIDIA<br>
-Dibyapran Sanyal, NVIDIA<br>
-Guatam Chakrabarti, NVIDIA<br>
-Ian Buck, NVIDIA<br>
-Jaydeep Marathe, NVIDIA<br>
-Jian-Zhong Wang, NVIDIA<br>
-Karthik Raghavan Ravi, NVIDIA<br>
-Kedar Patil, NVIDIA<br>
-Manjunath Kudlur, NVIDIA<br>
-Mark Harris, NVIDIA<br>
-Michael Gold, NVIDIA<br>
-Neil Trevett, NVIDIA<br>
-Richard Johnson, NVIDIA<br>
-Sean Lee, NVIDIA<br>
-Tushar Kashalikar, NVIDIA<br>
-Vinod Grover, NVIDIA<br>
-Xiangyun Kong, NVIDIA<br>
-Yogesh Kini, NVIDIA<br>
-Yuan Lin, NVIDIA<br>
-Mayuresh Pise, NVIDIA<br>
-Allan Tzeng, QUALCOMM<br>
-Alex Bourd, QUALCOMM<br>
-Anirudh Acharya, QUALCOMM<br>
-Andrew Gruber, QUALCOMM<br>
-Andrzej Mamona, QUALCOMM<br>
-Benedict Gaster, QUALCOMM<br>
-Bill Torzewski, QUALCOMM<br>
-Bob Rychlik, QUALCOMM<br>
-Chihong Zhang, QUALCOMM<br>
-Chris Mei, QUALCOMM<br>
-Colin Sharp, QUALCOMM<br>
-David Garcia, QUALCOMM<br>
-David Ligon, QUALCOMM<br>
-Jay Yun, QUALCOMM<br>
-Lee Howes, QUALCOMM<br>
-Richard Ruigrok, QUALCOMM<br>
-Robert J. Simpson, QUALCOMM<br>
-Sumesh Udayakumaran, QUALCOMM<br>
-Vineet Goel, QUALCOMM<br>
-Lihan Bin, QUALCOMM<br>
-Vlad Shimanskiy, QUALCOMM<br>
-Jian Liu, QUALCOMM<br>
-Tasneem Brutch, Samsung<br>
-Yoonseo Choi, Samsung<br>
-Dennis Adams, Sony<br>
-Pr-Anders Aronsson, Sony<br>
-Jim Rasmusson, Sony<br>
-Thierry Lepley, STMicroelectronics<br>
-Anton Gorenko, StreamHPC<br>
-Jakub Szuppe, StreamHPC<br>
-Vincent Hindriksen, StreamHPC<br>
-Alan Ward, Texas Instruments<br>
-Yuan Zhao, Texas Instruments<br>
-Pete Curry, Texas Instruments<br>
-Simon McIntosh-Smith, University of Bristol<br>
-James Price, University of Bristol<br>
-Paul Preney, University of Windsor<br>
-Shane Peelar, University of Windsor<br>
-Brian Hutsell, Vivante<br>
-Mike Cai, Vivante<br>
-Sumeet Kumar, Vivante<br>
-Wei-Lun Kao, Vivante<br>
-Xing Wang, Vivante<br>
-Jeff Fifield, Xilinx<br>
-Hem C. Neema, Xilinx<br>
-Henry Styles, Xilinx<br>
-Ralph Wittig, Xilinx<br>
-Ronan Keryell, Xilinx<br>
-AJ Guillon, YetiWare Inc<br></p>
-</div>
-<div style="page-break-after: always;"></div>
</div>
</div>
<div class="sect1">
@@ -1754,9 +1579,9 @@
</dd>
<dt class="hdlist1">Kernel Object </dt>
<dd>
-<p>A <em>kernel object</em> encapsulates a specific <code>__kernel</code> function declared
+<p>A <em>kernel object</em> encapsulates a specific <code><em>kernel</code> function declared
in a <em>program</em> and the argument values to be used when executing this
-<code>__kernel</code> function.</p>
+<code></em>kernel</code> function.</p>
</dd>
<dt class="hdlist1">Kernel Language </dt>
<dd>
@@ -1961,10 +1786,10 @@
When you create an object in OpenCL, its <em>reference count</em> is set to
one.
Subsequent calls to the appropriate <em>retain</em> API (such as
-<strong>clRetainContext</strong>, <strong>clRetainCommandQueue</strong>) increment the <em>reference
+<a href="#clRetainContext"><strong>clRetainContext</strong></a>, <a href="#clRetainCommandQueue"><strong>clRetainCommandQueue</strong></a>) increment the <em>reference
count</em>.
-Calls to the appropriate <em>release</em> API (such as <strong>clReleaseContext</strong>,
-<strong>clReleaseCommandQueue</strong>) decrement the <em>reference count</em>.
+Calls to the appropriate <em>release</em> API (such as <a href="#clReleaseContext"><strong>clReleaseContext</strong></a>,
+<a href="#clReleaseCommandQueue"><strong>clReleaseCommandQueue</strong></a>) decrement the <em>reference count</em>.
Implementations may also modify the <em>reference count</em>, e.g. to track
attached objects or to ensure correct operation of in-progress or
scheduled activities.
@@ -2499,7 +2324,7 @@
<li>
<p><strong>Queued</strong>: The command is enqueued to a command-queue.
A command may reside in the queue until it is flushed either explicitly
-(a call to <strong>clFlush</strong>) or implicitly by some other command.</p>
+(a call to <a href="#clFlush"><strong>clFlush</strong></a>) or implicitly by some other command.</p>
</li>
<li>
<p><strong>Submitted</strong>: The command is flushed from the command-queue and submitted
@@ -2531,7 +2356,7 @@
<li>
<p><strong>Complete</strong>: The command and its child commands have finished execution
and the status of the event object, if any, associated with the command
-is set to CL_COMPLETE.</p>
+is set to <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>.</p>
</li>
</ol>
</div>
@@ -2555,7 +2380,7 @@
<div class="paragraph">
<p>Commands communicate their status through <em>Event objects</em>.
Successful completion is indicated by setting the event status associated
-with a command to CL_COMPLETE.
+with a command to <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>.
Unsuccessful completion results in abnormal termination of the command which
is indicated by setting the event status to a negative value.
In this case, the command-queue associated with the abnormally terminated
@@ -2587,8 +2412,8 @@
</li>
<li>
<p>The third source of prerequisites can be the presence of non-trivial C
-initializers or C constructors for program scope global variables.
-In this case, OpenCL C/C compiler shall generate program
+initializers or C++ constructors for program scope global variables.
+In this case, OpenCL C/C++ compiler shall generate program
initialization kernels that perform C initialization or C++
construction.
These kernels must be executed by OpenCL runtime on a device before any
@@ -2610,7 +2435,7 @@
linked together) is undefined.</p>
</div>
<div class="paragraph">
-<p>Note that C initializers, C constructors, or C destructors for program
+<p>Note that C initializers, C++ constructors, or C++ destructors for program
scope variables cannot use pointers to coarse grain and fine grain SVM
allocations.</p>
</div>
@@ -2869,7 +2694,7 @@
</li>
<li>
<p>Each of the events in an optional event list defined when the
-kernel-instance was enqueued are set to CL_COMPLETE.</p>
+kernel-instance was enqueued are set to <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>.</p>
</li>
</ul>
</div>
@@ -2886,7 +2711,7 @@
the kernel-instance end their execution, updates to global memory associated
with a command are visible globally, and the device signals successful
completion by setting the event associated with the kernel-enqueue command
-to CL_COMPLETE.</p>
+to <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>.</p>
</div>
<div class="paragraph">
<p>While a command-queue is associated with only one device, a single device
@@ -2974,16 +2799,16 @@
enforce order constraints just as for the command-queue on the host.
These events, however, are only visible to the parent kernel running on the
device.
-When these prerequisite events take on the value CL_COMPLETE, the
+When these prerequisite events take on the value <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>, the
work-groups associated with the child kernel are launched into the devices
work pool.
The device then schedules them for execution on the compute units of the
device.
Child and parent kernels execute asynchronously.
However, a parent will not indicate that it is complete by setting its event
-to CL_COMPLETE until all child kernels have ended execution and have
+to <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a> until all child kernels have ended execution and have
signaled completion by setting any associated events to the value
-CL_COMPLETE.
+<a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>.
Should any child kernel complete with an event status set to a negative
value (i.e. abnormally terminate), the parent kernel will abnormally
terminate and propagate the childs negative event value as the value of the
@@ -3068,7 +2893,7 @@
<ul>
<li>
<p><strong>Launching a command:</strong> A kernel-instance is launched onto a device after
-all events that kernel is waiting-on have been set to CL_COMPLETE.</p>
+all events that kernel is waiting-on have been set to <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>.</p>
</li>
<li>
<p><strong>Ending a command:</strong> Child kernels may be enqueued such that they wait
@@ -3083,7 +2908,7 @@
completed.
This is signaled to the host, a parent kernel or other kernels within
command queues by setting the value of the event associated with a
-kernel to CL_COMPLETE.</p>
+kernel to <a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a>.</p>
</li>
<li>
<p><strong>Blocking Commands:</strong> A blocking command defines a synchronization point
@@ -3096,9 +2921,9 @@
commands can be launched.</p>
</li>
<li>
-<p><strong>clFinish:</strong> This function blocks until all previously enqueued commands
-in the command queue have completed after which <strong>clFinish</strong> defines a
-synchronization point and the <strong>clFinish</strong> function returns.</p>
+<p><a href="#clFinish"><strong>clFinish</strong></a>: This function blocks until all previously enqueued commands
+in the command queue have completed after which <a href="#clFinish"><strong>clFinish</strong></a> defines a
+synchronization point and the <a href="#clFinish"><strong>clFinish</strong></a> function returns.</p>
</li>
</ul>
</div>
@@ -3411,7 +3236,7 @@
<p>Memory objects are allocated by host APIs.
The host program can provide the runtime with a pointer to a block of
continuous memory to hold the memory object when the object is created
-(CL_MEM_USE_HOST_PTR).
+(<a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>).
Alternatively, the physical memory can be managed by the OpenCL runtime and
not be directly accessible to the host program.</p>
</div>
@@ -3616,21 +3441,21 @@
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">Non-SVM buffers</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">OpenCL Memory objects(buffer)</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock"><strong>clCreateBuffer</strong></p></td>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">Host synchronization points on the same or between devices.</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">yes, through Map and Unmap commands.</p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">Coarse-Grained buffer SVM</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">OpenCL Memory objects (buffer)</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock"><strong>clSVMAlloc</strong></p></td>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">Host synchronization points between devices</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">yes, through Map and Unmap commands.</p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">Fine-Grained buffer SVM</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">Bytes within OpenCL Memory objects (buffer)</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock"><strong>clSVMAlloc</strong></p></td>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">Synchronization points plus atomics (if supported)</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">No</p></td>
</tr>
@@ -3811,7 +3636,7 @@
work-items executing across multiple devices and (when using SVM) the
host.
A release performed with <strong>memory_scope_all_svm_devices</strong> to a buffer that
-does not have the CL_MEM_SVM_ATOMICS flag set will commit to at least
+does not have the <a href="#CL_MEM_SVM_ATOMICS"><code>CL_​MEM_​SVM_​ATOMICS</code></a> flag set will commit to at least
<strong>memory_scope_device</strong> visibility, with full synchronization of the
buffer at a queue synchronization point (e.g. an OpenCL event).</p>
</li>
@@ -4472,7 +4297,7 @@
</li>
<li>
<p>The optional OpenCL 2.0 SVM atomic-controlled visibility specified by
-provision of the CL_MEM_SVM_ATOMICS flag must be supported by the device
+provision of the <a href="#CL_MEM_SVM_ATOMICS"><code>CL_​MEM_​SVM_​ATOMICS</code></a> flag must be supported by the device
and the flag provided to the SVM buffer on allocation.</p>
</li>
<li>
@@ -4771,10 +4596,10 @@
sharing that enqueues a kernel to a host command-queue to manipulate the
contents of a region of a buffer that the host thread then accesses
after the kernel completes.
-To do this, the host thread can call <strong>clEnqueueMapBuffer</strong> to enqueue a
+To do this, the host thread can call <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> to enqueue a
blocking-mode map command to map that buffer region, specifying that the
map command must wait on an event signaling the kernels completion.
-When <strong>clEnqueueMapBuffer</strong> returns, any memory operations performed by
+When <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> returns, any memory operations performed by
the kernel to that buffer region will global- happen-before subsequent
memory operations made by the host thread.</p>
</li>
@@ -4787,7 +4612,7 @@
event <strong>E</strong> that signals its completion, then <strong>E</strong> global-synchronizes-with
an API call <strong>X</strong> that waits on <strong>E</strong>.
For example, if a host thread or kernel-instance calls the
-wait-for-events function on <strong>E</strong> (e.g. the <strong>clWaitForEvents</strong> function
+wait-for-events function on <strong>E</strong> (e.g. the <a href="#clWaitForEvents"><strong>clWaitForEvents</strong></a> function
called from a host thread), then <strong>E</strong> global-synchronizes-with that
wait-for-events function call.</p>
</li>
@@ -4814,7 +4639,7 @@
command-queue.</p>
</li>
<li>
-<p>If a host thread executes a <strong>clFinish</strong> call <strong>X</strong>, then the events of all
+<p>If a host thread executes a <a href="#clFinish"><strong>clFinish</strong></a> call <strong>X</strong>, then the events of all
commands enqueued prior to <strong>X</strong> in the command-queue
global-synchronizes-with <strong>X</strong>.</p>
</li>
@@ -4839,8 +4664,8 @@
<li>
<p>If <strong>C</strong> is a command that waits for an event <strong>E</strong>'s completion, and API
function call <strong>X</strong> sets the status of a user event <strong>E</strong>'s status to
-CL_COMPLETE (for example, from a host thread using a
-<strong>clSetUserEventStatus</strong> function), then <strong>X</strong> global-synchronizes-with <strong>C</strong>.</p>
+<a href="#CL_COMPLETE"><code>CL_​COMPLETE</code></a> (for example, from a host thread using a
+<a href="#clSetUserEventStatus"><strong>clSetUserEventStatus</strong></a> function), then <strong>X</strong> global-synchronizes-with <strong>C</strong>.</p>
</li>
<li>
<p>If a device enqueues a command <strong>C</strong> with the
@@ -4895,8 +4720,8 @@
locations and can concurrently update non-overlapping memory regions, but
attempts to update the same memory locations are undefined.
Memory consistency is guaranteed at the OpenCL synchronization points
-without the need for calls to <strong>clEnqueueMapBuffer</strong> and
-<strong>clEnqueueUnmapMemObject</strong>.
+without the need for calls to <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and
+<a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>.
For fine-grained SVM buffers it is guaranteed that at synchronization points
only values written by the kernel will be updated.
No writes to fine-grained SVM buffers can be introduced that were not in the
@@ -4916,7 +4741,7 @@
synchronization points.</p>
</div>
<div class="paragraph">
-<p>A map operation (<strong>clEnqueueMapBuffer</strong> or <strong>clEnqueueMapImage</strong>) performed on a
+<p>A map operation (<a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> or <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) performed on a
non-SVM buffer or a coarse-grained SVM buffer is allowed to overwrite the
entire target region with the latest runtime view of the data as seen by the
command with which the map operation synchronizes, whether the values were
@@ -4982,7 +4807,7 @@
<div class="paragraph">
<p>The device version is an indication of the device’s capabilities separate
from the runtime and compiler as represented by the device info returned by
-<strong>clGetDeviceInfo</strong>.
+<a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>.
Examples of attributes associated with the device version are resource
limits (e.g., minimum size of local memory per compute unit) and extended
functionality (e.g., list of supported KHR extensions).
@@ -5029,8 +4854,8 @@
<p>An OpenCL 2.2 device must support all the requirements of an OpenCL 2.0
device in addition to the SPIR-V intermediate language at version 1.2 or
above.
-Intermediate language is encoded as a part of the binary object and no
-flags are required to be passed to the compiler.</p>
+Intermediate language versioning is encoded as a part of the binary
+object and no flags are required to be passed to the compiler.</p>
</li>
</ol>
</div>
@@ -5049,98 +4874,113 @@
</div>
<div class="sect2">
<h3 id="_querying_platform_info">4.1. Querying Platform Info</h3>
-<div class="paragraph">
-<p>The list of platforms available can be obtained using the following
-function.</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetPlatformIDs(cl_uint num_entries,
- cl_platform_id *platforms,
- cl_uint *num_platforms)</code></pre>
-</div>
-</div>
<div class="paragraph">
+<p>The list of platforms available can be obtained with the function:</p>
+</div>
+<div id="clGetPlatformIDs" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetPlatformIDs(
+ cl_uint num_entries,
+ cl_platform_id* platforms,
+ cl_uint* num_platforms);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>num_entries</em> is the number of cl_platform_id entries that can be added to
<em>platforms</em>.
If <em>platforms</em> is not <code>NULL</code>, the <em>num_entries</em> must be greater than zero.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>platforms</em> returns a list of OpenCL platforms found.
-The cl_platform_id_ values returned in <em>platforms</em> can be used to identify a
+The cl_platform_id values returned in <em>platforms</em> can be used to identify a
specific OpenCL platform.
-If <em>platforms</em> argument is <code>NULL</code>, this argument is ignored.
+If <em>platforms</em> is <code>NULL</code>, this argument is ignored.
The number of OpenCL platforms returned is the minimum of the value
specified by <em>num_entries</em> or the number of OpenCL platforms available.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>num_platforms</em> returns the number of OpenCL platforms available.
If <em>num_platforms</em> is <code>NULL</code>, this argument is ignored.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clGetPlatformIDs</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clGetPlatformIDs"><strong>clGetPlatformIDs</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_VALUE if <em>num_entries</em> is equal to zero and <em>platforms</em> is
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>num_entries</em> is equal to zero and <em>platforms</em> is
not <code>NULL</code> or if both <em>num_platforms</em> and <em>platforms</em> are <code>NULL</code>.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetPlatformInfo(cl_platform_id platform,
- cl_platform_info param_name,
- size_t param_value_size,
- <span class="directive">void</span> *param_value,
- size_t *param_value_size_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>gets specific information about the OpenCL platform.
-The information that can be queried using <strong>clGetPlatformInfo</strong> is specified
-in the <a href="#platform-queries-table">Platform Queries</a> table.</p>
+<p>Specific information about an OpenCL platform can be obtained with
+the function:</p>
</div>
-<div class="paragraph">
-<p><em>platform</em> refers to the platform ID returned by <strong>clGetPlatformIDs</strong> or can
+<div id="clGetPlatformInfo" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetPlatformInfo(
+ cl_platform_id platform,
+ cl_platform_info param_name,
+ size_t param_value_size,
+ <span class="directive">void</span>* param_value,
+ size_t* param_value_size_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>platform</em> refers to the platform ID returned by <a href="#clGetPlatformIDs"><strong>clGetPlatformIDs</strong></a> or can
be <code>NULL</code>.
If <em>platform</em> is <code>NULL</code>, the behavior is implementation-defined.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_name</em> is an enumeration constant that identifies the platform
information being queried.
It can be one of the following values as specified in the
<a href="#platform-queries-table">Platform Queries</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value</em> is a pointer to memory location where appropriate values for a
given <em>param_name</em>, as specified in the <a href="#platform-queries-table">Platform
Queries</a> table, will be returned.
If <em>param_value</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size</em> specifies the size in bytes of memory pointed to by
<em>param_value</em>.
This size in bytes must be ≥ size of return type specified in the
<a href="#platform-queries-table">Platform Queries</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size_ret</em> returns the actual size in bytes of data being
queried by <em>param_name</em>.
If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The information that can be queried using <a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> is specified
+in the <a href="#platform-queries-table">Platform Queries</a> table.</p>
</div>
<table id="platform-queries-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 3. OpenCL Platform Queries</caption>
+<caption class="title">Table 3. List of supported param_names by <a href="#clGetPlatformInfo">clGetPlatformInfo</a></caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 10%;">
@@ -5155,7 +4995,7 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_PLATFORM_PROFILE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_PROFILE"></a><a href="#CL_PLATFORM_PROFILE"><code>CL_​PLATFORM_​PROFILE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]<sup>1</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL profile string.
Returns the profile name supported by the implementation.
@@ -5171,7 +5011,7 @@
<a href="#opencl-embedded-profile">OpenCL Embedded Profile</a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_PLATFORM_VERSION</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_VERSION"></a><a href="#CL_PLATFORM_VERSION"><code>CL_​PLATFORM_​VERSION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL version string.
Returns the OpenCL version supported by the implementation.
@@ -5181,17 +5021,17 @@
<p class="tableblock"> The <em>major_version.minor_version</em> value returned will be 2.2.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_PLATFORM_NAME</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_NAME"></a><a href="#CL_PLATFORM_NAME"><code>CL_​PLATFORM_​NAME</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Platform name string.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_PLATFORM_VENDOR</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_VENDOR"></a><a href="#CL_PLATFORM_VENDOR"><code>CL_​PLATFORM_​VENDOR</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Platform vendor string.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_PLATFORM_EXTENSIONS</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_EXTENSIONS"></a><a href="#CL_PLATFORM_EXTENSIONS"><code>CL_​PLATFORM_​EXTENSIONS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a space separated list of extension names (the extension
names themselves do not contain any spaces) supported by the
@@ -5200,31 +5040,31 @@
platform must be reported here.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_PLATFORM_HOST_TIMER_RESOLUTION</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_PLATFORM_HOST_TIMER_RESOLUTION"></a><a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_​PLATFORM_​HOST_​TIMER_​RESOLUTION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_ulong</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the resolution of the host timer in nanoseconds as used by
- <strong>clGetDeviceAndHostTimer</strong>.</p></td>
+ <a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a>.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
-<p><strong>clGetPlatformInfo</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors<sup>2</sup>.</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_PLATFORM if <em>platform</em> is not a valid platform.</p>
+<p><a href="#CL_INVALID_PLATFORM"><code>CL_​INVALID_​PLATFORM</code></a> if <em>platform</em> is not a valid platform.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>param_name</em> is not one of the supported values or
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>param_name</em> is not one of the supported values or
if size in bytes specified by <em>param_value_size</em> is < size of return
type as specified in the <a href="#platform-queries-table">OpenCL Platform
Queries</a> table, and <em>param_value</em> is not a <code>NULL</code> value.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
<div class="dlist">
<dl>
@@ -5244,44 +5084,72 @@
</ul>
</div>
</div>
+</div>
+</div>
<div class="sect2">
<h3 id="platform-querying-devices">4.2. Querying Devices</h3>
+<div class="openblock">
+<div class="content">
<div class="paragraph">
<p>The list of devices available on a platform can be obtained using the
-following function<sup>3</sup>.</p>
+function<sup>3</sup>:</p>
</div>
-<div class="listingblock">
+<div id="clGetDeviceIDs" class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetDeviceIDs(cl_platform_id platform,
- cl_device_type device_type,
- cl_uint num_entries,
- cl_device_id * devices,
- cl_uint *num_devices)</code></pre>
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetDeviceIDs(
+ cl_platform_id platform,
+ cl_device_type device_type,
+ cl_uint num_entries,
+ cl_device_id* devices,
+ cl_uint* num_devices);</code></pre>
</div>
</div>
-<div class="paragraph">
-<p><em>platform</em> refers to the platform ID returned by <strong>clGetPlatformIDs</strong> or can
+<div class="ulist">
+<ul>
+<li>
+<p><em>platform</em> refers to the platform ID returned by <a href="#clGetPlatformIDs"><strong>clGetPlatformIDs</strong></a> or can
be <code>NULL</code>.
If <em>platform</em> is <code>NULL</code>, the behavior is implementation-defined.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>device_type</em> is a bitfield that identifies the type of OpenCL device.
The <em>device_type</em> can be used to query specific OpenCL devices or all OpenCL
devices available.
The valid values for <em>device_type</em> are specified in the
<a href="#device-categories-table">Device Categories</a> table.</p>
-</div>
+</li>
+<li>
+<p><em>num_entries</em> is the number of cl_device_id entries that can be added to
+<em>devices</em>.
+If <em>devices</em> is not <code>NULL</code>, the <em>num_entries</em> must be greater than zero.</p>
+</li>
+<li>
+<p><em>devices</em> returns a list of OpenCL devices found.
+The cl_device_id values returned in <em>devices</em> can be used to identify a
+specific OpenCL device.
+If <em>devices</em> is <code>NULL</code>, this argument is ignored.
+The number of OpenCL devices returned is the minimum of the value specified
+by <em>num_entries</em> or the number of OpenCL devices whose type matches
+<em>device_type</em>.</p>
+</li>
+<li>
+<p><em>num_devices</em> returns the number of OpenCL devices available that match
+<em>device_type</em>.
+If <em>num_devices</em> is <code>NULL</code>, this argument is ignored.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">3</dt>
<dd>
-<p><strong>clGetDeviceIDs</strong> may return all or a subset of the actual physical
+<p><a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> may return all or a subset of the actual physical
devices present in the platform and that match <em>device_type</em>.</p>
</dd>
</dl>
</div>
+</li>
+</ul>
+</div>
<table id="device-categories-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 4. List of OpenCL Device Categories</caption>
+<caption class="title">Table 4. List of supported device_types by <a href="#clGetDeviceIDs">clGetDeviceIDs</a></caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
@@ -5294,143 +5162,155 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_TYPE_CPU</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_CPU"></a><a href="#CL_DEVICE_TYPE_CPU"><code>CL_​DEVICE_​TYPE_​CPU</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An OpenCL device that is the host processor.
The host processor runs the OpenCL implementations and is a single or
multi-core CPU.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_TYPE_GPU</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_GPU"></a><a href="#CL_DEVICE_TYPE_GPU"><code>CL_​DEVICE_​TYPE_​GPU</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An OpenCL device that is a GPU.
By this we mean that the device can also be used to accelerate a 3D API
such as OpenGL or DirectX.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_TYPE_ACCELERATOR</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_ACCELERATOR"></a><a href="#CL_DEVICE_TYPE_ACCELERATOR"><code>CL_​DEVICE_​TYPE_​ACCELERATOR</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Dedicated OpenCL accelerators (for example the IBM CELL Blade).
These devices communicate with the host processor using a peripheral
interconnect such as PCIe.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_TYPE_CUSTOM</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_CUSTOM"></a><a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Dedicated accelerators that do not support programs written in an OpenCL
kernel language,</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_TYPE_DEFAULT</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_DEFAULT"></a><a href="#CL_DEVICE_TYPE_DEFAULT"><code>CL_​DEVICE_​TYPE_​DEFAULT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The default OpenCL device in the system.
- The default device cannot be a <strong>CL_DEVICE_TYPE_CUSTOM</strong> device.</p></td>
+ The default device cannot be a <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a> device.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_TYPE_ALL</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE_ALL"></a><a href="#CL_DEVICE_TYPE_ALL"><code>CL_​DEVICE_​TYPE_​ALL</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">All OpenCL devices available in the system except
- <strong>CL_DEVICE_TYPE_CUSTOM</strong> devices..</p></td>
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a> devices..</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
-<p><em>num_entries</em> is the number of cl_device_id entries that can be added to
-<em>devices</em>.
-If <em>devices</em> is not <code>NULL</code>, the <em>num_entries</em> must be greater than zero.</p>
-</div>
-<div class="paragraph">
-<p><em>devices</em> returns a list of OpenCL devices found.
-The cl_device_id values returned in <em>devices</em> can be used to identify a
-specific OpenCL device.
-If <em>devices</em> argument is <code>NULL</code>, this argument is ignored.
-The number of OpenCL devices returned is the minimum of the value specified
-by <em>num_entries</em> or the number of OpenCL devices whose type matches
-<em>device_type</em>.</p>
-</div>
-<div class="paragraph">
-<p><em>num_devices</em> returns the number of OpenCL devices available that match
-<em>device_type</em>.
-If <em>num_devices</em> is <code>NULL</code>, this argument is ignored.</p>
-</div>
-<div class="paragraph">
-<p><strong>clGetDeviceIDs</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_PLATFORM if <em>platform</em> is not a valid platform.</p>
+<p><a href="#CL_INVALID_PLATFORM"><code>CL_​INVALID_​PLATFORM</code></a> if <em>platform</em> is not a valid platform.</p>
</li>
<li>
-<p>CL_INVALID_DEVICE_TYPE if <em>device_type</em> is not a valid value.</p>
+<p><a href="#CL_INVALID_DEVICE_TYPE"><code>CL_​INVALID_​DEVICE_​TYPE</code></a> if <em>device_type</em> is not a valid value.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>num_entries</em> is equal to zero and <em>devices</em> is not
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>num_entries</em> is equal to zero and <em>devices</em> is not
<code>NULL</code> or if both <em>num_devices</em> and <em>devices</em> are <code>NULL</code>.</p>
</li>
<li>
-<p>CL_DEVICE_NOT_FOUND if no OpenCL devices that matched <em>device_type</em> were
+<p><a href="#CL_DEVICE_NOT_FOUND"><code>CL_​DEVICE_​NOT_​FOUND</code></a> if no OpenCL devices that matched <em>device_type</em> were
found.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The application can query specific capabilities of the OpenCL device(s)
-returned by <strong>clGetDeviceIDs</strong>.
+returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>.
This can be used by the application to determine which device(s) to use.</p>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetDeviceInfo(cl_device_id device,
- cl_device_info param_name,
- size_t param_value_size,
- <span class="directive">void</span> *param_value,
- size_t *param_value_size_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>gets specific information about an OpenCL device.</p>
+<p>To get specific information about an OpenCL device, call the function:</p>
</div>
-<div class="paragraph">
-<p><em>device</em> may be a device returned by <strong>clGetDeviceIDs</strong> or a sub-device
-created by <strong>clCreateSubDevices</strong>.
+<div id="clGetDeviceInfo" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetDeviceInfo(
+ cl_device_id device,
+ cl_device_info param_name,
+ size_t param_value_size,
+ <span class="directive">void</span>* param_value,
+ size_t* param_value_size_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>device</em> may be a device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> or a sub-device
+created by <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>.
If <em>device</em> is a sub-device, the specific information for the sub-device
will be returned.
-The information that can be queried using <strong>clGetDeviceInfo</strong> is specified in
+The information that can be queried using <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> is specified in
the <a href="#device-queries-table">Device Queries</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_name</em> is an enumeration constant that identifies the device
information being queried.
It can be one of the following values as specified in the
<a href="#device-queries-table">Device Queries</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value</em> is a pointer to memory location where appropriate values for a
given <em>param_name</em>, as specified in the <a href="#device-queries-table">Device
Queries</a> table, will be returned.
If <em>param_value</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size</em> specifies the size in bytes of memory pointed to by
<em>param_value</em>.
This size in bytes must be ≥ size of return type specified in the
<a href="#device-queries-table">Device Queries</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size_ret</em> returns the actual size in bytes of data being
queried by <em>param_name</em>.
If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The device queries described in the <a href="#device-queries-table">Device Queries</a>
+table should return the same information for a root-level device i.e. a
+device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> and any sub-devices created from this
+device except for the following queries:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#CL_DEVICE_GLOBAL_MEM_CACHE_SIZE"><code>CL_​DEVICE_​GLOBAL_​MEM_​CACHE_​SIZE</code></a></p>
+</li>
+<li>
+<p><a href="#CL_DEVICE_BUILT_IN_KERNELS"><code>CL_​DEVICE_​BUILT_​IN_​KERNELS</code></a></p>
+</li>
+<li>
+<p><a href="#CL_DEVICE_PARENT_DEVICE"><code>CL_​DEVICE_​PARENT_​DEVICE</code></a></p>
+</li>
+<li>
+<p><a href="#CL_DEVICE_PARTITION_TYPE"><code>CL_​DEVICE_​PARTITION_​TYPE</code></a></p>
+</li>
+<li>
+<p><a href="#CL_DEVICE_REFERENCE_COUNT"><code>CL_​DEVICE_​REFERENCE_​COUNT</code></a></p>
+</li>
+</ul>
</div>
<table id="device-queries-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 5. OpenCL Device Queries</caption>
+<caption class="title">Table 5. List of supported param_names by <a href="#clGetDeviceInfo">clGetDeviceInfo</a></caption>
<colgroup>
<col style="width: 30%;">
<col style="width: 20%;">
@@ -5445,96 +5325,96 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_TYPE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_TYPE"></a><a href="#CL_DEVICE_TYPE"><code>CL_​DEVICE_​TYPE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_type</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The OpenCL device type.
Currently supported values are:</p>
-<p class="tableblock"> CL_DEVICE_TYPE_CPU, CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ACCELERATOR,
- CL_DEVICE_TYPE_DEFAULT, a combination of the above types or
- CL_DEVICE_TYPE_CUSTOM.</p></td>
+<p class="tableblock"> <a href="#CL_DEVICE_TYPE_CPU"><code>CL_​DEVICE_​TYPE_​CPU</code></a>, <a href="#CL_DEVICE_TYPE_GPU"><code>CL_​DEVICE_​TYPE_​GPU</code></a>, <a href="#CL_DEVICE_TYPE_ACCELERATOR"><code>CL_​DEVICE_​TYPE_​ACCELERATOR</code></a>,
+ <a href="#CL_DEVICE_TYPE_DEFAULT"><code>CL_​DEVICE_​TYPE_​DEFAULT</code></a>, a combination of the above types, or
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_VENDOR_ID</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_VENDOR_ID"></a><a href="#CL_DEVICE_VENDOR_ID"><code>CL_​DEVICE_​VENDOR_​ID</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A unique device vendor identifier.
An example of a unique device identifier could be the PCIe ID.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_COMPUTE_UNITS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_COMPUTE_UNITS"></a><a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_​DEVICE_​MAX_​COMPUTE_​UNITS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The number of parallel compute units on the OpenCL device.
A work-group executes on a single compute unit.
The minimum value is 1.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"></a><a href="#CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"><code>CL_​DEVICE_​MAX_​WORK_​ITEM_​DIMENSIONS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum dimensions that specify the global and local work-item IDs
used by the data parallel execution model. (Refer to
- <strong>clEnqueueNDRangeKernel</strong>).
+ <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>).
The minimum value is 3 for devices that are not of type
- CL_DEVICE_TYPE_CUSTOM.</p></td>
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_WORK_ITEM_SIZES</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WORK_ITEM_SIZES"></a><a href="#CL_DEVICE_MAX_WORK_ITEM_SIZES"><code>CL_​DEVICE_​MAX_​WORK_​ITEM_​SIZES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t []</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of work-items that can be specified in each dimension
- of the work-group to <strong>clEnqueueNDRangeKernel</strong>.</p>
+ of the work-group to <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a>.</p>
<p class="tableblock"> Returns <em>n</em> size_t entries, where <em>n</em> is the value returned by the
- query for CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS.</p>
+ query for <a href="#CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS"><code>CL_​DEVICE_​MAX_​WORK_​ITEM_​DIMENSIONS</code></a>.</p>
<p class="tableblock"> The minimum value is (1, 1, 1) for devices that are not of type
- CL_DEVICE_TYPE_CUSTOM.</p></td>
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_WORK_GROUP_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WORK_GROUP_SIZE"></a><a href="#CL_DEVICE_MAX_WORK_GROUP_SIZE"><code>CL_​DEVICE_​MAX_​WORK_​GROUP_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of work-items in a work-group that a device is
capable of executing on a single compute unit, for any given
kernel-instance running on the device. (Refer also to
- <strong>clEnqueueNDRangeKernel</strong> and CL_KERNEL_WORK_GROUP_SIZE ).
+ <a href="#clEnqueueNDRangeKernel"><strong>clEnqueueNDRangeKernel</strong></a> and <a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_​KERNEL_​WORK_​GROUP_​SIZE</code></a> ).
The minimum value is 1.
The returned value is an upper limit and will not necessarily
maximize performance.
This maximum may be larger than supported by a specific kernel
- (refer to the CL_KERNEL_WORK_GROUP_SIZE query of <strong>clGetKernelWorkGroupInfo</strong>).</p></td>
+ (refer to the <a href="#CL_KERNEL_WORK_GROUP_SIZE"><code>CL_​KERNEL_​WORK_​GROUP_​SIZE</code></a> query of <a href="#clGetKernelWorkGroupInfo"><strong>clGetKernelWorkGroupInfo</strong></a>).</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR <br>
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT <br>
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT <br>
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG <br>
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT <br>
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE<br>
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​CHAR</code></a> <br>
+ <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​SHORT</code></a> <br>
+ <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​INT</code></a> <br>
+ <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​LONG</code></a> <br>
+ <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​FLOAT</code></a> <br>
+ <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​DOUBLE</code></a><br>
+ <a id="CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF"></a><a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​HALF</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Preferred native vector width size for built-in scalar types that
can be put into vectors.
The vector width is defined as the number of scalar elements that
can be stored in the vector.</p>
<p class="tableblock"> If double precision is not supported,
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE must return 0.</p>
+ <a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​DOUBLE</code></a> must return 0.</p>
<p class="tableblock"> If the <strong>cl_khr_fp16</strong> extension is not supported,
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF must return 0.</p></td>
+ <a href="#CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF"><code>CL_​DEVICE_​PREFERRED_​VECTOR_​WIDTH_​HALF</code></a> must return 0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR <br>
- CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT <br>
- CL_DEVICE_NATIVE_VECTOR_WIDTH_INT <br>
- CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG <br>
- CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT <br>
- CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE<br>
- CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​CHAR</code></a> <br>
+ <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​SHORT</code></a> <br>
+ <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_INT"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_INT"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​INT</code></a> <br>
+ <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​LONG</code></a> <br>
+ <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​FLOAT</code></a> <br>
+ <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​DOUBLE</code></a><br>
+ <a id="CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF"></a><a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​HALF</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the native ISA vector width.
The vector width is defined as the number of scalar elements that
can be stored in the vector.</p>
<p class="tableblock"> If double precision is not supported,
- CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE must return 0.</p>
+ <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​DOUBLE</code></a> must return 0.</p>
<p class="tableblock"> If the <strong>cl_khr_fp16</strong> extension is not supported,
- CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF must return 0.</p></td>
+ <a href="#CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF"><code>CL_​DEVICE_​NATIVE_​VECTOR_​WIDTH_​HALF</code></a> must return 0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_CLOCK_FREQUENCY</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_CLOCK_FREQUENCY"></a><a href="#CL_DEVICE_MAX_CLOCK_FREQUENCY"><code>CL_​DEVICE_​MAX_​CLOCK_​FREQUENCY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Clock frequency of the device in MHz.
The meaning of this value is implementation-defined.
@@ -5544,107 +5424,107 @@
reasons, the returned clock frequency may be any valid frequency.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_ADDRESS_BITS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ADDRESS_BITS"></a><a href="#CL_DEVICE_ADDRESS_BITS"><code>CL_​DEVICE_​ADDRESS_​BITS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The default compute device address space size of the global address
space specified as an unsigned integer value in bits.
Currently supported values are 32 or 64 bits.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_MEM_ALLOC_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_MEM_ALLOC_SIZE"></a><a href="#CL_DEVICE_MAX_MEM_ALLOC_SIZE"><code>CL_​DEVICE_​MAX_​MEM_​ALLOC_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_ulong</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max size of memory object allocation in bytes.
The minimum value is max(min(1024 × 1024 × 1024, 1/4<sup>th</sup>
- of CL_DEVICE_GLOBAL_MEM_SIZE), 32 × 1024 × 1024) for
- devices that are not of type CL_DEVICE_TYPE_CUSTOM.</p></td>
+ of <a href="#CL_DEVICE_GLOBAL_MEM_SIZE"><code>CL_​DEVICE_​GLOBAL_​MEM_​SIZE</code></a>), 32 × 1024 × 1024) for
+ devices that are not of type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE_SUPPORT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_SUPPORT"></a><a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_TRUE if images are supported by the OpenCL device and CL_FALSE
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if images are supported by the OpenCL device and <a href="#CL_FALSE"><code>CL_​FALSE</code></a>
otherwise.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_READ_IMAGE_ARGS<sup>4</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_READ_IMAGE_ARGS"></a><a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​READ_​IMAGE_​ARGS</code></a><sup>4</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the
read_only qualifier.
- The minimum value is 128 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+ The minimum value is 128 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_WRITE_IMAGE_ARGS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_WRITE_IMAGE_ARGS"></a><a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​WRITE_​IMAGE_​ARGS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the
write_only qualifier.
- The minimum value is 64 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+ The minimum value is 64 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS<sup>5</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"></a><a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​READ_​WRITE_​IMAGE_​ARGS</code></a><sup>5</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max number of image objects arguments of a kernel declared with the
write_only or read_write qualifier.
- The minimum value is 64 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+ The minimum value is 64 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IL_VERSION</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IL_VERSION"></a><a href="#CL_DEVICE_IL_VERSION"><code>CL_​DEVICE_​IL_​VERSION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The intermediate languages that can be supported by
- <strong>clCreateProgramWithIL</strong> for this device.
+ <a href="#clCreateProgramWithIL"><strong>clCreateProgramWithIL</strong></a> for this device.
Returns a space-separated list of IL version strings of the form
<IL_Prefix>_<Major_Version>.<Minor_Version>.
For OpenCL 2.2, SPIR-V is a required IL prefix.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE2D_MAX_WIDTH</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE2D_MAX_WIDTH"></a><a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_​DEVICE_​IMAGE2D_​MAX_​WIDTH</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max width of 2D image or 1D image not created from a buffer object
in pixels.</p>
-<p class="tableblock"> The minimum value is 16384 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 16384 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE2D_MAX_HEIGHT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE2D_MAX_HEIGHT"></a><a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_​DEVICE_​IMAGE2D_​MAX_​HEIGHT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max height of 2D image in pixels.</p>
-<p class="tableblock"> The minimum value is 16384 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 16384 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE3D_MAX_WIDTH</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE3D_MAX_WIDTH"></a><a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_​DEVICE_​IMAGE3D_​MAX_​WIDTH</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max width of 3D image in pixels.</p>
-<p class="tableblock"> The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE3D_MAX_HEIGHT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE3D_MAX_HEIGHT"></a><a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_​DEVICE_​IMAGE3D_​MAX_​HEIGHT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max height of 3D image in pixels.</p>
-<p class="tableblock"> The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE3D_MAX_DEPTH</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE3D_MAX_DEPTH"></a><a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_​DEVICE_​IMAGE3D_​MAX_​DEPTH</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max depth of 3D image in pixels.</p>
-<p class="tableblock"> The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE_MAX_BUFFER_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_MAX_BUFFER_SIZE"></a><a href="#CL_DEVICE_IMAGE_MAX_BUFFER_SIZE"><code>CL_​DEVICE_​IMAGE_​MAX_​BUFFER_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max number of pixels for a 1D image created from a buffer object.</p>
-<p class="tableblock"> The minimum value is 65536 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 65536 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE_MAX_ARRAY_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_MAX_ARRAY_SIZE"></a><a href="#CL_DEVICE_IMAGE_MAX_ARRAY_SIZE"><code>CL_​DEVICE_​IMAGE_​MAX_​ARRAY_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max number of images in a 1D or 2D image array.</p>
-<p class="tableblock"> The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 2048 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_SAMPLERS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_SAMPLERS"></a><a href="#CL_DEVICE_MAX_SAMPLERS"><code>CL_​DEVICE_​MAX_​SAMPLERS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of samplers that can be used in a kernel.</p>
-<p class="tableblock"> The minimum value is 16 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.</p></td>
+<p class="tableblock"> The minimum value is 16 if <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE_PITCH_ALIGNMENT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_PITCH_ALIGNMENT"></a><a href="#CL_DEVICE_IMAGE_PITCH_ALIGNMENT"><code>CL_​DEVICE_​IMAGE_​PITCH_​ALIGNMENT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The row pitch alignment size in pixels for 2D images created from a
buffer.
@@ -5652,24 +5532,24 @@
<p class="tableblock"> If the device does not support images, this value must be 0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"></a><a href="#CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"><code>CL_​DEVICE_​IMAGE_​BASE_​ADDRESS_​ALIGNMENT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This query should be used when a 2D image is created from a buffer
- which was created using CL_MEM_USE_HOST_PTR.
+ which was created using <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>.
The value returned must be a power of 2.</p>
<p class="tableblock"> This query specifies the minimum alignment in pixels of the host_ptr
- specified to <strong>clCreateBuffer</strong>.</p>
+ specified to <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a>.</p>
<p class="tableblock"> If the device does not support images, this value must be 0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_PIPE_ARGS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_PIPE_ARGS"></a><a href="#CL_DEVICE_MAX_PIPE_ARGS"><code>CL_​DEVICE_​MAX_​PIPE_​ARGS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of pipe objects that can be passed as arguments
to a kernel.
The minimum value is 16.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS"></a><a href="#CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS"><code>CL_​DEVICE_​PIPE_​MAX_​ACTIVE_​RESERVATIONS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of reservations that can be active for a pipe per
work-item in a kernel.
@@ -5678,117 +5558,118 @@
The minimum value is 1.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PIPE_MAX_PACKET_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PIPE_MAX_PACKET_SIZE"></a><a href="#CL_DEVICE_PIPE_MAX_PACKET_SIZE"><code>CL_​DEVICE_​PIPE_​MAX_​PACKET_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum size of pipe packet in bytes.
The minimum value is 1024 bytes.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_PARAMETER_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_PARAMETER_SIZE"></a><a href="#CL_DEVICE_MAX_PARAMETER_SIZE"><code>CL_​DEVICE_​MAX_​PARAMETER_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max size in bytes of all arguments that can be passed to a kernel.</p>
<p class="tableblock"> The minimum value is 1024 for devices that are not of type
- CL_DEVICE_TYPE_CUSTOM.
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.
For this minimum value, only a maximum of 128 arguments can be
passed to a kernel</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MEM_BASE_ADDR_ALIGN</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MEM_BASE_ADDR_ALIGN"></a><a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Alignment requirement (in bits) for sub-buffer offsets.
The minimum value is the size (in bits) of the largest OpenCL
built-in data type supported by the device (long16 in FULL profile,
long16 or int16 in EMBEDDED profile) for devices that are not of
- type CL_DEVICE_TYPE_CUSTOM.</p></td>
+ type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_SINGLE_FP_CONFIG<sup>6</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_SINGLE_FP_CONFIG"></a><a href="#CL_DEVICE_SINGLE_FP_CONFIG"><code>CL_​DEVICE_​SINGLE_​FP_​CONFIG</code></a><sup>6</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_fp_config</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Describes single precision floating-point capability of the device.
This is a bit-field that describes one or more of the following
values:</p>
-<p class="tableblock"> CL_FP_DENORM - denorms are supported</p>
-<p class="tableblock"> CL_FP_INF_NAN - INF and quiet NaNs are supported.</p>
-<p class="tableblock"> CL_FP_ROUND_TO_NEAREST-- round to nearest even rounding mode
+<p class="tableblock"> <a id="CL_FP_DENORM"></a><a href="#CL_FP_DENORM"><code>CL_​FP_​DENORM</code></a> - denorms are supported</p>
+<p class="tableblock"> <a id="CL_FP_INF_NAN"></a><a href="#CL_FP_INF_NAN"><code>CL_​FP_​INF_​NAN</code></a> - INF and quiet NaNs are supported.</p>
+<p class="tableblock"> <a id="CL_FP_ROUND_TO_NEAREST"></a><a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_​FP_​ROUND_​TO_​NEAREST</code></a>-- round to nearest even rounding mode
supported</p>
-<p class="tableblock"> CL_FP_ROUND_TO_ZERO - round to zero rounding mode supported</p>
-<p class="tableblock"> CL_FP_ROUND_TO_INF - round to positive and negative infinity
+<p class="tableblock"> <a id="CL_FP_ROUND_TO_ZERO"></a><a href="#CL_FP_ROUND_TO_ZERO"><code>CL_​FP_​ROUND_​TO_​ZERO</code></a> - round to zero rounding mode supported</p>
+<p class="tableblock"> <a id="CL_FP_ROUND_TO_INF"></a><a href="#CL_FP_ROUND_TO_INF"><code>CL_​FP_​ROUND_​TO_​INF</code></a> - round to positive and negative infinity
rounding modes supported</p>
-<p class="tableblock"> CL_FP_FMA - IEEE754-2008 fused multiply-add is supported.</p>
-<p class="tableblock"> CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT - divide and sqrt are correctly
+<p class="tableblock"> <a id="CL_FP_FMA"></a><a href="#CL_FP_FMA"><code>CL_​FP_​FMA</code></a> - IEEE754-2008 fused multiply-add is supported.</p>
+<p class="tableblock"> <a id="CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT"></a><a href="#CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT"><code>CL_​FP_​CORRECTLY_​ROUNDED_​DIVIDE_​SQRT</code></a> - divide and sqrt are correctly
rounded as defined by the IEEE754 specification.</p>
-<p class="tableblock"> CL_FP_SOFT_FLOAT - Basic floating-point operations (such as
+<p class="tableblock"> <a id="CL_FP_SOFT_FLOAT"></a><a href="#CL_FP_SOFT_FLOAT"><code>CL_​FP_​SOFT_​FLOAT</code></a> - Basic floating-point operations (such as
addition, subtraction, multiplication) are implemented in software.</p>
<p class="tableblock"> For the full profile, the mandated minimum floating-point capability
- for devices that are not of type CL_DEVICE_TYPE_CUSTOM is:
- CL_FP_ROUND_TO_NEAREST | CL_FP_INF_NAN.</p>
-<p class="tableblock"> For the embedded profile, see section 10.</p></td>
+ for devices that are not of type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a> is:
+ <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_​FP_​ROUND_​TO_​NEAREST</code></a> | <a href="#CL_FP_INF_NAN"><code>CL_​FP_​INF_​NAN</code></a>.</p>
+<p class="tableblock"> For the embedded profile, see the
+ <a href="#embedded-profile-single-fp-config-requirements">dedicated table</a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_DOUBLE_FP_CONFIG<sup>7</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_DOUBLE_FP_CONFIG"></a><a href="#CL_DEVICE_DOUBLE_FP_CONFIG"><code>CL_​DEVICE_​DOUBLE_​FP_​CONFIG</code></a><sup>7</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_fp_config</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Describes double precision floating-point capability of the OpenCL
device.
This is a bit-field that describes one or more of the following
values:</p>
-<p class="tableblock"> CL_FP_DENORM - denorms are supported</p>
-<p class="tableblock"> CL_FP_INF_NAN - INF and NaNs are supported.</p>
-<p class="tableblock"> CL_FP_ROUND_TO_NEAREST - round to nearest even rounding mode
+<p class="tableblock"> <a href="#CL_FP_DENORM"><code>CL_​FP_​DENORM</code></a> - denorms are supported</p>
+<p class="tableblock"> <a href="#CL_FP_INF_NAN"><code>CL_​FP_​INF_​NAN</code></a> - INF and NaNs are supported.</p>
+<p class="tableblock"> <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_​FP_​ROUND_​TO_​NEAREST</code></a> - round to nearest even rounding mode
supported.</p>
-<p class="tableblock"> CL_FP_ROUND_TO_ZERO - round to zero rounding mode supported.</p>
-<p class="tableblock"> CL_FP_ROUND_TO_INF - round to positive and negative infinity
+<p class="tableblock"> <a href="#CL_FP_ROUND_TO_ZERO"><code>CL_​FP_​ROUND_​TO_​ZERO</code></a> - round to zero rounding mode supported.</p>
+<p class="tableblock"> <a href="#CL_FP_ROUND_TO_INF"><code>CL_​FP_​ROUND_​TO_​INF</code></a> - round to positive and negative infinity
rounding modes supported.</p>
-<p class="tableblock"> CL_FP_FMA - IEEE754-2008 fused multiply-add is supported.</p>
-<p class="tableblock"> CL_FP_SOFT_FLOAT - Basic floating-point operations (such as
+<p class="tableblock"> <a href="#CL_FP_FMA"><code>CL_​FP_​FMA</code></a> - IEEE754-2008 fused multiply-add is supported.</p>
+<p class="tableblock"> <a href="#CL_FP_SOFT_FLOAT"><code>CL_​FP_​SOFT_​FLOAT</code></a> - Basic floating-point operations (such as
addition, subtraction, multiplication) are implemented in software.</p>
<p class="tableblock"> Double precision is an optional feature so the mandated minimum
double precision floating-point capability is 0.</p>
<p class="tableblock"> If double precision is supported by the device, then the minimum
double precision floating-point capability must be:<br>
- CL_FP_FMA |<br>
- CL_FP_ROUND_TO_NEAREST |<br>
- CL_FP_INF_NAN |<br>
- CL_FP_DENORM.</p></td>
+ <a href="#CL_FP_FMA"><code>CL_​FP_​FMA</code></a> |<br>
+ <a href="#CL_FP_ROUND_TO_NEAREST"><code>CL_​FP_​ROUND_​TO_​NEAREST</code></a> |<br>
+ <a href="#CL_FP_INF_NAN"><code>CL_​FP_​INF_​NAN</code></a> |<br>
+ <a href="#CL_FP_DENORM"><code>CL_​FP_​DENORM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_GLOBAL_MEM_CACHE_TYPE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_CACHE_TYPE"></a><a href="#CL_DEVICE_GLOBAL_MEM_CACHE_TYPE"><code>CL_​DEVICE_​GLOBAL_​MEM_​CACHE_​TYPE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_mem_cache_type</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Type of global memory cache supported.
- Valid values are: CL_NONE, CL_READ_ONLY_CACHE and
- CL_READ_WRITE_CACHE.</p></td>
+ Valid values are: <a href="#CL_NONE"><code>CL_​NONE</code></a>, <a id="CL_READ_ONLY_CACHE"></a><a href="#CL_READ_ONLY_CACHE"><code>CL_​READ_​ONLY_​CACHE</code></a>, and
+ <a id="CL_READ_WRITE_CACHE"></a><a href="#CL_READ_WRITE_CACHE"><code>CL_​READ_​WRITE_​CACHE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE"></a><a href="#CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE"><code>CL_​DEVICE_​GLOBAL_​MEM_​CACHELINE_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Size of global memory cache line in bytes.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_GLOBAL_MEM_CACHE_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_CACHE_SIZE"></a><a href="#CL_DEVICE_GLOBAL_MEM_CACHE_SIZE"><code>CL_​DEVICE_​GLOBAL_​MEM_​CACHE_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_ulong</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Size of global memory cache in bytes.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_GLOBAL_MEM_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_MEM_SIZE"></a><a href="#CL_DEVICE_GLOBAL_MEM_SIZE"><code>CL_​DEVICE_​GLOBAL_​MEM_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_ulong</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Size of global device memory in bytes.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE"></a><a href="#CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE"><code>CL_​DEVICE_​MAX_​CONSTANT_​BUFFER_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_ulong</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max size in bytes of a constant buffer allocation.
The minimum value is 64 KB for devices that are not of type
- CL_DEVICE_TYPE_CUSTOM.</p></td>
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_CONSTANT_ARGS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_CONSTANT_ARGS"></a><a href="#CL_DEVICE_MAX_CONSTANT_ARGS"><code>CL_​DEVICE_​MAX_​CONSTANT_​ARGS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Max number of arguments declared with the <code>__constant</code> qualifier
in a kernel.
The minimum value is 8 for devices that are not of type
- CL_DEVICE_TYPE_CUSTOM.</p></td>
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE"></a><a href="#CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE"><code>CL_​DEVICE_​MAX_​GLOBAL_​VARIABLE_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of bytes of storage that may be allocated for any
single variable in program scope or inside a function in an OpenCL
@@ -5796,7 +5677,7 @@
<p class="tableblock"> The minimum value is 64 KB.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE"></a><a href="#CL_DEVICE_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE"><code>CL_​DEVICE_​GLOBAL_​VARIABLE_​PREFERRED_​TOTAL_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum preferred total size, in bytes, of all program variables in
the global address space.
@@ -5807,102 +5688,102 @@
The minimum value is 0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_LOCAL_MEM_TYPE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_LOCAL_MEM_TYPE"></a><a href="#CL_DEVICE_LOCAL_MEM_TYPE"><code>CL_​DEVICE_​LOCAL_​MEM_​TYPE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_local_mem_type</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Type of local memory supported.
- This can be set to CL_LOCAL implying dedicated local memory storage
- such as SRAM , or CL_GLOBAL.</p>
-<p class="tableblock"> For custom devices, CL_NONE can also be returned indicating no local
+ This can be set to <a id="CL_LOCAL"></a><a href="#CL_LOCAL"><code>CL_​LOCAL</code></a> implying dedicated local memory storage
+ such as SRAM , or <a id="CL_GLOBAL"></a><a href="#CL_GLOBAL"><code>CL_​GLOBAL</code></a>.</p>
+<p class="tableblock"> For custom devices, <a href="#CL_NONE"><code>CL_​NONE</code></a> can also be returned indicating no local
memory support.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_LOCAL_MEM_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_LOCAL_MEM_SIZE"></a><a href="#CL_DEVICE_LOCAL_MEM_SIZE"><code>CL_​DEVICE_​LOCAL_​MEM_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_ulong</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Size of local memory region in bytes.
The minimum value is 32 KB for devices that are not of type
- CL_DEVICE_TYPE_CUSTOM.</p></td>
+ <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_ERROR_CORRECTION_SUPPORT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ERROR_CORRECTION_SUPPORT"></a><a href="#CL_DEVICE_ERROR_CORRECTION_SUPPORT"><code>CL_​DEVICE_​ERROR_​CORRECTION_​SUPPORT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_TRUE if the device implements error correction for all
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if the device implements error correction for all
accesses to compute device memory (global and constant).
- Is CL_FALSE if the device does not implement such error correction.</p></td>
+ Is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> if the device does not implement such error correction.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PROFILING_TIMER_RESOLUTION</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PROFILING_TIMER_RESOLUTION"></a><a href="#CL_DEVICE_PROFILING_TIMER_RESOLUTION"><code>CL_​DEVICE_​PROFILING_​TIMER_​RESOLUTION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Describes the resolution of device timer.
This is measured in nanoseconds.
Refer to <a href="#profiling-operations">Profiling Operations</a> for details.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_ENDIAN_LITTLE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_ENDIAN_LITTLE"></a><a href="#CL_DEVICE_ENDIAN_LITTLE"><code>CL_​DEVICE_​ENDIAN_​LITTLE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_TRUE if the OpenCL device is a little endian device and
- CL_FALSE otherwise</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if the OpenCL device is a little endian device and
+ <a href="#CL_FALSE"><code>CL_​FALSE</code></a> otherwise</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_AVAILABLE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_AVAILABLE"></a><a href="#CL_DEVICE_AVAILABLE"><code>CL_​DEVICE_​AVAILABLE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_TRUE if the device is available and CL_FALSE otherwise.
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if the device is available and <a href="#CL_FALSE"><code>CL_​FALSE</code></a> otherwise.
A device is considered to be available if the device can be expected
to successfully execute commands enqueued to the device.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_COMPILER_AVAILABLE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_COMPILER_AVAILABLE"></a><a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_​DEVICE_​COMPILER_​AVAILABLE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_FALSE if the implementation does not have a compiler available
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> if the implementation does not have a compiler available
to compile the program source.</p>
-<p class="tableblock"> Is CL_TRUE if the compiler is available.
- This can be CL_FALSE for the embedded platform profile only.</p></td>
+<p class="tableblock"> Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if the compiler is available.
+ This can be <a href="#CL_FALSE"><code>CL_​FALSE</code></a> for the embedded platform profile only.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_LINKER_AVAILABLE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_LINKER_AVAILABLE"></a><a href="#CL_DEVICE_LINKER_AVAILABLE"><code>CL_​DEVICE_​LINKER_​AVAILABLE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_FALSE if the implementation does not have a linker available.
- Is CL_TRUE if the linker is available.</p>
-<p class="tableblock"> This can be CL_FALSE for the embedded platform profile only.</p>
-<p class="tableblock"> This must be CL_TRUE if CL_DEVICE_COMPILER_AVAILABLE is CL_TRUE.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> if the implementation does not have a linker available.
+ Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if the linker is available.</p>
+<p class="tableblock"> This can be <a href="#CL_FALSE"><code>CL_​FALSE</code></a> for the embedded platform profile only.</p>
+<p class="tableblock"> This must be <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if <a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_​DEVICE_​COMPILER_​AVAILABLE</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_EXECUTION_CAPABILITIES</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_exec_ capabilities</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_EXECUTION_CAPABILITIES"></a><a href="#CL_DEVICE_EXECUTION_CAPABILITIES"><code>CL_​DEVICE_​EXECUTION_​CAPABILITIES</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_exec_capabilities</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Describes the execution capabilities of the device.
This is a bit-field that describes one or more of the following
values:</p>
-<p class="tableblock"> CL_EXEC_KERNEL - The OpenCL device can execute OpenCL kernels.</p>
-<p class="tableblock"> CL_EXEC_NATIVE_KERNEL - The OpenCL device can execute native
+<p class="tableblock"> <a id="CL_EXEC_KERNEL"></a><a href="#CL_EXEC_KERNEL"><code>CL_​EXEC_​KERNEL</code></a> - The OpenCL device can execute OpenCL kernels.</p>
+<p class="tableblock"> <a id="CL_EXEC_NATIVE_KERNEL"></a><a href="#CL_EXEC_NATIVE_KERNEL"><code>CL_​EXEC_​NATIVE_​KERNEL</code></a> - The OpenCL device can execute native
kernels.</p>
-<p class="tableblock"> The mandated minimum capability is: CL_EXEC_KERNEL.</p></td>
+<p class="tableblock"> The mandated minimum capability is: <a href="#CL_EXEC_KERNEL"><code>CL_​EXEC_​KERNEL</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_QUEUE_ON_HOST_PROPERTIES<sup>8</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_HOST_PROPERTIES"></a><a href="#CL_DEVICE_QUEUE_ON_HOST_PROPERTIES"><code>CL_​DEVICE_​QUEUE_​ON_​HOST_​PROPERTIES</code></a><sup>8</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_command_queue_properties</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Describes the on host command-queue properties supported by the
device.
This is a bit-field that describes one or more of the following
values:</p>
-<p class="tableblock"> CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE<br>
- CL_QUEUE_PROFILING_ENABLE</p>
+<p class="tableblock"> <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_​QUEUE_​OUT_​OF_​ORDER_​EXEC_​MODE_​ENABLE</code></a><br>
+ <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_​QUEUE_​PROFILING_​ENABLE</code></a></p>
<p class="tableblock"> These properties are described in the <a href="#queue-properties-table">Queue Properties</a> table.</p>
-<p class="tableblock"> The mandated minimum capability is: CL_QUEUE_PROFILING_ENABLE.</p></td>
+<p class="tableblock"> The mandated minimum capability is: <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_​QUEUE_​PROFILING_​ENABLE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_QUEUE_ON_DEVICE_PROPERTIES</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_DEVICE_PROPERTIES"></a><a href="#CL_DEVICE_QUEUE_ON_DEVICE_PROPERTIES"><code>CL_​DEVICE_​QUEUE_​ON_​DEVICE_​PROPERTIES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_command_queue_properties</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Describes the on device command-queue properties supported by the
device.
This is a bit-field that describes one or more of the following
values:</p>
-<p class="tableblock"> CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE<br>
- CL_QUEUE_PROFILING_ENABLE</p>
+<p class="tableblock"> <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_​QUEUE_​OUT_​OF_​ORDER_​EXEC_​MODE_​ENABLE</code></a><br>
+ <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_​QUEUE_​PROFILING_​ENABLE</code></a></p>
<p class="tableblock"> These properties are described in the <a href="#queue-properties-table">Queue Properties</a> table.</p>
<p class="tableblock"> The mandated minimum capability is:
- CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE | CL_QUEUE_PROFILING_ENABLE.</p></td>
+ <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_​QUEUE_​OUT_​OF_​ORDER_​EXEC_​MODE_​ENABLE</code></a> | <a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_​QUEUE_​PROFILING_​ENABLE</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"></a><a href="#CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"><code>CL_​DEVICE_​QUEUE_​ON_​DEVICE_​PREFERRED_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The size of the device queue in bytes preferred by the
implementation.
@@ -5911,21 +5792,21 @@
<p class="tableblock"> The minimum value is 16 KB</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"></a><a href="#CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"><code>CL_​DEVICE_​QUEUE_​ON_​DEVICE_​MAX_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The max. size of the device queue in bytes.
The minimum value is 256 KB for the full profile and 64 KB for the
embedded profile</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_ON_DEVICE_QUEUES</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_ON_DEVICE_QUEUES"></a><a href="#CL_DEVICE_MAX_ON_DEVICE_QUEUES"><code>CL_​DEVICE_​MAX_​ON_​DEVICE_​QUEUES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of device queues that can be created for this
device in a single context.</p>
<p class="tableblock"> The minimum value is 1.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_ON_DEVICE_EVENTS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_ON_DEVICE_EVENTS"></a><a href="#CL_DEVICE_MAX_ON_DEVICE_EVENTS"><code>CL_​DEVICE_​MAX_​ON_​DEVICE_​EVENTS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of events in use by a device queue.
These refer to events returned by the <code>enqueue_</code> built-in functions
@@ -5934,7 +5815,7 @@
<p class="tableblock"> The minimum value is 1024.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_BUILT_IN_KERNELS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_BUILT_IN_KERNELS"></a><a href="#CL_DEVICE_BUILT_IN_KERNELS"><code>CL_​DEVICE_​BUILT_​IN_​KERNELS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A semi-colon separated list of built-in kernels supported by the
device.
@@ -5942,28 +5823,28 @@
the device.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PLATFORM</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PLATFORM"></a><a href="#CL_DEVICE_PLATFORM"><code>CL_​DEVICE_​PLATFORM</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_platform_id</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The platform associated with this device.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_NAME</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_NAME"></a><a href="#CL_DEVICE_NAME"><code>CL_​DEVICE_​NAME</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Device name string.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_VENDOR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_VENDOR"></a><a href="#CL_DEVICE_VENDOR"><code>CL_​DEVICE_​VENDOR</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Vendor name string.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DRIVER_VERSION</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DRIVER_VERSION"></a><a href="#CL_DRIVER_VERSION"><code>CL_​DRIVER_​VERSION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL software driver version string.
Follows a vendor-specific format.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PROFILE<sup>9</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PROFILE"></a><a href="#CL_DEVICE_PROFILE"><code>CL_​DEVICE_​PROFILE</code></a><sup>9</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL profile string.
Returns the profile name supported by the device.
@@ -5975,35 +5856,36 @@
profile.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_VERSION</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_VERSION"></a><a href="#CL_DEVICE_VERSION"><code>CL_​DEVICE_​VERSION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL version string.
Returns the OpenCL version supported by the device. This version
string has the following format:</p>
<p class="tableblock"> <em>OpenCL<space><major_version.minor_version><space><vendor-specific
information></em></p>
-<p class="tableblock"> The major_version.minor_version value returned will be 2.2.</p></td>
+<p class="tableblock"> The major_version.minor_version value returned will be one of 1.0,
+ 1.1, 1.2, 2.0, 2.1 or 2.2.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_OPENCL_C_VERSION</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_OPENCL_C_VERSION"></a><a href="#CL_DEVICE_OPENCL_C_VERSION"><code>CL_​DEVICE_​OPENCL_​C_​VERSION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">OpenCL C version string.
Returns the highest OpenCL C version supported by the compiler for
- this device that is not of type CL_DEVICE_TYPE_CUSTOM.
+ this device that is not of type <a href="#CL_DEVICE_TYPE_CUSTOM"><code>CL_​DEVICE_​TYPE_​CUSTOM</code></a>.
This version string has the following format:</p>
<p class="tableblock"> <em>OpenCL<space>C<space><major_version.minor_version><space><vendor-specific
information></em></p>
<p class="tableblock"> The major_version.minor_version value returned must be 2.0 if
- CL_DEVICE_VERSION is OpenCL 2.0.</p>
+ <a href="#CL_DEVICE_VERSION"><code>CL_​DEVICE_​VERSION</code></a> is OpenCL 2.0, OpenCL 2.1, or OpenCL 2.2.</p>
<p class="tableblock"> The major_version.minor_version value returned must be 1.2 if
- CL_DEVICE_VERSION is OpenCL 1.2.</p>
+ <a href="#CL_DEVICE_VERSION"><code>CL_​DEVICE_​VERSION</code></a> is OpenCL 1.2.</p>
<p class="tableblock"> The major_version.minor_version value returned must be 1.1 if
- CL_DEVICE_VERSION is OpenCL 1.1.</p>
+ <a href="#CL_DEVICE_VERSION"><code>CL_​DEVICE_​VERSION</code></a> is OpenCL 1.1.</p>
<p class="tableblock"> The major_version.minor_version value returned can be 1.0 or 1.1 if
- CL_DEVICE_VERSION is OpenCL 1.0.</p></td>
+ <a href="#CL_DEVICE_VERSION"><code>CL_​DEVICE_​VERSION</code></a> is OpenCL 1.0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_EXTENSIONS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_EXTENSIONS"></a><a href="#CL_DEVICE_EXTENSIONS"><code>CL_​DEVICE_​EXTENSIONS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">char[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a space separated list of extension names (the extension
names themselves do not contain any spaces) supported by the device.
@@ -6032,84 +5914,84 @@
<strong>cl_khr_3d_image_writes</strong><br>
<strong>cl_khr_image2d_from_buffer</strong><br>
<strong>cl_khr_depth_images</strong></p>
-<p class="tableblock"> Please refer to the OpenCL 2.0 Extension Specification for a
+<p class="tableblock"> Please refer to the OpenCL Extension Specification for a
detailed description of these extensions.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PRINTF_BUFFER_SIZE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PRINTF_BUFFER_SIZE"></a><a href="#CL_DEVICE_PRINTF_BUFFER_SIZE"><code>CL_​DEVICE_​PRINTF_​BUFFER_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum size in bytes of the internal buffer that holds the output
of printf calls from a kernel.
The minimum value for the FULL profile is 1 MB.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PREFERRED_INTEROP_USER_SYNC</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_INTEROP_USER_SYNC"></a><a href="#CL_DEVICE_PREFERRED_INTEROP_USER_SYNC"><code>CL_​DEVICE_​PREFERRED_​INTEROP_​USER_​SYNC</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_TRUE if the devices preference is for the user to be
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if the devices preference is for the user to be
responsible for synchronization, when sharing memory objects between
- OpenCL and other APIs such as DirectX, CL_FALSE if the device /
+ OpenCL and other APIs such as DirectX, <a href="#CL_FALSE"><code>CL_​FALSE</code></a> if the device /
implementation has a performant path for performing synchronization
of memory object shared between OpenCL and other APIs such as
DirectX.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PARENT_DEVICE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARENT_DEVICE"></a><a href="#CL_DEVICE_PARENT_DEVICE"><code>CL_​DEVICE_​PARENT_​DEVICE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_id</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the cl_device_id of the parent device to which this
sub-device belongs.
If <em>device</em> is a root-level device, a <code>NULL</code> value is returned.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PARTITION_MAX_SUB_DEVICES</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_MAX_SUB_DEVICES"></a><a href="#CL_DEVICE_PARTITION_MAX_SUB_DEVICES"><code>CL_​DEVICE_​PARTITION_​MAX_​SUB_​DEVICES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the maximum number of sub-devices that can be created when a
device is partitioned.</p>
-<p class="tableblock"> The value returned cannot exceed CL_DEVICE_MAX_COMPUTE_UNITS.</p></td>
+<p class="tableblock"> The value returned cannot exceed <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_​DEVICE_​MAX_​COMPUTE_​UNITS</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PARTITION_PROPERTIES</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_PROPERTIES"></a><a href="#CL_DEVICE_PARTITION_PROPERTIES"><code>CL_​DEVICE_​PARTITION_​PROPERTIES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_partition_ property[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the list of partition types supported by <em>device</em>.
This is an array of cl_device_partition_property values drawn from
the following list:</p>
-<p class="tableblock"> CL_DEVICE_PARTITION_EQUALLY<br>
- CL_DEVICE_PARTITION_BY_COUNTS<br>
- CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN</p>
+<p class="tableblock"> <a href="#CL_DEVICE_PARTITION_EQUALLY"><code>CL_​DEVICE_​PARTITION_​EQUALLY</code></a><br>
+ <a href="#CL_DEVICE_PARTITION_BY_COUNTS"><code>CL_​DEVICE_​PARTITION_​BY_​COUNTS</code></a><br>
+ <a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_​DEVICE_​PARTITION_​BY_​AFFINITY_​DOMAIN</code></a></p>
<p class="tableblock"> If the device cannot be partitioned (i.e. there is no partitioning
scheme supported by the device that will return at least two
subdevices), a value of 0 will be returned.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PARTITION_AFFINITY_DOMAIN</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_AFFINITY_DOMAIN"></a><a href="#CL_DEVICE_PARTITION_AFFINITY_DOMAIN"><code>CL_​DEVICE_​PARTITION_​AFFINITY_​DOMAIN</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_affinity_ domain</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the list of supported affinity domains for partitioning the
- device using CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
+ device using <a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_​DEVICE_​PARTITION_​BY_​AFFINITY_​DOMAIN</code></a>.
This is a bit-field that describes one or more of the following
values:</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_NUMA<br>
- CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE<br>
- CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE<br>
- CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE<br>
- CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE<br>
- CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE</p>
+<p class="tableblock"> <a id="CL_DEVICE_AFFINITY_DOMAIN_NUMA"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_NUMA"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​NUMA</code></a><br>
+ <a id="CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L4_​CACHE</code></a><br>
+ <a id="CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L3_​CACHE</code></a><br>
+ <a id="CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L2_​CACHE</code></a><br>
+ <a id="CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L1_​CACHE</code></a><br>
+ <a id="CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"></a><a href="#CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​NEXT_​PARTITIONABLE</code></a></p>
<p class="tableblock"> If the device does not support any affinity domains, a value of 0
will be returned.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PARTITION_TYPE</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_partition_ property[]</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the properties argument specified in <strong>clCreateSubDevices</strong> if
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_TYPE"></a><a href="#CL_DEVICE_PARTITION_TYPE"><code>CL_​DEVICE_​PARTITION_​TYPE</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_partition_property[]</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the properties argument specified in <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> if
device is a sub-device.
- In the case where the properties argument to <strong>clCreateSubDevices</strong> is
- CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN,
- CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE, the affinity domain
+ In the case where the properties argument to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> is
+ <a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_​DEVICE_​PARTITION_​BY_​AFFINITY_​DOMAIN</code></a>,
+ <a href="#CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​NEXT_​PARTITIONABLE</code></a>, the affinity domain
used to perform the partition will be returned.
This can be one of the following values:</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_NUMA<br>
- CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE<br>
- CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE<br>
- CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE<br>
- CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE</p>
+<p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_NUMA"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​NUMA</code></a><br>
+ <a href="#CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L4_​CACHE</code></a><br>
+ <a href="#CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L3_​CACHE</code></a><br>
+ <a href="#CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L2_​CACHE</code></a><br>
+ <a href="#CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L1_​CACHE</code></a></p>
<p class="tableblock"> Otherwise the implementation may either return a
<em>param_value_size_ret</em> of 0 i.e. there is no partition type
associated with device or can return a property value of 0 (where 0
@@ -6117,41 +5999,41 @@
<em>param_value</em> points to.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_REFERENCE_COUNT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_REFERENCE_COUNT"></a><a href="#CL_DEVICE_REFERENCE_COUNT"><code>CL_​DEVICE_​REFERENCE_​COUNT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the <em>device</em> reference count.
If the device is a root-level device, a reference count of one is
returned.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_SVM_CAPABILITIES</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_svm_ capabilities</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_SVM_CAPABILITIES"></a><a href="#CL_DEVICE_SVM_CAPABILITIES"><code>CL_​DEVICE_​SVM_​CAPABILITIES</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_svm_capabilities</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Describes the various shared virtual memory (a.k.a. SVM) memory
allocation types the device supports.
Coarse-grain SVM allocations are required to be supported by all
OpenCL 2.0 devices.
This is a bit-field that describes a combination of the following
values:</p>
-<p class="tableblock"> CL_DEVICE_SVM_COARSE_GRAIN_BUFFER - Support for coarse-grain buffer
- sharing using <strong>clSVMAlloc</strong>.
+<p class="tableblock"> <a id="CL_DEVICE_SVM_COARSE_GRAIN_BUFFER"></a><a href="#CL_DEVICE_SVM_COARSE_GRAIN_BUFFER"><code>CL_​DEVICE_​SVM_​COARSE_​GRAIN_​BUFFER</code></a> - Support for coarse-grain buffer
+ sharing using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>.
Memory consistency is guaranteed at synchronization points and the
- host must use calls to <strong>clEnqueueMapBuffer</strong> and
- <strong>clEnqueueUnmapMemObject</strong>.</p>
-<p class="tableblock"> CL_DEVICE_SVM_FINE_GRAIN_BUFFER - Support for fine-grain buffer
- sharing using <strong>clSVMAlloc</strong>.
+ host must use calls to <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and
+ <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>.</p>
+<p class="tableblock"> <a id="CL_DEVICE_SVM_FINE_GRAIN_BUFFER"></a><a href="#CL_DEVICE_SVM_FINE_GRAIN_BUFFER"><code>CL_​DEVICE_​SVM_​FINE_​GRAIN_​BUFFER</code></a> - Support for fine-grain buffer
+ sharing using <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a>.
Memory consistency is guaranteed at synchronization points without
- need for <strong>clEnqueueMapBuffer</strong> and <strong>clEnqueueUnmapMemObject</strong>.</p>
-<p class="tableblock"> CL_DEVICE_SVM_FINE_GRAIN_SYSTEM - Support for sharing the host’s
+ need for <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> and <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>.</p>
+<p class="tableblock"> <a id="CL_DEVICE_SVM_FINE_GRAIN_SYSTEM"></a><a href="#CL_DEVICE_SVM_FINE_GRAIN_SYSTEM"><code>CL_​DEVICE_​SVM_​FINE_​GRAIN_​SYSTEM</code></a> - Support for sharing the host’s
entire virtual memory including memory allocated using <strong>malloc</strong>.
Memory consistency is guaranteed at synchronization points.</p>
-<p class="tableblock"> CL_DEVICE_SVM_ATOMICS - Support for the OpenCL 2.0 atomic
+<p class="tableblock"> <a id="CL_DEVICE_SVM_ATOMICS"></a><a href="#CL_DEVICE_SVM_ATOMICS"><code>CL_​DEVICE_​SVM_​ATOMICS</code></a> - Support for the OpenCL 2.0 atomic
operations that provide memory consistency across the host and all
OpenCL devices supporting fine-grain SVM allocations.</p>
<p class="tableblock"> The mandated minimum capability is
- CL_DEVICE_SVM_COARSE_GRAIN_BUFFER.</p></td>
+ <a href="#CL_DEVICE_SVM_COARSE_GRAIN_BUFFER"><code>CL_​DEVICE_​SVM_​COARSE_​GRAIN_​BUFFER</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PREFERRED_PLATFORM_ATOMIC_ALIGNMENT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_PLATFORM_ATOMIC_ALIGNMENT"></a><a href="#CL_DEVICE_PREFERRED_PLATFORM_ATOMIC_ALIGNMENT"><code>CL_​DEVICE_​PREFERRED_​PLATFORM_​ATOMIC_​ALIGNMENT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value representing the preferred alignment in bytes for
OpenCL 2.0 fine-grained SVM atomic types.
@@ -6159,7 +6041,7 @@
is aligned to the natural size of the type.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PREFERRED_GLOBAL_ATOMIC_ALIGNMENT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_GLOBAL_ATOMIC_ALIGNMENT"></a><a href="#CL_DEVICE_PREFERRED_GLOBAL_ATOMIC_ALIGNMENT"><code>CL_​DEVICE_​PREFERRED_​GLOBAL_​ATOMIC_​ALIGNMENT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value representing the preferred alignment in bytes for
OpenCL 2.0 atomic types to global memory.
@@ -6167,7 +6049,7 @@
is aligned to the natural size of the type.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_PREFERRED_LOCAL_ATOMIC_ALIGNMENT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PREFERRED_LOCAL_ATOMIC_ALIGNMENT"></a><a href="#CL_DEVICE_PREFERRED_LOCAL_ATOMIC_ALIGNMENT"><code>CL_​DEVICE_​PREFERRED_​LOCAL_​ATOMIC_​ALIGNMENT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value representing the preferred alignment in bytes for
OpenCL 2.0 atomic types to local memory.
@@ -6175,21 +6057,21 @@
is aligned to the natural size of the type.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_MAX_NUM_SUB_GROUPS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_MAX_NUM_SUB_GROUPS"></a><a href="#CL_DEVICE_MAX_NUM_SUB_GROUPS"><code>CL_​DEVICE_​MAX_​NUM_​SUB_​GROUPS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of sub-groups in a work-group that a device is
capable of executing on a single compute unit, for any given
kernel-instance running on the device.
The minimum value is 1.
- (Refer also to <strong>clGetKernelSubGroupInfo</strong>.)</p></td>
+ (Refer also to <a href="#clGetKernelSubGroupInfo"><strong>clGetKernelSubGroupInfo</strong></a>.)</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS"></a><a href="#CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS"><code>CL_​DEVICE_​SUB_​GROUP_​INDEPENDENT_​FORWARD_​PROGRESS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Is CL_TRUE if this device supports independent forward progress of
- sub-groups, CL_FALSE otherwise.
+<td class="tableblock halign-left valign-top"><p class="tableblock">Is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> if this device supports independent forward progress of
+ sub-groups, <a href="#CL_FALSE"><code>CL_​FALSE</code></a> otherwise.
If <strong>cl_khr_subgroups</strong> is supported by the device this must return
- CL_TRUE.</p></td>
+ <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.</p></td>
</tr>
</tbody>
</table>
@@ -6201,15 +6083,15 @@
image qualifier may result in additional read_only images resources being
created internally by an implementation.
The internally created read_only image resources will count against the max
-supported read image arguments given by CL_DEVICE_MAX_READ_IMAGE_ARGS.
+supported read image arguments given by <a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​READ_​IMAGE_​ARGS</code></a>.
Enqueuing a kernel that requires more images than the implementation can
-support will result in a CL_OUT_OF_RESOURCES error being returned.</p>
+support will result in a <a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> error being returned.</p>
</dd>
<dt class="hdlist1">5</dt>
<dd>
-<p>NOTE: <strong>CL_DEVICE_MAX_WRITE_IMAGE_ARGS</strong> is only there for backward
+<p>NOTE: <a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​WRITE_​IMAGE_​ARGS</code></a> is only there for backward
compatibility.
-<strong>CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS</strong> should be used instead.</p>
+<a href="#CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​READ_​WRITE_​IMAGE_​ARGS</code></a> should be used instead.</p>
</dd>
<dt class="hdlist1">6</dt>
<dd>
@@ -6227,8 +6109,8 @@
</dd>
<dt class="hdlist1">8</dt>
<dd>
-<p>CL_DEVICE_QUEUE_PROPERTIES is deprecated and replaced by
-CL_DEVICE_QUEUE_ON_HOST_PROPERTIES.</p>
+<p><a href="#CL_DEVICE_QUEUE_PROPERTIES"><code>CL_​DEVICE_​QUEUE_​PROPERTIES</code></a> is deprecated and replaced by
+<a href="#CL_DEVICE_QUEUE_ON_HOST_PROPERTIES"><code>CL_​DEVICE_​QUEUE_​ON_​HOST_​PROPERTIES</code></a>.</p>
</dd>
<dt class="hdlist1">9</dt>
<dd>
@@ -6238,49 +6120,24 @@
will support devices that are FULL_PROFILE and may also support devices
that are EMBEDDED_PROFILE.
The compiler must be available for all devices i.e.
-CL_DEVICE_COMPILER_AVAILABLE is CL_TRUE.
+<a href="#CL_DEVICE_COMPILER_AVAILABLE"><code>CL_​DEVICE_​COMPILER_​AVAILABLE</code></a> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>.
If the platform profile returned is EMBEDDED_PROFILE, then devices that
are only EMBEDDED_PROFILE are supported.</p>
</dd>
</dl>
</div>
<div class="paragraph">
-<p>The device queries described in the <a href="#device-queries-table">Device Queries</a>
-table should return the same information for a root-level device i.e. a
-device returned by <strong>clGetDeviceIDs</strong> and any sub-devices created from this
-device except for the following queries:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>CL_DEVICE_GLOBAL_MEM_CACHE_SIZE</p>
-</li>
-<li>
-<p>CL_DEVICE_BUILT_IN_KERNELS</p>
-</li>
-<li>
-<p>CL_DEVICE_PARENT_DEVICE</p>
-</li>
-<li>
-<p>CL_DEVICE_PARTITION_TYPE</p>
-</li>
-<li>
-<p>CL_DEVICE_REFERENCE_COUNT</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p><strong>clGetDeviceInfo</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_DEVICE if <em>device</em> is not valid.</p>
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>device</em> is not valid.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>param_name</em> is not one of the supported values or
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>param_name</em> is not one of the supported values or
if size in bytes specified by <em>param_value_size</em> is < size of return
type as specified in the <a href="#device-queries-table">Device Queries</a> table
and <em>param_value</em> is not a <code>NULL</code> value or if <em>param_name</em> is a value
@@ -6288,163 +6145,179 @@
supported by the device.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetDeviceAndHostTimer(cl_device_id device,
- cl_ulong* device_timestamp,
- cl_ulong* host_timestamp)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>Returns a reasonably synchronized pair of timestamps from the device timer
-and the host timer as seen by <em>device</em>.
-Implementations may need to execute this query with a high latency in order
-to provide reasonable synchronization of the timestamps.
-The host timestamp and device timestamp returned by this function and
-<strong>clGetHostTimer</strong> each have an implementation defined timebase.
-The timestamps will always be in their respective timebases regardless of
-which query function is used.
-The timestamp returned from <strong>clGetEventProfilingInfo</strong> for an event on a
-device and a device timestamp queried from the same device will always be in
-the same timebase.</p>
+<p>To query device and host timestamps, call the function:</p>
</div>
-<div class="paragraph">
-<p><em>device</em> is a device returned by <strong>clGetDeviceIDs</strong>.</p>
+<div id="clGetDeviceAndHostTimer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetDeviceAndHostTimer(
+ cl_device_id device,
+ cl_ulong* device_timestamp,
+ cl_ulong* host_timestamp);</code></pre>
</div>
-<div class="paragraph">
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>device</em> is a device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>.</p>
+</li>
+<li>
<p><em>device_timestamp</em> will be updated with the value of the device timer in
nanoseconds.
The resolution of the timer is the same as the device profiling timer
-returned by <strong>clGetDeviceInfo</strong> and the CL_DEVICE_PROFILING_TIMER_RESOLUTION
+returned by <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a> and the <a href="#CL_DEVICE_PROFILING_TIMER_RESOLUTION"><code>CL_​DEVICE_​PROFILING_​TIMER_​RESOLUTION</code></a>
query.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>host_timestamp</em> will be updated with the value of the host timer in
nanoseconds at the closest possible point in time to that at which
<em>device_timer</em> was returned.
-The resolution of the timer may be queried via <strong>clGetPlatformInfo</strong> and the
-flag CL_PLATFORM_HOST_TIMER_RESOLUTION.</p>
-</div>
-<div class="paragraph">
-<p><strong>clGetDeviceAndHostTimer</strong> will return CL_SUCCESS with a time value in
-<em>host_timestamp</em> if provided.
-Otherwise, it returns one of the following errors:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>CL_INVALID_DEVICE if <em>device</em> is not a valid OpenCL device.</p>
-</li>
-<li>
-<p>CL_INVALID_VALUE if <em>host_timestamp</em> or <em>device_timestamp</em> is <code>NULL</code>.</p>
-</li>
-<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
-by the OpenCL implementation on the device.</p>
-</li>
-<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
-required by the OpenCL implementation on the host.</p>
+The resolution of the timer may be queried via <a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> and the
+flag <a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_​PLATFORM_​HOST_​TIMER_​RESOLUTION</code></a>.</p>
</li>
</ul>
</div>
<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetHostTimer(cl_device_id device,
- cl_ulong* host_timestamp)</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Return the current value of the host clock as seen by <em>device</em>.
-This value is in the same timebase as the host_timestamp returned from
-<strong>clGetDeviceAndHostTimer</strong>.
-The implementation will return with as low a latency as possible to allow a
-correlation with a subsequent application sampled time.
+<p><a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> returns a reasonably synchronized pair of
+timestamps from the device timer and the host timer as seen by <em>device</em>.
+Implementations may need to execute this query with a high latency in order
+to provide reasonable synchronization of the timestamps.
The host timestamp and device timestamp returned by this function and
-<strong>clGetDeviceAndHostTimer</strong> each have an implementation defined timebase.
+<a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> each have an implementation defined timebase.
The timestamps will always be in their respective timebases regardless of
which query function is used.
-The timestamp returned from <strong>clGetEventProfilingInfo</strong> for an event on a
+The timestamp returned from <a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a> for an event on a
device and a device timestamp queried from the same device will always be in
the same timebase.</p>
</div>
<div class="paragraph">
-<p><em>device</em> is a device returned by <strong>clGetDeviceIDs</strong>.</p>
-</div>
-<div class="paragraph">
-<p><em>host_timestamp</em> will be updated with the value of the current timer in
-nanoseconds.
-The resolution of the timer may be queried via <strong>clGetPlatformInfo</strong> and the
-flag CL_PLATFORM_HOST_TIMER_RESOLUTION.</p>
-</div>
-<div class="paragraph">
-<p><strong>clGetHostTimer</strong> will return CL_SUCCESS with a time value in
+<p><a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> will return <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> with a time value in
<em>host_timestamp</em> if provided.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_DEVICE if <em>device</em> is not a valid OpenCL device.</p>
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>device</em> is not a valid OpenCL device.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>host_timestamp</em> is <code>NULL</code>.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>host_timestamp</em> or <em>device_timestamp</em> is <code>NULL</code>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
</div>
+</div>
+<div class="openblock">
+<div class="content">
+<div class="paragraph">
+<p>To query the host clock, call the function:</p>
+</div>
+<div id="clGetHostTimer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetHostTimer(
+ cl_device_id device,
+ cl_ulong* host_timestamp);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>device</em> is a device returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>.</p>
+</li>
+<li>
+<p><em>host_timestamp</em> will be updated with the value of the current timer in
+nanoseconds.
+The resolution of the timer may be queried via <a href="#clGetPlatformInfo"><strong>clGetPlatformInfo</strong></a> and the
+flag <a href="#CL_PLATFORM_HOST_TIMER_RESOLUTION"><code>CL_​PLATFORM_​HOST_​TIMER_​RESOLUTION</code></a>.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p><a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> returns the current value of the host clock as seen by
+<em>device</em>.
+This value is in the same timebase as the <em>host_timestamp</em> returned from
+<a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a>.
+The implementation will return with as low a latency as possible to allow a
+correlation with a subsequent application sampled time.
+The host timestamp and device timestamp returned by this function and
+<a href="#clGetDeviceAndHostTimer"><strong>clGetDeviceAndHostTimer</strong></a> each have an implementation defined timebase.
+The timestamps will always be in their respective timebases regardless of
+which query function is used.
+The timestamp returned from <a href="#clGetEventProfilingInfo"><strong>clGetEventProfilingInfo</strong></a> for an event on a
+device and a device timestamp queried from the same device will always be in
+the same timebase.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clGetHostTimer"><strong>clGetHostTimer</strong></a> will return <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> with a time value in
+<em>host_timestamp</em> if provided.
+Otherwise, it returns one of the following errors:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>device</em> is not a valid OpenCL device.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>host_timestamp</em> is <code>NULL</code>.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
+by the OpenCL implementation on the device.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
+required by the OpenCL implementation on the host.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
<div class="sect2">
<h3 id="_partitioning_a_device">4.3. Partitioning a Device</h3>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clCreateSubDevices(cl_device_id in_device,
- <span class="directive">const</span> cl_device_partition_property *properties,
- cl_uint num_devices,
- cl_device_id *out_devices,
- cl_uint *num_devices_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>creates an array of sub-devices that each reference a non-intersecting set
-of compute units within in_device, according to a partition scheme given by
-<em>properties</em>.
-The output sub-devices may be used in every way that the root (or parent)
-device can be used, including creating contexts, building programs, further
-calls to <strong>clCreateSubDevices</strong> and creating command-queues.
-When a command-queue is created against a sub-device, the commands enqueued
-on the queue are executed only on the sub-device.</p>
+<p>To create sub-devices partitioning an OpenCL device, call the function:</p>
</div>
-<div class="paragraph">
+<div id="clCreateSubDevices" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clCreateSubDevices(
+ cl_device_id in_device,
+ <span class="directive">const</span> cl_device_partition_property* properties,
+ cl_uint num_devices,
+ cl_device_id* out_devices,
+ cl_uint* num_devices_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>in_device</em> is the device to be partitioned.</p>
-</div>
-<div class="paragraph">
-<p><em>properties</em> specifies how <em>in_device</em> is to be partition described by a
+</li>
+<li>
+<p><em>properties</em> specifies how <em>in_device</em> is to be partitioned, described by a
partition name and its corresponding value.
Each partition name is immediately followed by the corresponding desired
value.
@@ -6453,9 +6326,38 @@
<a href="#subdevice-partition-table">Subdevice Partition</a> table.
Only one of the listed partitioning schemes can be specified in
<em>properties</em>.</p>
+</li>
+<li>
+<p><em>num_devices</em> is the size of memory pointed to by <em>out_devices</em> specified as
+the number of cl_device_id entries.</p>
+</li>
+<li>
+<p><em>out_devices</em> is the buffer where the OpenCL sub-devices will be returned.
+If <em>out_devices</em> is <code>NULL</code>, this argument is ignored.
+If <em>out_devices</em> is not <code>NULL</code>, <em>num_devices</em> must be greater than or equal
+to the number of sub-devices that <em>device</em> may be partitioned into according
+to the partitioning scheme specified in <em>properties</em>.</p>
+</li>
+<li>
+<p><em>num_devices_ret</em> returns the number of sub-devices that <em>device</em> may be
+partitioned into according to the partitioning scheme specified in
+<em>properties</em>.
+If <em>num_devices_ret</em> is <code>NULL</code>, it is ignored.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p><a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> creates an array of sub-devices that each reference a
+non-intersecting set of compute units within <em>in_device</em>, according to the
+partition scheme given by <em>properties</em>.
+The output sub-devices may be used in every way that the root (or parent)
+device can be used, including creating contexts, building programs, further
+calls to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> and creating command-queues.
+When a command-queue is created against a sub-device, the commands enqueued
+on the queue are executed only on the sub-device.</p>
</div>
<table id="subdevice-partition-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 6. <em>List of supported partition schemes by</em> <strong>clCreateSubDevices</strong></caption>
+<caption class="title">Table 6. List of supported partition schemes by <a href="#clCreateSubDevices">clCreateSubDevices</a></caption>
<colgroup>
<col style="width: 30%;">
<col style="width: 20%;">
@@ -6470,80 +6372,61 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_PARTITION_EQUALLY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_EQUALLY"></a><a href="#CL_DEVICE_PARTITION_EQUALLY"><code>CL_​DEVICE_​PARTITION_​EQUALLY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Split the aggregate device into as many smaller aggregate devices as
can be created, each containing <em>n</em> compute units.
The value <em>n</em> is passed as the value accompanying this property.
If <em>n</em> does not divide evenly into
- CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS, then the remaining compute
+ <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_​DEVICE_​MAX_​COMPUTE_​UNITS</code></a>, then the remaining compute
units are not used.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_PARTITION_BY_COUNTS</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_BY_COUNTS"></a><a href="#CL_DEVICE_PARTITION_BY_COUNTS"><code>CL_​DEVICE_​PARTITION_​BY_​COUNTS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">This property is followed by a
- CL_DEVICE_PARTITION_BY_COUNTS_LIST_END terminated list of compute
- unit counts.
+<td class="tableblock halign-left valign-top"><p class="tableblock">This property is followed by a list of compute unit counts
+ terminated with 0 or <a id="CL_DEVICE_PARTITION_BY_COUNTS_LIST_END"></a><a href="#CL_DEVICE_PARTITION_BY_COUNTS_LIST_END"><code>CL_​DEVICE_​PARTITION_​BY_​COUNTS_​LIST_​END</code></a>.
For each non-zero count <em>m</em> in the list, a sub-device is created
- with <em>m</em> compute units in it.
- CL_DEVICE_PARTITION_BY_COUNTS_LIST_END is defined to be 0.</p>
+ with <em>m</em> compute units in it.</p>
<p class="tableblock"> The number of non-zero count entries in the list may not exceed
- CL_DEVICE_PARTITION_MAX_SUB_DEVICES.</p>
+ <a href="#CL_DEVICE_PARTITION_MAX_SUB_DEVICES"><code>CL_​DEVICE_​PARTITION_​MAX_​SUB_​DEVICES</code></a>.</p>
<p class="tableblock"> The total number of compute units specified may not exceed
- CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS.</p></td>
+ <a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_​DEVICE_​MAX_​COMPUTE_​UNITS</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"></a><a href="#CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN"><code>CL_​DEVICE_​PARTITION_​BY_​AFFINITY_​DOMAIN</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_affinity_ domain</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Split the device into smaller aggregate devices containing one or
more compute units that all share part of a cache hierarchy.
The value accompanying this property may be drawn from the following
list:</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_NUMA - Split the device into sub-devices
+<p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_NUMA"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​NUMA</code></a> - Split the device into sub-devices
comprised of compute units that share a NUMA node.</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE - Split the device into
+<p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L4_​CACHE</code></a> - Split the device into
sub-devices comprised of compute units that share a level 4 data
cache.</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE - Split the device into
+<p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L3_​CACHE</code></a> - Split the device into
sub-devices comprised of compute units that share a level 3 data
cache.</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE - Split the device into
+<p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L2_​CACHE</code></a> - Split the device into
sub-devices comprised of compute units that share a level 2 data
cache.</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE - Split the device into
+<p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​L1_​CACHE</code></a> - Split the device into
sub-devices comprised of compute units that share a level 1 data
cache.</p>
-<p class="tableblock"> CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE - Split the device
+<p class="tableblock"> <a href="#CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE"><code>CL_​DEVICE_​AFFINITY_​DOMAIN_​NEXT_​PARTITIONABLE</code></a> - Split the device
along the next partitionable affinity domain.
The implementation shall find the first level along which the device
or sub-device may be further subdivided in the order NUMA, L4, L3,
L2, L1, and partition the device into sub-devices comprised of
compute units that share memory subsystems at this level.</p>
<p class="tableblock"> The user may determine what happened by calling
- <strong>clGetDeviceInfo</strong>(CL_DEVICE_PARTITION_TYPE) on the sub-devices.</p></td>
+ <a href="#clGetDeviceInfo"><strong>clGetDeviceInfo</strong></a>(<a href="#CL_DEVICE_PARTITION_TYPE"><code>CL_​DEVICE_​PARTITION_​TYPE</code></a>) on the sub-devices.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
-<p><em>num_devices</em> is the size of memory pointed to by <em>out_devices</em> specified as
-the number of cl_device_id entries.</p>
-</div>
-<div class="paragraph">
-<p><em>out_devices</em> is the buffer where the OpenCL sub-devices will be returned.
-If <em>out_devices</em> is <code>NULL</code>, this argument is ignored.
-If <em>out_devices</em> is not <code>NULL</code>, <em>num_devices</em> must be greater than or equal
-to the number of sub-devices that <em>device</em> may be partitioned into according
-to the partitioning scheme specified in <em>properties</em>.</p>
-</div>
-<div class="paragraph">
-<p><em>num_devices_ret</em> returns the number of sub-devices that <em>device</em> may be
-partitioned into according to the partitioning scheme specified in
-<em>properties</em>.
-If <em>num_devices_ret</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
-<p><strong>clCreateSubDevices</strong> returns CL_SUCCESS if the partition is created
+<p><a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the partition is created
successfully.
Otherwise, it returns a <code>NULL</code> value with the following error values
returned in <em>errcode_ret</em>:</p>
@@ -6551,44 +6434,44 @@
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_DEVICE if <em>in_device</em> is not valid.</p>
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>in_device</em> is not valid.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values specified in <em>properties</em> are not valid or if
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values specified in <em>properties</em> are not valid or if
values specified in <em>properties</em> are valid but not supported by the
device.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>out_devices</em> is not <code>NULL</code> and <em>num_devices</em> is
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>out_devices</em> is not <code>NULL</code> and <em>num_devices</em> is
less than the number of sub-devices created by the partition scheme.</p>
</li>
<li>
-<p>CL_DEVICE_PARTITION_FAILED if the partition name is supported by the
+<p><a href="#CL_DEVICE_PARTITION_FAILED"><code>CL_​DEVICE_​PARTITION_​FAILED</code></a> if the partition name is supported by the
implementation but in_device could not be further partitioned.</p>
</li>
<li>
-<p>CL_INVALID_DEVICE_PARTITION_COUNT if the partition name specified in
-<em>properties</em> is CL_DEVICE_PARTITION_BY_COUNTS and the number of
-sub-devices requested exceeds CL_DEVICE_PARTITION_MAX_SUB_DEVICES or the
+<p><a href="#CL_INVALID_DEVICE_PARTITION_COUNT"><code>CL_​INVALID_​DEVICE_​PARTITION_​COUNT</code></a> if the partition name specified in
+<em>properties</em> is <a href="#CL_DEVICE_PARTITION_BY_COUNTS"><code>CL_​DEVICE_​PARTITION_​BY_​COUNTS</code></a> and the number of
+sub-devices requested exceeds <a href="#CL_DEVICE_PARTITION_MAX_SUB_DEVICES"><code>CL_​DEVICE_​PARTITION_​MAX_​SUB_​DEVICES</code></a> or the
total number of compute units requested exceeds
-CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS for <em>in_device</em>, or the number of
+<a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_​DEVICE_​MAX_​COMPUTE_​UNITS</code></a> for <em>in_device</em>, or the number of
compute units requested for one or more sub-devices is less than zero or
the number of sub-devices requested exceeds
-CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS for <em>in_device</em>.</p>
+<a href="#CL_DEVICE_MAX_COMPUTE_UNITS"><code>CL_​DEVICE_​MAX_​COMPUTE_​UNITS</code></a> for <em>in_device</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A few examples that describe how to specify partition properties in
-<em>properties</em> argument to <strong>clCreateSubDevices</strong> are given below:</p>
+<em>properties</em> argument to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> are given below:</p>
</div>
<div class="paragraph">
<p>To partition a device containing 16 compute units into two sub-devices, each
@@ -6621,68 +6504,96 @@
<span class="integer">0</span> }</code></pre>
</div>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clRetainDevice(cl_device_id device)</code></pre>
+<div class="paragraph">
+<p>To retain a device, call the function:</p>
</div>
+<div id="clRetainDevice" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainDevice(
+ cl_device_id device);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>device</em> is the OpenCL device to retain.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>increments the <em>device</em> reference count if <em>device</em> is a valid sub-device
-created by a call to <strong>clCreateSubDevices</strong>.
+<p><a href="#clRetainDevice"><strong>clRetainDevice</strong></a> increments the <em>device</em> reference count if <em>device</em> is a
+valid sub-device created by a call to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>.
If <em>device</em> is a root level device i.e. a cl_device_id returned by
-<strong>clGetDeviceIDs</strong>, the <em>device</em> reference count remains unchanged.
-<strong>clRetainDevice</strong> returns CL_SUCCESS if the function is executed successfully
+<a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>, the <em>device</em> reference count remains unchanged.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clRetainDevice"><strong>clRetainDevice</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed successfully
or the device is a root-level device.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_DEVICE if <em>device</em> is not a valid sub-device created by a
-call to <strong>clCreateSubDevices</strong>.</p>
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>device</em> is not a valid sub-device created by a
+call to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clReleaseDevice(cl_device_id device)</code></pre>
+<div class="paragraph">
+<p>To release a device, call the function:</p>
</div>
+<div id="clReleaseDevice" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseDevice(
+ cl_device_id device);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>device</em> is the OpenCL device to retain.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>decrements the <em>device</em> reference count if device is a valid sub-device
-created by a call to <strong>clCreateSubDevices</strong>.
+<p><a href="#clReleaseDevice"><strong>clReleaseDevice</strong></a> decrements the <em>device</em> reference count if device is a
+valid sub-device created by a call to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>.
If <em>device</em> is a root level device i.e. a cl_device_id returned by
-<strong>clGetDeviceIDs</strong>, the <em>device</em> reference count remains unchanged.
-<strong>clReleaseDevice</strong> returns CL_SUCCESS if the function is executed
+<a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>, the <em>device</em> reference count remains unchanged.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clReleaseDevice"><strong>clReleaseDevice</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_DEVICE if <em>device</em> is not a valid sub-device created by a
-call to <strong>clCreateSubDevices</strong>.</p>
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>device</em> is not a valid sub-device created by a
+call to <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
@@ -6692,36 +6603,32 @@
to <em>device</em> (such as command-queues) are released, the <em>device</em> object is
deleted.
Using this function to release a reference that was not obtained by creating
-the object or by calling <strong>clRetainDevice</strong> causes undefined behavior.</p>
+the object or by calling <a href="#clRetainDevice"><strong>clRetainDevice</strong></a> causes undefined behavior.</p>
+</div>
+</div>
</div>
</div>
<div class="sect2">
<h3 id="_contexts">4.4. Contexts</h3>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_context clCreateContext(<span class="directive">const</span> cl_context_properties *properties,
- cl_uint num_devices,
- <span class="directive">const</span> cl_device_id *devices,
- <span class="directive">void</span>(CL_CALLBACK *pfn_notify)
- (<span class="directive">const</span> <span class="predefined-type">char</span> *errinfo,
- <span class="directive">const</span> <span class="directive">void</span> *private_info,
- size_t cb,
- <span class="directive">void</span> *user_data),
- <span class="directive">void</span> *user_data,
- cl_int *errcode_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>creates an OpenCL context.
-An OpenCL context is created with one or more devices.
-Contexts are used by the OpenCL runtime for managing objects such as
-command-queues, memory, program and kernel objects and for executing kernels
-on one or more devices specified in the context.</p>
+<p>To create an OpenCL context, call the function:</p>
</div>
-<div class="paragraph">
+<div id="clCreateContext" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_context clCreateContext(
+ <span class="directive">const</span> cl_context_properties* properties,
+ cl_uint num_devices,
+ <span class="directive">const</span> cl_device_id* devices,
+ <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(<span class="directive">const</span> <span class="predefined-type">char</span>*, <span class="directive">const</span> <span class="directive">void</span>*, size_t, <span class="directive">void</span>*),
+ <span class="directive">void</span>* user_data,
+ cl_int* errcode_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>properties</em> specifies a list of context property names and their
corresponding values.
Each property name is immediately followed by the corresponding desired
@@ -6731,48 +6638,14 @@
<a href="#context-properties-table">Context Properties</a> table.
<em>properties</em> can be <code>NULL</code> in which case the platform that is selected is
implementation-defined.</p>
-</div>
-<table id="context-properties-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 7. <em>List of supported properties by</em> <strong>clCreateContext</strong></caption>
-<colgroup>
-<col style="width: 34%;">
-<col style="width: 33%;">
-<col style="width: 33%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top"><strong>cl_context_properties enum</strong></th>
-<th class="tableblock halign-left valign-top">Property value</th>
-<th class="tableblock halign-left valign-top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_CONTEXT_PLATFORM</strong></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">cl_platform_id</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the platform to use.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_CONTEXT_INTEROP_USER_SYNC</strong></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether the user is responsible for synchronization
- between OpenCL and other APIs.
- Please refer to the specific sections in the OpenCL 2.0 extension
- specification that describe sharing with other APIs for restrictions
- on using this flag.</p>
-<p class="tableblock"> If CL_CONTEXT_INTEROP_USER_SYNC is not specified, a default of
- CL_FALSE is assumed.</p></td>
-</tr>
-</tbody>
-</table>
-<div class="paragraph">
+</li>
+<li>
<p><em>num_devices</em> is the number of devices specified in the <em>devices</em> argument.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>devices</em> is a pointer to a list of unique devices<sup>10</sup> returned by
-<strong>clGetDeviceIDs</strong> or sub-devices created by <strong>clCreateSubDevices</strong> for a
+<a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> or sub-devices created by <a href="#clCreateSubDevices"><strong>clCreateSubDevices</strong></a> for a
platform.</p>
-</div>
<div class="dlist">
<dl>
<dt class="hdlist1">10</dt>
@@ -6781,7 +6654,8 @@
</dd>
</dl>
</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>pfn_notify</em> is a callback function that can be registered by the
application.
This callback function will be used by the OpenCL implementation to report
@@ -6791,7 +6665,21 @@
implementation.
It is the applications responsibility to ensure that the callback function
is thread-safe.
-The parameters to this callback function are:</p>
+If <em>pfn_notify</em> is <code>NULL</code>, no callback function is registered.</p>
+</li>
+<li>
+<p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_notify</em> is
+called.
+<em>user_data</em> can be <code>NULL</code>.</p>
+</li>
+<li>
+<p><em>errcode_ret</em> will return an appropriate error code.
+If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The parameters to the callback function <em>pfn_notify</em> are:</p>
</div>
<div class="ulist">
<ul>
@@ -6809,8 +6697,43 @@
</ul>
</div>
<div class="paragraph">
-<p>If <em>pfn_notify</em> is <code>NULL</code>, no callback function is registered.</p>
+<p>Contexts are used by the OpenCL runtime for managing objects such as
+command-queues, memory, program and kernel objects and for executing kernels
+on one or more devices specified in the context.</p>
</div>
+<table id="context-properties-table" class="tableblock frame-all grid-all stretch">
+<caption class="title">Table 7. List of supported context creation properties by <a href="#clCreateContext">clCreateContext</a></caption>
+<colgroup>
+<col style="width: 34%;">
+<col style="width: 33%;">
+<col style="width: 33%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top"><strong>cl_context_properties enum</strong></th>
+<th class="tableblock halign-left valign-top">Property value</th>
+<th class="tableblock halign-left valign-top">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_PLATFORM"></a><a href="#CL_CONTEXT_PLATFORM"><code>CL_​CONTEXT_​PLATFORM</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">cl_platform_id</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the platform to use.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_INTEROP_USER_SYNC"></a><a href="#CL_CONTEXT_INTEROP_USER_SYNC"><code>CL_​CONTEXT_​INTEROP_​USER_​SYNC</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bool</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether the user is responsible for synchronization
+ between OpenCL and other APIs.
+ Please refer to the specific sections in the OpenCL Extension
+ Specification that describe sharing with other APIs for restrictions
+ on using this flag.</p>
+<p class="tableblock"> If <a href="#CL_CONTEXT_INTEROP_USER_SYNC"><code>CL_​CONTEXT_​INTEROP_​USER_​SYNC</code></a> is not specified, a default of
+ <a href="#CL_FALSE"><code>CL_​FALSE</code></a> is assumed.</p></td>
+</tr>
+</tbody>
+</table>
<div class="admonitionblock note">
<table>
<tr>
@@ -6827,85 +6750,72 @@
</table>
</div>
<div class="paragraph">
-<p><em>user_data</em> will be passed as the <em>user_data</em> argument when <em>pfn_notify</em> is
-called.
-<em>user_data</em> can be <code>NULL</code>.</p>
-</div>
-<div class="paragraph">
-<p><em>errcode_ret</em> will return an appropriate error code.
-If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
-</div>
-<div class="paragraph">
-<p><strong>clCreateContext</strong> returns a valid non-zero context and <em>errcode_ret</em> is set
-to CL_SUCCESS if the context is created successfully.
+<p><a href="#clCreateContext"><strong>clCreateContext</strong></a> returns a valid non-zero context and <em>errcode_ret</em> is set
+to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the context is created successfully.
Otherwise, it returns a <code>NULL</code> value with the following error values
returned in <em>errcode_ret</em>:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_PLATFORM if <em>properties</em> is <code>NULL</code> and no platform could be
+<p><a href="#CL_INVALID_PLATFORM"><code>CL_​INVALID_​PLATFORM</code></a> if <em>properties</em> is <code>NULL</code> and no platform could be
selected or if platform value specified in <em>properties</em> is not a valid
platform.</p>
</li>
<li>
-<p>CL_INVALID_PROPERTY if context property name in <em>properties</em> is not a
+<p><a href="#CL_INVALID_PROPERTY"><code>CL_​INVALID_​PROPERTY</code></a> if context property name in <em>properties</em> is not a
supported property name, if the value specified for a supported property
name is not valid, or if the same property name is specified more than
once.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>devices</em> is <code>NULL</code>.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>devices</em> is <code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>num_devices</em> is equal to zero.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>num_devices</em> is equal to zero.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not
<code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_DEVICE if <em>devices</em> contains an invalid device.</p>
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>devices</em> contains an invalid device.</p>
</li>
<li>
-<p>CL_DEVICE_NOT_AVAILABLE if a device in <em>devices</em> is currently not
-available even though the device was returned by <strong>clGetDeviceIDs</strong>.</p>
+<p><a href="#CL_DEVICE_NOT_AVAILABLE"><code>CL_​DEVICE_​NOT_​AVAILABLE</code></a> if a device in <em>devices</em> is currently not
+available even though the device was returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function<sup>11</sup></p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_context clCreateContextFromType(<span class="directive">const</span> cl_context_properties *properties,
- cl_device_type device_type,
- <span class="directive">void</span>(CL_CALLBACK *pfn_notify)(
- (<span class="directive">const</span> <span class="predefined-type">char</span> *errinfo,
- <span class="directive">const</span> <span class="directive">void</span> *private_info,
- size_t cb,
- <span class="directive">void</span> *user_data),
- <span class="directive">void</span> *user_data,
- cl_int *errcode_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>creates an OpenCL context from a device type that identifies the specific
-device(s) to use.
-Only devices that are returned by <strong>clGetDeviceIDs</strong> for <em>device_type</em> are
-used to create the context.
-The context does not reference any sub-devices that may have been created
-from these devices.</p>
+<p>To create an OpenCL context from a specific device type<sup>11</sup>, call the
+function:</p>
</div>
-<div class="paragraph">
+<div id="clCreateContextFromType" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_context clCreateContextFromType(
+ <span class="directive">const</span> cl_context_properties* properties,
+ cl_device_type device_type,
+ <span class="directive">void</span> (CL_CALLBACK* pfn_notify)(<span class="directive">const</span> <span class="predefined-type">char</span>*, <span class="directive">const</span> <span class="directive">void</span>*, size_t, <span class="directive">void</span>*),
+ <span class="directive">void</span>* user_data,
+ cl_int* errcode_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>properties</em> specifies a list of context property names and their
corresponding values.
Each property name is immediately followed by the corresponding desired
@@ -6914,102 +6824,104 @@
<a href="#context-properties-table">Context Properties</a> table.
<em>properties</em> can also be <code>NULL</code> in which case the platform that is selected
is implementation-defined.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>device_type</em> is a bit-field that identifies the type of device and is
described in the <a href="#device-categories-table">Device Categories</a> table.</p>
-</div>
-<div class="paragraph">
-<p><em>pfn_notify</em> and <em>user_data</em> are described in <strong>clCreateContext</strong>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
+<p><em>pfn_notify</em> and <em>user_data</em> are described in <a href="#clCreateContext"><strong>clCreateContext</strong></a>.</p>
+</li>
+<li>
<p><em>errcode_ret</em> will return an appropriate error code.
If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clCreateContextFromType</strong> returns a valid non-zero context and <em>errcode_ret</em>
-is set to CL_SUCCESS if the context is created successfully.
+<p>Only devices that are returned by <a href="#clGetDeviceIDs"><strong>clGetDeviceIDs</strong></a> for <em>device_type</em> are
+used to create the context.
+The context does not reference any sub-devices that may have been created
+from these devices.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">11</dt>
+<dd>
+<p><a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> may return all or a subset of the actual
+physical devices present in the platform and that match device_type.</p>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p><a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> returns a valid non-zero context and <em>errcode_ret</em>
+is set to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the context is created successfully.
Otherwise, it returns a <code>NULL</code> value with the following error values
returned in <em>errcode_ret</em>:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_PLATFORM if <em>properties</em> is <code>NULL</code> and no platform could be
+<p><a href="#CL_INVALID_PLATFORM"><code>CL_​INVALID_​PLATFORM</code></a> if <em>properties</em> is <code>NULL</code> and no platform could be
selected or if platform value specified in <em>properties</em> is not a valid
platform.</p>
</li>
<li>
-<p>CL_INVALID_PROPERTY if context property name in <em>properties</em> is not a
+<p><a href="#CL_INVALID_PROPERTY"><code>CL_​INVALID_​PROPERTY</code></a> if context property name in <em>properties</em> is not a
supported property name, if the value specified for a supported property
name is not valid, or if the same property name is specified more than
once.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>pfn_notify</em> is <code>NULL</code> but <em>user_data</em> is not
<code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_DEVICE_TYPE if <em>device_type</em> is not a valid value.</p>
+<p><a href="#CL_INVALID_DEVICE_TYPE"><code>CL_​INVALID_​DEVICE_​TYPE</code></a> if <em>device_type</em> is not a valid value.</p>
</li>
<li>
-<p>CL_DEVICE_NOT_AVAILABLE if no devices that match <em>device_type</em> and
+<p><a href="#CL_DEVICE_NOT_AVAILABLE"><code>CL_​DEVICE_​NOT_​AVAILABLE</code></a> if no devices that match <em>device_type</em> and
property values specified in <em>properties</em> are currently available.</p>
</li>
<li>
-<p>CL_DEVICE_NOT_FOUND if no devices that match <em>device_type</em> and property
+<p><a href="#CL_DEVICE_NOT_FOUND"><code>CL_​DEVICE_​NOT_​FOUND</code></a> if no devices that match <em>device_type</em> and property
values specified in <em>properties</em> were found.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
-<div class="dlist">
-<dl>
-<dt class="hdlist1">11</dt>
-<dd>
-<p><strong>clCreateContextfromType</strong> may return all or a subset of the actual
-physical devices present in the platform and that match device_type.</p>
-</dd>
-</dl>
-</div>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clRetainContext(cl_context context)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>increments the <em>context</em> reference count.
-<strong>clRetainContext</strong> returns CL_SUCCESS if the function is executed
-successfully.
-Otherwise, it returns one of the following errors:</p>
+<p>To retain a context, call the function:</p>
+</div>
+<div id="clRetainContext" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainContext(
+ cl_context context);</code></pre>
+</div>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid OpenCL context.</p>
-</li>
-<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
-by the OpenCL implementation on the device.</p>
-</li>
-<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
-required by the OpenCL implementation on the host.</p>
+<p><em>context</em> specifies the OpenCL context to retain.</p>
</li>
</ul>
</div>
<div class="paragraph">
-<p><strong>clCreateContext</strong> and <strong>clCreateContextFromType</strong> perform an implicit retain.
+<p><a href="#clRetainContext"><strong>clRetainContext</strong></a> increments the <em>context</em> reference count.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clCreateContext"><strong>clCreateContext</strong></a> and <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> perform an implicit retain.
This is very helpful for 3<sup>rd</sup> party libraries, which typically get a
context passed to them by the application.
However, it is possible that the application may delete the context without
@@ -7018,86 +6930,124 @@
the problem of a context being used by a library no longer being valid.</p>
</div>
<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clReleaseContext(cl_context context)</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>decrements the <em>context</em> reference count.
-<strong>clReleaseContext</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clRetainContext"><strong>clRetainContext</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid OpenCL context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid OpenCL context.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>After the <em>context</em> reference count becomes zero and all the objects
-attached to <em>context</em> (such as memory objects, command-queues) are released,
-the <em>context</em> is deleted.
-Using this function to release a reference that was not obtained by creating
-the object or by calling <strong>clRetainContext</strong> causes undefined behavior.</p>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetContextInfo(cl_context context,
- cl_context_info param_name,
- size_t param_value_size,
- <span class="directive">void</span> *param_value,
- size_t *param_value_size_ret)</code></pre>
+<div class="paragraph">
+<p>To release a context, call the function:</p>
</div>
+<div id="clReleaseContext" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseContext(
+ cl_context context);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>context</em> specifies the OpenCL context to release.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>can be used to query information about a context.</p>
+<p><a href="#clReleaseContext"><strong>clReleaseContext</strong></a> decrements the <em>context</em> reference count.
+After the reference count becomes zero and all the objects attached to
+<em>context</em> (such as memory objects, command-queues) are released, the
+<em>context</em> is deleted.
+Using this function to release a reference that was not obtained by creating
+the object or by calling <a href="#clRetainContext"><strong>clRetainContext</strong></a> causes undefined behavior.</p>
</div>
<div class="paragraph">
+<p><a href="#clReleaseContext"><strong>clReleaseContext</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
+successfully.
+Otherwise, it returns one of the following errors:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid OpenCL context.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
+by the OpenCL implementation on the device.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
+required by the OpenCL implementation on the host.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="openblock">
+<div class="content">
+<div class="paragraph">
+<p>To query information about a context, call the function:</p>
+</div>
+<div id="clGetContextInfo" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetContextInfo(
+ cl_context context,
+ cl_context_info param_name,
+ size_t param_value_size,
+ <span class="directive">void</span>* param_value,
+ size_t* param_value_size_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>context</em> specifies the OpenCL context being queried.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_name</em> is an enumeration constant that specifies the information to
query.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value</em> is a pointer to memory where the appropriate result being
queried is returned.
If <em>param_value</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size</em> specifies the size in bytes of memory pointed to by
<em>param_value</em>.
This size must be greater than or equal to the size of return type as
described in the <a href="#context-info-table">Context Attributes</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size_ret</em> returns the actual size in bytes of data being
queried by <em>param_name</em>.
If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
<p>The list of supported <em>param_name</em> values and the information returned in
-<em>param_value</em> by <strong>clGetContextInfo</strong> is described in the
+<em>param_value</em> by <a href="#clGetContextInfo"><strong>clGetContextInfo</strong></a> is described in the
<a href="#context-info-table">Context Attributes</a> table.</p>
</div>
<table id="context-info-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 8. List of supported param_names by <strong>clGetContextInfo</strong></caption>
+<caption class="title">Table 8. List of supported param_names by <a href="#clGetContextInfo">clGetContextInfo</a></caption>
<colgroup>
<col style="width: 34%;">
<col style="width: 33%;">
@@ -7112,31 +7062,31 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_CONTEXT_REFERENCE_COUNT</strong><sup>12</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_REFERENCE_COUNT"></a><a href="#CL_CONTEXT_REFERENCE_COUNT"><code>CL_​CONTEXT_​REFERENCE_​COUNT</code></a><sup>12</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the <em>context</em> reference count.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_CONTEXT_NUM_DEVICES</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_NUM_DEVICES"></a><a href="#CL_CONTEXT_NUM_DEVICES"><code>CL_​CONTEXT_​NUM_​DEVICES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the number of devices in <em>context</em>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_CONTEXT_DEVICES</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_DEVICES"></a><a href="#CL_CONTEXT_DEVICES"><code>CL_​CONTEXT_​DEVICES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_id[]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the list of devices and sub-devices in <em>context</em>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_CONTEXT_PROPERTIES</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_CONTEXT_PROPERTIES"></a><a href="#CL_CONTEXT_PROPERTIES"><code>CL_​CONTEXT_​PROPERTIES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_context_properties[]</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Return the properties argument specified in <strong>clCreateContext</strong> or
- <strong>clCreateContextFromType</strong>.</p>
-<p class="tableblock"> If the <em>properties</em> argument specified in <strong>clCreateContext</strong> or
- <strong>clCreateContextFromType</strong> used to create <em>context</em> is not <code>NULL</code>, the
+<td class="tableblock halign-left valign-top"><p class="tableblock">Return the properties argument specified in <a href="#clCreateContext"><strong>clCreateContext</strong></a> or
+ <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a>.</p>
+<p class="tableblock"> If the <em>properties</em> argument specified in <a href="#clCreateContext"><strong>clCreateContext</strong></a> or
+ <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> used to create <em>context</em> is not <code>NULL</code>, the
implementation must return the values specified in the properties
argument.</p>
-<p class="tableblock"> If the <em>properties</em> argument specified in <strong>clCreateContext</strong> or
- <strong>clCreateContextFromType</strong> used to create <em>context</em> is <code>NULL</code>, the
+<p class="tableblock"> If the <em>properties</em> argument specified in <a href="#clCreateContext"><strong>clCreateContext</strong></a> or
+ <a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a> used to create <em>context</em> is <code>NULL</code>, the
implementation may return either a <em>param_value_size_ret</em> of 0
i.e. there is no context property value to be returned or can return
a context property value of 0 (where 0 is used to terminate the
@@ -7156,27 +7106,27 @@
</dl>
</div>
<div class="paragraph">
-<p><strong>clGetContextInfo</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clGetContextInfo"><strong>clGetContextInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid context.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>param_name</em> is not one of the supported values or
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>param_name</em> is not one of the supported values or
if size in bytes specified by <em>param_value_size</em> is < size of return
type as specified in the <a href="#context-info-table">Context Attributes</a>
table and <em>param_value</em> is not a <code>NULL</code> value.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
@@ -7184,6 +7134,8 @@
</div>
</div>
</div>
+</div>
+</div>
<div class="sect1">
<h2 id="opencl-runtime">5. The OpenCL Runtime</h2>
<div class="sectionbody">
@@ -7209,32 +7161,34 @@
application to perform appropriate synchronization.
This is described in <a href="#shared-opencl-objects">Shared OpenCL Objects</a></p>
</div>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_command_queue clCreateCommandQueueWithProperties(
+<div class="paragraph">
+<p>To create a host or device command-queue on a specific device, call the
+function:</p>
+</div>
+<div id="clCreateCommandQueueWithProperties" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_command_queue clCreateCommandQueueWithProperties(
cl_context context,
cl_device_id device,
- <span class="directive">const</span> cl_queue_properties *properties,
- cl_int *errcode_ret)</code></pre>
+ <span class="directive">const</span> cl_queue_properties* properties,
+ cl_int* errcode_ret);</code></pre>
</div>
</div>
-<div class="paragraph">
-<p>creates a host or device command-queue on a specific device.</p>
-</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
<p><em>context</em> must be a valid OpenCL context.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>device</em> must be a device or sub-device associated with <em>context</em>.
It can either be in the list of devices and sub-devices specified when
-<em>context</em> is created using <strong>clCreateContext</strong> or be a root device with the
+<em>context</em> is created using <a href="#clCreateContext"><strong>clCreateContext</strong></a> or be a root device with the
same device type as specified when <em>context</em> is created using
-<strong>clCreateContextFromType</strong>.</p>
-</div>
-<div class="paragraph">
+<a href="#clCreateContextFromType"><strong>clCreateContextFromType</strong></a>.</p>
+</li>
+<li>
<p><em>properties</em> specifies a list of properties for the command-queue and their
corresponding values.
Each property name is immediately followed by the corresponding desired
@@ -7245,9 +7199,11 @@
default value will be used.
<em>properties</em> can be <code>NULL</code> in which case the default values for supported
command-queue properties will be used.</p>
+</li>
+</ul>
</div>
<table id="queue-properties-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 9. List of supported cl_queue_properties values and description</caption>
+<caption class="title">Table 9. List of supported queue creation properties by <a href="#clCreateCommandQueueWithProperties">clCreateCommandQueueWithProperties</a></caption>
<colgroup>
<col style="width: 34%;">
<col style="width: 33%;">
@@ -7262,39 +7218,39 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_PROPERTIES</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_PROPERTIES"></a><a href="#CL_QUEUE_PROPERTIES"><code>CL_​QUEUE_​PROPERTIES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_bitfield</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This is a bitfield and can be set to a combination of the following
values:</p>
-<p class="tableblock"> CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE - Determines whether the
+<p class="tableblock"> <a id="CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"></a><a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_​QUEUE_​OUT_​OF_​ORDER_​EXEC_​MODE_​ENABLE</code></a> - Determines whether the
commands queued in the command-queue are executed in-order or
out-of-order.
If set, the commands in the command-queue are executed out-of-order.
Otherwise, commands are executed in-order.</p>
-<p class="tableblock"> CL_QUEUE_PROFILING_ENABLE - Enable or disable profiling of commands
+<p class="tableblock"> <a id="CL_QUEUE_PROFILING_ENABLE"></a><a href="#CL_QUEUE_PROFILING_ENABLE"><code>CL_​QUEUE_​PROFILING_​ENABLE</code></a> - Enable or disable profiling of commands
in the command-queue.
If set, the profiling of commands is enabled.
Otherwise profiling of commands is disabled.</p>
-<p class="tableblock"> CL_QUEUE_ON_DEVICE - Indicates that this is a device queue.
- If CL_QUEUE_ON_DEVICE is set,
- CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE<sup>1</sup> must also be set.</p>
-<p class="tableblock"> CL_QUEUE_ON_DEVICE_DEFAULT<sup>2</sup> --indicates that this is the default
+<p class="tableblock"> <a id="CL_QUEUE_ON_DEVICE"></a><a href="#CL_QUEUE_ON_DEVICE"><code>CL_​QUEUE_​ON_​DEVICE</code></a> - Indicates that this is a device queue.
+ If <a href="#CL_QUEUE_ON_DEVICE"><code>CL_​QUEUE_​ON_​DEVICE</code></a> is set,
+ <a href="#CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE"><code>CL_​QUEUE_​OUT_​OF_​ORDER_​EXEC_​MODE_​ENABLE</code></a><sup>1</sup> must also be set.</p>
+<p class="tableblock"> <a id="CL_QUEUE_ON_DEVICE_DEFAULT"></a><a href="#CL_QUEUE_ON_DEVICE_DEFAULT"><code>CL_​QUEUE_​ON_​DEVICE_​DEFAULT</code></a><sup>2</sup> - indicates that this is the default
device queue.
- This can only be used with CL_QUEUE_ON_DEVICE.</p>
-<p class="tableblock"> If CL_QUEUE_PROPERTIES is not specified an in-order host command
+ This can only be used with <a href="#CL_QUEUE_ON_DEVICE"><code>CL_​QUEUE_​ON_​DEVICE</code></a>.</p>
+<p class="tableblock"> If <a href="#CL_QUEUE_PROPERTIES"><code>CL_​QUEUE_​PROPERTIES</code></a> is not specified an in-order host command
queue is created for the specified device</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_SIZE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_SIZE"></a><a href="#CL_QUEUE_SIZE"><code>CL_​QUEUE_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the size of the device queue in bytes.</p>
-<p class="tableblock"> This can only be specified if CL_QUEUE_ON_DEVICE is set in
- CL_QUEUE_PROPERTIES.
- This must be a value ≤ CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE.</p>
+<p class="tableblock"> This can only be specified if <a href="#CL_QUEUE_ON_DEVICE"><code>CL_​QUEUE_​ON_​DEVICE</code></a> is set in
+ <a href="#CL_QUEUE_PROPERTIES"><code>CL_​QUEUE_​PROPERTIES</code></a>.
+ This must be a value ≤ <a href="#CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE"><code>CL_​DEVICE_​QUEUE_​ON_​DEVICE_​MAX_​SIZE</code></a>.</p>
<p class="tableblock"> For best performance, this should be ≤
- CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE.</p>
-<p class="tableblock"> If CL_QUEUE_SIZE is not specified, the device queue is created with
- CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE as the size of the queue.</p></td>
+ <a href="#CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"><code>CL_​DEVICE_​QUEUE_​ON_​DEVICE_​PREFERRED_​SIZE</code></a>.</p>
+<p class="tableblock"> If <a href="#CL_QUEUE_SIZE"><code>CL_​QUEUE_​SIZE</code></a> is not specified, the device queue is created with
+ <a href="#CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE"><code>CL_​DEVICE_​QUEUE_​ON_​DEVICE_​PREFERRED_​SIZE</code></a> as the size of the queue.</p></td>
</tr>
</tbody>
</table>
@@ -7310,20 +7266,24 @@
containing calls to get_default_queue are enqueued.
There can only be one default device queue for each device within a
context.
-<strong>clCreateCommandQueueWithProperties</strong> with CL_QUEUE_PROPERTIES set to
-CL_QUEUE_ON_DEVICE or CL_QUEUE_ON_DEVICE_DEFAULT will return the default
+<a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> with <a href="#CL_QUEUE_PROPERTIES"><code>CL_​QUEUE_​PROPERTIES</code></a> set to
+<a href="#CL_QUEUE_ON_DEVICE"><code>CL_​QUEUE_​ON_​DEVICE</code></a> or <a href="#CL_QUEUE_ON_DEVICE_DEFAULT"><code>CL_​QUEUE_​ON_​DEVICE_​DEFAULT</code></a> will return the default
device queue that has already been created and increment its retain
count by 1.</p>
+<div class="ulist">
+<ul>
+<li>
+<p><em>errcode_ret</em> will return an appropriate error code.
+If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
+</li>
+</ul>
+</div>
</dd>
</dl>
</div>
<div class="paragraph">
-<p><em>errcode_ret</em> will return an appropriate error code.
-If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
-</div>
-<div class="paragraph">
-<p><strong>clCreateCommandQueueWithProperties</strong> returns a valid non-zero command-queue
-and <em>errcode_ret</em> is set to CL_SUCCESS if the command-queue is created
+<p><a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> returns a valid non-zero command-queue
+and <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the command-queue is created
successfully.
Otherwise, it returns a <code>NULL</code> value with one of the following error values
returned in <em>errcode_ret</em>:</p>
@@ -7331,107 +7291,116 @@
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid context.</p>
</li>
<li>
-<p>CL_INVALID_DEVICE if <em>device</em> is not a valid device or is not associated
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>device</em> is not a valid device or is not associated
with <em>context</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values specified in <em>properties</em> are not valid.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values specified in <em>properties</em> are not valid.</p>
</li>
<li>
-<p>CL_INVALID_QUEUE_PROPERTIES if values specified in <em>properties</em> are
+<p><a href="#CL_INVALID_QUEUE_PROPERTIES"><code>CL_​INVALID_​QUEUE_​PROPERTIES</code></a> if values specified in <em>properties</em> are
valid but are not supported by the device.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clSetDefaultDeviceCommandQueue(cl_context context,
- cl_device_id device,
- cl_command_queue command_queue)</code></pre>
+<div class="paragraph">
+<p>To replace the default command queue on a device, call the function</p>
</div>
+<div id="clSetDefaultDeviceCommandQueue" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clSetDefaultDeviceCommandQueue(
+ cl_context context,
+ cl_device_id device,
+ cl_command_queue command_queue);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>context</em> is the OpenCL context used to create <em>command_queue</em>.</p>
+</li>
+<li>
+<p><em>device</em> is a valid OpenCL device associated with <em>context</em>.</p>
+</li>
+<li>
+<p><em>command_queue</em> specifies a command queue object which replaces the
+default device command queue</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>replaces the default command queue on the <em>device</em>.</p>
+<p><a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a> may be used to replace a default device
+command queue created with <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> and the
+<a href="#CL_QUEUE_ON_DEVICE_DEFAULT"><code>CL_​QUEUE_​ON_​DEVICE_​DEFAULT</code></a> flag.</p>
</div>
<div class="paragraph">
-<p><strong>clSetDefaultDeviceCommandQueue</strong> returns CL_SUCCESS if the function is
+<p><a href="#clSetDefaultDeviceCommandQueue"><strong>clSetDefaultDeviceCommandQueue</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is
executed successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid context.</p>
</li>
<li>
-<p>CL_INVALID_DEVICE if <em>device</em> is not a valid device or is not associated
+<p><a href="#CL_INVALID_DEVICE"><code>CL_​INVALID_​DEVICE</code></a> if <em>device</em> is not a valid device or is not associated
with <em>context</em>.</p>
</li>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid command-queue
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid command-queue
for <em>device</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p><strong>clSetDefaultDeviceCommandQueue</strong> may be used to replace a default device
-command queue created with <strong>clCreateCommandQueueWithProperties</strong> and the
-CL_QUEUE_ON_DEVICE_DEFAULT flag.</p>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clRetainCommandQueue(cl_command_queue command_queue)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>increments the <em>command_queue</em> reference count.
-<strong>clRetainCommandQueue</strong> returns CL_SUCCESS if the function is executed
-successfully.
-Otherwise, it returns one of the following errors:</p>
+<p>To retain a command queue, call the function</p>
+</div>
+<div id="clRetainCommandQueue" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clRetainCommandQueue(
+ cl_command_queue command_queue);</code></pre>
+</div>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid
-command-queue.</p>
-</li>
-<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
-by the OpenCL implementation on the device.</p>
-</li>
-<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
-required by the OpenCL implementation on the host.</p>
+<p><em>command_queue</em> specifies the command-queue to be retained.</p>
</li>
</ul>
</div>
<div class="paragraph">
-<p><strong>clCreateCommandQueueWithProperties</strong> performs an implicit retain.
+<p>The <em>command_queue</em> reference count is incremented.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a> performs an implicit retain.
This is very helpful for 3<sup>rd</sup> party libraries, which typically get a
command-queue passed to them by the application.
However, it is possible that the application may delete the command-queue
@@ -7441,91 +7410,132 @@
being valid.</p>
</div>
<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clReleaseCommandQueue(cl_command_queue command_queue)</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>decrements the <em>command_queue</em> reference count.
-<strong>clReleaseCommandQueue</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clRetainCommandQueue"><strong>clRetainCommandQueue</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid
command-queue.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
+</div>
+</div>
+<div class="openblock">
+<div class="content">
+<div class="paragraph">
+<p>To release a command queue, call the function</p>
+</div>
+<div id="clReleaseCommandQueue" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clReleaseCommandQueue(
+ cl_command_queue command_queue);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>command_queue</em> specifies the command-queue to be released.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The <em>command_queue</em> reference count is decremented.</p>
+</div>
<div class="paragraph">
<p>After the <em>command_queue</em> reference count becomes zero and all commands
queued to <em>command_queue</em> have finished (eg.
kernel-instances, memory object updates etc.), the command-queue is deleted.</p>
</div>
<div class="paragraph">
-<p><strong>clReleaseCommandQueue</strong> performs an implicit flush to issue any previously
+<p><a href="#clReleaseCommandQueue"><strong>clReleaseCommandQueue</strong></a> performs an implicit flush to issue any previously
queued OpenCL commands in <em>command_queue</em>.
Using this function to release a reference that was not obtained by creating
-the object or by calling <strong>clRetainCommandQueue</strong> causes undefined behavior.</p>
+the object or by calling <a href="#clRetainCommandQueue"><strong>clRetainCommandQueue</strong></a> causes undefined behavior.</p>
</div>
<div class="paragraph">
-<p>The function</p>
+<p><a href="#clReleaseCommandQueue"><strong>clReleaseCommandQueue</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
+successfully.
+Otherwise, it returns one of the following errors:</p>
</div>
-<div class="listingblock">
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid
+command-queue.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
+by the OpenCL implementation on the device.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
+required by the OpenCL implementation on the host.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetCommandQueueInfo(cl_command_queue command_queue,
- cl_command_queue_info param_name,
- size_t param_value_size,
- <span class="directive">void</span> *param_value,
- size_t *param_value_size_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>can be used to query information about a command-queue.</p>
+<p>To query information about a command-queue, call the function</p>
</div>
-<div class="paragraph">
+<div id="clGetCommandQueueInfo" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetCommandQueueInfo(
+ cl_command_queue command_queue,
+ cl_command_queue_info param_name,
+ size_t param_value_size,
+ <span class="directive">void</span>* param_value,
+ size_t* param_value_size_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> specifies the command-queue being queried.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_name</em> specifies the information to query.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value</em> is a pointer to memory where the appropriate result being
queried is returned.
If <em>param_value</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to
by <em>param_value</em>.
This size must be ≥ size of return type as described in the
<a href="#command-queue-param-table">Command Queue Parameter</a> table.
If <em>param_value</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>param_value_size_ret</em> returns the actual size in bytes of data being
queried by <em>param_name</em>.
If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
<p>The list of supported <em>param_name</em> values and the information returned in
-<em>param_value</em> by <strong>clGetCommandQueueInfo</strong> is described in the
+<em>param_value</em> by <a href="#clGetCommandQueueInfo"><strong>clGetCommandQueueInfo</strong></a> is described in the
<a href="#command-queue-param-table">Command Queue Parameter</a> table.</p>
</div>
<table id="command-queue-param-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 10. List of supported param_names by <strong>clGetCommandQueueInfo</strong></caption>
+<caption class="title">Table 10. List of supported param_names by <a href="#clGetCommandQueueInfo">clGetCommandQueueInfo</a></caption>
<colgroup>
<col style="width: 34%;">
<col style="width: 33%;">
@@ -7540,36 +7550,36 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_CONTEXT</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_CONTEXT"></a><a href="#CL_QUEUE_CONTEXT"><code>CL_​QUEUE_​CONTEXT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_context</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the context specified when the command-queue is created.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_DEVICE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_DEVICE"></a><a href="#CL_QUEUE_DEVICE"><code>CL_​QUEUE_​DEVICE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_device_id</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the device specified when the command-queue is created.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_REFERENCE_COUNT</strong><sup>3</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_REFERENCE_COUNT"></a><a href="#CL_QUEUE_REFERENCE_COUNT"><code>CL_​QUEUE_​REFERENCE_​COUNT</code></a><sup>3</sup></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the command-queue reference count.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_PROPERTIES</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_PROPERTIES"></a><a href="#CL_QUEUE_PROPERTIES"><code>CL_​QUEUE_​PROPERTIES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_command_queue_properties</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the currently specified properties for the command-queue.
These properties are specified by the value associated with the
- CL_COMMAND_QUEUE_PROPERTIES passed in <em>properties</em> argument in
- <strong>clCreateCommandQueueWithProperties.</strong></p></td>
+ <a href="#CL_QUEUE_PROPERTIES"><code>CL_​QUEUE_​PROPERTIES</code></a> passed in <em>properties</em> argument in
+ <a href="#clCreateCommandQueueWithProperties"><strong>clCreateCommandQueueWithProperties</strong></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_SIZE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_SIZE"></a><a href="#CL_QUEUE_SIZE"><code>CL_​QUEUE_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the currently specified size for the device command-queue.
This query is only supported for device command queues.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_QUEUE_DEVICE_DEFAULT</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_QUEUE_DEVICE_DEFAULT"></a><a href="#CL_QUEUE_DEVICE_DEFAULT"><code>CL_​QUEUE_​DEVICE_​DEFAULT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_command_queue</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return the current default command queue for the underlying device.</p></td>
</tr>
@@ -7586,28 +7596,28 @@
</dl>
</div>
<div class="paragraph">
-<p><strong>clGetCommandQueueInfo</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clGetCommandQueueInfo"><strong>clGetCommandQueueInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>param_name</em> is not one of the supported values or
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>param_name</em> is not one of the supported values or
if size in bytes specified by <em>param_value_size</em> is < size of return
type as specified in the <a href="#command-queue-param-table">Command Queue
Parameter</a> table, and <em>param_value</em> is not a <code>NULL</code> value.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
@@ -7635,6 +7645,8 @@
</table>
</div>
</div>
+</div>
+</div>
<div class="sect2">
<h3 id="_buffer_objects">5.2. Buffer Objects</h3>
<div class="paragraph">
@@ -7644,32 +7656,48 @@
</div>
<div class="sect3">
<h4 id="_creating_buffer_objects">5.2.1. Creating Buffer Objects</h4>
+<div class="openblock">
+<div class="content">
<div class="paragraph">
<p>A <strong>buffer object</strong> is created using the following function</p>
</div>
-<div class="listingblock">
+<div id="clCreateBuffer" class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_mem clCreateBuffer(cl_context context,
- cl_mem_flags flags,
- size_t size,
- <span class="directive">void</span> *host_ptr,
- cl_int *errcode_ret)</code></pre>
+<pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateBuffer(
+ cl_context context,
+ cl_mem_flags flags,
+ size_t size,
+ <span class="directive">void</span>* host_ptr,
+ cl_int* errcode_ret);</code></pre>
</div>
</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
<p><em>context</em> is a valid OpenCL context used to create the buffer object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>flags</em> is a bit-field that is used to specify allocation and usage
information such as the memory arena that should be used to allocate the
buffer object and how it will be used.
The <a href="#memory-flags-table">Memory Flags</a> table describes the possible values
for <em>flags</em>.
-If value specified for <em>flags</em> is 0, the default is used which is
-CL_MEM_READ_WRITE.</p>
+If the value specified for <em>flags</em> is 0, the default is used which is
+<a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a>.</p>
+</li>
+<li>
+<p><em>size</em> is the size in bytes of the buffer memory object to be allocated.</p>
+</li>
+<li>
+<p><em>host_ptr</em> is a pointer to the buffer data that may already be allocated
+by the application.
+The size of the buffer that <em>host_ptr</em> points to must be ≥ <em>size</em>
+bytes.</p>
+</li>
+</ul>
</div>
<table id="memory-flags-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 11. List of supported cl_mem_flags values</caption>
+<caption class="title">Table 11. List of supported memory flag values</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
@@ -7682,36 +7710,36 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_READ_WRITE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_READ_WRITE"></a><a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the memory object will be read
and written by a kernel.
This is the default.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_WRITE_ONLY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_WRITE_ONLY"></a><a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the memory object will be
written but not read by a kernel.</p>
-<p class="tableblock"> Reading from a buffer or image object created with CL_MEM_WRITE_ONLY
+<p class="tableblock"> Reading from a buffer or image object created with <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a>
inside a kernel is undefined.</p>
-<p class="tableblock"> CL_MEM_READ_WRITE and CL_MEM_WRITE_ONLY are mutually exclusive.</p></td>
+<p class="tableblock"> <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> and <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a> are mutually exclusive.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_READ_ONLY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_READ_ONLY"></a><a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the memory object is a
readonly memory object when used inside a kernel.</p>
-<p class="tableblock"> Writing to a buffer or image object created with CL_MEM_READ_ONLY inside
+<p class="tableblock"> Writing to a buffer or image object created with <a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a> inside
a kernel is undefined.</p>
-<p class="tableblock"> CL_MEM_READ_WRITE or CL_MEM_WRITE_ONLY and CL_MEM_READ_ONLY are mutually
+<p class="tableblock"> <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> or <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a> and <a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a> are mutually
exclusive.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_USE_HOST_PTR</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_USE_HOST_PTR"></a><a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag is valid only if host_ptr is not <code>NULL</code>.
If specified, it indicates that the application wants the OpenCL
implementation to use memory referenced by host_ptr as the storage bits
for the memory object.</p>
<p class="tableblock"> The contents of the memory pointed to by host_ptr at the time of the
- clCreateBuffer call define the initial contents of the buffer object.</p>
+ <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> call define the initial contents of the buffer object.</p>
<p class="tableblock"> OpenCL implementations are allowed to cache the buffer contents pointed
to by host_ptr in device memory.
This cached copy can be used when kernels are executed on a device.</p>
@@ -7720,27 +7748,27 @@
is considered to be undefined.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_ALLOC_HOST_PTR</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_ALLOC_HOST_PTR"></a><a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the application wants the OpenCL implementation
to allocate memory from host accessible memory.</p>
-<p class="tableblock"> CL_MEM_ALLOC_HOST_PTR and CL_MEM_USE_HOST_PTR are mutually exclusive.</p></td>
+<p class="tableblock"> <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> are mutually exclusive.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_COPY_HOST_PTR</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_COPY_HOST_PTR"></a><a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag is valid only if host_ptr is not <code>NULL</code>.
If specified, it indicates that the application wants the OpenCL
implementation to allocate memory for the memory object and copy the
data from memory referenced by host_ptr.
The implementation will copy the memory immediately and host_ptr is
- available for reuse by the application when the <strong>clCreateBuffer</strong> or
- <strong>clCreateImage</strong> operation returns.</p>
-<p class="tableblock"> CL_MEM_COPY_HOST_PTR and CL_MEM_USE_HOST_PTR are mutually exclusive.</p>
-<p class="tableblock"> CL_MEM_COPY_HOST_PTR can be used with CL_MEM_ALLOC_HOST_PTR to
+ available for reuse by the application when the <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> or
+ <a href="#clCreateImage"><strong>clCreateImage</strong></a> operation returns.</p>
+<p class="tableblock"> <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> are mutually exclusive.</p>
+<p class="tableblock"> <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> can be used with <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a> to
initialize the contents of the cl_mem object allocated using
host-accessible (e.g. PCIe) memory.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_HOST_WRITE_ONLY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_HOST_WRITE_ONLY"></a><a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the host will only write to the memory object
(using OpenCL APIs that enqueue a write or a map for write).
This can be used to optimize write access from the host (e.g. enable
@@ -7748,34 +7776,34 @@
communicate with the host over a system bus such as PCIe).</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_HOST_READ_ONLY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_HOST_READ_ONLY"></a><a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the host will only read
the memory object (using OpenCL APIs that enqueue a read or a map for
read).</p>
-<p class="tableblock"> CL_MEM_HOST_WRITE_ONLY and CL_MEM_HOST_READ_ONLY are mutually exclusive.</p></td>
+<p class="tableblock"> <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> and <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> are mutually exclusive.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_HOST_NO_ACCESS</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_HOST_NO_ACCESS"></a><a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the host will not read or
write the memory object.</p>
-<p class="tableblock"> CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_READ_ONLY and
- CL_MEM_HOST_NO_ACCESS are mutually exclusive.</p></td>
+<p class="tableblock"> <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> or <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> and
+ <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> are mutually exclusive.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_KERNEL_READ_AND_WRITE"></a><a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_​MEM_​KERNEL_​READ_​AND_​WRITE</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">This flag is only used by <a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> to query image
+ formats that may be both read from and written to by the same kernel
+ instance.
+ To create a memory object that may be read from and written to use
+ <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a>.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
-<p><em>size</em> is the size in bytes of the buffer memory object to be allocated.</p>
-</div>
-<div class="paragraph">
-<p><em>host_ptr</em> is a pointer to the buffer data that may already be allocated by
-the application.
-The size of the buffer that <em>host_ptr</em> points to must be ≥ <em>size</em> bytes.</p>
-</div>
-<div class="paragraph">
<p>The user is responsible for ensuring that data passed into and out of OpenCL
images are natively aligned relative to the start of the buffer as per
kernel language or IL requirements.
-OpenCL buffers created with CL_MEM_USE_HOST_PTR need to provide an
+OpenCL buffers created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> need to provide an
appropriately aligned host memory pointer that is aligned to the data types
used to access these buffers in a kernel(s).</p>
</div>
@@ -7784,17 +7812,17 @@
If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
</div>
<div class="paragraph">
-<p>If <strong>clCreateBuffer</strong> is called with CL_MEM_USE_HOST_PTR set in its <em>flags</em>
+<p>If <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> is called with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> set in its <em>flags</em>
argument, the contents of the memory pointed to by <em>host_ptr</em> at the time
-of the <strong>clCreateBuffer</strong> call define the initial contents of the
+of the <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> call define the initial contents of the
buffer object.</p>
</div>
<div class="paragraph">
-<p>If <strong>clCreateBuffer</strong> is called with a pointer returned by <strong>clSVMAlloc</strong> as its
-<em>host_ptr</em> argument, and CL_MEM_USE_HOST_PTR is set in its <em>flags</em> argument,
-<strong>clCreateBuffer</strong> will succeed and return a valid non-zero buffer object as
-long as the <em>size</em> argument to <strong>clCreateBuffer</strong> is no larger than the <em>size</em>
-argument passed in the original <strong>clSVMAlloc</strong> call.
+<p>If <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> is called with a pointer returned by <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> as its
+<em>host_ptr</em> argument, and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> is set in its <em>flags</em> argument,
+<a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> will succeed and return a valid non-zero buffer object as
+long as the <em>size</em> argument to <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> is no larger than the <em>size</em>
+argument passed in the original <a href="#clSVMAlloc"><strong>clSVMAlloc</strong></a> call.
The new buffer object returned has the shared memory as the underlying
storage.
Locations in the buffers underlying shared memory can be operated on using
@@ -7802,45 +7830,45 @@
model.</p>
</div>
<div class="paragraph">
-<p><strong>clCreateBuffer</strong> returns a valid non-zero buffer object and <em>errcode_ret</em> is
-set to CL_SUCCESS if the buffer object is created successfully.
+<p><a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> returns a valid non-zero buffer object and <em>errcode_ret</em> is
+set to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the buffer object is created successfully.
Otherwise, it returns a <code>NULL</code> value with one of the following error values
returned in <em>errcode_ret</em>:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid context.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values specified in <em>flags</em> are not valid as defined
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values specified in <em>flags</em> are not valid as defined
in the <a href="#memory-flags-table">Memory Flags</a> table.</p>
</li>
<li>
-<p>CL_INVALID_BUFFER_SIZE if <em>size</em> is 0<sup>4</sup>.</p>
+<p><a href="#CL_INVALID_BUFFER_SIZE"><code>CL_​INVALID_​BUFFER_​SIZE</code></a> if <em>size</em> is 0<sup>4</sup>.</p>
</li>
<li>
-<p>CL_INVALID_HOST_PTR if <em>host_ptr</em> is <code>NULL</code> and CL_MEM_USE_HOST_PTR or
-CL_MEM_COPY_HOST_PTR are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code>
-but CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in <em>flags</em>.</p>
+<p><a href="#CL_INVALID_HOST_PTR"><code>CL_​INVALID_​HOST_​PTR</code></a> if <em>host_ptr</em> is <code>NULL</code> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> or
+<a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code>
+but <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> or <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> are not set in <em>flags</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for buffer object.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">4</dt>
<dd>
-<p>Implementations may return CL_INVALID_BUFFER_SIZE if size is greater
-than CL_DEVICE_MAX_MEM_ALLOC_SIZE value specified in the
+<p>Implementations may return <a href="#CL_INVALID_BUFFER_SIZE"><code>CL_​INVALID_​BUFFER_​SIZE</code></a> if size is greater
+than <a href="#CL_DEVICE_MAX_MEM_ALLOC_SIZE"><code>CL_​DEVICE_​MAX_​MEM_​ALLOC_​SIZE</code></a> value specified in the
<a href="#device-queries-table">Device Queries</a> table for all devices in
context.</p>
</dd>
@@ -7849,52 +7877,58 @@
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_mem clCreateSubBuffer(cl_mem buffer,
- cl_mem_flags flags,
- cl_buffer_create_type buffer_create_type,
- <span class="directive">const</span> <span class="directive">void</span> *buffer_create_info,
- cl_int *errcode_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>can be used to create a new buffer object (referred to as a sub-buffer
-object) from an existing buffer object.</p>
+<p>To create a new buffer object (referred to as a sub-buffer object) from an
+existing buffer object, call the function</p>
</div>
-<div class="paragraph">
+<div id="clCreateSubBuffer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateSubBuffer(
+ cl_mem buffer,
+ cl_mem_flags flags,
+ cl_buffer_create_type buffer_create_type,
+ <span class="directive">const</span> <span class="directive">void</span>* buffer_create_info,
+ cl_int* errcode_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>buffer</em> must be a valid buffer object and cannot be a sub-buffer object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>flags</em> is a bit-field that is used to specify allocation and usage
information about the sub-buffer memory object being created and is
described in the <a href="#memory-flags-table">Memory Flags</a> table.
-If the CL_MEM_READ_WRITE, CL_MEM_READ_ONLY or CL_MEM_WRITE_ONLY values are
+If the <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a>, <a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a>, or <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a> values are
not specified in <em>flags</em>, they are inherited from the corresponding memory
access qualifiers associated with <em>buffer</em>.
-The CL_MEM_USE_HOST_PTR, CL_MEM_ALLOC_HOST_PTR and CL_MEM_COPY_HOST_PTR
+The <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a>, and <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a>
values cannot be specified in <em>flags</em> but are inherited from the
corresponding memory access qualifiers associated with <em>buffer</em>.
-If CL_MEM_COPY_HOST_PTR is specified in the memory access qualifier values
+If <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> is specified in the memory access qualifier values
associated with <em>buffer</em> it does not imply any additional copies when the
sub-buffer is created from <em>buffer</em>.
-If the CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY or
-CL_MEM_HOST_NO_ACCESS values are not specified in <em>flags</em>, they are
+If the <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a>, <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a>, or
+<a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> values are not specified in <em>flags</em>, they are
inherited from the corresponding memory access qualifiers associated with
<em>buffer</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>buffer_create_type</em> and <em>buffer_create_info</em> describe the type of buffer
object to be created.
The list of supported values for <em>buffer_create_type</em> and corresponding
descriptor that <em>buffer_create_info</em> points to is described in the
<a href="#subbuffer-create-info-table">SubBuffer Attributes</a> table.</p>
+</li>
+</ul>
</div>
<table id="subbuffer-create-info-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 12. List of supported names and values in <strong>clCreateSubBuffer</strong></caption>
+<caption class="title">Table 12. List of supported buffer creation types by <a href="#clCreateSubBuffer">clCreateSubBuffer</a></caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
@@ -7907,101 +7941,78 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_BUFFER_CREATE_TYPE_REGION</strong></p></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
-<p>Create a buffer object that represents a
- specific region in buffer.</p>
-</div>
-<div class="openblock">
-<div class="content">
-<div class="paragraph">
-<p>buffer_create_info is a pointer to the following structure:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c"><span class="keyword">typedef</span> <span class="keyword">struct</span> _cl_buffer_region {
- size_t origin;
- size_t size;
-} cl_buffer_region;</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>(<em>origin</em>, <em>size</em>) defines the offset and size in bytes in buffer.</p>
-</div>
-<div class="paragraph">
-<p>If buffer is created with CL_MEM_USE_HOST_PTR, the host_ptr associated with
-the buffer object returned is <em>host_ptr + origin</em>.</p>
-</div>
-<div class="paragraph">
-<p>The buffer object returned references the data store allocated for buffer
-and points to a specific region given by (origin, size) in this data store.</p>
-</div>
-<div class="paragraph">
-<p>CL_INVALID_VALUE is returned in errcode_ret if the region specified by
-(origin, size) is out of bounds in buffer.</p>
-</div>
-<div class="paragraph">
-<p>CL_INVALID_BUFFER_SIZE if size is 0.</p>
-</div>
-<div class="paragraph">
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET is returned in errcode_ret if there are no
-devices in context associated with buffer for which the origin value is
-aligned to the CL_DEVICE_MEM_BASE_ADDR_ALIGN value.</p>
-</div>
-</div>
-</div></div></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_BUFFER_CREATE_TYPE_REGION"></a><a href="#CL_BUFFER_CREATE_TYPE_REGION"><code>CL_​BUFFER_​CREATE_​TYPE_​REGION</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Create a buffer object that represents a specific region in <em>buffer</em>.</p>
+<p class="tableblock"> <em>buffer_create_info</em> is a pointer to a <strong><a href="#cl_buffer_region">cl_buffer_region</a></strong> structure
+ specifying a region of the buffer.</p>
+<p class="tableblock"> If <em>buffer</em> is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, the <em>host_ptr</em>
+ associated with the buffer object returned is <em>host_ptr + origin</em>.</p>
+<p class="tableblock"> The buffer object returned references the data store allocated for
+ buffer and points to the region specified by <em>buffer_create_info</em> in
+ this data store.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
-<p><strong>clCreateSubBuffer</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors in <em>errcode_ret</em>:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>buffer</em> is not a valid buffer object or is a
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>buffer</em> is not a valid buffer object or is a
sub-buffer object.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>buffer</em> was created with CL_MEM_WRITE_ONLY and
-<em>flags</em> specifies CL_MEM_READ_WRITE or CL_MEM_READ_ONLY, or if <em>buffer</em>
-was created with CL_MEM_READ_ONLY and <em>flags</em> specifies
-CL_MEM_READ_WRITE or CL_MEM_WRITE_ONLY, or if <em>flags</em> specifies
-CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR or CL_MEM_COPY_HOST_PTR.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>buffer</em> was created with <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a> and
+<em>flags</em> specifies <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> or <a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a>, or if <em>buffer</em>
+was created with <a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a> and <em>flags</em> specifies
+<a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> or <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a>, or if <em>flags</em> specifies
+<a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> or <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a> or <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>buffer</em> was created with CL_MEM_HOST_WRITE_ONLY and
-<em>flags</em> specify CL_MEM_HOST_READ_ONLY, or if <em>buffer</em> was created with
-CL_MEM_HOST_READ_ONLY and <em>flags</em> specify CL_MEM_HOST_WRITE_ONLY, or if
-<em>buffer</em> was created with CL_MEM_HOST_NO_ACCESS and <em>flags</em> specify
-CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_WRITE_ONLY.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>buffer</em> was created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> and
+<em>flags</em> specify <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a>, or if <em>buffer</em> was created with
+<a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> and <em>flags</em> specify <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a>, or if
+<em>buffer</em> was created with <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> and <em>flags</em> specify
+<a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> or <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if value specified in <em>buffer_create_type</em> is not
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the value specified in <em>buffer_create_type</em> is not
valid.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if value(s) specified in <em>buffer_create_info</em> (for a
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if value(s) specified in <em>buffer_create_info</em> (for a
given <em>buffer_create_type</em>) is not valid or if <em>buffer_create_info</em> is
<code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_BUFFER_SIZE if <em>size</em> is 0.</p>
-</li>
-<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for sub-buffer object.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
+<li>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the region specified by the <strong><a href="#cl_buffer_region">cl_buffer_region</a></strong>
+structure passed in <em>buffer_create_info</em> is out of bounds in <em>buffer</em>.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_BUFFER_SIZE"><code>CL_​INVALID_​BUFFER_​SIZE</code></a> if the <em>size</em> field of the <strong><a href="#cl_buffer_region">cl_buffer_region</a></strong>
+structure passed in <em>buffer_create_info</em> is 0.</p>
+</li>
+<li>
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if there are no devices in <em>context</em>
+associated with <em>buffer</em> for which the <em>origin</em> field of the
+<strong><a href="#cl_buffer_region">cl_buffer_region</a></strong> structure passed in <em>buffer_create_info</em> is
+aligned to the <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value.</p>
+</li>
</ul>
</div>
<div class="admonitionblock note">
@@ -8024,94 +8035,102 @@
</table>
</div>
</div>
+</div>
+<div class="openblock">
+<div class="content">
+<div class="paragraph">
+<p>The <strong>cl_buffer_region</strong> structure specifies a region of a buffer object:</p>
+</div>
+<div id="cl_buffer_region" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_buffer_region {
+ size_t origin;
+ size_t size;
+} cl_buffer_region;</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>origin</em> is the offset in bytes of the region.</p>
+</li>
+<li>
+<p><em>size</em> is the size in bytes of the region.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Constraints on the values of <em>origin</em> and <em>size</em> are specified for the
+<a href="#clCreateSubBuffer"><strong>clCreateSubBuffer</strong></a> function to which this structure is passed.</p>
+</div>
+</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_reading_writing_and_copying_buffer_objects">5.2.2. Reading, Writing and Copying Buffer Objects</h4>
<div class="paragraph">
<p>The following functions enqueue commands to read from a buffer object to
host memory or write to a buffer object from host memory.</p>
</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueReadBuffer(cl_command_queue command_queue,
- cl_mem buffer,
- cl_bool blocking_read,
- size_t offset,
- size_t size,
- <span class="directive">void</span> *ptr,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueWriteBuffer(cl_command_queue command_queue,
- cl_mem buffer,
- cl_bool blocking_write,
- size_t offset,
- size_t size,
- <span class="directive">const</span> <span class="directive">void</span> *ptr,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
<div class="paragraph">
+<p>To read from a buffer object to host memory, call one of the functions</p>
+</div>
+<div id="clEnqueueReadBuffer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueReadBuffer(
+ cl_command_queue command_queue,
+ cl_mem buffer,
+ cl_bool blocking_read,
+ size_t offset,
+ size_t size,
+ <span class="directive">void</span>* ptr,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div id="clEnqueueWriteBuffer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueWriteBuffer(
+ cl_command_queue command_queue,
+ cl_mem buffer,
+ cl_bool blocking_write,
+ size_t offset,
+ size_t size,
+ <span class="directive">const</span> <span class="directive">void</span>* ptr,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> is a valid host command-queue in which the read / write
command will be queued.
<em>command_queue</em> and <em>buffer</em> must be created with the same OpenCL context.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>buffer</em> refers to a valid buffer object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>blocking_read</em> and <em>blocking_write</em> indicate if the read and write
-operations are <em>blocking</em> or <em>non-blocking</em>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_read</em> is CL_TRUE i.e. the read command is blocking,
-<strong>clEnqueueReadBuffer</strong> does not return until the buffer data has been read
-and copied into memory pointed to by <em>ptr</em>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_read</em> is CL_FALSE i.e. the read command is non-blocking,
-<strong>clEnqueueReadBuffer</strong> queues a non-blocking read command and returns.
-The contents of the buffer that <em>ptr</em> points to cannot be used until the
-read command has completed.
-The <em>event</em> argument returns an event object which can be used to query the
-execution status of the read command.
-When the read command has completed, the contents of the buffer that <em>ptr</em>
-points to can be used by the application.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_write</em> is CL_TRUE, the write command is blocking and does not
-return until the command is complete, including transfer of the data.
-The memory pointed to by <em>ptr</em> can be reused by the application after the
-<strong>clEnqueueWriteBuffer</strong> call returns.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_write</em> is CL_FALSE, the OpenCL implementation will use <em>ptr</em> to
-perform a non-blocking write.
-As the write is non-blocking the implementation can return immediately.
-The memory pointed to by <em>ptr</em> cannot be reused by the application after the
-call returns.
-The <em>event</em> argument returns an event object which can be used to query the
-execution status of the write command.
-When the write command has completed, the memory pointed to by <em>ptr</em> can
-then be reused by the application.</p>
-</div>
-<div class="paragraph">
+operations are <em>blocking</em> or <em>non-blocking</em> (see below).</p>
+</li>
+<li>
<p><em>offset</em> is the offset in bytes in the buffer object to read from or write
to.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>size</em> is the size in bytes of data being read or written.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>ptr</em> is the pointer to buffer in host memory where data is to be read into
or to be written from.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -8125,8 +8144,8 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular read / write
command and can be used to query or queue a wait for this particular command
to complete.
@@ -8136,132 +8155,17 @@
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
-</div>
-<div class="paragraph">
-<p><strong>clEnqueueReadBuffer</strong> and <strong>clEnqueueWriteBuffer</strong> return CL_SUCCESS if the
-function is executed successfully.
-Otherwise, it returns one of the following errors:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
-command-queue.</p>
-</li>
-<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em> and
-<em>buffer</em> are not the same or if the context associated with
-<em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p>
-</li>
-<li>
-<p>CL_INVALID_MEM_OBJECT if <em>buffer</em> is not a valid buffer object.</p>
-</li>
-<li>
-<p>CL_INVALID_VALUE if the region being read or written specified by
-(<em>offset</em>, <em>size</em>) is out of bounds or if <em>ptr</em> is a <code>NULL</code> value.</p>
-</li>
-<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
-<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
-<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
-are not valid events.</p>
-</li>
-<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>buffer</em> is a sub-buffer object and
-<em>offset</em> specified when the sub-buffer object is created is not aligned
-to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with
-<em>queue</em>.</p>
-</li>
-<li>
-<p>CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write
-operations are blocking and the execution status of any of the events in
-<em>event_wait_list</em> is a negative integer value.</p>
-</li>
-<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
-memory for data store associated with <em>buffer</em>.</p>
-</li>
-<li>
-<p>CL_INVALID_OPERATION if <strong>clEnqueueReadBuffer</strong> is called on <em>buffer</em>
-which has been created with CL_MEM_HOST_WRITE_ONLY or
-CL_MEM_HOST_NO_ACCESS.</p>
-</li>
-<li>
-<p>CL_INVALID_OPERATION if <strong>clEnqueueWriteBuffer</strong> is called on <em>buffer</em>
-which has been created with CL_MEM_HOST_READ_ONLY or
-CL_MEM_HOST_NO_ACCESS.</p>
-</li>
-<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
-by the OpenCL implementation on the device.</p>
-</li>
-<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
-required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
<div class="paragraph">
-<p>The following functions enqueue commands to read a 2D or 3D rectangular
-region from a buffer object to host memory or write a 2D or 3D rectangular
-region to a buffer object from host memory.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueReadBufferRect(cl_command_queue command_queue,
- cl_mem buffer,
- cl_bool blocking_read,
- <span class="directive">const</span> size_t *buffer_origin,
- <span class="directive">const</span> size_t *host_origin,
- <span class="directive">const</span> size_t *region,
- size_t buffer_row_pitch,
- size_t buffer_slice_pitch,
- size_t host_row_pitch,
- size_t host_slice_pitch,
- <span class="directive">void</span> *ptr,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueWriteBufferRect(cl_command_queue command_queue,
- cl_mem buffer,
- cl_bool blocking_write,
- <span class="directive">const</span> size_t *buffer_origin,
- <span class="directive">const</span> size_t *host_origin,
- <span class="directive">const</span> size_t *region,
- size_t buffer_row_pitch,
- size_t buffer_slice_pitch,
- size_t host_row_pitch,
- size_t host_slice_pitch,
- <span class="directive">const</span> <span class="directive">void</span> *ptr,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
+<p>If <em>blocking_read</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> i.e. the read command is blocking,
+<a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> does not return until the buffer data has been read
+and copied into memory pointed to by <em>ptr</em>.</p>
</div>
<div class="paragraph">
-<p><em>command_queue</em> refers is a valid host command-queue in which the read /
-write command will be queued.
-<em>command_queue</em> and <em>buffer</em> must be created with the same OpenCL context.</p>
-</div>
-<div class="paragraph">
-<p><em>buffer</em> refers to a valid buffer object.</p>
-</div>
-<div class="paragraph">
-<p><em>blocking_read</em> and <em>blocking_write</em> indicate if the read and write
-operations are <em>blocking</em> or <em>non-blocking</em>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_read</em> is CL_TRUE i.e. the read command is blocking,
-<strong>clEnqueueReadBufferRect</strong> does not return until the buffer data has been
-read and copied into memory pointed to by <em>ptr</em>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_read</em> is CL_FALSE i.e. the read command is non-blocking,
-<strong>clEnqueueReadBufferRect</strong> queues a non-blocking read command and returns.
+<p>If <em>blocking_read</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> i.e. the read command is non-blocking,
+<a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> queues a non-blocking read command and returns.
The contents of the buffer that <em>ptr</em> points to cannot be used until the
read command has completed.
The <em>event</em> argument returns an event object which can be used to query the
@@ -8270,13 +8174,13 @@
points to can be used by the application.</p>
</div>
<div class="paragraph">
-<p>If <em>blocking_write</em> is CL_TRUE, the write command is blocking and does not
+<p>If <em>blocking_write</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>, the write command is blocking and does not
return until the command is complete, including transfer of the data.
The memory pointed to by <em>ptr</em> can be reused by the application after the
-<strong>clEnqueueWriteBufferRect</strong> call returns.</p>
+<a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> call returns.</p>
</div>
<div class="paragraph">
-<p>If <em>blocking_write</em> is CL_FALSE, the OpenCL implementation will use <em>ptr</em> to
+<p>If <em>blocking_write</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>, the OpenCL implementation will use <em>ptr</em> to
perform a non-blocking write.
As the write is non-blocking the implementation can return immediately.
The memory pointed to by <em>ptr</em> cannot be reused by the application after the
@@ -8287,6 +8191,131 @@
then be reused by the application.</p>
</div>
<div class="paragraph">
+<p><a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> and <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> return <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the
+function is executed successfully.
+Otherwise, it returns one of the following errors:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
+command-queue.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em> and
+<em>buffer</em> are not the same or if the context associated with
+<em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the region being read or written specified by
+(<em>offset</em>, <em>size</em>) is out of bounds or if <em>ptr</em> is a <code>NULL</code> value.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
+<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
+<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
+are not valid events.</p>
+</li>
+<li>
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and
+<em>offset</em> specified when the sub-buffer object is created is not aligned
+to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated with
+<em>queue</em>.</p>
+</li>
+<li>
+<p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_​EXEC_​STATUS_​ERROR_​FOR_​EVENTS_​IN_​WAIT_​LIST</code></a> if the read and write
+operations are blocking and the execution status of any of the events in
+<em>event_wait_list</em> is a negative integer value.</p>
+</li>
+<li>
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
+memory for data store associated with <em>buffer</em>.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> is called on <em>buffer</em>
+which has been created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> or
+<a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a>.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> is called on <em>buffer</em>
+which has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> or
+<a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a>.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
+by the OpenCL implementation on the device.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
+required by the OpenCL implementation on the host.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="openblock">
+<div class="content">
+<div class="paragraph">
+<p>The following functions enqueue commands to read a 2D or 3D rectangular
+region from a buffer object to host memory or write a 2D or 3D rectangular
+region to a buffer object from host memory.</p>
+</div>
+<div id="clEnqueueReadBufferRect" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueReadBufferRect(
+ cl_command_queue command_queue,
+ cl_mem buffer,
+ cl_bool blocking_read,
+ <span class="directive">const</span> size_t* buffer_offset,
+ <span class="directive">const</span> size_t* host_offset,
+ <span class="directive">const</span> size_t* region,
+ size_t buffer_row_pitch,
+ size_t buffer_slice_pitch,
+ size_t host_row_pitch,
+ size_t host_slice_pitch,
+ <span class="directive">void</span>* ptr,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div id="clEnqueueWriteBufferRect" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueWriteBufferRect(
+ cl_command_queue command_queue,
+ cl_mem buffer,
+ cl_bool blocking_write,
+ <span class="directive">const</span> size_t* buffer_offset,
+ <span class="directive">const</span> size_t* host_offset,
+ <span class="directive">const</span> size_t* region,
+ size_t buffer_row_pitch,
+ size_t buffer_slice_pitch,
+ size_t host_row_pitch,
+ size_t host_slice_pitch,
+ <span class="directive">const</span> <span class="directive">void</span>* ptr,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>command_queue</em> refers is a valid host command-queue in which the read /
+write command will be queued.
+<em>command_queue</em> and <em>buffer</em> must be created with the same OpenCL context.</p>
+</li>
+<li>
+<p><em>buffer</em> refers to a valid buffer object.</p>
+</li>
+<li>
+<p><em>blocking_read</em> and <em>blocking_write</em> indicate if the read and write
+operations are <em>blocking</em> or <em>non-blocking</em> (see below).</p>
+</li>
+<li>
<p><em>buffer_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region
associated with <em>buffer</em>.
For a 2D rectangle region, the <em>z</em> value given by <em>buffer_origin</em>[2] should
@@ -8294,8 +8323,8 @@
The offset in bytes is computed as <em>buffer_origin</em>[2] ×
<em>buffer_slice_pitch</em> + <em>buffer_origin</em>[1] × <em>buffer_row_pitch</em> +
<em>buffer_origin</em>[0].</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>host_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region
pointed to by <em>ptr</em>.
For a 2D rectangle region, the <em>z</em> value given by <em>host_origin</em>[2] should be
@@ -8303,40 +8332,40 @@
The offset in bytes is computed as <em>host_origin</em>[2] ×
<em>host_slice_pitch</em> + <em>host_origin</em>[1] × <em>host_row_pitch</em> +
<em>host_origin</em>[0].</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>region</em> defines the (<em>width</em> in bytes, <em>height</em> in rows, <em>depth</em> in slices)
of the 2D or 3D rectangle being read or written.
For a 2D rectangle copy, the <em>depth</em> value given by <em>region</em>[2] should be 1.
The values in region cannot be 0.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>buffer_row_pitch</em> is the length of each row in bytes to be used for the
memory region associated with <em>buffer</em>.
If <em>buffer_row_pitch</em> is 0, <em>buffer_row_pitch</em> is computed as <em>region</em>[0].</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>buffer_slice_pitch</em> is the length of each 2D slice in bytes to be used for
the memory region associated with <em>buffer</em>.
If <em>buffer_slice_pitch</em> is 0, <em>buffer_slice_pitch</em> is computed as
<em>region</em>[1] × <em>buffer_row_pitch</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>host_row_pitch</em> is the length of each row in bytes to be used for the
memory region pointed to by <em>ptr</em>.
If <em>host_row_pitch</em> is 0, <em>host_row_pitch</em> is computed as <em>region</em>[0].</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>host_slice_pitch</em> is the length of each 2D slice in bytes to be used for
the memory region pointed to by <em>ptr</em>.
If <em>host_slice_pitch</em> is 0, <em>host_slice_pitch</em> is computed as <em>region</em>[1]
× <em>host_row_pitch</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>ptr</em> is the pointer to buffer in host memory where data is to be read into
or to be written from.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -8350,8 +8379,8 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular read / write
command and can be used to query or queue a wait for this particular command
to complete.
@@ -8361,92 +8390,126 @@
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueReadBufferRect</strong> and <strong>clEnqueueWriteBufferRect</strong> return CL_SUCCESS
+<p>If <em>blocking_read</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> i.e. the read command is blocking,
+<a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> does not return until the buffer data has been
+read and copied into memory pointed to by <em>ptr</em>.</p>
+</div>
+<div class="paragraph">
+<p>If <em>blocking_read</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> i.e. the read command is non-blocking,
+<a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> queues a non-blocking read command and returns.
+The contents of the buffer that <em>ptr</em> points to cannot be used until the
+read command has completed.
+The <em>event</em> argument returns an event object which can be used to query the
+execution status of the read command.
+When the read command has completed, the contents of the buffer that <em>ptr</em>
+points to can be used by the application.</p>
+</div>
+<div class="paragraph">
+<p>If <em>blocking_write</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>, the write command is blocking and does not
+return until the command is complete, including transfer of the data.
+The memory pointed to by <em>ptr</em> can be reused by the application after the
+<a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> call returns.</p>
+</div>
+<div class="paragraph">
+<p>If <em>blocking_write</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>, the OpenCL implementation will use <em>ptr</em> to
+perform a non-blocking write.
+As the write is non-blocking the implementation can return immediately.
+The memory pointed to by <em>ptr</em> cannot be reused by the application after the
+call returns.
+The <em>event</em> argument returns an event object which can be used to query the
+execution status of the write command.
+When the write command has completed, the memory pointed to by <em>ptr</em> can
+then be reused by the application.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> and <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> return <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a>
if the function is executed successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em> and
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em> and
<em>buffer</em> are not the same or if the context associated with
<em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>buffer</em> is not a valid buffer object.</p>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if the region being read or written specified by
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the region being read or written specified by
(<em>buffer_origin</em>, <em>region</em>, <em>buffer_row_pitch</em>, <em>buffer_slice_pitch</em>) is
out of bounds.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>ptr</em> is a <code>NULL</code> value.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>ptr</em> is a <code>NULL</code> value.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if any <em>region</em> array element is 0.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if any <em>region</em> array element is 0.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>buffer_row_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>buffer_row_pitch</em> is not 0 and is less than
<em>region</em>[0].</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>host_row_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>host_row_pitch</em> is not 0 and is less than
<em>region</em>[0].</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>buffer_slice_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>buffer_slice_pitch</em> is not 0 and is less than
<em>region</em>[1] × <em>buffer_row_pitch</em> and not a multiple of
<em>buffer_row_pitch</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>host_slice_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>host_slice_pitch</em> is not 0 and is less than
<em>region</em>[1] × <em>host_row_pitch</em> and not a multiple of
<em>host_row_pitch</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>buffer</em> is a sub-buffer object and
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and
<em>offset</em> specified when the sub-buffer object is created is not aligned
-to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with
+to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated with
<em>queue</em>.</p>
</li>
<li>
-<p>CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write
+<p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_​EXEC_​STATUS_​ERROR_​FOR_​EVENTS_​IN_​WAIT_​LIST</code></a> if the read and write
operations are blocking and the execution status of any of the events in
<em>event_wait_list</em> is a negative integer value.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>buffer</em>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if <strong>clEnqueueReadBufferRect</strong> is called on <em>buffer</em>
-which has been created with CL_MEM_HOST_WRITE_ONLY or
-CL_MEM_HOST_NO_ACCESS.</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> is called on <em>buffer</em>
+which has been created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> or
+<a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if <strong>clEnqueueWriteBufferRect</strong> is called on <em>buffer</em>
-which has been created with CL_MEM_HOST_READ_ONLY or
-CL_MEM_HOST_NO_ACCESS.</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> is called on <em>buffer</em>
+which has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> or
+<a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
@@ -8459,10 +8522,10 @@
</td>
<td class="content">
<div class="paragraph">
-<p>Calling <strong>clEnqueueReadBuffer</strong> to read a region of the buffer object with the
+<p>Calling <a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a> to read a region of the buffer object with the
<em>ptr</em> argument value set to <em>host_ptr</em> + <em>offset</em>, where <em>host_ptr</em> is a
pointer to the memory region specified when the buffer object being read is
-created with CL_MEM_USE_HOST_PTR, must meet the following requirements in
+created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, must meet the following requirements in
order to avoid undefined behavior:</p>
</div>
<div class="ulist">
@@ -8484,18 +8547,18 @@
</ul>
</div>
<div class="paragraph">
-<p>Calling <strong>clEnqueueReadBufferRect</strong> to read a region of the buffer object with
+<p>Calling <a href="#clEnqueueReadBufferRect"><strong>clEnqueueReadBufferRect</strong></a> to read a region of the buffer object with
the <em>ptr</em> argument value set to <em>host_ptr</em> and <em>host_origin</em>,
<em>buffer_origin</em> values are the same, where <em>host_ptr</em> is a pointer to the
memory region specified when the buffer object being read is created with
-CL_MEM_USE_HOST_PTR, must meet the same requirements given above for
-<strong>clEnqueueReadBuffer</strong>.</p>
+<a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, must meet the same requirements given above for
+<a href="#clEnqueueReadBuffer"><strong>clEnqueueReadBuffer</strong></a>.</p>
</div>
<div class="paragraph">
-<p>Calling <strong>clEnqueueWriteBuffer</strong> to update the latest bits in a region of the
+<p>Calling <a href="#clEnqueueWriteBuffer"><strong>clEnqueueWriteBuffer</strong></a> to update the latest bits in a region of the
buffer object with the <em>ptr</em> argument value set to <em>host_ptr</em> + <em>offset</em>,
where <em>host_ptr</em> is a pointer to the memory region specified when the buffer
-object being written is created with CL_MEM_USE_HOST_PTR, must meet the
+object being written is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, must meet the
following requirements in order to avoid undefined behavior:</p>
</div>
<div class="ulist">
@@ -8516,11 +8579,11 @@
</ul>
</div>
<div class="paragraph">
-<p>Calling <strong>clEnqueueWriteBufferRect</strong> to update the latest bits in a region of
+<p>Calling <a href="#clEnqueueWriteBufferRect"><strong>clEnqueueWriteBufferRect</strong></a> to update the latest bits in a region of
the buffer object with the <em>ptr</em> argument value set to <em>host_ptr</em> and
<em>host_origin</em>, <em>buffer_origin</em> values are the same, where <em>host_ptr</em> is a
pointer to the memory region specified when the buffer object being written
-is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in
+is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, must meet the following requirements in
order to avoid undefined behavior:</p>
</div>
<div class="ulist">
@@ -8544,44 +8607,48 @@
</tr>
</table>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueCopyBuffer(cl_command_queue command_queue,
- cl_mem src_buffer,
- cl_mem dst_buffer,
- size_t src_offset,
- size_t dst_offset,
- size_t size,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to copy a buffer object identified by <em>src_buffer</em> to
-another buffer object identified by <em>dst_buffer</em>.</p>
+<p>To enqueue a command to copy a buffer object identified by <em>src_buffer</em> to
+another buffer object identified by <em>dst_buffer</em>, call the function</p>
</div>
-<div class="paragraph">
+<div id="clEnqueueCopyBuffer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyBuffer(
+ cl_command_queue command_queue,
+ cl_mem src_buffer,
+ cl_mem dst_buffer,
+ size_t src_offset,
+ size_t dst_offset,
+ size_t size,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> refers to a host command-queue in which the copy command
will be queued.
The OpenCL context associated with <em>command_queue</em>, <em>src_buffer</em> and
<em>dst_buffer</em> must be the same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>src_offset</em> refers to the offset where to begin copying data from
<em>src_buffer</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>dst_offset</em> refers to the offset where to begin copying data into
<em>dst_buffer</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>size</em> refers to the size in bytes to copy.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -8595,65 +8662,67 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular copy command
and can be used to query or queue a wait for this particular command to
complete.
<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
application to query the status of this command or queue a wait for this
command to complete.
-<strong>clEnqueueBarrierWithWaitList</strong> can be used instead.
+<a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> can be used instead.
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueCopyBuffer</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clEnqueueCopyBuffer"><strong>clEnqueueCopyBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em>,
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em>,
<em>src_buffer</em> and <em>dst_buffer</em> are not the same or if the context
associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not
the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>src_buffer</em> and <em>dst_buffer</em> are not valid
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are not valid
buffer objects.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>src_offset</em>, <em>dst_offset</em>, <em>size</em>, <em>src_offset</em>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>src_offset</em>, <em>dst_offset</em>, <em>size</em>, <em>src_offset</em>
+ <em>size</em> or <em>dst_offset</em> + <em>size</em> require accessing elements
outside the <em>src_buffer</em> and <em>dst_buffer</em> buffer objects respectively.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>src_buffer</em> is a sub-buffer object
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>src_buffer</em> is a sub-buffer object
and <em>offset</em> specified when the sub-buffer object is created is not
-aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated
+aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated
with <em>queue</em>.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>dst_buffer</em> is a sub-buffer object
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>dst_buffer</em> is a sub-buffer object
and <em>offset</em> specified when the sub-buffer object is created is not
-aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated
+aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated
with <em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_COPY_OVERLAP if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer
+<p><a href="#CL_MEM_COPY_OVERLAP"><code>CL_​MEM_​COPY_​OVERLAP</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer
or sub-buffer object and the source and destination regions overlap or
if <em>src_buffer</em> and <em>dst_buffer</em> are different sub-buffers of the same
associated buffer object and they overlap.
@@ -8662,44 +8731,129 @@
<em>dst_offset</em> + <em>size</em> 1.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>src_buffer</em> or <em>dst_buffer</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueCopyBufferRect(cl_command_queue command_queue,
- cl_mem src_buffer,
- cl_mem dst_buffer,
- <span class="directive">const</span> size_t *src_origin,
- <span class="directive">const</span> size_t *dst_origin,
- <span class="directive">const</span> size_t *region,
- size_t src_row_pitch,
- size_t src_slice_pitch,
- size_t dst_row_pitch,
- size_t dst_slice_pitch,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
+<div class="paragraph">
+<p>To enqueue a command to copy a 2D or 3D rectangular region from the buffer
+object identified by <em>src_buffer</em> to a 2D or 3D region in the buffer object
+identified by <em>dst_buffer</em>, call the function</p>
</div>
+<div id="clEnqueueCopyBufferRect" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyBufferRect(
+ cl_command_queue command_queue,
+ cl_mem src_buffer,
+ cl_mem dst_buffer,
+ <span class="directive">const</span> size_t* src_origin,
+ <span class="directive">const</span> size_t* dst_origin,
+ <span class="directive">const</span> size_t* region,
+ size_t src_row_pitch,
+ size_t src_slice_pitch,
+ size_t dst_row_pitch,
+ size_t dst_slice_pitch,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>command_queue</em> refers to the host command-queue in which the copy command
+will be queued.
+The OpenCL context associated with <em>command_queue</em>, <em>src_buffer</em> and
+<em>dst_buffer</em> must be the same.</p>
+</li>
+<li>
+<p><em>src_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region
+associated with <em>src_buffer</em>.
+For a 2D rectangle region, the <em>z</em> value given by <em>src_origin</em>[2] should be
+0.
+The offset in bytes is computed as <em>src_origin</em>[2] × <em>src_slice_pitch</em>
++ <em>src_origin</em>[1] × <em>src_row_pitch</em> + <em>src_origin</em>[0].</p>
+</li>
+<li>
+<p><em>dst_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region
+associated with <em>dst_buffer</em>.
+For a 2D rectangle region, the <em>z</em> value given by <em>dst_origin</em>[2] should be
+0.
+The offset in bytes is computed as <em>dst_origin</em>[2] × <em>dst_slice_pitch</em>
++ <em>dst_origin</em>[1] × <em>dst_row_pitch</em> + <em>dst_origin</em>[0].</p>
+</li>
+<li>
+<p><em>region</em> defines the (<em>width</em> in bytes, <em>height</em> in rows, <em>depth</em> in slices)
+of the 2D or 3D rectangle being copied.
+For a 2D rectangle, the <em>depth</em> value given by <em>region</em>[2] should be 1.
+The values in region cannot be 0.</p>
+</li>
+<li>
+<p><em>src_row_pitch</em> is the length of each row in bytes to be used for the memory
+region associated with <em>src_buffer</em>.
+If <em>src_row_pitch</em> is 0, <em>src_row_pitch</em> is computed as <em>region</em>[0].</p>
+</li>
+<li>
+<p><em>src_slice_pitch</em> is the length of each 2D slice in bytes to be used for the
+memory region associated with <em>src_buffer</em>.
+If <em>src_slice_pitch</em> is 0, <em>src_slice_pitch</em> is computed as <em>region</em>[1]
+× <em>src_row_pitch</em>.</p>
+</li>
+<li>
+<p><em>dst_row_pitch</em> is the length of each row in bytes to be used for the memory
+region associated with <em>dst_buffer</em>.
+If <em>dst_row_pitch</em> is 0, <em>dst_row_pitch</em> is computed as <em>region</em>[0].</p>
+</li>
+<li>
+<p><em>dst_slice_pitch</em> is the length of each 2D slice in bytes to be used for the
+memory region associated with <em>dst_buffer</em>.
+If <em>dst_slice_pitch</em> is 0, <em>dst_slice_pitch</em> is computed as <em>region</em>[1]
+× <em>dst_row_pitch</em>.</p>
+</li>
+<li>
+<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
+complete before this particular command can be executed.
+If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
+on any event to complete.
+If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0.
+If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by
+<em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be
+greater than 0.
+The events specified in <em>event_wait_list</em> act as synchronization points.
+The context associated with events in <em>event_wait_list</em> and <em>command_queue</em>
+must be the same.
+The memory associated with <em>event_wait_list</em> can be reused or freed after
+the function returns.</p>
+</li>
+<li>
+<p><em>event</em> returns an event object that identifies this particular copy command
+and can be used to query or queue a wait for this particular command to
+complete.
+<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
+application to query the status of this command or queue a wait for this
+command to complete.
+<a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> can be used instead.
+If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
+<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
+array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>enqueues a command to copy a 2D or 3D rectangular region from the buffer
-object identified by <em>src_buffer</em> to a 2D or 3D region in the buffer object
-identified by <em>dst_buffer</em>.
-Copying begins at the source offset and destination offset which are
+<p>Copying begins at the source offset and destination offset which are
computed as described below in the description for <em>src_origin</em> and
<em>dst_origin</em>.
Each byte of the region’s width is copied from the source offset to the
@@ -8726,212 +8880,135 @@
</table>
</div>
<div class="paragraph">
-<p><em>command_queue</em> refers to the host command-queue in which the copy command
-will be queued.
-The OpenCL context associated with <em>command_queue</em>, <em>src_buffer</em> and
-<em>dst_buffer</em> must be the same.</p>
-</div>
-<div class="paragraph">
-<p><em>src_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region
-associated with <em>src_buffer</em>.
-For a 2D rectangle region, the <em>z</em> value given by <em>src_origin</em>[2] should be
-0.
-The offset in bytes is computed as <em>src_origin</em>[2] × <em>src_slice_pitch</em>
-+ <em>src_origin</em>[1] × <em>src_row_pitch</em> + <em>src_origin</em>[0].</p>
-</div>
-<div class="paragraph">
-<p><em>dst_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in the memory region
-associated with <em>dst_buffer</em>.
-For a 2D rectangle region, the <em>z</em> value given by <em>dst_origin</em>[2] should be
-0.
-The offset in bytes is computed as <em>dst_origin</em>[2] × <em>dst_slice_pitch</em>
-+ <em>dst_origin</em>[1] × <em>dst_row_pitch</em> + <em>dst_origin</em>[0].</p>
-</div>
-<div class="paragraph">
-<p><em>region</em> defines the (<em>width</em> in bytes, <em>height</em> in rows, <em>depth</em> in slices)
-of the 2D or 3D rectangle being copied.
-For a 2D rectangle, the <em>depth</em> value given by <em>region</em>[2] should be 1.
-The values in region cannot be 0.</p>
-</div>
-<div class="paragraph">
-<p><em>src_row_pitch</em> is the length of each row in bytes to be used for the memory
-region associated with <em>src_buffer</em>.
-If <em>src_row_pitch</em> is 0, <em>src_row_pitch</em> is computed as <em>region</em>[0].</p>
-</div>
-<div class="paragraph">
-<p><em>src_slice_pitch</em> is the length of each 2D slice in bytes to be used for the
-memory region associated with <em>src_buffer</em>.
-If <em>src_slice_pitch</em> is 0, <em>src_slice_pitch</em> is computed as <em>region</em>[1]
-× <em>src_row_pitch</em>.</p>
-</div>
-<div class="paragraph">
-<p><em>dst_row_pitch</em> is the length of each row in bytes to be used for the memory
-region associated with <em>dst_buffer</em>.
-If <em>dst_row_pitch</em> is 0, <em>dst_row_pitch</em> is computed as <em>region</em>[0].</p>
-</div>
-<div class="paragraph">
-<p><em>dst_slice_pitch</em> is the length of each 2D slice in bytes to be used for the
-memory region associated with <em>dst_buffer</em>.
-If <em>dst_slice_pitch</em> is 0, <em>dst_slice_pitch</em> is computed as <em>region</em>[1]
-× <em>dst_row_pitch</em>.</p>
-</div>
-<div class="paragraph">
-<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
-complete before this particular command can be executed.
-If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
-on any event to complete.
-If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0.
-If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by
-<em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be
-greater than 0.
-The events specified in <em>event_wait_list</em> act as synchronization points.
-The context associated with events in <em>event_wait_list</em> and <em>command_queue</em>
-must be the same.
-The memory associated with <em>event_wait_list</em> can be reused or freed after
-the function returns.</p>
-</div>
-<div class="paragraph">
-<p><em>event</em> returns an event object that identifies this particular copy command
-and can be used to query or queue a wait for this particular command to
-complete.
-<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
-application to query the status of this command or queue a wait for this
-command to complete.
-<strong>clEnqueueBarrierWithWaitList</strong> can be used instead.
-If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
-<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
-array.</p>
-</div>
-<div class="paragraph">
-<p><strong>clEnqueueCopyBufferRect</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clEnqueueCopyBufferRect"><strong>clEnqueueCopyBufferRect</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em>,
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em>,
<em>src_buffer</em> and <em>dst_buffer</em> are not the same or if the context
associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not
the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>src_buffer</em> and <em>dst_buffer</em> are not valid
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are not valid
buffer objects.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if (<em>src_origin, region, src_row_pitch,
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if (<em>src_origin, region, src_row_pitch,
src_slice_pitch</em>) or (<em>dst_origin, region, dst_row_pitch,
dst_slice_pitch</em>) require accessing elements outside the <em>src_buffer</em>
and <em>dst_buffer</em> buffer objects respectively.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if any <em>region</em> array element is 0.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if any <em>region</em> array element is 0.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>src_row_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>src_row_pitch</em> is not 0 and is less than
<em>region</em>[0].</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>dst_row_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>dst_row_pitch</em> is not 0 and is less than
<em>region</em>[0].</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>src_slice_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>src_slice_pitch</em> is not 0 and is less than
<em>region</em>[1] × <em>src_row_pitch</em> or if <em>src_slice_pitch</em> is not 0 and
is not a multiple of <em>src_row_pitch</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>dst_slice_pitch</em> is not 0 and is less than
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>dst_slice_pitch</em> is not 0 and is less than
<em>region</em>[1] × <em>dst_row_pitch</em> or if <em>dst_slice_pitch</em> is not 0 and
is not a multiple of <em>dst_row_pitch</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer
object and <em>src_slice_pitch</em> is not equal to <em>dst_slice_pitch</em> and
<em>src_row_pitch</em> is not equal to <em>dst_row_pitch</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_MEM_COPY_OVERLAP if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer
+<p><a href="#CL_MEM_COPY_OVERLAP"><code>CL_​MEM_​COPY_​OVERLAP</code></a> if <em>src_buffer</em> and <em>dst_buffer</em> are the same buffer
or sub-buffer object and the source and destination regions overlap or
if <em>src_buffer</em> and <em>dst_buffer</em> are different sub-buffers of the same
associated buffer object and they overlap.
-Refer to <a href="#check-copy-overlap">CL_MEM_COPY_OVERLAP</a> for details on how
-to determine if source and destination regions overlap.</p>
+Refer to <a href="#check-copy-overlap">Checking for Memory Copy Overlap</a> for
+details on how to determine if source and destination regions overlap.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>src_buffer</em> is a sub-buffer object
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>src_buffer</em> is a sub-buffer object
and <em>offset</em> specified when the sub-buffer object is created is not
-aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated
+aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated
with <em>queue</em>.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>dst_buffer</em> is a sub-buffer object
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>dst_buffer</em> is a sub-buffer object
and <em>offset</em> specified when the sub-buffer object is created is not
-aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated
+aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated
with <em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>src_buffer</em> or <em>dst_buffer</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_filling_buffer_objects">5.2.3. Filling Buffer Objects</h4>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueFillBuffer(cl_command_queue command_queue,
- cl_mem buffer,
- <span class="directive">const</span> <span class="directive">void</span> *pattern,
- size_t pattern_size,
- size_t offset,
- size_t size,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to fill a buffer object with a pattern of a given pattern
-size.
-The usage information which indicates whether the memory object can be read
-or written by a kernel and/or the host and is given by the cl_mem_flags
-argument value specified when <em>buffer</em> is created is ignored by
-<strong>clEnqueueFillBuffer</strong>.</p>
+<p>To enqueue a command to fill a buffer object with a pattern of a given
+pattern size, call the function</p>
</div>
-<div class="paragraph">
+<div id="clEnqueueFillBuffer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueFillBuffer(
+ cl_command_queue command_queue,
+ cl_mem buffer,
+ <span class="directive">const</span> <span class="directive">void</span>* pattern,
+ size_t pattern_size,
+ size_t offset,
+ size_t size,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> refers to the host command-queue in which the fill command
will be queued.
The OpenCL context associated with <em>command_queue</em> and <em>buffer</em> must be the
same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>buffer</em> is a valid buffer object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>pattern</em> is a pointer to the data pattern of size <em>pattern_size</em> in bytes.
<em>pattern</em> will be used to fill a region in <em>buffer</em> starting at <em>offset</em> and
is <em>size</em> bytes in size.
@@ -8946,16 +9023,16 @@
floating-point vector data type supported by the OpenCL device.
The memory associated with <em>pattern</em> can be reused or freed after the
function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>offset</em> is the location in bytes of the region being filled in <em>buffer</em> and
must be a multiple of <em>pattern_size</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>size</em> is the size in bytes of region being filled in <em>buffer</em> and must be a
multiple of <em>pattern_size</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -8969,135 +9046,152 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular command and
can be used to query or queue a wait for this particular command to
complete.
<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
application to query the status of this command or queue a wait for this
command to complete.
-<strong>clEnqueueBarrierWithWaitList</strong> can be used instead.
+<a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> can be used instead.
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueFillBuffer</strong> returns CL_SUCCESS if the function is executed
+<p>The usage information which indicates whether the memory object can be read
+or written by a kernel and/or the host and is given by the cl_mem_flags
+argument value specified when <em>buffer</em> is created is ignored by
+<a href="#clEnqueueFillBuffer"><strong>clEnqueueFillBuffer</strong></a>.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clEnqueueFillBuffer"><strong>clEnqueueFillBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em> and
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em> and
<em>buffer</em> are not the same or if the context associated with
<em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>buffer</em> is not a valid buffer object.</p>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>offset</em> or <em>offset</em> + <em>size</em> require accessing
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>offset</em> or <em>offset</em> + <em>size</em> require accessing
elements outside the <em>buffer</em> buffer object respectively.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>pattern</em> is <code>NULL</code> or if <em>pattern_size</em> is 0 or if
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>pattern</em> is <code>NULL</code> or if <em>pattern_size</em> is 0 or if
<em>pattern_size</em> is not one of { 1, 2, 4, 8, 16, 32, 64, 128 }.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>offset</em> and <em>size</em> are not a multiple of
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>offset</em> and <em>size</em> are not a multiple of
<em>pattern_size</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>buffer</em> is a sub-buffer object and
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and
offset specified when the sub-buffer object is created is not aligned to
-CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with <em>queue</em>.</p>
+<a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>buffer</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_mapping_buffer_objects">5.2.4. Mapping Buffer Objects</h4>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c"><span class="directive">void</span>* clEnqueueMapBuffer(cl_command_queue command_queue,
- cl_mem buffer,
- cl_bool blocking_map,
- cl_map_flags map_flags,
- size_t offset,
- size_t size,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event,
- cl_int *errcode_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to map a region of the buffer object given by <em>buffer</em>
-into the host address space and returns a pointer to this mapped region.</p>
+<p>To enqueue a command to map a region of the buffer object given by <em>buffer</em>
+into the host address space and returns a pointer to this mapped region,
+call the function</p>
</div>
-<div class="paragraph">
+<div id="clEnqueueMapBuffer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span>* clEnqueueMapBuffer(
+ cl_command_queue command_queue,
+ cl_mem buffer,
+ cl_bool blocking_map,
+ cl_map_flags map_flags,
+ size_t offset,
+ size_t size,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event,
+ cl_int* errcode_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> must be a valid host command-queue.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>blocking_map</em> indicates if the map operation is <em>blocking</em> or
<em>non-blocking</em>.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>If <em>blocking_map</em> is CL_TRUE, <strong>clEnqueueMapBuffer</strong> does not return until the
+<p>If <em>blocking_map</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>, <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> does not return until the
specified region in <em>buffer</em> is mapped into the host address space and the
application can access the contents of the mapped region using the pointer
-returned by <strong>clEnqueueMapBuffer</strong>.</p>
+returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>.</p>
</div>
<div class="paragraph">
-<p>If <em>blocking_map</em> is CL_FALSE i.e. map operation is non-blocking, the
-pointer to the mapped region returned by <strong>clEnqueueMapBuffer</strong> cannot be used
+<p>If <em>blocking_map</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> i.e. map operation is non-blocking, the
+pointer to the mapped region returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> cannot be used
until the map command has completed.
The <em>event</em> argument returns an event object which can be used to query the
execution status of the map command.
When the map command is completed, the application can access the contents
-of the mapped region using the pointer returned by <strong>clEnqueueMapBuffer</strong>.</p>
+of the mapped region using the pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a>.</p>
</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
<p><em>map_flags</em> is a bit-field and is described in the
<a href="#memory-map-flags-table">Memory Map Flags</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>buffer</em> is a valid buffer object.
The OpenCL context associated with <em>command_queue</em> and <em>buffer</em> must be the
same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>offset</em> and <em>size</em> are the offset in bytes and the size of the region in
the buffer object that is being mapped.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -9111,8 +9205,8 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular command and
can be used to query or queue a wait for this particular command to
complete.
@@ -9122,14 +9216,16 @@
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>errcode_ret</em> will return an appropriate error code.
If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueMapBuffer</strong> will return a pointer to the mapped region.
-The <em>errcode_ret</em> is set to CL_SUCCESS.</p>
+<p><a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> will return a pointer to the mapped region.
+The <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a>.</p>
</div>
<div class="paragraph">
<p>A <code>NULL</code> pointer is returned otherwise with one of the following error
@@ -9138,66 +9234,66 @@
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if context associated with <em>command_queue</em> and
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if context associated with <em>command_queue</em> and
<em>buffer</em> are not the same or if the context associated with
<em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>buffer</em> is not a valid buffer object.</p>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>buffer</em> is not a valid buffer object.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if region being mapped given by (<em>offset</em>, <em>size</em>) is
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if region being mapped given by (<em>offset</em>, <em>size</em>) is
out of bounds or if <em>size</em> is 0 or if values specified in <em>map_flags</em>
are not valid.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>buffer</em> is a sub-buffer object and
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>buffer</em> is a sub-buffer object and
<em>offset</em> specified when the sub-buffer object is created is not aligned
-to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for the device associated with
+to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for the device associated with
<em>queue</em>.</p>
</li>
<li>
-<p>CL_MAP_FAILURE if there is a failure to map the requested region into
+<p><a href="#CL_MAP_FAILURE"><code>CL_​MAP_​FAILURE</code></a> if there is a failure to map the requested region into
the host address space.
This error cannot occur for buffer objects created with
-CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR.</p>
+<a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> or <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a>.</p>
</li>
<li>
-<p>CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the map operation is
+<p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_​EXEC_​STATUS_​ERROR_​FOR_​EVENTS_​IN_​WAIT_​LIST</code></a> if the map operation is
blocking and the execution status of any of the events in
<em>event_wait_list</em> is a negative integer value.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>buffer</em>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if buffer_ has been created with
-CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_NO_ACCESS and CL_MAP_READ is set
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <em>buffer</em> has been created with
+<a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> and <a href="#CL_MAP_READ"><code>CL_​MAP_​READ</code></a> is set
in <em>map_flags</em> or if <em>buffer</em> has been created with
-CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS and CL_MAP_WRITE or
-CL_MAP_WRITE_INVALIDATE_REGION is set in <em>map_flags</em>.</p>
+<a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> and <a href="#CL_MAP_WRITE"><code>CL_​MAP_​WRITE</code></a> or
+<a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_​MAP_​WRITE_​INVALIDATE_​REGION</code></a> is set in <em>map_flags</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if mapping would lead to overlapping regions being
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if mapping would lead to overlapping regions being
mapped for writing.</p>
</li>
</ul>
@@ -9208,29 +9304,29 @@
The result of a memory access outside this region is undefined.</p>
</div>
<div class="paragraph">
-<p>If the buffer object is created with CL_MEM_USE_HOST_PTR set in <em>mem_flags</em>,
+<p>If the buffer object is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> set in <em>mem_flags</em>,
the following will be true:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>The <em>host_ptr</em> specified in <strong>clCreateBuffer</strong> to contain the latest bits
-in the region being mapped when the <strong>clEnqueueMapBuffer</strong> command has
+<p>The <em>host_ptr</em> specified in <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> to contain the latest bits
+in the region being mapped when the <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> command has
completed.</p>
</li>
<li>
-<p>The pointer value returned by <strong>clEnqueueMapBuffer</strong> will be derived from
+<p>The pointer value returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> will be derived from
the <em>host_ptr</em> specified when the buffer object is created.</p>
</li>
</ul>
</div>
<div class="paragraph">
-<p>Mapped buffer objects are unmapped using <strong>clEnqueueUnmapMemObject</strong>.
+<p>Mapped buffer objects are unmapped using <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>.
This is described in <a href="#unmapping-mapped-memory">Unmapping Mapped Memory
Objects</a>.</p>
</div>
<table id="memory-map-flags-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 13. List of supported cl_map_flags values</caption>
+<caption class="title">Table 13. List of supported map flag values</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
@@ -9243,39 +9339,41 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MAP_READ</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAP_READ"></a><a href="#CL_MAP_READ"><code>CL_​MAP_​READ</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the region being mapped in the memory object is
being mapped for reading.</p>
-<p class="tableblock"> The pointer returned by <strong>clEnqueueMapBuffer</strong> (<strong>clEnqueueMapImage</strong>) is
+<p class="tableblock"> The pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) is
guaranteed to contain the latest bits in the region being mapped when
- the <strong>clEnqueueMapBuffer</strong> (<strong>clEnqueueMapImage</strong>) command has completed.</p></td>
+ the <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) command has completed.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MAP_WRITE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAP_WRITE"></a><a href="#CL_MAP_WRITE"><code>CL_​MAP_​WRITE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the region being mapped in the memory object is
being mapped for writing.</p>
-<p class="tableblock"> The pointer returned by <strong>clEnqueueMapBuffer</strong> (<strong>clEnqueueMapImage</strong>) is
+<p class="tableblock"> The pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) is
guaranteed to contain the latest bits in the region being mapped when
- the <strong>clEnqueueMapBuffer</strong> (<strong>clEnqueueMapImage</strong>) command has completed</p></td>
+ the <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) command has completed</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MAP_WRITE_INVALIDATE_REGION</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MAP_WRITE_INVALIDATE_REGION"></a><a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_​MAP_​WRITE_​INVALIDATE_​REGION</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag specifies that the region being mapped in the memory object is
being mapped for writing.</p>
<p class="tableblock"> The contents of the region being mapped are to be discarded.
This is typically the case when the region being mapped is overwritten
by the host.
This flag allows the implementation to no longer guarantee that the
- pointer returned by <strong>clEnqueueMapBuffer</strong> (<strong>clEnqueueMapImage</strong>) contains
+ pointer returned by <a href="#clEnqueueMapBuffer"><strong>clEnqueueMapBuffer</strong></a> (<a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>) contains
the latest bits in the region being mapped which can be a significant
performance enhancement.</p>
-<p class="tableblock"> CL_MAP_READ or CL_MAP_WRITE and CL_MAP_WRITE_INVALIDATE_REGION are
+<p class="tableblock"> <a href="#CL_MAP_READ"><code>CL_​MAP_​READ</code></a> or <a href="#CL_MAP_WRITE"><code>CL_​MAP_​WRITE</code></a> and <a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_​MAP_​WRITE_​INVALIDATE_​REGION</code></a> are
mutually exclusive.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
+</div>
+</div>
<div class="sect2">
<h3 id="_image_objects">5.3. Image Objects</h3>
<div class="paragraph">
@@ -9287,51 +9385,35 @@
</div>
<div class="sect3">
<h4 id="_creating_image_objects">5.3.1. Creating Image Objects</h4>
+<div class="openblock">
+<div class="content">
<div class="paragraph">
<p>A <strong>1D image</strong>, <strong>1D image buffer</strong>, <strong>1D image array</strong>, <strong>2D image</strong>, <strong>2D image
array</strong> and <strong>3D image object</strong> can be created using the following function</p>
</div>
-<div class="listingblock">
+<div id="clCreateImage" class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_mem clCreateImage(cl_context context,
- cl_mem_flags flags,
- <span class="directive">const</span> cl_image_format *image_format,
- <span class="directive">const</span> cl_image_desc *image_desc,
- <span class="directive">void</span> *host_ptr,
- cl_int *errcode_ret)</code></pre>
+<pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreateImage(
+ cl_context context,
+ cl_mem_flags flags,
+ <span class="directive">const</span> cl_image_format* image_format,
+ <span class="directive">const</span> cl_image_desc* image_desc,
+ <span class="directive">void</span>* host_ptr,
+ cl_int* errcode_ret);</code></pre>
</div>
</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
<p><em>context</em> is a valid OpenCL context on which the image object is to be
created.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>flags</em> is a bit-field that is used to specify allocation and usage
information about the image memory object being created and is described in
the <a href="#memory-flags-table">Memory Flags</a> table.</p>
-</div>
-<div class="paragraph">
-<p>For all image types except CL_MEM_OBJECT_IMAGE1D_BUFFER, if value specified
-for <em>flags</em> is 0, the default is used which is CL_MEM_READ_WRITE.</p>
-</div>
-<div class="paragraph">
-<p>For CL_MEM_OBJECT_IMAGE1D_BUFFER image type, or an image created from
-another memory object (image or buffer), if the CL_MEM_READ_WRITE,
-CL_MEM_READ_ONLY or CL_MEM_WRITE_ONLY values are not specified in <em>flags</em>,
-they are inherited from the corresponding memory access qualifiers associated
-with <em>mem_object</em>.
-The CL_MEM_USE_HOST_PTR, CL_MEM_ALLOC_HOST_PTR and CL_MEM_COPY_HOST_PTR
-values cannot be specified in <em>flags</em> but are inherited from the
-corresponding memory access qualifiers associated with <em>mem_object</em>.
-If CL_MEM_COPY_HOST_PTR is specified in the memory access qualifier values
-associated with <em>mem_object</em> it does not imply any additional copies when
-the image is created from <em>mem_object</em>.
-If the CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY or
-CL_MEM_HOST_NO_ACCESS values are not specified in <em>flags</em>, they are
-inherited from the corresponding memory access qualifiers associated with
-<em>mem_object</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image_format</em> is a pointer to a structure that describes format properties
of the image to be allocated.
A 1D image buffer or 2D image can be created from a buffer by specifying a
@@ -9340,20 +9422,43 @@
image object in the <em>image_desc</em>→_mem_object_.
Refer to <a href="#image-format-descriptor">Image Format Descriptor</a> for a detailed
description of the image format descriptor.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image_desc</em> is a pointer to a structure that describes type and dimensions
of the image to be allocated.
Refer to <a href="#image-descriptor">Image Descriptor</a> for a detailed description
of the image descriptor.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>host_ptr</em> is a pointer to the image data that may already be allocated by
the application.
It is only used to initialize the image, and can be freed after the call to
-<strong>clCreateImage</strong>.
+<a href="#clCreateImage"><strong>clCreateImage</strong></a>.
Refer to table below for a description of how large the buffer that
<em>host_ptr</em> points to must be.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>For all image types except <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_​MEM_​OBJECT_​IMAGE1D_​BUFFER</code></a>, if value specified
+for <em>flags</em> is 0, the default is used which is <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a>.</p>
+</div>
+<div class="paragraph">
+<p>For <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_​MEM_​OBJECT_​IMAGE1D_​BUFFER</code></a> image type, or an image created from
+another memory object (image or buffer), if the <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a>,
+<a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a> or <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a> values are not specified in <em>flags</em>,
+they are inherited from the corresponding memory access qualifiers associated
+with <em>mem_object</em>.
+The <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a> and <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a>
+values cannot be specified in <em>flags</em> but are inherited from the
+corresponding memory access qualifiers associated with <em>mem_object</em>.
+If <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> is specified in the memory access qualifier values
+associated with <em>mem_object</em> it does not imply any additional copies when
+the image is created from <em>mem_object</em>.
+If the <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a>, <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> or
+<a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> values are not specified in <em>flags</em>, they are
+inherited from the corresponding memory access qualifiers associated with
+<em>mem_object</em>.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
@@ -9368,27 +9473,27 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_OBJECT_IMAGE1D</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE1D"></a><a href="#CL_MEM_OBJECT_IMAGE1D"><code>CL_​MEM_​OBJECT_​IMAGE1D</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_row_pitch</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_OBJECT_IMAGE1D_BUFFER</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE1D_BUFFER"></a><a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_​MEM_​OBJECT_​IMAGE1D_​BUFFER</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_row_pitch</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_OBJECT_IMAGE2D</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE2D"></a><a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_​MEM_​OBJECT_​IMAGE2D</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_row_pitch × image_height</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_OBJECT_IMAGE3D</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE3D"></a><a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_​MEM_​OBJECT_​IMAGE3D</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_slice_pitch × image_depth</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_OBJECT_IMAGE1D_ARRAY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE1D_ARRAY"></a><a href="#CL_MEM_OBJECT_IMAGE1D_ARRAY"><code>CL_​MEM_​OBJECT_​IMAGE1D_​ARRAY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_slice_pitch × image_array_size</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_MEM_OBJECT_IMAGE2D_ARRAY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_MEM_OBJECT_IMAGE2D_ARRAY"></a><a href="#CL_MEM_OBJECT_IMAGE2D_ARRAY"><code>CL_​MEM_​OBJECT_​IMAGE2D_​ARRAY</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">≥ image_slice_pitch × image_array_size</p></td>
</tr>
</tbody>
@@ -9424,8 +9529,8 @@
If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
</div>
<div class="paragraph">
-<p><strong>clCreateImage</strong> returns a valid non-zero image object created and the
-<em>errcode_ret</em> is set to CL_SUCCESS if the image object is created
+<p><a href="#clCreateImage"><strong>clCreateImage</strong></a> returns a valid non-zero image object created and the
+<em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the image object is created
successfully.
Otherwise, it returns a <code>NULL</code> value with one of the following error values
returned in <em>errcode_ret</em>:</p>
@@ -9433,142 +9538,184 @@
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid context.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values specified in <em>flags</em> are not valid.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values specified in <em>flags</em> are not valid.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if values specified in <em>image_format</em>
+<p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_​INVALID_​IMAGE_​FORMAT_​DESCRIPTOR</code></a> if values specified in <em>image_format</em>
are not valid or if <em>image_format</em> is <code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if a 2D image is created from a
+<p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_​INVALID_​IMAGE_​FORMAT_​DESCRIPTOR</code></a> if a 2D image is created from a
buffer and the row pitch and base address alignment does not follow the
rules described for creating a 2D image from a buffer.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if a 2D image is created from a 2D
+<p><a href="#CL_INVALID_IMAGE_FORMAT_DESCRIPTOR"><code>CL_​INVALID_​IMAGE_​FORMAT_​DESCRIPTOR</code></a> if a 2D image is created from a 2D
image object and the rules described above are not followed.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_DESCRIPTOR if values specified in <em>image_desc</em> are not
+<p><a href="#CL_INVALID_IMAGE_DESCRIPTOR"><code>CL_​INVALID_​IMAGE_​DESCRIPTOR</code></a> if values specified in <em>image_desc</em> are not
valid or if <em>image_desc</em> is <code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_SIZE if image dimensions specified in <em>image_desc</em>
+<p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_​INVALID_​IMAGE_​SIZE</code></a> if image dimensions specified in <em>image_desc</em>
exceed the maximum image dimensions described in the
<a href="#device-queries-table">Device Queries</a> table for all devices
-in_context_.</p>
+in <em>context</em>.</p>
</li>
<li>
-<p>CL_INVALID_HOST_PTR if <em>host_ptr</em> is <code>NULL</code> and CL_MEM_USE_HOST_PTR or
-CL_MEM_COPY_HOST_PTR are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code>
-but CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in <em>flags</em>.</p>
+<p><a href="#CL_INVALID_HOST_PTR"><code>CL_​INVALID_​HOST_​PTR</code></a> if <em>host_ptr</em> is <code>NULL</code> and <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> or
+<a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code>
+but <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a> or <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> are not set in <em>flags</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if an image is being created from another memory object
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if an image is being created from another memory object
(buffer or image) under one of the following circumstances: 1)
-<em>mem_object</em> was created with CL_MEM_WRITE_ONLY and <em>flags</em> specifies
-CL_MEM_READ_WRITE or CL_MEM_READ_ONLY, 2) <em>mem_object</em> was created with
-CL_MEM_READ_ONLY and <em>flags</em> specifies CL_MEM_READ_WRITE or
-CL_MEM_WRITE_ONLY, 3) <em>flags</em> specifies CL_MEM_USE_HOST_PTR or
-CL_MEM_ALLOC_HOST_PTR or CL_MEM_COPY_HOST_PTR.</p>
+<em>mem_object</em> was created with <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a> and <em>flags</em> specifies
+<a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> or <a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a>, 2) <em>mem_object</em> was created with
+<a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a> and <em>flags</em> specifies <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> or
+<a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a>, 3) <em>flags</em> specifies <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> or
+<a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a> or <a href="#CL_MEM_COPY_HOST_PTR"><code>CL_​MEM_​COPY_​HOST_​PTR</code></a>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if an image is being created from another memory object
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if an image is being created from another memory object
(buffer or image) and <em>mem_object</em> object was created with
-CL_MEM_HOST_WRITE_ONLY and <em>flags</em> specifies CL_MEM_HOST_READ_ONLY, or
-if <em>mem_object</em> was created with CL_MEM_HOST_READ_ONLY and <em>flags</em>
-specifies CL_MEM_HOST_WRITE_ONLY, or if <em>mem_object</em> was created with
-CL_MEM_HOST_NO_ACCESS and_flags_ specifies CL_MEM_HOST_READ_ONLY or
-CL_MEM_HOST_WRITE_ONLY.</p>
+<a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> and <em>flags</em> specifies <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a>, or
+if <em>mem_object</em> was created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> and <em>flags</em>
+specifies <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a>, or if <em>mem_object</em> was created with
+<a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> and_flags_ specifies <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> or
+<a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a>.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_NOT_SUPPORTED if the <em>image_format</em> is not supported.</p>
+<p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED</code></a> if the <em>image_format</em> is not supported.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for image object.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if there are no devices in <em>context</em> that support
-images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the
-<a href="#device-queries-table">Device Queries</a> table is CL_FALSE).</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if there are no devices in <em>context</em> that support
+images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> specified in the
+<a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>).</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
+</div>
+</div>
<div class="sect4">
<h5 id="image-format-descriptor">Image Format Descriptor</h5>
-<div class="paragraph">
-<p>The image format descriptor structure is defined as</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_image_format {
- cl_channel_order image_channel_order;
- cl_channel_type image_channel_data_type;
+<div class="paragraph">
+<p>The <strong>cl_image_format</strong> image format descriptor structure describes an image
+format, and is defined as:</p>
+</div>
+<div id="cl_image_format" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_image_format {
+ cl_channel_order image_channel_order;
+ cl_channel_type image_channel_data_type;
} cl_image_format;</code></pre>
</div>
</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
<p><code>image_channel_order</code> specifies the number of channels and the channel
layout i.e. the memory layout in which channels are stored in the image.
Valid values are described in the <a href="#image-channel-order-table">Image Channel
Order</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><code>image_channel_data_type</code> describes the size of the channel data type.
The list of supported values is described in the
<a href="#image-channel-data-types-table">Image Channel Data Types</a> table.
The number of bits per element determined by the <code>image_channel_data_type</code>
and <code>image_channel_order</code> must be a power of two.</p>
+</li>
+</ul>
</div>
<table id="image-channel-order-table" class="tableblock frame-all grid-all stretch">
<caption class="title">Table 14. List of supported Image Channel Order Values</caption>
<colgroup>
-<col style="width: 100%;">
+<col style="width: 50%;">
+<col style="width: 50%;">
</colgroup>
<thead>
<tr>
-<th class="tableblock halign-left valign-top">Enum values that can be specified in channel_order</th>
+<th class="tableblock halign-left valign-top">Image Channel Order</th>
+<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_R</strong>, <strong>CL_Rx</strong> or <strong>CL_A</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_R"></a><a href="#CL_R"><code>CL_​R</code></a>, <a id="CL_A"></a><a href="#CL_A"><code>CL_​A</code></a>,</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Single channel image formats where the single channel represents a <code>RED</code> or <code>ALPHA</code> component.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_INTENSITY</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_DEPTH"></a><a href="#CL_DEPTH"><code>CL_​DEPTH</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A single channel image format where the single channel represents a <code>DEPTH</code> component.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_LUMINANCE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_LUMINANCE"></a><a href="#CL_LUMINANCE"><code>CL_​LUMINANCE</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A single channel image format where the single channel represents a <code>LUMINANCE</code> value.
+ The <code>LUMINANCE</code> value is replicated into the <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_DEPTH</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_INTENSITY"></a><a href="#CL_INTENSITY"><code>CL_​INTENSITY</code></a>,</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A single channel image format where the single channel represents an <code>INTENSITY</code> value.
+ The <code>INTENSITY</code> value is replicated into the <code>RED</code>, <code>GREEN</code>, <code>BLUE</code>, and <code>ALPHA</code> components.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_RG</strong>, <strong>CL_RGx</strong> or <strong>CL_RA</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RG"></a><a href="#CL_RG"><code>CL_​RG</code></a>, <a id="CL_RA"></a><a href="#CL_RA"><code>CL_​RA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Two channel image formats.
+ The first channel always represents a <code>RED</code> component.
+ The second channel represents a <code>GREEN</code> component or an <code>ALPHA</code> component.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_RGB</strong> or <strong>CL_RGBx</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_Rx"></a><a href="#CL_Rx"><code>CL_​Rx</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A two channel image format, where the first channel represents a <code>RED</code> component and the second channel is ignored.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_RGBA</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGB"></a><a href="#CL_RGB"><code>CL_​RGB</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A three channel image format, where the three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_sRGB</strong>, <strong>CL_sRGBx</strong>, <strong>CL_sRGBA</strong>, or <strong>CL_sBGRA</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGx"></a><a href="#CL_RGx"><code>CL_​RGx</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A three channel image format, where the first two channels represent <code>RED</code> and <code>GREEN</code> components and the third channel is ignored.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_ARGB</strong>, <strong>CL_BGRA</strong>, or <strong>CL_ABGR</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGBA"></a><a href="#CL_RGBA"><code>CL_​RGBA</code></a>, <a id="CL_ARGB"></a><a href="#CL_ARGB"><code>CL_​ARGB</code></a>, <a id="CL_BGRA"></a><a href="#CL_BGRA"><code>CL_​BGRA</code></a>, <a id="CL_ABGR"></a><a href="#CL_ABGR"><code>CL_​ABGR</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Four channel image formats, where the four channels represent <code>RED</code>, <code>GREEN</code>, <code>BLUE</code>, and <code>ALPHA</code> components.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_RGBx"></a><a href="#CL_RGBx"><code>CL_​RGBx</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A four channel image format, where the first three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components and the fourth channel is ignored.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_sRGB"></a><a href="#CL_sRGB"><code>CL_​sRGB</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A three channel image format, where the three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components in the sRGB color space.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_sRGBA"></a><a href="#CL_sRGBA"><code>CL_​sRGBA</code></a>, <a id="CL_sBGRA"></a><a href="#CL_sBGRA"><code>CL_​sBGRA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Four channel image formats, where the first three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components in the sRGB color space.
+ The fourth channel represents an <code>ALPHA</code> component.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_sRGBx"></a><a href="#CL_sRGBx"><code>CL_​sRGBx</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A four channel image format, where the three channels represent <code>RED</code>, <code>GREEN</code>, and <code>BLUE</code> components in the sRGB color space.
+ The fourth channel is ignored.</p></td>
</tr>
</tbody>
</table>
@@ -9586,79 +9733,79 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_SNORM_INT8</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SNORM_INT8"></a><a href="#CL_SNORM_INT8"><code>CL_​SNORM_​INT8</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized signed 8-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_SNORM_INT16</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SNORM_INT16"></a><a href="#CL_SNORM_INT16"><code>CL_​SNORM_​INT16</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized signed 16-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNORM_INT8</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT8"></a><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized unsigned 8-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNORM_INT16</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT16"></a><a href="#CL_UNORM_INT16"><code>CL_​UNORM_​INT16</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a normalized unsigned 16-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNORM_SHORT_565</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_SHORT_565"></a><a href="#CL_UNORM_SHORT_565"><code>CL_​UNORM_​SHORT_​565</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized 5-6-5 3-channel RGB image.
- The channel order must be CL_RGB or CL_RGBx.</p></td>
+ The channel order must be <a href="#CL_RGB"><code>CL_​RGB</code></a> or <a href="#CL_RGBx"><code>CL_​RGBx</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNORM_SHORT_555</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_SHORT_555"></a><a href="#CL_UNORM_SHORT_555"><code>CL_​UNORM_​SHORT_​555</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized x-5-5-5 4-channel xRGB image.
- The channel order must be CL_RGB or CL_RGBx.</p></td>
+ The channel order must be <a href="#CL_RGB"><code>CL_​RGB</code></a> or <a href="#CL_RGBx"><code>CL_​RGBx</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNORM_INT_101010</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT_101010"></a><a href="#CL_UNORM_INT_101010"><code>CL_​UNORM_​INT_​101010</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized x-10-10-10 4-channel xRGB image.
- The channel order must be CL_RGB or CL_RGBx.</p></td>
+ The channel order must be <a href="#CL_RGB"><code>CL_​RGB</code></a> or <a href="#CL_RGBx"><code>CL_​RGBx</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNORM_INT_101010_2</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNORM_INT_101010_2"></a><a href="#CL_UNORM_INT_101010_2"><code>CL_​UNORM_​INT_​101010_​2</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Represents a normalized 10-10-10-2 four-channel RGBA image.
- The channel order must be CL_RGBA.</p></td>
+ The channel order must be <a href="#CL_RGBA"><code>CL_​RGBA</code></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_SIGNED_INT8</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SIGNED_INT8"></a><a href="#CL_SIGNED_INT8"><code>CL_​SIGNED_​INT8</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized signed 8-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_SIGNED_INT16</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SIGNED_INT16"></a><a href="#CL_SIGNED_INT16"><code>CL_​SIGNED_​INT16</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized signed 16-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_SIGNED_INT32</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_SIGNED_INT32"></a><a href="#CL_SIGNED_INT32"><code>CL_​SIGNED_​INT32</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized signed 32-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNSIGNED_INT8</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNSIGNED_INT8"></a><a href="#CL_UNSIGNED_INT8"><code>CL_​UNSIGNED_​INT8</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized unsigned 8-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNSIGNED_INT16</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNSIGNED_INT16"></a><a href="#CL_UNSIGNED_INT16"><code>CL_​UNSIGNED_​INT16</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized unsigned 16-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_UNSIGNED_INT32</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_UNSIGNED_INT32"></a><a href="#CL_UNSIGNED_INT32"><code>CL_​UNSIGNED_​INT32</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is an unnormalized unsigned 32-bit integer value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_HALF_FLOAT</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_HALF_FLOAT"></a><a href="#CL_HALF_FLOAT"><code>CL_​HALF_​FLOAT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a 16-bit half-float value</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_FLOAT</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_FLOAT"></a><a href="#CL_FLOAT"><code>CL_​FLOAT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each channel component is a single precision floating-point value</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>For example, to specify a normalized unsigned 8-bit / channel RGBA image,
-<code>image_channel_order</code> = CL_RGBA, and <code>image_channel_data_type</code> =
-CL_UNORM_INT8.
+<code>image_channel_order</code> = <a href="#CL_RGBA"><code>CL_​RGBA</code></a>, and <code>image_channel_data_type</code> =
+<a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a>.
The memory layout of this image format is described below:</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 60%;">
@@ -9701,8 +9848,8 @@
</tbody>
</table>
<div class="paragraph">
-<p>Similar, if <code>image_channel_order</code> = CL_RGBA and <code>image_channel_data_type</code> =
-CL_SIGNED_INT16, the memory layout of this image format is described below:</p>
+<p>Similar, if <code>image_channel_order</code> = <a href="#CL_RGBA"><code>CL_​RGBA</code></a> and <code>image_channel_data_type</code> =
+<a href="#CL_SIGNED_INT16"><code>CL_​SIGNED_​INT16</code></a>, the memory layout of this image format is described below:</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 60%;">
<colgroup>
@@ -9744,20 +9891,20 @@
</tbody>
</table>
<div class="paragraph">
-<p><code>image_channel_data_type</code> values of CL_UNORM_SHORT_565, CL_UNORM_SHORT_555,
-CL_UNORM_INT_101010 and CL_UNORM_INT_101010_2 are special cases of packed
+<p><code>image_channel_data_type</code> values of <a href="#CL_UNORM_SHORT_565"><code>CL_​UNORM_​SHORT_​565</code></a>, <a href="#CL_UNORM_SHORT_555"><code>CL_​UNORM_​SHORT_​555</code></a>,
+<a href="#CL_UNORM_INT_101010"><code>CL_​UNORM_​INT_​101010</code></a>, and <a href="#CL_UNORM_INT_101010_2"><code>CL_​UNORM_​INT_​101010_​2</code></a> are special cases of packed
image formats where the channels of each element are packed into a single
unsigned short or unsigned int.
For these special packed image formats, the channels are normally packed
with the first channel in the most significant bits of the bitfield, and
successive channels occupying progressively less significant locations.
-For CL_UNORM_SHORT_565, R is in bits 15:11, G is in bits 10:5 and B is in
+For <a href="#CL_UNORM_SHORT_565"><code>CL_​UNORM_​SHORT_​565</code></a>, R is in bits 15:11, G is in bits 10:5 and B is in
bits 4:0.
-For CL_UNORM_SHORT_555, bit 15 is undefined, R is in bits 14:10, G in bits
+For <a href="#CL_UNORM_SHORT_555"><code>CL_​UNORM_​SHORT_​555</code></a>, bit 15 is undefined, R is in bits 14:10, G in bits
9:5 and B in bits 4:0.
-For CL_UNORM_INT_101010, bits 31:30 are undefined, R is in bits 29:20, G in
+For <a href="#CL_UNORM_INT_101010"><code>CL_​UNORM_​INT_​101010</code></a>, bits 31:30 are undefined, R is in bits 29:20, G in
bits 19:10 and B in bits 9:0.
-For CL_UNORM_INT_101010_2, R is in bits 31:22, G in bits 21:12, B in bits
+For <a href="#CL_UNORM_INT_101010_2"><code>CL_​UNORM_​INT_​101010_​2</code></a>, R is in bits 31:22, G in bits 21:12, B in bits
11:2 and A in bits 1:0.</p>
</div>
<div class="paragraph">
@@ -9765,67 +9912,78 @@
number of bits in <code>image_channel_data_type</code>.
If the image format specified by <code>image_channel_order</code>, and
<code>image_channel_data_type</code> cannot be supported by the OpenCL implementation,
-then the call to <strong>clCreateImage</strong> will return a <code>NULL</code> memory object.</p>
+then the call to <a href="#clCreateImage"><strong>clCreateImage</strong></a> will return a <code>NULL</code> memory object.</p>
+</div>
+</div>
</div>
</div>
<div class="sect4">
<h5 id="image-descriptor">Image Descriptor</h5>
-<div class="paragraph">
-<p>The image descriptor structure describes the type and dimensions of the
-image or image array and is defined as:</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_image_desc {
- cl_mem_object_type image_type,
- size_t image_width;
- size_t image_height;
- size_t image_depth;
- size_t image_array_size;
- size_t image_row_pitch;
- size_t image_slice_pitch;
- cl_uint num_mip_levels;
- cl_uint num_samples;
- cl_mem mem_object;
+<div class="paragraph">
+<p>The <strong>cl_image_desc</strong> image descriptor structure describes the type and
+dimensions of an image or image array, and is defined as:</p>
+</div>
+<div id="cl_image_desc" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">typedef</span> <span class="keyword">struct</span> cl_image_desc {
+ cl_mem_object_type image_type;
+ size_t image_width;
+ size_t image_height;
+ size_t image_depth;
+ size_t image_array_size;
+ size_t image_row_pitch;
+ size_t image_slice_pitch;
+ cl_uint num_mip_levels;
+ cl_uint num_samples;
+ <span class="preprocessor">#ifdef</span> __GNUC__
+ __extension__ <span class="comment">/* Prevents warnings about anonymous union in -pedantic builds */</span>
+<span class="preprocessor">#endif</span>
+ <span class="keyword">union</span> {
+ cl_mem buffer;
+ cl_mem mem_object;
+ };
} cl_image_desc;</code></pre>
</div>
</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
<p><code>image_type</code> describes the image type and must be either
-CL_MEM_OBJECT_IMAGE1D, CL_MEM_OBJECT_IMAGE1D_BUFFER,
-CL_MEM_OBJECT_IMAGE1D_ARRAY, CL_MEM_OBJECT_IMAGE2D,
-CL_MEM_OBJECT_IMAGE2D_ARRAY or CL_MEM_OBJECT_IMAGE3D.</p>
-</div>
-<div class="paragraph">
+<a href="#CL_MEM_OBJECT_IMAGE1D"><code>CL_​MEM_​OBJECT_​IMAGE1D</code></a>, <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_​MEM_​OBJECT_​IMAGE1D_​BUFFER</code></a>,
+<a href="#CL_MEM_OBJECT_IMAGE1D_ARRAY"><code>CL_​MEM_​OBJECT_​IMAGE1D_​ARRAY</code></a>, <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_​MEM_​OBJECT_​IMAGE2D</code></a>,
+<a href="#CL_MEM_OBJECT_IMAGE2D_ARRAY"><code>CL_​MEM_​OBJECT_​IMAGE2D_​ARRAY</code></a>, or <a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_​MEM_​OBJECT_​IMAGE3D</code></a>.</p>
+</li>
+<li>
<p><code>image_width</code> is the width of the image in pixels.
For a 2D image and image array, the image width must be a value ≥ 1 and
-≤ CL_DEVICE_IMAGE2D_MAX_WIDTH.
+≤ <a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_​DEVICE_​IMAGE2D_​MAX_​WIDTH</code></a>.
For a 3D image, the image width must be a value ≥1 and ≤
-CL_DEVICE_IMAGE3D_MAX_WIDTH.
+<a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_​DEVICE_​IMAGE3D_​MAX_​WIDTH</code></a>.
For a 1D image buffer, the image width must be a value ≥1 and ≤
-CL_DEVICE_IMAGE_MAX_BUFFER_SIZE.
+<a href="#CL_DEVICE_IMAGE_MAX_BUFFER_SIZE"><code>CL_​DEVICE_​IMAGE_​MAX_​BUFFER_​SIZE</code></a>.
For a 1D image and 1D image array, the image width must be a value ≥1
-and ≤ CL_DEVICE_IMAGE2D_MAX_WIDTH.</p>
-</div>
-<div class="paragraph">
-<p><code>image_height</code> is height of the image in pixels.
+and ≤ <a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_​DEVICE_​IMAGE2D_​MAX_​WIDTH</code></a>.</p>
+</li>
+<li>
+<p><code>image_height</code> is the height of the image in pixels.
This is only used if the image is a 2D or 3D image, or a 2D image array.
For a 2D image or image array, the image height must be a value ≥ 1 and
-≤ CL_DEVICE_IMAGE2D_MAX_HEIGHT.
+≤ <a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_​DEVICE_​IMAGE2D_​MAX_​HEIGHT</code></a>.
For a 3D image, the image height must be a value ≥ 1 and ≤
-CL_DEVICE_IMAGE3D_MAX_HEIGHT.</p>
-</div>
-<div class="paragraph">
+<a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_​DEVICE_​IMAGE3D_​MAX_​HEIGHT</code></a>.</p>
+</li>
+<li>
<p><code>image_depth</code> is the depth of the image in pixels.
This is only used if the image is a 3D image and must be a value ≥ 1 and
-≤ CL_DEVICE_IMAGE3D_MAX_DEPTH.</p>
-</div>
-<div class="paragraph">
+≤ <a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_​DEVICE_​IMAGE3D_​MAX_​DEPTH</code></a>.</p>
+</li>
+<li>
<p><code>image_array_size</code><sup>5</sup> is the number of images in the image array.
This is only used if the image is a 1D or 2D image array.
The values for <code>image_array_size</code>, if specified, must be a value ≥ 1 and
-≤ CL_DEVICE_IMAGE_MAX_ARRAY_SIZE.</p>
-</div>
+≤ <a href="#CL_DEVICE_IMAGE_MAX_ARRAY_SIZE"><code>CL_​DEVICE_​IMAGE_​MAX_​ARRAY_​SIZE</code></a>.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">5</dt>
@@ -9835,7 +9993,8 @@
</dd>
</dl>
</div>
-<div class="paragraph">
+</li>
+<li>
<p><code>image_row_pitch</code> is the scan-line pitch in bytes.
This must be 0 if <em>host_ptr</em> is <code>NULL</code> and can be either 0 or ≥
<code>image_width</code> × size of element in bytes if <em>host_ptr</em> is not <code>NULL</code>.
@@ -9845,10 +10004,10 @@
size in bytes.
For a 2D image created from a buffer, the pitch specified (or computed if
pitch specified is 0) must be a multiple of the maximum of the
-CL_DEVICE_IMAGE_PITCH_ALIGNMENT value for all devices in the context
-associated with <code>image_desc</code>→`mem_object` and that support images.</p>
-</div>
-<div class="paragraph">
+<a href="#CL_DEVICE_IMAGE_PITCH_ALIGNMENT"><code>CL_​DEVICE_​IMAGE_​PITCH_​ALIGNMENT</code></a> value for all devices in the context
+associated with the buffer specified by <code>mem_object</code> that support images.</p>
+</li>
+<li>
<p><code>image_slice_pitch</code> is the size in bytes of each 2D slice in the 3D image or
the size in bytes of each image in a 1D or 2D image array.
This must be 0 if <em>host_ptr</em> is <code>NULL</code>.
@@ -9860,22 +10019,21 @@
array or 3D image and <code>image_row_pitch</code> for a 1D image array.
If <code>image_slice_pitch</code> is not 0, it must be a multiple of the
<code>image_row_pitch</code>.</p>
-</div>
-<div class="paragraph">
-<p>num_mip_levels and num_samples must be 0.</p>
-</div>
-<div class="paragraph">
-<p>mem_object may refer to a valid buffer or image memory object.
-mem_object can be a buffer memory object if <code>image_type</code> is
-CL_MEM_OBJECT_IMAGE1D_BUFFER or CL_MEM_OBJECT_IMAGE2D<sup>6</sup>.
-mem_object can be an image object if <code>image_type</code> is
-CL_MEM_OBJECT_IMAGE2D<sup>7</sup>.
+</li>
+<li>
+<p><code>num_mip_levels</code> and <code>num_samples</code> must be 0.</p>
+</li>
+<li>
+<p><code>mem_object</code> may refer to a valid buffer or image memory object.
+<code>mem_object</code> can be a buffer memory object if <code>image_type</code> is
+<a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_​MEM_​OBJECT_​IMAGE1D_​BUFFER</code></a> or <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_​MEM_​OBJECT_​IMAGE2D</code></a><sup>6</sup>.
+<code>mem_object</code> can be an image object if <code>image_type</code> is
+<a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_​MEM_​OBJECT_​IMAGE2D</code></a><sup>7</sup>.
Otherwise it must be <code>NULL</code>.
The image pixels are taken from the memory objects data store.
When the contents of the specified memory objects data store are modified,
those changes are reflected in the contents of the image object and
vice-versa at corresponding synchronization points.</p>
-</div>
<div class="dlist">
<dl>
<dt class="hdlist1">6</dt>
@@ -9890,8 +10048,11 @@
</dd>
</dl>
</div>
+</li>
+</ul>
+</div>
<div class="paragraph">
-<p>For a 1D image buffer create from a buffer object, the <code>image_width</code> ×
+<p>For a 1D image buffer created from a buffer object, the <code>image_width</code> ×
size of element in bytes must be ≤ size of the buffer object.
The image data in the buffer object is stored as a single scanline which is
a linear sequence of adjacent elements.</p>
@@ -9899,7 +10060,7 @@
<div class="paragraph">
<p>For a 2D image created from a buffer object, the <code>image_row_pitch</code> ×
<code>image_height</code> must be ≤ size of the buffer object specified by
-mem_object.
+<code>mem_object</code>.
The image data in the buffer object is stored as a linear sequence of
adjacent scanlines.
Each scanline is a linear sequence of image elements padded to
@@ -9907,45 +10068,48 @@
</div>
<div class="paragraph">
<p>For an image object created from another image object, the values specified
-in the image descriptor except for mem_object must match the image
-descriptor information associated with mem_object.</p>
+in the image descriptor except for <code>mem_object</code> must match the image
+descriptor information associated with <code>mem_object</code>.</p>
</div>
<div class="paragraph">
<p>Image elements are stored according to their image format as described in
<a href="#image-format-descriptor">Image Format Descriptor</a>.</p>
</div>
<div class="paragraph">
-<p>If the buffer object specified by mem_object is created with
-CL_MEM_USE_HOST_PTR, the <em>host_ptr</em> specified to <strong>clCreateBuffer</strong> must be
-aligned to the minimum of the <strong>CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT</strong> value
+<p>If the buffer object specified by <code>mem_object</code> was created with
+<a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, the <em>host_ptr</em> specified to <a href="#clCreateBuffer"><strong>clCreateBuffer</strong></a> must be
+aligned to the maximum of the <a href="#CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT"><code>CL_​DEVICE_​IMAGE_​BASE_​ADDRESS_​ALIGNMENT</code></a> value
for all devices in the context associated with the buffer specified by
-mem_object and that support images.</p>
+<code>mem_object</code> that support images.</p>
</div>
<div class="paragraph">
<p>Creating a 2D image object from another 2D image object allows users to
-create a new image object that shares the image data store with mem_object
+create a new image object that shares the image data store with <code>mem_object</code>
but views the pixels in the image with a different channel order.
The restrictions are:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>all the values specified in `image_desc except for mem_object must match
-the image descriptor information associated with mem_object.</p>
+<p>all the values specified in <code>image_desc</code> except for <code>mem_object</code> must match
+the image descriptor information associated with <code>mem_object</code>.</p>
</li>
<li>
-<p>The <em>`image_desc</em> used for creation of <em>mem_object</em> may not be
-equivalent to image descriptor information associated with mem_object.
+<p>The <code>image_desc</code> used for creation of <code>mem_object</code> may not be
+equivalent to image descriptor information associated with <code>mem_object</code>.
To ensure the values in <em>`image_desc</em> will match one can query
-mem_object for associated information using <strong>clGetImageInfo</strong> function
+<code>mem_object</code> for associated information using <a href="#clGetImageInfo"><strong>clGetImageInfo</strong></a> function
described in <a href="#image-object-queries">Image Object Queries</a>.</p>
</li>
<li>
<p>the channel data type specified in <code>image_format</code> must match the channel
-data type associated with mem_object.
+data type associated with <code>mem_object</code>.
The channel order values<sup>8</sup> supported are:</p>
-<div class="openblock">
-<div class="content">
+</li>
+</ul>
+</div>
+</div>
+</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
@@ -9954,54 +10118,55 @@
<thead>
<tr>
<th class="tableblock halign-left valign-top"><code>image_channel_order</code> specified in <code>image_format</code></th>
-<th class="tableblock halign-left valign-top">image channel order of mem_object</th>
+<th class="tableblock halign-left valign-top">image channel order of <code>mem_object</code></th>
</tr>
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sBGRA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_BGRA</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sBGRA"><code>CL_​sBGRA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_BGRA"><code>CL_​BGRA</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_BGRA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sBGRA</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_BGRA"><code>CL_​BGRA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sBGRA"><code>CL_​sBGRA</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sRGBA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGBA</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBA"><code>CL_​sRGBA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_​RGBA</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGBA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sRGBA</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_​RGBA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBA"><code>CL_​sRGBA</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sRGB</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGB</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGB"><code>CL_​sRGB</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGB"><code>CL_​RGB</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGB</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sRGB</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGB"><code>CL_​RGB</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGB"><code>CL_​sRGB</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sRGBx</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGBx</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBx"><code>CL_​sRGBx</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBx"><code>CL_​RGBx</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGBx</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sRGBx</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBx"><code>CL_​RGBx</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBx"><code>CL_​sRGBx</code></a></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEPTH</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_R</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEPTH"><code>CL_​DEPTH</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_R"><code>CL_​R</code></a></p></td>
</tr>
</tbody>
</table>
-</div>
-</div>
-</li>
+<div class="openblock">
+<div class="content">
+<div class="ulist">
+<ul>
<li>
<p>the channel order specified must have the same number of channels as the
-channel order of mem_object.</p>
+channel order of <code>mem_object</code>.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">8</dt>
@@ -10043,120 +10208,114 @@
</div>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_querying_list_of_supported_image_formats">5.3.2. Querying List of Supported Image Formats</h4>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetSupportedImageFormats(cl_context context,
- cl_mem_flags flags,
- cl_mem_object_type image_type,
- cl_uint num_entries,
- cl_image_format *image_formats,
- cl_uint *num_image_formats)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>can be used to get the list of image formats supported by an OpenCL
-implementation when the following information about an image memory object
-is specified:</p>
+<p>To get the list of image formats supported by an OpenCL implementation for a
+specified context, image type, and allocation information, call the function</p>
+</div>
+<div id="clGetSupportedImageFormats" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetSupportedImageFormats(
+ cl_context context,
+ cl_mem_flags flags,
+ cl_mem_object_type image_type,
+ cl_uint num_entries,
+ cl_image_format* image_formats,
+ cl_uint* num_image_formats);</code></pre>
+</div>
</div>
<div class="ulist">
<ul>
<li>
-<p>Context</p>
-</li>
-<li>
-<p>Image type 1D, 2D, or 3D image, 1D image buffer, 1D or 2D image array.</p>
-</li>
-<li>
-<p>Image object allocation information</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p><strong>clGetSupportedImageFormats</strong> returns a union of image formats supported by
-all devices in the context.</p>
-</div>
-<div class="paragraph">
<p><em>context</em> is a valid OpenCL context on which the image object(s) will be
created.</p>
-</div>
-<div class="paragraph">
-<p><em>flags</em> is a bit-field that is used to specify allocation and usage
-information about the image memory object being queried and is described in
+</li>
+<li>
+<p><em>flags</em> is a bit-field that is used to specify usage
+information about the image formats being queried and is described in
the <a href="#memory-flags-table">Memory Flags</a> table.
-To get a list of supported image formats that can be read from or written to
-by a kernel, <em>flags</em> must be set to CL_MEM_READ_WRITE (get a list of images
-that can be read from and written to by different kernel instances when
-correctly ordered by event dependencies), CL_MEM_READ_ONLY (list of images
-that can be read from by a kernel) or CL_MEM_WRITE_ONLY (list of images that
-can be written to by a kernel).
-To get a list of supported image formats that can be both read from and
-written to by the same kernel instance, <em>flags</em> must be set to
-CL_MEM_KERNEL_READ_AND_WRITE.
+<em>flags</em> may be <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> to query image formats that may be read
+from and written to by different kernel instances when correctly ordered by
+event dependencies, or <a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a> to query image formats that may
+be read from by a kernel, or <a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a> to query image formats that
+may be written to by a kernel, or <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_​MEM_​KERNEL_​READ_​AND_​WRITE</code></a> to query
+image formats that may be both read from and written to by the same kernel
+instance.
Please see <a href="#image-format-mapping">Image Format Mapping</a> for clarification.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image_type</em> describes the image type and must be either
-CL_MEM_OBJECT_IMAGE1D, CL_MEM_OBJECT_IMAGE1D_BUFFER, CL_MEM_OBJECT_IMAGE2D,
-CL_MEM_OBJECT_IMAGE3D, CL_MEM_OBJECT_IMAGE1D_ARRAY or
-CL_MEM_OBJECT_IMAGE2D_ARRAY.</p>
-</div>
-<div class="paragraph">
+<a href="#CL_MEM_OBJECT_IMAGE1D"><code>CL_​MEM_​OBJECT_​IMAGE1D</code></a>, <a href="#CL_MEM_OBJECT_IMAGE1D_BUFFER"><code>CL_​MEM_​OBJECT_​IMAGE1D_​BUFFER</code></a>, <a href="#CL_MEM_OBJECT_IMAGE2D"><code>CL_​MEM_​OBJECT_​IMAGE2D</code></a>,
+<a href="#CL_MEM_OBJECT_IMAGE3D"><code>CL_​MEM_​OBJECT_​IMAGE3D</code></a>, <a href="#CL_MEM_OBJECT_IMAGE1D_ARRAY"><code>CL_​MEM_​OBJECT_​IMAGE1D_​ARRAY</code></a>, or
+<a href="#CL_MEM_OBJECT_IMAGE2D_ARRAY"><code>CL_​MEM_​OBJECT_​IMAGE2D_​ARRAY</code></a>.</p>
+</li>
+<li>
<p><em>num_entries</em> specifies the number of entries that can be returned in the
memory location given by <em>image_formats</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image_formats</em> is a pointer to a memory location where the list of
supported image formats are returned.
Each entry describes a <em>cl_image_format</em> structure supported by the OpenCL
implementation.
If <em>image_formats</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>num_image_formats</em> is the actual number of supported image formats for a
specific <em>context</em> and values specified by <em>flags</em>.
If <em>num_image_formats</em> is <code>NULL</code>, it is ignored.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clGetSupportedImageFormats</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> returns a union of image formats supported by
+all devices in the context.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid context.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>flags</em> or <em>image_type</em> are not valid, or if
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>flags</em> or <em>image_type</em> are not valid, or if
<em>num_entries</em> is 0 and <em>image_formats</em> is not <code>NULL</code>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
<div class="paragraph">
-<p>If CL_DEVICE_IMAGE_SUPPORT specified in the <a href="#device-queries-table">Device
-Queries</a> table is CL_TRUE, the values assigned to
-CL_DEVICE_MAX_READ_IMAGE_ARGS, CL_DEVICE_MAX_WRITE_IMAGE_ARGS,
-CL_DEVICE_IMAGE2D_MAX_WIDTH, CL_DEVICE_IMAGE2D_MAX_HEIGHT,
-CL_DEVICE_IMAGE3D_MAX_WIDTH, CL_DEVICE_IMAGE3D_MAX_HEIGHT,
-CL_DEVICE_IMAGE3D_MAX_DEPTH and CL_DEVICE_MAX_SAMPLERS by the implementation
+<p>If <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> specified in the <a href="#device-queries-table">Device
+Queries</a> table is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>, the values assigned to
+<a href="#CL_DEVICE_MAX_READ_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​READ_​IMAGE_​ARGS</code></a>, <a href="#CL_DEVICE_MAX_WRITE_IMAGE_ARGS"><code>CL_​DEVICE_​MAX_​WRITE_​IMAGE_​ARGS</code></a>
+<a href="#CL_DEVICE_IMAGE2D_MAX_WIDTH"><code>CL_​DEVICE_​IMAGE2D_​MAX_​WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE2D_MAX_HEIGHT"><code>CL_​DEVICE_​IMAGE2D_​MAX_​HEIGHT</code></a>
+<a href="#CL_DEVICE_IMAGE3D_MAX_WIDTH"><code>CL_​DEVICE_​IMAGE3D_​MAX_​WIDTH</code></a>, <a href="#CL_DEVICE_IMAGE3D_MAX_HEIGHT"><code>CL_​DEVICE_​IMAGE3D_​MAX_​HEIGHT</code></a>
+<a href="#CL_DEVICE_IMAGE3D_MAX_DEPTH"><code>CL_​DEVICE_​IMAGE3D_​MAX_​DEPTH</code></a>, and <a href="#CL_DEVICE_MAX_SAMPLERS"><code>CL_​DEVICE_​MAX_​SAMPLERS</code></a> by the implementation
must be greater than or equal to the minimum values specified in the
<a href="#device-queries-table">Device Queries</a> table.</p>
</div>
+</div>
+</div>
<div class="sect4">
-<h5 id="_minimum_list_of_supported_image_formats">Minimum List of Supported Image Formats</h5>
+<h5 id="minimum-list-of-supported-image-formats">Minimum List of Supported Image Formats</h5>
+<div class="openblock">
+<div class="content">
<div class="paragraph">
<p>For 1D, 1D image from buffer, 2D, 3D image objects, 1D and 2D image array
objects, the mandated minimum list of image formats that can be read from
@@ -10166,7 +10325,7 @@
Kernel Read Or Write</a> table.</p>
</div>
<table id="min-supported-cross-kernel-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 16. Min. list of supported image formats kernel read or write</caption>
+<caption class="title">Table 16. Minimum list of required image formats: kernel read or write</caption>
<colgroup>
<col style="width: 34%;">
<col style="width: 33%;">
@@ -10182,67 +10341,67 @@
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_R</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT8<br>
- CL_UNORM_INT16<br>
- CL_SNORM_INT8<br>
- CL_SNORM_INT16<br>
- CL_SIGNED_INT8<br>
- CL_SIGNED_INT16<br>
- CL_SIGNED_INT32<br>
- CL_UNSIGNED_INT8<br>
- CL_UNSIGNED_INT16<br>
- CL_UNSIGNED_INT32<br>
- CL_HALF_FLOAT<br>
- CL_FLOAT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_R"><code>CL_​R</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a><br>
+ <a href="#CL_UNORM_INT16"><code>CL_​UNORM_​INT16</code></a><br>
+ <a href="#CL_SNORM_INT8"><code>CL_​SNORM_​INT8</code></a><br>
+ <a href="#CL_SNORM_INT16"><code>CL_​SNORM_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT8"><code>CL_​SIGNED_​INT8</code></a><br>
+ <a href="#CL_SIGNED_INT16"><code>CL_​SIGNED_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT32"><code>CL_​SIGNED_​INT32</code></a><br>
+ <a href="#CL_UNSIGNED_INT8"><code>CL_​UNSIGNED_​INT8</code></a><br>
+ <a href="#CL_UNSIGNED_INT16"><code>CL_​UNSIGNED_​INT16</code></a><br>
+ <a href="#CL_UNSIGNED_INT32"><code>CL_​UNSIGNED_​INT32</code></a><br>
+ <a href="#CL_HALF_FLOAT"><code>CL_​HALF_​FLOAT</code></a><br>
+ <a href="#CL_FLOAT"><code>CL_​FLOAT</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_DEPTH<sup>9</sup></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT16<br>
- CL_FLOAT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_DEPTH"><code>CL_​DEPTH</code></a><sup>9</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT16"><code>CL_​UNORM_​INT16</code></a><br>
+ <a href="#CL_FLOAT"><code>CL_​FLOAT</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT8<br>
- CL_UNORM_INT16<br>
- CL_SNORM_INT8<br>
- CL_SNORM_INT16<br>
- CL_SIGNED_INT8<br>
- CL_SIGNED_INT16<br>
- CL_SIGNED_INT32<br>
- CL_UNSIGNED_INT8<br>
- CL_UNSIGNED_INT16<br>
- CL_UNSIGNED_INT32<br>
- CL_HALF_FLOAT<br>
- CL_FLOAT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RG"><code>CL_​RG</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a><br>
+ <a href="#CL_UNORM_INT16"><code>CL_​UNORM_​INT16</code></a><br>
+ <a href="#CL_SNORM_INT8"><code>CL_​SNORM_​INT8</code></a><br>
+ <a href="#CL_SNORM_INT16"><code>CL_​SNORM_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT8"><code>CL_​SIGNED_​INT8</code></a><br>
+ <a href="#CL_SIGNED_INT16"><code>CL_​SIGNED_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT32"><code>CL_​SIGNED_​INT32</code></a><br>
+ <a href="#CL_UNSIGNED_INT8"><code>CL_​UNSIGNED_​INT8</code></a><br>
+ <a href="#CL_UNSIGNED_INT16"><code>CL_​UNSIGNED_​INT16</code></a><br>
+ <a href="#CL_UNSIGNED_INT32"><code>CL_​UNSIGNED_​INT32</code></a><br>
+ <a href="#CL_HALF_FLOAT"><code>CL_​HALF_​FLOAT</code></a><br>
+ <a href="#CL_FLOAT"><code>CL_​FLOAT</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGBA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT8<br>
- CL_UNORM_INT16<br>
- CL_SNORM_INT8<br>
- CL_SNORM_INT16<br>
- CL_SIGNED_INT8<br>
- CL_SIGNED_INT16<br>
- CL_SIGNED_INT32<br>
- CL_UNSIGNED_INT8<br>
- CL_UNSIGNED_INT16<br>
- CL_UNSIGNED_INT32<br>
- CL_HALF_FLOAT<br>
- CL_FLOAT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_​RGBA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a><br>
+ <a href="#CL_UNORM_INT16"><code>CL_​UNORM_​INT16</code></a><br>
+ <a href="#CL_SNORM_INT8"><code>CL_​SNORM_​INT8</code></a><br>
+ <a href="#CL_SNORM_INT16"><code>CL_​SNORM_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT8"><code>CL_​SIGNED_​INT8</code></a><br>
+ <a href="#CL_SIGNED_INT16"><code>CL_​SIGNED_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT32"><code>CL_​SIGNED_​INT32</code></a><br>
+ <a href="#CL_UNSIGNED_INT8"><code>CL_​UNSIGNED_​INT8</code></a><br>
+ <a href="#CL_UNSIGNED_INT16"><code>CL_​UNSIGNED_​INT16</code></a><br>
+ <a href="#CL_UNSIGNED_INT32"><code>CL_​UNSIGNED_​INT32</code></a><br>
+ <a href="#CL_HALF_FLOAT"><code>CL_​HALF_​FLOAT</code></a><br>
+ <a href="#CL_FLOAT"><code>CL_​FLOAT</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_BGRA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT8</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_BGRA"><code>CL_​BGRA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_sRGBA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT8<sup>10</sup></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_sRGBA"><code>CL_​sRGBA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a><sup>10</sup></p></td>
</tr>
</tbody>
</table>
@@ -10250,7 +10409,7 @@
<dl>
<dt class="hdlist1">9</dt>
<dd>
-<p>CL_DEPTH channel order is supported only for 2D image and 2D image array
+<p><a href="#CL_DEPTH"><code>CL_​DEPTH</code></a> channel order is supported only for 2D image and 2D image array
objects.</p>
</dd>
<dt class="hdlist1">10</dt>
@@ -10269,8 +10428,10 @@
<a href="#min-supported-same-kernel-table">Supported Formats - Kernel Read And
Write</a> table.</p>
</div>
-<table id="min-supported-same-kernel-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 17. Min. list of supported image formats kernel read and write</caption>
+<div id="min-supported-same-kernel-table" class="paragraph">
+<p>_Minimum list of required image formats: kernel read and write</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 34%;">
<col style="width: 33%;">
@@ -10286,33 +10447,35 @@
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_R</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT8<br>
- CL_SIGNED_INT8<br>
- CL_SIGNED_INT16<br>
- CL_SIGNED_INT32<br>
- CL_UNSIGNED_INT8<br>
- CL_UNSIGNED_INT16<br>
- CL_UNSIGNED_INT32<br>
- CL_HALF_FLOAT<br>
- CL_FLOAT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_R"><code>CL_​R</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a><br>
+ <a href="#CL_SIGNED_INT8"><code>CL_​SIGNED_​INT8</code></a><br>
+ <a href="#CL_SIGNED_INT16"><code>CL_​SIGNED_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT32"><code>CL_​SIGNED_​INT32</code></a><br>
+ <a href="#CL_UNSIGNED_INT8"><code>CL_​UNSIGNED_​INT8</code></a><br>
+ <a href="#CL_UNSIGNED_INT16"><code>CL_​UNSIGNED_​INT16</code></a><br>
+ <a href="#CL_UNSIGNED_INT32"><code>CL_​UNSIGNED_​INT32</code></a><br>
+ <a href="#CL_HALF_FLOAT"><code>CL_​HALF_​FLOAT</code></a><br>
+ <a href="#CL_FLOAT"><code>CL_​FLOAT</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_RGBA</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_UNORM_INT8<br>
- CL_SIGNED_INT8<br>
- CL_SIGNED_INT16<br>
- CL_SIGNED_INT32<br>
- CL_UNSIGNED_INT8<br>
- CL_UNSIGNED_INT16<br>
- CL_UNSIGNED_INT32<br>
- CL_HALF_FLOAT<br>
- CL_FLOAT</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_RGBA"><code>CL_​RGBA</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_UNORM_INT8"><code>CL_​UNORM_​INT8</code></a><br>
+ <a href="#CL_SIGNED_INT8"><code>CL_​SIGNED_​INT8</code></a><br>
+ <a href="#CL_SIGNED_INT16"><code>CL_​SIGNED_​INT16</code></a><br>
+ <a href="#CL_SIGNED_INT32"><code>CL_​SIGNED_​INT32</code></a><br>
+ <a href="#CL_UNSIGNED_INT8"><code>CL_​UNSIGNED_​INT8</code></a><br>
+ <a href="#CL_UNSIGNED_INT16"><code>CL_​UNSIGNED_​INT16</code></a><br>
+ <a href="#CL_UNSIGNED_INT32"><code>CL_​UNSIGNED_​INT32</code></a><br>
+ <a href="#CL_HALF_FLOAT"><code>CL_​HALF_​FLOAT</code></a><br>
+ <a href="#CL_FLOAT"><code>CL_​FLOAT</code></a></p></td>
</tr>
</tbody>
</table>
</div>
+</div>
+</div>
<div class="sect4">
<h5 id="image-format-mapping">Image format mapping to OpenCL kernel language image access qualifiers</h5>
<div class="paragraph">
@@ -10321,7 +10484,7 @@
Not all image formats supported by the device and platform are valid to be
passed to all of these access qualifiers.
For each access qualifier, only images whose format is in the list of
-formats returned by <strong>clGetSupportedImageFormats</strong> with the given flag
+formats returned by <a href="#clGetSupportedImageFormats"><strong>clGetSupportedImageFormats</strong></a> with the given flag
arguments in the <a href="#image-format-mapping-table">Image Format Mapping</a> table
are permitted.
It is not valid to pass an image supporting writing as both a <code>read_only</code>
@@ -10329,7 +10492,7 @@
parameter and any other image parameter.</p>
</div>
<table id="image-format-mapping-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 18. Mapping from format flags passed to <strong>clGetSupportedImageFormats</strong> to OpenCL kernel language image access qualifiers</caption>
+<caption class="title">Table 17. Mapping from format flags passed to <a href="#clGetSupportedImageFormats">clGetSupportedImageFormats</a> to OpenCL kernel language image access qualifiers</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
@@ -10343,19 +10506,19 @@
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>read_only</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_MEM_READ_ONLY,<br>
- CL_MEM_READ_WRITE,<br>
- CL_MEM_KERNEL_READ_AND_WRITE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_READ_ONLY"><code>CL_​MEM_​READ_​ONLY</code></a>,<br>
+ <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a>,<br>
+ <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_​MEM_​KERNEL_​READ_​AND_​WRITE</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>write_only</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_MEM_WRITE_ONLY,<br>
- CL_MEM_READ_WRITE,<br>
- CL_MEM_KERNEL_READ_AND_WRITE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_WRITE_ONLY"><code>CL_​MEM_​WRITE_​ONLY</code></a>,<br>
+ <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a>,<br>
+ <a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_​MEM_​KERNEL_​READ_​AND_​WRITE</code></a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>read_write</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CL_MEM_KERNEL_READ_AND_WRITE</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#CL_MEM_KERNEL_READ_AND_WRITE"><code>CL_​MEM_​KERNEL_​READ_​AND_​WRITE</code></a></p></td>
</tr>
</tbody>
</table>
@@ -10363,86 +10526,60 @@
</div>
<div class="sect3">
<h4 id="_reading_writing_and_copying_image_objects">5.3.3. Reading, Writing and Copying Image Objects</h4>
+<div class="openblock">
+<div class="content">
<div class="paragraph">
<p>The following functions enqueue commands to read from an image or image
array object to host memory or write to an image or image array object from
host memory.</p>
</div>
-<div class="listingblock">
+<div id="clEnqueueReadImage" class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueReadImage(cl_command_queue command_queue,
- cl_mem image,
- cl_bool blocking_read,
- <span class="directive">const</span> size_t *origin,
- <span class="directive">const</span> size_t *region,
- size_t row_pitch,
- size_t slice_pitch,
- <span class="directive">void</span> *ptr,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueReadImage(
+ cl_command_queue command_queue,
+ cl_mem image,
+ cl_bool blocking_read,
+ <span class="directive">const</span> size_t* origin,
+ <span class="directive">const</span> size_t* region,
+ size_t row_pitch,
+ size_t slice_pitch,
+ <span class="directive">void</span>* ptr,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
</div>
</div>
-<div class="listingblock">
+<div id="clEnqueueWriteImage" class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueWriteImage(cl_command_queue command_queue,
- cl_mem image,
- cl_bool blocking_write,
- <span class="directive">const</span> size_t *origin,
- <span class="directive">const</span> size_t *region,
- size_t input_row_pitch,
- size_t input_slice_pitch,
- <span class="directive">const</span> <span class="directive">void</span> *ptr,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueWriteImage(
+ cl_command_queue command_queue,
+ cl_mem image,
+ cl_bool blocking_write,
+ <span class="directive">const</span> size_t* origin,
+ <span class="directive">const</span> size_t* region,
+ size_t input_row_pitch,
+ size_t input_slice_pitch,
+ <span class="directive">const</span> <span class="directive">void</span>* ptr,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
</div>
</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> refers to the host command-queue in which the read / write
command will be queued.
<em>command_queue</em> and <em>image</em> must be created with the same OpenCL context.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image</em> refers to a valid image or image array object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>blocking_read</em> and <em>blocking_write</em> indicate if the read and write
operations are <em>blocking</em> or <em>non-blocking</em>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_read</em> is CL_TRUE i.e. the read command is blocking,
-<strong>clEnqueueReadImage</strong> does not return until the buffer data has been read and
-copied into memory pointed to by <em>ptr</em>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_read</em> is CL_FALSE i.e. the read command is non-blocking,
-<strong>clEnqueueReadImage</strong> queues a non-blocking read command and returns.
-The contents of the buffer that <em>ptr</em> points to cannot be used until the
-read command has completed.
-The <em>event</em> argument returns an event object which can be used to query the
-execution status of the read command.
-When the read command has completed, the contents of the buffer that <em>ptr</em>
-points to can be used by the application.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_write</em> is CL_TRUE, the write command is blocking and does not
-return until the command is complete, including transfer of the data.
-The memory pointed to by <em>ptr</em> can be reused by the application after the
-<strong>clEnqueueWriteImage</strong> call returns.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_write</em> is CL_FALSE, the OpenCL implementation will use <em>ptr</em> to
-perform a non-blocking write.
-As the write is non-blocking the implementation can return immediately.
-The memory pointed to by <em>ptr</em> cannot be reused by the application after the
-call returns.
-The <em>event</em> argument returns an event object which can be used to query the
-execution status of the write command.
-When the write command has completed, the memory pointed to by <em>ptr</em> can
-then be reused by the application.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or 3D
image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or
the (<em>x</em>) offset and the image index in the 1D image array.
@@ -10454,8 +10591,8 @@
in the 1D image array.
If <em>image</em> is a 2D image array object, <em>origin</em>[2] describes the image index
in the 2D image array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or
3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the
number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D
@@ -10465,19 +10602,19 @@
<em>region</em>[2] must be 1.
If <em>image</em> is a 1D image array object, <em>region</em>[2] must be 1.
The values in <em>region</em> cannot be 0.</p>
-</div>
-<div class="paragraph">
-<p><em>row_pitch</em> in <strong>clEnqueueReadImage</strong> and <em>input_row_pitch</em> in
-<strong>clEnqueueWriteImage</strong> is the length of each row in bytes.
+</li>
+<li>
+<p><em>row_pitch</em> in <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and <em>input_row_pitch</em> in
+<a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> is the length of each row in bytes.
This value must be greater than or equal to the element size in bytes
× <em>width</em>.
If <em>row_pitch</em> (or <em>input_row_pitch</em>) is set to 0, the appropriate row pitch
is calculated based on the size of each element in bytes multiplied by
<em>width</em>.</p>
-</div>
-<div class="paragraph">
-<p><em>slice_pitch</em> in <strong>clEnqueueReadImage</strong> and <em>input_slice_pitch</em> in
-<strong>clEnqueueWriteImage</strong> is the size in bytes of the 2D slice of the 3D region
+</li>
+<li>
+<p><em>slice_pitch</em> in <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and <em>input_slice_pitch</em> in
+<a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> is the size in bytes of the 2D slice of the 3D region
of a 3D image or each image of a 1D or 2D image array being read or written
respectively.
This must be 0 if <em>image</em> is a 1D or 2D image.
@@ -10485,14 +10622,14 @@
<em>height</em>.
If <em>slice_pitch</em> (or <em>input_slice_pitch</em>) is set to 0, the appropriate slice
pitch is calculated based on the <em>row_pitch</em> × <em>height</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>ptr</em> is the pointer to a buffer in host memory where image data is to be
read from or to be written to.
The alignment requirements for ptr are specified in
<a href="#alignment-app-data-types">Alignment of Application Data Types</a>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -10506,8 +10643,8 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular read / write
command and can be used to query or queue a wait for this particular command
to complete.
@@ -10517,78 +10654,112 @@
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueReadImage</strong> and <strong>clEnqueueWriteImage</strong> return CL_SUCCESS if the
+<p>If <em>blocking_read</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a> i.e. the read command is blocking,
+<a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> does not return until the buffer data has been read and
+copied into memory pointed to by <em>ptr</em>.</p>
+</div>
+<div class="paragraph">
+<p>If <em>blocking_read</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> i.e. the read command is non-blocking,
+<a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> queues a non-blocking read command and returns.
+The contents of the buffer that <em>ptr</em> points to cannot be used until the
+read command has completed.
+The <em>event</em> argument returns an event object which can be used to query the
+execution status of the read command.
+When the read command has completed, the contents of the buffer that <em>ptr</em>
+points to can be used by the application.</p>
+</div>
+<div class="paragraph">
+<p>If <em>blocking_write</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>, the write command is blocking and does not
+return until the command is complete, including transfer of the data.
+The memory pointed to by <em>ptr</em> can be reused by the application after the
+<a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> call returns.</p>
+</div>
+<div class="paragraph">
+<p>If <em>blocking_write</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>, the OpenCL implementation will use <em>ptr</em> to
+perform a non-blocking write.
+As the write is non-blocking the implementation can return immediately.
+The memory pointed to by <em>ptr</em> cannot be reused by the application after the
+call returns.
+The <em>event</em> argument returns an event object which can be used to query the
+execution status of the write command.
+When the write command has completed, the memory pointed to by <em>ptr</em> can
+then be reused by the application.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> and <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> return <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the
function is executed successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em> and
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em> and
<em>image</em> are not the same or if the context associated with
<em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if i_mage_ is not a valid image object.</p>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if i_mage_ is not a valid image object.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if the region being read or written specified by
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the region being read or written specified by
<em>origin</em> and <em>region</em> is out of bounds or if <em>ptr</em> is a <code>NULL</code> value.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values in <em>origin</em> and <em>region</em> do not follow rules
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values in <em>origin</em> and <em>region</em> do not follow rules
described in the argument description for <em>origin</em> and <em>region</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_SIZE if image dimensions (image width, height,
+<p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_​INVALID_​IMAGE_​SIZE</code></a> if image dimensions (image width, height,
specified or compute row and/or slice pitch) for <em>image</em> are not
supported by device associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_NOT_SUPPORTED if image format (image channel order and
+<p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED</code></a> if image format (image channel order and
data type) for <em>image</em> are not supported by device associated with
<em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>image</em>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if the device associated with <em>command_queue</em> does
-not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the
-<a href="#device-queries-table">Device Queries</a> table is CL_FALSE).</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if the device associated with <em>command_queue</em> does
+not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> specified in the
+<a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>).</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if <strong>clEnqueueReadImage</strong> is called on <em>image</em> which
-has been created with CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_NO_ACCESS.</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> is called on <em>image</em> which
+has been created with <a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if <strong>clEnqueueWriteImage</strong> is called on <em>image</em> which
-has been created with CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS.</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> is called on <em>image</em> which
+has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a>.</p>
</li>
<li>
-<p>CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write
+<p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_​EXEC_​STATUS_​ERROR_​FOR_​EVENTS_​IN_​WAIT_​LIST</code></a> if the read and write
operations are blocking and the execution status of any of the events in
<em>event_wait_list</em> is a negative integer value.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
@@ -10601,11 +10772,11 @@
</td>
<td class="content">
<div class="paragraph">
-<p>Calling <strong>clEnqueueReadImage</strong> to read a region of the <em>image</em> with the <em>ptr</em>
+<p>Calling <a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> to read a region of the <em>image</em> with the <em>ptr</em>
argument value set to <em>host_ptr</em> + (<em>origin</em>[2] × <em>image slice pitch</em>
+ <em>origin</em>[1] × <em>image row pitch</em> + <em>origin</em>[0] × <em>bytes
per pixel</em>), where <em>host_ptr</em> is a pointer to the memory region specified
-when the <em>image</em> being read is created with CL_MEM_USE_HOST_PTR, must meet
+when the <em>image</em> being read is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, must meet
the following requirements in order to avoid undefined behavior:</p>
</div>
<div class="ulist">
@@ -10616,7 +10787,7 @@
</li>
<li>
<p>The <em>row_pitch</em> and <em>slice_pitch</em> argument values in
-<strong>clEnqueueReadImage</strong> must be set to the image row pitch and slice pitch.</p>
+<a href="#clEnqueueReadImage"><strong>clEnqueueReadImage</strong></a> must be set to the image row pitch and slice pitch.</p>
</li>
<li>
<p>The image object is not mapped.</p>
@@ -10628,12 +10799,12 @@
</ul>
</div>
<div class="paragraph">
-<p>Calling <strong>clEnqueueWriteImage</strong> to update the latest bits in a region of the
+<p>Calling <a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> to update the latest bits in a region of the
<em>image</em> with the <em>ptr</em> argument value set to <em>host_ptr</em> + (<em>origin</em>[2]
× <em>image slice pitch</em> + <em>origin</em>[1] × <em>image row pitch</em> +
<em>origin</em>[0] × <em>bytes per pixel</em>), where <em>host_ptr</em> is a pointer to the
memory region specified when the <em>image</em> being written is created with
-CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid
+<a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a>, must meet the following requirements in order to avoid
undefined behavior:</p>
</div>
<div class="ulist">
@@ -10644,7 +10815,7 @@
</li>
<li>
<p>The <em>input_row_pitch</em> and <em>input_slice_pitch</em> argument values in
-<strong>clEnqueueWriteImage</strong> must be set to the image row pitch and slice
+<a href="#clEnqueueWriteImage"><strong>clEnqueueWriteImage</strong></a> must be set to the image row pitch and slice
pitch.</p>
</li>
<li>
@@ -10660,38 +10831,44 @@
</tr>
</table>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueCopyImage(cl_command_queue command_queue,
- cl_mem src_image,
- cl_mem dst_image,
- <span class="directive">const</span> size_t *src_origin,
- <span class="directive">const</span> size_t *dst_origin,
- <span class="directive">const</span> size_t *region,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to copy image objects.
-<em>src_image</em> and <em>dst_image</em> can be 1D, 2D, 3D image or a 1D, 2D image array
+<p>To enqueue a command to copy image objects, call the function</p>
+</div>
+<div id="clEnqueueCopyImage" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyImage(
+ cl_command_queue command_queue,
+ cl_mem src_image,
+ cl_mem dst_image,
+ <span class="directive">const</span> size_t* src_origin,
+ <span class="directive">const</span> size_t* dst_origin,
+ <span class="directive">const</span> size_t* region,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><em>src_image</em> and <em>dst_image</em> can be 1D, 2D, 3D image or a 1D, 2D image array
objects.
It is possible to copy subregions between any combinations of source and
destination types, provided that the dimensions of the subregions are the
same e.g., one can copy a rectangular region from a 2D image to a slice of a
3D image.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>command_queue</em> refers to the host command-queue in which the copy command
will be queued.
The OpenCL context associated with <em>command_queue</em>, <em>src_image</em> and
<em>dst_image</em> must be the same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>src_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or
3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or
the (<em>x</em>) offset and the image index in the 1D image array.
@@ -10703,8 +10880,8 @@
image index in the 1D image array.
If <em>src_image</em> is a 2D image array object, <em>src_origin</em>[2] describes the
image index in the 2D image array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>dst_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or
3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or
the (<em>x</em>) offset and the image index in the 1D image array.
@@ -10716,8 +10893,8 @@
image index in the 1D image array.
If <em>dst_image</em> is a 2D image array object, <em>dst_origin</em>[2] describes the
image index in the 2D image array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or
3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the
number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D
@@ -10728,8 +10905,8 @@
If <em>src_image</em> or <em>dst_image</em> is a 1D image array object, <em>region</em>[2] must
be 1.
The values in <em>region</em> cannot be 0.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -10743,139 +10920,142 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular copy command
and can be used to query or queue a wait for this particular command to
complete.
<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
application to query the status of this command or queue a wait for this
command to complete.
-<strong>clEnqueueBarrierWithWaitList</strong> can be used instead.
+<a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> can be used instead.
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
<p>It is currently a requirement that the <em>src_image</em> and <em>dst_image</em> image
-memory objects for <strong>clEnqueueCopyImage</strong> must have the exact same image
+memory objects for <a href="#clEnqueueCopyImage"><strong>clEnqueueCopyImage</strong></a> must have the exact same image
format (i.e. the cl_image_format descriptor specified when <em>src_image</em> and
<em>dst_image</em> are created must match).</p>
</div>
<div class="paragraph">
-<p><strong>clEnqueueCopyImage</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clEnqueueCopyImage"><strong>clEnqueueCopyImage</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em>,
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em>,
<em>src_image</em> and <em>dst_image</em> are not the same or if the context
associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not
the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>src_image</em> and <em>dst_image</em> are not valid image
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>src_image</em> and <em>dst_image</em> are not valid image
objects.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_MISMATCH if <em>src_image</em> and <em>dst_image</em> do not use the
+<p><a href="#CL_IMAGE_FORMAT_MISMATCH"><code>CL_​IMAGE_​FORMAT_​MISMATCH</code></a> if <em>src_image</em> and <em>dst_image</em> do not use the
same image format.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if the 2D or 3D rectangular region specified by
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the 2D or 3D rectangular region specified by
<em>src_origin</em> and <em>src_origin</em> + <em>region</em> refers to a region outside
<em>src_image</em>, or if the 2D or 3D rectangular region specified by
<em>dst_origin</em> and <em>dst_origin</em> + <em>region</em> refers to a region outside
<em>dst_image</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values in <em>src_origin</em>, <em>dst_origin</em> and <em>region</em> do
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values in <em>src_origin</em>, <em>dst_origin</em> and <em>region</em> do
not follow rules described in the argument description for <em>src_origin</em>,
<em>dst_origin</em> and <em>region</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_SIZE if image dimensions (image width, height,
+<p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_​INVALID_​IMAGE_​SIZE</code></a> if image dimensions (image width, height,
specified or compute row and/or slice pitch) for <em>src_image</em> or
<em>dst_image</em> are not supported by device associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_NOT_SUPPORTED if image format (image channel order and
+<p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED</code></a> if image format (image channel order and
data type) for <em>src_image</em> or <em>dst_image</em> are not supported by device
associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>src_image</em> or <em>dst_image</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if the device associated with <em>command_queue</em> does
-not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the
-<a href="#device-queries-table">Device Queries</a> table is CL_FALSE).</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if the device associated with <em>command_queue</em> does
+not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> specified in the
+<a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>).</p>
</li>
<li>
-<p>CL_MEM_COPY_OVERLAP if <em>src_image</em> and <em>dst_image</em> are the same image
+<p><a href="#CL_MEM_COPY_OVERLAP"><code>CL_​MEM_​COPY_​OVERLAP</code></a> if <em>src_image</em> and <em>dst_image</em> are the same image
object and the source and destination regions overlap.</p>
</li>
</ul>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_filling_image_objects">5.3.4. Filling Image Objects</h4>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueFillImage(cl_command_queue command_queue,
- cl_mem image,
- <span class="directive">const</span> <span class="directive">void</span> *fill_color,
- <span class="directive">const</span> size_t *origin,
- <span class="directive">const</span> size_t *region,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to fill an image object with a specified color.
-The usage information which indicates whether the memory object can be read
-or written by a kernel and/or the host and is given by the cl_mem_flags
-argument value specified when <em>image</em> is created is ignored by
-<strong>clEnqueueFillImage</strong>.</p>
+<p>To enqueue a command to fill an image object with a specified color, call
+the function</p>
</div>
-<div class="paragraph">
+<div id="clEnqueueFillImage" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueFillImage(
+ cl_command_queue command_queue,
+ cl_mem image,
+ <span class="directive">const</span> <span class="directive">void</span>* fill_color,
+ <span class="directive">const</span> size_t* origin,
+ <span class="directive">const</span> size_t* region,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> refers to the host command-queue in which the fill command
will be queued.
The OpenCL context associated with <em>command_queue</em> and <em>image</em> must be the
same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image</em> is a valid image object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>fill_color</em> is the color used to fill the image.
The fill color is a single floating point value if the channel order is
-CL_DEPTH.
+<a href="#CL_DEPTH"><code>CL_​DEPTH</code></a>.
Otherwise, the fill color is a four component RGBA floating-point color
value if the <em>image</em> channel data type is not an unnormalized signed or
unsigned integer type, is a four component signed integer value if the
@@ -10884,8 +11064,8 @@
unnormalized unsigned integer type.
The fill color will be converted to the appropriate image channel format and
order associated with <em>image</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or 3D
image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or
the (<em>x</em>) offset and the image index in the 1D image array.
@@ -10897,8 +11077,8 @@
in the 1D image array.
If <em>image</em> is a 2D image array object, <em>origin</em>[2] describes the image index
in the 2D image array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or
3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the
number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D
@@ -10908,8 +11088,8 @@
<em>region</em>[2] must be 1.
If <em>image</em> is a 1D image array object, <em>region</em>[2] must be 1.
The values in <em>region</em> cannot be 0.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -10923,113 +11103,126 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular command and
can be used to query or queue a wait for this particular command to
complete.
<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
application to query the status of this command or queue a wait for this
command to complete.
-<strong>clEnqueueBarrierWithWaitList</strong> can be used instead.
+<a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> can be used instead.
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueFillImage</strong> returns CL_SUCCESS if the function is executed
+<p>The usage information which indicates whether the memory object can be read
+or written by a kernel and/or the host and is given by the cl_mem_flags
+argument value specified when <em>image</em> is created is ignored by
+<a href="#clEnqueueFillImage"><strong>clEnqueueFillImage</strong></a>.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clEnqueueFillImage"><strong>clEnqueueFillImage</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em> and
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em> and
<em>image</em> are not the same or if the context associated with
<em>command_queue</em> and events in <em>event_wait_list</em> are not the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>image</em> is not a valid image object.</p>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>image</em> is not a valid image object.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>fill_color</em> is <code>NULL</code>.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>fill_color</em> is <code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if the region being filled as specified by <em>origin</em> and
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the region being filled as specified by <em>origin</em> and
<em>region</em> is out of bounds or if <em>ptr</em> is a <code>NULL</code> value.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values in <em>origin</em> and <em>region</em> do not follow rules
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values in <em>origin</em> and <em>region</em> do not follow rules
described in the argument description for <em>origin</em> and <em>region</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_SIZE if image dimensions (image width, height,
+<p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_​INVALID_​IMAGE_​SIZE</code></a> if image dimensions (image width, height,
specified or compute row and/or slice pitch) for <em>image</em> are not
supported by device associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_NOT_SUPPORTED if image format (image channel order and
+<p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED</code></a> if image format (image channel order and
data type) for <em>image</em> are not supported by device associated with
<em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>image</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_copying_between_image_and_buffer_objects">5.3.5. Copying between Image and Buffer Objects</h4>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueCopyImageToBuffer(cl_command_queue command_queue,
- cl_mem src_image,
- cl_mem dst_buffer,
- <span class="directive">const</span> size_t *src_origin,
- <span class="directive">const</span> size_t *region,
- size_t dst_offset,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to copy an image object to a buffer object.</p>
+<p>To enqueue a command to copy an image object to a buffer object, call the
+function</p>
</div>
-<div class="paragraph">
+<div id="clEnqueueCopyImageToBuffer" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyImageToBuffer(
+ cl_command_queue command_queue,
+ cl_mem src_image,
+ cl_mem dst_buffer,
+ <span class="directive">const</span> size_t* src_origin,
+ <span class="directive">const</span> size_t* region,
+ size_t dst_offset,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> must be a valid host command-queue.
The OpenCL context associated with <em>command_queue</em>, <em>src_image</em> and
<em>dst_buffer</em> must be the same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>src_image</em> is a valid image object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>dst_buffer</em> is a valid buffer object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>src_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or
3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or
the (<em>x</em>) offset and the image index in the 1D image array.
@@ -11041,8 +11234,8 @@
image index in the 1D image array.
If <em>src_image</em> is a 2D image array object, <em>src_origin</em>[2] describes the
image index in the 2D image array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or
3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the
number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D
@@ -11052,8 +11245,8 @@
<em>region</em>[2] must be 1.
If <em>src_image</em> is a 1D image array object, <em>region</em>[2] must be 1.
The values in <em>region</em> cannot be 0.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>dst_offset</em> refers to the offset where to begin copying data into
<em>dst_buffer</em>.
The size in bytes of the region to be copied referred to as <em>dst_cb</em> is
@@ -11065,8 +11258,8 @@
as <em>width</em> × <em>bytes/image element</em> if <em>src_image</em> is a 1D image or 1D
image buffer object and is computed as <em>width</em> × <em>arraysize</em> ×
<em>bytes/image element</em> if <em>src_image</em> is a 1D image array object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
complete before this particular command can be executed.
If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
@@ -11080,128 +11273,135 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular copy command
and can be used to query or queue a wait for this particular command to
complete.
<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
application to query the status of this command or queue a wait for this
command to complete.
-<strong>clEnqueueBarrierWithWaitList</strong> can be used instead.
+<a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> can be used instead.
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueCopyImageToBuffer</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clEnqueueCopyImageToBuffer"><strong>clEnqueueCopyImageToBuffer</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em>,
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em>,
<em>src_image</em> and <em>dst_buffer</em> are not the same or if the context
associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not
the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>src_image</em> is not a valid image object or
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>src_image</em> is not a valid image object or
<em>dst_buffer</em> is not a valid buffer object or if <em>src_image</em> is a 1D
image buffer object created from <em>dst_buffer</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if the 1D, 2D or 3D rectangular region specified by
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the 1D, 2D or 3D rectangular region specified by
<em>src_origin</em> and <em>src_origin</em> + <em>region</em> refers to a region outside
<em>src_image</em>, or if the region specified by <em>dst_offset</em> and <em>dst_offset</em>
+ <em>dst_cb</em> to a region outside <em>dst_buffer</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values in <em>src_origin</em> and <em>region</em> do not follow
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values in <em>src_origin</em> and <em>region</em> do not follow
rules described in the argument description for <em>src_origin</em> and
<em>region</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>dst_buffer</em> is a sub-buffer object
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>dst_buffer</em> is a sub-buffer object
and <em>offset</em> specified when the sub-buffer object is created is not
-aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated
+aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated
with <em>queue</em>.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_SIZE if image dimensions (image width, height,
+<p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_​INVALID_​IMAGE_​SIZE</code></a> if image dimensions (image width, height,
specified or compute row and/or slice pitch) for <em>src_image</em> are not
supported by device associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_NOT_SUPPORTED if image format (image channel order and
+<p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED</code></a> if image format (image channel order and
data type) for <em>src_image</em> are not supported by device associated with
<em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>src_image</em> or <em>dst_buffer</em>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if the device associated with <em>command_queue</em> does
-not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the
-<a href="#device-queries-table">Device Queries</a> table is CL_FALSE).</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if the device associated with <em>command_queue</em> does
+not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> specified in the
+<a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>).</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>The function</p>
</div>
-<div class="listingblock">
+</div>
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clEnqueueCopyBufferToImage(cl_command_queue command_queue,
- cl_mem src_buffer,
- cl_mem dst_image,
- size_t src_offset,
- <span class="directive">const</span> size_t *dst_origin,
- <span class="directive">const</span> size_t *region,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to copy a buffer object to an image object.</p>
+<p>To enqueue a command to copy a buffer object to an image object, call the
+function</p>
</div>
-<div class="paragraph">
+<div id="clEnqueueCopyBufferToImage" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clEnqueueCopyBufferToImage(
+ cl_command_queue command_queue,
+ cl_mem src_buffer,
+ cl_mem dst_image,
+ size_t src_offset,
+ <span class="directive">const</span> size_t* dst_origin,
+ <span class="directive">const</span> size_t* region,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> must be a valid host command-queue.
The OpenCL context associated with <em>command_queue</em>, <em>src_buffer</em> and
<em>dst_image</em> must be the same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>src_buffer</em> is a valid buffer object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>dst_image</em> is a valid image object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>src_offset</em> refers to the offset where to begin copying data from
<em>src_buffer</em>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>dst_origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or
3D image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or
the (<em>x</em>) offset and the image index in the 1D image array.
@@ -11213,8 +11413,8 @@
image index in the 1D image array.
If <em>dst_image</em> is a 2D image array object, <em>dst_origin</em>[2] describes the
image index in the 2D image array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or
3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the
number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D
@@ -11224,6 +11424,35 @@
<em>region</em>[2] must be 1.
If <em>dst_image</em> is a 1D image array object, <em>region</em>[2] must be 1.
The values in <em>region</em> cannot be 0.</p>
+</li>
+<li>
+<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
+complete before this particular command can be executed.
+If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
+on any event to complete.
+If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0.
+If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by
+<em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be
+greater than 0.
+The events specified in <em>event_wait_list</em> act as synchronization points.
+The context associated with events in <em>event_wait_list</em> and <em>command_queue</em>
+must be the same.
+The memory associated with <em>event_wait_list</em> can be reused or freed after
+the function returns.</p>
+</li>
+<li>
+<p><em>event</em> returns an event object that identifies this particular copy command
+and can be used to query or queue a wait for this particular command to
+complete.
+<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
+application to query the status of this command or queue a wait for this
+command to complete.
+<a href="#clEnqueueBarrierWithWaitList"><strong>clEnqueueBarrierWithWaitList</strong></a> can be used instead.
+If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
+<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
+array.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
<p>The size in bytes of the region to be copied from <em>src_buffer</em> referred to
@@ -11238,164 +11467,127 @@
object.</p>
</div>
<div class="paragraph">
-<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
-complete before this particular command can be executed.
-If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait
-on any event to complete.
-If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0.
-If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by
-<em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be
-greater than 0.
-The events specified in <em>event_wait_list</em> act as synchronization points.
-The context associated with events in <em>event_wait_list</em> and <em>command_queue</em>
-must be the same.
-The memory associated with <em>event_wait_list</em> can be reused or freed after
-the function returns.</p>
-</div>
-<div class="paragraph">
-<p><em>event</em> returns an event object that identifies this particular copy command
-and can be used to query or queue a wait for this particular command to
-complete.
-<em>event</em> can be <code>NULL</code> in which case it will not be possible for the
-application to query the status of this command or queue a wait for this
-command to complete.
-<strong>clEnqueueBarrierWithWaitList</strong> can be used instead.
-If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
-<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
-array.</p>
-</div>
-<div class="paragraph">
-<p><strong>clEnqueueCopyBufferToImage</strong> returns CL_SUCCESS if the function is executed
+<p><a href="#clEnqueueCopyBufferToImage"><strong>clEnqueueCopyBufferToImage</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
successfully.
Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if the context associated with <em>command_queue</em>,
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if the context associated with <em>command_queue</em>,
<em>src_buffer</em> and <em>dst_image</em> are not the same or if the context
associated with <em>command_queue</em> and events in <em>event_wait_list</em> are not
the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>src_buffer</em> is not a valid buffer object or
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>src_buffer</em> is not a valid buffer object or
<em>dst_image</em> is not a valid image object or if <em>dst_image</em> is a 1D image
buffer object created from <em>src_buffer</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if the 1D, 2D or 3D rectangular region specified by
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if the 1D, 2D or 3D rectangular region specified by
<em>dst_origin</em> and <em>dst_origin</em> + <em>region</em> refer to a region outside
<em>dst_image</em>, or if the region specified by <em>src_offset</em> and <em>src_offset</em>
+ <em>src_cb</em> refer to a region outside <em>src_buffer</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values in <em>dst_origin</em> and <em>region</em> do not follow
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values in <em>dst_origin</em> and <em>region</em> do not follow
rules described in the argument description for <em>dst_origin</em> and
<em>region</em>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_MISALIGNED_SUB_BUFFER_OFFSET if <em>src_buffer</em> is a sub-buffer object
+<p><a href="#CL_MISALIGNED_SUB_BUFFER_OFFSET"><code>CL_​MISALIGNED_​SUB_​BUFFER_​OFFSET</code></a> if <em>src_buffer</em> is a sub-buffer object
and <em>offset</em> specified when the sub-buffer object is created is not
-aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated
+aligned to <a href="#CL_DEVICE_MEM_BASE_ADDR_ALIGN"><code>CL_​DEVICE_​MEM_​BASE_​ADDR_​ALIGN</code></a> value for device associated
with <em>queue</em>.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_SIZE if image dimensions (image width, height,
+<p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_​INVALID_​IMAGE_​SIZE</code></a> if image dimensions (image width, height,
specified or compute row and/or slice pitch) for <em>dst_image</em> are not
supported by device associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_NOT_SUPPORTED if image format (image channel order and
+<p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED</code></a> if image format (image channel order and
data type) for <em>dst_image</em> are not supported by device associated with
<em>queue</em>.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>src_buffer</em> or <em>dst_image</em>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if the device associated with <em>command_queue</em> does
-not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the
-<a href="#device-queries-table">Device Queries</a> table is CL_FALSE).</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if the device associated with <em>command_queue</em> does
+not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> specified in the
+<a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>).</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_mapping_image_objects">5.3.6. Mapping Image Objects</h4>
-<div class="paragraph">
-<p>The function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c"><span class="directive">void</span>* clEnqueueMapImage(cl_command_queue command_queue,
- cl_mem image,
- cl_bool blocking_map,
- cl_map_flags map_flags,
- <span class="directive">const</span> size_t *origin,
- <span class="directive">const</span> size_t *region,
- size_t *image_row_pitch,
- size_t *image_slice_pitch,
- cl_uint num_events_in_wait_list,
- <span class="directive">const</span> cl_event *event_wait_list,
- cl_event *event,
- cl_int *errcode_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p>enqueues a command to map a region in the image object given by <em>image</em> into
-the host address space and returns a pointer to this mapped region.</p>
+<p>To enqueue a command to map a region in the image object given by <em>image</em>
+into the host address space and returns a pointer to this mapped region,
+call the function</p>
</div>
-<div class="paragraph">
+<div id="clEnqueueMapImage" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span>* clEnqueueMapImage(
+ cl_command_queue command_queue,
+ cl_mem image,
+ cl_bool blocking_map,
+ cl_map_flags map_flags,
+ <span class="directive">const</span> size_t* origin,
+ <span class="directive">const</span> size_t* region,
+ size_t* image_row_pitch,
+ size_t* image_slice_pitch,
+ cl_uint num_events_in_wait_list,
+ <span class="directive">const</span> cl_event* event_wait_list,
+ cl_event* event,
+ cl_int* errcode_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>command_queue</em> must be a valid host command-queue.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image</em> is a valid image object.
The OpenCL context associated with <em>command_queue</em> and <em>image</em> must be the
same.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>blocking_map</em> indicates if the map operation is <em>blocking</em> or
<em>non-blocking</em>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_map</em> is CL_TRUE, <strong>clEnqueueMapImage</strong> does not return until the
-specified region in <em>image</em> is mapped into the host address space and the
-application can access the contents of the mapped region using the pointer
-returned by <strong>clEnqueueMapImage</strong>.</p>
-</div>
-<div class="paragraph">
-<p>If <em>blocking_map</em> is CL_FALSE i.e. map operation is non-blocking, the
-pointer to the mapped region returned by <strong>clEnqueueMapImage</strong> cannot be used
-until the map command has completed.
-The <em>event</em> argument returns an event object which can be used to query the
-execution status of the map command.
-When the map command is completed, the application can access the contents
-of the mapped region using the pointer returned by <strong>clEnqueueMapImage</strong>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>map_flags</em> is a bit-field and is described in the
<a href="#memory-map-flags-table">Memory Map Flags</a> table.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>origin</em> defines the (<em>x</em>, <em>y</em>, <em>z</em>) offset in pixels in the 1D, 2D or 3D
image, the (<em>x</em>, <em>y</em>) offset and the image index in the 2D image array or
the (<em>x</em>) offset and the image index in the 1D image array.
@@ -11407,8 +11599,8 @@
in the 1D image array.
If <em>image</em> is a 2D image array object, <em>origin</em>[2] describes the image index
in the 2D image array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>region</em> defines the (<em>width</em>, <em>height</em>, <em>depth</em>) in pixels of the 1D, 2D or
3D rectangle, the (<em>width</em>, <em>height</em>) in pixels of the 2D rectangle and the
number of images of a 2D image array or the (<em>width</em>) in pixels of the 1D
@@ -11418,24 +11610,24 @@
<em>region</em>[2] must be 1.
If <em>image</em> is a 1D image array object, <em>region</em>[2] must be 1.
The values in <em>region</em> cannot be 0.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image_row_pitch</em> returns the scan-line pitch in bytes for the mapped
region.
This must be a non-<code>NULL</code> value.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>image_slice_pitch</em> returns the size in bytes of each 2D slice of a 3D image
or the size of each 1D or 2D image in a 1D or 2D image array for the mapped
region.
For a 1D and 2D image, zero is returned if this argument is not <code>NULL</code>.
For a 3D image, 1D and 2D image array, <em>image_slice_pitch</em> must be a
non-<code>NULL</code> value.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to
-complete before <strong>clEnqueueMapImage</strong> can be executed.
-If <em>event_wait_list</em> is <code>NULL</code>, then <strong>clEnqueueMapImage</strong> does not wait on
+complete before <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> can be executed.
+If <em>event_wait_list</em> is <code>NULL</code>, then <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> does not wait on
any event to complete.
If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0.
If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by
@@ -11446,8 +11638,8 @@
must be the same.
The memory associated with <em>event_wait_list</em> can be reused or freed after
the function returns.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>event</em> returns an event object that identifies this particular command and
can be used to query or queue a wait for this particular command to
complete.
@@ -11457,14 +11649,31 @@
If the <em>event_wait_list</em> and the <em>event</em> arguments are not <code>NULL</code>, the
<em>event</em> argument should not refer to an element of the <em>event_wait_list</em>
array.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>errcode_ret</em> will return an appropriate error code.
If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clEnqueueMapImage</strong> will return a pointer to the mapped region.
-The <em>errcode_ret</em> is set to CL_SUCCESS.</p>
+<p>If <em>blocking_map</em> is <a href="#CL_TRUE"><code>CL_​TRUE</code></a>, <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> does not return until the
+specified region in <em>image</em> is mapped into the host address space and the
+application can access the contents of the mapped region using the pointer
+returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>.</p>
+</div>
+<div class="paragraph">
+<p>If <em>blocking_map</em> is <a href="#CL_FALSE"><code>CL_​FALSE</code></a> i.e. map operation is non-blocking, the
+pointer to the mapped region returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> cannot be used
+until the map command has completed.
+The <em>event</em> argument returns an event object which can be used to query the
+execution status of the map command.
+When the map command is completed, the application can access the contents
+of the mapped region using the pointer returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>.</p>
+</div>
+<div class="paragraph">
+<p><a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> will return a pointer to the mapped region.
+The <em>errcode_ret</em> is set to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a>.</p>
</div>
<div class="paragraph">
<p>A <code>NULL</code> pointer is returned otherwise with one of the following error
@@ -11473,86 +11682,86 @@
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_COMMAND_QUEUE if <em>command_queue</em> is not a valid host
+<p><a href="#CL_INVALID_COMMAND_QUEUE"><code>CL_​INVALID_​COMMAND_​QUEUE</code></a> if <em>command_queue</em> is not a valid host
command-queue.</p>
</li>
<li>
-<p>CL_INVALID_CONTEXT if context associated with <em>command_queue</em> and
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if context associated with <em>command_queue</em> and
<em>image</em> are not the same or if context associated with <em>command_queue</em>
and events in <em>event_wait_list</em> are not the same.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>image</em> is not a valid image object.</p>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>image</em> is not a valid image object.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if region being mapped given by (<em>origin</em>,
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if region being mapped given by (<em>origin</em>,
<em>origin+region</em>) is out of bounds or if values specified in <em>map_flags</em>
are not valid.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values in <em>origin</em> and <em>region</em> do not follow rules
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values in <em>origin</em> and <em>region</em> do not follow rules
described in the argument description for <em>origin</em> and <em>region</em>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>image_row_pitch</em> is <code>NULL</code>.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>image_row_pitch</em> is <code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>image</em> is a 3D image, 1D or 2D image array object
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>image</em> is a 3D image, 1D or 2D image array object
and <em>image_slice_pitch</em> is <code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_EVENT_WAIT_LIST if <em>event_wait_list</em> is <code>NULL</code> and
+<p><a href="#CL_INVALID_EVENT_WAIT_LIST"><code>CL_​INVALID_​EVENT_​WAIT_​LIST</code></a> if <em>event_wait_list</em> is <code>NULL</code> and
<em>num_events_in_wait_list</em> > 0, or <em>event_wait_list</em> is not <code>NULL</code> and
<em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em>
are not valid events.</p>
</li>
<li>
-<p>CL_INVALID_IMAGE_SIZE if image dimensions (image width, height,
+<p><a href="#CL_INVALID_IMAGE_SIZE"><code>CL_​INVALID_​IMAGE_​SIZE</code></a> if image dimensions (image width, height,
specified or compute row and/or slice pitch) for <em>image</em> are not
supported by device associated with <em>queue</em>.</p>
</li>
<li>
-<p>CL_IMAGE_FORMAT_NOT_SUPPORTED if image format (image channel order and
+<p><a href="#CL_IMAGE_FORMAT_NOT_SUPPORTED"><code>CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED</code></a> if image format (image channel order and
data type) for <em>image</em> are not supported by device associated with
<em>queue</em>.</p>
</li>
<li>
-<p>CL_MAP_FAILURE if there is a failure to map the requested region into
+<p><a href="#CL_MAP_FAILURE"><code>CL_​MAP_​FAILURE</code></a> if there is a failure to map the requested region into
the host address space.
This error cannot occur for image objects created with
-CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR.</p>
+<a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> or <a href="#CL_MEM_ALLOC_HOST_PTR"><code>CL_​MEM_​ALLOC_​HOST_​PTR</code></a>.</p>
</li>
<li>
-<p>CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the map operation is
+<p><a href="#CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST"><code>CL_​EXEC_​STATUS_​ERROR_​FOR_​EVENTS_​IN_​WAIT_​LIST</code></a> if the map operation is
blocking and the execution status of any of the events in
<em>event_wait_list</em> is a negative integer value.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for data store associated with <em>image</em>.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if the device associated with <em>command_queue</em> does
-not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the
-<a href="#device-queries-table">Device Queries</a> table is CL_FALSE).</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if the device associated with <em>command_queue</em> does
+not support images (i.e. <a href="#CL_DEVICE_IMAGE_SUPPORT"><code>CL_​DEVICE_​IMAGE_​SUPPORT</code></a> specified in the
+<a href="#device-queries-table">Device Queries</a> table is <a href="#CL_FALSE"><code>CL_​FALSE</code></a>).</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if <em>image</em> has been created with
-CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_NO_ACCESS and CL_MAP_READ is set
-in <em>map_flags</em> or if <em>image</em> has been created with CL_MEM_HOST_READ_ONLY
-or CL_MEM_HOST_NO_ACCESS and CL_MAP_WRITE or
-CL_MAP_WRITE_INVALIDATE_REGION is set in <em>map_flags</em>.</p>
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if <em>image</em> has been created with
+<a href="#CL_MEM_HOST_WRITE_ONLY"><code>CL_​MEM_​HOST_​WRITE_​ONLY</code></a> or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> and <a href="#CL_MAP_READ"><code>CL_​MAP_​READ</code></a> is set
+in <em>map_flags</em> or if <em>image</em> has been created with <a href="#CL_MEM_HOST_READ_ONLY"><code>CL_​MEM_​HOST_​READ_​ONLY</code></a>
+or <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> and <a href="#CL_MAP_WRITE"><code>CL_​MAP_​WRITE</code></a> or
+<a href="#CL_MAP_WRITE_INVALIDATE_REGION"><code>CL_​MAP_​WRITE_​INVALIDATE_​REGION</code></a> is set in <em>map_flags</em>.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
<li>
-<p>CL_INVALID_OPERATION if mapping would lead to overlapping regions being
+<p><a href="#CL_INVALID_OPERATION"><code>CL_​INVALID_​OPERATION</code></a> if mapping would lead to overlapping regions being
mapped for writing.</p>
</li>
</ul>
@@ -11566,101 +11775,84 @@
The result of a memory access outside this region is undefined.</p>
</div>
<div class="paragraph">
-<p>If the image object is created with CL_MEM_USE_HOST_PTR set in <em>mem_flags</em>,
+<p>If the image object is created with <a href="#CL_MEM_USE_HOST_PTR"><code>CL_​MEM_​USE_​HOST_​PTR</code></a> set in <em>mem_flags</em>,
the following will be true:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>The <em>host_ptr</em> specified in <strong>clCreateImage</strong> is guaranteed to contain the
-latest bits in the region being mapped when the <strong>clEnqueueMapImage</strong>
+<p>The <em>host_ptr</em> specified in <a href="#clCreateImage"><strong>clCreateImage</strong></a> is guaranteed to contain the
+latest bits in the region being mapped when the <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a>
command has completed.</p>
</li>
<li>
-<p>The pointer value returned by <strong>clEnqueueMapImage</strong> will be derived from
+<p>The pointer value returned by <a href="#clEnqueueMapImage"><strong>clEnqueueMapImage</strong></a> will be derived from
the <em>host_ptr</em> specified when the image object is created.</p>
</li>
</ul>
</div>
<div class="paragraph">
-<p>Mapped image objects are unmapped using <strong>clEnqueueUnmapMemObject</strong>.
+<p>Mapped image objects are unmapped using <a href="#clEnqueueUnmapMemObject"><strong>clEnqueueUnmapMemObject</strong></a>.
This is described in <a href="#unmapping-mapped-memory">Unmapping Mapped Memory
Objects</a>.</p>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="image-object-queries">5.3.7. Image Object Queries</h4>
<div class="paragraph">
<p>To get information that is common to all memory objects, use the
-<strong>clGetMemObjectInfo</strong> function described in <a href="#memory-object-queries">Memory
+<a href="#clGetMemObjectInfo"><strong>clGetMemObjectInfo</strong></a> function described in <a href="#memory-object-queries">Memory
Object Queries</a>.</p>
</div>
-<div class="paragraph">
-<p>To get information specific to an image object created with <strong>clCreateImage</strong>,
-use the following function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetImageInfo(cl_mem image,
- cl_image_info param_name,
- size_t param_value_size,
- <span class="directive">void</span> *param_value,
- size_t *param_value_size_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
-<p><em>image</em> specifies the image object being queried.</p>
+<p>To get information specific to an image object created with <a href="#clCreateImage"><strong>clCreateImage</strong></a>,
+call the function</p>
</div>
-<div class="paragraph">
-<p><em>param_name</em> specifies the information to query.
-The list of supported <em>param_name</em> types and the information returned in
-<em>param_value</em> by <strong>clGetImageInfo</strong> is described in the
-<a href="#image-info-table">Image Object Queries</a> table.</p>
+<div id="clGetImageInfo" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_int clGetImageInfo(
+ cl_mem image,
+ cl_image_info param_name,
+ size_t param_value_size,
+ <span class="directive">void</span>* param_value,
+ size_t* param_value_size_ret);</code></pre>
</div>
-<div class="paragraph">
-<p><em>param_value</em> is a pointer to memory where the appropriate result being
-queried is returned.
-If <em>param_value</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
-<p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to
-by <em>param_value</em>.
-This size must be ≥ size of return type as described in the
-<a href="#image-info-table">Image Object Queries</a> table.</p>
-</div>
-<div class="paragraph">
-<p><em>param_value_size_ret</em> returns the actual size in bytes of data being
-queried by <em>param_name</em>.
-If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p>
-</div>
-<div class="paragraph">
-<p><strong>clGetImageInfo</strong> returns CL_SUCCESS if the function is executed
-successfully.
-Otherwise, it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_VALUE if <em>param_name</em> is not valid, or if size in bytes
-specified by <em>param_value_size</em> is < size of return type as described in
-the <a href="#image-info-table">Image Object Queries</a> table and <em>param_value</em> is
-not <code>NULL</code>.</p>
+<p><em>image</em> specifies the image object being queried.</p>
</li>
<li>
-<p>CL_INVALID_MEM_OBJECT if <em>image</em> is a not a valid image object.</p>
+<p><em>param_name</em> specifies the information to query.
+The list of supported <em>param_name</em> types and the information returned in
+<em>param_value</em> by <a href="#clGetImageInfo"><strong>clGetImageInfo</strong></a> is described in the
+<a href="#image-info-table">Image Object Queries</a> table.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
-by the OpenCL implementation on the device.</p>
+<p><em>param_value</em> is a pointer to memory where the appropriate result being
+queried is returned.
+If <em>param_value</em> is <code>NULL</code>, it is ignored.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
-required by the OpenCL implementation on the host.</p>
+<p><em>param_value_size</em> is used to specify the size in bytes of memory pointed to
+by <em>param_value</em>.
+This size must be ≥ size of return type as described in the
+<a href="#image-info-table">Image Object Queries</a> table.</p>
+</li>
+<li>
+<p><em>param_value_size_ret</em> returns the actual size in bytes of data being
+queried by <em>param_name</em>.
+If <em>param_value_size_ret</em> is <code>NULL</code>, it is ignored.</p>
</li>
</ul>
</div>
<table id="image-info-table" class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 19. List of supported param_names by <strong>clGetImageInfo</strong></caption>
+<caption class="title">Table 18. List of supported param_names by <a href="#clGetImageInfo">clGetImageInfo</a></caption>
<colgroup>
<col style="width: 34%;">
<col style="width: 33%;">
@@ -11675,13 +11867,13 @@
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_FORMAT</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_FORMAT"></a><a href="#CL_IMAGE_FORMAT"><code>CL_​IMAGE_​FORMAT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_image_format</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return image format descriptor specified when <em>image</em> is created
- with <strong>clCreateImage</strong>.</p></td>
+ with <a href="#clCreateImage"><strong>clCreateImage</strong></a>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_ELEMENT_SIZE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_ELEMENT_SIZE"></a><a href="#CL_IMAGE_ELEMENT_SIZE"><code>CL_​IMAGE_​ELEMENT_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return size of each element of the image memory object given by
<em>image</em> in bytes.
@@ -11689,13 +11881,13 @@
The value of <em>n</em> is given in <em>cl_image_format</em> descriptor.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_ROW_PITCH</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_ROW_PITCH"></a><a href="#CL_IMAGE_ROW_PITCH"><code>CL_​IMAGE_​ROW_​PITCH</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return calculated row pitch in bytes of a row of elements of the
image object given by <em>image</em>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_SLICE_PITCH</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_SLICE_PITCH"></a><a href="#CL_IMAGE_SLICE_PITCH"><code>CL_​IMAGE_​SLICE_​PITCH</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return calculated slice pitch in bytes of a 2D slice for the 3D
image object or size of each image in a 1D or 2D image array given
@@ -11703,42 +11895,70 @@
For a 1D image, 1D image buffer and 2D image object return 0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_WIDTH</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_WIDTH"></a><a href="#CL_IMAGE_WIDTH"><code>CL_​IMAGE_​WIDTH</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return width of the image in pixels.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_HEIGHT</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_HEIGHT"></a><a href="#CL_IMAGE_HEIGHT"><code>CL_​IMAGE_​HEIGHT</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return height of the image in pixels.
For a 1D image, 1D image buffer and 1D image array object, height =
0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_DEPTH</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_DEPTH"></a><a href="#CL_IMAGE_DEPTH"><code>CL_​IMAGE_​DEPTH</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return depth of the image in pixels.
For a 1D image, 1D image buffer, 2D image or 1D and 2D image array
object, depth = 0.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_ARRAY_SIZE</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_ARRAY_SIZE"></a><a href="#CL_IMAGE_ARRAY_SIZE"><code>CL_​IMAGE_​ARRAY_​SIZE</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">size_t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Return number of images in the image array.
If <em>image</em> is not an image array, 0 is returned.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_NUM_MIP_LEVELS</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_NUM_MIP_LEVELS"></a><a href="#CL_IMAGE_NUM_MIP_LEVELS"><code>CL_​IMAGE_​NUM_​MIP_​LEVELS</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Return num_mip_levels associated with <em>image</em>.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Return <code>num_mip_levels</code> associated with <em>image</em>.</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CL_IMAGE_NUM_SAMPLES</strong></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="CL_IMAGE_NUM_SAMPLES"></a><a href="#CL_IMAGE_NUM_SAMPLES"><code>CL_​IMAGE_​NUM_​SAMPLES</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cl_uint</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Return num_samples associated with <em>image</em>.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Return <code>num_samples</code> associated with <em>image</em>.</p></td>
</tr>
</tbody>
</table>
+<div class="paragraph">
+<p><a href="#clGetImageInfo"><strong>clGetImageInfo</strong></a> returns <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the function is executed
+successfully.
+Otherwise, it returns one of the following errors:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>param_name</em> is not valid, or if size in bytes
+specified by <em>param_value_size</em> is < size of return type as described in
+the <a href="#image-info-table">Image Object Queries</a> table and <em>param_value</em> is
+not <code>NULL</code>.</p>
+</li>
+<li>
+<p><a href="#CL_INVALID_MEM_OBJECT"><code>CL_​INVALID_​MEM_​OBJECT</code></a> if <em>image</em> is a not a valid image object.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
+by the OpenCL implementation on the device.</p>
+</li>
+<li>
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
+required by the OpenCL implementation on the host.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
</div>
</div>
<div class="sect2">
@@ -11768,86 +11988,93 @@
</div>
<div class="sect3">
<h4 id="_creating_pipe_objects">5.4.1. Creating Pipe Objects</h4>
-<div class="paragraph">
-<p>A <strong>pipe object</strong> is created using the following function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_mem clCreatePipe(cl_context context,
- cl_mem_flags flags,
- cl_uint pipe_packet_size,
- cl_uint pipe_max_packets,
- <span class="directive">const</span> cl_pipe_properties *properties,
- cl_int *errcode_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
+<p>To create a <strong>pipe object</strong>, call the function</p>
+</div>
+<div id="clCreatePipe" class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c++">cl_mem clCreatePipe(
+ cl_context context,
+ cl_mem_flags flags,
+ cl_uint pipe_packet_size,
+ cl_uint pipe_max_packets,
+ <span class="directive">const</span> cl_pipe_properties* properties,
+ cl_int* errcode_ret);</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
<p><em>context</em> is a valid OpenCL context used to create the pipe object.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>flags</em> is a bit-field that is used to specify allocation and usage
information such as the memory arena that should be used to allocate the
pipe object and how it will be used.
The <a href="#memory-flags">Memory Flags</a> table describes the possible values for
<em>flags</em>.
-Only CL_MEM_READ_WRITE and CL_MEM_HOST_NO_ACCESS can be specified when
+Only <a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> and <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a> can be specified when
creating a pipe object.
If the value specified for <em>flags</em> is 0, the default is used which is
-CL_MEM_READ_WRITE | CL_MEM_HOST_NO_ACCESS.</p>
-</div>
-<div class="paragraph">
+<a href="#CL_MEM_READ_WRITE"><code>CL_​MEM_​READ_​WRITE</code></a> | <a href="#CL_MEM_HOST_NO_ACCESS"><code>CL_​MEM_​HOST_​NO_​ACCESS</code></a>.</p>
+</li>
+<li>
<p><em>pipe_packet_size</em> is the size in bytes of a pipe packet.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>pipe_max_packets</em> specifies the pipe capacity by specifying the maximum
number of packets the pipe can hold.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>properties</em> specifies a list of properties for the pipe and their
corresponding values.
Each property name is immediately followed by the corresponding desired
value.
The list is terminated with 0.
In OpenCL 2.2, <em>properties</em> must be <code>NULL</code>.</p>
-</div>
-<div class="paragraph">
+</li>
+<li>
<p><em>errcode_ret</em> will return an appropriate error code.
If <em>errcode_ret</em> is <code>NULL</code>, no error code is returned.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p><strong>clCreatePipe</strong> returns a valid non-zero pipe object and <em>errcode_ret</em> is set
-to CL_SUCCESS if the pipe object is created successfully.
+<p><a href="#clCreatePipe"><strong>clCreatePipe</strong></a> returns a valid non-zero pipe object and <em>errcode_ret</em> is set
+to <a href="#CL_SUCCESS"><code>CL_​SUCCESS</code></a> if the pipe object is created successfully.
Otherwise, it returns a <code>NULL</code> value with one of the following error values
returned in <em>errcode_ret</em>:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>CL_INVALID_CONTEXT if <em>context</em> is not a valid context.</p>
+<p><a href="#CL_INVALID_CONTEXT"><code>CL_​INVALID_​CONTEXT</code></a> if <em>context</em> is not a valid context.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if values specified in <em>flags</em> are not as defined
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if values specified in <em>flags</em> are not as defined
above.</p>
</li>
<li>
-<p>CL_INVALID_VALUE if <em>properties</em> is not <code>NULL</code>.</p>
+<p><a href="#CL_INVALID_VALUE"><code>CL_​INVALID_​VALUE</code></a> if <em>properties</em> is not <code>NULL</code>.</p>
</li>
<li>
-<p>CL_INVALID_PIPE_SIZE if <em>pipe_packet_size</em> is 0 or the
-<em>pipe_packet_size</em> exceeds CL_DEVICE_PIPE_MAX_PACKET_SIZE value
+<p><a href="#CL_INVALID_PIPE_SIZE"><code>CL_​INVALID_​PIPE_​SIZE</code></a> if <em>pipe_packet_size</em> is 0 or the
+<em>pipe_packet_size</em> exceeds <a href="#CL_DEVICE_PIPE_MAX_PACKET_SIZE"><code>CL_​DEVICE_​PIPE_​MAX_​PACKET_​SIZE</code></a> value
specified in the <a href="#device-queries-table">Device Queries</a> table for all
devices in <em>context</em> or if <em>pipe_max_packets</em> is 0.</p>
</li>
<li>
-<p>CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate
+<p><a href="#CL_MEM_OBJECT_ALLOCATION_FAILURE"><code>CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE</code></a> if there is a failure to allocate
memory for the pipe object.</p>
</li>
<li>
-<p>CL_OUT_OF_RESOURCES if there is a failure to allocate resources required
+<p><a href="#CL_OUT_OF_RESOURCES"><code>CL_​OUT_​OF_​RESOURCES</code></a> if there is a failure to allocate resources required
by the OpenCL implementation on the device.</p>
</li>
<li>
-<p>CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
+<p><a href="#CL_OUT_OF_HOST_MEMORY"><code>CL_​OUT_​OF_​HOST_​MEMORY</code></a> if there is a failure to allocate resources
required by the OpenCL implementation on the host.</p>
</li>
</ul>
@@ -11859,78 +12086,87 @@
same or different devices) is enforced at a synchronization point.</p>
</div>
</div>
+</div>
+</div>
<div class="sect3">
<h4 id="_pipe_object_queries">5.4.2. Pipe Object Queries</h4>
<div class="paragraph">
<p>To get information that is common to all memory objects, use the
-<strong>clGetMemObjectInfo</strong> function described in <a href="#memory-object-queries">Memory
+<a href="#clGetMemObjectInfo"><strong>clGetMemObjectInfo</strong></a> function described in <a href="#memory-object-queries">Memory
Object Queries</a>.</p>
</div>
-<div class="paragraph">
-<p>To get information specific to a pipe object created with <strong>clCreatePipe</strong>,
-use the following function</p>
-</div>
-<div class="listingblock">
+<div class="openblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c">cl_int clGetPipeInfo(cl_mem pipe,
- cl_pipe_info param_name,
- size_t param_value_size,
- <span class="directive">void</span> *param_value,
- size_t *param_value_size_ret)</code></pre>
-</div>
-</div>
<div class="paragraph">
+<p>To get information specific to a pipe object created with <a href="#clCreatePipe"><strong>clCreatePipe</strong></a>,