gegl-path

## gegl-path gegl-path |

## Functions

GeglPath * | gegl_path_new ()
GeglPath * | gegl_path_new_from_string ()
gboolean | gegl_path_is_empty ()
gint | gegl_path_get_n_nodes ()
gdouble | gegl_path_get_length ()
gboolean | gegl_path_get_node ()
gchar * | gegl_path_to_string ()
void | gegl_path_set_matrix ()
void | gegl_path_get_matrix ()
gdouble | gegl_path_closest_point ()
gint | gegl_path_calc_y_for_x ()
gboolean | gegl_path_calc ()
void | gegl_path_calc_values ()
void | gegl_path_get_bounds ()
void | gegl_path_foreach ()
void | gegl_path_foreach_flat ()
void | gegl_path_clear ()
void | gegl_path_insert_node ()
void | gegl_path_replace_node ()
void | gegl_path_remove_node ()
void | gegl_path_parse_string ()
void | gegl_path_append ()
void | gegl_path_freeze ()
void | gegl_path_thaw ()
GParamSpec * | gegl_param_spec_path ()
void | gegl_path_add_type ()
GeglPathList * | gegl_path_list_append ()
GeglPathList * | gegl_path_list_destroy ()
GeglPathList * | (*GeglFlattenerFunc) ()
void | gegl_path_add_flattener ()
GeglPathList * | gegl_path_get_path ()
GeglPathList * | gegl_path_get_flat_path ()
void | gegl_path_point_lerp ()
gdouble | gegl_path_point_dist ()
void | gegl_path_dirty ()

## Types and Values

| GeglPath
#define | LP
#define | RP

## Description

## Functions

### gegl_path_new ()

    GeglPath *
    gegl_path_new (void);

Creates a new GeglPath with no nodes.

Returns the newly created GeglPath

### gegl_path_new_from_string ()

    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.

Returns the newly created GeglPath

#### Parameters

instructions | a string describing the path. |

### gegl_path_is_empty ()

    gboolean
    gegl_path_is_empty (GeglPath *path);

Check if the path contains any nodes.

Returns TRUE if the path has no nodes.

#### Parameters

path | a GeglPath |

### gegl_path_get_n_nodes ()

    gint
    gegl_path_get_n_nodes (GeglPath *path);

Retrieves the number of nodes in the path.

#### Parameters

path | a GeglPath |

#### Returns

the number of nodes in the path.

### gegl_path_get_length ()

    gdouble
    gegl_path_get_length (GeglPath *path);

Returns the total length of the path.

#### Parameters

path | a GeglPath |

#### Returns

the length of the path.

### gegl_path_get_node ()

    gboolean
    gegl_path_get_node (GeglPath *path,
                        gint index,
                        GeglPathItem *node);

Retrieve the node of the path at position `pos` .

Returns TRUE if the node was successfully retrieved.

#### Parameters

path | a GeglPath |
index | the node number to retrieve |
node | a pointer to a GeglPathItem record to be written. | [out]

### gegl_path_to_string ()

    gchar *
    gegl_path_to_string (GeglPath *path);

Serialize the paths nodes to a string.

#### Parameters

path | a GeglPath |

#### Returns

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

### gegl_path_set_matrix ()

    void
    gegl_path_set_matrix (GeglPath *path,
                          GeglMatrix3 *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.

#### Parameters

path | a GeglPath |
matrix | a GeglMatrix3 to copy the matrix from. | [in][transfer none]

### gegl_path_get_matrix ()

    void
    gegl_path_get_matrix (GeglPath *path,
                          GeglMatrix3 *matrix);

Get the transformation matrix of the path.

#### Parameters

path | a GeglPath |
matrix | a GeglMatrix3 to copy the matrix into. | [out caller-allocates]

### gegl_path_closest_point ()

    gdouble
    gegl_path_closest_point (GeglPath *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.

Returns the length along the path where the closest point was encountered.

#### Parameters

path | a GeglPath |
x | x coordinate. |
y | y coordinate |
on_path_x | return location for x coordinate on the path that was closest. | [out]
on_path_y | return location for y coordinate on the path that was closest. | [out]
node_pos_before | the node position interpreted before this position was deemed the closest coordinate. | [out]

### gegl_path_calc_y_for_x ()

    gint
    gegl_path_calc_y_for_x (GeglPath *path,
                            gdouble x,
                            gdouble *y);

Compute a corresponding y coordinate for a given x input coordinate, returns 0 if computed correctly and -1 if the path doesn't exist for the specified x coordinate.

#### Parameters

path | a GeglPath |
x | x coordinate to compute for |
y | return location for y coordinate. | [out]

### gegl_path_calc ()

    gboolean
    gegl_path_calc (GeglPath *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).

#### Parameters

path | a GeglPath |
pos | how far along the path. |
x | return location for x coordinate. | [out]
y | return location for y coordinate. | [out]

### gegl_path_calc_values ()

    void
    gegl_path_calc_values (GeglPath *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.

[skip]

#### Parameters

path | a GeglPath |
num_samples | number of samples to compute |
xs | return location for x coordinates. | [out caller-allocates][array length=num_samples]
ys | return location for y coordinates. | [out caller-allocates][array length=num_samples]

### gegl_path_get_bounds ()

    void
    gegl_path_get_bounds (GeglPath *self,
                          gdouble *min_x,
                          gdouble *max_x,
                          gdouble *min_y,
                          gdouble *max_y);

Compute the bounding box of a path.

#### Parameters

self | a GeglPath. |
min_x | return location for minimum x coordinate. | [out]
max_x | return location for maximum x coordinate. | [out]
min_y | return location for minimum y coordinate. | [out]
max_y | return location for maximum y coordinate. | [out]

### gegl_path_foreach ()

    void
    gegl_path_foreach (GeglPath *path,
                       GeglNodeFunction each_item,
                       gpointer user_data);

Execute a provided function for every node in the path (useful for drawing and otherwise traversing a path.)

#### Parameters

path | a GeglPath |
each_item | a function to call for each node in the path. | [closure user_data][scope call]
user_data | user data to pass to the function (in addition to the GeglPathItem). |

### gegl_path_foreach_flat ()

    void
    gegl_path_foreach_flat (GeglPath *path,
                            GeglNodeFunction each_item,
                            gpointer user_data);

Execute a provided function for the segments of a poly line approximating the path.

#### Parameters

path | a GeglPath |
each_item | a function to call for each node in the path. | [closure user_data][scope call]
user_data | user data to pass to a node. |

### gegl_path_clear ()

    void
    gegl_path_clear (GeglPath *path);

Remove all nods from a `path` .

#### Parameters

path | a GeglPath |

### gegl_path_insert_node ()

    void
    gegl_path_insert_node (GeglPath *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.

#### Parameters

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 |

### gegl_path_replace_node ()

    void
    gegl_path_replace_node (GeglPath *path,
                            gint pos,
                            const GeglPathItem *node);

Replaces the exiting node at position `pos` in `path` .

#### Parameters

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

### gegl_path_remove_node ()

    void
    gegl_path_remove_node (GeglPath *path,
                           gint pos);

Removes the node number `pos` in `path` .

#### Parameters

path | a GeglPath |
pos | a node in the path. |

### gegl_path_parse_string ()

    void
    gegl_path_parse_string (GeglPath *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.

#### Parameters

path | a GeglPath |
instructions | a string describing a path. |

### gegl_path_append ()

    void
    gegl_path_append (GeglPath *path,
                      ...);

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.

#### Parameters

path | a GeglPath |
... | first instruction. |

### gegl_path_freeze ()

    void
    gegl_path_freeze (GeglPath *path);

Make the `GeglPath` stop firing signals as it changes must be paired with a `gegl_path_thaw()` for the signals to start again.

#### Parameters

path | a `GeglPath` |

### gegl_path_thaw ()

    void
    gegl_path_thaw (GeglPath *path);

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

#### Parameters

path | a `GeglPath` |

### gegl_param_spec_path ()

    GParamSpec *
    gegl_param_spec_path (const gchar *name,
                          const gchar *nick,
                          const gchar *blurb,
                          GeglPath *default_path,
                          GParamFlags flags);

Creates a new GParamSpec instance specifying a GeglPath property.

#### Parameters

name | canonical name of the property specified |
nick | nick name for the property specified |
blurb | description of the property specified |
default_path | the default value for the property specified |
flags | flags for the property specified |

#### Returns

a newly created parameter specification.

[transfer full]

### gegl_path_add_type ()

    void
    gegl_path_add_type (gchar type,
                        gint items,
                        const gchar *description);

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.

#### Parameters

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 |

### gegl_path_list_append ()

    GeglPathList *
    gegl_path_list_append (GeglPathList *head,
                           ...);

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

[skip]

#### Parameters

head | a GeglPathList |
... | additional GeglPathList items to append |

### gegl_path_list_destroy ()

    GeglPathList *
    gegl_path_list_destroy (GeglPathList *path);

Frees up a path list

[skip]

#### Parameters

path | A GeglPathList |

### GeglFlattenerFunc ()

    GeglPathList *
    (*GeglFlattenerFunc) (GeglPathList *original);

### gegl_path_add_flattener ()

    void
    gegl_path_add_flattener (GeglFlattenerFunc func);

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.

[skip]

#### Parameters

func | a GeglFlattenerFunc |

### gegl_path_get_path ()

    GeglPathList *
    gegl_path_get_path (GeglPath *path);

Return the internal untouched GeglPathList

[skip]

#### Parameters

path | a GeglPath |

### gegl_path_get_flat_path ()

    GeglPathList *
    gegl_path_get_flat_path (GeglPath *path);

Return a polyline version of `path`

[skip]

#### Parameters

path | a GeglPath |

### gegl_path_point_lerp ()

    void
    gegl_path_point_lerp (GeglPathPoint *dest,
                          GeglPathPoint *a,
                          GeglPathPoint *b,
                          gfloat t);

linear interpolation between two GeglPathPoint

[skip]

#### Parameters

dest | return location for the result |
a | origin GeglPathPoint |
b | destination GeglPathPoint |
t | ratio between `a` and `b` |

### gegl_path_point_dist ()

    gdouble
    gegl_path_point_dist (GeglPathPoint *a,
                          GeglPathPoint *b);

Compute the distance between GeglPathPoint `a` and `b`

[skip]

#### Parameters

a | an arbitrary GeglPathPoint |
b | an arbitrary GeglPathPoint |

### gegl_path_dirty ()

    void
    gegl_path_dirty (GeglPath *path);

Marks the path as dirty and issues an invalidation for the path rendering, use this if modifying the values of a GeglPathPoint inline.

#### Parameters

path | a GeglPath |

## Types and Values

### GeglPath

    typedef struct {
      GObject parent_instance;
    } GeglPath;

### LP

    #define LP (

### RP

    #define RP )