Back to Adaptive Vision Library website

You are here: Start » Function Reference » Configuration » AvsFilter_InitGPUProcessing

AvsFilter_InitGPUProcessing


This is Filter Equivalent. This function may be present in generated code, but should not be used in hand-written code.

Header: AVL.h
Namespace: avs
Module: FoundationBasic

Initializes GPU OpenCL processing.

Syntax

void avs::AvsFilter_InitGPUProcessing
(
	InitGPUProcessingState& ioState,
	const atl::Optional<const atl::String&>& inPlatformName,
	const atl::Optional<const atl::String&>& inDeviceName,
	atl::Optional<atl::String&> diagDeviceInfo
)

Parameters

Name Type Default Description
ioState InitGPUProcessingState& Object used to maintain state of the function.
inPlatformName const Optional<const String&>& NIL Name or fragment of a name of OpenCL provider platform
inDeviceName const Optional<const String&>& NIL Name or fragment of a name of OpenCL device
diagDeviceInfo Optional<String&> Provides human readable diagnostic information about OpenCL device selected for processing

Description

This filter selects desired OpenCL processing device and initializes internal OpenCL processing context. This filter is required to be executed at beginning of a program in order to move processing of OpenCL capable filters to OpenCL device. After executing this filter OpenCL processing is initialized and enabled for consecutive filters. Refer to filters documentation to find which filters can benefit from OpenCL processing. Do not initialize OpenCL processing if you are not using OpenCL capable filters to not waste system resources.

Performance of OpenCL capable filters may vary depending on processed data and target system hardware properties. Resulting performance is hard to predict and always have to be measured on target system. In some situations filters can be executed on OpenCL device without significant speedup or even slower than on CPU and in such cases specific filter instances can be excluded from processing on OpenCL device. In order to specify how OpenCL capable filters will be executed (using CPU or OpenCL device) use AvsFilter_EnableGPUProcessing.

Processing is performed using single OpenCL device from system. By default (when inputs are left on auto) the first graphics card found in system that supports required OpenCL properties is selected as processing device. inPlatformName input can be used to limit device search only to specified OpenCL provider platform. inPlatformName is case insensitive and must be set to a name or a fragment of a name of required platform (like "intel" for "Intel(R) OpenCL" platform or "nvidia" for "NVIDIA CUDA" platform). inDeviceName input can be used to manually pick a processing device from local system. Similarly inPlatformName is case insensitive and must be set to a full name or a fragment of a name of required OpenCL device.

diagDeviceInfo diagnostic output can be used to verify which device is used for processing and what are its capabilities. Output is formed as a human readable text that can be viewed by dragging this output to a preview panel.

For OpenCL capable device to be available for processing a proper device driver or a runtime environment must be installed on a target system. For graphics cards a dedicated device driver, provided by its vendor, must be installed. Be sure to use the newest drivers and always keep device drivers up to date. For some devices a separate dedicated OpenCL runtime library may be needed on target system. Refer to device vendor documentation for more information. Adaptive Vision Studio filters requires OpenCL device supporting OpenCL C language with compiler in version 1.1 or greater.

When there is no OpenCL capable device available in system, specified platform name or device name cannot be found or selected device does not supports required properties an IOError is raised by this filter.

Be aware that first execution of this filter as well as first execution of OpenCL processing filters (when OpenCL processing is enabled) requires an extra initialization of OpenCL state and can be significantly longer that execution in next iterations.

Errors

List of possible exceptions:

Error type Description
DomainError Empty device name specified.
inDeviceName is set to empty text.
DomainError Empty platform name specified.
inPlatformName is set to empty text.
IoError No suitable GPU OpenCL device available in local system.
Platform name and device name was not specified and there is no OpenCL capable graphics card installed in local system, there is no proper runtime software for it or it does not meet requirements.
IoError No suitable GPU OpenCL device available in selected local platform.
Platform name was specified and found but it does not contain an OpenCL capable graphics card or it does not meet requirements.
IoError OpenCL is not available in local system.
No OpenCL platform runtime software has been installed on local system.
IoError Selected OpenCL device does not provides an OpenCL C compiler.
Device name was specified and found but it does not provide an OpenCL C compiler.
IoError Selected OpenCL device does not supports required minimal version of OpenCL C language.
Device name was specified and found but its OpenCL C compiler does not supports OpenCL C standard of required minimal version.
IoError Selected OpenCL device has endianness different than host.
Device name was specified and found but it reports endianness different than host CPU endianness.
IoError Unable to find OpenCL device with specified name.
Device name was specified but local system (or specified platform) does not contain a device with matching name.
IoError Unable to find OpenCL platform with specified name.
Platform name was specified but there is not OpenCL platform in local system with matching name.

See Also