Table of Contents

OpenCL Acceleration with UMat

OpenCvSharp can use OpenCV's Transparent API (T-API) through UMat. When OpenCL is available and an operation has an OpenCL implementation, passing UMat inputs and outputs allows OpenCV to select that implementation without changing the Cv2 method being called.

OpenCL acceleration is not the same as CUDA support. OpenCvSharp does not expose OpenCV's CUDA modules, and UMat uses OpenCL rather than CUDA.

Treat acceleration as an execution choice, not a guarantee

Using UMat does not guarantee that an operation runs on a GPU or that it is faster than Mat:

  • The operating system must provide a working OpenCL runtime and device driver.
  • OpenCV must have an OpenCL implementation for the operation, image type, and parameters.
  • OpenCV may reject an OpenCL path through its runtime performance checks and fall back to the CPU.
  • Kernel compilation, host-device transfers, and synchronization can outweigh the benefit for small images or short pipelines.
  • Performance varies by operation, device, and driver. An optimization that performs well on one vendor's device may behave differently on another.

Measure the complete production-shaped pipeline instead of assuming that replacing Mat with UMat will improve it.

Check availability and the current state

Use Cv2.Ocl to inspect and control OpenCL use:

Console.WriteLine($"OpenCL available: {Cv2.Ocl.HaveOpenCL()}");
Console.WriteLine($"OpenCL enabled:   {Cv2.Ocl.UseOpenCL()}");

Cv2.Ocl.SetUseOpenCL(true);
Console.WriteLine($"OpenCL enabled:   {Cv2.Ocl.UseOpenCL()}");

These methods answer different questions:

  • HaveOpenCL() reports whether OpenCV can find an OpenCL runtime with at least one platform.
  • UseOpenCL() reports whether OpenCL is currently enabled for the calling thread.
  • SetUseOpenCL(bool) enables or disables OpenCL use for the calling thread.

An available and enabled runtime still does not prove that a particular operation used OpenCL. OpenCV can fall back to another implementation for that call.

Inspect platforms and devices

GetPlatformsInfo() returns read-only snapshots of the OpenCL platforms and devices visible to OpenCV. It returns an empty list when no runtime is available.

foreach (var platform in Cv2.Ocl.GetPlatformsInfo())
{
    Console.WriteLine(
        $"Platform: {platform.Name} ({platform.Vendor}, {platform.Version})");

    foreach (var device in platform.Devices)
    {
        Console.WriteLine($"  Device: {device.Name}");
        Console.WriteLine($"  Type:   {device.Type}");
        Console.WriteLine($"  OpenCL: {device.OpenCLVersion}");
        Console.WriteLine($"  Driver: {device.DriverVersion}");
        Console.WriteLine($"  Memory: {device.GlobalMemorySize} bytes");
    }
}

The returned objects contain diagnostic information. They do not expose or own native OpenCL platform, device, context, or queue handles, and they cannot be used to select a device.

Keep a pipeline in UMat

OpenCL is most useful when several supported operations can run while the data remains in UMat storage:

using var source = new UMat(1080, 1920, MatType.CV_8UC3);
using var blurred = new UMat();
using var hsv = new UMat();

Cv2.GaussianBlur(source, blurred, new Size(5, 5), 0);
Cv2.CvtColor(blurred, hsv, ColorConversionCodes.BGR2HSV);

Converting between Mat and UMat, accessing pixels on the CPU, or calling UMat.GetMat() can introduce synchronization and host-device transfers. Frequent transitions can cost more than the accelerated operations save.

Use GetMat(AccessFlag.READ) when the CPU genuinely needs the result, not merely to make an asynchronous benchmark wait.

Benchmark queued work correctly

OpenCL commands may be queued asynchronously. Measuring only the calls that enqueue work can produce unrealistically short results. Warm up the operation to exclude one-time kernel compilation, then call Finish() at the measurement boundaries:

static TimeSpan MeasureOpenCL(Action operation, int iterations)
{
    operation();
    Cv2.Ocl.Finish(); // Complete warm-up and kernel compilation.

    var stopwatch = Stopwatch.StartNew();
    for (var i = 0; i < iterations; i++)
    {
        operation();
    }

    Cv2.Ocl.Finish(); // Include completion of all queued operations.
    stopwatch.Stop();
    return stopwatch.Elapsed;
}

Run the operation and Finish() on the same thread because OpenCL enablement and the default execution context are thread-specific.

Do not call Finish() after every operation in a normal pipeline. It blocks the calling thread and prevents OpenCV from overlapping or batching queued work. It is primarily useful for benchmarks and genuine synchronization boundaries.

Compare equivalent Mat and UMat pipelines with the same source data, output consumption, dimensions, types, warm-up, and build configuration. Use Release builds, and report both latency and throughput.

Interpret OpenCL build information

Cv2.GetBuildInformation() reports whether OpenCV was built with OpenCL support. An include path containing a version such as opencl/1.2 identifies the OpenCL headers used to compile OpenCV; it does not cap the version reported by the installed runtime or device.

OpenCV loads the OpenCL runtime at execution time. A device can therefore report OpenCL 3.0 through GetPlatformsInfo() even when the build information mentions 1.2 headers. Rebuilding OpenCvSharp with newer headers is not, by itself, expected to make an image-processing operation faster.

Diagnose unexpected performance

When reporting an OpenCL performance problem, include:

  • OpenCvSharp managed and runtime package versions.
  • Operating system and architecture.
  • Release or Debug build configuration.
  • HaveOpenCL() and UseOpenCL() results.
  • Platform, device, OpenCL, and driver values from GetPlatformsInfo().
  • The OpenCL section of Cv2.GetBuildInformation().
  • Equivalent, warmed-up Mat and synchronized UMat measurements.
  • Image dimensions, MatType, parameters, and iteration count.

OpenCvSharp forwards operations such as Cv2.GaussianBlur to OpenCV. Device-specific OpenCL kernels, performance guards, and CPU fallbacks are implemented by upstream OpenCV. Once synchronization and transfer costs have been accounted for, an operation-specific regression will usually need to be reproduced and investigated upstream.

Official OpenCV reference

Edit this page