C Specification

To create a sampler object, call the function

cl_sampler clCreateSamplerWithProperties(
    cl_context context,
    const cl_sampler_properties* sampler_properties,
    cl_int* errcode_ret);
clCreateSamplerWithProperties is missing before version 2.0.


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


Table 1. List of supported sampler creation properties by clCreateSamplerWithProperties
Sampler Property Property Value Description



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.



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.



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.

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

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

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 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0