CLENQUEUECOPYBUFFER(3clc)

📦
version 1.0~svn33624 · 3 versions
, in ubuntu jammy, ubuntu noble

💖 CLENQUEUECOPYBUFFER 💖

okay bestie, we're doing the OpenCL manual page for clEnqueueCopyBuffer, from the OpenCL Manual, and it's literally about yeeting bytes from one buffer object into another. two buffers. one copy command. let's go ✨

🌸 NAME 🌸

clEnqueueCopyBuffer — Enqueues a command to copy from one buffer object to another. 💅

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

🎀 PARAMETERS 🎀

  • command_queue — the command-queue where this copy command is gonna get queued up. and listen: the OpenCL context that's chillin' with command_queue, src_buffer, and dst_buffer has to be the same context. all three. no mixing contexts, that's not the vibe. 🙅‍♀️
  • src_offset — where you start copying data from in src_buffer. like, the starting line. 🏁
  • dst_offset — where you start copying data into dst_buffer. the destination's starting line. 📍
  • size — the size, in bytes, of what you're copying. bytes!! fr fr. 📏
  • event_wait_list, num_events_in_wait_list — these specify the events that need to finish up before this particular command can even be executed. so:
    • if event_wait_list is NULL, then this particular command does not wait on any event to complete. free spirit. 🦋
    • if event_wait_list is NULL, then num_events_in_wait_list must be 0.
    • if event_wait_list is not NULL, the list of events that event_wait_list points to must be valid, and num_events_in_wait_list must be greater than 0.
    • the events in event_wait_list act as synchronization points. ⏳
    • the context associated with the events in event_wait_list and the one associated with command_queue must be the same.
    • and good news: the memory associated with event_wait_list can be reused or freed after the function returns. no need to hoard it. 💖
  • event — returns an event object that identifies this particular copy command, and you can use it to query or queue a wait for this particular command to complete. but event can be NULL, and in that 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. (if that's your situation, clEnqueueBarrierWithWaitList(3clc) can be used instead.) also, if the event_wait_list and the event arguments are not NULL, the event argument should not refer to an element of the event_wait_list array. 👑

🔥 ERRORS 🔥

Returns CL_SUCCESS if the function is executed successfully. otherwise, it returns one of these:

  • CL_INVALID_COMMAND_QUEUE — if command_queue is not a valid command-queue. 💀
  • CL_INVALID_CONTEXT — if the context associated with command_queue, src_buffer, and dst_buffer are not the same, or if the context associated with command_queue and events in event_wait_list are not the same.
  • CL_INVALID_MEM_OBJECT — if src_buffer and dst_buffer are not valid buffer objects.
  • CL_INVALID_VALUE — if src_offset, dst_offset, size, src_offset + size, or dst_offset + size require accessing elements outside the src_buffer and dst_buffer buffer objects respectively. stay in bounds babes 🚧
  • CL_INVALID_VALUE — if size is 0. (yes, zero counts as a crime here.)
  • CL_INVALID_EVENT_WAIT_LIST — if event_wait_list is NULL and num_events_in_wait_list is > 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
  • CL_MISALIGNED_SUB_BUFFER_OFFSET — if src_buffer is a sub-buffer object and the offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for the device associated with queue. 📐
  • CL_MISALIGNED_SUB_BUFFER_OFFSET — if dst_buffer is a sub-buffer object and the offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for the device associated with queue.
  • CL_MEM_COPY_OVERLAP — if src_buffer and dst_buffer are the same buffer or subbuffer object and the source and destination regions overlap, or if src_buffer and dst_buffer are different sub-buffers of the same associated buffer object and they overlap. the regions overlap if src_offset ≤ to dst_offset ≤ to src_offset + size - 1, or if dst_offset ≤ to src_offset ≤ to dst_offset + size - 1. ⚠️ overlapping is not it.
  • CL_MEM_OBJECT_ALLOCATION_FAILURE — if there is a failure to allocate memory for the data store associated with src_buffer or dst_buffer.
  • 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. 😭

🌈 SPECIFICATION 🌈

OpenCL Specification[1]

🫶 SEE ALSO 🫶

👑 AUTHORS 👑

The Khronos Group

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the following condition: the above copyright notice and this permission notice shall be included in all copies or substantial portions of the Materials.

🧚 NOTES 🧚

  1. OpenCL Specification page 79, section 5.2.2 - Reading, Writing, Copying Buffer Objects

and that's the whole page bestie, no cap 💅 this was brought to you by The Khronos Group, dated 01/14/2021 — mwah, go copy some buffers responsibly 🎀✨

📦 where this page comes from