Image wrapper

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

Data Structures
struct	ccl_image_desc
	Describes the type and dimensions of the image or image array independently of the OpenCL version. More...

Macros
#define	CCL_IMAGE_DESC_BLANK   {0, 0, 0, 0, 0, 0, 0, 0, 0, NULL}
	This macro can be used to set a CCLImageDesc object to all zeros. More...
#define	CCL_IMAGE_DESC_BLANK   {0, 0, 0, 0, 0, 0, 0, 0, 0, NULL}
	This macro can be used to set a CCLImageDesc object to all zeros. More...
#define	ccl_image_enqueue_unmap(img, cq, ptr, ewl, err)   ccl_memobj_enqueue_unmap((CCLMemObj*) img, cq, ptr, ewl, err)
	Enqueues a command to unmap a previously mapped image object. More...
#define	ccl_image_enqueue_unmap(img, cq, ptr, ewl, err)   ccl_memobj_enqueue_unmap((CCLMemObj*) img, cq, ptr, ewl, err)
	Enqueues a command to unmap a previously mapped image object. More...
#define	ccl_image_get_info(img, param_name, err)
	Get a CCLWrapperInfo image information object. More...
#define	ccl_image_get_info(img, param_name, err)
	Get a CCLWrapperInfo image information object. More...
#define	ccl_image_get_info_array(img, param_name, param_type, err)
	Macro which returns an array image information value. More...
#define	ccl_image_get_info_array(img, param_name, param_type, err)
	Macro which returns an array image information value. More...
#define	ccl_image_get_info_scalar(img, param_name, param_type, err)
	Macro which returns a scalar image information value. More...
#define	ccl_image_get_info_scalar(img, param_name, param_type, err)
	Macro which returns a scalar image information value. More...
#define	ccl_image_ref(img)   ccl_wrapper_ref((CCLWrapper*) img)
	Increase the reference count of the image wrapper object. More...
#define	ccl_image_ref(img)   ccl_wrapper_ref((CCLWrapper*) img)
	Increase the reference count of the image wrapper object. More...
#define	ccl_image_unref(img)   ccl_image_destroy(img)
	Alias to ccl_image_destroy(). More...
#define	ccl_image_unref(img)   ccl_image_destroy(img)
	Alias to ccl_image_destroy(). More...
#define	ccl_image_unwrap(img)   ((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) img))
	Get the OpenCL image memory object. More...
#define	ccl_image_unwrap(img)   ((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) img))
	Get the OpenCL image memory object. More...

Typedefs
typedef struct ccl_image	CCLImage
	Image wrapper class.
typedef struct ccl_image_desc	CCLImageDesc
	Describes the type and dimensions of the image or image array independently of the OpenCL version. More...
typedef struct ccl_image_desc	CCLImageDesc
	Describes the type and dimensions of the image or image array independently of the OpenCL version. More...

Functions
void	ccl_image_destroy (CCLImage *img)
	Decrements the reference count of the wrapper object. More...
CCLEvent *	ccl_image_enqueue_copy (CCLImage *src_img, CCLImage *dst_img, CCLQueue *cq, const size_t *src_origin, const size_t *dst_origin, const size_t *region, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Copy image objects. More...
CCLEvent *	ccl_image_enqueue_copy_to_buffer (CCLImage *src_img, CCLBuffer *dst_buf, CCLQueue *cq, const size_t *src_origin, const size_t *region, size_t dst_offset, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Copy an image object to a buffer object. More...
CCLEvent *	ccl_image_enqueue_fill (CCLImage *img, CCLQueue *cq, const void *fill_color, const size_t *origin, const size_t *region, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Fill an image object with a specified color. More...
void *	ccl_image_enqueue_map (CCLImage *img, CCLQueue *cq, cl_bool blocking_map, cl_map_flags map_flags, const size_t *origin, const size_t *region, size_t *image_row_pitch, size_t *image_slice_pitch, CCLEventWaitList *evt_wait_lst, CCLEvent **evt, CCLErr **err)
	Map a region of the image into the host address space and return a pointer to this mapped region. More...
CCLEvent *	ccl_image_enqueue_read (CCLImage *img, CCLQueue *cq, cl_bool blocking_read, const size_t *origin, const size_t *region, size_t row_pitch, size_t slice_pitch, void *ptr, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Read from an image or image array object to host memory. More...
CCLEvent *	ccl_image_enqueue_write (CCLImage *img, CCLQueue *cq, cl_bool blocking_write, const size_t *origin, const size_t *region, size_t input_row_pitch, size_t input_slice_pitch, void *ptr, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Write to an image or image array object from host memory. More...
CCLImage *	ccl_image_new (CCLContext *ctx, cl_mem_flags flags, const cl_image_format *image_format, void *host_ptr, CCLErr **err,...)
	Creates a new image wrapper object using a variable list of key-value pairs which describe the image. More...
CCLImage *	ccl_image_new_v (CCLContext *ctx, cl_mem_flags flags, const cl_image_format *image_format, const CCLImageDesc *img_dsc, void *host_ptr, CCLErr **err)
	Creates a new image wrapper object. More...
CCLImage *	ccl_image_new_wrap (cl_mem mem_object)
	Get the image wrapper for the given OpenCL image. More...

Detailed Description

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

All the functions in this module are direct wrappers of the respective OpenCL image functions. The ccl_image_new() constructor accepts a variable list of arguments which describe the image to be created. There is also the ccl_image_new_v() constructor, which accepts the image description arguments given in a CCLImageDesc* object. Both constructors will automatically use the old style clCreateImage2D()/clCreateImage3D() OpenCL functions if the OpenCL version of the underlying platform is less or equal than 1.1, or the new clCreateImage() constructor otherwise. Instantiation and destruction of image wrappers follows the cf4ocl new/destroy rule; as such, images should be freed with the ccl_image_destroy() destructor.

Image wrapper objects can be directly passed as kernel arguments to functions such as ccl_program_enqueue_kernel() or ccl_kernel_set_arg().

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

• ccl_image_get_info_scalar()
• ccl_image_get_info_array()
• ccl_image_get_info()

If the information to be fetched is relative to the memory object parent class (e.g. CL_MEM_TYPE or CL_MEM_FLAGS), then the memory object module info macros should be used instead:

• ccl_memobj_get_info_scalar()
• ccl_memobj_get_info_array()
• ccl_memobj_get_info()

Example:

CCLQueue* queue;
CCLImage* img_in;
CCLImage* img_out;
cl_uchar4 host_img[IMG_X * IMG_Y];
cl_image_format image_format = { CL_RGBA, CL_UNSIGNED_INT8 };
size_t origin[3] = { 0, 0, 0 };
size_t region[3] = { IMG_X, IMG_Y, 1 };

img_in = ccl_image_new(ctx, CL_MEM_READ_ONLY, &image_format, NULL, &err,
    "image_type", (cl_mem_object_type) CL_MEM_OBJECT_IMAGE2D,
    "image_width", (size_t) IMG_X,
    "image_height", (size_t) IMG_Y,
    NULL);
img_out = ccl_image_new(ctx, CL_MEM_WRITE_ONLY, &image_format, NULL, &err,
    "image_type", (cl_mem_object_type) CL_MEM_OBJECT_IMAGE2D,
    "image_width", (size_t) IMG_X,
    "image_height", (size_t) IMG_Y,
    NULL);

ccl_image_enqueue_write(queue, img_in, CL_TRUE, origin, region,
    0, 0, host_img, NULL, NULL);

enqueue some image processing kernel...

ccl_image_enqueue_read(queue, img_out, CL_TRUE, origin, region,
    0, 0, host_img, NULL, NULL);

ccl_image_destroy(img_in);
ccl_image_destroy(img_out);

---

Data Structure Documentation

struct ccl_image_desc

Describes the type and dimensions of the image or image array independently of the OpenCL version.

Should be initialized with the CCL_IMAGE_DESC_BLANK macro.

Definition at line 127 of file ccl_image_wrapper.h.

Collaboration diagram for ccl_image_desc:

Data Fields
size_t	image_array_size	Number of images in the image array. Used for 1D and 2D image arrays.
size_t	image_depth	Depth of the image in pixels. Used only for 3D images.
size_t	image_height	Height of the image in pixels. Used for 2D and 3D images and 2D image arrays.
size_t	image_row_pitch	Scan-line pitch in bytes. Must be 0 if host_ptr is NULL.
size_t	image_slice_pitch	Size in bytes of each 2D slice in the 3D image or the size in bytes of each image in a 1D or 2D image array. Must be 0 if host_ptr is NULL.
cl_mem_object_type	image_type	The type of image, must be supported by the underlying OpenCL version. Only CL_MEM_OBJECT_IMAGE2D and CL_MEM_OBJECT_IMAGE3D are supported in all OpenCL versions.
size_t	image_width	Width of the image in pixels. Used for all image types.
CCLMemObj *	memobj	A memory object wrapper. In OpenCL 1.2, it refers to a buffer wrapper and is used for 1D image buffers. In OpenCL 2.0 it can also be used with 2D images to create a new 2D image from data shared with the specified memory object (either a buffer or a 2D image).
cl_uint	num_mip_levels	Unused up to OpenCL 2.0.
cl_uint	num_samples	Unused up to OpenCL 2.0.

Macro Definition Documentation

#define CCL_IMAGE_DESC_BLANK   {0, 0, 0, 0, 0, 0, 0, 0, 0, NULL}

This macro can be used to set a CCLImageDesc object to all zeros.

For example:

CCLImageDesc image_desc = CCL_IMAGE_DESC_BLANK;

Definition at line 120 of file ccl_image_wrapper.h.

#define CCL_IMAGE_DESC_BLANK   {0, 0, 0, 0, 0, 0, 0, 0, 0, NULL}

This macro can be used to set a CCLImageDesc object to all zeros.

For example:

CCLImageDesc image_desc = CCL_IMAGE_DESC_BLANK;

Definition at line 120 of file ccl_image_wrapper.h.

#define ccl_image_enqueue_unmap	(		img,
			cq,
			ptr,
			ewl,
			err
	)		ccl_memobj_enqueue_unmap((CCLMemObj*) img, cq, ptr, ewl, err)

Enqueues a command to unmap a previously mapped image object.

This is a utility macro that expands to ccl_memobj_enqueue_unmap(), casting img into a CCLMemObj object.

Parameters

[in]	img	An image wrapper object.
[in]	cq	A command queue wrapper object.
[in]	ptr	The host address returned by a previous call to ccl_image_enqueue_map().
[in,out]	ewl	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this command.

Definition at line 283 of file ccl_image_wrapper.h.

#define ccl_image_enqueue_unmap	(		img,
			cq,
			ptr,
			ewl,
			err
	)		ccl_memobj_enqueue_unmap((CCLMemObj*) img, cq, ptr, ewl, err)

Enqueues a command to unmap a previously mapped image object.

This is a utility macro that expands to ccl_memobj_enqueue_unmap(), casting img into a CCLMemObj object.

Parameters

[in]	img	An image wrapper object.
[in]	cq	A command queue wrapper object.
[in]	ptr	The host address returned by a previous call to ccl_image_enqueue_map().
[in,out]	ewl	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this command.

Definition at line 283 of file ccl_image_wrapper.h.

#define ccl_image_get_info	(		img,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) img, NULL, param_name, 0, \
        CCL_INFO_IMAGE, CL_FALSE, err)

Get a CCLWrapperInfo image information object.

Parameters

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

Definition at line 297 of file ccl_image_wrapper.h.

#define ccl_image_get_info	(		img,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) img, NULL, param_name, 0, \
        CCL_INFO_IMAGE, CL_FALSE, err)

Get a CCLWrapperInfo image information object.

Parameters

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

Definition at line 297 of file ccl_image_wrapper.h.

#define ccl_image_get_info_array	(		img,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) img, \
        NULL, param_name, sizeof(param_type), CCL_INFO_IMAGE, CL_FALSE, err)

Macro which returns an array image 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]	img	The image 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 image information value. This value will be automatically freed when the image wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 337 of file ccl_image_wrapper.h.

#define ccl_image_get_info_array	(		img,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) img, \
        NULL, param_name, sizeof(param_type), CCL_INFO_IMAGE, CL_FALSE, err)

Macro which returns an array image 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]	img	The image 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 image information value. This value will be automatically freed when the image wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 337 of file ccl_image_wrapper.h.

#define ccl_image_get_info_scalar	(		img,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) img, \
        NULL, param_name, sizeof(param_type), CCL_INFO_IMAGE, CL_FALSE, err))

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

Definition at line 317 of file ccl_image_wrapper.h.

#define ccl_image_get_info_scalar	(		img,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) img, \
        NULL, param_name, sizeof(param_type), CCL_INFO_IMAGE, CL_FALSE, err))

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

Definition at line 317 of file ccl_image_wrapper.h.

#define ccl_image_ref

(

img

)

ccl_wrapper_ref((CCLWrapper*) img)

Increase the reference count of the image wrapper object.

Parameters

[in]

img

The image wrapper object.

Definition at line 346 of file ccl_image_wrapper.h.

#define ccl_image_ref

(

img

)

ccl_wrapper_ref((CCLWrapper*) img)

Increase the reference count of the image wrapper object.

Parameters

[in]

img

The image wrapper object.

Definition at line 346 of file ccl_image_wrapper.h.

#define ccl_image_unref

(

img

)

ccl_image_destroy(img)

Alias to ccl_image_destroy().

Parameters

[in]

img

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

Definition at line 355 of file ccl_image_wrapper.h.

#define ccl_image_unref

(

img

)

ccl_image_destroy(img)

Alias to ccl_image_destroy().

Parameters

[in]

img

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

Definition at line 355 of file ccl_image_wrapper.h.

#define ccl_image_unwrap

(

img

)

((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) img))

Get the OpenCL image memory object.

Parameters

[in]

img

The image wrapper object.

Returns

The OpenCL image memory object.

Definition at line 363 of file ccl_image_wrapper.h.

#define ccl_image_unwrap

(

img

)

((cl_mem) ccl_wrapper_unwrap((CCLWrapper*) img))

Get the OpenCL image memory object.

Parameters

[in]

img

The image wrapper object.

Returns

The OpenCL image memory object.

Definition at line 363 of file ccl_image_wrapper.h.

Typedef Documentation

typedef struct ccl_image_desc CCLImageDesc

Describes the type and dimensions of the image or image array independently of the OpenCL version.

Should be initialized with the CCL_IMAGE_DESC_BLANK macro.

typedef struct ccl_image_desc CCLImageDesc

Describes the type and dimensions of the image or image array independently of the OpenCL version.

Should be initialized with the CCL_IMAGE_DESC_BLANK macro.

Function Documentation

void ccl_image_destroy

(

CCLImage *

img

)

Decrements the reference count of the wrapper object.

If it reaches 0, the wrapper object is destroyed.

Parameters

[in]

img

The image wrapper object.

Examples:

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

Definition at line 177 of file ccl_image_wrapper.c.

CCLEvent * ccl_image_enqueue_copy	(	CCLImage *	src_img,
		CCLImage *	dst_img,
		CCLQueue *	cq,
		const size_t *	src_origin,
		const size_t *	dst_origin,
		const size_t *	region,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Copy image objects.

This function wraps the clEnqueueCopyImage() OpenCL function.

Parameters

[in]	src_img	Source image wrapper object.
[out]	dst_img	Destination image wrapper object.
[in]	cq	Command-queue wrapper object in which the copy command will be queued.
[in]	src_origin	The offset in pixels in the 1D, 2D, or 3D image source image, the offset and the image index in the source image array or the offset and the image index in the source 1D image array.
[in]	dst_origin	The offset in pixels in the 1D, 2D, or 3D destination image, the offset and the image index in the destination image array or the offset and the image index in the 1D destination image array.
[in]	region	The in pixels of the 1D, 2D or 3D rectangle, the in pixels of the 2D rectangle and the number of images of a 2D image array or the in pixels of the 1D rectangle and the number of images of a 1D image array.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this copy command.

Definition at line 662 of file ccl_image_wrapper.c.

CCLEvent * ccl_image_enqueue_copy_to_buffer	(	CCLImage *	src_img,
		CCLBuffer *	dst_buf,
		CCLQueue *	cq,
		const size_t *	src_origin,
		const size_t *	region,
		size_t	dst_offset,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Copy an image object to a buffer object.

This function wraps the clEnqueueCopyImageToBuffer() OpenCL function.

Parameters

[in]	src_img	Source image wrapper object where to read from.
[out]	dst_buf	Destination buffer wrapper object where to write to.
[in]	cq	Command-queue wrapper object in which the copy command will be queued.
[in]	src_origin	The offset in pixels in the 1D, 2D or 3D image, the offset and the image index in the 2D image array or the offset and the image index in the 1D image array.
[in]	region	The in pixels of the 1D, 2D or 3D rectangle, the in pixels of the 2D rectangle and the number of images of a 2D image array or the in pixels of the 1D rectangle and the number of images of a 1D image array.
[in]	dst_offset	The offset where to begin copying data into dst_buf.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this copy command.

Definition at line 750 of file ccl_image_wrapper.c.

CCLEvent * ccl_image_enqueue_fill	(	CCLImage *	img,
		CCLQueue *	cq,
		const void *	fill_color,
		const size_t *	origin,
		const size_t *	region,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Fill an image object with a specified color.

This function wraps the clEnqueueFillImage() OpenCL function.

Note

Requires OpenCL >= 1.2

Parameters

[out]	img	Image wrapper object to fill.
[in]	cq	Command-queue wrapper object in which the fill command will be queued.
[in]	fill_color	The fill color.
[in]	origin	The offset in pixels in the 1D, 2D, or 3D image, the offset and the image index in the image array or the offset and the image index in the 1D image array.
[in]	region	The in pixels of the 1D, 2D or 3D rectangle, the in pixels of the 2D rectangle and the number of images of a 2D image array or the in pixels of the 1D rectangle and the number of images of a 1D image array.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this fill command.

Examples:

image_fill.c.

Definition at line 934 of file ccl_image_wrapper.c.

void * ccl_image_enqueue_map	(	CCLImage *	img,
		CCLQueue *	cq,
		cl_bool	blocking_map,
		cl_map_flags	map_flags,
		const size_t *	origin,
		const size_t *	region,
		size_t *	image_row_pitch,
		size_t *	image_slice_pitch,
		CCLEventWaitList *	evt_wait_lst,
		CCLEvent **	evt,
		CCLErr **	err
	)

Map a region of the image into the host address space and return a pointer to this mapped region.

This function wraps the clEnqueueMapImage() OpenCL function.

Parameters

[in,out]	img	Image wrapper object to be mapped.
[in]	cq	Command-queue wrapper object in which the map command will be queued.
[in]	blocking_map	Indicates if the map operation is blocking or non-blocking.
[in]	map_flags	Flags which specify the type of mapping to perform.
[in]	origin	The offset in pixels in the 1D, 2D, or 3D image, the offset and the image index in the image array or the offset and the image index in the 1D image array.
[in]	region	The in pixels of the 1D, 2D or 3D rectangle, the in pixels of the 2D rectangle and the number of images of a 2D image array or the in pixels of the 1D rectangle and the number of images of a 1D image array.
[out]	image_row_pitch	Returns the scan-line pitch in bytes for the mapped region. This must be a non-NULL value.
[out]	image_slice_pitch	Returns the size in bytes of each 2D slice of a 3D image or the size of each 1D or 2D image in a 1D or 2D image array for the mapped region. For a 1D and 2D image, zero is returned if this argument is not NULL. For a 3D image, 1D, and 2D image array, image_slice_pitch must be a non-NULL value.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	evt	An event wrapper object that identifies this particular map command. If NULL, no event will be returned.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

A pointer in the host address space for the mapped region.

Definition at line 848 of file ccl_image_wrapper.c.

CCLEvent * ccl_image_enqueue_read	(	CCLImage *	img,
		CCLQueue *	cq,
		cl_bool	blocking_read,
		const size_t *	origin,
		const size_t *	region,
		size_t	row_pitch,
		size_t	slice_pitch,
		void *	ptr,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Read from an image or image array object to host memory.

This function wraps the clEnqueueReadImage() OpenCL function.

Parameters

[in]	img	Image wrapper object where to read from.
[in]	cq	Command-queue wrapper object in which the read command will be queued.
[in]	blocking_read	Indicates if the read operation is blocking or non-blocking.
[in]	origin	The offset in pixels in the 1D, 2D, or 3D image, the offset and the image index in the image array or the offset and the image index in the 1D image array.
[in]	region	The in pixels of the 1D, 2D or 3D rectangle, the in pixels of the 2D rectangle and the number of images of a 2D image array or the in pixels of the 1D rectangle and the number of images of a 1D image array.
[in]	row_pitch	The length of each row in bytes.
[in]	slice_pitch	Size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being read.
[out]	ptr	A pointer to a buffer in host memory where data is to be read into.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this read command.

Examples:

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

Definition at line 485 of file ccl_image_wrapper.c.

CCLEvent * ccl_image_enqueue_write	(	CCLImage *	img,
		CCLQueue *	cq,
		cl_bool	blocking_write,
		const size_t *	origin,
		const size_t *	region,
		size_t	input_row_pitch,
		size_t	input_slice_pitch,
		void *	ptr,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Write to an image or image array object from host memory.

This function wraps the clEnqueueWriteImage() OpenCL function.

Parameters

[out]	img	Image wrapper object where to write to.
[in]	cq	Command-queue wrapper object in which the write command will be queued.
[in]	blocking_write	Indicates if the write operation is blocking or non-blocking.
[in]	origin	The offset in pixels in the 1D, 2D, or 3D image, the offset and the image index in the image array or the offset and the image index in the 1D image array.
[in]	region	The in pixels of the 1D, 2D or 3D rectangle, the in pixels of the 2D rectangle and the number of images of a 2D image array or the in pixels of the 1D rectangle and the number of images of a 1D image array.
[in]	input_row_pitch	The length of each row in bytes.
[in]	input_slice_pitch	Size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being written.
[in]	ptr	A pointer to a buffer in host memory where data is to be written from.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

Event wrapper object that identifies this write command.

Examples:

ca.c.

Definition at line 575 of file ccl_image_wrapper.c.

CCLImage * ccl_image_new	(	CCLContext *	ctx,
		cl_mem_flags	flags,
		const cl_image_format *	image_format,
		void *	host_ptr,
		CCLErr **	err,
			...
	)

Creates a new image wrapper object using a variable list of key-value pairs which describe the image.

The keys are assumed to be of type const char*, while the type of each corresponding value depends on the key, as defined in the table below (see the ccl_image_desc struct for a detailed description of each key or parameter). The list must end with NULL.

Keys and corresponding types

Key	Value type
"image_type"	cl_mem_object_type
"image_width"	size_t
"image_height"	size_t
"image_depth"	size_t
"image_array_size"	size_t
"image_row_pitch"	size_t
"image_slice_pitch"	size_t
"num_mip_levels"	cl_uint
"num_samples"	cl_uint
"memobj"	CCLMemObj*

Usage example

...
CCLImage* img;
...
img = ccl_image_new(ctx, flags, image_format, NULL, NULL,
    "image_type", (cl_mem_object_type) CL_MEM_OBJECT_IMAGE2D
    "image_width", (size_t) 1024,
    "image_height", (size_t) 512,
    NULL);

Attention

Make sure the values passed in the variable argument list are of the expected type (as defined by the corresponding key). This requires the use of casts when passing values directly (as in the example above).

The variable argument list must end with NULL.

The underlying OpenCL image object is created using the clCreateImage2D() and clCreateImage3D() if the platform's OpenCL version is 1.1 or lower, or the clCreateImage() function otherwise.

Parameters

[in]	ctx	A context wrapper object on which the image wrapper object is to be created.
[in]	flags	Specifies allocation and usage information about the image wrapper object being created.
[in]	image_format	A pointer to the OpenCL cl_image_format structure, which describes format properties of the image to be allocated.
[in]	host_ptr	A pointer to the image data that may already be allocated by the application.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.
[in]	...	A NULL-terminated list of key-value pairs which describe the type and dimensions of the image to be allocated.

Returns

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

Examples:

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

Definition at line 391 of file ccl_image_wrapper.c.

CCLImage * ccl_image_new_v	(	CCLContext *	ctx,
		cl_mem_flags	flags,
		const cl_image_format *	image_format,
		const CCLImageDesc *	img_dsc,
		void *	host_ptr,
		CCLErr **	err
	)

Creates a new image wrapper object.

The type and dimensions of the image are defined in the img_dsc parameter.

Usage example

...
CCLImage* img;
...
CCLImageDesc image_desc = CCL_IMAGE_DESC_BLANK;
image_desc.image_width = 1024;
image_desc.image_height = 512;
image_desc.image_type = CL_MEM_OBJECT_IMAGE2D;
...
img = ccl_image_new_v(
    ctx, flags, image_format, img_dsc, NULL, NULL);

The underlying OpenCL image object is created using the clCreateImage2D() and clCreateImage3D() if the platform's OpenCL version is 1.1 or lower, or the clCreateImage() function otherwise.

Parameters

[in]	ctx	A context wrapper object on which the image wrapper object is to be created.
[in]	flags	Specifies allocation and usage information about the image wrapper object being created.
[in]	image_format	A pointer to the OpenCL cl_image_format structure, which describes format properties of the image to be allocated.
[in]	img_dsc	A pointer to a CCLImageDesc object which describes type and dimensions of the image to be allocated.
[in]	host_ptr	A pointer to the image data that may already be allocated by the application.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

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

Definition at line 226 of file ccl_image_wrapper.c.

CCLImage * ccl_image_new_wrap ( cl_mem  mem_object )

protected

Get the image wrapper for the given OpenCL image.

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 image in a CCLImage wrapper object.

Parameters

[in]

mem_object

The OpenCL image to be wrapped.

Returns

The CCLImage wrapper for the given OpenCL image.

Definition at line 161 of file ccl_image_wrapper.c.