Contents

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.
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.

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_operation_list_properties.

gchar **
gegl_list_operations
(guint *
n_operations_p)

Return value: (transfer container): An alphabetically sorted array of available operation names. The list should be freed with g_free after use.

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);
gegl_operation_list_properties
(const gchar *
operation_type,
guint *
n_properties_p)

Return value: (transfer container): An allocated array of GParamSpecs describing the properties of the operation available when a node has operation_type set.

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);
gegl_node_new
(void)

Create a new graph that can contain further processing nodes.

Return value: (transfer full): 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.

gegl_node_new_child
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.

Return value: (transfer none): A newly created GeglNode. 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.)

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);
gboolean 
gegl_node_connect_from
sink,
const gchar *
input_pad_name,
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
source,
const gchar *
output_pad_name,
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.
gboolean 
gegl_node_disconnect
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
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_set_valist
node,
const gchar *
first_property_name,
args)

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.
void 
gegl_node_get
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);
void 
gegl_node_get_valist
node,
const gchar *
first_property_name,
args)

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.

void 
gegl_node_blit
node,
gdouble 
scale,
const GeglRectangle *
roi,
const Babl *
format,
gpointer 
destination_buf,
gint 
rowstride,
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
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 to handle such cases.

gegl_node_add_child
graph,
child)

Make the GeglNode graph, take a reference on child. This reference will be dropped when the reference count on the graph reaches zero.

Return value: (transfer none): the child.

Arguments:

graph a GeglNode (graph)
child a GeglNode.
gegl_node_remove_child
graph,
child)

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.

Return value: (transfer none): the child.

Arguments:

graph a GeglNode (graph)
child a GeglNode.
gegl_node_get_parent
node)

Arguments:

node a GeglNode
Returns a GeglNode that keeps a reference on a child.

Return value: (transfer none): 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.

gegl_node_detect
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.

Return value: (transfer none): the GeglNode providing the data ending up at x,y in the output of node.

Arguments:

node a GeglNode
x x coordinate
y y coordinate
gegl_node_find_property
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.
gegl_node_get_bounding_box
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
node)

Return value: (element-type Gegl.Node) (transfer container): a list of the nodes contained within a GeglNode that is a subgraph. Use g_list_free () on the list when done.

Arguments:

node the node to retrieve the children of.
gint 
gegl_node_get_consumers
node,
const gchar *
output_pad,
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.
gegl_node_get_input_proxy
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.
gegl_node_get_output_proxy
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.
gegl_node_get_producer
node,
gchar *
input_pad_name,
gchar **
output_pad_name)

Return value: (transfer none): the node providing data or NULL if no node is connected to the input_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.
gboolean 
gegl_node_has_pad
node,
const gchar *
pad_name)

Arguments:

node the node we are querying
pad_name the pad name we are looking for
Returns TRUE if the node has a pad with the specified name

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.

gegl_node_create_child
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.

Return value: (transfer none):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.)

Arguments:

parent a GeglNode
operation the type of node to create.
void 
gegl_node_get_property
node,
const gchar *
property_name,
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
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.

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.

Return value: (transfer full): a GeglNode containing the parsed XML as a subgraph.

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.
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.

Return value: (transfer full): a GeglNode containing the parsed XML as a subgraph.

Arguments:

path the path to a file on the local file system to be parsed.
gchar *
gegl_node_to_xml
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.

gegl_node_new_processor
node,
const GeglRectangle *
rectangle)

Return value: (transfer full): a new GeglProcessor.

Arguments:

node a GeglNode
rectangle the GeglRectangle to work on or NULL to work on all available data.
void 
gegl_processor_set_rectangle
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
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);
g_object_unref (processor);

GeglConfig

GEGL uses a singleton configuration object

gegl_config
(void)

Returns a GeglConfig object 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)

gegl_node
(const gchar *
op_type,
const gchar *
first_property_name,
..., NULL)

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]])

Return value: (transfer full): a new Gegl node.

Arguments:

op_type the type of operation to create
first_property_name
...
gegl_graph
node)

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 (..)));

Return value: (transfer full):a GeglNode graph.

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 2
#define GEGL_MICRO_VERSION 0
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

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.

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 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.
gegl_buffer_new_for_backend
(const GeglRectangle *
extent,
void *
backend)

Create a new GeglBuffer from a backend, if NULL is passed in the extent of the buffer will be inherited from the extent of the backend.

returns a GeglBuffer, that holds a reference to the provided backend.

Arguments:

extent the geometry of the buffer (origin, width and height) a GeglRectangle.
backend an instance of a GeglTileBackend subclass.
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.
Returns: a GeglBuffer object.
void 
gegl_buffer_save
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.
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.
Returns: a GeglBuffer object.
void 
gegl_buffer_flush
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
gegl_buffer_create_sub_buffer
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.
const GeglRectangle *
gegl_buffer_get_extent
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
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 buffer's 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 buffer's extent.

Arguments:

buffer a GeglBuffer
gegl_buffer_get_y
(
buffer)

Evaluates to the Y coordinate of the upper left corner of the buffer's extent.

Arguments:

buffer a GeglBuffer
gegl_buffer_get_width
(
buffer)

Evaluates to the width of the buffer's extent.

Arguments:

buffer a GeglBuffer
gegl_buffer_get_height
(
buffer)

Evaluates to the height of the buffer's 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
buffer,
const GeglRectangle *
rect,
gdouble 
scale,
const Babl *
format,
gpointer 
dest,
gint 
rowstride,
repeat_mode)

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.
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.
scale sampling scale, 1.0 = pixel for pixel 2.0 = magnify, 0.5 scale down.
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.
repeat_mode how request outside the buffer extent are handled. Valid values: GEGL_ABYSS_NONE
void 
gegl_buffer_set
buffer,
const GeglRectangle *
rect,
gint 
scale_level,
const Babl *
format,
const 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 of the linear buffer being set, scale specifies the scaling factor applied to the data when setting.
scale_level1 = default = base mipmap level, 1 = 1:2, 2=1:4, 3=1:8 ..
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_set_color
buffer,
const GeglRectangle *
rect,
color)

Sets the region covered by rect to the specified color.

Arguments:

buffer a GeglBuffer
rect a rectangular region to fill with a color.
color the GeglColor to fill with.
void 
gegl_buffer_set_pattern
buffer,
const GeglRectangle *
rect,
pattern,
gdouble 
x_offset,
gdouble 
y_offset)

Fill a region with a repeating pattern.

Arguments:

buffer a GeglBuffer
rect a rectangular region
pattern a GeglBuffer to be repeated as a pattern
x_offset where the pattern starts horizontally
y_offset where the pattern starts vertical
const Babl *
gegl_buffer_get_format
buffer)

Get the babl format of the buffer, this might not be the format the buffer was originally created with, you need to use gegl_buffer_set_format (buf, NULL); to retireve the original format (potentially having save away the original format of the buffer to re-set it.)

Arguments:

buffer a GeglBuffer
Returns: the babl format used for storing pixels in the buffer.

const Babl *
gegl_buffer_set_format
buffer,
const Babl *
format)

Set the babl format of the buffer, setting the babl format of the buffer requires the new format to have exactly the same bytes per pixel as the original format. If NULL is passed in the format of the buffer is reset to the original format.

Arguments:

buffer a GeglBuffer
format the new babl format, must have same bpp as original format.
Returns: the new babl format or NULL if it the passed in buffer was incompatible (then the original format is still used).
void 
gegl_buffer_clear
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
src,
const GeglRectangle *
src_rect,
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.
gegl_buffer_dup
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
buffer,
gdouble 
x,
gdouble 
y,
scale,
gpointer 
dest,
const Babl *
format,
sampler_type,
repeat_mode)

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 a matrix that indicates scaling factors, see gegl_sampler_compute_scale the same.
dest buffer capable of storing one pixel in format.
format the format to store the sampled color in.
sampler_type the sampler type to use, to be ported from working code. Valid values: GEGL_SAMPLER_NEAREST, GEGL_SAMPLER_LINEAR, GEGL_SAMPLER_CUBIC and GEGL_SAMPLER_LOHALO
repeat_mode how request outside the buffer extent are handled. valid values: GEGL_ABYSS_NONE
void 
gegl_buffer_sample_cleanup
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
gegl_sampler_type_from_string
(const gchar *
string)

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

Arguments:

string the string to look up
gegl_buffer_sampler_new
buffer,
const Babl *
format,
sampler_type)

Create a new sampler, when you are done with the sampler, g_object_unref it.

Arguments:

buffer buffer to create a new sampler for
format format we want data back in
sampler_type the sampler type to use, to be ported from working code. Valid values: GEGL_SAMPLER_NEAREST, GEGL_SAMPLER_LINEAR, GEGL_SAMPLER_CUBIC and GEGL_SAMPLER_LOHALO
void 
gegl_sampler_get
sampler,
gdouble 
x,
gdouble 
y,
scale,
void *
output,
repeat_mode)

Perform a sampling with the provided sampler.

Arguments:

sampler a GeglSampler gotten from gegl_buffer_sampler_new
x x coordinate to sample
y y coordinate to sample
scale matrix representing extent of sampling area in source buffer.
output memory location for output data.
repeat_mode how request outside the buffer extent are handled. valid values: GEGL_ABYSS_NONE
const GeglRectangle *
gegl_sampler_get_context_rect
sampler)

Arguments:

sampler a GeglSampler gotten from gegl_buffer_sampler_new
Returns:The context rectangle of the given sampler.
gegl_buffer_linear_new
(const GeglRectangle *
extent,
const Babl *
format)

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.
Returns: a GeglBuffer that can be used as any other GeglBuffer.
gegl_buffer_linear_new_from_data
(const gpointer
data,
const Babl *
format,
const GeglRectangle *
extent,
gint 
rowstride,
destroy_fn,
gpointer 
destroy_fn_data)

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.
Returns: a GeglBuffer that can be used as any other GeglBuffer.
gpointer *
gegl_buffer_linear_open
buffer,
const GeglRectangle *
extent,
gint *
rowstride,
const Babl *
format)

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.
Returns: a pointer to a linear memory region describing the buffer, if the request is compatible with the underlying data storage direct access to the underlying data is provided.
void 
gegl_buffer_linear_close
buffer,
gpointer 
linear)

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.
const GeglRectangle *
gegl_buffer_get_abyss
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;
 };

void 
gegl_rectangle_set
rectangle,
gint 
x,
gint 
y,
guint 
width,
guint 
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.
gboolean 
gegl_rectangle_equal
(const GeglRectangle *
rectangle1,
const GeglRectangle *
rectangle2)

Check if two GeglRectangles are equal.

Arguments:

rectangle1 a GeglRectangle
rectangle2 a GeglRectangle
Returns TRUE if rectangle and rectangle2 are equal.
gboolean 
gegl_rectangle_equal_coords
(const GeglRectangle *
rectangle,
gint 
x,
gint 
y,
gint 
width,
gint 
height)

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
Returns TRUE if rectangle and x,y width x height are equal.
gboolean 
gegl_rectangle_is_empty
(const GeglRectangle *
rectangle)

Check if a rectangle has zero area.

Arguments:

rectangle a GeglRectangle
Returns TRUE if rectangle height and width are both zero.
void 
gegl_rectangle_copy
destination,
const GeglRectangle *
source)

Copies the rectangle information stored in source over the information in destination.

Arguments:

destination a GeglRectangle
source a GeglRectangle
void 
gegl_rectangle_bounding_box
destination,
const GeglRectangle *
source1,
const GeglRectangle *
source2)

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
gboolean 
gegl_rectangle_intersect
dest,
const GeglRectangle *
src1,
const GeglRectangle *
src2)

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
Returns TRUE if the rectangles intersect.
gboolean 
gegl_rectangle_contains
(const GeglRectangle *
parent,
const GeglRectangle *
child)

Checks if the GeglRectangle child is fully contained within parent.

Arguments:

parent a GeglRectangle
child a GeglRectangle
Returns TRUE if the child is fully contained in parent.
gegl_rectangle_infinite_plane
(void)

Returns a GeglRectangle that represents an infininte plane.
gboolean 
gegl_rectangle_is_infinite_plane
(const GeglRectangle *
rectangle)

Arguments:

rectangle A GeglRectangle.
Returns TRUE if the GeglRectangle represents an infininte plane, FALSE otherwise.
void 
gegl_rectangle_dump
(const GeglRectangle *
rectangle)

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.

gpointer 
gegl_malloc
n_bytes)

Allocates n_bytes of memory. If n_bytes is 0 it returns NULL.

Arguments:

n_bytes the number of bytes to allocte.
Returns a pointer to the allocated memory.
void 
gegl_free
(gpointer 
mem)

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.

gegl_color_new
(const gchar *
string)

Creates a new GeglColor.

Arguments:

string a string describing the color to be created.
Returns the newly created GeglColor.
void 
gegl_color_get_rgba
color,
gdouble *
red,
gdouble *
green,
gdouble *
blue,
gdouble *
alpha)

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.
void 
gegl_color_set_rgba
color,
gdouble 
red,
gdouble 
green,
gdouble 
blue,
gdouble 
alpha)

Retrieves the current set color as linear light non premultipled RGBA data

Arguments:

color a GeglColor
red red value
green green value
blue blue value
alpha alpha value
void 
gegl_color_set_pixel
color,
const Babl *
format,
const void *
pixel)

Set a GeglColor from a pointer to a pixel and it's babl format.

Arguments:

color a GeglColor
format a babl pixel format
pixel pointer to a pixel
void 
gegl_color_get_pixel
color,
const Babl *
format,
void *
pixel)

Store the color in a pixel in the given format.

Arguments:

color a GeglColor
format a babl pixel format
pixel pointer to a pixel

GeglMatrix3

GeglMatrix3 is a 3x3 matrix for GEGL. Matrixes are currently used by GeglPath and the affine operations, they might be used more centrally in the core of GEGL later.

gegl_matrix3_get_type
(void)

Returns: the GType for GeglMatrix3 objects

gegl_matrix3_new
(void)

Return: A newly allocated GeglMatrix3

void 
gegl_matrix3_identity
matrix)

Set the provided matrix to the identity matrix.

Arguments:

matrix a GeglMatrix
gboolean 
gegl_matrix3_equal
matrix1,
matrix2)

Check if two matrices are equal.

Arguments:

matrix1 a GeglMatrix
matrix2 a GeglMatrix
Returns TRUE if the matrices are equal.
gboolean 
gegl_matrix3_is_identity
matrix)

Check if a matrix is the identity matrix.

Arguments:

matrix a GeglMatrix
Returns TRUE if the matrix is the identity matrix.
gboolean 
gegl_matrix3_is_scale
matrix)

Check if a matrix only does scaling.

Arguments:

matrix a GeglMatrix
Returns TRUE if the matrix only does scaling.
gboolean 
gegl_matrix3_is_translate
matrix)

Check if a matrix only does translation.

Arguments:

matrix a GeglMatrix
Returns TRUE if the matrix only does trasnlation.
void 
gegl_matrix3_copy_into
dst,
src)

Copies the matrix in src into dst.

Arguments:

dst a GeglMatrix
src a GeglMatrix
gegl_matrix3_copy
matrix)

Arguments:

matrix a GeglMatrix
Returns a copy of src.
gdouble 
gegl_matrix3_determinant
matrix)

Arguments:

matrix a GeglMatrix
Returns the determinant for the matrix.
void 
gegl_matrix3_invert
matrix)

Inverts matrix.

Arguments:

matrix a GeglMatrix
void 
gegl_matrix3_multiply
left,
right,
product)

Multiples product = left ยท right

Arguments:

left a GeglMatrix
right a GeglMatrix
product a GeglMatrix to store the result in.
void 
gegl_matrix3_originate
matrix,
gdouble 
x,
gdouble 
y)

Hmm not quite sure what this does.

Arguments:

matrix a GeglMatrix
x x coordinate of new origin
y y coordinate of new origin.
void 
gegl_matrix3_transform_point
matrix,
gdouble *
x,
gdouble *
y)

transforms the coordinates provided in x and y and changes to the coordinates gotten when the transformed with the matrix.

Arguments:

matrix a GeglMatrix
x pointer to an x coordinate
y pointer to an y coordinate
void 
gegl_matrix3_parse_string
matrix,
const gchar *
string)

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)
gchar *
gegl_matrix3_to_string
matrix)

Serialize a GeglMatrix to a string.

Arguments:

matrix a GeglMatrix
Returns a freshly allocated string representing that GeglMatrix, the returned string should be g_free()'d.

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.

GeglPathItem

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 GeglPathPoint
 {
   gfloat x;
   gfloat y;
 } GeglPathPoint;

typedef struct GeglPathItem
 {
   gchar  type;
   GeglPathPoint  point[4];
 } GeglPathItem;

gegl_path_new
(void)

Creates a new GeglPath with no nodes.

Returns the newly created GeglPath
gegl_path_new_from_string
(const gchar *
instructions)

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.
Returns the newly created GeglPath
gboolean 
gegl_path_is_empty
path)

Check if the path contains any nodes.

Arguments:

path a GeglPath
Returns TRUE if the path has no nodes.
gint 
gegl_path_get_n_nodes
path)

Retrieves the number of nodes in the path.

Return value: the number of nodes in the path.

Arguments:

path a GeglPath
gdouble 
gegl_path_get_length
path)

Arguments:

path a GeglPath
Returns the total length of the path.

Return value: the length of the path.

gboolean 
gegl_path_get_node
path,
gint 
index,
node)

Retrieve the node of the path at position pos.

Arguments:

path a GeglPath
index the node number to retrieve
node a pointer to a GeglPathItem record to be written.
Returns TRUE if the node was successfully retrieved.
gchar *
gegl_path_to_string
path)

Serialize the paths nodes to a string.

Return value: return a string with instructions describing the string you need to free this with g_free().

Arguments:

path a GeglPath
void 
gegl_path_set_matrix
path,
matrix)

Set the transformation matrix of the path.

The path is transformed through this matrix when being evaluated, causing the calculated positions and length to be changed by the transform.

Arguments:

path a GeglPath
matrix a GeglMatrix3 to copy the matrix from
void 
gegl_path_get_matrix
path,
matrix)

Get the transformation matrix of the path.

Arguments:

path a GeglPath
matrix a GeglMatrix3 to copy the matrix into
gdouble 
gegl_path_closest_point
path,
gdouble 
x,
gdouble 
y,
gdouble *
on_path_x,
gdouble *
on_path_y,
gint *
node_pos_before)

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.
Returns the length along the path where the closest point was encountered.
gboolean 
gegl_path_calc
path,
gdouble 
pos,
gdouble *
x,
gdouble *
y)

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 location for y coordinate
void 
gegl_path_calc_values
path,
guint 
num_samples,
gdouble *
xs,
gdouble *
ys)

Compute 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
void 
gegl_path_get_bounds
self,
gdouble *
min_x,
gdouble *
max_x,
gdouble *
min_y,
gdouble *
max_y)

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
void 
gegl_path_foreach
path,
each_item,
gpointer 
user_data)

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).
void 
gegl_path_foreach_flat
path,
each_item,
gpointer 
user_data)

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.
void 
gegl_path_clear
path)

Remove all nods from a path.

Arguments:

path a GeglPath
void 
gegl_path_insert_node
path,
gint 
pos,
const GeglPathItem *
node)

Insert the new node node at position pos in path. if pos = -1, the node is added in the last position.

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
void 
gegl_path_replace_node
path,
gint 
pos,
const GeglPathItem *
node)

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.
void 
gegl_path_remove_node
path,
gint 
pos)

Removes the node number pos in path.

Arguments:

path a GeglPath
pos a node in the path.
void 
gegl_path_parse_string
path,
const gchar *
instructions)

Parses instructions and appends corresponding nodes to path (call gegl_path_clean() first if you want to replace the existing path.

Arguments:

path a GeglPath
instructions a string describing a path.
void 
gegl_path_append
path,
..., NULL)

Use as follows: gegl_path_append (path, 'M', 0.0, 0.0); and gegl_path_append (path, 'C', 10.0, 10.0, 50.0, 10.0, 60.0, 0.0) the number of arguments are determined from the instruction provided.

Arguments:

path a GeglPath
... first instruction.
void 
gegl_path_freeze
path)

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
void 
gegl_path_thaw
path)

Restart firing signals (unless the path has been frozen multiple times).

Arguments:

path a GeglPath

GeglPathList

Linked list used internally, and for the plug-in API for new path interpolators.

gegl_path_list_append
head,
..., NULL)

Appends to path list, if head is NULL a new list is created

Arguments:

head a GeglPathList
... additional GeglPathList items to append
gegl_path_list_destroy
path)

Frees up a path list

Arguments:

path A GeglPathList

GeglFlattenerFunc

prototype of function passed to gegl_path_add_flattener()

void 
gegl_path_add_flattener

Add a new flattener, the flattener should produce a type of path that GeglPath already understands, if the flattener is unable to flatten the incoming path (doesn't understand the instructions), the original path should be returned.

Arguments:

func a GeglFlattenerFunc
gegl_path_get_path
path)

Return the internal untouched GeglPathList

Arguments:

path a GeglPath
gegl_path_get_flat_path
path)

Return a polyline version of path

Arguments:

path a GeglPath

GeglPathPoint

void 
gegl_path_point_lerp
dest,
gfloat 
t)

linear interpolation between two GeglPathPoint

Arguments:

dest return location for the result
a origin GeglPathPoint
b destination GeglPathPoint
t ratio between a and b
gdouble 
gegl_path_point_dist

Compute the distance between GeglPathPoint a and b

Arguments:

a an arbitrary GeglPathPoint
b an arbitrary GeglPathPoint

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.

gegl_curve_new
(gdouble 
y_min,
gdouble 
y_max)

Create a GeglCurve that can store a curve with values between y_min and y_max.

Arguments:

y_min minimum y value for curve.
y_max maximum y value for curve.
Returns the newly created GeglCurve.
void 
gegl_curve_get_y_bounds
curve,
gdouble *
min_y,
gdouble *
max_y)

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.
guint 
gegl_curve_add_point
curve,
gdouble 
x,
gdouble 
y)

Add a point to the curve at x y (replacing the value exactly for x if it already exists.

Arguments:

curve a GeglCurve.
x x coordinate
y y coordinate
void 
gegl_curve_get_point
curve,
guint 
index,
gdouble *
x,
gdouble *
y)

Retrive the coordinates for an index.

Arguments:

curve a GeglCurve.
index the position of the value number to retrieve.
x x coordinate return location.
y y coordinate return location.
void 
gegl_curve_set_point
curve,
guint 
index,
gdouble 
x,
gdouble 
y)

Replace an existing point in a curve.

Arguments:

curve a GeglCurve.
index the position of the value number to retrieve.
x x coordinate
y y coordinate
guint 
gegl_curve_num_points
curve)

Retrieve the number of points in the curve.

Arguments:

curve a GeglCurve.
Returns the number of points for the coordinates in the curve.
gdouble 
gegl_curve_calc_value
curve)

Retrieve the number of points in the curve.

Arguments:

curve a GeglCurve.
Returns the number of points for the coordinates in the curve.
void 
gegl_curve_calc_values
curve,
gdouble 
x_min,
gdouble 
x_max,
guint 
num_samples,
gdouble *
xs,
gdouble *
ys)

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