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

Definition at line 286 of file opencl.h.

◆ platform

Definition at line 287 of file opencl.h.

Function Documentation

◆ addDevice()

static void afcl::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]devis the OpenCL device for which user provided context will be used by ArrayFire
[in]ctxis the user provided OpenCL cl_context to be used by ArrayFire
[in]queis 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 244 of file opencl.h.

245 {
246  af_err err = afcl_add_device_context(dev, ctx, que);
247  if (err!=AF_SUCCESS) throw af::exception("Failed to push user provided device/context to ArrayFire pool");
248 }
The function returned successfully.
Definition: defines.h:67
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.
af_err
Definition: defines.h:63

◆ 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]devis the OpenCL device for which user provided context will be used by ArrayFire
[in]ctxis the user provided OpenCL cl_context to be used by ArrayFire
[in]queis 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]devis the OpenCL device id that has to be popped
[in]ctxis 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]ctxthe current context being used by ArrayFire
[in]retainif 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]idthe 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]queuethe current command queue being used by ArrayFire
[in]retainif 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]devis the OpenCL device id that is to be set as Active device inside ArrayFire
[in]ctxis 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]idthe cl_device_id of the device to be set as active device
Returns
af_err error code

◆ array() [1/5]

static af::array afcl::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]idimsthe dimensions of the buffer
[in]bufthe OpenCL memory object
[in]typethe data type contained in the buffer
[in]retainif 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
Examples:
getting_started/convolve.cpp, getting_started/integer.cpp, image_processing/brain_segmentation.cpp, image_processing/image_demo.cpp, image_processing/morphing.cpp, and image_processing/optical_flow.cpp.

Definition at line 327 of file opencl.h.

328  {
329  const unsigned ndims = (unsigned)idims.ndims();
330  const dim_t *dims = idims.get();
331 
332  cl_context context;
333  cl_int clerr = clGetMemObjectInfo(buf, CL_MEM_CONTEXT, sizeof(cl_context), &context, NULL);
334  if (clerr != CL_SUCCESS) {
335  throw af::exception("Failed to get context from cl_mem object \"buf\" ");
336  }
337 
338  if (context != getContext()) {
339  throw(af::exception("Context mismatch between input \"buf\" and arrayfire"));
340  }
341 
342 
343  if (retain) clerr = clRetainMemObject(buf);
344 
345  af_array out;
346  af_err err = af_device_array(&out, buf, ndims, dims, type);
347 
348  if (err != AF_SUCCESS || clerr != CL_SUCCESS) {
349  if (retain && clerr == CL_SUCCESS) clReleaseMemObject(buf);
350  throw af::exception("Failed to create device array");
351  }
352 
353  return af::array(out);
354  }
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
Definition: opencl.h:425
The function returned successfully.
Definition: defines.h:67
af_err
Definition: defines.h:63
dim_t * get()
Definition: dim4.hpp:46
long long dim_t
Definition: defines.h:50
static cl_context getContext(bool retain=false)
Get a handle to ArrayFire's OpenCL context
Definition: opencl.h:179
dim_t ndims()
AFAPI af_err af_device_array(af_array *arr, const void *data, const unsigned ndims, const dim_t *const dims, const af_dtype type)
Create array from device memory.
void * af_array
Definition: defines.h:222

◆ array() [2/5]

static af::array afcl::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]dim0the length of the first dimension of the buffer
[in]bufthe OpenCL memory object
[in]typethe data type contained in the buffer
[in]retainif 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 367 of file opencl.h.

369  {
370  return afcl::array(af::dim4(dim0), buf, type, retain);
371  }
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:327

◆ array() [3/5]

static af::array afcl::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]dim0the length of the first dimension of the buffer
[in]dim1the length of the second dimension of the buffer
[in]bufthe OpenCL memory object
[in]typethe data type contained in the buffer
[in]retainif 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 385 of file opencl.h.

387  {
388  return afcl::array(af::dim4(dim0, dim1), buf, type, retain);
389  }
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:327

◆ array() [4/5]

static af::array afcl::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]dim0the length of the first dimension of the buffer
[in]dim1the length of the second dimension of the buffer
[in]dim2the length of the third dimension of the buffer
[in]bufthe OpenCL memory object
[in]typethe data type contained in the buffer
[in]retainif 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 404 of file opencl.h.

407  {
408  return afcl::array(af::dim4(dim0, dim1, dim2), buf, type, retain);
409  }
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:327

◆ array() [5/5]

static af::array afcl::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]dim0the length of the first dimension of the buffer
[in]dim1the length of the second dimension of the buffer
[in]dim2the length of the third dimension of the buffer
[in]dim3the length of the fourth dimension of the buffer
[in]bufthe OpenCL memory object
[in]typethe data type contained in the buffer
[in]retainif 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 425 of file opencl.h.

428  {
429  return afcl::array(af::dim4(dim0, dim1, dim2, dim3), buf, type, retain);
430  }
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:327

◆ deleteDevice()

static void afcl::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]devis the OpenCL device id that has to be popped
[in]ctxis 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 277 of file opencl.h.

278 {
279  af_err err = afcl_delete_device_context(dev, ctx);
280  if (err!=AF_SUCCESS) throw af::exception("Failed to remove the requested device from ArrayFire device pool");
281 }
The function returned successfully.
Definition: defines.h:67
af_err
Definition: defines.h:63
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 afcl::getContext ( bool  retain = false)
inlinestatic


Get a handle to ArrayFire's OpenCL context

Parameters
[in]retainif 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 179 of file opencl.h.

180  {
181  cl_context ctx;
182  af_err err = afcl_get_context(&ctx, retain);
183  if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL context from arrayfire");
184  return ctx;
185  }
The function returned successfully.
Definition: defines.h:67
AFAPI af_err afcl_get_context(cl_context *ctx, const bool retain)
Get a handle to ArrayFire's OpenCL context
af_err
Definition: defines.h:63

◆ getDeviceId()

static cl_device_id afcl::getDeviceId ( )
inlinestatic

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

Returns
the cl_device_id of the current device

Definition at line 207 of file opencl.h.

208  {
209  cl_device_id id;
210  af_err err = afcl_get_device_id(&id);
211  if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL device ID");
212 
213  return id;
214  }
The function returned successfully.
Definition: defines.h:67
AFAPI af_err afcl_get_device_id(cl_device_id *id)
Get the device ID for ArrayFire's current active device.
af_err
Definition: defines.h:63

◆ getDeviceType()

static deviceType afcl::getDeviceType ( )
inlinestatic

Get the type of the current device.

Definition at line 294 of file opencl.h.

295 {
297  af_err err = afcl_get_device_type(&res);
298  if (err!=AF_SUCCESS) throw af::exception("Failed to get OpenCL device type");
299  return res;
300 }
The function returned successfully.
Definition: defines.h:67
af_err
Definition: defines.h:63
afcl_device_type
Definition: opencl.h:24
AFAPI af_err afcl_get_device_type(afcl_device_type *res)
Get the type of the current device.

◆ getPlatform()

static platform afcl::getPlatform ( )
inlinestatic

Get a vendor enumeration for the current platform.

Definition at line 307 of file opencl.h.

308 {
310  af_err err = afcl_get_platform(&res);
311  if (err!=AF_SUCCESS) throw af::exception("Failed to get OpenCL platform");
312  return res;
313 }
The function returned successfully.
Definition: defines.h:67
afcl_platform
Definition: opencl.h:34
AFAPI af_err afcl_get_platform(afcl_platform *res)
Get the platform of the current device.
af_err
Definition: defines.h:63

◆ getQueue()

static cl_command_queue afcl::getQueue ( bool  retain = false)
inlinestatic


Get a handle to ArrayFire's OpenCL command queue

Parameters
[in]retainif 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 195 of file opencl.h.

196  {
197  cl_command_queue queue;
198  af_err err = afcl_get_queue(&queue, retain);
199  if (err != AF_SUCCESS) throw af::exception("Failed to get OpenCL command queue from arrayfire");
200  return queue;
201  }
The function returned successfully.
Definition: defines.h:67
AFAPI af_err afcl_get_queue(cl_command_queue *queue, const bool retain)
Get a handle to ArrayFire's OpenCL command queue.
af_err
Definition: defines.h:63

◆ setDevice()

static void afcl::setDevice ( cl_device_id  dev,
cl_context  ctx 
)
inlinestatic

Set active device using cl_context and cl_device_id.

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

Definition at line 258 of file opencl.h.

259 {
260  af_err err = afcl_set_device_context(dev, ctx);
261  if (err!=AF_SUCCESS) throw af::exception("Failed to set device based on cl_device_id & cl_context");
262 }
AFAPI af_err afcl_set_device_context(cl_device_id dev, cl_context ctx)
Set active device using cl_context and cl_device_id.
The function returned successfully.
Definition: defines.h:67
af_err
Definition: defines.h:63

◆ setDeviceId()

static void afcl::setDeviceId ( cl_device_id  id)
inlinestatic

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

Parameters
[in]idthe cl_device_id of the device to be set as active device

Definition at line 222 of file opencl.h.

223  {
224  af_err err = afcl_set_device_id(id);
225  if (err != AF_SUCCESS) throw af::exception("Failed to set OpenCL device as active device");
226  }
The function returned successfully.
Definition: defines.h:67
af_err
Definition: defines.h:63
AFAPI af_err afcl_set_device_id(cl_device_id id)
Set ArrayFire's active device based on id of type cl_device_id.