QGIS API Documentation 3.28.0-Firenze (ed3ad0430f)
Classes | Public Types | Static Public Member Functions | Static Public Attributes | List of all members
QgsOpenClUtils Class Reference

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

#include <qgsopenclutils.h>

Classes

struct  CPLAllocator
 Tiny smart-pointer-like wrapper around CPLMalloc and CPLFree: this is needed because OpenCL C++ API may throw exceptions. More...
 

Public Types

enum  ExceptionBehavior { Catch , Throw }
 The ExceptionBehavior enum define how exceptions generated by OpenCL should be treated. More...
 
enum  HardwareType { CPU , GPU , Other }
 The Type enum represent OpenCL device type. More...
 
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. More...
 

Static Public Member Functions

static cl::Device activeDevice ()
 Returns the active device. More...
 
static QString activeDeviceInfo (const Info infoType=Info::Name)
 Returns infoType information about the active (default) device. More...
 
static QString activePlatformVersion ()
 Returns the active platform OpenCL version string (e.g. More...
 
static bool 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. More...
 
static QString buildLog (cl::BuildError &error)
 Extract and return the build log error from error. More...
 
static Q_DECL_DEPRECATED cl::Program 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. More...
 
static cl::Program buildProgram (const QString &source, ExceptionBehavior exceptionBehavior=Catch)
 Build the program from source, depending on exceptionBehavior can throw or catch the exceptions. More...
 
static cl::CommandQueue commandQueue ()
 Create an OpenCL command queue from the default context. More...
 
static cl::Context context ()
 Context factory. More...
 
static QString deviceDescription (const cl::Device device)
 Returns a formatted description for the device. More...
 
static QString deviceDescription (const QString deviceId)
 Returns a formatted description for the device identified by deviceId. More...
 
static QString deviceId (const cl::Device device)
 Create a string identifier from a device. More...
 
static QString deviceInfo (const Info infoType, cl::Device device)
 Returns infoType information about the device. More...
 
static const std::vector< cl::Device > devices ()
 Returns a list of OpenCL devices found on this sysytem. More...
 
static bool enabled ()
 Returns true if OpenCL is enabled in the user settings. More...
 
static QString errorText (const int errorCode)
 Returns a string representation from an OpenCL errorCode. More...
 
static QString preferredDevice ()
 Read from the settings the preferred device identifier. More...
 
static void setEnabled (bool enabled)
 Set the OpenCL user setting to enabled. More...
 
static void setSourcePath (const QString &value)
 Set the base path to OpenCL program directory. More...
 
static QString sourceFromBaseName (const QString &baseName)
 Returns the full path to a an OpenCL source file from the baseName ('.cl' extension is automatically appended) More...
 
static QString sourceFromPath (const QString &path)
 Read an OpenCL source file from path. More...
 
static QString sourcePath ()
 Returns the base path to OpenCL program directory. More...
 
static void storePreferredDevice (const QString deviceId)
 Store in the settings the preferred deviceId device identifier. More...
 

Static Public Attributes

static QLatin1String LOGMESSAGE_TAG = QLatin1String( "OpenCL" )
 OpenCL string for message logs. More...
 

Detailed Description

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

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.
{
// 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
...
}
static Q_DECL_DEPRECATED cl::Program 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 ca...
static cl::Context context()
Context factory.
static bool enabled()
Returns true if OpenCL is enabled in the user settings.
static bool available()
Checks whether a suitable OpenCL platform and device is available on this system and initialize the Q...
static QString sourceFromBaseName(const QString &baseName)
Returns the full path to a an OpenCL source file from the baseName ('.cl' extension is automatically ...
Note
not available in Python bindings
Since
QGIS 3.4

Definition at line 79 of file qgsopenclutils.h.

Member Enumeration Documentation

◆ ExceptionBehavior

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

Enumerator
Catch 

Write errors in the message log and silently fail.

Throw 

Write errors in the message log and re-throw exceptions.

Definition at line 88 of file qgsopenclutils.h.

◆ HardwareType

The Type enum represent OpenCL device type.

Enumerator
CPU 
GPU 
Other 

Definition at line 97 of file qgsopenclutils.h.

◆ Info

The Info enum maps to OpenCL info constants.

See also
deviceInfo()
Enumerator
Name 
Vendor 
Version 
Profile 
ImageSupport 
Image2dMaxWidth 
Image2dMaxHeight 
MaxMemAllocSize 
Type 

Definition at line 111 of file qgsopenclutils.h.

Member Function Documentation

◆ activeDevice()

cl::Device QgsOpenClUtils::activeDevice ( )
static

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).

Definition at line 282 of file qgsopenclutils.cpp.

◆ activeDeviceInfo()

QString QgsOpenClUtils::activeDeviceInfo ( const Info  infoType = Info::Name)
static

Returns infoType information about the active (default) device.

Definition at line 218 of file qgsopenclutils.cpp.

◆ activePlatformVersion()

QString QgsOpenClUtils::activePlatformVersion ( )
static

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

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

Since
QGIS 3.6

Definition at line 287 of file qgsopenclutils.cpp.

◆ available()

bool QgsOpenClUtils::available ( )
static

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

Definition at line 475 of file qgsopenclutils.cpp.

◆ buildLog()

QString QgsOpenClUtils::buildLog ( cl::BuildError &  error)
static

Extract and return the build log error from error.

Definition at line 513 of file qgsopenclutils.cpp.

◆ buildProgram() [1/2]

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

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

Returns
the built program
Deprecated:
since QGIS 3.6

Definition at line 654 of file qgsopenclutils.cpp.

◆ buildProgram() [2/2]

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

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

Returns
the built program

Definition at line 660 of file qgsopenclutils.cpp.

◆ commandQueue()

cl::CommandQueue QgsOpenClUtils::commandQueue ( )
static

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

Definition at line 619 of file qgsopenclutils.cpp.

◆ context()

cl::Context QgsOpenClUtils::context ( )
static

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

Definition at line 640 of file qgsopenclutils.cpp.

◆ deviceDescription() [1/2]

QString QgsOpenClUtils::deviceDescription ( const cl::Device  device)
static

Returns a formatted description for the device.

Definition at line 442 of file qgsopenclutils.cpp.

◆ deviceDescription() [2/2]

QString QgsOpenClUtils::deviceDescription ( const QString  deviceId)
static

Returns a formatted description for the device identified by deviceId.

Definition at line 465 of file qgsopenclutils.cpp.

◆ deviceId()

QString QgsOpenClUtils::deviceId ( const cl::Device  device)
static

Create a string identifier from a device.

Definition at line 311 of file qgsopenclutils.cpp.

◆ deviceInfo()

QString QgsOpenClUtils::deviceInfo ( const Info  infoType,
cl::Device  device 
)
static

Returns infoType information about the device.

Definition at line 223 of file qgsopenclutils.cpp.

◆ devices()

const std::vector< cl::Device > QgsOpenClUtils::devices ( )
static

Returns a list of OpenCL devices found on this sysytem.

Definition at line 40 of file qgsopenclutils.cpp.

◆ enabled()

bool QgsOpenClUtils::enabled ( )
static

Returns true if OpenCL is enabled in the user settings.

Definition at line 277 of file qgsopenclutils.cpp.

◆ errorText()

QString QgsOpenClUtils::errorText ( const int  errorCode)
static

Returns a string representation from an OpenCL errorCode.

Definition at line 522 of file qgsopenclutils.cpp.

◆ preferredDevice()

QString QgsOpenClUtils::preferredDevice ( )
static

Read from the settings the preferred device identifier.

Definition at line 306 of file qgsopenclutils.cpp.

◆ setEnabled()

void QgsOpenClUtils::setEnabled ( bool  enabled)
static

Set the OpenCL user setting to enabled.

Definition at line 481 of file qgsopenclutils.cpp.

◆ setSourcePath()

void QgsOpenClUtils::setSourcePath ( const QString &  value)
static

Set the base path to OpenCL program directory.

Definition at line 213 of file qgsopenclutils.cpp.

◆ sourceFromBaseName()

QString QgsOpenClUtils::sourceFromBaseName ( const QString &  baseName)
static

Returns the full path to a an OpenCL source file from the baseName ('.cl' extension is automatically appended)

Definition at line 507 of file qgsopenclutils.cpp.

◆ sourceFromPath()

QString QgsOpenClUtils::sourceFromPath ( const QString &  path)
static

Read an OpenCL source file from path.

Definition at line 488 of file qgsopenclutils.cpp.

◆ sourcePath()

QString QgsOpenClUtils::sourcePath ( )
static

Returns the base path to OpenCL program directory.

Definition at line 208 of file qgsopenclutils.cpp.

◆ storePreferredDevice()

void QgsOpenClUtils::storePreferredDevice ( const QString  deviceId)
static

Store in the settings the preferred deviceId device identifier.

Definition at line 301 of file qgsopenclutils.cpp.

Member Data Documentation

◆ LOGMESSAGE_TAG

QLatin1String QgsOpenClUtils::LOGMESSAGE_TAG = QLatin1String( "OpenCL" )
static

OpenCL string for message logs.

Definition at line 189 of file qgsopenclutils.h.


The documentation for this class was generated from the following files: