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.

static QString	activeDeviceInfo (const Info infoType=Info::Name)
	Returns infoType information about the active (default) device.

static QString	activePlatformVersion ()
	Returns the active platform OpenCL version string (e.g.

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.

static QString	buildLog (cl::BuildError &error)
	Extract and return the build log error from error.

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.

static cl::Program	buildProgram (const QString &source, ExceptionBehavior exceptionBehavior=Catch)
	Build the program from source, depending on exceptionBehavior can throw or catch the exceptions.

static cl::CommandQueue	commandQueue ()
	Create an OpenCL command queue from the default context.

static cl::Context	context ()
	Context factory.

static QString	deviceDescription (const cl::Device device)
	Returns a formatted description for the device.

static QString	deviceDescription (const QString deviceId)
	Returns a formatted description for the device identified by deviceId.

static QString	deviceId (const cl::Device device)
	Create a string identifier from a device.

static QString	deviceInfo (const Info infoType, cl::Device device)
	Returns infoType information about the device.

static const std::vector< cl::Device >	devices ()
	Returns a list of OpenCL devices found on this sysytem.

static bool	enabled ()
	Returns `true` if OpenCL is enabled in the user settings.

static QString	errorText (const int errorCode)
	Returns a string representation from an OpenCL errorCode.

static QString	preferredDevice ()
	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 QString	sourceFromBaseName (const QString &baseName)
	Returns the full path to a an OpenCL source file from the baseName ('.cl' extension is automatically appended)

static QString	sourceFromPath (const QString &path)
	Read an OpenCL source file from path.

static QString	sourcePath ()
	Returns the base path to OpenCL program directory.

static void	storePreferredDevice (const QString deviceId)
	Store in the settings the preferred deviceId device identifier.

Static Public Attributes
static QLatin1String	LOGMESSAGE_TAG = QLatin1String( "OpenCL" )
	OpenCL string for message logs.

Detailed Description

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

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

Note: not available in Python bindings

Since: QGIS 3.4

Definition at line 79 of file qgsopenclutils.h.

Member Enumeration Documentation

◆ ExceptionBehavior

enum QgsOpenClUtils::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

enum QgsOpenClUtils::HardwareType

The Type enum represent OpenCL device type.

Enumerator
CPU
GPU
Other

Definition at line 97 of file qgsopenclutils.h.

◆ Info

enum QgsOpenClUtils::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 301 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 237 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 306 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 494 of file qgsopenclutils.cpp.

◆ buildLog()

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

static

Extract and return the build log error from error.

Definition at line 532 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:: QGIS 3.6

Definition at line 673 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 679 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 638 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 659 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 461 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 484 of file qgsopenclutils.cpp.

◆ deviceId()

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

static

Create a string identifier from a device.

Definition at line 330 of file qgsopenclutils.cpp.

◆ deviceInfo()

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

static

Returns infoType information about the device.

Definition at line 242 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 44 of file qgsopenclutils.cpp.

◆ enabled()

bool QgsOpenClUtils::enabled ( )

static

Returns true if OpenCL is enabled in the user settings.

Definition at line 296 of file qgsopenclutils.cpp.

◆ errorText()

QString QgsOpenClUtils::errorText ( const int errorCode )

static

Returns a string representation from an OpenCL errorCode.

Definition at line 541 of file qgsopenclutils.cpp.

◆ preferredDevice()

QString QgsOpenClUtils::preferredDevice ( )

static

Read from the settings the preferred device identifier.

Definition at line 325 of file qgsopenclutils.cpp.

◆ setEnabled()

void QgsOpenClUtils::setEnabled ( bool enabled )

static

Set the OpenCL user setting to enabled.

Definition at line 500 of file qgsopenclutils.cpp.

◆ setSourcePath()

void QgsOpenClUtils::setSourcePath ( const QString & value )

static

Set the base path to OpenCL program directory.

Definition at line 232 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 526 of file qgsopenclutils.cpp.

◆ sourceFromPath()

QString QgsOpenClUtils::sourceFromPath ( const QString & path )

static

Read an OpenCL source file from path.

Definition at line 507 of file qgsopenclutils.cpp.

◆ sourcePath()

QString QgsOpenClUtils::sourcePath ( )

static

Returns the base path to OpenCL program directory.

Definition at line 227 of file qgsopenclutils.cpp.

◆ storePreferredDevice()

void QgsOpenClUtils::storePreferredDevice ( const QString deviceId )

static

Store in the settings the preferred deviceId device identifier.

Definition at line 320 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:

/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/qgsopenclutils.h
/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/qgsopenclutils.cpp

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ ExceptionBehavior

◆ HardwareType

◆ Info

Member Function Documentation

◆ activeDevice()

◆ activeDeviceInfo()

◆ activePlatformVersion()

◆ available()

◆ buildLog()

◆ buildProgram() [1/2]

◆ buildProgram() [2/2]

◆ commandQueue()

◆ context()

◆ deviceDescription() [1/2]

◆ deviceDescription() [2/2]

◆ deviceId()

◆ deviceInfo()

◆ devices()

◆ enabled()

◆ errorText()

◆ preferredDevice()

◆ setEnabled()

◆ setSourcePath()

◆ sourceFromBaseName()

◆ sourceFromPath()

◆ sourcePath()

◆ storePreferredDevice()

Member Data Documentation

◆ LOGMESSAGE_TAG