"assure")"destroy")"active") "active_id") "get_resources") "device_selection", [str]) Manage the OpenCL Context.
ocl_context ("assure") sets up the OpenCL context and makes it
active and usable for operations with OpenCL memory objects and programs.
The single currently selected OpenCL device (see below) is determined and,
if valid, is used for setting up the OpenCL context.
If the OpenCL context was already active, ocl_context has no effect.
If any step is unsuccessful, ocl_context aborts with an error.
ocl_context ("destroy") destroys the OpenCL context.
If no OpenCL context was active, ocl_context has no effect.
Destroying the OpenCL context has two distinct consequences: First, the OpenCL
memory and programs allocated within the context are immediately deleted and
freed on the device.
Second, all OCL or octave objects which rely on these deleted OpenCL objects
and which remain in octave
memory are made inoperable and will produce an error when used afterwards.
ocl_context ("active") returns whether an OpenCL context is currently active.
A nonzero value active means that a context is currently active.
A nonzero value of the optional output variable fp64 means that the active context
is capable of computing with 64-bit floating-point (i.e., double precision).
ocl_context ("active_id") is similar to ocl_context ("active"),
but returns the current context identifier activeid instead.
The context identifier is only nonzero when a context is active.
When using ocl_context ("destroy") in between, the context identifier value is
distinct for each subsequent active OpenCL context
(which means that each OpenCL memory object or program object is associated with a specific
context identifier to be operable with).
ocl_context ("get_resources") returns comprehensive information on the available
resources (hardware and software) which can potentially be used for OpenCL computations.
The return value resources is a hierarchical struct of which many leaf values have
self-explanatory names; for detailled reference, see the OpenCL specification.
resources itself is assembled by ocl_context and contains the following fields:
.platformsA struct array containing information on the available OpenCL platforms (i.e., vendors).
.devicesA cell array containing, per platform, all OpenCL devices (i.e., hardware units with separate memory and processors), each with detailled information.
.summaryA struct array containing a pre-ordered single list of all devices with only the most important information.
This information, especially the summary field, should give
the user enough guidance on which device
to select for actual OCL computations (see below).
ocl_context ("device_selection", ...) can be used
to query or set the device selection strategy, or to return the single device so selected.
To set the device selection strategy, str must be one of:
"auto"The future selected device will be the first device from the (pre-ordered) resource summary list.
"GPU"The future selected device will be the first GPU device from the resource summary list.
"GPUn"The future selected device will be the (n+1)-th GPU device from the resource summary list,
with n being a non-negative integer (i.e., "GPU0" is equivalent to "GPU").
"ACC"The future selected device will be the first ACC device from the resource summary list.
"ACCn"The future selected device will be the (n+1)-th ACC device from the resource summary list.
"CPU"The future selected device will be the first CPU device from the resource summary list.
"CPUn"The future selected device will be the (n+1)-th CPU device from the resource summary list.
"devn"The future selected device will be the (n+1)-th device from the resource summary list.
Without str, or when an output parameter selection is requested, the current or prior setting of the device selection strategy is returned as one of the above strings. These calls have no immediate effect on the OpenCL library or context. No checking of availability against present resources is performed (only syntax checking of str).
In contrast, ocl_context ("device_selection", "selected") applies the
current device selection strategy onto the actually available resources and
selects a single OpenCL device from the summary accordingly.
If the strategy fails to find a corresponding device, ocl_context aborts
with an error at this point.
Otherwise, selection returns a 2x1 array containing the platform and
device index (starting from zero; as counted in the resources fields).
The first four subfunctions of ocl_context only need to be called explicitly
in rare situations, since many other ("higher") OCL functions call them internally.
These subfunctions are provided mainly for testing.
ocl_context ("get_resources") is of regular interest to the user, and
ocl_context ("device_selection", ...) to choose the device selection strategy
is likey to be called once or more per octave session
(maybe even in your .octaverc file).
Note that ocl_context ("assure"), ocl_context ("get_resources"), and
ocl_context ("device_selection", "selected") automatically load the OpenCL library.
See also: oclArray.
Package: ocl