OpenCL™规范 5.3.1.2. 图像描述符

5.3.1.2. Image Descriptor

5.3.1.2. 图像描述符

The cl_image_desc image descriptor structure describes the image type and dimensions of an image or image array when creating an image using clCreateImage or clCreateImageWithProperties, and is defined as:

​cl_image_desc图像描述符结构描述了使用clCreateImage或clCreateImageWithProperties创建图像时图像或图像阵列的图像类型和尺寸，并定义为：

// Provided by CL_VERSION_1_2
typedef struct cl_image_desc {
    cl_mem_object_type    image_type;
    size_t                image_width;
    size_t                image_height;
    size_t                image_depth;
    size_t                image_array_size;
    size_t                image_row_pitch;
    size_t                image_slice_pitch;
    cl_uint               num_mip_levels;
    cl_uint               num_samples;
    union {
        cl_mem buffer;
        cl_mem mem_object;
    };
} cl_image_desc;

• image_type describes the image type and must be either CL_MEM_OBJECT_IMAGE1D, CL_MEM_OBJECT_IMAGE1D_BUFFER, CL_MEM_OBJECT_IMAGE1D_ARRAY, CL_MEM_OBJECT_IMAGE2D, CL_MEM_OBJECT_IMAGE2D_ARRAY, or CL_MEM_OBJECT_IMAGE3D.

• ​image_type描述图像类型，并且必须是CL_MEM_OBJECT_IMAGE1D、CL_MEM_OBJECT_IMAGE1D_BUFFER、CL_MEM_OBJECT_IMAGE1D_ARRAY、CL_MEM _OBJECT-IMAGE2D、CL_MEM_OBJECT_IMAGE2D_ARRAY或CL_MEM_OBJECT_IMAGE3D。

• image_width is the width of the image in pixels. For a 2D image and image array, the image width must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE2D_MAX_WIDTH. For a 3D image, the image width must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE3D_MAX_WIDTH. For a 1D image buffer, the image width must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE_MAX_BUFFER_SIZE. For a 1D image and 1D image array, the image width must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE2D_MAX_WIDTH.

• ​image_width是以像素为单位的图像宽度。对于2D图像和图像阵列，图像宽度必须为≥1且≤CL_DEVICE_IMAGE2D_MAX_WIDTH的值。对于3D图像，图像宽度必须为≥1且≤CL_DEVICE_IMAGE3D_MAX_WIDTH的值。对于1D图像缓冲区，图像宽度必须为≥1且≤CL_DEVICE_IMAGE_MAX_BUFFER_SIZE的值。对于1D图像和1D图像阵列，图像宽度必须为≥1且≤CL_DEVICE_IMAGE2D_MAX_WIDTH的值。

• image_height is the height of the image in pixels. This is only used if the image is a 2D or 3D image, or a 2D image array. For a 2D image or image array, the image height must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE2D_MAX_HEIGHT. For a 3D image, the image height must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE3D_MAX_HEIGHT.

• ​image_height是以像素为单位的图像的高度。仅当图像是2D或3D图像或2D图像阵列时才使用此选项。对于2D图像或图像阵列，图像高度必须为≥1且≤CL_DEVICE_IMAGE2D_MAX_HEIGHT的值。对于3D图像，图像高度必须为≥1且≤CL_DEVICE_IMAGE3D_MAX_HEIGHT的值。

• image_depth is the depth of the image in pixels. This is only used if the image is a 3D image and must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE3D_MAX_DEPTH.

• ​image_depth是以像素为单位的图像深度。仅当图像是3D图像并且其值必须≥1且≤CL_DEVICE_IMAGE3D_MAX_DEPTH时才使用此选项。

• image_array_size [17] is the number of images in the image array. This is only used if the image is a 1D or 2D image array. The values for image_array_size, if specified, must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE_MAX_ARRAY_SIZE.

• ​image_array_size[17]是图像阵列中的图像数量。这仅在图像是1D或2D图像阵列时使用。image_array_size的值（如果指定）必须是≥1且≤CL_DEVICE_IMAGE_MAX_ARRAY_SIZE的值。

• image_row_pitch is the scan-line pitch in bytes. The image_row_pitch must be zero if host_ptr is NULL, the image is not an image created from an external memory handle, and the image is not a 2D image created from a buffer, If image_row_pitch is zero and host_ptr is not NULL, then the image row pitch is calculated as image_width × the size of an image element in bytes. If image_row_pitch is zero and the image is created from an external memory handle, then the image row pitch is implementation-defined. The image row pitch must be ≥ image_width × the size of an image element in bytes, and must be a multiple of the size of an image element in bytes. For a 2D image created from a buffer the image row pitch must also be a multiple of the maximum of the CL_DEVICE_IMAGE_PITCH_ALIGNMENT value for all devices in the context that support images.

• ​image_row_pitch是以字节为单位的扫描线间距。如果host_ptr为NULL，图像不是从外部内存句柄创建的图像，并且图像不是从缓冲区创建的2D图像，则image_row_pitch必须为零。如果image_row_pritch为零，host_ptr不为NULL，则图像行间距计算为image_width×图像元素的大小（以字节为单位）。如果image_row_pitch为零，并且图像是从外部内存句柄创建的，那么图像行间距是实现定义的。图像行间距必须≥image_width×以字节为单位的图像元素的大小，并且必须是以字节为单元的图像元素大小的倍数。对于从缓冲区创建的2D图像，图像行间距也必须是支持图像的上下文中所有设备的CL_DEVICE_IMAGE_PITCH_ALIGNMENT值的最大值的倍数。

• image_slice_pitch is the size in bytes of each 2D slice in a 3D image, or the size in bytes of each image in a 1D or 2D image array. The image_slice_pitch must be zero if host_ptr is NULL and the image is not an image created from an external memory handle, If image_slice_pitch is zero and host_ptr is not NULL then the image slice pitch is calculated as the image row pitch × image_height for a 2D image array or a 3D image, and as the image row pitch for a 1D image array. If image_slice_pitch is zero and the image is created from an external memory handle, then the image slice pitch is implementation-defined. The image slice pitch must be ≥ the image image row pitch × image_height for a 2D image array or a 3D image, must be ≥ the image row pitch for a 1D image array, and must be a multiple of the image row pitch.

• image_slice_pitch是3D图像中每个2D切片的以字节为单位的大小，或者是1D或2D图像阵列中每个图像的以字节为单位的大小。如果host_ptr为NULL，并且图像不是从外部内存句柄创建的图像，则image_slice_pitch必须为零。如果image_slice_pitch为零并且host_ptr不为NULL，则图像切片间距计算为2D图像阵列或3D图像的图像行间距×image_height，以及1D图像阵列的图像行距。如果image_slice_pitch为零，并且图像是从外部内存句柄创建的，则图像切片间距是实现定义的。对于2D图像阵列或3D图像，图像切片间距必须≥图像图像行间距×图像高度，对于1D图像阵列，必须≥图像行间距，并且必须是图像行间距的倍数。

• num_mip_levels must be 0 unless the cl_khr_mipmap_image extension is supported, in which case it must be a value greater than 1 specifying the number of mipmap levels in the image.

• ​除非支持cl_khr_mipmap_image扩展，否则num_mip_levels必须为0。在这种情况下，它必须是大于1的值，指定图像中的mipmap级别数。

• num_samples must be 0.

• num_samples必须为0。

• mem_object may refer to a valid buffer or image memory object. mem_object can be a buffer memory object if image_type is CL_MEM_OBJECT_IMAGE1D_BUFFER or CL_MEM_OBJECT_IMAGE2D [18]. mem_object can be an image object if image_type is CL_MEM_OBJECT_IMAGE2D [19]. Otherwise it must be NULL. The image pixels are taken from the memory objects data store. When the contents of the specified memory objects data store are modified, those changes are reflected in the contents of the image object and vice-versa at corresponding synchronization points.

• ​mem_object可以指有效的缓冲区或图像存储器对象。如果image_type是CL_MEM_OBJECT_IMAGE1D_BUFFER或CL_MEM_OBJECT_IMAGE2D[18]，则mem_object可以是缓冲存储器对象。如果image_type是CL_MEM_OBJECT_IMAGE2D[19]，则mem_object可以是图像对象。否则，它必须为NULL。图像像素取自存储器对象数据存储器。当指定的存储器对象数据存储的内容被修改时，这些变化反映在图像对象的内容中，反之亦然。

For a 1D image buffer created from a buffer object, the image_width × size of element in bytes must be ≤ size of the buffer object. The image data in the buffer object is stored as a single scanline which is a linear sequence of adjacent elements.

对于从缓冲区对象创建的1D图像缓冲区，image_width×元素大小（以字节为单位）必须≤缓冲区对象的大小。缓冲对象中的图像数据被存储为单个扫描线，该扫描线是相邻元素的线性序列。

For a 2D image created from a buffer object, the image_row_pitch × image_height must be ≤ size of the buffer object specified by mem_object. The image data in the buffer object is stored as a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements padded to image_row_pitch bytes.

对于从缓冲区对象创建的2D图像，image_row_pitch×image_height必须≤mem_object指定的缓冲区对象的大小。缓冲对象中的图像数据被存储为相邻扫描线的线性序列。每条扫描线是填充到image_row_pitch字节的图像元素的线性序列。

For an image object created from another image object, the values specified in the image descriptor except for mem_object must match the image descriptor information associated with mem_object.

对于从另一个图像对象创建的图像对象，在图像描述符中指定的值（mem_object除外）必须与与mem_objects关联的图像描述符信息匹配。

Image elements are stored according to their image format as described in Image Format Descriptor.

​根据图像格式描述符中描述的图像格式来存储图像元素。

If the buffer object specified by mem_object was created with CL_MEM_USE_HOST_PTR, the host_ptr specified to clCreateBuffer or clCreateBufferWithProperties must be aligned to the maximum of the CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT value for all devices in the context associated with the buffer specified by mem_object that support images.

​如果mem_object指定的缓冲区对象是使用CL_MEM_USE_HOST_PTR创建的，则指定给clCreateBuffer或clCreateBufferWithProperties的HOST_PTR必须与上下文中与mem_objects指定的支持映像的缓冲区相关联的所有设备的CL_DEVICE_IMAGE_BASE_ADDRES_ALIGNENT值的最大值对齐。

Creating a 2D image object from another 2D image object creates a new 2D image object that shares the image data store with mem_object but views the pixels in the image with a different image channel order. Restrictions are:

从另一个2D图像对象创建2D图像对象会创建一个新的2D图像对象，该对象与mem_object共享图像数据存储，但以不同的图像通道顺序查看图像中的像素。限制是：

• All of the values specified in image_desc must match the image descriptor information associated with mem_object, except for mem_object.

• image_desc中指定的所有值都必须与mem_object相关联的图像描述符信息匹配，mem_objects除外。

• The image channel data type specified in image_format must match the image channel data type associated with mem_object.

• image_format中指定的图像通道数据类型必须与mem_object关联的图像通道的数据类型匹配。

• The image channel order specified in image_format must be compatible with the image channel order associated with mem_object, as described in the Compatible Image Channel Orders table.

• ​image_format中指定的图像通道顺序必须与mem_object关联的图像通道次序兼容，如compatible image channel Orders表中所述。

The image channel order compatibility constraint allows creation of a sRGB view of the image from a linear RGB view or vice-versa, i.e. the pixels stored in the image can be accessed as linear RGB or sRGB values. 图像通道顺序兼容性约束允许从线性RGB视图创建图像的sRGB视图，反之亦然，即存储在图像中的像素可以作为线性RGB或sRGB值访问。

Table 26. Compatible Image Channel Orders

表26 兼容的图像通道顺序

Image Channel Order in image_format: Image_format中的图像通道顺序：	Image Channel Order associated with mem_object: 与mem_object关联的图像通道顺序：
CL_sBGRA	CL_BGRA
CL_BGRA	CL_sBGRA
CL_sRGBA	CL_RGBA
CL_RGBA	CL_sRGBA
CL_sRGB	CL_RGB
CL_RGB	CL_sRGB
CL_sRGBx	CL_RGBx
CL_RGBx	CL_sRGBx
CL_DEPTH	CL_R

Concurrent reading from, writing to and copying between both a buffer object and 1D image buffer or 2D image object associated with the buffer object is undefined. Only reading from both a buffer object and 1D image buffer or 2D image object associated with the buffer object is defined. 缓冲对象和与缓冲对象相关联的1D图像缓冲区或2D图像对象之间的并行读取、写入和复制是未定义的。仅定义从缓冲对象和与缓冲对象相关联的1D图像缓冲区或2D图像对象两者读取。 Writing to an image created from a buffer and then reading from this buffer in a kernel even if appropriate synchronization operations (such as a barrier) are performed between the writes and reads is undefined. Similarly, writing to the buffer and reading from the image created from this buffer with appropriate synchronization between the writes and reads is undefined. 写入到从缓冲区创建的图像，然后从内核中的缓冲区读取，即使在写入和读取之间执行了适当的同步操作（如屏障）也是未定义的。类似地，在写入和读取之间具有适当同步的情况下，向缓冲区写入和从从该缓冲区创建的图像读取是未定义的。