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);


  • 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 https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html#clCreateSamplerWithProperties
cl_sampler_properties enum 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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.