diff options
| -rw-r--r-- | docs/Makefile.am | 6 | ||||
| -rw-r--r-- | docs/bugzilla.txt | 14 | ||||
| -rw-r--r-- | docs/build.txt | 52 | ||||
| -rw-r--r-- | docs/commandline.txt | 49 | ||||
| -rw-r--r-- | docs/copyright.txt | 18 | ||||
| -rw-r--r-- | docs/environment.txt | 37 | ||||
| -rw-r--r-- | docs/features.txt | 39 | ||||
| -rw-r--r-- | docs/gegl.css | 6 | ||||
| -rw-r--r-- | docs/glossary.txt | 31 | ||||
| -rw-r--r-- | docs/hello-world.txt | 13 | ||||
| -rw-r--r-- | docs/index.txt | 50 | ||||
| -rw-r--r-- | docs/index.txt.in | 507 | ||||
| -rw-r--r-- | docs/operation-api.txt | 68 | ||||
| -rw-r--r-- | docs/source-overview.txt | 63 |
14 files changed, 456 insertions, 497 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index 98b27015..27aebfff 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -14,7 +14,7 @@ sync-txt: txts=ASC_DOC=`for a in *.txt;do echo -n ' '$$a|sed s/txt/html/;done;echo ''`;\ txts=$$txts" #ASC_DOC_HOTPATCH";\ cat Makefile.am | sed "s/ASC\_DOC.*ASC_DOC_HOTPATCH/$$txts/" > /tmp/mktmp; cp /tmp/mktmp Makefile.am; -ASC_DOC= abyss_policy.html contribute.html development.html editor.html index.html journal.html todo.html #ASC_DOC_HOTPATCH +ASC_DOC= abyss_policy.html bugzilla.html build.html commandline.html contribute.html copyright.html development.html editor.html environment.html features.html glossary.html hello-world.html journal.html operation-api.html source-overview.html todo.html #ASC_DOC_HOTPATCH HTML_FILES = \ @@ -201,7 +201,7 @@ if HAVE_DOT endif endif -%.html: %.txt \ +%.html: %.txt $<\ $(top_srcdir)/AUTHORS \ gegl.css \ $(top_srcdir)/NEWS \ @@ -210,7 +210,7 @@ endif Makefile.am if HAVE_ASCIIDOC @echo "HTML: $@" - $(ASCIIDOC) --unsafe -o $@ -a stylesheet=`pwd`/gegl.css -a toc -a quirks! $< + $(ASCIIDOC) --unsafe -o $@ -a stylesheet=`pwd`/gegl.css -a quirks! $< else @echo "*** asciidoc must be available in order to make dist" @false diff --git a/docs/bugzilla.txt b/docs/bugzilla.txt new file mode 100644 index 00000000..ef0daad3 --- /dev/null +++ b/docs/bugzilla.txt @@ -0,0 +1,14 @@ +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] diff --git a/docs/build.txt b/docs/build.txt new file mode 100644 index 00000000..62865561 --- /dev/null +++ b/docs/build.txt @@ -0,0 +1,52 @@ +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 diff --git a/docs/commandline.txt b/docs/commandline.txt new file mode 100644 index 00000000..1530df0b --- /dev/null +++ b/docs/commandline.txt @@ -0,0 +1,49 @@ +//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. + +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'] +------- + + diff --git a/docs/copyright.txt b/docs/copyright.txt new file mode 100644 index 00000000..bf3c8bca --- /dev/null +++ b/docs/copyright.txt @@ -0,0 +1,18 @@ +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[] + diff --git a/docs/environment.txt b/docs/environment.txt new file mode 100644 index 00000000..5bfd5ee0 --- /dev/null +++ b/docs/environment.txt @@ -0,0 +1,37 @@ +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. diff --git a/docs/features.txt b/docs/features.txt new file mode 100644 index 00000000..276324e3 --- /dev/null +++ b/docs/features.txt @@ -0,0 +1,39 @@ +Functionality Overview +---------------------- + + - Floating point handling and processing and output of larger 8bit, 16bit + integer and 32bit floating point per component buffers larger than RAM. + + - C based, object oriented API with introspection support for dynamic + languages like python, ruby, javascript and php. + + - 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#cat_math[Arithmetic operations] + * link:operations.html#cat_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) diff --git a/docs/gegl.css b/docs/gegl.css index beadc4e3..867cfc2d 100644 --- a/docs/gegl.css +++ b/docs/gegl.css @@ -196,15 +196,15 @@ div#toc { background-color: #333; - position: absolute; - position: fixed; + /*position: absolute; + position: fixed;*/ width: 12em; top: 0; right: 0; z-index: 2; height: 100%; overflow: auto; - float: left; + float: right; padding-top: 0.5em; } div#toc ul { diff --git a/docs/glossary.txt b/docs/glossary.txt new file mode 100644 index 00000000..142a2dd4 --- /dev/null +++ b/docs/glossary.txt @@ -0,0 +1,31 @@ +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. +sampler:: + A resampling strategy used for transformations and warps. +property:: + Properties are what controls the behavior of operations. Through the use of + GParamSpecs properties they are self documenting via introspection. diff --git a/docs/hello-world.txt b/docs/hello-world.txt new file mode 100644 index 00000000..13d2aa30 --- /dev/null +++ b/docs/hello-world.txt @@ -0,0 +1,13 @@ +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] +--------------------------- + diff --git a/docs/index.txt b/docs/index.txt new file mode 100644 index 00000000..6fceca6f --- /dev/null +++ b/docs/index.txt @@ -0,0 +1,50 @@ +GEGL-0.2.1 +=========== + +[[gegl]] +GEGL +---- + +image::images/GEGL.png[GEGL] + +link:operations.html[operations reference] +link:api.html[public API reference] + +*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'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. + +News +~~~~ +This website was built at the time of the previous GEGL tarball release and +is a snapshot of a corresponding documentation build. 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. + +GEGL development is discussed on IRC in #gegl (and sometimes in #gimp) on +GIMPnet (irc.gimp.org). + +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[]. + +++++++++ +<div id='fnord'>fnord</div> +++++++++ diff --git a/docs/index.txt.in b/docs/index.txt.in index 88621df4..07fb3a6b 100644 --- a/docs/index.txt.in +++ b/docs/index.txt.in @@ -1,64 +1,31 @@ GEGL-@GEGL_VERSION@ =========== - [[gegl]] GEGL ---- image::images/GEGL.png[GEGL] +link:operations.html[operations reference] +link:api.html[public API reference] + *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. +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. -[[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#cat_math[Arithmetic operations] - * link:operations.html#cat_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) +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. 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: +This website was built at the time of the previous GEGL tarball release and +is a snapshot of a corresponding documentation build. 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. @@ -69,25 +36,8 @@ http://bugzilla.gnome.org/buglist.cgi?product=GEGL&bug_status=NEW&bug_status=ASS http://blog.gmane.org/gmane.comp.video.gegl.devel?set_blog_all=yes[mail]:: The mailinglist archives for some discussion and announcement. - -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 -~~~~~~~~~ +GEGL development is discussed on IRC in #gegl (and sometimes in #gimp) on +GIMPnet (irc.gimp.org). You can subscribe to gegl-developer and view the archives http://mail.gnome.org/mailman/listinfo/gegl-developer-list[here]. The GEGL @@ -95,431 +45,6 @@ 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. - -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. - │ ├──transform 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. - │ - ├──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="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="https://mail.gnome.org/archives/gegl-developer-list/">mailarchive</a></div> -<div class="toclevel2"><a href="http://git.gnome.org/cgit/gegl/log/">browse online</a></div> - - - -</div> +<div id='fnord'>fnord</div> ++++++++ diff --git a/docs/operation-api.txt b/docs/operation-api.txt new file mode 100644 index 00000000..a7d3a339 --- /dev/null +++ b/docs/operation-api.txt @@ -0,0 +1,68 @@ +GEGL 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. diff --git a/docs/source-overview.txt b/docs/source-overview.txt new file mode 100644 index 00000000..baa90413 --- /dev/null +++ b/docs/source-overview.txt @@ -0,0 +1,63 @@ +Source 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. + │ ├──transform 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. + │ + ├──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. |