clEnqueueCopyBuffer

clEnqueueCopyBuffer is an OpenCL API function that enqueues a command to copy a block of memory from one buffer to another within a specified command queue. The copy operates on device memory and is performed asynchronously relative to the host, allowing overlap with host work.

Signature: 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 cb, cl_uint num_events_in_wait_list, const cl_event* event_wait_list, cl_event* event);

Parameters: command_queue must be a valid command queue associated with a context. src_buffer and dst_buffer must be valid memory objects. src_offset and dst_offset specify the starting offsets within their respective buffers, and cb is the number of bytes to copy. num_events_in_wait_list and event_wait_list define events that must complete before the copy starts; if there are no dependencies, you may pass 0 and NULL. If event is not NULL, the function returns an event object that can be used to synchronize or chain further commands.

Notes: The copy is constrained by the sizes of the source and destination buffers; src_offset + cb must not exceed the size of src_buffer, and dst_offset + cb must not exceed the size of dst_buffer. If the source and destination refer to overlapping regions within the same memory object, behavior is implementation-defined in some cases and may return an error such as CL_MEM_COPY_OVERLAP on certain implementations.

Return values: On success, CL_SUCCESS is returned. Error codes may include CL_INVALID_COMMAND_QUEUE, CL_INVALID_MEM_OBJECT, CL_INVALID_VALUE, and CL_INVALID_EVENT_WAIT_LIST, among others, depending on context and parameters.

See also: clEnqueueReadBuffer, clEnqueueWriteBuffer, clEnqueueCopyBufferRect.