OpenCL™规范 5.3.5. 填充图像对象

5.3.5. Filling Image Objects

5.3.5. 填充图像对象

Filling image objects is missing before version 1.2. ​ 1.2版本之前缺少填充图像对象。

To enqueue a command to fill an image object with a specified color, call the function

要将用指定颜色填充图像对象的命令排入队列，请调用函数

// Provided by CL_VERSION_1_2
cl_int clEnqueueFillImage(
    cl_command_queue command_queue,
    cl_mem image,
    const void* fill_color,
    const size_t* origin,
    const size_t* region,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

clEnqueueFillImage is missing before version 1.2. clEnqueueFillImage在版本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 image must be the same.

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

• image is a valid image object.

• 图像是有效的图像对象。

• fill_color is the color used to fill the image. The fill color is a single floating-point value if the channel order is CL_DEPTH. Otherwise, the fill color is a four component RGBA floating-point color value if the image channel data type is not an unnormalized signed or unsigned integer type, is a four component signed integer value if the image channel data type is an unnormalized signed integer type and is a four component unsigned integer value if the image channel data type is an unnormalized unsigned integer type. The fill color will be converted to the appropriate image channel format and order associated with image.

• ​fill_color是用于填充图像的颜色。如果通道顺序为CL_DEPTH，则填充颜色为单个浮点值。否则，如果图像通道数据类型不是非标准化的有符号或无符号整数类型，则填充颜色是四分量RGBA浮点颜色值；如果图像通道的数据类型是非标准化有符号整数类型则填充颜色为四分量有符号整数值；如果图像信道的数据类型为非标准化无符号整数，则填充色为四分量无符号整数值。填充颜色将被转换为与图像相关联的适当图像通道格式和顺序。

• origin defines the (x, y, z) offset in pixels in the 1D, 2D or 3D image, the (x, y) offset and the image index in the 2D image array or the (x) offset and the image index in the 1D image array. If image is a 2D image object, origin[2] must be 0. If image is a 1D image or 1D image buffer object, origin[1] and origin[2] must be 0. If image is a 1D image array object, origin[2] must be 0. If image is a 1D image array object, origin[1] describes the image index in the 1D image array. If image is a 2D image array object, origin[2] describes the image index in the 2D image array. If image is a mipmapped image, the mip level to fill is determined from origin as described in Specifying Mipmap Levels to Image Operations

• origin定义1D、2D或3D图像中以像素为单位的（x，y，z）偏移、2D图像阵列中的（x、y）偏移和图像索引或1D图像阵列中（x）偏移和图象索引。如果图像是2D图像对象，则原点[2]必须为0。如果图像是1D图像或1D图像缓冲区对象，则origin[1]和origin[2]必须为0。如果图像是1D图像阵列对象，则origin[2]必须为0。如果图像是1D图像阵列对象，origin[1]描述1D图像数组中的图像索引。如果图像是2D图像阵列对象，origin[2]描述2D图像阵列中的图像索引。如果图像是Mipmap图像，则要填充的mip级别是从原点确定的，如“为图像操作指定Mipmap级别”中所述

• region defines the (width, height, depth) in pixels of the 1D, 2D or 3D rectangle, the (width, height) in pixels of the 2D rectangle and the number of images of a 2D image array or the (width) in pixels of the 1D rectangle and the number of images of a 1D image array. If image is a 2D image object, region[2] must be 1. If image is a 1D image or 1D image buffer object, region[1] and region[2] must be 1. If image is a 1D image array object, region[2] must be 1. The values in region cannot be 0.

• region定义1D、2D或3D矩形的（宽度、高度、深度）（以像素为单位）、2D矩形的（宽、高）和2D图像阵列的图像数量或1D矩形的（高）和1D图像阵列的（宽）和图像数量。如果图像是2D图像对象，则region[2]必须为1。如果图像是1D图像或1D图像缓冲对象，则region[1]和region[2]必须为1。如果图像是1D图像阵列对象，则region[2]必须为1。region中的值不能为0。

• 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 image is created is ignored by clEnqueueFillImage.

​clEnqueueFillImage会忽略使用信息，该使用信息指示内存对象是否可以由内核或主机读取或写入，并且由创建映像时指定的cl_mem_flags参数值提供。

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

如果函数执行成功，clEnqueueFillImage将返回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 image are not the same or if the context associated with command_queue and events in event_wait_list are not the same.

• 如果与command_queue和image相关联的上下文不相同，或者与command_ queue和event_wait_list中的事件相关联的语境不相同，则CL_INVALID_CONTEXT。

• CL_INVALID_MEM_OBJECT if image is not a valid image object.

• CL_INVALID_MEM_OBJECT（如果图像不是有效的图像对象）。

• CL_INVALID_VALUE if fill_color is NULL.

• 如果fill_color为NULL，则CL_INVALID_VALUE。

• CL_INVALID_VALUE if origin or region is NULL.

• CL_INVALID_VALUE（如果origin或region为NULL）。

• CL_INVALID_VALUE if the region being filled as specified by origin and region is out of bounds.

• CL_INVALID_VALUE，如果按origin和region指定填充的区域越界。

• CL_INVALID_VALUE if values in origin and region do not follow rules described in the argument description for origin and region.

• CL_INVALID_VALUE，如果原点和区域中的值不遵循origin和region的参数描述中描述的规则。

• 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_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for image are not supported by device associated with queue.

• CL_INVALID_IMAGE_SIZE如果与队列相关联的设备不支持图像的图像尺寸（图像宽度、高度、指定或计算行和/或切片间距）。

• CL_IMAGE_FORMAT_NOT_SUPPORTED if image format (image channel order and data type) for image are not supported by device associated with queue.

• 如果与队列关联的设备不支持图像的图像格式（图像通道顺序和数据类型），则CL_IMAGE_FORMAT_NOT_SUPPORTED。

• CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with image.

• 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实现所需的资源失败。

• CL_INVALID_MIP_LEVEL if the cl_khr_mipmap_image extension is supported, and the mip level specified in origin is not a valid level for image,

• CL_INVALID_MIP_LEVEL如果支持CL_khr_mipmap_image扩展，并且在origin中指定的MIP级别不是图像的有效级别，