C Specification

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.

Parameters

  • context must be a valid OpenCL context.

  • 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.

  • errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

Description

Table 1. List of supported sampler creation properties by 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.

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_CLAMP_TO_EDGE - Out-of-range image coordinates are clamped to the edge of the image.

CL_ADDRESS_CLAMP - Out-of-range image coordinates are assigned a border color value.

CL_ADDRESS_REPEAT - Out-of-range image coordinates read from the image as if the image data were replicated in all dimensions.

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.

The default is 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_LINEAR - Returns a weighted average of the four image elements nearest to the image coordinate.

The default value is 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:

CL_FILTER_NEAREST - Use the nearest mipmap level to the image coordinate.

CL_FILTER_LINEAR - Use a weighted average of the two mipmap levels nearest to the image coordinate.

The default is 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.

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.
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.

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:

  • CL_INVALID_CONTEXT if context is not a valid 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_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_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.

See Also

CL_VERSION_2_0, cl_context, cl_int, cl_sampler_properties

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL 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