OpenCL™规范 5.7.1. 创建采样器对象

꧁白杨树下꧂

于 2024-07-12 14:11:44 发布

阅读量54

点赞数

分类专栏： openCL 文章标签： opencl

原文链接：https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#_creating_sampler_objects

版权

openCL 专栏收录该内容

167 篇文章 12 订阅

订阅专栏

5.7.1. Creating Sampler Objects

5.7.1. 创建采样器对象

To create a sampler object, call the function

要创建采样器对象，请调用函数

// Provided by CL_VERSION_2_0
cl_sampler clCreateSamplerWithProperties(
    cl_context context,
    const cl_sampler_properties* sampler_properties,
    cl_int* errcode_ret);

clCreateSamplerWithProperties is missing before version 2.0.

clCreateSamplerWithProperties在版本2.0之前丢失。

context must be a valid OpenCL context.
context必须是有效的OpenCL上下文。
sampler_properties specifies a list of sampler property names and their corresponding values. Each sampler property name is immediately followed by the corresponding desired value. The list is terminated with 0. The list of supported properties is described in the Sampler Properties table. If a supported property and its value is not specified in sampler_properties, its default value will be used. sampler_properties can be NULL in which case the default values for supported sampler properties will be used.
sampler_properties指定采样器属性名称及其相应值的列表。每个采样器属性名称后面紧跟着相应的所需值。列表以0终止。“采样器属性”表中介绍了支持的属性列表。如果sampler_properties中未指定受支持的属性及其值，则将使用其默认值。sampler_properties可以为NULL，在这种情况下，将使用支持的采样器属性的默认值。
errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

Table 41. List of supported sampler creation properties by clCreateSamplerWithProperties

表41 clCreateSamplerWithProperties支持的采样器创建属性列表
Sampler Property 采样器属性	Property Value 属性值	Description 描述
CL_SAMPLER_NORMALIZED_COORDS	`cl_bool`	A boolean value that specifies whether the image coordinates specified are normalized or not. The default value (i.e. the value used if this property is not specified in sampler_properties) is CL_TRUE. 一个布尔值，用于指定指定的图像坐标是否规一化。默认值（即，如果sampler_properties中未指定此属性，则使用的值）为CL_TRUE。
CL_SAMPLER_ADDRESSING_MODE	`cl_addressing_mode`	Specifies how out-of-range image coordinates are handled when reading from an image. Valid values are: 指定从图像读取时如何处理超出范围的图像坐标。有效值为： CL_ADDRESS_NONE - Behavior is undefined for out-of-range image coordinates. CL_ADDRESS_NONE-未定义超出范围的图像坐标的行为。 CL_ADDRESS_CLAMP_TO_EDGE - Out-of-range image coordinates are clamped to the edge of the image. CL_ADDRESS_CLAMP_TO_EDGE-超出范围的图像坐标被箝位到图像的边缘。 CL_ADDRESS_CLAMP - Out-of-range image coordinates are assigned a border color value. CL_ADDRESS_CLAMP-为超出范围的图像坐标指定边界颜色值。 CL_ADDRESS_REPEAT - Out-of-range image coordinates read from the image as if the image data were replicated in all dimensions. CL_ADDRESS_REPEAT-从图像读取的超出范围的图像坐标，就好像在所有维度上复制了图像数据一样。 CL_ADDRESS_MIRRORED_REPEAT - Out-of-range image coordinates read from the image as if the image data were replicated in all dimensions, mirroring the image contents at the edge of each replication. CL_ADDRESS_MIRRRED_REPAT-从图像读取的超出范围的图像坐标，就好像在所有维度上复制了图像数据一样，镜像了每次复制边缘的图像内容。 The default is CL_ADDRESS_CLAMP. 默认值为CL_ADDRESS_CLAMP。
CL_SAMPLER_FILTER_MODE	`cl_filter_mode`	Specifies the type of filter that is applied when reading an image. Valid values are: 指定读取图像时应用的过滤器类型。有效值为： CL_FILTER_NEAREST - Returns the image element nearest to the image coordinate. CL_FILTER_NEAREST-返回最接近图像坐标的图像元素。 CL_FILTER_LINEAR - Returns a weighted average of the four image elements nearest to the image coordinate. CL_FILTER_LINEAR-返回最接近图像坐标的四个图像元素的加权平均值。 The default value is CL_FILTER_NEAREST. 默认值为CL_FILTER_NEAREST。
CL_SAMPLER_MIP_FILTER_MODE_KHR provided by the `cl_khr_mipmap_image` extension.	`cl_filter_mode`	Specifies the mipmap filter used when sampling from a mipmapped image. The available filter are: 指定从mipmap图像采样时使用的mipmap过滤器。可用的过滤器有： CL_FILTER_NEAREST - Use the nearest mipmap level to the image coordinate. CL_FILTER_NEAREST-使用与图像坐标最近的mipmap级别。 CL_FILTER_LINEAR - Use a weighted average of the two mipmap levels nearest to the image coordinate. CL_FILTER_LINEAR-使用最接近图像坐标的两个mipmap级别的加权平均值。 The default is CL_FILTER_NEAREST. 默认值为CL_FILTER_NEAREST。
CL_SAMPLER_LOD_MIN_KHR provided by the `cl_khr_mipmap_image` extension.	`cl_float`	Specifies the minimum value to which the computed level of detail lambda is clamped when sampling from a mipmapped image. The default is `0.0f`. 指定从mipmap图像采样时，计算的详细程度lambda被钳制到的最小值。默认值为0.0f。
CL_SAMPLER_LOD_MAX_KHR provided by the `cl_khr_mipmap_image` extension.	`cl_float`	Specifies the maximum value to which the computed level of detail lambda is clamped when sampling from a mipmapped image. The default is `MAXFLOAT`. 指定从mipmap图像采样时，计算的详细程度lambda被钳制到的最大值。默认值为MAXFLOAT。

When the cl_khr_mipmap_image extension is supported, the sampler properties CL_SAMPLER_MIP_FILTER_MODE_KHR, CL_SAMPLER_LOD_MIN_KHR and CL_SAMPLER_LOD_MAX_KHR cannot be specified with any samplers initialized in the OpenCL program source. Only the default values for these properties will be used. To create a sampler with specific values for these properties, a sampler object must be created with clCreateSamplerWithProperties and passed as an argument to a kernel.

如果支持cl_khr_mipmap_image扩展，则无法使用OpenCL程序源中初始化的任何采样器指定采样器属性CL_SAMPLER_MIP_FILTER_MODE_KHR、CL_SAMPLER_LOD_MIN_KHR和CL_SAMPLER_LOD_MAX_KHR。将仅使用这些属性的默认值。要为这些属性创建具有特定值的采样器，必须使用clCreateSamplerWithProperties创建采样器对象，并将其作为参数传递给内核。

clCreateSamplerWithProperties returns a valid non-zero sampler object and errcode_ret is set to CL_SUCCESS if the sampler object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

clCreateSamplerWithProperties返回一个有效的非零采样器对象，如果成功创建采样器对象，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_CONTEXT（如果context 不是有效上下文）。
CL_INVALID_VALUE if the property name in sampler_properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once.
CL_INVALID_VALUE如果sampler_properties中的属性名称不是支持的属性名称，如果为支持的属性名指定的值无效，或者如果多次指定相同的属性名。
CL_INVALID_OPERATION if images are not supported by any device associated with context (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the Device Queries table is CL_FALSE).
CL_INVALID_OPERATION，如果与上下文相关联的任何设备都不支持图像（即，在设备查询表中指定的CL_DEVICE_IMAGE_SUPPORT为CL_FALSE）。
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实现所需的资源失败。

To create a sampler object, call the function

要创建采样器对象，请调用函数

// Provided by CL_VERSION_1_0
cl_sampler clCreateSampler(
    cl_context context,
    cl_bool normalized_coords,
    cl_addressing_mode addressing_mode,
    cl_filter_mode filter_mode,
    cl_int* errcode_ret);

clCreateSampler is deprecated by version 2.0.

clCreateSampler已被2.0版本弃用。

context must be a valid OpenCL context.
context 必须是有效的OpenCL上下文。
normalized_coords has the same interpretation as CL_SAMPLER_NORMALIZED_COORDS in the sampler creation properties table.
normalized_coords与采样器创建属性表中的CL_SAMPLER_NORMALIZED_COORDS具有相同的解释。
addressing_mode has the same interpretation as CL_SAMPLER_ADDRESSING_MODE in the sampler creation properties table.
addressing_mode与采样器创建属性表中的CL_SAMPLER_ADDRESSING_MODE具有相同的解释。
filter_mode has the same interpretation as CL_SAMPLER_FILTER_MODE in the sampler creation properties table.
filter_mode与采样器创建属性表中的CL_SAMPLER_FILTER_MODE具有相同的解释。
errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

clCreateSampler returns a valid non-zero sampler object and errcode_ret is set to CL_SUCCESS if the sampler object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

clCreateSampler返回一个有效的非零采样器对象，如果成功创建采样器对象，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_CONTEXT（如果context不是有效上下文）。
CL_INVALID_VALUE if addressing_mode, filter_mode, normalized_coords or a combination of these arguements are not valid.
CL_INVALID_VALUE，如果addressing_mode、filter_mode、normalized_coords或这些参数的组合无效。
CL_INVALID_OPERATION if images are not supported by any device associated with context (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the Device Queries table is CL_FALSE).
CL_INVALID_OPERATION，如果与context相关联的任何设备都不支持图像（即，在设备查询表中指定的CL_DEVICE_IMAGE_SUPPORT为CL_FALSE）。
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实现所需的资源失败。

To retain a sampler object, call the function

要保留采样器对象，请调用函数

// Provided by CL_VERSION_1_0
cl_int clRetainSampler(
    cl_sampler sampler);

sampler specifies the sampler to be released.
sampler指定要释放的采样器。

The sampler reference count is incremented. clCreateSamplerWithProperties and clCreateSampler perform an implicit retain.

sampler参考计数递增。clCreateSamplerWithProperties和clCreateSampler执行隐式保留。

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

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

CL_INVALID_SAMPLER if sampler is 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实现所需的资源。

To release a sampler object, call the function

要释放采样器对象，请调用函数

// Provided by CL_VERSION_1_0
cl_int clReleaseSampler(
    cl_sampler sampler);

sampler specifies the sampler to be released.
sampler指定要释放的采样器。

The sampler reference count is decremented. The sampler object is deleted after the reference count becomes zero and commands queued for execution on a command-queue(s) that use sampler have finished.

sampler引用计数递减。在引用计数变为零并且使用采样器的命令队列上排队执行的命令已完成后，采样器对象将被删除。

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

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

CL_INVALID_SAMPLER if sampler is 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实现所需的资源。