Sampler wrapper

The sampler wrapper module provides functionality for simple handling of OpenCL sampler objects. More...

Macros
#define	ccl_sampler_get_info(smplr, param_name, err)
	Get a CCLWrapperInfo sampler information object. More...
#define	ccl_sampler_get_info(smplr, param_name, err)
	Get a CCLWrapperInfo sampler information object. More...
#define	ccl_sampler_get_info_array(smplr, param_name, param_type, err)
	Macro which returns an array sampler information value. More...
#define	ccl_sampler_get_info_array(smplr, param_name, param_type, err)
	Macro which returns an array sampler information value. More...
#define	ccl_sampler_get_info_scalar(smplr, param_name, param_type, err)
	Macro which returns a scalar sampler information value. More...
#define	ccl_sampler_get_info_scalar(smplr, param_name, param_type, err)
	Macro which returns a scalar sampler information value. More...
#define	ccl_sampler_ref(smplr)   ccl_wrapper_ref((CCLWrapper*) smplr)
	Increase the reference count of the sampler wrapper object. More...
#define	ccl_sampler_ref(smplr)   ccl_wrapper_ref((CCLWrapper*) smplr)
	Increase the reference count of the sampler wrapper object. More...
#define	ccl_sampler_unref(smplr)   ccl_sampler_destroy(smplr)
	Alias to ccl_sampler_destroy(). More...
#define	ccl_sampler_unref(smplr)   ccl_sampler_destroy(smplr)
	Alias to ccl_sampler_destroy(). More...
#define	ccl_sampler_unwrap(smplr)   ((cl_sampler) ccl_wrapper_unwrap((CCLWrapper*) smplr))
	Get the OpenCL sampler object. More...
#define	ccl_sampler_unwrap(smplr)   ((cl_sampler) ccl_wrapper_unwrap((CCLWrapper*) smplr))
	Get the OpenCL sampler object. More...

Typedefs
typedef struct ccl_sampler	CCLSampler
	Sampler wrapper class.

Functions
void	ccl_sampler_destroy (CCLSampler *smplr)
	Decrements the reference count of the wrapper object. More...
CCLSampler *	ccl_sampler_new (CCLContext *ctx, cl_bool normalized_coords, cl_addressing_mode addressing_mode, cl_filter_mode filter_mode, CCLErr **err)
	Create a new sampler wrapper object by specifying a basic set of sampler properties. More...
CCLSampler *	ccl_sampler_new_full (CCLContext *ctx, const cl_sampler_properties *sampler_properties, CCLErr **err)
	Create a new sampler wrapper object using a list of properties. More...
CCLSampler *	ccl_sampler_new_wrap (cl_sampler sampler)
	Get the sampler wrapper for the given OpenCL sampler. More...

Detailed Description

The sampler wrapper module provides functionality for simple handling of OpenCL sampler objects.

Sampler wrapper objects can be instanced with two constructors:

• ccl_sampler_new()
• ccl_sampler_new_full()

The former follows the constructor format in OpenCL 1.0-1.2, where three main sampler properties are directly given as constructor arguments, namely the normalized coordinates flag, the addressing mode and the filter mode. The later uses the OpenCL 2.0 constructor format, in which sampler properties are given in a zero-terminated array of cl_sampler_properties. Both formats can be used without concern for the underlying platform's OpenCL version, because cf4ocl will automatically select the most adequate OpenCL constructor.

Sampler wrapper objects should be freed with the ccl_sampler_destroy() function, in accordance with the cf4ocl new/destroy rule.

Sampler wrapper objects can be directly passed as kernel arguments to functions such as ccl_kernel_set_args_and_enqueue_ndrange() or ccl_kernel_set_args().

Information about sampler objects can be fetched using the sampler info macros:

• ccl_sampler_get_info_scalar()
• ccl_sampler_get_info_array()
• ccl_sampler_get_info()

Example:

    CCLContext* ctx;
    CCLSampler* smplr;
    CCLErr* err = NULL;

    smplr = ccl_sampler_new(ctx, CL_FALSE, CL_ADDRESS_CLAMP_TO_EDGE,
        CL_FILTER_NEAREST, &err);

    ccl_sampler_destroy(smplr);

Macro Definition Documentation

#define ccl_sampler_get_info	(		smplr,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) smplr, NULL, param_name, 0, \
        CCL_INFO_SAMPLER, CL_FALSE, err)

Get a CCLWrapperInfo sampler information object.

Parameters

[in]	smplr	The sampler wrapper object.
[in]	param_name	Name of information/parameter to get.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested sampler information object. This object will be automatically freed when the sampler wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 118 of file ccl_sampler_wrapper.h.

#define ccl_sampler_get_info	(		smplr,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) smplr, NULL, param_name, 0, \
        CCL_INFO_SAMPLER, CL_FALSE, err)

Get a CCLWrapperInfo sampler information object.

Parameters

[in]	smplr	The sampler wrapper object.
[in]	param_name	Name of information/parameter to get.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested sampler information object. This object will be automatically freed when the sampler wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 118 of file ccl_sampler_wrapper.h.

#define ccl_sampler_get_info_array	(		smplr,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) smplr, \
        NULL, param_name, sizeof(param_type), CCL_INFO_SAMPLER, CL_FALSE, err)

Macro which returns an array sampler information value.

Note

As of OpenCL 2.0, there are no array sampler information values. This macro is provided for completeness.

Use with care. In case an error occurs, NULL is returned, which might be ambiguous if NULL is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	smplr	The sampler wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. char*, size_t*, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested sampler information value. This value will be automatically freed when the sampler wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 161 of file ccl_sampler_wrapper.h.

#define ccl_sampler_get_info_array	(		smplr,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) smplr, \
        NULL, param_name, sizeof(param_type), CCL_INFO_SAMPLER, CL_FALSE, err)

Macro which returns an array sampler information value.

Note

As of OpenCL 2.0, there are no array sampler information values. This macro is provided for completeness.

Use with care. In case an error occurs, NULL is returned, which might be ambiguous if NULL is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	smplr	The sampler wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. char*, size_t*, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested sampler information value. This value will be automatically freed when the sampler wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 161 of file ccl_sampler_wrapper.h.

#define ccl_sampler_get_info_scalar	(		smplr,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) smplr, \
        NULL, param_name, sizeof(param_type), CCL_INFO_SAMPLER, CL_FALSE, err))

Macro which returns a scalar sampler information value.

Use with care. In case an error occurs, zero is returned, which might be ambiguous if zero is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	smplr	The sampler wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. cl_uint, size_t, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested sampler information value. This value will be automatically freed when the sampler wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 138 of file ccl_sampler_wrapper.h.

#define ccl_sampler_get_info_scalar	(		smplr,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) smplr, \
        NULL, param_name, sizeof(param_type), CCL_INFO_SAMPLER, CL_FALSE, err))

Macro which returns a scalar sampler information value.

Use with care. In case an error occurs, zero is returned, which might be ambiguous if zero is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	smplr	The sampler wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. cl_uint, size_t, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested sampler information value. This value will be automatically freed when the sampler wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 138 of file ccl_sampler_wrapper.h.

#define ccl_sampler_ref

(

smplr

)

ccl_wrapper_ref((CCLWrapper*) smplr)

Increase the reference count of the sampler wrapper object.

Parameters

[in]

smplr

The sampler wrapper object.

Definition at line 170 of file ccl_sampler_wrapper.h.

#define ccl_sampler_ref

(

smplr

)

ccl_wrapper_ref((CCLWrapper*) smplr)

Increase the reference count of the sampler wrapper object.

Parameters

[in]

smplr

The sampler wrapper object.

Definition at line 170 of file ccl_sampler_wrapper.h.

#define ccl_sampler_unref

(

smplr

)

ccl_sampler_destroy(smplr)

Alias to ccl_sampler_destroy().

Parameters

[in]

smplr

sampler wrapper object to destroy if reference count is 1, otherwise just decrement the reference count.

Definition at line 179 of file ccl_sampler_wrapper.h.

#define ccl_sampler_unref

(

smplr

)

ccl_sampler_destroy(smplr)

Alias to ccl_sampler_destroy().

Parameters

[in]

smplr

sampler wrapper object to destroy if reference count is 1, otherwise just decrement the reference count.

Definition at line 179 of file ccl_sampler_wrapper.h.

#define ccl_sampler_unwrap

(

smplr

)

((cl_sampler) ccl_wrapper_unwrap((CCLWrapper*) smplr))

Get the OpenCL sampler object.

Parameters

[in]

smplr

The sampler wrapper object.

Returns

The OpenCL sampler object.

Definition at line 187 of file ccl_sampler_wrapper.h.

#define ccl_sampler_unwrap

(

smplr

)

((cl_sampler) ccl_wrapper_unwrap((CCLWrapper*) smplr))

Get the OpenCL sampler object.

Parameters

[in]

smplr

The sampler wrapper object.

Returns

The OpenCL sampler object.

Definition at line 187 of file ccl_sampler_wrapper.h.

Function Documentation

void ccl_sampler_destroy

(

CCLSampler *

smplr

)

Decrements the reference count of the wrapper object.

If it reaches 0, the wrapper object is destroyed.

Parameters

[in]

smplr

The sampler wrapper object.

Examples:

image_filter.c.

Definition at line 155 of file ccl_sampler_wrapper.c.

CCLSampler * ccl_sampler_new	(	CCLContext *	ctx,
		cl_bool	normalized_coords,
		cl_addressing_mode	addressing_mode,
		cl_filter_mode	filter_mode,
		CCLErr **	err
	)

Create a new sampler wrapper object by specifying a basic set of sampler properties.

This function mimicks the style of the classic sampler constructor, clCreateSampler(), but can be used with any version of OpenCL. This function calls the ccl_sampler_new_full() function for actual sampler creation.

Parameters

[in]	ctx	A context wrapper object.
[in]	normalized_coords	Are the image coordinates normalized?
[in]	addressing_mode	How to handle out-of-range coordinates.
[in]	filter_mode	Filter to apply when reading an image.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new sampler wrapper object or NULL if an error occurs.

Examples:

image_filter.c.

Definition at line 182 of file ccl_sampler_wrapper.c.

CCLSampler * ccl_sampler_new_full	(	CCLContext *	ctx,
		const cl_sampler_properties *	sampler_properties,
		CCLErr **	err
	)

Create a new sampler wrapper object using a list of properties.

If a supported property is not specified, a default value is used. Some valid properties are CL_SAMPLER_NORMALIZED_COORDS (default value is CL_TRUE), CL_SAMPLER_ADDRESSING_MODE (default value is CL_ADDRESS_CLAMP) and CL_SAMPLER_FILTER_MODE (default value is CL_FILTER_NEAREST).

This function mimicks the style of the OpenCL 2.0 sampler constructor, clCreateSamplerWithProperties(), but can be used with any version of OpenCL. Thus, The underlying OpenCL sampler object is created using:

• clCreateSampler() - for platforms with OpenCL version <= 1.2
• clCreateSamplerWithProperties() - for platforms with OpenCL version >= 2.0.

Parameters

[in]	ctx	A context wrapper object.
[in]	sampler_properties	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. If a supported property is not specified, its default value will be used. If NULL, default values for supported sampler properties will be used.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new sampler wrapper object or NULL if an error occurs.

Definition at line 229 of file ccl_sampler_wrapper.c.

CCLSampler * ccl_sampler_new_wrap ( cl_sampler  sampler )

protected

Get the sampler wrapper for the given OpenCL sampler.

If the wrapper doesn't exist, its created with a reference count of 1. Otherwise, the existing wrapper is returned and its reference count is incremented by 1.

This function will rarely be called from client code, except when clients wish to directly wrap an OpenCL sampler in a CCLSampler wrapper object.

Parameters

[in]

sampler

The OpenCL sampler to be wrapped.

Returns

The CCLSampler wrapper for the given OpenCL sampler.

Definition at line 139 of file ccl_sampler_wrapper.c.