clCreateSamplerWithProperties

Creates a sampler object.

`cl_sampler clCreateSamplerWithProperties (`	cl_context `context`,
	const cl_sampler_properties `*sampler_properties`,
	cl_int `*errcode_ret)`

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

cl_sampler_properties enum Property Value Description

cl_sampler_properties enum	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_MIRRORED_REPEAT` `CL_ADDRESS_REPEAT` `CL_ADDRESS_CLAMP_TO_EDGE` `CL_ADDRESS_CLAMP` `CL_ADDRESS_NONE` The default is `CL_ADDRESS_CLAMP`.
`CL_SAMPLER_FILTER_MODE`	cl_filter_mode	Specifies the type of filter that must be applied when reading an image. Valid values are: `CL_FILTER_NEAREST` `CL_FILTER_LINEAR` The default is `CL_FILTER_NEAREST`.

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_MIRRORED_REPEAT
CL_ADDRESS_REPEAT
CL_ADDRESS_CLAMP_TO_EDGE
CL_ADDRESS_CLAMP
CL_ADDRESS_NONE

The default is CL_ADDRESS_CLAMP.

CL_SAMPLER_FILTER_MODE

cl_filter_mode

Specifies the type of filter that must be applied when reading an image. Valid values are:

CL_FILTER_NEAREST
CL_FILTER_LINEAR

The default is CL_FILTER_NEAREST.

If the cl_khr_mipmap_image extension is supported, the following sampler properties can be specified when a sampler object is created using clCreateSamplerWithProperties:

cl_sampler_properties enum	Property Value	Default Value
`CL_SAMPLER_MIP_FILTER_MODE`	cl_filter_mode	`CL_FILTER_NONE`
`CL_SAMPLER_LOD_MIN`	float	`0.0f`
`CL_SAMPLER_LOD_MAX`	float	`MAXFLOAT`

errcode_ret

Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

Notes

A sampler object describes how to sample an image when the image is read in the kernel. The built-in functions to read from an image in a kernel take a sampler as an argument. The sampler arguments to the image read function can be sampler objects created using OpenCL functions and passed as argument values to the kernel or can be samplers declared inside a kernel.

For more information about working with samplers, see sampler_t

If the cl_khr_mipmap_image extension is supported, the sampler properties CL_SAMPLER_MIP_FILTER_MODE, CL_SAMPLER_LOD_MIN and CL_SAMPLER_LOD_MAX 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.

Errors

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 table of OpenCL Device Queries for clGetDeviceInfo 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.

Specification

OpenCL Specification

Also see

clRetainSampler, clReleaseSampler, clGetSamplerInfo sampler_t, cl_khr_mipmap_image

Copyright © 2007-2013 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.