clGetImageInfo.adoc

_header.adoc

clGetImageInfo

Get information specific to an image object created with clCreateImage.

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)

Parameters

image

Specifies the image object being queried.

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 table below (Table 5.9).

param_value

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

param_value_size

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 table below (Table 5.9).

cl_image_info	Return Type	Info. returned in param_value
CL_IMAGE_FORMAT	cl_image_format	Return image format descriptor specified when image is created with clCreateImage.
CL_IMAGE_ELEMENT_SIZE	size_t	Return size of each element of the image memory object given by image in bytes. An element is made up of n channels. The value of n is given in cl_image_format descriptor.
CL_IMAGE_ROW_PITCH	size_t	Return calculated row pitch in bytes of a row of elements of the image object given by image.
CL_IMAGE_SLICE_PITCH	size_t	Return calculated 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. For a 1D image, 1D image buffer and 2D image object return 0.
CL_IMAGE_WIDTH	size_t	Return width of image in pixels.
CL_IMAGE_HEIGHT	size_t	Return height of image in pixels. For a 1D image, 1D image buffer and 1D image array object, height = 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.
CL_IMAGE_ARRAY_SIZE	size_t	Return number of images in the image array. If image is not an image array, 0 is returned.
CL_IMAGE_NUM_MIP_LEVELS	cl_uint	Return num_mip_levels associated with image.
CL_IMAGE_NUM_SAMPLES	cl_uint	Return num_samples associated with image.
CL_IMAGE_D3D10_SUBRESOURCE_KHR	ID3D10Resource *	(if the cl_khr_d3d10_sharing extension is enabled) If image was created using clCreateFromD3D10Texture2DKHR or clCreateFromD3D10Texture3DKHR, returns the subresource argument specified when image was created.
CL_IMAGE_DX9_MEDIA_PLANE_KHR	cl_uint	Returns the plane argument value specified when memobj is created using clCreateFromDX9MediaSurfaceKHR. (If the cl_khr_dx9_media_sharing extension is supported)
CL_IMAGE_D3D11_- SUBRESOURCE_KHR	ID3D11Resource *	If the cl_khr_d3d11_sharing extension is suported, If image was created using clCreateFromD3D11Texture2DKHR, or clCreateFromD3D11Texture3DKHR, returns the subresource argument specified when image was created.
CL_IMAGE_D3D11_- SUBRESOURCE_KHR	UINT	If the cl_khr_d3d11_sharing extension is suported, If image was created using clCreateFromD3D11Texture2DKHR, or clCreateFromD3D11Texture3DKHR, returns the subresource argument specified when image was created.
CL_IMAGE_D3D11_- SUBRESOURCE_KHR	UINT	If the cl_khr_d3d11_sharing extension is suported, If image was created using clCreateFromD3D11Texture2DKHR, or clCreateFromD3D11Texture3DKHR, returns the subresource argument specified when image was created.

param_value_size_ret

Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

Notes

To get information that is common to all memory objects, use the clGetMemObjectInfo function.

Errors

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

• 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 table above and param_value is not NULL.

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

• CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_INVALID_DX9_MEDIA_SURFACE_KHR if param_name is CL_IMAGE_DX9_MEDIA_PLANE_KHR and image was not created by the function clCreateFromDX9MediaSurfaceKHR. (If the cl_khr_dx9_media_sharing extension is supported)

• CL_INVALID_D3D10_RESOURCE_KHR if param_name is CL_MEM_D3D10_SUBRESOURCE_KHR and image was not created by the function clCreateFromD3D10Texture2DKHR or clCreateFromD3D10Texture3DKHR. (If the cl_khr_d3d10_sharing extension is supported)

• CL_INVALID_D3D11_RESOURCE_KHR if param_name is CL_MEM_D3D11_SUBRESOURCE_KHR and image was not created by the function clCreateFromD3D11Texture2DKHR or clCreateFromD3D11Texture3DKHR. (If the cl_khr_d3d11_sharing extension is supported)

Also see

clGetMemObjectInfo

_footer.adoc