QgsOpenClUtils class

The QgsOpenClUtils class is responsible for common OpenCL operations such as.

Reference

enable/disable opencl
store and retrieve preferences for the default device
check opencl device availability and automatically choose the first GPU device
creating the default context
loading program sources from standard locations
build programs and log errors

Usage:

// This will check if OpenCL is enabled in user options and if there is a suitable
// device, if a device is found it is initialized.
if ( QgsOpenClUtils::enabled() && QgsOpenClUtils::available() )
{
   // Use the default context
   cl::Context ctx = QgsOpenClUtils::context();
   cl::CommandQueue queue( ctx );
   // Load the program from a standard location and build it
   cl::Program program = QgsOpenClUtils::buildProgram( ctx, QgsOpenClUtils::sourceFromBaseName( QStringLiteral ( "hillshade" ) ) );
   // Continue with the usual OpenCL buffer, kernel and execution
   ...
}

Public types

template<typename T> struct CPLAllocator: Tiny smart-pointer-like wrapper around CPLMalloc and CPLFree: this is needed because OpenCL C++ API may throw exceptions.
enum ExceptionBehavior { Catch, Throw }: The ExceptionBehavior enum define how exceptions generated by OpenCL should be treated.
enum HardwareType { CPU, GPU, Other }: The Type enum represent OpenCL device type.
enum Info { Name = CL_DEVICE_NAME, Vendor = CL_DEVICE_VENDOR, Version = CL_DEVICE_VERSION, Profile = CL_DEVICE_PROFILE, ImageSupport = CL_DEVICE_IMAGE_SUPPORT, Image2dMaxWidth = CL_DEVICE_IMAGE2D_MAX_WIDTH, Image2dMaxHeight = CL_DEVICE_IMAGE2D_MAX_HEIGHT, MaxMemAllocSize = CL_DEVICE_MAX_MEM_ALLOC_SIZE, Type = CL_DEVICE_TYPE }: The Info enum maps to OpenCL info constants.

Public static variables

static QLatin1String LOGMESSAGE_TAG: OpenCL string for message logs.

Public static functions

static auto activeDevice() -> cl::Device: Returns the active device.
static auto activeDeviceInfo(const Info infoType = Info::Name) -> QString: Returns infoType information about the active (default) device.
static auto activePlatformVersion() -> QString: Returns the active platform OpenCL version string (e.g.
static auto available() -> bool: Checks whether a suitable OpenCL platform and device is available on this system and initialize the QGIS OpenCL system by activating the preferred device if specified in the user the settings, if no preferred device was set or the preferred device could not be found the first GPU device is activated, the first CPU device acts as a fallback if none of the previous could be found.
static auto buildLog(cl::BuildError& error) -> QString: Extract and return the build log error from error.
static auto buildProgram(const cl::Context& context, const QString& source, ExceptionBehavior exceptionBehavior = Catch) -> Q_DECL_DEPRECATED cl::Program deprecated: Build the program from source in the given context and depending on exceptionBehavior can throw or catch the exceptions.
static auto buildProgram(const QString& source, ExceptionBehavior exceptionBehavior = Catch) -> cl::Program: Build the program from source, depending on exceptionBehavior can throw or catch the exceptions.
static auto commandQueue() -> cl::CommandQueue: Create an OpenCL command queue from the default context.
static auto context() -> cl::Context: Context factory.
static auto deviceDescription(const cl::Device device) -> QString: Returns a formatted description for the device.
static auto deviceDescription(const QString deviceId) -> QString: Returns a formatted description for the device identified by deviceId.
static auto deviceId(const cl::Device device) -> QString: Create a string identifier from a device.
static auto deviceInfo(const Info infoType, cl::Device device) -> QString: Returns infoType information about the device.
static auto devices() -> const std::vector<cl::Device>: Returns a list of OpenCL devices found on this sysytem.
static auto enabled() -> bool: Returns true if OpenCL is enabled in the user settings.
static auto errorText(const int errorCode) -> QString: Returns a string representation from an OpenCL errorCode.
static auto preferredDevice() -> QString: Read from the settings the preferred device identifier.
static void setEnabled(bool enabled): Set the OpenCL user setting to enabled.
static void setSourcePath(const QString& value): Set the base path to OpenCL program directory.
static auto sourceFromBaseName(const QString& baseName) -> QString: Returns the full path to a an OpenCL source file from the baseName ('.cl' extension is automatically appended)
static auto sourceFromPath(const QString& path) -> QString: Read an OpenCL source file from path.
static auto sourcePath() -> QString: Returns the base path to OpenCL program directory.
static void storePreferredDevice(const QString deviceId): Store in the settings the preferred deviceId device identifier.

Enum documentation

enum QgsOpenClUtils::ExceptionBehavior

The ExceptionBehavior enum define how exceptions generated by OpenCL should be treated.

Enumerators
Catch
Throw	Write errors in the message log and silently fail. Write errors in the message log and re-throw exceptions

Enumerators

Catch

Throw

Write errors in the message log and silently fail.

Write errors in the message log and re-throw exceptions

enum QgsOpenClUtils::Info

The Info enum maps to OpenCL info constants.

Function documentation

static cl::Device QgsOpenClUtils::activeDevice()

Returns the active device.

The active device is set as the default device for all OpenCL operations, once it is set it cannot be changed until QGIS is restarted (this is due to the way the underlying OpenCL library is built).

static QString QgsOpenClUtils::activePlatformVersion()

Returns the active platform OpenCL version string (e.g.

1.1, 2.0 etc.) or a blank string if there is no active platform.

static bool QgsOpenClUtils::available()

Checks whether a suitable OpenCL platform and device is available on this system and initialize the QGIS OpenCL system by activating the preferred device if specified in the user the settings, if no preferred device was set or the preferred device could not be found the first GPU device is activated, the first CPU device acts as a fallback if none of the previous could be found.

This function must always be called before using QGIS OpenCL utils

static Q_DECL_DEPRECATED cl::Program QgsOpenClUtils::buildProgram(const cl::Context& context, const QString& source, ExceptionBehavior exceptionBehavior = Catch)

Build the program from source in the given context and depending on exceptionBehavior can throw or catch the exceptions.

Returns	the built program

static cl::Program QgsOpenClUtils::buildProgram(const QString& source, ExceptionBehavior exceptionBehavior = Catch)

Build the program from source, depending on exceptionBehavior can throw or catch the exceptions.

Returns	the built program

static cl::CommandQueue QgsOpenClUtils::commandQueue()

Create an OpenCL command queue from the default context.

This wrapper is required in order to prevent a crash when running on OpenCL platforms < 2

static cl::Context QgsOpenClUtils::context()

Context factory.

Returns	a new context for the default device or an invalid context if no device were identified or OpenCL support is not available and enabled