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 ();
}
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. |
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.
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.
Arguments:
n_operations_p | return location for number of operations. |
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);
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. |
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);
Create a new graph that can contain further processing nodes.
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. |
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);
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. |
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 |
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. |
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.
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);
valist version of gegl_node_set
Arguments:
node | a GeglNode |
first_property_name | name of the first property to set |
args | value for the first property, followed optionally by more name/value pairs, followed by 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);
valist version of gegl_node_get
Arguments:
node | a GeglNode |
first_property_name | name of the first property to get. |
args | return location for the first property, followed optionally by more name/value pairs, followed by 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.
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. |
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 to handle such cases.
(gegl_node_adopt_child is deprecated, and will be removed in a future release)
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 |
Removes a child from a GeglNode. The reference previously held will be dropped so increase the reference count before removing when reparenting a child between two graphs.
Arguments:
graph | a GeglNode (graph) |
child | a GeglNode. |
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.
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 |
Arguments:
node | the node to lookup a paramspec on |
property_name | the name of the property to get a paramspec for. |
Arguments:
node | a GeglNode |
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. |
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. |
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. |
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. |
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.
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. |
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 |
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.
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. |
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. |
Arguments:
node | a GeglNode |
path_root | filesystem path to construct relative paths from. |
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.
Arguments:
node | a GeglNode |
rectangle | the GeglRectangle to work on or NULL to work on all available data. |
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. |
Do an iteration of work for the processor.
Arguments:
processor | a GeglProcessor |
progress | a location to store the (estimated) percentage complete. |
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);
"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)
Construct a GEGL node, connecting it to needed input nodes. The returned node does not have a parent but a single reference it is meant to be passed to gegl_graph () for gegl_graph () to assume its ownership. This is syntactic sugar for use from C, similar conveniences can easily be built externally in other languages.
gegl_node(op_type, [key, value, [...]], NULL, [input, [aux]])
Arguments:
op_type | the type of operation to create |
first_property_name | |
... |
Creates a GeglNode containing a free floating graph constructed using gegl_node(). The GeglGraph adopts all the passed in nodes making it sufficient to unref the resulting graph.
gegl_graph (gegl_node ("gegl:over", NULL, gegl_node (..), gegl_node (..)));
Arguments:
node | the end result of a composition created with gegl_node() |
GEGL version information
These macros tell the version of GEGL you are compiling against. GEGL's version number consists of three parts: major, minor and micro.
#define GEGL_MAJOR_VERSION 0 #define GEGL_MINOR_VERSION 1 #define GEGL_MICRO_VERSION 1
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 |
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.
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 empty 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. |
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. |
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. |
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. |
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 |
Create a new sub GeglBuffer, that is a view on a larger buffer.
Arguments:
buffer | parent buffer. |
extent | coordinates of new 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. |
Arguments:
buffer | the buffer to operate on. |
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 buffer's extent are at the moment undefined.
Arguments:
buffer | the buffer to operate on. |
extent | new extent. |
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. |
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. |
Clears the provided rectangular region by setting all the associated memory to 0
Arguments:
buffer | a GeglBuffer |
roi | a rectangular region |
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. |
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. |
Query interpolate pixel values at a given coordinate using a specified form of interpolation. The samplers used cache for a small neighbourhood of the buffer for more efficient access.
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 lead 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, GEGL_INTERPOLATON_CUBIC and GEGL_INTERPOLATION_LANCZOS. |
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 |
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 |
Creates a GeglBuffer backed by a linear memory buffer, of the given extent in the specified format. babl_format ("R'G'B'A u8") for instance to make a normal 8bit buffer.
Arguments:
extent | dimensions of buffer. |
format | desired pixel format. |
Creates a GeglBuffer backed by a linear memory buffer that already exists, of the given extent in the specified format. babl_format ("R'G'B'A u8") for instance to make a normal 8bit buffer.
Arguments:
data | a pointer to a linear buffer in memory. |
format | the format of the data in memory |
extent | the dimensions (and upper left coordinates) of linear buffer. |
rowstride | the number of bytes between rowstarts in memory (or 0 to autodetect) |
destroy_fn | function to call to free data or NULL if memory should not be freed. |
destroy_fn_data | extra argument to be passed to void destroy(ptr, data) type function. |
Raw direct random access to the full data of a buffer in linear memory.
Arguments:
buffer | a GeglBuffer. |
extent | region to open, pass NULL for entire buffer. |
rowstride | return location for rowstride. |
format | desired format or NULL to use buffers format. |
This function makes sure GeglBuffer and underlying code is aware of changes being made to the linear buffer. If the request was not a compatible one it is written back to the buffer. Multiple concurrent users can be handed the same buffer (both raw access and converted).
Arguments:
buffer | a GeglBuffer. |
linear | a previously returned buffer. |
Return the abyss extent of a buffer, this expands out to the parents extent in subbuffers.
Arguments:
buffer | a GeglBuffer. |
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; };
Sets the x, y, width and height on rectangle.
Arguments:
rectangle | a GeglRectangle |
x | upper left x coordinate |
y | upper left y coordinate |
width | width in pixels. |
height | height in pixels. |
Check if two GeglRectangles are equal.
Arguments:
rectangle1 | a GeglRectangle |
rectangle2 | a GeglRectangle |
Check if a rectangle is equal to a set of parameters.
Arguments:
rectangle | a GeglRectangle |
x | X coordinate |
y | Y coordinate |
width | width of rectangle |
height | height of rectangle |
Copies the rectangle information stored in source over the information in destination.
Arguments:
destination | a GeglRectangle |
source | a GeglRectangle |
Computes the bounding box of the rectangles source1 and source2 and stores the resulting bounding box in destination.
Arguments:
destination | a GeglRectangle |
source1 | a GeglRectangle |
source2 | a GeglRectangle |
Calculates the intersection of two rectangles. It is allows for dest to be the same as either src1 or src2. If the rectangles do not intersect, dest's width and height are set to 0 and its x and y values are undefined.
Arguments:
dest | return location for the intersection of src1 and src2, or NULL. |
src1 | a GeglRectangle |
src2 | a GeglRectangle |
Checks if the GeglRectangle child is fully contained within parent.
Arguments:
parent | a GeglRectangle |
child | a GeglRectangle |
Arguments:
rectangle | A GeglRectangle. |
For debugging purposes, not stable API.
Arguments:
rectangle | A GeglRectangle. |
Aligned memory
GEGL provides functions to allocate and free buffers that are guaranteed to be on 16 byte aligned memory addresses.
Allocates n_bytes of memory. If n_bytes is 0 it returns NULL.
Arguments:
n_bytes | the number of bytes to allocte. |
Frees the memory pointed to by mem, if mem is NULL it will warn and abort.
Arguments:
mem | the memory to free. |
GeglColor
GeglColor is an object containing a color at the moment only RGB colors are supported, in the future a GeglColor might also indicate other enumerated or natively in other color representations colors.
Retrieves the current set color as linear light non premultipled RGBA data, any of the return pointers can be omitted.
Arguments:
color | a GeglColor |
red | red return location. |
green | green return location. |
blue | blue return location. |
alpha | alpha return location. |
GeglMatrix
GeglMatrix a 3x3 matrix for GEGL represented by the structure: Matrixes are currently used by GeglPath and the affine operations, they might be used more centrally in the core of GEGL later.
typedef gdouble GeglMatrix3 [3][3];
Arguments:
matrix | a GeglMatrix |
Multiples product = left ยท right
Arguments:
left | a GeglMatrix |
right | a GeglMatrix |
product | a GeglMatrix to store the result in. |
Arguments:
matrix | a GeglMatrix |
x | x coordinate of new origin |
y | y coordinate of new origin. Hmm not quite sure what this does. |
Arguments:
matrix | a GeglMatrix |
x | pointer to an x coordinate |
y | pointer to an y coordinate transforms the coordinates provided in x and y and changes to the coordinates gotten when the transformed with the matrix. |
Parse a transofmation matrix from a string.
Arguments:
matrix | a GeglMatrix |
string | a string describing the matrix (right now a small subset of the transform strings allowed by SVG) |
GeglPath
GeglPath is GEGLs means of storing the nodes and other knots and the instructions for rendering 2d paths like poly lines, bezier curves and other curve representations.
A GeglPathItem contains the type of instruction to perform as well as it's arguments. In the public API the PathItem always has 4 points internally only the needed amount of memory is stored for a GeglPathItem.
typedef struct Point { gfloat x; gfloat y; } Point;
typedef struct GeglPathItem { gchar type; Point point[4]; } GeglPathItem;
Creates a new GeglPath with the nodes described in the string instructions. See gegl_path_parse_string() for details of the format of the string.
Arguments:
instructions | a string describing the path. |
Retrieve the node of the path at positiong pos.
Arguments:
path | a GeglPath |
index | the node number to retrieve |
node | a pointer to a GeglPathItem record to be written. |
Set the matrix of the path, the path is thransformed through this matrix when being evaluated. Causing the calcuated positions and length to be changed by the transform.
Arguments:
path | a GeglPath |
matrix | a GeglMatrix3 |
Retrieve the node of the path at positiong pos.
Return value: pointer to the node of the path at position pos or NULL if no such node.
Arguments:
path | a GeglPath |
matrix | a GeglMatrix3 |
Figure out what and where on a path is closest to arbitrary coordinates.
Arguments:
path | a GeglPath |
x | x coordinate. |
y | y coordinate |
on_path_x | return location for x coordinate on the path that was closest |
on_path_y | return location for y coordinate on the path that was closest |
node_pos_before | the node position interpreted before this position was deemed the closest coordinate. |
Compute the coordinates of the path at the position (length measured from start of path, not including discontinuities).
Arguments:
path | a GeglPath |
pos | how far along the path. |
x | return location for x coordinate. |
y | return locateion for y coordinate |
Copmute num_samples for a path into the provided arrays xs and ys the returned values include the start and end positions of the path.
Arguments:
path | a GeglPath |
num_samples | number of samples to compute |
xs | return location for x coordinates |
ys | return location for y coordinates |
Compute the bounding box of a path.
Arguments:
self | a GeglPath. |
min_x | return location for minimum x coordinate |
max_x | return location for maximum x coordinate |
min_y | return location for minimum y coordinate |
max_y | return location for maximum y coordinate |
Execute a provided function for every node in the path (useful for drawing and otherwise traversing a path.)
Arguments:
path | a GeglPath |
each_item | a function to call for each node in the path. |
user_data | user data to pass to the function (in addition to the GeglPathItem). |
Execute a provided function for the segments of a poly line approximating the path.
Arguments:
path | a GeglPath |
each_item | a function to call for each node in the path. |
user_data | user data to pass to a node. |
Insert the new node node at position pos in path.
Arguments:
path | a GeglPath |
pos | the position we want the new node to have. |
node | pointer to a structure describing the GeglPathItem we want to store |
Replaces the exiting node at position pos in path.
Arguments:
path | a GeglPath |
pos | the position we want the new node to have. |
node | pointer to a structure describing the GeglPathItem we want to store. |
Make the GeglPath stop firing signals as it changes must be paired with a gegl_path_thaw() for the signals to start again.
Arguments:
path | a GeglPath |
Restart firing signals (unless the path has been frozen multiple times).
Arguments:
path | a GeglPath |
Adds a new type to the path system, FIXME this should probably return something on registration conflicts, for now it expects all registered paths to be aware of each other.
Arguments:
type | a gchar to recognize in path descriptions. |
items | the number of floating point data items the instruction takes |
description | a human readable description of this entry |
GeglCurve
GeglCurve is a curve describing a unique mapping of values.
Used for things like the curves widget in gimp it is a form of doodle alpha.
Get the bounds on the values of the curve and store the values in the return locaitons provided in min_y and max_y.
Arguments:
curve | a GeglCurve. |
min_y | return location for minimal value. |
max_y | return location for maximal value. |
Compute a set (lookup table) of coordinates.
Arguments:
curve | a GeglCurve. |
x_min | the minimum value to compute for |
x_max | the maxmimum value to compute for |
num_samples | number of samples to calculate |
xs | return location for the x coordinates |
ys | return location for the y coordinates |