GEGL-@GEGL_VERSION@
===========
[[gegl]]
GEGL
----
image::images/GEGL.png[GEGL]
*GEGL* (Generic Graphics Library) is a graph based image processing framework.
GEGL provides infrastructure to do demand based cached non destructive image
editing on larger than RAM buffers. Through link:http://gegl.org/babl/[babl]
it provides support for a wide range of color models and pixel storage formats
for input and output.
[[features]]
Features
~~~~~~~~
- Floating point handling and processing and output of larger 8bit, 16bit
integer and 32bit floating point per component buffers larger than RAM.
- C, http://gegl.org/gegl-vala[vala], http://gegl.org/gegl-sharp/[C#],
http://gegl.org/pygegl/[Python] and http://gegl.org/rgegl/[Ruby] interfaces
using a consistent DOM like graph API to manage processing graphs.
- Processing
* Iterative chunk-wise processing.
* Processes subregions and dependencies.
* Subgraph caches to aid performance of non-destructive editing.
* Experimental OpenCL acceleration, with possibility of hybrid cpu/gpu
processing.
- link:api.html#GeglBuffer[GeglBuffer]
* Storage of all babl supported formats.
* Tiled sparse buffers (larger than RAM images).
* linear buffers (allocated internally or from external allocation.)
* On demand tiled mipmapping.
* inter process shared storage
* External tile-backends (allow wrapping other tiled buffer systems
to use them through the GeglBuffer API).
- Operations
* PNG, JPEG, SVG, EXR, RAW, ffmpeg, v4l and other image sources.
* link:operations.html#cat_render[Pattern renderers]
* link:operations.html#math[Arithmetic operations]
* link_operations.html#porter_duff[porter duff compositing]
* SVG filter modes and full set of compositing ops from SVG-1.2 draft.
* Gaussian blur, bilateral-filter, symmetric nearest neighbour, linear
* blur, unsharp mask, pixelize and more.
* link:operations.html#cat_color[Color correction].
* Text rendering using cairo and http://pango.org/[pango].
* HDR exposure merging and tone mapping operations.
* Most operations operate in
http://en.wikipedia.org/wiki/ScRGB_color_space[scRGB] (using 32bit
floating point/HDR linear light RGBA)
- Bounding box based hit detection.
- XML serialization format (not-finalized)
News
~~~~
This website is built at the time of the previous GEGL tarball release,
for information about what might change on the way to the next release
follow the following news sources:
http://git.gnome.org/cgit/gegl/log/[Change log]::
For day to day fixes, contributions and changes.
http://git.gnome.org/cgit/gegl/tree/NEWS[NEWS]::
The NEWS file for a list of major new features (also contains older NEWS).
http://bugzilla.gnome.org/buglist.cgi?product=GEGL&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=UNCONFIRMED&bug_status=NEEDINFO[bugzilla]::
for known and tracked issues with GEGL and perhaps see the
http://blog.gmane.org/gmane.comp.video.gegl.devel?set_blog_all=yes[mail]::
The mailinglist archives for some discussion and announcement.
Gallery
~~~~~~~
For examples of what GEGL's rendering engine currently can do look at the
link:gallery/index.html[gallery].
Bugzilla
~~~~~~~~
The GEGL project uses http://bugzilla.gnome.org/[GNOME Bugzilla], a
bug-tracking system that allows us to coordinate bug reports. Bugzilla is also
used for enhancement requests and the preferred way to submit patches for GEGL
is to open a bug report and attach the patch to it. Bugzilla is also the
closest you will find to a roadmap for GEGL.
Below is a list of links to get you started with Bugzilla:
- http://bugzilla.gnome.org/buglist.cgi?product=GEGL&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED[List of Open Bugs]
- http://bugzilla.gnome.org/buglist.cgi?product=GEGL&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial[List of Open Bugs] (excluding enhancement requests)
- http://bugzilla.gnome.org/buglist.cgi?product=GEGL&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=UNCONFIRMED&bug_status=NEEDINFO&bug_severity=enhancement[List of Enhancement Proposals]
- http://bugzilla.gnome.org/reports/weekly-bug-summary.cgi[Bugzilla Weekly Summary]
Community
~~~~~~~~~
You can subscribe to gegl-developer and view the archives
http://mail.gnome.org/mailman/listinfo/gegl-developer-list[here]. The GEGL
developer list is the appopriate place to ask development questions, and get
more information about GEGL development in general. You can email this list at
mailto:gegl-developer-list@gnome.org[].
GEGL development is also discussed in #gegl on GIMPnet (irc.gimp.org).
Copyright
~~~~~~~~~
GEGL is free software; you can redistribute it and/or modify it under the terms
of the link:LGPL[GNU Lesser General Public License] and link:GPL[GNU General
Public License] as published by the Free Software Foundation; either version 3
of the Licenses, or (at your option) any later version. The library itself is
licensed under LGPL while the sample commandline application and GUI binary
gegl is licensed under GPL.
Contributors
~~~~~~~~~~~~
Many people have contributed to GEGL
http://www.ohloh.net/projects/4349/analyses/latest[over time] the following
lists are are ordered chronologically according to when they are mentioned in
the ChangeLog.
include::@top_srcdir@/AUTHORS[]
Building from source
--------------------
GEGL and it's dependencies are known to work on Linux based systems, windows
with msys/mingw, and probably other platforms.
Download
~~~~~~~~
The latest development snapshot, and eventually stable versions of GEGL are
available at ftp://ftp.gimp.org/pub/gegl/[].
The current code under development can be
http://git.gnome.org/cgit/gegl/tree[browsed online] and cloned from
GNOME git using:
$ git clone git://git.gnome.org/babl
$ git clone git://git.gnome.org/gegl
Dependencies
~~~~~~~~~~~~
GEGL currently builds and works on linux, win32 and OSX most probably also on
other systems where glib and gtk+ work.
- Core
* glib (including gobject, and gmodule) 2.16 or newer, which provides
inheritance, dynamic modules, common algorithms and data structures
for C programming.
* http://gegl.org/babl/[babl] 0.0.22 or newer (for pixel-format
agnostisism).
* libpng (png load/export ops, and image magick fallback import)
* ruby (only if building from git)
- GUI (sandbox for testing ops and the API)
* GTK+
- Optional dependencies for operations.
* SDL (display op)
* libjpeg (jpg loader op)
* libopenexr (exr loader op)
* http://freedesktop.org/wiki/Software/libopenraw[libopenraw] (raw
loader op)
* cairo, pango (text source op)
* avcodec, avformat (ff-load and experimental ff-save)
* librsvg (svg loader)
- Documentation (this document)
* asciidoc
Compiling
~~~~~~~~~
To build GEGL type the following in the toplevel source directory:
$ ./configure # or: ./autogen.sh if building from git
$ make
$ sudo make install
Documentation
-------------
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's programmer/user interface is a Directed Acyclic Graph of nodes. The DAG
expresses a processing chain of operations. A DAG, or any node in it, expresses
a composited and processed image. It is possible to request rectangular regions
in a wide range of pixel formats from any node.
Development
-----------
This link:development.html[howto] describes good-to-know things for developing gegl
Public API
~~~~~~~~~~
The link:api.html[public API reference] documents the API used for creating
things with GEGL, this API does not change much at all and is also the API
provided by language bindings. To make the public API available when compiling
a .c file add #include <link:gegl.h.html[gegl.h]>, compile and link with the
flags provided by pkg-config and you should be all set. When you are
comfortable with the public API, or are using GEGL in some project looking at
the link:operations.html[Operation reference] might be useful.
The public API also includes link:api.html#GeglBuffer[GeglBuffer], a flexible
tiled and linear raster buffer storage system.
Bindings
^^^^^^^^
The bindings for use of GEGL in other programming languages than C are
co-hosted with GEGL in GNOME git but are not part of the regular GEGL
distribution. The following language bindings are currently available:
http://gegl.org/gegl-vala[vala], http://gegl.org/gegl-sharp/[C#],
http://gegl.org/pygegl/[Python] and http://gegl.org/rgegl/[Ruby].
Hello world
^^^^^^^^^^^
The following is a small sample GEGL application that animates a zoom on a
mandelbrot fractal. compile it with:
$ gcc hello-world.c `pkg-config --libs --cflags gegl` -o hello-world
This example and others can be found in the examples subdir of the GEGL distribution.
---------------------------
sys::[cat @top_srcdir@/examples/hello-world.c]
---------------------------
Operation API
~~~~~~~~~~~~~
An API to extend the functionality of GEGL with new image processing primitive,
file loaders, export formats or similar.
Each GEGL operation is defined in a .c file that gets turned into a single
shared object that is loaded. Each operation is a subclass of one of the
provided base classes:
link:gegl-operation.h.html[GeglOperation]::
The base operation class, which all the other base classes are derived
from, deriving from this is often quite a bit of work and is encouraged
only when your operation doesn't fit into any of the other categories
link:gegl-operation-filter.h.html[GeglOperationFilter]::
The filter base class sets up GeglBuffers for input and output pads
link:gegl-operation-point-filter.h.html[GeglOperationPointFilter]::
The point-filter base class is for filters where an output pixel only
depends on the color and alpha values of the corresponding input pixel.
This allows you to do the processing on linear buffers, in the future
versions of GEGL operations implemented using the point-filter will get
speed increases due to more intelligent processing possible in the point
filter class
link:gegl-operation-area-filter.h.html[GeglOperationAreaFilter]::
The AreaFilter base class allows defining operations where the output data
depends on a neighbourhood with an input window that extends beyond the
output window, the information about needed extra pixels in different
directions should be set up in the prepare callback for the operation.
link:gegl-operation-composer.h.html[GeglOperationComposer]::
Composer operations are operations that take two inputs named 'input' and
'aux' and write their output to the output pad 'output'
link:gegl-operation-point-composer.h.html[GeglOperationPointComposer]::
A baseclass for composer functions where the output pixels' values depends
only on the values of the single corresponding input and aux pixels.
link:gegl-operation-source.h.html[GeglOperationSource]::
Operations used as render sources or file loaders, the process method
receives a GeglBuffer to write it's output into
link:gegl-operation-point-render.h.html[GeglOperationPointRender]::
The point-render base class is a specialized source operation, where the
render is done in small piece to lower the need to do copies. It's dedicated
to operation which may be rendered in pieces, like pattern generation.
link:gegl-operation-sink.h.html[GeglOperationSink]::
An operation that consumes a GeglBuffer, used for filewriters, display (for
the sdl display node)
link:gegl-operation-temporal.h.html[GeglOperationTemporal]::
Base class for operations that want access to previous frames in a video
sequence, it contains API to configure the amounts of frames to store as
well as getting a GeglBuffer pointing to any of the previously stored
frames.
link:gegl-operation-meta.h.html[GeglOperationMeta]::
Used for GEGL operations that are implemented as a sub-graph, at the moment
these are defined as C files but should in the future be possible to
declare as XML instead.
To create your own operations you should start by looking for one that does
approximatly what you already need. Copy it to a new .c source file, and
replace the occurences of the filename (operation name in the source.)
Take a look at link:brightness-contrast.c.html[the brightness contrast
operation] for a point operation well sprinkled with comments as a starting point.
//XML data model
//~~~~~~~~~~~~~~
//The tree allows clones, making it possible to express any acyclic graph where
//the nodes are all of the types: source, filter and composer.
//
//GEGL can write and reads its data model to and from XML. The XML is chains of
//image processing commands, where some chains allow a child chain (the 'over'
//operator to implement layers for instance).
//
//The type of operation associated with a node can be specified either with a
//class attribute or by using the operation name as the tag name for the node.
//
//or documentation on how this XML works, take a look at the sources in the
//gallery. And browse the documentation for operations.
Environment
~~~~~~~~~~~
Some environment variables can be set to alter how GEGL runs, all of these
options are also available as properties on a singleton GObject returned from
gegl_config ().
GEGL_QUALITY::
A value between 0.0 and 1.0 indicating a trade-off between quality and
speed. Defaults to 1.0 (max quality).
BABL_TOLERANCE::
The amount of error that babl tolerates, set it to for instance 0.1 to use
some conversions that trade some quality for speed.
GEGL_CHUNK_SIZE::
The number of pixels processed simulatnously.
GEGL_TILE_SIZE::
The tile size used internally by GEGL, defaults to 128x64
GEGL_SWAP::
The directory where temporary swap files are written, if not specified GEGL
will not swap to disk. Be aware that swapping to disk is still experimental
and GEGL is currently not removing the per process swap files.
GEGL_CACHE_SIZE::
The size of the tile cache used by GeglBuffer specified in megabytes.
GEGL_DEBUG::
set it to "all" to enable all debugging, more specific domains for
debugging information are also available.
BABL_STATS::
When set babl will write a html file (/tmp/babl-stats.html) containing a
matrix of used conversions, as well as all existing conversions and which
optimized paths are followed.
GEGL_DEBUG_BUFS::
Display tile/buffer leakage statistics.
GEGL_DEBUG_RECTS::
Show the results of have/need rect negotiations.
GEGL_DEBUG_TIME::
Print a performance instrumentation breakdown of GEGL and it's operations.
GEGL_USE_OPENCL:
Enable use of OpenCL processing.
gegl
~~~~
GEGL provides a commandline tool called gegl, for working with the XML data
model from file, stdin or the commandline. It can display the result of
processing the layer tree or save it to file.
Some examples:
Render a composition to a PNG file:
$ gegl composition.xml -o composition.png
Invoke gegl like a viewer for gegl compositions:
$ gegl -ui -d 5 composition.xml
Using gegl with png's passing through stdin/stdout piping.
$ cat input.png | gegl -o - -x "<gegl>
<tree>
<node class='invert'/>
<node class='scale' x='0.5' y='0.5'/>
<node class='png-load' path='-'/></tree></gegl>" > output.png
The latest development version is available in the gegl repository in GNOME
git.
gegl usage
^^^^^^^^^^
The following is the usage information of the gegl binary, this documentation
might not be complete.
-------
sys::[bash -c '../bin/gegl -h 2>&1']
-------
Appendixes
----------
Operations
~~~~~~~~~~
The main source of documentation as GEGL grows is the
link:operations.html[operations reference]. Plug-ins themselves register
information about the categories they belong to, what they do, and
documentation of the available parameters.
Glossary
~~~~~~~~
connection::
A link/pipe routing image flow between operations within the graph goes
from an output pad to an input pad, in graph glossary this might also be
referred to as an edge.
DAG::
Directed Acyclic Graph, see graph.
graph::
A composition of nodes, the graph is a DAG.
node::
The nodes are connected in the graph. A node has an associated operation or
can be constructed graph.
operation::
The processing primitive of GEGL, is where the actual image processing
takes place. Operations are plug-ins and provide the actual functionality
of GEGL
pad::
The part of a node that exchanges image content. The place where image
"pipes" are used to connect the various operations in the composition.
input pad::
consumes image data, might also be seen as an image parameter to the
operation.
output pad::
a place where data can be requested, multiple input pads can reference
the same output pad.
property::
Properties are what controls the behavior of operations. Through the use of
GParamSpecs properties they are self documenting via introspection.
Directory overview
~~~~~~~~~~~~~~~~~~
GEGL dirs
^^^^^^^^^
Directories marked with ⊙ use GNU make extensions to include any .c file
dropped into the directory in the build.
gegl-dist-root
│
│
├──gegl core source of GEGL, library init/deinit,
│ │
│ ├──buffer contains the implementation of GeglBuffer
│ │ - sparse (tiled)
│ │ - recursivly subbuffer extendable
│ │ - clipping rectangle (defaults to bounds when making
│ │ subbuffers)
│ │ - storage in any babl supported pixel format
│ │ - read/write rectangular region as linear buffer for
│ │ any babl supported pixel format.
│ ├──graph graph storage and manipulation code.
│ ├──module The code to load plug-ins located in a colon seperated
│ │ list of paths from the environment variable GEGL_PATH
│ ├──operation The GeglOperation base class, and subclasses that act
│ │ as baseclasses for implementeting different types of
│ │ operation plug-ins.
│ ├──process The code controlling data processing.
│ └──property-types specialized classes/paramspecs for GeglOperation
│ properties.
│
├──examples ⊙ hello-world and other example uses of the GEGL API.
│
├──tests various tests used to maintain stability when developing
│ GEGL.
│
├──operations Runtime loaded plug-ins for image processing operations.
│ │
│ ├──core ⊙ Basic operations tightly coupled with GEGL.
│ ├──affine Transforming operations (rotate/scale/translate)
│ ├──generated ⊙ Operations generated from scripts (currently
│ ├──external Operations with external dependencies.
│ ├──common ⊙ Other operations.
│ └──workshop ⊙ Works in progress, (you must pass --enable-workshop
│ │ when configurig to build these by default, you can enter
│ │ the directory manually and type make && sudo make install
│ │ as well.
│ │
│ ├──external operations in the workshop with external dependencies.
│ └──generated generated operations that are in the workshop.
│
│
├──docs The GEGL website (this documentation), built for your
│ │ the corresponding sourcetree with correct documentation
│ │ etc.
│ │
│ └──gallery ⊙ A gallery of sample GEGL compositions, using the
│ │ (not yet stabilized) XML format.
│ │
│ └──data Image data used by the sample compositions.
│
├──bin gegl binary, for processing XML compositions to png files.
│
├──bindings bindings for using GEGL from other programming languages
│ not included in the tarball distribution but exist in
│ the git repository.
│
└──tools some small utilities to help the build.
++++++++
<div id='toc'>
<div id="toctitle">Table of Contents</div>
<div class="toclevel1"><a href="#gegl">GEGL</a></div>
<div class="toclevel2"><a href="#features">Features</a></div>
<div class="toclevel2"><a href="#_news">News</a></div>
<div class="toclevel2"><a href="gallery/index.html">Gallery</a></div>
<!--<div class="toclevel2"><a href="http://bugzilla.gnome.org/buglist.cgi?product=GEGL&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">Bugzilla</a></div>
<div class="toclevel2"><a href="#_mailinglist">Mailinglist</a></div>-->
<div class="toclevel2"><a href="#_copyright">Copyright</a></div>
<div class="toclevel2"><a href="#_code">Contributors</a></div>
<div class="toclevel2"><a href="contribute.html">Todo</a></div>
<div class="toclevel1"><a href="#_building_from_source">Building from source</a></div>
<div class="toclevel2"><a href="#_download">Download</a></div>
<div class="toclevel2"><a href="#_dependencies">Dependencies</a></div>
<div class="toclevel2"><a href="#_compiling">Compiling</a></div>
<div class="toclevel2"><a href="development.html">Developer notes</a></div>
<div class="toclevel1"><a href="#_documentation_2">Documentation</a></div>
<div class="toclevel2"><a href="operations.html">Operations</a></div>
<div class="toclevel2"><a href="api.html">Public API</a></div>
<div class="toclevel2"><a href="#_operation_api">Operation API</a></div>
<div class="toclevel2"><a href="#_environment">Environment</a></div>
<div class="toclevel2"><a href="#_gegl">gegl</a></div>
<div class="toclevel1"><a href="#_appendixes">Appendixes</a></div>
<div class="toclevel2"><a href="operations.html">Operations</a></div>
<div class="toclevel2"><a href="#_glossary">Glossary</a></div>
<div class="toclevel2"><a href="#_directory_overview">Directory overview</a></div>
<div> </div>
<div class="toclevel1"> </div>
<div class="toclevel2"><a href="http://git.gnome.org/cgit/gegl/log/">changes</a></div>
<div class="toclevel2"><a href="http://bugzilla.gnome.org/buglist.cgi?product=GEGL&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=UNCONFIRMED&bug_status=NEEDINFO">bugzilla</a></div>
<div class="toclevel2"><a href="http://blog.gmane.org/gmane.comp.video.gegl.devel?set_blog_all=yes">mailarchive</a></div>
<div class="toclevel2"><a href="http://git.gnome.org/cgit/gegl/log/">browse online</a></div>
</div>
++++++++