OpenCL™规范 5.3.9. 图像对象查询

5.3.9. Image Object Queries

5.3.9. 图像对象查询

To get information that is common to all memory objects, use the clGetMemObjectInfo function described in Memory Object Queries.

​要获取所有内存对象通用的信息，请使用“内存对象查询”中描述的clGetMemObjectInfo函数。

To get information specific to an image object created with clCreateImage, clCreateImageWithProperties, clCreateImage2D, or clCreateImage3D call the function

若要获取特定于使用clCreateImage、clCreateImageWithProperties、clCreateImage 2D或clCreateImage3D创建的图像对象的信息，请调用函数

// Provided by CL_VERSION_1_0
cl_int clGetImageInfo(
    cl_mem image,
    cl_image_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

• image specifies the image object being queried.

• image指定要查询的图像对象。

• param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetImageInfo is described in the Image Object Queries table.

• ​param_name指定要查询的信息。支持的param_name类型的列表以及clGetImageInfo以param_value返回的信息在Image Object Queries表中进行了描述。

• param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

• param_value是一个指向内存的指针，在内存中返回所查询的适当结果。如果param_value为NULL，则忽略它。

• param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the Image Object Queries table.

• ​param_value_size用于指定param_value指向的内存大小（以字节为单位）。此大小必须≥返回类型的大小，如图像对象查询表中所述。

• param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

• param_value_size_ret返回param_name查询的数据的实际大小（以字节为单位）。如果param_value_size_ret为NULL，则忽略它。

Table 35. List of supported param_names by clGetImageInfo
表35 clGetImageInfo支持的参数名称列表

Image Info 图像信息	Return type 返回类型	Description 描述
CL_IMAGE_FORMAT	cl_image_format	Return the image format descriptor specified when image is created with clCreateImage, clCreateImageWithProperties, clCreateImage2D or clCreateImage3D. ​ 返回使用clCreateImage、clCreateImageWithProperties、clCreateImage 2D或clCreateImage3D创建图像时指定的图像格式描述符。
CL_IMAGE_ELEMENT_SIZE	size_t	Return size of each element of the image memory object given by image in bytes. 返回图像给定的图像内存对象的每个元素的大小（以字节为单位）。
CL_IMAGE_ROW_PITCH	size_t	Returns the row pitch in bytes of a row of elements of the image object given by image. 返回由图像给定的图像对象的元素行的行间距（以字节为单位）。 If image was created with a non-zero value for image_row_pitch, then the value provided for image_row_pitch by the application is returned, otherwise the returned value is calculated as CL_IMAGE_WIDTH × CL_IMAGE_ELEMENT_SIZE. ​ 如果创建的图像的image_row_pitch值为非零值，则返回应用程序为image_row_pritch提供的值，否则返回的值计算为CL_IMAGE_WIDTH×CL_IMAGE_ELEMENT_SIZE。
CL_IMAGE_SLICE_PITCH	size_t	Returns the slice pitch in bytes of a 2D slice for the 3D image object or size of each image in a 1D or 2D image array given by image. 返回3D图像对象的2D切片的切片间距（以字节为单位）或图像给定的1D或2D图像阵列中每个图像的大小。 If image was created with a non-zero value for image_slice_pitch then the value provided for image_slice_pitch by the application is returned, otherwise the returned value is calculated as: 如果创建的图像的image_slice_pitch值为非零值，则返回应用程序为image_slice_pitch提供的值，否则返回值计算为： - CL_IMAGE_ROW_PITCH for 1D image arrays. -CL_IMAGE_ROW_PITCH用于1D图像阵列。 ​ - CL_IMAGE_HEIGHT × CL_IMAGE_ROW_PITCH for 3D images and 2D image arrays. -CL_IMAGE_HEIGHT×CL_IMAGE_ROW_PITCH用于3D图像和2D图像阵列。 ​ For a 1D image, 1D image buffer and 2D image object return 0. 对于1D图像，1D图像缓冲区和2D图像对象返回0。
CL_IMAGE_WIDTH	size_t	Return width of the image in pixels. 返回图像的宽度（以像素为单位）。
CL_IMAGE_HEIGHT	size_t	Return height of the image in pixels. For a 1D image, 1D image buffer and 1D image array object, height = 0. 返回图像的高度（以像素为单位）。对于1D图像、1D图像缓冲区和1D图像阵列对象，高度=0。
CL_IMAGE_DEPTH	size_t	Return depth of the image in pixels. For a 1D image, 1D image buffer, 2D image or 1D and 2D image array object, depth = 0. 返回图像的深度（以像素为单位）。对于1D图像、1D图像缓冲器、2D图像或1D和2D图像阵列对象，深度=0。
CL_IMAGE_ARRAY_SIZE missing before version 1.2.	size_t	Return number of images in the image array. If image is not an image array, 0 is returned. 返回图像阵列中的图像数。如果图像不是图像数组，则返回0。
CL_IMAGE_BUFFER missing before version 1.2 and deprecated by version 2.0.	cl_mem	Return buffer object associated with image. 返回与图像关联的缓冲区对象。
CL_IMAGE_NUM_MIP_LEVELS missing before version 1.2.	cl_uint	Return num_mip_levels associated with image. 返回与图像关联的num_mip_levels。
CL_IMAGE_NUM_SAMPLES missing before version 1.2.	cl_uint	Return num_samples associated with image. 返回与图像关联的num_samples。
CL_IMAGE_DX9_MEDIA_PLANE_KHR provided by the cl_khr_dx9_media_sharing extension.	cl_uint	If image was created using clCreateFromDX9MediaSurfaceKHR, returns the plane argument specified when image was created. 如果图像是使用clCreateFromDX9MediaSurfaceKHR创建的，则返回创建图像时指定的平面参数。
CL_IMAGE_D3D10_SUBRESOURCE_KHR provided by the cl_khr_d3d10_sharing extension.	cl_uint	If image was created using clCreateFromD3D10Texture2DKHR, or clCreateFromD3D10Texture3DKHR, returns the subresource argument specified when image was created. 如果图像是使用clCreateFromD3D10Texture2DKHR或clCreateFromD3 D10Texture3DKHR创建的，则返回创建图像时指定的子资源参数。
CL_IMAGE_D3D11_SUBRESOURCE_KHR provided by the cl_khr_d3d11_sharing extension.	cl_uint	If image was created using clCreateFromD3D11Texture2DKHR, or clCreateFromD3D11Texture3DKHR, returns the subresource argument specified when image was created. 如果图像是使用clCreateFromD3D11Texture2DKHR或clCreateFromD3 D11Textre3DKHR创建的，则返回创建图像时指定的子资源参数。

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

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

• CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in the Image Object Queries table and param_value is not NULL.

• CL_INVALID_VALUE如果param_name无效，或者param_value_size指定的字节大小小于图像对象查询表中描述的返回类型的大小，并且param_value不为NULL。

• CL_INVALID_MEM_OBJECT if image is a not a valid image object.

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

• 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 errors may be returned if the cl_khr_dx9_media_sharing extension is supported:

​如果支持cl_khr_dx9_media_sharing扩展，则可能返回以下错误：

• CL_INVALID_DX9_MEDIA_SURFACE_KHR if param_name is CL_IMAGE_DX9_MEDIA_PLANE_KHR and image was not created by calling clCreateFromDX9MediaSurfaceKHR.

• 如果参数名称为CL_IMAGE_DX9_MEDIA_PLANE_KHR，并且图像不是通过调用clCreateFromDX9MediaSurfaceKHR创建的，则为CL_INVALID_DX9_MEDIA-SURFACE_KHR。

The following errors may be returned if the cl_khr_d3d10_sharing extension is supported:

​如果支持cl_khr_d3d10_shareing扩展，则可能返回以下错误：

• CL_INVALID_D3D10_RESOURCE_KHR if param_name is CL_IMAGE_D3D10_SUBRESOURCE_KHR and image was not created by the function clCreateFromD3D10Texture2DKHR, or clCreateFromD3D10Texture3DKHR.

• CL_INVALID_D3D10_RESOURCE_KHR如果param_name为CL_IMAGE_D3D10_SUBRESOURCE_KHR并且图像不是由函数clCreateFromD3D10Texture2DKHR或clCreateFromD3 D10Texture3DKHR创建的。

The following errors may be returned if the cl_khr_d3d11_sharing extension is supported:

​如果支持cl_khr_d3d11_共享扩展，则可能返回以下错误：

• CL_INVALID_D3D11_RESOURCE_KHR if param_name is CL_IMAGE_D3D11_SUBRESOURCE_KHR and image was not created by the function clCreateFromD3D11Texture2DKHR, or clCreateFromD3D11Texture3DKHR.

• CL_INVALID_D3D11_RESOURCE_KHR，如果参数名称为CL_IMAGE_D3D11_SUBRESOURCE_KHR，并且图像不是由函数clCreateFromD3D11Texture2DKHR或clCreateFromD3 D11Texture 3DKHR创建的。