From 689b0fc2c0722b55dc534523720f3319b0aaa6ca Mon Sep 17 00:00:00 2001 From: Deny Dias Date: Wed, 5 Jan 2022 04:17:02 -0300 Subject: [PATCH] Update OpenCL documentation (#84) * Updated OpenCL documentation as per ImageMagick/ImageMagick#4646 --- include/opencl.php | 60 +++++++++++++++++++++++++++------------------- script/session.php | 7 ++++-- 2 files changed, 41 insertions(+), 26 deletions(-) diff --git a/include/opencl.php b/include/opencl.php index ba2e50bf..bc2eb722 100644 --- a/include/opencl.php +++ b/include/opencl.php @@ -1,30 +1,42 @@
-

The following is a list of image operators that have been OpenCL-accelerated:

- +

ImageMagick has built-in support for some OpenCL accelerated operations. However, there are some conditions for its operation. These requirements are listed below.

-

When the OpenCL acceleration is invoked for the first time, ImageMagick conducts a series of tests to configure the OpenCL environment according to the system hardware; therefore, it is normal to experience a higher latency the first time you use an accelerated option. The OpenCL kernels are embedded inside ImageMagick in source format. During the initial setup, ImageMagick discovers all the available OpenCL devices and compiles the kernels for each of these targets. ImageMagick also runs several performance tests internally to determine the preferred device to use. The compiled kernel code and the performance test results are stored into the cache directory so that the data can be reused by subsequent invocations of the OpenCL path. By default, the OpenCL cached data is stored in $HOME/.cache/ImageMagick on Linux and on MacOSX or in %LOCALAPPDATA%\ImageMagick on Windows. To change the cache directory, set the MAGICK_OPENCL_CACHE_DIR environment variable. ImageMagick is able to detect hardware changes, driver updates, and new kernel sources and re-run the setup and the calibration test. You can also force ImageMagick to re-run the process by removing the content from the cache directory.

-

If ImageMagick includes OpenCL support, the OpenCL path is enable by default. You can disable it, simply set the environment variable MAGICK_OCL_DEVICE to OFF. You could also force the OpenCL path to use a particular class of devices by setting it to GPU or CPU.

-

In addition to the environment variables just mentioned, ImageMagick provides a set of APIs that allow developers to gain a finer grain control of the OpenCL acceleration. For example, use the InitializeOpenCL) function to initialize the OpenCL environment:

+
    +
  1. GPU platform: AMD or Intel GPUs are supported. NVIDIA support is not enabled at the moment.
    2. +
  2. OS and drivers: +
      +
    • Mac OS X: has built-in support for OpenCL. No other actions required.
      • +
    • Linux/Windows: on supported platforms, install required drivers to enable OpenCL.
      • +
    • Mobile: ImageMagick's OpenCL support is not available on mobile OSes (IOS/Android).
      • +
    +
    3. +
  3. Compile-time flag: ImageMagick's OpenCL must be explicitly enabled when compiling. This is done by running configure with --enable-opencl flag set.
    4. +
  4. Check runtime support: to verify if OpenCL support is enabled, run magick --version. The command output should read Features: ... OpenCL ...
    5. +
  5. Runtime flag: OpenCL is disabled by default in runtime. To enable it use the environment variable MAGICK_OCL_DEVICE=true, e.g. MAGICK_OCL_DEVICE=true magick <options>.
    6. +
  6. Command line utility: for proper OpenCL support it's recommended to use magick utility over convert, mogrify and others.
    7. +
  7. Image type: OpenCL acceleration only works on images without a color map. Use true color images instead.
    8. +
  8. Operators: the following is a list of image operators that have been OpenCL accelerated. +
        blur
+  contrast
+  charcoal
+  function
+  grayscale
+  motion-blur
+  resize
    + The following operators are OpenCL accelerated as well, but they require alpha channel to be enabled, e.g. MAGICK_OCL_DEVICE=true magick sample.jpg -alpha on -despeckle null:. +
        despeckle
+  equalize
+  modulate
    +
    9. +
+ +

OpenCL Operation Notes

+ +

When some of the OpenCL accelerated operators are invoked for the first time and all the conditions above are met, ImageMagick conducts a series of tests to configure the OpenCL environment according to the system hardware; therefore, it is normal to experience a higher latency the first time you use an accelerated option. The OpenCL kernels are embedded inside ImageMagick in source format. During the initial setup, ImageMagick discovers all the available OpenCL devices and compiles the kernels for each of these targets. ImageMagick also runs several performance tests internally to determine the preferred device to use. The compiled kernel code and the performance test results are stored into the cache directory so that the data can be reused by subsequent invocations of the OpenCL path. By default, the OpenCL cached data is stored in $HOME/.cache/ImageMagick on Linux and on MacOSX or in %LOCALAPPDATA%\ImageMagick on Windows. To run these tests for the first time, use the comand below:

+ +

To change the cache directory, set the MAGICK_OPENCL_CACHE_DIR environment variable. ImageMagick is able to detect hardware changes, driver updates, and new kernel sources and re-run the setup and the calibration test. You can also force ImageMagick to re-run the process by removing the content from the cache directory.

+

In addition to the environment variables mentioned above, ImageMagick provides a set of APIs that allow developers to gain more fine-grained control of the OpenCL acceleration. For example, use the InitializeOpenCL() function to initialize the OpenCL environment: