Enqueues a command to copy image objects.
cl_int clEnqueueCopyImage(cl_command_queue command_queue,
cl_mem src_image,
cl_mem dst_image,
const size_t *src_origin,
const size_t *dst_origin,
const size_t *region,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event)
command_queue
-
Refers to the host command-queue in which the copy command will be queued. The OpenCL context associated with
command_queue
,src_image
anddst_image
must be the same. src_image,
dst_image,
-
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.
src_origin
-
Defines the (x, y, z) offset in pixels in the 1D, 2D or 3D image, the (x, y) offset and the image index in the 2D image array or the (x) offset and the image index in the 1D image array. If
image
is a 2D image object,src_origin
[2] must be 0. Ifsrc_image
is a 1D image object,src_origin
[1] andsrc_origin
[2] must be 0. Ifsrc_image
is a 1D image array object,src_origin
[2] must be 0. Ifsrc_image
is a 1D image array object,src_origin
[1] describes the image index in the 1D image array. Ifsrc_image
is a 2D image array object,src_origin
[2] describes the image index in the 2D image array. dst_origin
-
Defines the (x, y, z) offset in pixels in the 1D, 2D or 3D image, the (x, y) offset and the image index in the 2D image array or the (x) offset and the image index in the 1D image array. If
dst_image
is a 2D image object,dst_origin
[2] must be 0. Ifdst_image
is a 1D image or 1D image buffer object,dst_origin
[1] anddst_origin
[2] must be 0. Ifdst_image
is a 1D image array object,dst_origin
[2] must be 0. Ifdst_image
is a 1D image array object,dst_origin
[1] describes the image index in the 1D image array. Ifdst_image
is a 2D image array object,dst_origin
[2] describes the image index in the 2D image array. region
-
Defines the (width, height, depth) in pixels of the 1D, 2D or 3D rectangle, the (width, height) in pixels of the 2D rectangle and the number of images of a 2D image array or the (width) in pixels of the 1D rectangle and the number of images of a 1D image array. If
src_image
ordst_image
is a 2D image object,region
[2] must be 1. Ifsrc_image
ordst_image
is a 1D image or 1D image buffer object,region
[1] andregion
[2] must be 1. Ifsrc_image
ordst_image
is a 1D image array object,region
[2] must be 1. The values inregion
cannot be 0. event_wait_list ,
num_events_in_wait_list
-
Specify events that need to complete before this particular command can be executed. If
event_wait_list
is NULL, then this particular command does not wait on any event to complete. Ifevent_wait_list
is NULL,num_events_in_wait_list
must be 0. Ifevent_wait_list
is not NULL, the list of events pointed to byevent_wait_list
must be valid andnum_events_in_wait_list
must be greater than 0. The events specified inevent_wait_list
act as synchronization points. The context associated with events inevent_wait_list
andcommand_queue
must be the same. The memory associated withevent_wait_list
can be reused or freed after the function returns. event
-
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.
event
can be NULL 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.clEnqueueBarrierWithWaitList
can be used instead. If theevent_wait_list
and theevent
arguments are not NULL, theevent
argument should not refer to an element of theevent_wait_list
array.
It is currently a requirement that the src_image
and dst_image
image memory objects for clEnqueueCopyImage
must have the exact same image format (i.e.
the cl_image_format
descriptor specified when src_image
and dst_image
are created must match).
If the mipmap extensions are enabled with cl_khr_mipmap_image
, calls to clEnqueueCopyImage
, clEnqueueCopyImageToBuffer
, and clEnqueueCopyBufferToImage
can also be used to copy from and to a specific mip-level of a mip-mapped image.
If src_image
argument is a 1D image, src_origin
[1] specifies the mip-level to use.
If src_image
argument is a 1D image array, src_origin
[2] specifies the mip-level to use.
If src_image
argument is a 2D image, src_origin
[3] specifies the mip-level to use.
If src_image
argument is a 2D image array or a 3D image, src_origin
[3] specifies the mip-level to use.
If dst_image
argument is a 1D image, dst_origin
[1] specifies the mip-level to use.
If dst_image
argument is a 1D image array, dst_origin
[2] specifies the mip-level to use.
If dst_image
argument is a 2D image, dst_origin
[3] specifies the mip-level to use.
If dst_image
argument is a 2D image array or a 3D image, dst_origin
[3] specifies the mip-level to use.
If the mip level specified is not a valid value, these functions return the error CL_INVALID_MIP_LEVEL
.
clEnqueueCopyImage
returns CL_SUCCESS
if the function is executed successfully.
Otherwise, it returns one of the following errors:
-
CL_INVALID_COMMAND_QUEUE
ifcommand_queue
is not a valid host command-queue. -
CL_INVALID_CONTEXT
if the context associated withcommand_queue
,src_image
anddst_image
are not the same or if the context associated withcommand_queue
and events inevent_wait_list
are not the same. -
CL_INVALID_MEM_OBJECT
ifsrc_image
anddst_image
are not valid image objects. -
CL_IMAGE_FORMAT_MISMATCH
ifsrc_image
anddst_image
do not use the same image format. -
CL_INVALID_VALUE
if the 2D or 3D rectangular region specified bysrc_origin
andsrc_origin
+region
refers to a region outsidesrc_image
, or if the 2D or 3D rectangular region specified bydst_origin
anddst_origin
+region
refers to a region outsidedst_image
. -
CL_INVALID_VALUE
if values insrc_origin
,dst_origin
andregion
do not follow rules described in the argument description forsrc_origin
,dst_origin
andregion
. -
CL_INVALID_EVENT_WAIT_LIST
ifevent_wait_list
is NULL andnum_events_in_wait_list
> 0, orevent_wait_list
is not NULL andnum_events_in_wait_list
is 0, or if event objects inevent_wait_list
are not valid events. -
CL_INVALID_IMAGE_SIZE
if image dimensions (image width, height, specified or compute row and/or slice pitch) forsrc_image
ordst_image
are not supported by device associated withqueue
. -
CL_IMAGE_FORMAT_NOT_SUPPORTED
if image format (image channel order and data type) forsrc_image
ordst_image
are not supported by device associated withqueue
. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated withsrc_image
ordst_image
. -
CL_OUT_OF_RESOURCES
if there is a failure to allocate resources required by the OpenCL implementation on the device. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host. -
CL_INVALID_OPERATION
if the device associated withcommand_queue
does not support images (i.e.CL_DEVICE_IMAGE_SUPPORT
specified in the table of OpenCL Device Queries forclGetDeviceInfo
isCL_FALSE
). -
CL_MEM_COPY_OVERLAP
ifsrc_image
anddst_image
are the same image object and the source and destination regions overlap.