Description

The image read functions take a sampler argument. The sampler can be passed as an argument to the kernel using clSetKernelArg, or can be declared in the outermost scope of kernel functions, or it can be a constant variable of type sampler_t declared in the program source.

Sampler variables in a program are declared to be of type sampler_t. A variable of sampler_t type declared in the program source must be initialized with a 32-bit unsigned integer constant, which is interpreted as a bit-field specifying the following properties:

  • Addressing Mode

  • Filter Mode

  • Normalized Coordinates

These properties control how elements of an image object are read by read_image{f|i|ui}.

Samplers can also be declared as global constants in the program source using the following syntax.

const sampler_t <sampler name> = <value>

or

constant sampler_t <sampler name> = <value>

or

__constant sampler_t <sampler_name> = <value>

Note that samplers declared using the constant qualifier are not counted towards the maximum number of arguments pointing to the constant address space or the maximum size of the constant address space allowed per device (i.e. the value of the CL_DEVICE_MAX_CONSTANT_ARGS and CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE device queries).

The sampler fields are described in the following table.

Table 1. Sampler Descriptor
Sampler State Description

<normalized coords>

Specifies whether the x, y and z coordinates are passed in as normalized or unnormalized values. This must be a literal value and can be one of the following predefined enums:

CLK_NORMALIZED_COORDS_TRUE or CLK_NORMALIZED_COORDS_FALSE.

The samplers used with an image in multiple calls to read_image{f|i|ui} declared in a kernel must use the same value for <normalized coords>.

<addressing mode>

Specifies the image addressing mode, i.e. how out-of-range image coordinates are handled. This must be a literal value and can be one of the following predefined enums:

CLK_ADDRESS_MIRRORED_REPEAT - Flip the image coordinate at every integer junction. This addressing mode can only be used with normalized coordinates. If normalized coordinates are not used, this addressing mode may generate image coordinates that are undefined.

CLK_ADDRESS_REPEAT - out-of-range image coordinates are wrapped to the valid range. This addressing mode can only be used with normalized coordinates. If normalized coordinates are not used, this addressing mode may generate image coordinates that are undefined.

CLK_ADDRESS_CLAMP_TO_EDGE - out-of-range image coordinates are clamped to the extent.

CLK_ADDRESS_CLAMP - out-of-range image coordinates will return a border color [1].

CLK_ADDRESS_NONE - for this addressing mode the programmer guarantees that the image coordinates used to sample elements of the image refer to a location inside the image; otherwise the results are undefined.

For 1D and 2D image arrays, the addressing mode applies only to the x and (x, y) coordinates. The addressing mode for the coordinate which specifies the array index is always CLK_ADDRESS_CLAMP_TO_EDGE.

<filter mode>

Specifies the filter mode to use. This must be a literal value and can be one of the following predefined enums: CLK_FILTER_NEAREST or CLK_FILTER_LINEAR.

Refer to the detailed description of these filter modes.

Examples:

const sampler_t samplerA = CLK_NORMALIZED_COORDS_TRUE |
                           CLK_ADDRESS_REPEAT |
                           CLK_FILTER_NEAREST;

samplerA specifies a sampler that uses normalized coordinates, the repeat addressing mode and a nearest filter.

The maximum number of samplers that can be declared in a kernel can be queried using the CL_DEVICE_MAX_SAMPLERS token in clGetDeviceInfo.

See Also

No cross-references are available

Document Notes

For more information, see the OpenCL C Specification

This page is extracted from the OpenCL C Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0

1. This is similar to the GL_ADDRESS_CLAMP_TO_BORDER addressing mode.