CLENQUEUECOPYBUFFERR(3clc)

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

💖 clEnqueueCopyBufferRect — the OpenCL manual, but make it make sense 💖

okay so bestie, you're in the 3clc girlies now, this is the OpenCL Manual section for clEnqueueCopyBufferRect, and we're gonna copy a whole rectangular region from one buffer object to another. like, a rectangle. in memory. slay. 🎀

✨ NAME ✨

clEnqueueCopyBufferRect — enqueues a command to copy a rectangular region from a buffer object to another buffer object. that's it, that's the whole vibe. 🦋

✨ SYNOPSIS ✨

cl_int clEnqueueCopyBufferRect(cl_command_queue command_queue,
                               cl_mem src_buffer, cl_mem dst_buffer,
                               const size_t *src_origin,
                               const size_t *dst_origin,
                               const size_t *region,
                               size_t src_row_pitch,
                               size_t src_slice_pitch,
                               size_t dst_row_pitch,
                               size_t dst_slice_pitch,
                               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 gets queued. 🫶 important: the OpenCL context attached to command_queue, src_buffer, and dst_buffer has to be, like, the same one. no context-mixing, that's not the move.
  • src_origin — the (x, y, z) offset inside the memory region that belongs to src_buffer. for a 2D rectangle region, the z value in src_origin[2] should be 0. the offset in bytes is computed as src_origin[2] * src_slice_pitch + src_origin[1] * src_row_pitch + src_origin[0]. math girlies rise 💅
  • dst_origin — the (x, y, z) offset inside the memory region that belongs to dst_buffer. for a 2D rectangle region, the z value in dst_origin[2] should be 0. the offset in bytes is computed as dst_origin[2] * dst_slice_pitch + dst_origin[1] * dst_row_pitch + dst_origin[0]. same energy, different buffer ✨
  • region — the (width, height, depth) in bytes of the 2D or 3D rectangle being copied. for a 2D rectangle, the depth value in region[2] should be 1. yes queen, it's bytes not elements 🙈
  • src_row_pitch — the length of each row, in bytes, used for the memory region of src_buffer. if src_row_pitch is 0, then src_row_pitch is computed as region[0]. lazy girlie defaults, we love her 💖
  • src_slice_pitch — the length of each 2D slice, in bytes, used for the memory region of src_buffer. if src_slice_pitch is 0, then src_slice_pitch is computed as region[1] * src_row_pitch. 🍓
  • dst_row_pitch — the length of each row, in bytes, used for the memory region of dst_buffer. if dst_row_pitch is 0, then dst_row_pitch is computed as region[0]. ✨
  • dst_slice_pitch — the length of each 2D slice, in bytes, used for the memory region of dst_buffer. if dst_slice_pitch is 0, then dst_slice_pitch is computed as region[1] * dst_row_pitch. 🌸
  • event_wait_list, num_events_in_wait_list — these specify the events that need to finish before this particular command can run. if event_wait_list is NULL, then this command doesn't wait on any event at all (main character behavior). if event_wait_list is NULL, num_events_in_wait_list must be 0. if event_wait_list is not NULL, then the list of events it 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 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 strings attached 💅
  • event — returns an event object that identifies this particular copy command, which you can use to query it or queue a wait for it to complete. event can be NULL, but then it won't be possible for the app to query the status of this command or queue a wait for it to complete — clEnqueueBarrierWithWaitList(3clc) can be used instead. also, if both event_wait_list and the event argument are not NULL, the event argument should not refer to an element of the event_wait_list array. don't do that. that's not it. 😭

✨ NOTES ✨

clEnqueueCopyBufferRect enqueues a command that copies a 2D or 3D rectangular region from the buffer object identified by src_buffer to a 2D or 3D region in the buffer object identified by dst_buffer. the copying kicks off at the source offset and destination offset, which get computed the way we described up there for src_origin and dst_origin. 📐

every byte of the region's width gets copied from the source offset to the destination offset. after each width is copied, the source and destination offsets are incremented by their respective source and destination row pitches. and after each 2D rectangle is copied, the source and destination offsets are incremented by their respective source and destination slice pitches. it's giving assembly line but make it ✨geometric✨

NOTE: if src_buffer and dst_buffer are the same buffer object, then src_row_pitch must equal dst_row_pitch and src_slice_pitch must equal dst_slice_pitch. no cap. 🔥

✨ ERRORS ✨

returns CL_SUCCESS if the function runs successfully. otherwise it returns one of these bad boys:

  • 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, region) or (dst_offset, region) require accessing elements outside the src_buffer and dst_buffer objects respectively. 🚫
  • CL_INVALID_VALUE if any region array element is 0. zero width? we don't know her.
  • CL_INVALID_VALUE if src_row_pitch is not 0 and is less than region[0].
  • CL_INVALID_VALUE if dst_row_pitch is not 0 and is less than region[0].
  • CL_INVALID_VALUE if src_slice_pitch is not 0 and is less than region[1] * src_row_pitch, or if src_slice_pitch is not 0 and is not a multiple of src_row_pitch.
  • CL_INVALID_VALUE if dst_slice_pitch is not 0 and is less than region[1] * dst_row_pitch, or if dst_slice_pitch is not 0 and is not a multiple of dst_row_pitch.
  • CL_INVALID_VALUE if src_buffer and dst_buffer are the same buffer object and src_slice_pitch is not equal to dst_slice_pitch and src_row_pitch is not equal to dst_row_pitch.
  • 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_MEM_COPY_OVERLAP if src_buffer and dst_buffer are the same buffer 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. refer to Appendix E in the OpenCL specification for details on how to determine if source and destination regions overlap. 📖
  • 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_OBJECT_ALLOCATION_FAILURE if there's a failure to allocate memory for the data store associated with src_buffer or dst_buffer.
  • CL_OUT_OF_RESOURCES if there's a failure to allocate resources required by the OpenCL implementation on the device. 😭
  • CL_OUT_OF_HOST_MEMORY if there's a failure to allocate resources required by the OpenCL implementation on the host. 😭

✨ SPECIFICATION ✨

OpenCL Specification[1] 📚

✨ SEE ALSO ✨

clEnqueueReadBuffer(3clc), clEnqueueReadBufferRect(3clc), clEnqueueWriteBuffer(3clc), clEnqueueWriteBufferRect(3clc), clEnqueueCopyBuffer(3clc), clCreateBuffer(3clc), clCreateSubBuffer(3clc), clEnqueueCopyBufferToImage(3clc), clEnqueueCopyImageToBuffer(3clc)

the whole friend group, honestly 🫶

✨ 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 condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

✨ NOTES (the footnote one, not the other one) ✨

  1. OpenCL Specification page 81, section 5.2.2 - Reading, Writing and Copying Buffer Objects 📄

and that's the whole page bestie, you ate 💅

shoutout to The Khronos Group, this manual page came to you from 01/14/2021, and yes the header up top said OpenCL Manual and the section was CLENQUEUECOPYBUFFERR(3clc) — iykyk 🎀✨💖

📦 where this page comes from