Enqueues a command to copy an image object to a buffer object.
cl_int clEnqueueCopyImageToBuffer(cl_command_queue command_queue,
cl_mem src_image,
cl_mem dst_buffer,
const size_t *src_origin,
const size_t *region,
size_t dst_offset,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event)
command_queue
-
Must be a valid host command-queue. The OpenCL context associated with
command_queue
,src_image
, anddst_buffer
must be the same. src_image
-
A valid image object.
dst_buffer
-
A valid buffer object.
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
src_image
is a 2D image object,src_origin
[2] must be 0. Ifsrc_image
is a 1D image or 1D image buffer 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. 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
is a 2D image object,region
[2] must be 1. Ifsrc_image
is a 1D image or 1D image buffer object,region
[1] andregion
[2] must be 1. Ifsrc_image
is a 1D image array object,region
[2] must be 1. The values inregion
cannot be 0. dst_offset
-
Refers to the offset where to begin copying data into
dst_buffer
. The size in bytes of the region to be copied referred to asdst_cb
is computed aswidth * height * depth * bytes/image element
ifsrc_image
is a 3D image object, is computed aswidth * height * bytes/image element
ifsrc_image
is a 2D image, is computed aswidth * height * arraysize * bytes/image element
ifsrc_image
is a 2D image array object, is computed aswidth * bytes/image element
ifsrc_image
is a 1D image or 1D image buffer object and is computed aswidth * arraysize * bytes/image element
ifsrc_image
is a 1D image array object. 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.
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
.
clEnqueueCopyImageToBuffer
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_buffer
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
is not a valid image object ordst_buffer
is not a valid buffer object or ifsrc_image
is a 1D image buffer object created fromdst_buffer
. -
CL_INVALID_VALUE
if the 1D, 2D, or 3D rectangular region specified bysrc_origin
andsrc_origin
+region
refers to a region outsidesrc_image
, or if the region specified bydst_offset
anddst_offset
+dst_cb
refers to a region outsidedst_buffer
. -
CL_INVALID_VALUE
if values insrc_origin
andregion
do not follow rules described in the argument description forsrc_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_MISALIGNED_SUB_BUFFER_OFFSET
ifdst_buffer
is a sub-buffer object andoffset
specified when the sub-buffer object is created is not aligned toCL_DEVICE_MEM_BASE_ADDR_ALIGN
value for device associated withqueue
. -
CL_INVALID_IMAGE_SIZE
if image dimensions (image width, height, specified or compute row and/or slice pitch) forsrc_image
are not supported by device associated withqueue
. -
CL_IMAGE_FORMAT_NOT_SUPPORTED
if image format (image channel order and data type) forsrc_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_buffer
. -
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_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.