GEGL API

The GEGL API

This document is both a tutorial and a reference for the C API of GEGL. The concepts covered in this reference should also be applicable when using other languages.

The core API of GEGL isn't frozen yet and feedback regarding its use as well as the clarity of this documentation is most welcome.

Introduction

Algorithms created with GEGL are expressed as graphs of nodes. The nodes have associated image processing operations. A node has output and input pads which can be connected. By connecting these nodes in chains a set of image operation filters and combinators can be applied to the image data.

To make GEGL process data you request a rectangular region of a node's output pad to be rendered into a provided linear buffer of any (supported by babl) pixel format. GEGL uses information provided by the nodes to determine the smallest buffers needed at each stage of processing.

Initialization

Before GEGL can be used the engine should be initialized by either calling gegl_init or through the use of gegl_get_option_group. To shut down the GEGL engine call gegl_exit.

#include <gegl.h>

int main(int argc, char **argv)
{
  gegl_init (&argc, &argv);
      # other GEGL code
  gegl_exit ();
}

void

gegl_init

(gint *

argc,

gchar ***

argv)

Call this function before using any other GEGL functions. It will initialize everything needed to operate GEGL and parses some standard command line options. argc and argv are adjusted accordingly so your own code will never see those standard arguments. gegl_init() will call g_thread_init(), unless you, or some other code already has initialized gthread.

Note that there is an alternative way to initialize GEGL: if you are calling g_option_context_parse() with the option group returned by gegl_get_option_group(), you don't have to call gegl_init() but you have to call g_thread_init() before any glib or glib dependant code yourself.

Arguments:

argc	a pointer to the number of command line arguments.
argv	a pointer to the array of command line arguments.

GOptionGroup *

gegl_get_option_group

(void)

Returns a GOptionGroup for the commandline arguments recognized by GEGL. You should add this group to your GOptionContext with g_option_context_add_group() if you are using g_option_context_parse() to parse your commandline arguments.

void

gegl_exit

(void)

Call this function when you're done using GEGL. It will clean up caches and write/dump debug information if the correct debug flags are set.

void

gegl_get_version

(int *

major,

int *

minor,

int *

micro)

This function fetches the version of the GEGL library being used by the running process.

Arguments:

major	a pointer to a int where the major version number will be stored
minor	ditto for the minor version number
micro	ditto for the micro version number

Available operations

Gegl provides means to check for available processing operations that can be used with nodes using gegl_list_operations and for a specified op give a list of properties with gegl_list_properties.

gchar **

gegl_list_operations

(guint *

n_operations_p)

Arguments:

n_operations_p

return location for number of operations.

Returns an alphabetically sorted array of available operation names. The list should be freed with g_free after use.

gchar **operations;
guint   n_operations;
gint i;

operations = gegl_list_operations (&n_operations);
g_print ("Available operations:\n");
for (i=0; i < n_operations; i++)
  {
    g_print ("\t%s\n", operations[i]);
  }
g_free (operations);

GParamSpec**

gegl_list_properties

(const gchar *

operation_type,

guint *

n_properties_p)

Arguments:

operation_type	the name of the operation type we want to query to properties of.
n_properties_p	return location for number of properties.

Returns an allocated array of GParamSpecs describing the properties of the operation available when a node has operation_type set.

GeglNode

The Node is the image processing primitive connected to create compositions in GEGL. The toplevel GeglNode which contains a graph of GeglNodes is created with gegl_node_new. Using this toplevel node we can create children of this node which are individual processing elements using gegl_node_new_child

A node either has an associated operation or is a parent for other nodes, that are connected to their parent through proxies created with gegl_node_get_input_proxy and gegl_node_get_output_proxy.

The properties available on a node depends on which operation is specified.

GeglNode *gegl, *load, *bcontrast;

gegl = gegl_node_new ();
load = gegl_node_new_child (gegl,
                            "operation", "load",
                            "path",      "input.png",
                            NULL);
bcontrast = gegl_node_new_child (gegl,
                                 "operation", "brightness-contrast",
                                 "brightness", 0.2,
                                 "contrast",   1.5,
                                 NULL);

GeglNode *

gegl_node_new

(void)

Create a new graph that can contain further processing nodes.

Returns a new top level GeglNode (which can be used as a graph). When you are done using this graph instance it should be unreferenced with g_object_unref. This will also free any sub nodes created from this node.

GeglNode *

gegl_node_new_child

(GeglNode *

parent,

const gchar *

first_property_name,

..., NULL)

Creates a new processing node that performs the specified operation with a NULL terminated list of key/value pairs for initial parameter values configuring the operation. Usually the first pair should be "operation" and the type of operation to be associated. If no operation is provided the node doesn't have an initial operation and can be used to construct a subgraph with special middle-man routing nodes created with gegl_node_get_output_proxy and gegl_node_get_input_proxy.

Arguments:

parent	a GeglNode
first_property_name	the first property name
...	first property value, optionally followed by more key/value pairs, ended terminated with NULL.

Returns a newly created node. The node will be destroyed by the parent. Calling g_object_unref on a node will cause the node to be dropped by the parent. (You may also add additional references using g_object_ref/g_object_unref, but in general relying on the parents reference counting is easiest.)

Making connections

Nodes in GEGL are connected to each other. The resulting graph of nodes represents the image processing pipeline to be processed.

gegl_node_link_many (background, over, png_save, NULL);
gegl_node_connect_to (translate, "output", over, "aux");
gegl_node_link_many (text, blur, translate, NULL);

gboolean

gegl_node_connect_from

(GeglNode *

sink,

const gchar *

input_pad_name,

GeglNode *

source,

const gchar *

output_pad_name)

Makes a connection between the pads of two nodes.

Arguments:

sink	the node we're connecting an input to
input_pad_name	the name of the input pad we are connecting to
source	the node producing data we want to connect.
output_pad_name	the output pad we want to use on the source.

Returns TRUE if the connection was succesfully made.

gboolean

gegl_node_connect_to

(GeglNode *

source,

const gchar *

output_pad_name,

GeglNode *

sink,

const gchar *

input_pad_name)

Makes a connection between the pads of two nodes.

Arguments:

source	the node producing data we want to connect.
output_pad_name	the output pad we want to use on the source.
sink	the node we're connecting an input to
input_pad_name	the name of the input pad we are connecting to

Returns TRUE if the connection was succesfully made.

void

gegl_node_link

(GeglNode *

source,

GeglNode *

sink)

Synthetic sugar for linking the "output" pad of source to the "input" pad of sink.

Arguments:

source	the producer of data.
sink	the consumer of data.

void

gegl_node_link_many

(GeglNode *

source,

GeglNode *

first_sink,

..., NULL)

Synthetic sugar for linking a chain of nodes with "input"->"output". The list is NULL terminated.

Arguments:

source	the producer of data.
first_sink	the first consumer of data.
...	NULL, or optionally more consumers followed by NULL.

gboolean

gegl_node_disconnect

(GeglNode *

node,

const gchar *

input_pad)

Disconnects node connected to input_pad of node (if any).

Arguments:

node	a GeglNode
input_pad	the input pad to disconnect.

Returns TRUE if a connection was broken.

Properties

Properties can be set either when creating the node with gegl_node_new_child as well as later when changing the initial value with gegl_node_set.

To see what properties are available for a given operation look in the Operations reference or use gegl_node_get.

void

gegl_node_set

(GeglNode *

node,

const gchar *

first_property_name,

..., NULL)

Set properties on a node, possible properties to be set are the properties of the currently set operations as well as "name" and "operation". "operation" changes the current operations set for the node, "name" doesn't have any role internally in GEGL.

Arguments:

node	a GeglNode
first_property_name	name of the first property to set
...	value for the first property, followed optionally by more name/value pairs, followed by NULL.

gegl_node_set (node, "brightness", -0.2,
                     "contrast",   2.0,
                     NULL);

void

gegl_node_get

(GeglNode *

node,

const gchar *

first_property_name,

..., NULL)

Gets properties of a GeglNode.

Arguments:

node	a GeglNode
first_property_name	name of the first property to get.
...	return location for the first property, followed optionally by more name/value pairs, followed by NULL.

double level;
char  *path;

gegl_node_get (png_save, "path", &path, NULL);
gegl_node_get (threshold, "level", &level, NULL);

Processing

There are two different ways to do processing with GEGL, either you query any node providing output for a rectangular region to be rendered using gegl_node_blit, or you use gegl_node_process on a sink node (A display node, an image file writer or similar). To do iterative processing you need to use a GeglProcessor. See gegl_processor_work for a code sample.

void

gegl_node_blit

(GeglNode *

node,

gdouble

scale,

const GeglRectangle *

roi,

const Babl *

format,

gpointer

destination_buf,

gint

rowstride,

GeglBlitFlags

flags)

Render a rectangular region from a node.

Arguments:

node	a GeglNode
scale	the scale to render at 1.0 is default, other values changes the width/height of the sampled region.
roi	the rectangle to render from the node, the coordinate system used is coordinates after scale has been applied.
format	the BablFormat desired.
destination_buf	a memory buffer large enough to contain the data, can be left as NULL when forcing a rendering of a region.
rowstride	rowstride in bytes, or GEGL_AUTO_ROWSTRIDE to compute the rowstride based on the width and bytes per pixel for the specified format.
flags	an or'ed combination of GEGL_BLIT_DEFAULT, GEGL_BLIT_CACHE and GEGL_BLIT_DIRTY. if cache is enabled, a cache will be set up for subsequent requests of image data from this node. By passing in GEGL_BLIT_DIRTY the function will return with the latest rendered results in the cache without regard to wheter the regions has been rendered or not.

void

gegl_node_process

(GeglNode *

sink_node)

Render a composition. This can be used for instance on a node with a "png-save" operation to render all neccesary data, and make it be written to file. This function wraps the usage of a GeglProcessor in a single blocking function call. If you need a non-blocking operation, then make a direct use of gegl_processor_work. See GeglProcessor.

Arguments:

sink_node

a GeglNode without outputs.

GeglNode      *gegl;
GeglRectangle  roi;
GeglNode      *png_save;
unsigned char *buffer;

gegl = gegl_parse_xml (xml_data);
roi      = gegl_node_get_bounding_box (gegl);
# create png_save from the graph, the parent/child relationship
# only mean anything when it comes to memory management.
png_save = gegl_node_new_child (gegl,
                                "operation", "png-save",
                                "path",      "output.png",
                                NULL);

gegl_node_link (gegl, png_save);
gegl_node_process (png_save);

buffer = malloc (roi.w*roi.h*4);
gegl_node_blit (gegl,
                &roi,
                1.0,
                babl_format("R'G'B'A u8",
                roi.w*4,
                buffer,
                GEGL_BLIT_DEFAULT);

Reparenting

Sometimes it is useful to be able to move nodes between graphs or even handle orphaned nods that are not part of a graph. gegl_node_adopt_child and gegl_node_get_parent are provided ot handle such cases.

GeglNode *

gegl_node_adopt_child

(GeglNode *

parent,

GeglNode *

child)

Adds child to the responsibilities of node, this makes the parent node take a reference on the child that is kept as long as the parent itself is being referenced. The node is stolen from an existing parent if there is one, or a presumed existing reference is used. If parent is NULL the child will be orphaned and the developer is given a reference to be responsible of.

Arguments:

parent	a GeglNode or NULL.
child	a GeglNode

Returns the child, or NULL if there was a problem with the arguments.

GeglNode *

gegl_node_get_parent

(GeglNode *

node)

Arguments:

node	a GeglNode

Returns a GeglNode that keeps a reference on a child.

Returns the parent of a node or NULL.

State queries

This section lists functions that retrieve information, mostly needed for interacting with a graph in a GUI, not creating one from scratch.

You can figure out what the bounding box of a node is with gegl_node_get_bounding_box, retrieve the values of named properties using gegl_node_get.

GeglNode *

gegl_node_detect

(GeglNode *

node,

gint

x,

gint

y)

Performs hit detection by returning the node providing data at a given coordinate pair. Currently operates only on bounding boxes and not pixel data.

Arguments:

node	a GeglNode
x	x coordinate
y	y coordinate

Returns the GeglNode providing the data ending up at x,y in the output of node.

GParamSpec *

gegl_node_find_property

(GeglNode *

node,

const gchar *

property_name)

Arguments:

node	the node to lookup a paramspec on
property_name	the name of the property to get a paramspec for.

Returns the GParamSpec of property or NULL if no such property exists.

GeglRectangle

gegl_node_get_bounding_box

(GeglNode *

node)

Arguments:

node	a GeglNode

Returns the position and dimensions of a rectangle spanning the area defined by a node.

GSList *

gegl_node_get_children

(GeglNode *

node)

Arguments:

node	the node to retrieve the children of.

Returns a list of nodes with children/internal nodes. The list must be freed by the caller.

gint

gegl_node_get_consumers

(GeglNode *

node,

const gchar *

output_pad,

GeglNode ***

nodes,

const gchar ***

pads)

Retrieve which pads on which nodes are connected to a named output_pad, and the number of connections. Both the location for the generated nodes array and pads array can be left as NULL. If they are non NULL both should be freed with g_free. The arrays are NULL terminated.

Arguments:

node	the node we are querying.
output_pad	the output pad we want to know who uses.
nodes	optional return location for array of nodes.
pads	optional return location for array of pad names.

Returns the number of consumers connected to this output_pad.

GeglNode *

gegl_node_get_input_proxy

(GeglNode *

node,

const gchar *

pad_name)

Proxies are used to route between nodes of a subgraph contained within a node.

Arguments:

node	a GeglNode
pad_name	the name of the pad.

Returns an input proxy for the named pad. If no input proxy exists with this name a new one will be created.

const gchar *

gegl_node_get_operation

(const GeglNode *

node)

Arguments:

node	a GeglNode

Returns the type of processing operation associated with this node, or NULL if there is no op associated. The special name "GraphNode" is returned if the node is the container of a subgraph.

GeglNode *

gegl_node_get_output_proxy

(GeglNode *

node,

const gchar *

pad_name)

Proxies are used to route between nodes of a subgraph contained within a node.

Arguments:

node	a GeglNode
pad_name	the name of the pad.

Returns a output proxy for the named pad. If no output proxy exists with this name a new one will be created.

GeglNode *

gegl_node_get_producer

(GeglNode *

node,

gchar *

input_pad_name,

gchar **

output_pad_name)

Arguments:

node	the node we are querying
input_pad_name	the input pad we want to get the producer for
output_pad_name	optional pointer to a location where we can store a freshly allocated string with the name of the output pad.

Returns the node providing data or NULL if no node is connected to the input_pad.

Binding conveniences

The following functions are mostly included to make it easier to create language bindings for the nodes. The varargs versions will in most cases lead to both more efficient and readable code from C.

GeglNode *

gegl_node_create_child

(GeglNode *

parent,

const gchar *

operation)

Creates a new processing node that performs the specified operation. All properties of the operation will have their default values. This is included as an addiiton to gegl_node_new_child in the public API to have a non varargs entry point for bindings as well as sometimes simpler more readable code.

Arguments:

parent	a GeglNode
operation	the type of node to create.

Returns a newly created node. The node will be destroyed by the parent. Calling g_object_unref on a node will cause the node to be dropped by the parent. (You may also add additional references using g_object_ref/g_object_unref, but in general relying on the parents reference counting is easiest.)

void

gegl_node_get_property

(GeglNode *

node,

const gchar *

property_name,

GValue *

value)

This is mainly included for language bindings. Using gegl_node_get is more convenient when programming in C.

Arguments:

node	the node to get a property from
property_name	the name of the property to get
value	pointer to a GValue where the value of the property should be stored

void

gegl_node_set_property

(GeglNode *

node,

const gchar *

property_name,

const GValue *

value)

This is mainly included for language bindings. Using gegl_node_set is more convenient when programming in C.

Arguments:

node	a GeglNode
property_name	the name of the property to set
value	a GValue containing the value to be set in the property.

XML

The XML format used by GEGL is not stable and should not be relied on for anything but testing purposes yet.

GeglNode *

gegl_node_new_from_xml

(const gchar *

xmldata,

const gchar *

path_root)

The GeglNode returned contains the graph described by the tree of stacks in the XML document. The tree is connected to the "output" pad of the returned node and thus can be used directly for processing.

Arguments:

xmldata	a \0 terminated string containing XML data to be parsed.
path_root	a file system path that relative paths in the XML will be resolved in relation to.

Returns a GeglNode containing the parsed XML as a subgraph.

GeglNode *

gegl_node_new_from_file

(const gchar *

path)

The GeglNode returned contains the graph described by the tree of stacks in the XML document. The tree is connected to the "output" pad of the returned node and thus can be used directly for processing.

Arguments:

path	the path to a file on the local file system to be parsed.

Returns a GeglNode containing the parsed XML as a subgraph.

gchar *

gegl_node_to_xml

(GeglNode *

node,

const gchar *

path_root)

Arguments:

node	a GeglNode
path_root	filesystem path to construct relative paths from.

Returns a freshly allocated \0 terminated string containing a XML serialization of the composition produced by a node (and thus also the nodes contributing data to the specified node). To export a gegl graph, connect the internal output node to an output proxy (see gegl_node_get_output_proxy.) and use the proxy node as the basis for the serialization.

GeglProcessor

A GeglProcessor, is a worker that can be used for background rendering of regions in a node's cache. Or for processing a sink node. For most non GUI tasks using gegl_node_blit and gegl_node_process directly should be sufficient. See gegl_processor_work for a code sample.

GeglProcessor *

gegl_node_new_processor

(GeglNode *

node,

const GeglRectangle *

rectangle)

Arguments:

node	a GeglNode
rectangle	the GeglRectangle to work on or NULL to work on all available data.

Returns a new GeglProcessor.

void

gegl_processor_set_rectangle

(GeglProcessor *

processor,

const GeglRectangle *

rectangle)

Change the rectangle a GeglProcessor is working on.

Arguments:

processor	a GeglProcessor
rectangle	the new GeglRectangle the processor shold work on or NULL to make it work on all data in the buffer.

gboolean

gegl_processor_work

(GeglProcessor *

processor,

gdouble *

progress)

Do an iteration of work for the processor.

Arguments:

processor	a GeglProcessor
progress	a location to store the (estimated) percentage complete.

Returns TRUE if there is more work to be done.

GeglProcessor *processor = gegl_node_new_processor (node, &roi);
double         progress;

while (gegl_processor_work (processor, &progress))
  g_warning ("%f%% complete", progress);
gegl_processor_destroy (processor);

void

gegl_processor_destroy

(GeglProcessor *

processor)

Frees up resources used by a processing handle.

Arguments:

processor

a GeglProcessor

GObject *

gegl_config

(void)

Returns a GObject with properties that can be manipulated to control GEGLs behavior. Properties available on the object are:

"cache-size" "quality" and "swap", the two first is an integer denoting number of bytes, the secons a double value between 0 and 1 and the last the path of the directory to swap to (or "ram" to not use diskbased swap)

GeglRectangle

GeglRectangles are used in gegl_node_get_bounding_box and gegl_node_blit for specifying rectangles.

struct GeglRectangle
 {
   gint x;
   gint y;
   gint width;
   gint height;
 };

GeglBuffer

GeglBuffer is the API used by GEGL for storing and retrieving raster data. GeglBuffer heavily relies on babl for translation and description of different pixel formats.

Internally GeglBuffer currently uses a tiled mipmap pyramid structure that can be swapped to disk. In the future GeglBuffer might also support a linear backend, a GPU memory backend and a network backend for buffers.

GeglBuffer*

gegl_buffer_new

(const GeglRectangle *

extent,

const Babl *

format)

Create a new GeglBuffer of a given format with a given extent. It is possible to pass in NULL for both extent and format, a NULL extent creates an exmpty buffer and a NULL format makes the buffer default to "RGBA float".

Arguments:

extent	the geometry of the buffer (origin, width and height) a GeglRectangle.
format	the Babl pixel format to be used, create one with babl_format("RGBA u8") and similar.

GeglBuffer*

gegl_buffer_open

(const gchar *

path)

Open an existing on-disk GeglBuffer, this buffer is opened in a monitored state so multiple instances of gegl can share the same buffer. Sets on one buffer are reflected in the other.

Arguments:

path	the path to a gegl buffer on disk. be opened.

Returns: a GeglBuffer object.

void

gegl_buffer_save

(GeglBuffer *

buffer,

const gchar *

path,

const GeglRectangle *

roi)

Write a GeglBuffer to a file.

Arguments:

buffer	a GeglBuffer.
path	the path where the gegl buffer will be saved, any writable GIO uri is valid.
roi	the region of interest to write, this is the tiles that will be collected and written to disk.

GeglBuffer *

gegl_buffer_load

(const gchar *

path)

Loads an existing GeglBuffer from disk, if it has previously been saved with gegl_buffer_save it should be possible to open through any GIO transport, buffers that have been used as swap needs random access to be opened.

Arguments:

path	the path to a gegl buffer on disk. be opened.

Returns: a GeglBuffer object.

void

gegl_buffer_flush

(GeglBuffer *

buffer)

Flushes all unsaved data to disk, this is not neccesary for shared geglbuffers opened with gegl_buffer_open since they auto-sync on writes.

Arguments:

buffer

a GeglBuffer

GeglBuffer*

gegl_buffer_create_sub_buffer

(GeglBuffer *

buffer,

const GeglRectangle *

extent)

Create a new sub GeglBuffer, that is a view on a larger buffer.

Arguments:

buffer	parent buffer.
extent	coordinates of new buffer.

void

gegl_buffer_destroy

(GeglBuffer *

buffer)

Destroys a buffer and frees up the resources used by a buffer, internally this is done with reference counting and gobject, and gegl_buffer_destroy is a thin wrapper around g_object_unref.

Arguments:

buffer

the buffer we're done with.

const GeglRectangle *

gegl_buffer_get_extent

(GeglBuffer *

buffer)

Arguments:

buffer

the buffer to operate on.

Returns a pointer to a GeglRectangle structure defining the geometry of a specific GeglBuffer, this is also the default width/height of buffers passed in to gegl_buffer_set and gegl_buffer_get (with a scale of 1.0 at least).

gboolean

gegl_buffer_set_extent

(GeglBuffer *

buffer,

const GeglRectangle *

extent)

Changes the size and position that is considered active in a buffer, this operation is valid on any buffer, reads on subbuffers outside the master buffers extent are at the moment undefined.

Arguments:

buffer	the buffer to operate on.
extent	new extent.

Returns TRUE if the change of extent was succesful.

gegl_buffer_get_x

(

buffer)

Evaluates to the X coordinate of the upper left corner of the buffers extent.

Arguments:

buffer

a GeglBuffer

gegl_buffer_get_y

(

buffer)

Evaluates to the Y coordinate of the upper left corner of the buffers extent.

Arguments:

buffer

a GeglBuffer

gegl_buffer_get_width

(

buffer)

Evaluates to the width of the buffers extent.

Arguments:

buffer

a GeglBuffer

gegl_buffer_get_height

(

buffer)

Evaluates to the height of the buffers extent.

Arguments:

buffer

a GeglBuffer

gegl_buffer_get_pixel_count

(

buffer)

Arguments:

buffer

a GeglBuffer

Returns the number of pixels of the extent of the buffer.

void

gegl_buffer_get

(GeglBuffer *

buffer,

gdouble

scale,

const GeglRectangle *

rect,

const Babl *

format,

gpointer

dest,

gint

rowstride)

Fetch a rectangular linear buffer of pixel data from the GeglBuffer, the data is converted to the desired BablFormat, if the BablFormat stored and fetched is the same this amounts to a series of memcpy's aligned to demux the tile structure into a linear buffer.

Arguments:

buffer	the buffer to retrieve data from.
scale	sampling scale, 1.0 = pixel for pixel 2.0 = magnify, 0.5 scale down.
rect	the coordinates we want to retrieve data from, and width/height of destination buffer, if NULL equal to the extent of the buffer. The coordinates and dimensions are after scale has been applied.
format	the BablFormat to store in the linear buffer dest.
dest	the memory destination for a linear buffer for the pixels, the size needed depends on the requested BablFormat.
rowstride	rowstride in bytes, or GEGL_AUTO_ROWSTRIDE to compute the rowstride based on the width and bytes per pixel for the specified format.

const Babl *

gegl_buffer_set

(GeglBuffer *

buffer,

const GeglRectangle *

rect,

const Babl *

format,

void *

src,

gint

rowstride)

Store a linear raster buffer into the GeglBuffer.

Arguments:

buffer	the buffer to modify.
rect	the coordinates we want to change the data of and the width/height extent, if NULL equal to the extent of the buffer.
format	the babl_format the linear buffer src.
src	linear buffer of image data to be stored in buffer.
rowstride	rowstride in bytes, or GEGL_AUTO_ROWSTRIDE to compute the rowstride based on the width and bytes per pixel for the specified format.

void

gegl_buffer_clear

(GeglBuffer *

buffer,

const GeglRectangle *

roi)

Clears the provided rectangular region by setting all the associated memory to 0

Arguments:

buffer	a GeglBuffer
roi	a rectangular region

void

gegl_buffer_copy

(GeglBuffer *

src,

const GeglRectangle *

src_rect,

GeglBuffer *

dst,

const GeglRectangle *

dst_rect)

copies a region from source buffer to destination buffer.

If the babl_formats of the buffers are the same, and the tile boundaries align, this should optimally lead to shared tiles that are copy on write, this functionality is not implemented yet.

Arguments:

src	source buffer.
src_rect	source rectangle (or NULL to copy entire source buffer)
dst	destination buffer.
dst_rect	position of upper left destination pixel, or NULL for top left coordinates of the buffer extents.

GeglBuffer *

gegl_buffer_dup

(GeglBuffer *

buffer)

duplicate a buffer (internally uses gegl_buffer_copy), this should ideally lead to a buffer that shares the raster data with the original on a tile by tile COW basis. This is not yet implemented

Arguments:

buffer

the GeglBuffer to duplicate.

void

gegl_buffer_sample

(GeglBuffer *

buffer,

gdouble

x,

gdouble

y,

gdouble

scale,

gpointer

dest,

const Babl *

format,

GeglInterpolation

interpolation)

Resample the buffer at some given coordinates using a specified format. For some operations this might be sufficient, but it might be considered prototyping convenience that needs to be optimized away from algorithms using it later.

Arguments:

buffer	the GeglBuffer to sample from
x	x coordinate to sample in buffer coordinates
y	y coordinate to sample in buffer coordinates
scale	the scale we're fetching at (<1.0 can leads to decimation)
dest	buffer capable of storing one pixel in format.
format	the format to store the sampled color in.
interpolation	the interpolation behavior to use, currently only nearest neighbour is implemented for this API, bilinear, bicubic and lanczos needs to be ported from working code. Valid values: GEGL_INTERPOLATION_NEAREST and GEGL_INTERPOLATION_LINEAR, CUBIC and LANCZOS will become available for now they fall back to linear.

void

gegl_buffer_sample_cleanup

(GeglBuffer *

buffer)

Clean up resources used by sampling framework of buffer (will be freed automatically later when the buffer is destroyed, for long lived buffers cleaning up the sampling infrastructure when it has been used for its purpose will sometimes be more efficient).

Arguments:

buffer

the GeglBuffer to sample from

GeglInterpolation

gegl_buffer_interpolation_from_string

(const gchar *

string)

Looks up the GeglInterpolation corresponding to a string, if no matching interpolation is found returns GEGL_INTERPOLATION_NEAREST.

Arguments:

string

the string to look up

GeglOperation

All the image processing code in GEGL is implemented as GeglOperations, GEGL oeprations are implemented as GObject with a convenience API called chanting that abstracts away the boiler plater needed to generate introspectable named properties of different types.

Most types of operations like: filters, composers, sources, sinks, point operations, compositing operations, and spatial operations with fixed neighbourhoods. These base classes builds on top of the GeglOperationsClass:

See gegl-plugin.h for details.

Contents

The GEGL API

Introduction

Initialization

Available operations

GeglNode

Making connections

Properties

Processing

Reparenting

State queries

Binding conveniences

XML

GeglProcessor

GeglRectangle

GeglBuffer

GeglOperation