Hacking:Porting filters to GEGL

Last updated: see tab 'history'

How to port

GEGL part

This is the general process for writing a new GEGL operation:

1. Gather information:
   1. Go over the source code of the plugin you wish to port. Understand the algorithm it implements.
   2. Read the GEGL website carefully. There is lot of information there.
   3. Read the babl website. Understand the differences between color models.
   4. You may wish to find a similar existing operation and get inspiration from it.
2. Choose a base class. This is the general structure of your operation, the number of inputs and outputs, and what kind of optimizations GEGL can do.
3. Create a new file for your operation. The exact directory where you should put your file into is explained at GEGL's website.
4. Register the operation in Makefile.am. Exactly how this is done depends on which directory you're placing your files into. For operations in operations/common/ (should be most operations), you need to add a single line mentioning your operation to the variable op_LTLIBRARIES. For example, if your c file is named edge.c, you would add a line that says "edge.la \". Please keep it in alphabetical order.
5. Copy another operation with the same base class and clean it up to have your operation skeleton. GEGL uses a macro system called GEGL chant. It makes it unnecessary for you to write all the GObject boilerplate, and eases your work registering parameters for your operation. Look at other operations to see how it works.
6. Use the prepare function to specify which color model your op will operate with for each input/output.
7. Create your operation's parameters using the chant system. You can have integer, floats, string, color, curve, enum ... There are some predefined enums in the GEGL core, for instance GeglSamplerType. You can register your own like in the Ripple op.
8. Write your operation in the process function. Here are some hints:
   1. GEGL stores data in tiles. This imposes some restrictions, especially for transform operations. You usually need to write your algorithm backwards, i.e. iterate over the output, compute where the data come from, and use a sampler to get it and affect the output.
   2. ROI means region of interest. It's the area you are currently working on.
   3. Sometimes you need to know the size of the full input, not just the ROI. You can have it using gegl_operation_source_get_bounding_box.
   4. Rather than carrying a lot of parameters in your various functions, you can register a custom aggregate structure in the chant system, like the WarpPrivate structure in the Warp operation.
   5. If you fetch data from outside of the input buffer (in its abyss), you get zeroed memory by default. The abyss policy allows you to chose what you want here. In particular you can choose to clamp to the border, loop in the buffer extent, or it allows you to implement a more intelligent algorithm. For instance see the Ripple operation. Setting the abyss policy to GEGL_ABYSS_LOOP adds the tileability to the operation for free.
9. Test your operation. You can use the GEGL binary to run an XML file or use the GEGL tool in GIMP.

GIMP part

Alternative 1: Use a GeglBuffer to work on. For instance see /plug-ins/common/file-aa.c.

Alternative 2: In your program, create a GEGL graph and let it call gegl_node_process on it. See the column 'GEGL operation' below to see what has already been done in GEGL. For instance, see /plug-ins/common/file-gegl.c.

For more inspiration, see the other files that have already been ported.

Porting matrix

Legend

Columns 'GEGL port', 'OpenCL version':

	completely unimplemented yet
	implementation unfinished
	implementation finished, no matter of the test results
	doesn't need porting

Columns 'Test result':

	tests failed (please also describe the failure shortly in the comment field or link to a Bugzilla bug report)
	tests unfinished
	tests ok
	not tested at all yet

You can sort the following tables by clicking the little arrow symbol in the column headers. If that doesn't work out of the box, please activate Javascript for this page.

GIMP core (Layer modes, Transformation and Color Adjustment Tools)

The GIMP core is already migrated to GEGL. See Michael Natterers blogposting and an article at libgregraphicsworld.org.

Processing, color grading and effects

GIMP filter	GEGL operation	GEGL port	Test result	OpenCL version	Test result	Comment
Alien Map	alien-map	Yes	untested	Yes	untested
Align Visible Layers						Doesn't need porting
Animation Playback		Yes	untested	No	untested
Antialias	antialias	Yes	untested	No	untested
Apply Canvas	texturize-canvas	work in progress	untested	Yes	untested	texturize-canvas should be more generic and allow any input texture instead of the hard-coded one only.
Apply Lens	apply-lens	Yes	untested	No	untested	get_required_for_output and get_invalidated_by_change methods need a better implementation
Assign Color Profile		No	untested	No	untested
Autocrop Image		Yes	untested	No	untested	Done in core
Autocrop Layer		Yes	untested	No	untested	Done in core
Border Average		Yes	untested	No	untested
Bump Map	bump-map	Yes	untested	No	untested
Cartoon	cartoon	work in progress	untested	No	untested	Result is a bit different compared to original plugin, because it uses another color format to proceed (Y'CbCr instead of HSL)
Channel Mixer	channel-mixer	Yes	untested	No	untested
Checkerboard	checkerboard	work in progress	untested	No	untested	Missing Psychobilly Option
CML Explorer		No	untested	No	untested
Color Enhance	color-enhance	Yes	untested	No	untested
Color Exchange	color-exchange	Yes	untested	Yes	untested
Color to Alpha	color-to-alpha	work in progress	untested	Yes	untested	The pdb wrapper needs some more love (see comment in there)
Colorcube Analysis		No	untested	No	untested
Compose		Yes	untested	No	untested	Compatibility with 2.8 is currently not maintained : An image decomposed in 2.8 won't be recomposed correctly in 2.10. Also it's inconsistent with gimp's gamma policy. Nobody know who is right currently.
Convert to Color Profile		No	untested	No	untested
Convolution Matrix	convolution-matrix	No	untested	No	untested	Not sure the wip GEGL operation is the right approach for that op. Shouldn't that matrix be given as an aux input, instead of the chant property ?
Cubism	cubism	work in progress	untested	No	untested	It doesn't honnor the GeglOperationAreaFilter class properly
Curve Bend		No	untested	No	untested
Decompose		Yes	untested	No	untested	inconsistent with gimp's gamma policy currently. Nobody know who is right currently. See also Compose
Deinterlace	deinterlace	work in progress	untested	No	untested	The current GEGL implementation is wrong (just try it on a black/white 1px grid), and not sure what the parameter size is for...
Depth Merge		No	untested	No	untested
Despeckle		No	untested	No	untested
Destripe		No	untested	No	untested
Difference of Gaussians	difference-of-gaussians	work in progress	untested	No	untested	The port is missing Normalize and Invert options
Diffraction Patterns	diffraction-patterns	Yes	untested	Yes	untested
Dilate		Yes	untested	No	untested	Provided by the value-propagate operation
Displace	displace	Yes	untested	work in progress	untested	Is currently being ported by some students as an university project focused on OpenCL. Results can be expected in 2015.
Drop Shadow	dropshadow	work in progress	untested	No	untested	Shadow effect only seen in transparent areas inside the layer bounds.
Edge-Detect (Edge...)	edge	Yes	untested	No	untested
Edge-Detect (Laplace)	edge-laplace	Yes	untested	Yes	untested
Edge-Detect (Neon)		No	untested	No	untested
Edge-Detect (Sobel)	edge-sobel	work in progress	untested	Yes	untested
Emboss	emboss	work in progress	untested	No	untested
Engrave	engrave	Yes	untested	work in progress	untested	Is currently being ported by some students as an university project focused on OpenCL. Results can be expected in 2015.
Erode		Yes	untested	No	untested	Provided by the value-propagate operation
Filmstrip		No	untested	No	untested
Filterpack		No	untested	No	untested
Flame		No	untested	No	untested
Fractal Explorer	fractal-explorer	work in progress	untested	No	untested
Fractal Trace	fractal-trace	work in progress	untested	No	untested
From Webpage			untested			Doesn't need porting
Gaussian blur	gaussian-blur	work in progress	untested	work in progress	untested	https://bugzilla.gnome.org/show_bug.cgi?id=721396
Gfig						Doesn't need porting
GIMPressionist		No	untested	No	untested
Glass Tile	tile-glass	Yes	untested	No	untested
Gradient Flare		No	untested	No	untested
Gradient Map		Yes	untested	No	untested	Ported as a gimp plug-in
Grey	grey	No	untested	Yes	untested	Similar to the Desaturation tool, but without its options
Grid	grid	work in progress	untested	No	untested	Missing intersection option, is it needed ?
Hot		No	untested	No	untested
IFS Fractal		work in progress	untested	No	untested
Illusion	illusion	Yes	Yes	work in progress	untested	Is currently being ported by some students as an university project focused on OpenCL. Results can be expected in 2015.
Image Map		No	untested	No	untested	Deprecated code has to be ported to gegl (GimpDrawable, GimpPixelRgn, ...)
Invert	invert-gamma	No	untested	Yes	untested	The pdb documentation needs to be updated. Apart from that it's done.
iWarp						To be replaced with Warp Transform tool
Jigsaw		No	untested	No	untested
Lens Distortion	lens-distortion	Yes	untested	No	untested
Lens Flare	lens-flare	Yes	Yes	No	untested
Lighting Effects		No	untested	No	untested
Make Seamless	tile-seamless	Yes	untested	No	untested
Maximum RGB						Will be removed without replacement
Maze	maze	Yes	untested	No	untested
Mosaic	mosaic	Yes	untested	No	untested	The GEGL op tries to allocate the whole input.
Motion Blur (circular)	motion-blur-circular	Yes	untested	No	untested	Is allocating the whole input
Motion Blur (linear)	motion-blur-linear	Yes	untested	Yes	untested	Is allocating the whole input
Motion Blur (zoom)	motion-blur-zoom	Yes	untested	No	untested	Is allocating the whole input
Newsprint	newsprint	Yes	untested	No	untested	Reimplementation of scratch of most of the functionality of GIMP's newsprint plug-in with additional color based modulation of halftoned results. More documentation/exampels of this op will appear at https://pippin.gimp.org/spachrotyzer/
NL Filter		No	untested	No	untested
Noise (HSV Noise)	noise-hsv	Yes	untested	Yes	untested	The GEGL implementation is not strictly identical to the legacy one, but similar enough...
Noise (Hurl)	noise-hurl	Yes	Yes	Yes	Yes
Noise (Pick)	noise-pick	Yes	untested	No	untested
Noise (RGB Noise)	noise-rgb	work in progress	untested	No	untested
Noise (Slur)	noise-slur	Yes	untested	No	untested
Noise (Spread)	noise-spread	work in progress	untested	No	untested
Normalize		Yes	untested	No	untested	Provided by the stretch-contrast operation when "keep colors" is checked
Oilify	oilify	work in progress	untested	Yes	untested
Optimize (Difference)		No	untested	No	untested
Optimize (for GIF)		No	untested	No	untested
Pagecurl		No	untested	No	untested
Palette Map		Yes	untested	No	untested
Paper Tile	tile-paper	Yes	untested	No	untested
Photocopy	photocopy	work in progress	untested	No	untested
Pixelize	pixelize	Yes	untested	Yes	untested
Plasma	plasma	Yes	untested	No	untested
Polar Coordinates	polar-coordinates	work in progress	untested	No	untested	Currently renders partially garbage
Qbist		No	untested	No	untested
Rearrange Colormap		Yes	untested	No	untested	Not to be confused with GEGL's 'remap' operation.
Recompose		Yes	untested	No	untested	See compose
Red Eye Removal	red-eye-removal	work in progress	untested	Yes	untested
Retinex		No	untested	No	untested
Ripple	ripple	Yes	untested	No	untested
Rotate Colors	color-rotate	No	untested	No	untested
Sample Colorize		No	untested	No	untested
Screenshot		Yes	untested	No	untested
Selection to Path		Yes	untested	No	untested
Selective Gaussian Blur	gaussian-blur-selective	Yes	untested	Yes	untested
Set Colormap		Yes	untested	No	untested	Not to be confused with GEGL's 'remap' operation.
Shift	shift	Yes	Yes	No	untested
Sinus	sinus	Yes	untested	No	untested
Smooth Palette		work in progress	untested	Yes	untested	See https://bugzilla.gnome.org/show_bug.cgi?id=774807 and https://bugzilla.gnome.org/show_bug.cgi?id=749220
Softglow	softglow	Yes	untested	No	untested	Also it uses a different intensity function (Y' instead of (max(R', G', B') + min (R', G', B')) / 2). I suggest the new behaviour is better.
Solid Noise	noise-solid	Yes	untested	No	untested
Sparkle	sparkle	work in progress	untested	work in progress	untested	Is currently being ported by some students as an university project focused on OpenCL. Results can be expected in 2015.
Sphere Designer		No	untested	No	untested
Stretch Contrast	stretch-contrast	Yes	Yes	Yes	Yes
Stretch HSV	stretch-contrast-hsv	Yes	Yes	No	untested
Supernova	supernova	Yes	untested	No	untested
Tile	tile	Yes	untested	No	untested	Kept as a gimp plug-in to resize drawables or create new image ; use gegl:tile operation internally.
Unoptimize		No	untested	No	untested
Unsharp Mask	unsharp-mask	work in progress	untested	No	untested
Value Invert	value-invert	work in progress	untested	Yes	untested
Value Propagate	value-propagate	Yes	untested	No	untested
Van Gogh (LIC)		No	untested	No	untested	The filter has nothing to do with van-Gogh-style art and has no obvious function. We should remove it.
Video	video-degradation	Yes	untested	Yes	untested
Waves	waves	work in progress	untested	No	untested	Missing reflective option that produce strange result, I suggest dropping that.
Whirl and Pinch	whirl-pinch	work in progress	untested	No	untested
Wind	wind	Yes	untested	No	untested
Zealous Crop	N/A	Yes	untested	No	untested	Zealous Crop can't be performed as a GEGL operation because get_bounding_box depends on the image content. It was ported as a gimp plugin instead.

Display filters

Display filter	GEGL port	Test result	OpenCL version	Test result	Comment
Color deficient vision	work in progress	untested	No	untested
Color management	work in progress	untested	No	untested
Color proof	work in progress	untested	No	untested
Contrast	work in progress	untested	No	untested
Gamma	work in progress	untested	No	untested

Port of new GEGL ops to OpenCL

GEGL operation	OpenCL version	Test result	Comment
Bilateral filter	Yes	untested
Box blur	Yes	untested
Box max	Yes	untested	GEGL op is work in progress.
Box min	Yes	untested	GEGL op is work in progress.
Box percentile	No	untested	GEGL op is work in progress.
Brightness and Contrast	Yes	untested
Buffer cache	No	untested	GEGL op is work in progress. Does this need an OpenCL port?
C2g	Yes	untested	HDR related
Cell Noise	Yes	untested
Checkerboard	Yes	untested
Cielch Noise	No	untested
Color	No	untested
Color Reduction	No	untested
Color Temperature	Yes	untested
Contrast Curve	work in progress	untested
Demosaic (bimedian)	No	untested	GEGL op is work in progress.
Demosaic (simple)	No	untested	GEGL op is work in progress.
Disc percentile	No	untested	GEGL op is work in progress.
Display	No	untested	Does this need an OpenCL port?
Ditto	No	untested	GEGL op is work in progress. Test op - does this need an OpenCL port?
Exp combine	No	untested	HDR related
Exposure	No	untested	HDR related
Fattal02	No	untested	HDR related
gluas	No	untested	GEGL op is work in progress. Does this need an OpenCL port?
Gnomonic projection	No	untested
HStack	No	untested	GEGL op is work in progress.
Hue-Chroma	Yes	untested
Image compare	No	untested
Ink simulator	No	untested
Introspect	No	untested	Does this need an OpenCL port?
Kuwahara	No	untested	GEGL op is work in progress.
Lens correction	No	untested	GEGL op is work in progress.
Line profile	No	untested	GEGL op is work in progress.
Linear gradient	No	untested	GEGL op is work in progress.
Mandelbrot	No	untested	GEGL op is work in progress.
Mantiuk06	No	untested	HDR related
Mirrors	No	untested
Mono mixer	Yes	untested
Noise	No	untested	Perlin noise generator
Noise Reduction	Yes	untested
Over	No	untested	Porter Duff operation over (d = cA + cB * (1 - aA))
Radial gradient	No	untested	GEGL op is work in progress.
Reinhard05	Yes	untested	HDR related
Remap	No	untested
Shadows-Highlights	Yes	untested
SNN (mean)	Yes	untested
SNN (percentile)	No	untested	GEGL op is work in progress.
Stereographic projection	No	untested
SVG Hue rotate	No	untested
SVG Luminance to Alpha	No	untested
SVG Matrix	No	untested
SVG Saturate	No	untested
Unpremul	No	untested	GEGL op is work in progress.
Vignette	Yes	untested
Weighted Blend	Yes	untested