C Specification

To record a command to copy a buffer object to an image object, call the function

// Provided by cl_khr_command_buffer
cl_int clCommandCopyBufferToImageKHR(
    cl_command_buffer_khr command_buffer,
    cl_command_queue command_queue,
    const cl_command_properties_khr* properties,
    cl_mem src_buffer,
    cl_mem dst_image,
    size_t src_offset,
    const size_t* dst_origin,
    const size_t* region,
    cl_uint num_sync_points_in_wait_list,
    const cl_sync_point_khr* sync_point_wait_list,
    cl_sync_point_khr* sync_point,
    cl_mutable_command_khr* mutable_handle);
clCommandCopyBufferToImageKHR is provided by the cl_khr_command_buffer extension.

Parameters

  • command_buffer refers to a valid command-buffer object.

  • command_queue specifies the command-queue the command will be recorded to.
    If the cl_khr_command_buffer_multi_device extension is not supported, only a single command-queue is supported, and command_queue must be NULL.
    If the cl_khr_command_buffer_multi_device extension is supported and command_queue is NULL, then only one command-queue must have been set on command_buffer creation; otherwise, command_queue must not be NULL.

  • properties specifies a list of properties for the command and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. The cl_khr_command_buffer extension does not define any properties, but supported properties may be defined by layered extensions in future.

  • src_buffer, dst_image, src_offset, dst_origin, region refer to clEnqueueCopyBufferToImage

  • sync_point_wait_list, num_sync_points_in_wait_list specify synchronization-points that need to complete before this particular command can be executed.

    If sync_point_wait_list is NULL, num_sync_points_in_wait_list must be 0. If sync_point_wait_list is not NULL, the list of synchronization-points pointed to by sync_point_wait_list must be valid and num_sync_points_in_wait_list must be greater than 0. The synchronization-points specified in sync_point_wait_list are device-side synchronization-points. The command-buffer associated with synchronization-points in sync_point_wait_list must be the same as command_buffer. The memory associated with sync_point_wait_list can be reused or freed after the function returns.

  • sync_point returns a synchronization-point ID that identifies this particular command. Synchronization-point objects are unique and can be used to identify this command later on. sync_point can be NULL in which case it will not be possible for the application to record a wait for this command to complete. If the sync_point_wait_list and the sync_point arguments are not NULL, the sync_point argument should not refer to an element of the sync_point_wait_list array.

  • mutable_handle returns a handle to the command. This parameter is unused, and must be NULL.

Description

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 src_buffer or dst_image is created is ignored by clCommandCopyBufferToImageKHR.

clCommandCopyBufferToImageKHR returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the errors defined by clEnqueueCopyBufferToImage except:

CL_INVALID_COMMAND_QUEUE is replaced with:

  • CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is not supported and command_queue is not NULL.

  • CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is supported; and either command_queue is NULL and command_buffer was created with more than one queue, or command_queue is not NULL and not a command-queue listed on command_buffer creation.

CL_INVALID_CONTEXT is replaced with:

  • CL_INVALID_CONTEXT if the context associated with command_buffer, src_buffer, and dst_image is not the same.

  • CL_INVALID_CONTEXT if command_queue is not NULL, and the context associated with command_queue and command_buffer is not the same.

CL_INVALID_EVENT_WAIT_LIST is replaced with:

  • CL_INVALID_SYNC_POINT_WAIT_LIST_KHR if sync_point_wait_list is NULL and num_sync_points_in_wait_list is > 0, or sync_point_wait_list is not NULL and num_sync_points_in_wait_list is 0, or if synchronization-point objects in sync_point_wait_list are not valid synchronization-points.

New errors:

  • CL_INVALID_COMMAND_BUFFER_KHR if command_buffer is not a valid command-buffer.

  • CL_INVALID_OPERATION if command_buffer has been finalized.

  • CL_INVALID_VALUE if values specified in properties are not valid.

  • CL_INVALID_VALUE if mutable_handle is not NULL.

See Also

cl_command_buffer_khr, cl_command_properties_khr, cl_command_queue, cl_khr_command_buffer, cl_mem, cl_mutable_command_khr, cl_sync_point_khr, cl_uint

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0