GEGL-OpenCL

First official OPP (OpenCL Porting Project) of OpenCL.org

GEGL (Generic Graphics Library) is a graph based image processing framework.

With GEGL you chain together image processing operations represented by nodes into a graph. GEGL provides such operations for loading and storing images, adjusting colors, filtering in different ways, transforming and compositing images.

GEGL also depends on BABL to translate pixel formats. BABL allows converting between different methods of storing pixels known as pixel formats that have with different bitdepths and other data representations, color models and component permutations. A vocabulary to formulate new pixel formats from existing primitives is provided as well as the framework to add new color models and data types.

For a brief explanation on how GEGL works, read this document

Index

1. Installing
2. Development
3. Contributing
4. How to Port an Operation
5. How to Test Output
6. How to Benchmark Performance

Installing

Read the document above for more information, or refer to the links below for the respective platforms

On Windows

On Linux Platforms

Ensure that BABL is installed first before GEGL.

Development

The code for GEGL-OpenCL can be found at GEGL-OpenCL Github.

There already exists OpenCL integration into GEGL and some operations have already been ported to run on OpenCL. However, there is still a lot of operations that need porting as listed in the Google Sheet below.

Task List for GEGL-OpenCL (Excel)

Task List for GEGL-OpenCL (Github)

Likewise, we have a slack channel for discussions pertaining to development and issues here, GEGL-OpenCL Slack

Contributing

It is recommended that you fork this repository and create your branches there. After every discussion, if your kernel has the fastest speed for the vendor, you can create a pull request to have your changes merged. Please include the test results (correctness and timing), and name the pull request according to the operation you're working on and the vendor you're optimizing for, eg. box-blur_kernel_nv

Please ensure that make clean is executed before requesting a pull request

How to Port an Operation

• Find an operation you'd like to work on under /operations/, eg. box-blur which can be found under /operations/common/
• In box-blur.c, add the following line in the gegl_op_class_init function:

static void
gegl_op_class_init (GeglOpClass *klass)
{
  GeglOperationClass       *operation_class;
  GeglOperationFilterClass *filter_class;

  operation_class = GEGL_OPERATION_CLASS (klass);
  filter_class    = GEGL_OPERATION_FILTER_CLASS (klass);

  filter_class->process    = process;
  operation_class->prepare = prepare;
  
  // insert this line below
  operation_class->opencl_support = TRUE;
  
  gegl_operation_class_set_keys (operation_class,
      "name",        "gegl:box-blur",
      "title",       _("Box Blur"),
      "categories",  "blur",
      "description", _("Blur resulting from averaging the colors of a square neighbourhood."),
      NULL);
}

• Create a cl_process function (which contains the host-code implementation) with the following parameters in the same file

static gboolean
cl_process (GeglOperation       *operation,
            GeglBuffer          *input,
            GeglBuffer          *output,
            const GeglRectangle *result)

• Add a function call in the main process function before the cpu implementation

if (gegl_operation_use_opencl (operation))
    if (cl_process (operation, input, output, result))
      return TRUE;

• Both kernel and kernel header file (.cl and .cl.h) should be stored in the /opencl/ folder.
• Include both files, and any other necessary gegl-cl header in the operation's source code (eg. box-blur.c)

#include "opencl/gegl-cl.h"
#include "buffer/gegl-buffer-cl-iterator.h"
#include "opencl/box-blur.cl.h"

How to Test Output

• create an xml file (eg. box-blur.xml) containing the following code

<?xml version='1.0' encoding='UTF-8'?>
<gegl>
  <node operation='gegl:box-blur'>
    <params>
      <param name='radius'>25</param>
    </params>
  </node>
  <node operation='gegl:load'>
    <params>
      <param name='path'>../compositions/data/car-stack.png</param>
    </params>
  </node>
</gegl>

• run the following shell command to generate an output

$ gegl box-blur.xml -o test.jpg GEGL_USE_OPENCL=yes

• to check correctness of the image generated, run a command with OpenCL disabled first

$ gegl box-blur.xml -o test2.jpg GEGL_USE_OPENCL=no

• and run the below to get a measure of correctness

$ gegl-imgcmp test2.jpg test.jpg

• there is also a script in /tests/compositions that can be used to verify that the OpenCL operation works

$ cd tests/compositions
$ python run-compositions.py alien-map.xml
$ python run-compositions.py alien-map.xml --without-opencl

How to Benchmark Performance

• create an xml file similar to the above in /tests/opencl
• before running the shell script ensure that the perl module below is installed

$ cpan
cpan[1]> install "XML::Twig";

• to run the benchmark script

$ cd tests/opencl
$ perl benchmark.pl box-blur.xml no 1
$ perl benchmark.pl box-blur.xml gpu 1
$ perl benchmark.pl box-blur.xml cpu 1

• note that 'gpu'/'cpu' denotes that OpenCL is enabled, while 'no' denotes that OpenCL is disabled
• the number at the end denotes the number of iterations to run, after which the average time for the operation is returned