1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
8
<keyword>clEnqueueCopyBufferToImage</keyword>
14
clEnqueueCopyBufferToImage
19
<year>2007-2011</year>
20
<holder>The Khronos Group Inc.
21
Permission is hereby granted, free of charge, to any person obtaining a
22
copy of this software and/or associated documentation files (the
23
"Materials"), to deal in the Materials without restriction, including
24
without limitation the rights to use, copy, modify, merge, publish,
25
distribute, sublicense, and/or sell copies of the Materials, and to
26
permit persons to whom the Materials are furnished to do so, subject to
27
the condition that this copyright notice and permission notice shall be included
28
in all copies or substantial portions of the Materials.</holder>
31
<manvolnum>3</manvolnum>
34
<!-- ================================ SYNOPSIS -->
36
<refnamediv id="clEnqueueCopyBufferToImage">
38
clEnqueueCopyBufferToImage
42
Enqueues a command to copy a buffer object to an image object.
46
<refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
50
<link xlink:href="scalarDataTypes.html">cl_int</link>
51
<function>clEnqueueCopyBufferToImage</function>
53
<paramdef><link xlink:href="abstractDataTypes.html">cl_command_queue</link><parameter>command_queue</parameter></paramdef>
54
<paramdef><link xlink:href="abstractDataTypes.html">cl_mem</link><parameter>src_buffer</parameter></paramdef>
55
<paramdef><link xlink:href="abstractDataTypes.html">cl_mem</link> <parameter>dst_image</parameter></paramdef>
56
<paramdef><link xlink:href="scalarDataTypes.html">size_t</link><parameter>src_offset</parameter></paramdef>
57
<paramdef>const <link xlink:href="scalarDataTypes.html">size_t</link><parameter>*dst_origin</parameter></paramdef>
58
<paramdef>const <link xlink:href="scalarDataTypes.html">size_t</link><parameter>*region</parameter></paramdef>
59
<paramdef><link xlink:href="scalarDataTypes.html">cl_uint</link><parameter>num_events_in_wait_list</parameter></paramdef>
60
<paramdef>const <link xlink:href="abstractDataTypes.html">cl_event</link><parameter>*event_wait_list</parameter></paramdef>
61
<paramdef><link xlink:href="abstractDataTypes.html">cl_event</link><parameter>*event</parameter></paramdef>
66
<!-- ================================ PARAMETERS -->
68
<refsect1 id="parameters">
69
<title>Parameters</title>
73
<term> <varname> command_queue </varname> </term>
76
A valid command-queue. The OpenCL context associated with
77
<varname>command_queue</varname>, <varname>src_buffer</varname>, and
78
<varname>dst_image</varname> must be the same.
84
<term> <varname> src_buffer </varname> </term>
87
A valid buffer object.
93
<term> <varname> dst_image </varname> </term>
102
<term> <varname> src_offset </varname> </term>
105
The offset where to begin copying data from <varname>src_buffer</varname>.
111
<term> <varname> dst_origin </varname> </term>
114
Defines the (x, y, z) offset in pixels in the 1D, 2D or 3D image,
115
the (x, y) offset and the image index in the 2D image array or the
116
(x) offset and the image index in the 1D image array. If dst_image
117
is a 2D image object, <varname>dst_origin</varname>[2] must be 0.
118
If <varname>dst_image</varname> is a 1D image or 1D image buffer object,
119
<varname>dst_origin</varname>[1] and <varname>dst_origin</varname>[2]
120
must be 0. If <varname>dst_image</varname> is a 1D image array object,
121
<varname>dst_origin</varname>[2] must be 0. If <varname>dst_image</varname>
122
is a 1D image array object, <varname>dst_origin</varname>[1] describes
123
the image index in the 1D image array. If <varname>dst_image</varname>
124
is a 2D image array object, <varname>dst_origin</varname>[2] describes
125
the image index in the 2D image array.
131
<term> <varname> region </varname> </term>
134
Defines the (width, height, depth) in pixels of the 1D, 2D or 3D rectangle,
135
the (width, height) in pixels of the 2D rectangle and the number of images
136
of a 2D image array or the (width) in pixels of the 1D rectangle and the
137
number of images of a 1D image array. If <varname>dst_image</varname>
138
is a 2D image object, <varname>region</varname>[2] must be 1. If
139
<varname>dst_image</varname> is a 1D image or 1D image buffer object,
140
<varname>region</varname>[1] and <varname>region</varname>[2] must
141
be 1. If <varname>dst_image</varname> is a 1D image array object,
142
<varname>region</varname>[2] must be 1.
146
The size in bytes of the region to be copied
147
from <varname>src_buffer</varname> referred to as
148
<varname>src_cb</varname> is computed as <varname>width</varname>
149
* <varname>height</varname> * <varname>depth</varname> *
150
<varname>bytes</varname>/<varname>image_element</varname> if
151
<varname>dst_image</varname> is a 3D image object, is computed
152
as <varname>width</varname> * <varname>height</varname> *
153
<varname>bytes</varname>/<varname>image_element</varname>
154
if <varname>dst_image</varname> is a 2D
155
image, is computed as <varname>width</varname> *
156
<varname>height</varname> * <varname>arraysize</varname> *
157
<varname>bytes</varname>/<varname>image_element</varname>
158
if <varname>dst_image</varname> is a 2D image array
159
object, is computed as <varname>width</varname> *
160
<varname>bytes</varname>/<varname>image_element</varname> if
161
<varname>dst_image</varname> is a 1D image or 1D image buffer object and
162
is computed as <varname>width</varname> * <varname>arraysize</varname>
163
* <varname>bytes</varname>/<varname>image_element</varname> if
164
<varname>dst_image</varname> is a 1D image array object.
175
num_events_in_wait_list
181
Specify events that need to complete before this particular
182
command can be executed. If <varname>event_wait_list</varname>
183
is NULL, then this particular command does not wait on any
184
event to complete. If <varname>event_wait_list</varname> is
185
NULL, <varname>num_events_in_wait_list</varname> must be 0. If
186
<varname>event_wait_list</varname> is not NULL, the list of events
187
pointed to by <varname>event_wait_list</varname> must be valid
188
and <varname>num_events_in_wait_list</varname> must be greater
189
than 0. The events specified in <varname>event_wait_list</varname>
190
act as synchronization points. The context associated with events in
191
<varname>event_wait_list</varname> and <varname>command_queue</varname>
192
must be the same. The memory associated with event_wait_list can be
193
reused or freed after the function returns.
199
<term> <varname> event </varname> </term>
202
Returns an event object that identifies this particular copy command
203
and can be used to query or queue a wait for this particular
204
command to complete. <varname>event</varname> can be NULL in
205
which case it will not be possible for the application to query the
206
status of this command or queue a wait for this command to complete.
207
<citerefentry><refentrytitle>clEnqueueBarrierWithWaitList</refentrytitle></citerefentry>
208
can be used instead. If the <varname>event_wait_list</varname>
209
and the <varname>event</varname> arguments are not NULL, the
210
<varname>event</varname> argument should not refer to an element of the
211
<varname>event_wait_list</varname> array.
218
<!-- ================================ NOTES -->
219
<!-- Use <function /> to refer ONLY to the function that this page describes. All other functions should use
220
<citerefentry /><refentrytitle /> to make it a link. Use <varname /> for parameters. Use <constant /> for
221
constants (or anything to be set in monospace, non-bold type.
223
<refsect1 id="notes"><title>Notes</title>
230
<!-- ================================ ERRORS -->
232
<refsect1 id="errors"><title>Errors</title>
234
<function>clEnqueueCopyBufferToImage</function> returns <errorname>CL_SUCCESS</errorname>
235
if the function is executed successfully. Otherwise, it returns one of the following
239
<itemizedlist mark="disc">
241
<errorname>CL_INVALID_COMMAND_QUEUE</errorname> if <varname>command_queue</varname>
242
is not a valid command-queue.
246
<errorname>CL_INVALID_CONTEXT</errorname> if the context associated
247
with <varname>command_queue</varname>, <varname>src_buffer</varname> and
248
<varname>dst_image</varname> are not the same or if the context associated with
249
<varname>command_queue</varname> and events in <varname>event_wait_list</varname>
254
<errorname>CL_INVALID_MEM_OBJECT</errorname> if <varname>src_buffer</varname> is
255
not a valid buffer object and <varname>dst_image</varname> is not a valid image
256
object or if <varname>dst_image</varname> is a 1D image buffer object created
257
from <varname>src_buffer</varname>.
261
<errorname>CL_INVALID_VALUE</errorname> if the 1D, 2D, or 3D rectangular region
262
specified by <varname>dst_origin</varname> and <varname>dst_origin</varname> +
263
<varname>region</varname> refers to a region outside <varname>dst_origin</varname>,
264
or if the region specified by <varname>src_offset</varname> and
265
<varname>src_offset</varname> + <varname>src_cb</varname> refers to a region
266
outside <varname>src_buffer</varname>.
270
<errorname>CL_INVALID_VALUE</errorname> if values in <varname>dst_origin</varname>
271
and <varname>region</varname> do not follow rules described in the argument
272
description for <varname>dst_origin</varname> and <varname>region</varname>.
276
<errorname>CL_INVALID_EVENT_WAIT_LIST</errorname>
277
if <varname>event_wait_list</varname> is NULL and
278
<varname>num_events_in_wait_list</varname> > 0,
279
or <varname>event_wait_list</varname> is not NULL and
280
<varname>num_events_in_wait_list</varname> is 0, or if event objects in
281
<varname>event_wait_list</varname> are not valid events.
285
<errorname>CL_MISALIGNED_SUB_BUFFER_OFFSET</errorname> if
286
<varname>src_buffer</varname> is a sub-buffer object and <varname>offset</varname>
287
specified when the sub-buffer object is created is not aligned to
288
<constant>CL_DEVICE_MEM_BASE_ADDR_ALIGN</constant> value for device associated
289
with <varname>queue</varname>.
293
<errorname>CL_INVALID_IMAGE_SIZE</errorname> if image dimensions (image width,
294
height, specified or compute row and/or slice pitch) for <varname>dst_image</varname>
295
are not supported by device associated with <varname>queue</varname>.
299
<errorname>CL_INVALID_IMAGE_FORMAT</errorname> if image format (image channel
300
order and data type) for <varname>dst_image</varname> are not supported by device
301
associated with <varname>queue</varname>.
305
<errorname>CL_MEM_OBJECT_ALLOCATION_FAILURE</errorname> if there is a failure
306
to allocate memory for data store associated with <varname>src_buffer</varname>
307
or <varname>dst_image</varname>.
311
<errorname>CL_INVALID_OPERATION</errorname> if the device associated
312
with <varname>command_queue</varname> does not support images (i.e.
313
CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for
314
<citerefentry><refentrytitle>clGetDeviceInfo</refentrytitle></citerefentry>
319
<errorname>CL_OUT_OF_RESOURCES</errorname> if there is a failure to allocate
320
resources required by the OpenCL implementation on the device.
324
<errorname>CL_OUT_OF_HOST_MEMORY</errorname> if there is a failure to allocate
325
resources required by the OpenCL implementation on the host.
331
<!-- ================================ EXAMPLE -->
332
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
334
<refsect2 id="example1">
339
<informaltable frame="none">
340
<tgroup cols="1" align="left" colsep="0" rowsep="0">
341
<colspec colname="col1" colnum="1" />
345
Example goes here - it will be set in "code" type with white space preserved.
354
<!-- ================================ SPECIFICATION -->
355
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
357
<refsect1 id="specification"><title>Specification</title>
360
<imagedata fileref="pdficon_small1.gif" format="gif" />
363
<olink uri="clEnqueueCopyBufferToImage">OpenCL Specification</olink>
367
<!-- ================================ ALSO SEE -->
369
<refsect1 id="seealso"><title>Also see</title>
371
<citerefentry><refentrytitle>clEnqueueReadBuffer</refentrytitle></citerefentry>,
372
<citerefentry><refentrytitle>clEnqueueWriteBuffer</refentrytitle></citerefentry>,
373
<citerefentry><refentrytitle>clCreateBuffer</refentrytitle></citerefentry>,
374
<citerefentry><refentrytitle>clEnqueueCopyBuffer</refentrytitle></citerefentry>,
375
<citerefentry><refentrytitle>clEnqueueCopyImageToBuffer</refentrytitle></citerefentry>
379
<!-- ================================ COPYRIGHT -->
380
<!-- Content included from copyright.inc.xsl -->
382
<refsect3 id="Copyright"><title></title>
384
<imagedata fileref="KhronosLogo.jpg" format="jpg" />
added
removed
clEnqueueCopyBufferToImage.xml
