OpenCL™规范 5.2.2. 读取、写入和复制缓冲区对象

最新推荐文章于 2024-07-21 12:03:06 发布

꧁白杨树下꧂

最新推荐文章于 2024-07-21 12:03:06 发布

阅读量200

点赞数

分类专栏： openCL 文章标签： openCL

原文链接：https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#_reading_writing_and_copying_buffer_objects

版权

openCL 专栏收录该内容

148 篇文章 12 订阅

订阅专栏

5.2.2. Reading, Writing and Copying Buffer Objects

5.2.2. 读取、写入和复制缓冲区对象

The following functions enqueue commands to read from a buffer object to host memory or write to a buffer object from host memory.

以下函数将从缓冲区对象读取到主机内存或从主机内存写入缓冲区对象的命令队列。

To read from a buffer object to host memory or to write to a buffer object from host memory call one of the functions

要从缓冲区对象读取到主机内存或从主机内存写入缓冲区对象，请调用以下函数之一

cl_int clEnqueueReadBuffer(
    cl_command_queue command_queue,
    cl_mem buffer,
    cl_bool blocking_read,
    size_t offset,
    size_t size,
    void* ptr,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

cl_int clEnqueueWriteBuffer(
    cl_command_queue command_queue,
    cl_mem buffer,
    cl_bool blocking_write,
    size_t offset,
    size_t size,
    const void* ptr,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

command_queue is a valid host command-queue in which the read / write command will be queued. command_queue and buffer must be created with the same OpenCL context.
command_queue是一个有效的主机命令队列，读/写命令将在其中排队。command_queue和buffer必须使用相同的OpenCL上下文创建。
buffer refers to a valid buffer object.
buffer指的是一个有效的缓冲区对象。
blocking_read and blocking_write indicate if the read and write operations are blocking or non-blocking (see below).
blocking_read和blocking_write指示读取和写入操作是阻塞还是非阻塞（见下文）。
offset is the offset in bytes in the buffer object to read from or write to.
offset是缓冲区对象中要读取或写入的偏移量（以字节为单位）。
size is the size in bytes of data being read or written.
size是正在读取或写入的数据的字节大小。
ptr is the pointer to buffer in host memory where data is to be read into or to be written from.
ptr是指向主机内存中要读取或写入数据的缓冲区的指针。
event_wait_list and 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. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.
event_wait_list和num_events_in_wait_list指定在执行此特定命令之前需要完成的事件。如果event_wait_list为NULL，则此特定命令不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于0。event_wait_list中指定的事件充当同步点。与event_wait_list和command_queue中的事件关联的上下文必须相同。函数返回后，可以重用或释放与event_wait_list关联的内存。
event returns an event object that identifies this read / write command and can be used to query or queue a wait for this command to complete. If event is NULL or the enqueue is unsuccessful, no event will be created and therefore it will not be possible to query the status of this command or to wait for this command to complete. If event_wait_list and event are not NULL, event must not refer to an element of the event_wait_list array.
event返回一个事件对象，该对象标识此读/写命令，可用于查询或排队等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

If blocking_read is CL_TRUE i.e. the read command is blocking, clEnqueueReadBuffer does not return until the buffer data has been read and copied into memory pointed to by ptr.

如果blocking_read为CL_TRUE，即读取命令为blocking，则clEnqueueReadBuffer不会返回，直到缓冲区数据已被读取并复制到ptr指向的内存中。

If blocking_read is CL_FALSE i.e. the read command is non-blocking, clEnqueueReadBuffer queues a non-blocking read command and returns. The contents of the buffer that ptr points to cannot be used until the read command has completed. The event argument returns an event object which can be used to query the execution status of the read command. When the read command has completed, the contents of the buffer that ptr points to can be used by the application.

如果blocking_read为CL_FALSE，即读取命令为非阻塞，则clEnqueueReadBuffer将非阻塞读取命令排队并返回。ptr指向的缓冲区的内容在读取命令完成之前无法使用。事件参数返回一个事件对象，该对象可用于查询读取命令的执行状态。读取命令完成后，ptr所指向的缓冲区的内容可以由应用程序使用。

If blocking_write is CL_TRUE, the write command is blocking and does not return until the command is complete, including transfer of the data. The memory pointed to by ptr can be reused by the application after the clEnqueueWriteBuffer call returns.

如果blocking_write为CL_TRUE，则写入命令处于阻塞状态，并且在命令完成（包括数据传输）之前不会返回。在clEnqueueWriteBuffer调用返回后，ptr指向的内存可以被应用程序重用。

If blocking_write is CL_FALSE, the OpenCL implementation will use ptr to perform a non-blocking write. As the write is non-blocking the implementation can return immediately. The memory pointed to by ptr cannot be reused by the application after the call returns. The event argument returns an event object which can be used to query the execution status of the write command. When the write command has completed, the memory pointed to by ptr can then be reused by the application.

如果blocking_write为CL_FALSE，则OpenCL实现将使用ptr执行非阻塞写入。由于写入是非阻塞的，因此实现可以立即返回。ptr指向的内存在调用返回后无法被应用程序重用。事件参数返回一个事件对象，该对象可用于查询写入命令的执行状态。当写命令完成后，ptr指向的内存就可以被应用程序重用。

clEnqueueReadBuffer and clEnqueueWriteBuffer return CL_SUCCESS if the function is executed successfully. Otherwise, they return one of the following errors:

如果函数执行成功，clEnqueueReadBuffer和clEnqueueWriteBuffer将返回CL_SUCCESS。否则，它们将返回以下错误之一：

CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.
CL_INVALID_COMMAND_QUEUE（如果命令队列不是有效的主机命令队列）。
CL_INVALID_CONTEXT if the context associated with command_queue and buffer are not the same or if the context associated with command_queue and events in event_wait_list are not the same.
如果与command_queue和buffer关联的上下文不相同，或者与command_ queue关联的上下文和event_wait_list中的事件不相同，则CL_INVALID_CONTEXT。
CL_INVALID_MEM_OBJECT if buffer is not a valid buffer object.
CL_INVALID_MEM_OBJECT（如果缓冲区不是有效的缓冲区对象）。
CL_INVALID_VALUE if the region being read or written specified by (offset, size) is out of bounds or if ptr is a NULL value.
CL_INVALID_VALUE如果由（偏移量、大小）指定的正在读取或写入的区域超出界限，或者ptr为NULL值。
CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 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_INVALID_EVENT_WAIT_LIST如果event_wait_list为NULL且num_events_in_wait_list>0，或者event_wait_list不为NULL且num_events_in_wait_list为0，或者如果event_wait_list中的事件对象不是有效事件。
CL_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue. This error code is missing before version 1.1.
CL_MISALIGNED_SUB_BUFFER_OFFSET，如果缓冲区是子缓冲区对象，并且创建子缓冲区时指定的偏移量未与与队列关联的设备的CL_DEVICE_MEM_BASE_ADDR_ALIGN值对齐。1.1版本之前缺少此错误代码。
CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value. This error code is missing before version 1.1.
CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST，如果读取和写入操作是阻塞的，并且event_wait_list中任何事件的执行状态是负整数值。1.1版本之前缺少此错误代码。
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
CL_MEM_OBJECT_ALLOCATION_FAILURE（如果为与缓冲区关联的数据存储分配内存失败）。
CL_INVALID_OPERATION if clEnqueueReadBuffer is called on buffer which has been created with CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_NO_ACCESS.
CL_INVALID_OPERATION（如果对使用CL_MEM_HOST_WRITE_ONLY或CL_MEM_HOST_NO_ACCESS创建的缓冲区调用clEnqueueReadBuffer）。
CL_INVALID_OPERATION if clEnqueueWriteBuffer is called on buffer which has been created with CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS.
CL_INVALID_OPERATION（如果对使用CL_MEM_HOST_READ_ONLY或CL_MEM-HOST_NO_ACCESS创建的缓冲区调用clEnqueueWriteBuffer）。
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

The following functions enqueue commands to read a 2D or 3D rectangular region from a buffer object to host memory or write a 2D or 3D rectangular region to a buffer object from host memory.

以下功能将从缓冲对象读取2D或3D矩形区域到主存储器的命令排队，或将2D或3D长方形区域从主存储器写入缓冲对象的命令排队。

cl_int clEnqueueReadBufferRect(
    cl_command_queue command_queue,
    cl_mem buffer,
    cl_bool blocking_read,
    const size_t* buffer_origin,
    const size_t* host_origin,
    const size_t* region,
    size_t buffer_row_pitch,
    size_t buffer_slice_pitch,
    size_t host_row_pitch,
    size_t host_slice_pitch,
    void* ptr,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

clEnqueueReadBufferRect is missing before version 1.1.

clEnqueueReadBufferRect在版本1.1之前丢失。

cl_int clEnqueueWriteBufferRect(
    cl_command_queue command_queue,
    cl_mem buffer,
    cl_bool blocking_write,
    const size_t* buffer_origin,
    const size_t* host_origin,
    const size_t* region,
    size_t buffer_row_pitch,
    size_t buffer_slice_pitch,
    size_t host_row_pitch,
    size_t host_slice_pitch,
    const void* ptr,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

clEnqueueWriteBufferRect is missing before version 1.1.

clEnqueueWriteBufferRect在版本1.1之前丢失。

command_queue refers is a valid host command-queue in which the read / write command will be queued. command_queue and buffer must be created with the same OpenCL context.
command_queue是一个有效的主机命令队列，读/写命令将在其中排队。command_queue和buffer必须使用相同的OpenCL上下文创建。
buffer refers to a valid buffer object.
buffer指的是一个有效的缓冲区对象。
blocking_read and blocking_write indicate if the read and write operations are blocking or non-blocking (see below).
blocking_read和blocking_write指示读取和写入操作是阻塞还是非阻塞（见下文）。
buffer_origin defines the (x, y, z) offset in the memory region associated with buffer. For a 2D rectangle region, the z value given by buffer_origin[2] should be 0. The offset in bytes is computed as buffer_origin[2] × buffer_slice_pitch + buffer_origin[1] × buffer_row_pitch + buffer_origin[0].
buffer_origin定义与缓冲区相关联的内存区域中的（x，y，z）偏移量。对于2D矩形区域，buffer_origin[2]给出的z值应为0。以字节为单位的偏移量计算为buffer_origin[2]×buffer_slice_pitch+buffer_origin[1]×buffer_row_pitch+buffer_original[0]。
host_origin defines the (x, y, z) offset in the memory region pointed to by ptr. For a 2D rectangle region, the z value given by host_origin[2] should be 0. The offset in bytes is computed as host_origin[2] × host_slice_pitch + host_origin[1] × host_row_pitch + host_origin[0].
host_origin定义ptr指向的内存区域中的（x，y，z）偏移量。对于2D矩形区域，host_origin[2]给出的z值应为0。以字节为单位的偏移量计算为host_origin[2]×host_slice_pitch+host_origin[1]×host_row_pitch+host_origin[0]。
region defines the (width in bytes, height in rows, depth in slices) of the 2D or 3D rectangle being read or written. For a 2D rectangle copy, the depth value given by region[2] should be 1. The values in region cannot be 0.
region定义了正在读取或写入的2D或3D矩形的宽度（以字节为单位）、行的高度、片的深度。对于2D矩形副本，区域[2]给出的深度值应为1。区域中的值不能为0。
buffer_row_pitch is the length of each row in bytes to be used for the memory region associated with buffer. If buffer_row_pitch is 0, buffer_row_pitch is computed as region[0].
buffer_row_pitch是用于与缓冲区相关联的存储器区域的每一行的长度（以字节为单位）。如果buffer_row_pitch为0，则将buffer_row_pritch计算为region[0]。
buffer_slice_pitch is the length of each 2D slice in bytes to be used for the memory region associated with buffer. If buffer_slice_pitch is 0, buffer_slice_pitch is computed as region[1] × buffer_row_pitch.
buffer_slice_ppitch是要用于与缓冲器相关联的存储器区域的每个2D切片的长度（以字节为单位）。如果buffer_slice_pitch为0，则将buffer_sliche_pitch计算为region[1]×buffer_row_pitch。
host_row_pitch is the length of each row in bytes to be used for the memory region pointed to by ptr. If host_row_pitch is 0, host_row_pitch is computed as region[0].
host_row_pitch是ptr指向的内存区域所使用的每一行的长度（以字节为单位）。如果host_row_pitch为0，则将host_row_pritch计算为region[0]。
host_slice_pitch is the length of each 2D slice in bytes to be used for the memory region pointed to by ptr. If host_slice_pitch is 0, host_slice_pitch is computed as region[1] × host_row_pitch.
host_slice_pitch是要用于ptr所指向的存储器区域的每个2D切片的长度（以字节为单位）。如果host_slice_pitch为0，则host_slice_pitch计算为region[1]×host_row_pitch。
ptr is the pointer to buffer in host memory where data is to be read into or to be written from.
ptr是指向主机内存中要读取或写入数据的缓冲区的指针。
event_wait_list and 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. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.
event_wait_list和num_events_in_wait_list指定在执行此特定命令之前需要完成的事件。如果event_wait_list为NULL，则此特定命令不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于0。event_wait_list中指定的事件充当同步点。与event_wait_list和command_queue中的事件关联的上下文必须相同。函数返回后，可以重用或释放与event_wait_list关联的内存。
event returns an event object that identifies this read / write command and can be used to query or queue a wait for this command to complete. If event is NULL or the enqueue is unsuccessful, no event will be created and therefore it will not be possible to query the status of this command or to wait for this command to complete. If event_wait_list and event are not NULL, event must not refer to an element of the event_wait_list array.
event返回一个事件对象，该对象标识此读/写命令，可用于查询或排队等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

If blocking_read is CL_TRUE i.e. the read command is blocking, clEnqueueReadBufferRect does not return until the buffer data has been read and copied into memory pointed to by ptr.

如果blocking_read为CL_TRUE，即读取命令为blocking，则clEnqueueReadBufferRect不会返回，直到缓冲区数据已被读取并复制到ptr指向的内存中。

If blocking_read is CL_FALSE i.e. the read command is non-blocking, clEnqueueReadBufferRect queues a non-blocking read command and returns. The contents of the buffer that ptr points to cannot be used until the read command has completed. The event argument returns an event object which can be used to query the execution status of the read command. When the read command has completed, the contents of the buffer that ptr points to can be used by the application.

如果blocking_read为CL_FALSE，即读取命令为非阻塞，则clEnqueueReadBufferRect将非阻塞读取命令排队并返回。ptr指向的缓冲区的内容在读取命令完成之前无法使用。事件参数返回一个事件对象，该对象可用于查询读取命令的执行状态。读取命令完成后，ptr所指向的缓冲区的内容可以由应用程序使用。

如果blocking_write为CL_TRUE，则写入命令处于阻塞状态，并且在命令完成（包括数据传输）之前不会返回。在clEnqueueWriteBufferRect调用返回后，应用程序可以重用ptr指向的内存。

clEnqueueReadBufferRect and clEnqueueWriteBufferRect return CL_SUCCESS if the function is executed successfully. Otherwise, they return one of the following errors:

如果函数执行成功，clEnqueueReadBufferRect和clEnqueueWriteBufferRect将返回CL_SUCCESS。否则，它们将返回以下错误之一：

CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.
CL_INVALID_COMMAND_QUEUE（如果命令队列不是有效的主机命令队列）。
CL_INVALID_CONTEXT if the context associated with command_queue and buffer are not the same or if the context associated with command_queue and events in event_wait_list are not the same.
如果与command_queue和buffer关联的上下文不相同，或者与command_ queue关联的上下文和event_wait_list中的事件不相同，则CL_INVALID_CONTEXT。
CL_INVALID_MEM_OBJECT if buffer is not a valid buffer object.
CL_INVALID_MEM_OBJECT（如果缓冲区不是有效的缓冲区对象）。
CL_INVALID_VALUE if buffer_origin, host_origin, or region is NULL.
CL_INVALID_VALUE，如果buffer_origin、host_origin或region 为NULL。
CL_INVALID_VALUE if the region being read or written specified by (buffer_origin, region, buffer_row_pitch, buffer_slice_pitch) is out of bounds.
CL_INVALID_VALUE如果由（buffer_origin、region、buffer_row_pitch、buffer_slice_pitch）指定的正在读取或写入的区域越界。
CL_INVALID_VALUE if any region array element is 0.
CL_INVALID_VALUE，如果任何区域数组元素为0。
CL_INVALID_VALUE if buffer_row_pitch is not 0 and is less than region[0].
CL_INVALID_VALUE，如果buffer_row_pitch不为0并且小于region[0]。
CL_INVALID_VALUE if host_row_pitch is not 0 and is less than region[0].
如果host_row_pitch不为0并且小于region[0]，则CL_INVALID_VALUE。
CL_INVALID_VALUE if buffer_slice_pitch is not 0 and is less than region[1] × buffer_row_pitch and not a multiple of buffer_row_pitch.
CL_INVALID_VALUE，如果buffer_slice_pitch不为0且小于region[1]×buffer_row_pitch且不是buffer_row_pritch的倍数。
CL_INVALID_VALUE if host_slice_pitch is not 0 and is less than region[1] × host_row_pitch and not a multiple of host_row_pitch.
CL_INVALID_VALUE，如果host_slice_pitch不为0且小于region[1]×host_row_pitch且不是host_row_pritch的倍数。
CL_INVALID_VALUE if ptr is NULL.
CL_INVALID_VALUE（如果ptr为NULL）。
CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 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_INVALID_EVENT_WAIT_LIST如果event_wait_list为NULL且num_events_in_wait_list>0，或者event_wait_list不为NULL且num_events_in_wait_list为0，或者如果event_wait_list中的事件对象不是有效事件。
CL_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue. This error code is missing before version 1.1.
CL_MISALIGNED_SUB_BUFFER_OFFSET，如果缓冲区是子缓冲区对象，并且创建子缓冲区时指定的偏移量未与队列关联的设备的CL_DEVICE_MEM_BASE_ADDR_ALIGN值对齐。1.1版本之前缺少此错误代码。
CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value. This error code is missing before version 1.1.
CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST，如果读取和写入操作是阻塞的，并且event_wait_list中任何事件的执行状态是负整数值。1.1版本之前缺少此错误代码。
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
CL_MEM_OBJECT_ALLOCATION_FAILURE（如果为与缓冲区关联的数据存储分配内存失败）。
CL_INVALID_OPERATION if clEnqueueReadBufferRect is called on buffer which has been created with CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_NO_ACCESS.
CL_INVALID_OPERATION，如果在使用CL_MEM_HOST_WRITE_ONLY或CL_MEM_HOST_NO_ACCESS创建的缓冲区上调用clEnqueueReadBufferRect。
CL_INVALID_OPERATION if clEnqueueWriteBufferRect is called on buffer which has been created with CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS.
CL_INVALID_OPERATION（如果对使用CL_MEM_HOST_READ_ONLY或CL_MEM_HOST_NO_ACCESS创建的缓冲区调用clEnqueueWriteBufferRect）。
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

Calling clEnqueueReadBuffer to read a region of the buffer object with the ptr argument value set to host_ptr + offset, where host_ptr is a pointer to the memory region specified when the buffer object being read is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:

调用clEnqueueReadBuffer读取缓冲区对象的一个区域，ptr参数值设置为host_ptr+偏移量，其中host_ptr是在使用CL_MEM_USE_HOST_PTR创建要读取的缓冲区对象时指定的内存区域的指针，必须满足以下要求，以避免未定义的行为：

All commands that use this buffer object or a memory object (buffer or image) created from this buffer object have finished execution before the read command begins execution.
在读取命令开始执行之前，使用此缓冲区对象或从此缓冲区对象创建的内存对象（缓冲区或图像）的所有命令都已完成执行。
The buffer object or memory objects created from this buffer object are not mapped.
缓冲区对象或从此缓冲区对象创建的内存对象未映射。
The buffer object or memory objects created from this buffer object are not used by any command-queue until the read command has finished execution.
在读取命令完成执行之前，任何命令队列都不会使用由该缓冲区对象创建的缓冲区对象或内存对象。

Calling clEnqueueReadBufferRect to read a region of the buffer object with the ptr argument value set to host_ptr and host_origin, buffer_origin values are the same, where host_ptr is a pointer to the memory region specified when the buffer object being read is created with CL_MEM_USE_HOST_PTR, must meet the same requirements given above for clEnqueueReadBuffer.

调用clEnqueueReadBufferRect以读取缓冲区对象的一个区域，其中ptr参数值设置为host_ptr和host_origin，buffer_origin值相同，其中host_ptr是在使用CL_MEM_USE_HOST_PTR创建要读取的缓冲区对象时指定的内存区域的指针，必须满足上述clEnqueueReadBuffer的相同要求。

Calling clEnqueueWriteBuffer to update the latest bits in a region of the buffer object with the ptr argument value set to host_ptr + offset, where host_ptr is a pointer to the memory region specified when the buffer object being written is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:

调用clEnqueueWriteBuffer以更新缓冲区对象的某个区域中的最新位，ptr参数值设置为host_ptr+偏移量，其中host_ptr是在使用CL_MEM_USE_HOST_PTR创建正在写入的缓冲区对象时指定的内存区域的指针，必须满足以下要求，以避免未定义的行为：

The host memory region given by (host_ptr + offset, cb) contains the latest bits when the enqueued write command begins execution.
由（host_ptr+offset，cb）给定的主机内存区域包含排队写入命令开始执行时的最新位。
The buffer object or memory objects created from this buffer object are not mapped.
缓冲区对象或从此缓冲区对象创建的内存对象未映射。
The buffer object or memory objects created from this buffer object are not used by any command-queue until the write command has finished execution.
在写入命令完成执行之前，任何命令队列都不会使用由该缓冲区对象创建的缓冲区对象或内存对象。

Calling clEnqueueWriteBufferRect to update the latest bits in a region of the buffer object with the ptr argument value set to host_ptr and host_origin, buffer_origin values are the same, where host_ptr is a pointer to the memory region specified when the buffer object being written is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:

调用clEnqueueWriteBufferRect以更新缓冲区对象区域中的最新位，其中ptr参数值设置为host_ptr和host_origin，buffer_origin值相同，其中host_ptr是指向使用CL_MEM_USE_HOST_PTR创建正在写入的缓冲区对象时指定的内存区域的指针，必须满足以下要求，以避免未定义的行为：

The host memory region given by (buffer_origin region) contains the latest bits when the enqueued write command begins execution.
（buffer_origin region）给出的主机内存区域包含排队写入命令开始执行时的最新位。
The buffer object or memory objects created from this buffer object are not mapped.
缓冲区对象或从此缓冲区对象创建的内存对象未映射。
The buffer object or memory objects created from this buffer object are not used by any command-queue until the write command has finished execution.
在写入命令完成执行之前，任何命令队列都不会使用由该缓冲区对象创建的缓冲区对象或内存对象。

To enqueue a command to copy a buffer object identified by src_buffer to another buffer object identified by dst_buffer, call the function

要将命令排队以将src_buffer标识的缓冲区对象复制到dst_buffer标识的另一个缓冲区对象，请调用以下函数

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);

command_queue refers to a host command-queue in which the copy command will be queued. The OpenCL context associated with command_queue, src_buffer and dst_buffer must be the same.
command_queue是指复制命令将在其中排队的主机命令队列。与command_queue、src_buffer和dst_buffer关联的OpenCL上下文必须相同。
src_offset refers to the offset where to begin copying data from src_buffer.
src_offset是指开始从src_buffer复制数据的偏移量。
dst_offset refers to the offset where to begin copying data into dst_buffer.
dst_offset是指开始将数据复制到dst_buffer中的偏移量。
size refers to the size in bytes to copy.
size是指要复制的大小（以字节为单位）。
event_wait_list and 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. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.
event_wait_list和num_events_in_wait_list指定在执行此特定命令之前需要完成的事件。如果event_wait_list为NULL，则此特定命令不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于0。event_wait_list中指定的事件充当同步点。与event_wait_list和command_queue中的事件关联的上下文必须相同。函数返回后，可以重用或释放与event_wait_list关联的内存。
event returns an event object that identifies this copy command and can be used to query or queue a wait for this command to complete. If event is NULL or the enqueue is unsuccessful, no event will be created and therefore it will not be possible to query the status of this command or to wait for this command to complete. If event_wait_list and event are not NULL, event must not refer to an element of the event_wait_list array.
event返回一个事件对象，该对象标识此复制命令，可用于查询或排队等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

clEnqueueCopyBuffer returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clEnqueueCopyBuffer将返回CL_SUCCESS。否则，它将返回以下错误之一：

CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.
CL_INVALID_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_CONTEXT如果与command_queue、src_buffer和dst_buffer关联的上下文不相同，或者与command_ queue关联的上下文和event_wait_list中的事件不相同。
CL_INVALID_MEM_OBJECT if src_buffer and dst_buffer are not valid buffer objects.
如果src_buffer和dst_buffer不是有效的缓冲区对象，则CL_INVALID_MEM_OBJECT。
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.
CL_INVALID_VALUE如果src_offset、dst_offset、size、src_offset+size或dst_offset+size分别需要访问src_buffer和dst_buffer缓冲区对象之外的元素。
CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 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_INVALID_EVENT_WAIT_LIST如果EVENT_WAIT_LIST为NULL且num_events_in_WAIT_LIST>0，或者EVENT_wail_LIST不为NULL且num_events_in.WAIT_LIST为0，或者如果EVENT_wwait_LIST中的事件对象不是有效事件。
CL_MISALIGNED_SUB_BUFFER_OFFSET if src_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue. This error code is missing before version 1.1.
CL_MISALIGNED_SUB_BUFFER_OFFSET（如果src_BUFFER是子缓冲区对象，并且创建子缓冲区时指定的偏移量未与队列相关设备的CL_DEVICE_MEM_BASE_ADDR_ALIGN值对齐）。1.1版本之前缺少此错误代码。
CL_MISALIGNED_SUB_BUFFER_OFFSET if dst_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue. This error code is missing before version 1.1.
CL_MISALIGNED_SUB_BUFFER_OFFSET（如果dst_BUFFER是子缓冲区对象，并且创建子缓冲区时指定的偏移量未与队列相关设备的CL_DEVICE_MEM_BASE_ADDR_ALIGN值对齐）。1.1版本之前缺少此错误代码。
CL_MEM_COPY_OVERLAP if src_buffer and dst_buffer are the same buffer or sub-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. The regions overlap if src_offset ≤ dst_offset ≤ src_offset + size - 1 or if dst_offset ≤ src_offset ≤ dst_offset + size - 1.
CL_MEM_COPY_OVERLAP，如果src_buffer和dst_buffer是相同的缓冲区或子缓冲区对象并且源和目的区域重叠。如果src_offset≤dst_offset≤src_offset+size-1，或者如果dst_offset≤src_offset≤dst_ooffset+size-1，则区域重叠。
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_buffer or dst_buffer.
如果为与src_buffer或dst_buffer关联的数据存储分配内存失败，则CL_MEM_OBJECT_ALLOCATION_FAILURE。
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

To enqueue a command to copy 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, call the function

要将命令排入队列，以便将二维或三维矩形区域从src_buffer标识的缓冲区对象复制到dst_buffer标识的缓冲区时的二维或三维区域，请调用函数

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);

clEnqueueCopyBufferRect is missing before version 1.1.

clEnqueueCopyBufferRect在版本1.1之前丢失。

command_queue refers to the host command-queue in which the copy command will be queued. The OpenCL context associated with command_queue, src_buffer and dst_buffer must be the same.
command_queue是指复制命令将在其中排队的主机命令队列。与command_queue、src_buffer和dst_buffer关联的OpenCL上下文必须相同。
src_origin defines the (x, y, z) offset in the memory region associated with src_buffer. For a 2D rectangle region, the z value given by 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].
src_origin定义与src_buffer相关联的存储器区域中的（x，y，z）偏移。对于2D矩形区域，src_origin[2]给出的z值应为0。以字节为单位的偏移量计算为src_origin[2]×src_slice_pitch+src_origin[1]×src_row_pitch+src_original[0]。
dst_origin defines the (x, y, z) offset in the memory region associated with dst_buffer. For a 2D rectangle region, the z value given by 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].
dst_origin定义与dst_buffer相关联的存储器区域中的（x，y，z）偏移。对于2D矩形区域，dst_origin[2]给出的z值应为0。以字节为单位的偏移量计算为dst_origin[2]×dst_slice_pitch+dst_origin[1]×dst_row_pitch+dst_origin[0]。
region defines the (width in bytes, height in rows, depth in slices) of the 2D or 3D rectangle being copied. For a 2D rectangle, the depth value given by region[2] should be 1. The values in region cannot be 0.
区域定义了要复制的2D或3D矩形的宽度（以字节为单位）、行的高度、片的深度。对于2D矩形，区域[2]给出的深度值应为1。区域中的值不能为0。
src_row_pitch is the length of each row in bytes to be used for the memory region associated with src_buffer. If src_row_pitch is 0, src_row_pitch is computed as region[0].
src_row_pitch是用于与src_buffer相关联的存储器区域的每一行的长度（以字节为单位）。如果src_row_pitch为0，则将src_row_pritch计算为region[0]。
src_slice_pitch is the length of each 2D slice in bytes to be used for the memory region associated with src_buffer. If src_slice_pitch is 0, src_slice_pitch is computed as region[1] × src_row_pitch.
src_ slice_ pitch是要用于与src_ buffer相关联的存储器区域的每个2D切片的长度（以字节为单位）。如果src_slice_pitch为0，则将src_slite_pitch计算为region[1]×src_row_pitch。
dst_row_pitch is the length of each row in bytes to be used for the memory region associated with dst_buffer. If dst_row_pitch is 0, dst_row_pitch is computed as region[0].
dst_row_pitch是要用于与dst_buffer相关联的存储器区域的每一行的长度（以字节为单位）。如果dst_row_pitch为0，则将dst_row_pritch计算为region[0]。
dst_slice_pitch is the length of each 2D slice in bytes to be used for the memory region associated with dst_buffer. If dst_slice_pitch is 0, dst_slice_pitch is computed as region[1] × dst_row_pitch.
dst_slice_pitch是要用于与dst_buffer相关联的存储器区域的每个2D切片的长度（以字节为单位）。如果dst_slice_pitch为0，则将dst_slice_pitch计算为region[1]×dst_row_pitch。
event_wait_list and 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. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.
event_wait_list和num_events_in_wait_list指定在执行此特定命令之前需要完成的事件。如果event_wait_list为NULL，则此特定命令不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于0。event_wait_list中指定的事件充当同步点。与event_wait_list和command_queue中的事件关联的上下文必须相同。函数返回后，可以重用或释放与event_wait_list关联的内存。
event returns an event object that identifies this copy command and can be used to query or queue a wait for this command to complete. If event is NULL or the enqueue is unsuccessful, no event will be created and therefore it will not be possible to query the status of this command or to wait for this command to complete. If event_wait_list and event are not NULL, event must not refer to an element of the event_wait_list array.
event返回一个事件对象，该对象标识此复制命令，可用于查询或排队等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

Copying begins at the source offset and destination offset which are computed as described below in the description for src_origin and dst_origin. Each byte of the region’s width is copied from the source offset to the destination offset. After copying each width, the source and destination offsets are incremented by their respective source and destination row pitches. After copying each 2D rectangle, the source and destination offsets are incremented by their respective source and destination slice pitches.

复制从源偏移量和目标偏移量开始，这两个偏移量的计算方法如下src_origin和dst_origin的说明所述。区域宽度的每个字节都从源偏移量复制到目标偏移量。复制每个宽度后，源偏移和目标偏移将按其各自的源行间距和目标行间距递增。复制每个2D矩形后，源偏移和目标偏移将按其各自的源切片节距和目标切片节距递增。

If src_buffer and dst_buffer are the same buffer object, src_row_pitch must equal dst_row_pitch and src_slice_pitch must equal dst_slice_pitch.

如果src_buffer和dst_buffer是同一缓冲区对象，则src_row_pitch必须等于dst_row_pitch，src_slice_pitch也必须等于dst_slice_pitch。

clEnqueueCopyBufferRect returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clEnqueueCopyBufferRect将返回CL_SUCCESS。否则，它将返回以下错误之一：

CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.
CL_INVALID_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_CONTEXT如果与command_queue、src_buffer和dst_buffer关联的上下文不相同，或者与command_ queue关联的上下文和event_wait_list中的事件不相同。
CL_INVALID_MEM_OBJECT if src_buffer and dst_buffer are not valid buffer objects.
如果src_buffer和dst_buffer不是有效的缓冲区对象，则CL_INVALID_MEM_OBJECT。
CL_INVALID_VALUE if src_origin, dst_origin, or region is NULL.
如果src_origin、dst_oorigin或region为NULL，则CL_INVALID_VALUE。
CL_INVALID_VALUE if (src_origin, region, src_row_pitch, src_slice_pitch) or (dst_origin, region, dst_row_pitch, dst_slice_pitch) require accessing elements outside the src_buffer and dst_buffer buffer objects respectively.
CL_INVALID_VALUE如果（src_origin，region，src_row_pitch，src_slice_pitch）或（dst_oorigin，region，dst_row_pitch和dst_slice_pitch）需要分别访问src_buffer和dst_buffer缓冲区对象之外的元素。
CL_INVALID_VALUE if any region array element is 0.
CL_INVALID_VALUE，如果任何区域数组元素为0。
CL_INVALID_VALUE if src_row_pitch is not 0 and is less than region[0].
如果src_row_pitch不为0并且小于region[0]，则CL_INVALID_VALUE。
CL_INVALID_VALUE if dst_row_pitch is not 0 and is less than region[0].
如果dst_row_pitch不为0并且小于region[0]，则CL_INVALID_VALUE。
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，如果src_slice_ppitch不为0并且小于region[1]×src_row_pitch，或者如果src_slice_pitch不为零并且不是src_row_pritch的倍数。
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，如果dst_slice_pitch不为0且小于region[1]×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_VALUE如果src_buffer和dst_buffer是相同的缓冲区对象，并且src_slice_pitch不等于dst_slice_pitch并且src_row_pitch也不等于dst_row_pitch。
CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 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_INVALID_EVENT_WAIT_LIST如果event_wait_list为NULL且num_events_in_wait_list>0，或者event_wait_list不为NULL且num_events_in_wait_list为0，或者如果event_wait_list中的事件对象不是有效事件。
CL_MEM_COPY_OVERLAP if src_buffer and dst_buffer are the same buffer or sub-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 Checking for Memory Copy Overlap for details on how to determine if source and destination regions overlap.
CL_MEM_COPY_OVERLAP，如果src_buffer和dst_buffer是相同的缓冲区或子缓冲区对象并且源和目的区域重叠。有关如何确定源区域和目标区域是否重叠的详细信息，请参阅检查内存复制重叠。
CL_MISALIGNED_SUB_BUFFER_OFFSET if src_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue. This error code is missing before version 1.1.
CL_MISALIGNED_SUB_BUFFER_OFFSET（如果src_buffer是子缓冲区对象，并且创建子缓冲区时指定的偏移量未与队列相关设备的CL_DEVICE_MEM_BASE_ADDR_ALIGN值对齐）。1.1版本之前缺少此错误代码。
CL_MISALIGNED_SUB_BUFFER_OFFSET if dst_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue. This error code is missing before version 1.1.
CL_MISALIGNED_SUB_BUFFER_OFFSET（如果dst_buffer是子缓冲区对象，并且创建子缓冲区时指定的偏移量未与队列相关设备的CL_DEVICE_MEM_BASE_ADDR_ALIGN值对齐）。1.1版本之前缺少此错误代码。
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_buffer or dst_buffer.
如果为与src_buffer或dst_buffer关联的数据存储分配内存失败，则CL_MEM_OBJECT_ALLOCATION_FAILURE。
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。