OpenCL™规范 5.2.3. 填充缓冲区对象

5.2.3. Filling Buffer Objects

5.2.3. 填充缓冲区对象

Filling buffer objects is missing before version 1.2. ​ 1.2版本之前缺少填充缓冲区对象。

To enqueue a command to fill a buffer object with a pattern of a given pattern size, call the function

要将命令排入队列以使用给定模式大小的模式填充缓冲区对象，请调用函数

// Provided by CL_VERSION_1_2
cl_int clEnqueueFillBuffer(
    cl_command_queue command_queue,
    cl_mem buffer,
    const void* pattern,
    size_t pattern_size,
    size_t offset,
    size_t size,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

clEnqueueFillBuffer is missing before version 1.2. clEnqueueFillBuffer在版本1.2之前丢失。

• command_queue refers to the host command-queue in which the fill command will be queued. The OpenCL context associated with command_queue and buffer must be the same.

• command_queue是指填充命令将在其中排队的主机命令队列。与command_queue和buffer关联的OpenCL上下文必须相同。

• buffer is a valid buffer object.

• buffer是一个有效的缓冲区对象。

• pattern is a pointer to the data pattern of size pattern_size in bytes. pattern will be used to fill a region in buffer starting at offset and is size bytes in size. The data pattern must be a scalar or vector integer or floating-point data type supported by OpenCL as described in Shared Application Scalar Data Types and Supported Application Vector Data Types. For example, if buffer is to be filled with a pattern of float4 values, then pattern will be a pointer to a cl_float4 value and pattern_size will be sizeof(cl_float4). The maximum value of pattern_size is the size of the largest integer or floating-point vector data type supported by the OpenCL device. The memory associated with pattern can be reused or freed after the function returns.

• ​pattern是指向以字节为单位的patternsize大小的数据模式的指针。模式将用于填充缓冲区中从偏移量开始的区域，大小为字节。数据模式必须是OpenCL支持的标量、矢量整数或浮点数据类型，如共享应用程序标量数据类型和支持的应用程序矢量数据类型中所述。例如，如果缓冲区要用float4值的模式填充，那么模式将是指向cl_float4值，pattern_size将是sizeof（cl_fload4）。pattern_size的最大值是OpenCL设备支持的最大整数或浮点矢量数据类型的大小。在函数返回后，可以重用或释放与模式相关联的内存。

• offset is the location in bytes of the region being filled in buffer and must be a multiple of pattern_size.

• offset是缓冲区中填充区域的位置（以字节为单位），必须是pattern_size的倍数。

• size is the size in bytes of region being filled in buffer and must be a multiple of pattern_size.

• size是缓冲区中填充区域的字节大小，必须是pattern_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 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数组的元素。

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 buffer is created is ignored by clEnqueueFillBuffer.

​clEnqueueFillBuffer忽略使用信息，该使用信息指示内存对象是否可以由内核和/或主机读取或写入，并由创建缓冲区时指定的cl_mem_flags参数值提供。

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

如果函数执行成功，clEnqueueFillBuffer将返回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 offset or offset + size require accessing elements outside the buffer buffer object respectively.

• CL_INVALID_VALUE，如果偏移量或偏移量+大小分别需要访问缓冲缓冲区对象外部的元素。

• CL_INVALID_VALUE if pattern is NULL or if pattern_size is 0 or if pattern_size is not one of { 1, 2, 4, 8, 16, 32, 64, 128 }.

• CL_INVALID_VALUE如果pattern为NULL或者pattern_size为0或者pattern_size不是{1,2,4,8,16,32,64128}之一。

• CL_INVALID_VALUE if offset and size are not a multiple of pattern_size.

• CL_INVALID_VALUE，如果偏移量和大小不是pattern_size的倍数。

• 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_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with 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实现所需的资源失败。