Context wrapper

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

Macros
#define	ccl_context_get_info(ctx, param_name, err)
	Get a CCLWrapperInfo context information object. More...
#define	ccl_context_get_info(ctx, param_name, err)
	Get a CCLWrapperInfo context information object. More...
#define	ccl_context_get_info_array(ctx, param_name, param_type, err)
	Macro which returns an array context information value. More...
#define	ccl_context_get_info_array(ctx, param_name, param_type, err)
	Macro which returns an array context information value. More...
#define	ccl_context_get_info_scalar(ctx, param_name, param_type, err)
	Macro which returns a scalar context information value. More...
#define	ccl_context_get_info_scalar(ctx, param_name, param_type, err)
	Macro which returns a scalar context information value. More...
#define	ccl_context_new_accel(err)
	Creates a context wrapper for an Accelerator device. More...
#define	ccl_context_new_accel(err)
	Creates a context wrapper for an Accelerator device. More...
#define	ccl_context_new_any(err)   ccl_context_new_from_indep_filter(NULL, NULL, (err))
	Creates a context wrapper for the first found device(s). More...
#define	ccl_context_new_any(err)   ccl_context_new_from_indep_filter(NULL, NULL, (err))
	Creates a context wrapper for the first found device(s). More...
#define	ccl_context_new_cpu(err)
	Creates a context wrapper for a CPU device. More...
#define	ccl_context_new_cpu(err)
	Creates a context wrapper for a CPU device. More...
#define	ccl_context_new_from_dep_filter(filter, data, err)   ccl_context_new_from_filter(CCL_DEVSEL_DEP, (filter), (data), (err))
	Creates a context wrapper using one dependent device filter specified in the function parameters. More...
#define	ccl_context_new_from_dep_filter(filter, data, err)   ccl_context_new_from_filter(CCL_DEVSEL_DEP, (filter), (data), (err))
	Creates a context wrapper using one dependent device filter specified in the function parameters. More...
#define	ccl_context_new_from_device_index(data, err)   ccl_context_new_from_dep_filter(ccl_devsel_dep_index, (data), (err))
	Creates a context wrapper using a device selected by its index. More...
#define	ccl_context_new_from_device_index(data, err)   ccl_context_new_from_dep_filter(ccl_devsel_dep_index, (data), (err))
	Creates a context wrapper using a device selected by its index. More...
#define	ccl_context_new_from_devices(num_devices, devices, err)
	Creates a context wrapper given an array of CCLDevice wrappers. More...
#define	ccl_context_new_from_devices(num_devices, devices, err)
	Creates a context wrapper given an array of CCLDevice wrappers. More...
#define	ccl_context_new_from_filters(filters, err)
	Create a new context wrapper object selecting devices using the given set of filters. More...
#define	ccl_context_new_from_filters(filters, err)
	Create a new context wrapper object selecting devices using the given set of filters. More...
#define	ccl_context_new_from_indep_filter(filter, data, err)   ccl_context_new_from_filter(CCL_DEVSEL_INDEP, (filter), (data), (err))
	Creates a context wrapper using one independent device filter specified in the function parameters. More...
#define	ccl_context_new_from_indep_filter(filter, data, err)   ccl_context_new_from_filter(CCL_DEVSEL_INDEP, (filter), (data), (err))
	Creates a context wrapper using one independent device filter specified in the function parameters. More...
#define	ccl_context_new_from_menu(err)   ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, NULL, (err))
	Creates a context wrapper from a device selected by the user from a menu. More...
#define	ccl_context_new_from_menu(err)   ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, NULL, (err))
	Creates a context wrapper from a device selected by the user from a menu. More...
#define	ccl_context_new_from_menu_full(data, err)   ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, (data), (err))
	Creates a context wrapper using a device which the user selects from a menu. More...
#define	ccl_context_new_from_menu_full(data, err)   ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, (data), (err))
	Creates a context wrapper using a device which the user selects from a menu. More...
#define	ccl_context_new_gpu(err)
	Creates a context wrapper for a GPU device. More...
#define	ccl_context_new_gpu(err)
	Creates a context wrapper for a GPU device. More...
#define	ccl_context_ref(ctx)   ccl_wrapper_ref((CCLWrapper*) ctx)
	Increase the reference count of the context wrapper object. More...
#define	ccl_context_ref(ctx)   ccl_wrapper_ref((CCLWrapper*) ctx)
	Increase the reference count of the context wrapper object. More...
#define	ccl_context_unref(ctx)   ccl_context_destroy(ctx)
	Alias to ccl_context_destroy(). More...
#define	ccl_context_unref(ctx)   ccl_context_destroy(ctx)
	Alias to ccl_context_destroy(). More...
#define	ccl_context_unwrap(ctx)   ((cl_context) ccl_wrapper_unwrap((CCLWrapper*) ctx))
	Get the OpenCL context object. More...
#define	ccl_context_unwrap(ctx)   ((cl_context) ccl_wrapper_unwrap((CCLWrapper*) ctx))
	Get the OpenCL context object. More...

Typedefs
typedef void(*	ccl_context_callback )(const char *errinfo, const void *private_info, size_t cb, void *user_data)
	A callback function used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. More...
typedef void(*	ccl_context_callback )(const char *errinfo, const void *private_info, size_t cb, void *user_data)
	A callback function used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. More...
typedef struct ccl_context	CCLContext
	Context wrapper class.

Functions
void	ccl_context_destroy (CCLContext *ctx)
	Decrements the reference count of the context wrapper object. More...
CCLDevice *const *	ccl_context_get_all_devices (CCLContext *ctx, CCLErr **err)
	Get all device wrappers in context. More...
CCLDevice *	ccl_context_get_device (CCLContext *ctx, cl_uint index, CCLErr **err)
	Get CCLDevice wrapper at given index. More...
cl_uint	ccl_context_get_num_devices (CCLContext *ctx, CCLErr **err)
	Return number of devices in context. More...
cl_uint	ccl_context_get_opencl_version (CCLContext *ctx, CCLErr **err)
	Get the OpenCL version of the platform associated with this context. More...
CCLPlatform *	ccl_context_get_platform (CCLContext *ctx, CCLErr **err)
	Get the platform associated with the context devices. More...
const cl_image_format *	ccl_context_get_supported_image_formats (CCLContext *ctx, cl_mem_flags flags, cl_mem_object_type image_type, cl_uint *num_image_formats, CCLErr **err)
	Get the list of image formats supported by a given context. More...
CCLContext *	ccl_context_new_from_devices_full (const cl_context_properties *properties, cl_uint num_devices, CCLDevice *const *devices, ccl_context_callback pfn_notify, void *user_data, CCLErr **err)
	Creates a context wrapper given an array of CCLDevice wrappers and the remaining parameters required by the clCreateContext() function. More...
CCLContext *	ccl_context_new_from_filter (CCLDevSelFilterType ftype, void *filter, void *data, CCLErr **err)
	Creates a context wrapper using one device filter specified in the function parameters. More...
CCLContext *	ccl_context_new_from_filters_full (const cl_context_properties *properties, CCLDevSelFilters *filters, ccl_context_callback pfn_notify, void *user_data, CCLErr **err)
	Create a new context wrapper object selecting devices using the given set of filters. More...
CCLContext *	ccl_context_new_wrap (cl_context context)
	Get the context wrapper for the given OpenCL context. More...

Detailed Description

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

Context wrappers can be created using three different approaches:

1. From a list of CCLDevice* device wrappers, using the ccl_context_new_from_devices_full() function or the ccl_context_new_from_devices() macro.
2. From a list of CCLDevSelFilters* device filters, using the ccl_context_new_from_filters_full() function or the ccl_context_new_from_filters() macro. This is a very flexible mechanism, which is explained in detail in the device selection module section.
3. Using one of the several convenience constructors, which contain predefined filters, such as ccl_context_new_gpu(), ccl_context_new_any() or ccl_context_new_from_menu().

Instantiation and destruction of context wrappers follows the cf4ocl new/destroy rule; as such, context wrapper objects must be released with the ccl_context_destroy() function.

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

• ccl_context_get_info_scalar()
• ccl_context_get_info_array()
• ccl_context_get_info()

The CCLContext* class extends the CCLDevContainer* class; as such, it provides methods for handling a list of devices associated with the context:

• ccl_context_get_all_devices()
• ccl_context_get_device()
• ccl_context_get_num_devices()

Example: using all devices in a platform

CCLPlatform* platf;
CCLContext* ctx;
const* CCLDevice* devs;
cl_uint num_devs;

devs = ccl_platform_get_all_devices(platf, NULL);
num_devs = ccl_platform_get_num_devices(platf, NULL);

ctx = ccl_context_new_from_devices(num_devs, devs, NULL);

ccl_context_destroy(ctx);

Example: select device from menu

CCLContext* ctx;

ctx = ccl_context_new_from_menu(NULL);

ccl_context_destroy(ctx);

Macro Definition Documentation

#define ccl_context_get_info	(		ctx,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) ctx, NULL, param_name, 0, \
        CCL_INFO_CONTEXT, CL_FALSE, err)

Get a CCLWrapperInfo context information object.

Parameters

[in]	ctx	The context 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 context information object. This object will be automatically freed when the context wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 355 of file ccl_context_wrapper.h.

#define ccl_context_get_info	(		ctx,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) ctx, NULL, param_name, 0, \
        CCL_INFO_CONTEXT, CL_FALSE, err)

Get a CCLWrapperInfo context information object.

Parameters

[in]	ctx	The context 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 context information object. This object will be automatically freed when the context wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 355 of file ccl_context_wrapper.h.

#define ccl_context_get_info_array	(		ctx,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) ctx, \
        NULL, param_name, sizeof(param_type), \
        CCL_INFO_CONTEXT, CL_FALSE, err)

Macro which returns an array context information value.

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]	ctx	The context 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 context information value. This value will be automatically freed when the context wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 396 of file ccl_context_wrapper.h.

#define ccl_context_get_info_array	(		ctx,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) ctx, \
        NULL, param_name, sizeof(param_type), \
        CCL_INFO_CONTEXT, CL_FALSE, err)

Macro which returns an array context information value.

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]	ctx	The context 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 context information value. This value will be automatically freed when the context wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 396 of file ccl_context_wrapper.h.

#define ccl_context_get_info_scalar	(		ctx,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) ctx, \
        NULL, param_name, sizeof(param_type), \
        CCL_INFO_CONTEXT, CL_FALSE, err))

Macro which returns a scalar context 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]	ctx	The context 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 context information value. This value will be automatically freed when the context wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 375 of file ccl_context_wrapper.h.

#define ccl_context_get_info_scalar	(		ctx,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) ctx, \
        NULL, param_name, sizeof(param_type), \
        CCL_INFO_CONTEXT, CL_FALSE, err))

Macro which returns a scalar context 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]	ctx	The context 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 context information value. This value will be automatically freed when the context wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 375 of file ccl_context_wrapper.h.

#define ccl_context_new_accel

(

err

)

Value:

ccl_context_new_from_indep_filter( \
        ccl_devsel_indep_type_accel, NULL, (err))

Creates a context wrapper for an Accelerator device.

The first found Accelerator device is used. More than one Accelerator might be used if all Accelerators belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 200 of file ccl_context_wrapper.h.

#define ccl_context_new_accel

(

err

)

Value:

ccl_context_new_from_indep_filter( \
        ccl_devsel_indep_type_accel, NULL, (err))

Creates a context wrapper for an Accelerator device.

The first found Accelerator device is used. More than one Accelerator might be used if all Accelerators belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 200 of file ccl_context_wrapper.h.

#define ccl_context_new_any

(

err

)

ccl_context_new_from_indep_filter(NULL, NULL, (err))

Creates a context wrapper for the first found device(s).

The first found device is used. More than one device might be used if all devices belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 214 of file ccl_context_wrapper.h.

#define ccl_context_new_any

(

err

)

ccl_context_new_from_indep_filter(NULL, NULL, (err))

Creates a context wrapper for the first found device(s).

The first found device is used. More than one device might be used if all devices belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 214 of file ccl_context_wrapper.h.

#define ccl_context_new_cpu

(

err

)

Value:

ccl_context_new_from_indep_filter( \
        ccl_devsel_indep_type_cpu, NULL, (err))

Creates a context wrapper for a CPU device.

The first found CPU device is used. More than one CPU might be used if all CPUs belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 172 of file ccl_context_wrapper.h.

#define ccl_context_new_cpu

(

err

)

Value:

ccl_context_new_from_indep_filter( \
        ccl_devsel_indep_type_cpu, NULL, (err))

Creates a context wrapper for a CPU device.

The first found CPU device is used. More than one CPU might be used if all CPUs belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 172 of file ccl_context_wrapper.h.

#define ccl_context_new_from_dep_filter	(		filter,
			data,
			err
	)		ccl_context_new_from_filter(CCL_DEVSEL_DEP, (filter), (data), (err))

Creates a context wrapper using one dependent device filter specified in the function parameters.

The first device accepted by the given filter is used. More than one device may be used if all devices belong to the same platform (and pass the given filter).

Parameters

[in]	filter	A dependent device filter. If NULL, no independent filter is used, and the first found device(s) is selected.
[in]	data	If not NULL, can point to a device index, such that the device is automatically selected.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 251 of file ccl_context_wrapper.h.

#define ccl_context_new_from_dep_filter	(		filter,
			data,
			err
	)		ccl_context_new_from_filter(CCL_DEVSEL_DEP, (filter), (data), (err))

Creates a context wrapper using one dependent device filter specified in the function parameters.

The first device accepted by the given filter is used. More than one device may be used if all devices belong to the same platform (and pass the given filter).

Parameters

[in]	filter	A dependent device filter. If NULL, no independent filter is used, and the first found device(s) is selected.
[in]	data	If not NULL, can point to a device index, such that the device is automatically selected.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 251 of file ccl_context_wrapper.h.

#define ccl_context_new_from_device_index	(		data,
			err
	)		ccl_context_new_from_dep_filter(ccl_devsel_dep_index, (data), (err))

Creates a context wrapper using a device selected by its index.

The device index depends on the ordering of platforms within the system, and of devices within the platforms.

Parameters

[in]	data	Must point to a valid device index of type cl_uint.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 265 of file ccl_context_wrapper.h.

#define ccl_context_new_from_device_index	(		data,
			err
	)		ccl_context_new_from_dep_filter(ccl_devsel_dep_index, (data), (err))

Creates a context wrapper using a device selected by its index.

The device index depends on the ordering of platforms within the system, and of devices within the platforms.

Parameters

[in]	data	Must point to a valid device index of type cl_uint.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 265 of file ccl_context_wrapper.h.

#define ccl_context_new_from_devices	(		num_devices,
			devices,
			err
	)

Value:

ccl_context_new_from_devices_full( \
        NULL, (num_devices), (devices), NULL, NULL, (err))

Creates a context wrapper given an array of CCLDevice wrappers.

This macro simply calls ccl_context_new_from_devices_full() setting properties, callback and user data to NULL.

Parameters

[in]	num_devices	Number of cl_devices_id's in list.
[in]	devices	Array of CCLDevice wrappers.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new context wrapper object.

Definition at line 158 of file ccl_context_wrapper.h.

#define ccl_context_new_from_devices	(		num_devices,
			devices,
			err
	)

Value:

ccl_context_new_from_devices_full( \
        NULL, (num_devices), (devices), NULL, NULL, (err))

Creates a context wrapper given an array of CCLDevice wrappers.

This macro simply calls ccl_context_new_from_devices_full() setting properties, callback and user data to NULL.

Parameters

[in]	num_devices	Number of cl_devices_id's in list.
[in]	devices	Array of CCLDevice wrappers.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new context wrapper object.

Definition at line 158 of file ccl_context_wrapper.h.

#define ccl_context_new_from_filters	(		filters,
			err
	)

Value:

ccl_context_new_from_filters_full( \
        NULL, (filters), NULL, NULL, (err))

Create a new context wrapper object selecting devices using the given set of filters.

Parameters

[in]	filters	Filters for selecting device.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new context wrapper object.

Definition at line 142 of file ccl_context_wrapper.h.

#define ccl_context_new_from_filters	(		filters,
			err
	)

Value:

ccl_context_new_from_filters_full( \
        NULL, (filters), NULL, NULL, (err))

Create a new context wrapper object selecting devices using the given set of filters.

Parameters

[in]	filters	Filters for selecting device.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new context wrapper object.

Examples:

device_filter.c.

Definition at line 142 of file ccl_context_wrapper.h.

#define ccl_context_new_from_indep_filter	(		filter,
			data,
			err
	)		ccl_context_new_from_filter(CCL_DEVSEL_INDEP, (filter), (data), (err))

Creates a context wrapper using one independent device filter specified in the function parameters.

The first device accepted by the given filter is used. More than one device may be used if all devices belong to the same platform (and pass the given filter).

Parameters

[in]	filter	An independent device filter. If NULL, no independent filter is used, and the first found device(s) is selected.
[in]	data	Specific filter data.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 232 of file ccl_context_wrapper.h.

#define ccl_context_new_from_indep_filter	(		filter,
			data,
			err
	)		ccl_context_new_from_filter(CCL_DEVSEL_INDEP, (filter), (data), (err))

Creates a context wrapper using one independent device filter specified in the function parameters.

The first device accepted by the given filter is used. More than one device may be used if all devices belong to the same platform (and pass the given filter).

Parameters

[in]	filter	An independent device filter. If NULL, no independent filter is used, and the first found device(s) is selected.
[in]	data	Specific filter data.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 232 of file ccl_context_wrapper.h.

#define ccl_context_new_from_menu

(

err

)

ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, NULL, (err))

Creates a context wrapper from a device selected by the user from a menu.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 287 of file ccl_context_wrapper.h.

#define ccl_context_new_from_menu

(

err

)

ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, NULL, (err))

Creates a context wrapper from a device selected by the user from a menu.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 287 of file ccl_context_wrapper.h.

#define ccl_context_new_from_menu_full	(		data,
			err
	)		ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, (data), (err))

Creates a context wrapper using a device which the user selects from a menu.

Parameters

[in]	data	If not NULL, can point to a device index, such that the device is automatically selected.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Examples:

ca.c, canon.c, image_fill.c, and image_filter.c.

Definition at line 277 of file ccl_context_wrapper.h.

#define ccl_context_new_from_menu_full	(		data,
			err
	)		ccl_context_new_from_dep_filter(ccl_devsel_dep_menu, (data), (err))

Creates a context wrapper using a device which the user selects from a menu.

Parameters

[in]	data	If not NULL, can point to a device index, such that the device is automatically selected.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 277 of file ccl_context_wrapper.h.

#define ccl_context_new_gpu

(

err

)

Value:

ccl_context_new_from_indep_filter( \
        ccl_devsel_indep_type_gpu, NULL, (err))

Creates a context wrapper for a GPU device.

The first found GPU device is used. More than one GPU might be used if all GPUs belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 186 of file ccl_context_wrapper.h.

#define ccl_context_new_gpu

(

err

)

Value:

ccl_context_new_from_indep_filter( \
        ccl_devsel_indep_type_gpu, NULL, (err))

Creates a context wrapper for a GPU device.

The first found GPU device is used. More than one GPU might be used if all GPUs belong to the same platform.

Parameters

[out]

err

Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 186 of file ccl_context_wrapper.h.

#define ccl_context_ref

(

ctx

)

ccl_wrapper_ref((CCLWrapper*) ctx)

Increase the reference count of the context wrapper object.

Parameters

[in]

ctx

The context wrapper object.

Definition at line 405 of file ccl_context_wrapper.h.

#define ccl_context_ref

(

ctx

)

ccl_wrapper_ref((CCLWrapper*) ctx)

Increase the reference count of the context wrapper object.

Parameters

[in]

ctx

The context wrapper object.

Definition at line 405 of file ccl_context_wrapper.h.

#define ccl_context_unref

(

ctx

)

ccl_context_destroy(ctx)

Alias to ccl_context_destroy().

Parameters

[in]

ctx

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

Definition at line 414 of file ccl_context_wrapper.h.

#define ccl_context_unref

(

ctx

)

ccl_context_destroy(ctx)

Alias to ccl_context_destroy().

Parameters

[in]

ctx

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

Definition at line 414 of file ccl_context_wrapper.h.

#define ccl_context_unwrap

(

ctx

)

((cl_context) ccl_wrapper_unwrap((CCLWrapper*) ctx))

Get the OpenCL context object.

Parameters

[in]

ctx

The context wrapper object.

Returns

The OpenCL context object.

Definition at line 423 of file ccl_context_wrapper.h.

#define ccl_context_unwrap

(

ctx

)

((cl_context) ccl_wrapper_unwrap((CCLWrapper*) ctx))

Get the OpenCL context object.

Parameters

[in]

ctx

The context wrapper object.

Returns

The OpenCL context object.

Definition at line 423 of file ccl_context_wrapper.h.

Typedef Documentation

typedef void(* ccl_context_callback)(const char *errinfo, const void *private_info, size_t cb, void *user_data)

A callback function used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context.

Ignored if NULL.

Parameters

[in]	errinfo	Pointer to an error string.
[out]	private_info	Pointer to binary data returned by OpenCL, used to log additional debugging information.
[out]	cb	Size of private_info data.
[in]	user_data	Passed as the user_data argument when pfn_notify is called. user_data can be NULL.

Definition at line 125 of file ccl_context_wrapper.h.

typedef void(* ccl_context_callback)(const char *errinfo, const void *private_info, size_t cb, void *user_data)

A callback function used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context.

Ignored if NULL.

Parameters

[in]	errinfo	Pointer to an error string.
[out]	private_info	Pointer to binary data returned by OpenCL, used to log additional debugging information.
[out]	cb	Size of private_info data.
[in]	user_data	Passed as the user_data argument when pfn_notify is called. user_data can be NULL.

Definition at line 125 of file ccl_context_wrapper.h.

Function Documentation

void ccl_context_destroy

(

CCLContext *

ctx

)

Decrements the reference count of the context wrapper object.

If it reaches 0, the context wrapper object is destroyed.

Parameters

[in]

ctx

The context wrapper object.

Examples:

ca.c, canon.c, device_filter.c, image_fill.c, and image_filter.c.

Definition at line 478 of file ccl_context_wrapper.c.

CCLDevice *const * ccl_context_get_all_devices	(	CCLContext *	ctx,
		CCLErr **	err
	)

Get all device wrappers in context.

This function returns the internal array containing the context device wrappers. As such, clients should not modify the returned array (e.g. they should not free it directly).

Parameters

[in]	ctx	The context wrapper object.
[in]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

An array containing the CCLDevice wrappers which belong to the given context, or NULL if an error occurs.

Definition at line 719 of file ccl_context_wrapper.c.

CCLDevice * ccl_context_get_device	(	CCLContext *	ctx,
		cl_uint	index,
		CCLErr **	err
	)

Get CCLDevice wrapper at given index.

Parameters

[in]	ctx	The context wrapper object.
[in]	index	Index of device in context.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The CCLDevice wrapper at given index or NULL if an error occurs.

Examples:

ca.c, canon.c, image_fill.c, and image_filter.c.

Definition at line 677 of file ccl_context_wrapper.c.

cl_uint ccl_context_get_num_devices	(	CCLContext *	ctx,
		CCLErr **	err
	)

Return number of devices in context.

Parameters

[in]	ctx	The context wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The number of devices in context or 0 if an error occurs or is otherwise not possible to get any device.

Examples:

device_filter.c.

Definition at line 696 of file ccl_context_wrapper.c.

cl_uint ccl_context_get_opencl_version	(	CCLContext *	ctx,
		CCLErr **	err
	)

Get the OpenCL version of the platform associated with this context.

The version is returned as an integer, in the following format:

• 100 for OpenCL 1.0
• 110 for OpenCL 1.1
• 120 for OpenCL 1.2
• 200 for OpenCL 2.0
• 210 for OpenCL 2.1
• etc.

Parameters

[in]	ctx	The context wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The OpenCL version of the platform associated with this context as an integer. If an error occurs, 0 is returned.

Definition at line 506 of file ccl_context_wrapper.c.

CCLPlatform * ccl_context_get_platform	(	CCLContext *	ctx,
		CCLErr **	err
	)

Get the platform associated with the context devices.

Parameters

[in]	ctx	The context wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The CCLPlatform wrapper associated with the context devices or NULL if an error occurs.

Definition at line 537 of file ccl_context_wrapper.c.

const cl_image_format * ccl_context_get_supported_image_formats	(	CCLContext *	ctx,
		cl_mem_flags	flags,
		cl_mem_object_type	image_type,
		cl_uint *	num_image_formats,
		CCLErr **	err
	)

Get the list of image formats supported by a given context.

This function wraps the clGetSupportedImageFormats() OpenCL function.

Parameters

[in]	ctx	A context wrapper object.
[in]	flags	Allocation and usage information about the image memory object being queried.
[in]	image_type	The image type. Acceptable values depend on the OpenCL version.
[out]	num_image_formats	Return location for number of image formats in list, which will be zero if an error occurs.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A list of supported image formats, or NULL if an error occurs. Doesn't need to be freed.

Definition at line 597 of file ccl_context_wrapper.c.

CCLContext * ccl_context_new_from_devices_full	(	const cl_context_properties *	properties,
		cl_uint	num_devices,
		CCLDevice *const *	devices,
		ccl_context_callback	pfn_notify,
		void *	user_data,
		CCLErr **	err
	)

Creates a context wrapper given an array of CCLDevice wrappers and the remaining parameters required by the clCreateContext() function.

If the properties parameter is NULL, this function obtains the cl_platform_id object from the first device.

Parameters

[in]	properties	Context properties, may be NULL.
[in]	num_devices	Number of CCLDevice wrappers in array.
[in]	devices	Array of CCLDevice wrappers.
[in]	pfn_notify	A callback function used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. Ignored if NULL.
[in]	user_data	Passed as argument to pfn_notify, can be NULL.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new context wrapper object.

Definition at line 319 of file ccl_context_wrapper.c.

CCLContext * ccl_context_new_from_filter	(	CCLDevSelFilterType	ftype,
		void *	filter,
		void *	data,
		CCLErr **	err
	)

Creates a context wrapper using one device filter specified in the function parameters.

The first device accepted by the given filter is used. More than one device may be used if all devices belong to the same platform (and pass the given filter).

Parameters

[in]	ftype	Filter type, either CCL_DEVSEL_DEP or CCL_DEVSEL_INDEP.
[in]	filter	Filter used to select device(s). If NULL, no filter is used, and the first found device(s) is selected.
[in]	data	Specific filter data.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 411 of file ccl_context_wrapper.c.

CCLContext * ccl_context_new_from_filters_full	(	const cl_context_properties *	properties,
		CCLDevSelFilters *	filters,
		ccl_context_callback	pfn_notify,
		void *	user_data,
		CCLErr **	err
	)

Create a new context wrapper object selecting devices using the given set of filters.

This function accepts all the parameters required for the clCreateContext() OpenCL function. For simple context creation use the ccl_context_new_from_filters() macro instead.

The client should provide the necessary filters such that the filtered devices belong to the same platform. Adding the ccl_devsel_dep_platform() filter last to the filters set will ensure this.

Parameters

[in]	properties	A set of OpenCL context properties.
[in]	filters	Filters for selecting device.
[in]	pfn_notify	A callback function used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. Ignored if NULL.
[in]	user_data	Passed as argument to pfn_notify, can be NULL.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A new context wrapper object.

Definition at line 246 of file ccl_context_wrapper.c.

CCLContext * ccl_context_new_wrap

(

cl_context

context

)

Get the context wrapper for the given OpenCL context.

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 create the OpenCL context directly (using the clCreateContext() function) and then wrap the OpenCL context in a CCLContext wrapper object.

Parameters

[in]

context

The OpenCL context to be wrapped.

Returns

The context wrapper for the given OpenCL context.

Definition at line 212 of file ccl_context_wrapper.c.