OpenCL specific functions

Accessing ArrayFire's context, queue, and share data with other OpenCL code. More...

Typedefs
typedef afcl_device_type	deviceType
typedef afcl_platform	platform

Functions
static cl_context	getContext (bool retain=false)
	Get a handle to ArrayFire's OpenCL context. More...
static cl_command_queue	getQueue (bool retain=false)
	Get a handle to ArrayFire's OpenCL command queue. More...
static cl_device_id	getDeviceId ()
	Get the device ID for ArrayFire's current active device. More...
static void	setDeviceId (cl_device_id id)
	Set ArrayFire's active device based on id of type cl_device_id. More...
static void	addDevice (cl_device_id dev, cl_context ctx, cl_command_queue que)
	Push user provided device control constructs into the ArrayFire device manager pool. More...
static void	setDevice (cl_device_id dev, cl_context ctx)
	Set active device using cl_context and cl_device_id. More...
static void	deleteDevice (cl_device_id dev, cl_context ctx)
	Remove the user provided device control constructs from the ArrayFire device manager pool. More...
static deviceType	getDeviceType ()
	Get the type of the current device. More...
static platform	getPlatform ()
	Get a vendor enumeration for the current platform. More...
static af::array	array (af::dim4 idims, cl_mem buf, af::dtype type, bool retain=false)
	Create an af::array object from an OpenCL cl_mem buffer. More...
static af::array	array (dim_t dim0, cl_mem buf, af::dtype type, bool retain=false)
	Create an af::array object from an OpenCL cl_mem buffer. More...
static af::array	array (dim_t dim0, dim_t dim1, cl_mem buf, af::dtype type, bool retain=false)
	Create an af::array object from an OpenCL cl_mem buffer. More...
static af::array	array (dim_t dim0, dim_t dim1, dim_t dim2, cl_mem buf, af::dtype type, bool retain=false)
	Create an af::array object from an OpenCL cl_mem buffer. More...
static af::array	array (dim_t dim0, dim_t dim1, dim_t dim2, dim_t dim3, cl_mem buf, af::dtype type, bool retain=false)
	Create an af::array object from an OpenCL cl_mem buffer. More...
AFAPI af_err	afcl_get_context (cl_context *ctx, const bool retain)
	Get a handle to ArrayFire's OpenCL context. More...
AFAPI af_err	afcl_get_queue (cl_command_queue *queue, const bool retain)
	Get a handle to ArrayFire's OpenCL command queue. More...
AFAPI af_err	afcl_get_device_id (cl_device_id *id)
	Get the device ID for ArrayFire's current active device. More...
AFAPI af_err	afcl_set_device_id (cl_device_id id)
	Set ArrayFire's active device based on id of type cl_device_id. More...
AFAPI af_err	afcl_add_device_context (cl_device_id dev, cl_context ctx, cl_command_queue que)
	Push user provided device control constructs into the ArrayFire device manager pool. More...
AFAPI af_err	afcl_set_device_context (cl_device_id dev, cl_context ctx)
	Set active device using cl_context and cl_device_id. More...
AFAPI af_err	afcl_delete_device_context (cl_device_id dev, cl_context ctx)
	Remove the user provided device control constructs from the ArrayFire device manager pool. More...
AFAPI af_err	afcl_get_device_type (afcl_device_type *res)
	Get the type of the current device. More...
AFAPI af_err	afcl_get_platform (afcl_platform *res)
	Get the platform of the current device. More...

Detailed Description

Accessing ArrayFire's context, queue, and share data with other OpenCL code.

If your software is using ArrayFire's OpenCL backend, you can also write custom kernels and do custom memory operations using native OpenCL commands. The functions contained in the afcl namespace provide methods to get the context, queue, and device(s) that ArrayFire is using as well as convert cl_mem handles to af::array objects.

Please note: the af::array constructors are not thread safe. You may create and upload data to cl_mem objects from separate threads, but the thread which instantiated ArrayFire must do the cl_mem to af::array conversion.

Typedef Documentation

deviceType

typedef afcl_device_type deviceType

Definition at line 289 of file opencl.h.

platform

typedef afcl_platform platform

Definition at line 290 of file opencl.h.

Function Documentation

addDevice()

static void addDevice ( cl_device_id  dev, cl_context  ctx, cl_command_queue  que  )

inlinestatic

Push user provided device control constructs into the ArrayFire device manager pool.

This function should be used only when the user would like ArrayFire to use an user generated OpenCL context and related objects for ArrayFire operations.

Parameters

[in]	dev	is the OpenCL device for which user provided context will be used by ArrayFire
[in]	ctx	is the user provided OpenCL cl_context to be used by ArrayFire
[in]	que	is the user provided OpenCL cl_command_queue to be used by ArrayFire. If this parameter is NULL, then we create a command queue for the user using the OpenCL context they provided us.

Note

ArrayFire does not take control of releasing the objects passed to it. The user needs to release them appropriately.

Definition at line 247 of file opencl.h.

{
    af_err err = afcl_add_device_context(dev, ctx, que);
    if (err!=AF_SUCCESS) throw af::exception("Failed to push user provided device/context to ArrayFire pool");
}

afcl_add_device_context()

AFAPI af_err afcl_add_device_context	(	cl_device_id	dev,
		cl_context	ctx,
		cl_command_queue	que
	)

Push user provided device control constructs into the ArrayFire device manager pool.

This function should be used only when the user would like ArrayFire to use an user generated OpenCL context and related objects for ArrayFire operations.

Parameters

[in]	dev	is the OpenCL device for which user provided context will be used by ArrayFire
[in]	ctx	is the user provided OpenCL cl_context to be used by ArrayFire
[in]	que	is the user provided OpenCL cl_command_queue to be used by ArrayFire. If this parameter is NULL, then we create a command queue for the user using the OpenCL context they provided us.

Note

ArrayFire does not take control of releasing the objects passed to it. The user needs to release them appropriately.

afcl_delete_device_context()

AFAPI af_err afcl_delete_device_context	(	cl_device_id	dev,
		cl_context	ctx
	)

Remove the user provided device control constructs from the ArrayFire device manager pool.

This function should be used only when the user would like ArrayFire to remove an already pushed user generated OpenCL context and related objects.

Parameters

[in]	dev	is the OpenCL device id that has to be popped
[in]	ctx	is the cl_context object to be removed from ArrayFire pool

Note

ArrayFire does not take control of releasing the objects passed to it. The user needs to release them appropriately.

afcl_get_context()

AFAPI af_err afcl_get_context	(	cl_context *	ctx,
		const bool	retain
	)

Get a handle to ArrayFire's OpenCL context.

Parameters

[out]	ctx	the current context being used by ArrayFire
[in]	retain	if true calls clRetainContext prior to returning the context

Returns

af_err error code

Note

Set retain to true if this value will be passed to a cl::Context constructor

afcl_get_device_id()

AFAPI af_err afcl_get_device_id

(

cl_device_id *

id

)

Get the device ID for ArrayFire's current active device.

Parameters

[out]

id

the cl_device_id of the current device

Returns

af_err error code

afcl_get_device_type()

AFAPI af_err afcl_get_device_type

(

afcl_device_type *

res

)

Get the type of the current device.

afcl_get_platform()

AFAPI af_err afcl_get_platform

(

afcl_platform *

res

)

Get the platform of the current device.

afcl_get_queue()

AFAPI af_err afcl_get_queue	(	cl_command_queue *	queue,
		const bool	retain
	)

Get a handle to ArrayFire's OpenCL command queue.

Parameters

[out]	queue	the current command queue being used by ArrayFire
[in]	retain	if true calls clRetainCommandQueue prior to returning the context

Returns

af_err error code

Note

Set retain to true if this value will be passed to a cl::CommandQueue constructor

afcl_set_device_context()

AFAPI af_err afcl_set_device_context	(	cl_device_id	dev,
		cl_context	ctx
	)

Set active device using cl_context and cl_device_id.

Parameters

[in]	dev	is the OpenCL device id that is to be set as Active device inside ArrayFire
[in]	ctx	is the OpenCL cl_context being used by ArrayFire

afcl_set_device_id()

AFAPI af_err afcl_set_device_id

(

cl_device_id

id

)

Set ArrayFire's active device based on id of type cl_device_id.

Parameters

[in]

id

the cl_device_id of the device to be set as active device

Returns

af_err error code

array() [1/5]

static af::array array ( af::dim4  idims, cl_mem  buf, af::dtype  type, bool  retain = false  )

inlinestatic

Create an af::array object from an OpenCL cl_mem buffer.

Parameters

[in]	idims	the dimensions of the buffer
[in]	buf	the OpenCL memory object
[in]	type	the data type contained in the buffer
[in]	retain	if true, instructs ArrayFire to retain the memory object

Returns

an array object created from the OpenCL buffer

Note

Set retain to true if the memory originates from a cl::Buffer object

Definition at line 330 of file opencl.h.

 {
     const unsigned ndims = (unsigned)idims.ndims();
     const dim_t *dims = idims.get();
 
     cl_context context;
     cl_int clerr = clGetMemObjectInfo(buf, CL_MEM_CONTEXT, sizeof(cl_context), &context, NULL);
     if (clerr != CL_SUCCESS) {
         throw af::exception("Failed to get context from cl_mem object \"buf\" ");
     }
 
     if (context != getContext()) {
         throw(af::exception("Context mismatch between input \"buf\" and arrayfire"));
     }
 
 
     if (retain) clerr = clRetainMemObject(buf);
 
     af_array out;
     af_err err = af_device_array(&out, buf, ndims, dims, type);
 
     if (err != AF_SUCCESS || clerr != CL_SUCCESS) {
         if (retain && clerr == CL_SUCCESS) clReleaseMemObject(buf);
         throw af::exception("Failed to create device array");
     }
 
     return af::array(out);
 }

array() [2/5]

static af::array array ( dim_t  dim0, cl_mem  buf, af::dtype  type, bool  retain = false  )

inlinestatic

Create an af::array object from an OpenCL cl_mem buffer.

Parameters

[in]	dim0	the length of the first dimension of the buffer
[in]	buf	the OpenCL memory object
[in]	type	the data type contained in the buffer
[in]	retain	if true, instructs ArrayFire to retain the memory object

Returns

an array object created from the OpenCL buffer

Note

Set retain to true if the memory originates from a cl::Buffer object

Definition at line 370 of file opencl.h.

 {
     return afcl::array(af::dim4(dim0), buf, type, retain);
 }

array() [3/5]

static af::array array ( dim_t  dim0, dim_t  dim1, cl_mem  buf, af::dtype  type, bool  retain = false  )

inlinestatic

Create an af::array object from an OpenCL cl_mem buffer.

Parameters

[in]	dim0	the length of the first dimension of the buffer
[in]	dim1	the length of the second dimension of the buffer
[in]	buf	the OpenCL memory object
[in]	type	the data type contained in the buffer
[in]	retain	if true, instructs ArrayFire to retain the memory object

Returns

an array object created from the OpenCL buffer

Note

Set retain to true if the memory originates from a cl::Buffer object

Definition at line 388 of file opencl.h.

 {
     return afcl::array(af::dim4(dim0, dim1), buf, type, retain);
 }

array() [4/5]

static af::array array ( dim_t  dim0, dim_t  dim1, dim_t  dim2, cl_mem  buf, af::dtype  type, bool  retain = false  )

inlinestatic

Create an af::array object from an OpenCL cl_mem buffer.

Parameters

[in]	dim0	the length of the first dimension of the buffer
[in]	dim1	the length of the second dimension of the buffer
[in]	dim2	the length of the third dimension of the buffer
[in]	buf	the OpenCL memory object
[in]	type	the data type contained in the buffer
[in]	retain	if true, instructs ArrayFire to retain the memory object

Returns

an array object created from the OpenCL buffer

Note

Set retain to true if the memory originates from a cl::Buffer object

Definition at line 407 of file opencl.h.

 {
     return afcl::array(af::dim4(dim0, dim1, dim2), buf, type, retain);
 }

array() [5/5]

static af::array array ( dim_t  dim0, dim_t  dim1, dim_t  dim2, dim_t  dim3, cl_mem  buf, af::dtype  type, bool  retain = false  )

inlinestatic

Create an af::array object from an OpenCL cl_mem buffer.

Parameters

[in]	dim0	the length of the first dimension of the buffer
[in]	dim1	the length of the second dimension of the buffer
[in]	dim2	the length of the third dimension of the buffer
[in]	dim3	the length of the fourth dimension of the buffer
[in]	buf	the OpenCL memory object
[in]	type	the data type contained in the buffer
[in]	retain	if true, instructs ArrayFire to retain the memory object

Returns

an array object created from the OpenCL buffer

Note

Set retain to true if the memory originates from a cl::Buffer object

Definition at line 428 of file opencl.h.

 {
     return afcl::array(af::dim4(dim0, dim1, dim2, dim3), buf, type, retain);
 }

deleteDevice()

static void deleteDevice ( cl_device_id  dev, cl_context  ctx  )

inlinestatic

Remove the user provided device control constructs from the ArrayFire device manager pool.

This function should be used only when the user would like ArrayFire to remove an already pushed user generated OpenCL context and related objects.

Parameters

[in]	dev	is the OpenCL device id that has to be popped
[in]	ctx	is the cl_context object to be removed from ArrayFire pool

Note

ArrayFire does not take control of releasing the objects passed to it. The user needs to release them appropriately.

Definition at line 280 of file opencl.h.

{
    af_err err = afcl_delete_device_context(dev, ctx);
    if (err!=AF_SUCCESS) throw af::exception("Failed to remove the requested device from ArrayFire device pool");
}

getContext()

static cl_context getContext ( bool  retain = false )

inlinestatic

Get a handle to ArrayFire's OpenCL context.

Parameters

[in]

retain

if true calls clRetainContext prior to returning the context

Returns

the current context being used by ArrayFire

Note

Set retain to true if this value will be passed to a cl::Context constructor

Definition at line 182 of file opencl.h.

 {
     cl_context ctx;
     af_err err = afcl_get_context(&ctx, retain);
     if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL context from arrayfire");
     return ctx;
 }

getDeviceId()

static cl_device_id getDeviceId ( )

inlinestatic

Get the device ID for ArrayFire's current active device.

Returns

the cl_device_id of the current device

Definition at line 210 of file opencl.h.

 {
     cl_device_id id;
     af_err err = afcl_get_device_id(&id);
     if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL device ID");
 
     return id;
 }

getDeviceType()

static deviceType getDeviceType ( )

inlinestatic

Get the type of the current device.

Definition at line 297 of file opencl.h.

{
    afcl_device_type res = AFCL_DEVICE_TYPE_UNKNOWN;
    af_err err = afcl_get_device_type(&res);
    if (err!=AF_SUCCESS) throw af::exception("Failed to get OpenCL device type");
    return res;
}

getPlatform()

static platform getPlatform ( )

inlinestatic

Get a vendor enumeration for the current platform.

Definition at line 310 of file opencl.h.

{
    afcl_platform res = AFCL_PLATFORM_UNKNOWN;
    af_err err = afcl_get_platform(&res);
    if (err!=AF_SUCCESS) throw af::exception("Failed to get OpenCL platform");
    return res;
}

getQueue()

static cl_command_queue getQueue ( bool  retain = false )

inlinestatic

Get a handle to ArrayFire's OpenCL command queue.

Parameters

[in]

retain

if true calls clRetainCommandQueue prior to returning the context

Returns

the current command queue being used by ArrayFire

Note

Set retain to true if this value will be passed to a cl::CommandQueue constructor

Definition at line 198 of file opencl.h.

 {
     cl_command_queue queue;
     af_err err = afcl_get_queue(&queue, retain);
     if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL command queue from arrayfire");
     return queue;
 }

setDevice()

static void setDevice ( cl_device_id  dev, cl_context  ctx  )

inlinestatic

Set active device using cl_context and cl_device_id.

Parameters

[in]	dev	is the OpenCL device id that is to be set as Active device inside ArrayFire
[in]	ctx	is the OpenCL cl_context being used by ArrayFire

Definition at line 261 of file opencl.h.

{
    af_err err = afcl_set_device_context(dev, ctx);
    if (err!=AF_SUCCESS) throw af::exception("Failed to set device based on cl_device_id & cl_context");
}

setDeviceId()

static void setDeviceId ( cl_device_id  id )

inlinestatic

Set ArrayFire's active device based on id of type cl_device_id.

Parameters

[in]

id

the cl_device_id of the device to be set as active device

Definition at line 225 of file opencl.h.

 {
     af_err err = afcl_set_device_id(id);
     if (err != AF_SUCCESS) throw af::exception("Failed to set OpenCL device as active device");
 }