A high-performance general-purpose compute library

- Main Page
- Tutorials
- Release Notes
- Examples

Typedefs | Functions
OpenCL specific functions
ArrayFire Functions by Category » Interface 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.
static cl_command_queue | getQueue (bool retain=false)
| Get a handle to ArrayFire's OpenCL command queue.
static cl_device_id | getDeviceId ()
| Get the device ID for ArrayFire's current active device.
static void | setDeviceId (cl_device_id id)
| Set ArrayFire's active device based on `id` of type cl_device_id.
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.
static void | setDevice (cl_device_id dev, cl_context ctx)
| Set active device using cl_context and cl_device_id.
static void | deleteDevice (cl_device_id dev, cl_context ctx)
| Remove the user provided device control constructs from the ArrayFire device manager pool.
static deviceType | getDeviceType ()
| Get the type of the current device.
static platform | getPlatform ()
| Get a vendor enumeration for the current platform.
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.
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.
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.
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.
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.
AFAPI af_err | afcl_get_context (cl_context *ctx, const bool retain)
| Get a handle to ArrayFire's OpenCL context.
AFAPI af_err | afcl_get_queue (cl_command_queue *queue, const bool retain)
| Get a handle to ArrayFire's OpenCL command queue.
AFAPI af_err | afcl_get_device_id (cl_device_id *id)
| Get the device ID for ArrayFire's current active device.
AFAPI af_err | afcl_set_device_id (cl_device_id id)
| Set ArrayFire's active device based on `id` of type cl_device_id.
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.
AFAPI af_err | afcl_set_device_context (cl_device_id dev, cl_context ctx)
| Set active device using cl_context and cl_device_id.
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.
AFAPI af_err | afcl_get_device_type (afcl_device_type *res)
| Get the type of the current device.
AFAPI af_err | afcl_get_platform (afcl_platform *res)
| Get the platform of the current device.

## 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 )
| inline static

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.

248{
249 af_err err = afcl_add_device_context(dev, ctx, que);
250 if (err!=AF_SUCCESS) throw af::exception("Failed to push user provided device/context to ArrayFire pool");
251}
af::exception
An ArrayFire exception class.
Definition exception.h:22
af_err
af_err
Definition defines.h:71
AF_SUCCESS
@ AF_SUCCESS
The function returned successfully.
Definition defines.h:75
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.

## ◆ 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 )
| inline static

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.

331 {
332 const unsigned ndims = (unsigned)idims.ndims();
333 const dim_t *dims = idims.get();
334
335 cl_context context;
336 cl_int clerr = clGetMemObjectInfo(buf, CL_MEM_CONTEXT, sizeof(cl_context), &context, NULL);
337 if (clerr != CL_SUCCESS) {
338 throw af::exception("Failed to get context from cl_mem object \"buf\" ");
339 }
340
341 if (context != getContext()) {
342 throw(af::exception("Context mismatch between input \"buf\" and arrayfire"));
343 }
344
345
346 if (retain) clerr = clRetainMemObject(buf);
347
348 af_array out;
349 af_err err = af_device_array(&out, buf, ndims, dims, type);
350
351 if (err != AF_SUCCESS || clerr != CL_SUCCESS) {
352 if (retain && clerr == CL_SUCCESS) clReleaseMemObject(buf);
353 throw af::exception("Failed to create device array");
354 }
355
356 return af::array(out);
357 }
af::array
A multi dimensional data container.
Definition array.h:37
af::dim4::ndims
dim_t ndims()
Returns the number of axis whose values are greater than one.
af::dim4::get
dim_t * get()
Returns the underlying pointer to the dim4 object.
Definition dim4.hpp:103
dim_t
long long dim_t
Definition defines.h:56
af_array
void * af_array
Definition defines.h:240
af_device_array
AFAPI af_err af_device_array(af_array *arr, void *data, const unsigned ndims, const dim_t *const dims, const af_dtype type)
Create array from device memory.
afcl::getContext
static cl_context getContext(bool retain=false)
Get a handle to ArrayFire's OpenCL context.
Definition opencl.h:182

## ◆ array() [2/5]

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

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.

372 {
373 return afcl::array(af::dim4(dim0), buf, type, retain);
374 }
af::dim4
Generic object that represents size and shape.
Definition dim4.hpp:26
afcl::array
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.
Definition opencl.h:330

## ◆ array() [3/5]

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

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.

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

## ◆ 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 )
| inline static

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.

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

## ◆ 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 )
| inline static

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.

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

## ◆ deleteDevice()

static void deleteDevice | ( | cl_device_id | dev,
|  | cl_context | ctx )
| inline static

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.

281{
282 af_err err = afcl_delete_device_context(dev, ctx);
283 if (err!=AF_SUCCESS) throw af::exception("Failed to remove the requested device from ArrayFire device pool");
284}
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.

## ◆ getContext()

static cl_context getContext | ( | bool | retain = false | ) |
| inline static

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.

183 {
184 cl_context ctx;
185 af_err err = afcl_get_context(&ctx, retain);
186 if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL context from arrayfire");
187 return ctx;
188 }
afcl_get_context
AFAPI af_err afcl_get_context(cl_context *ctx, const bool retain)
Get a handle to ArrayFire's OpenCL context.

## ◆ getDeviceId()

static cl_device_id getDeviceId | ( |  | ) |
| inline static

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.

211 {
212 cl_device_id id;
213 af_err err = afcl_get_device_id(&id);
214 if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL device ID");
215
216 return id;
217 }
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.

## ◆ getDeviceType()

static deviceType getDeviceType | ( |  | ) |
| inline static

Get the type of the current device.

Definition at line 297 of file opencl.h.

298{
299 afcl_device_type res = AFCL_DEVICE_TYPE_UNKNOWN;
300 af_err err = afcl_get_device_type(&res);
301 if (err!=AF_SUCCESS) throw af::exception("Failed to get OpenCL device type");
302 return res;
303}
afcl_get_device_type
AFAPI af_err afcl_get_device_type(afcl_device_type *res)
Get the type of the current device.
afcl_device_type
afcl_device_type
Definition opencl.h:28
AFCL_DEVICE_TYPE_UNKNOWN
@ AFCL_DEVICE_TYPE_UNKNOWN
Definition opencl.h:32

## ◆ getPlatform()

static platform getPlatform | ( |  | ) |
| inline static

Get a vendor enumeration for the current platform.

Definition at line 310 of file opencl.h.

311{
312 afcl_platform res = AFCL_PLATFORM_UNKNOWN;
313 af_err err = afcl_get_platform(&res);
314 if (err!=AF_SUCCESS) throw af::exception("Failed to get OpenCL platform");
315 return res;
316}
afcl_get_platform
AFAPI af_err afcl_get_platform(afcl_platform *res)
Get the platform of the current device.
afcl_platform
afcl_platform
Definition opencl.h:38
AFCL_PLATFORM_UNKNOWN
@ AFCL_PLATFORM_UNKNOWN
Definition opencl.h:45

## ◆ getQueue()

static cl_command_queue getQueue | ( | bool | retain = false | ) |
| inline static

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.

199 {
200 cl_command_queue queue;
201 af_err err = afcl_get_queue(&queue, retain);
202 if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL command queue from arrayfire");
203 return queue;
204 }
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.

## ◆ setDevice()

static void setDevice | ( | cl_device_id | dev,
|  | cl_context | ctx )
| inline static

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.

262{
263 af_err err = afcl_set_device_context(dev, ctx);
264 if (err!=AF_SUCCESS) throw af::exception("Failed to set device based on cl_device_id & cl_context");
265}
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.

## ◆ setDeviceId()

static void setDeviceId | ( | cl_device_id | id | ) |
| inline static

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.

226 {
227 af_err err = afcl_set_device_id(id);
228 if (err != AF_SUCCESS) throw af::exception("Failed to set OpenCL device as active device");
229 }
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.