OpenCL™规范 5.7.2. 采样器对象查询

5.7.2. Sampler Object Queries

5.7.2. 采样器对象查询

To return information about a sampler object, call the function

要返回有关采样器对象的信息，请调用函数

// Provided by CL_VERSION_1_0
cl_int clGetSamplerInfo(
    cl_sampler sampler,
    cl_sampler_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

• sampler specifies the sampler being queried.

• sampler指定要查询的采样器。

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

• ​param_name指定要查询的信息。采样器对象查询表中描述了支持的param_name类型列表以及clGetSamplerInfo在param_value中返回的信息。

• 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 Sampler 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 42. List of supported param_names by clGetSamplerInfo​
表42 clGetSamplerInfo支持的参数名称列表

Sampler Info 采样信息	Return Type 返回类型	Description 描述
CL_SAMPLER_REFERENCE_COUNT [24]	cl_uint	Return the sampler reference count. 返回采样器参考计数。
CL_SAMPLER_CONTEXT	cl_context	Return the context specified when the sampler is created. 返回创建采样器时指定的上下文。
CL_SAMPLER_NORMALIZED_COORDS	cl_bool	Return the normalized coords value associated with sampler. 返回与采样器关联的标准化坐标值。
CL_SAMPLER_ADDRESSING_MODE	cl_addressing_mode	Return the addressing mode value associated with sampler. 返回与采样器关联的寻址模式值。
CL_SAMPLER_FILTER_MODE	cl_filter_mode	Return the filter mode value associated with sampler. 返回与采样器关联的过滤器模式值。
CL_SAMPLER_PROPERTIES missing before version 3.0.	cl_sampler_properties[]	Return the properties argument specified in clCreateSamplerWithProperties. ​返回clCreateSamplerWithProperties中指定的属性参数。 If the properties argument specified in clCreateSamplerWithProperties used to create sampler was not NULL, the implementation must return the values specified in the properties argument in the same order and without including additional properties. ​如果用于创建采样器的clCreateSamplerWithProperties中指定的properties参数不是NULL，则实现必须以相同的顺序返回properties参数中指定的值，并且不包括其他属性。 If sampler was created using clCreateSampler, or if the properties argument specified in clCreateSamplerWithProperties was NULL, the implementation must return param_value_size_ret equal to 0, indicating that there are no properties to be returned. ​如果sampler是使用clCreateSampler创建的，或者clCreateSamplerWithProperties中指定的properties参数为NULL，则实现必须返回等于0的param_value_size_ret，表示没有要返回的属性。

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

如果函数执行成功，clGetSamplerInfo将返回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 Sampler Object Queries table and param_value is not NULL.

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

• CL_INVALID_SAMPLER if sampler is a not a valid sampler object.

• CL_INVALID_SAMPLER，如果sampler不是有效的采样器对象。

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