gegl r2841 - in trunk: . gegl/property-types
- From: ok svn gnome org
- To: svn-commits-list gnome org
- Subject: gegl r2841 - in trunk: . gegl/property-types
- Date: Thu, 1 Jan 2009 17:22:37 +0000 (UTC)
Author: ok
Date: Thu Jan 1 17:22:37 2009
New Revision: 2841
URL: http://svn.gnome.org/viewvc/gegl?rev=2841&view=rev
Log:
* gegl/property-types/gegl-path.h: documented the path API.
* gegl/property-types/gegl-path.c: (gegl_path_stroke): include the
declaration for gegl_path_stroke here as well (rendering code
shouldn't be in this file).
Modified:
trunk/ChangeLog
trunk/gegl/property-types/gegl-path.c
trunk/gegl/property-types/gegl-path.h
Modified: trunk/gegl/property-types/gegl-path.c
==============================================================================
--- trunk/gegl/property-types/gegl-path.c (original)
+++ trunk/gegl/property-types/gegl-path.c Thu Jan 1 17:22:37 2009
@@ -1739,6 +1739,15 @@
gegl_buffer_set (buffer, roi, format, buf, 0);
}
+
+/* XXX: should be removed? */
+void gegl_path_fill (GeglBuffer *buffer,
+ GeglPath *vector,
+ GeglColor *color,
+ gboolean winding);
+
+
+
void gegl_path_fill (GeglBuffer *buffer,
GeglPath *vector,
GeglColor *color,
@@ -1997,6 +2006,15 @@
GeglColor *color,
gdouble linewidth,
gdouble hardness,
+ gdouble opacity);
+
+
+void gegl_path_stroke (GeglBuffer *buffer,
+ const GeglRectangle *clip_rect,
+ GeglPath *vector,
+ GeglColor *color,
+ gdouble linewidth,
+ gdouble hardness,
gdouble opacity)
{
GeglPathPrivate *priv = GEGL_PATH_GET_PRIVATE (vector);
Modified: trunk/gegl/property-types/gegl-path.h
==============================================================================
--- trunk/gegl/property-types/gegl-path.h (original)
+++ trunk/gegl/property-types/gegl-path.h Thu Jan 1 17:22:37 2009
@@ -16,6 +16,14 @@
* Copyright 2007 Ãyvind KolÃs <pippin gimp org>
*/
+/***
+ * 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.
+ */
+
#ifndef __GEGL_PATH_H__
#define __GEGL_PATH_H__
@@ -63,74 +71,292 @@
GType gegl_path_get_type (void) G_GNUC_CONST;
+
+/**
+ * gegl_path_new:
+ *
+ * Creates a new #GeglPath with no nodes.
+ *
+ * Returns the newly created #GeglPath
+ */
GeglPath * gegl_path_new (void);
-GeglPath * gegl_path_new_from_string(const gchar *path_string);
+/**
+ * gegl_path_new_from_string:
+ * @instructions: a string describing the path.
+ *
+ * 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
+ */
+GeglPath * gegl_path_new_from_string(const gchar *instructions);
+
+/**
+ * gegl_path_is_empty:
+ * @path: a #GeglPath
+ *
+ * Check if the path contains any nodes.
+ *
+ * Returns TRUE if the path has no nodes.
+ */
gboolean gegl_path_is_empty (GeglPath *path);
+
+/**
+ * gegl_path_get_n_nodes:
+ * @path: a #GeglPath
+ *
+ * Retrieves the number of nodes in the path.
+ *
+ * Return value: the number of nodes in the path.
+ */
gint gegl_path_get_n_nodes (GeglPath *path);
+
+/**
+ * gegl_path_get_length:
+ * @path: a #GeglPath
+ *
+ * Returns the total length of the path.
+ *
+ * Return value: the length of the path.
+ */
gdouble gegl_path_get_length (GeglPath *path);
+
+/**
+ * gegl_path_get_node:
+ * @path: a #GeglPath
+ * @pos: the node number to retrieve
+ *
+ * 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.
+ */
const GeglPathItem * gegl_path_get_node (GeglPath *path,
gint pos);
+
+/**
+ * gegl_path_to_string:
+ * @path: a #GeglPath
+ *
+ * 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().
+ */
gchar * gegl_path_to_string (GeglPath *path);
-void gegl_path_get_matrix (GeglPath *path,
- GeglMatrix3 matrix);
+
+
+/**
+ * gegl_path_set_matrix:
+ * @path: a #GeglPath
+ * @matrix: a GeglMatrix3
+ *
+ * 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.
+ */
void gegl_path_set_matrix (GeglPath *path,
GeglMatrix3 matrix);
+
+/**
+ * gegl_path_get_matrix:
+ * @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.
+ */
+void gegl_path_get_matrix (GeglPath *path,
+ GeglMatrix3 matrix);
+
+/**
+ * gegl_path_closest_point:
+ * @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.
+ *
+ * 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.
+ */
gdouble gegl_path_closest_point (GeglPath *path,
gdouble x,
gdouble y,
- gdouble *dx,
- gdouble *dy,
+ gdouble *on_path_x,
+ gdouble *on_path_y,
gint *node_pos_before);
+
+/**
+ * gegl_path_calc:
+ * @path: a #GeglPath
+ * @pos: how far along the path.
+ * @x: return location for x coordinate.
+ * @y: return locateion for y coordinate
+ *
+ * Compute the coordinates of the path at the @position (length measured from
+ * start of path, not including discontinuities).
+ */
void gegl_path_calc (GeglPath *path,
gdouble pos,
- gdouble *dest_x,
- gdouble *dest_y);
-void gegl_path_calc_values (GeglPath *self,
+ gdouble *x,
+ gdouble *y);
+
+/**
+ * gegl_path_calc_values:
+ * @path: a #GeglPath
+ * @num_samples: number of samples to compute
+ * @xs: return location for x coordinates
+ * @ys: return location for y coordinates
+ *
+ * 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.
+ */
+void gegl_path_calc_values (GeglPath *path,
guint num_samples,
- gdouble *dest_xs,
- gdouble *dest_ys);
+ gdouble *xs,
+ gdouble *ys);
+
+/**
+ * gegl_path_get_bounds:
+ * @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
+ *
+ * Compute the bounding box of a path.
+ */
void gegl_path_get_bounds (GeglPath *self,
gdouble *min_x,
gdouble *max_x,
gdouble *min_y,
gdouble *max_y);
-void gegl_path_foreach (GeglPath *path,
- void (*each_item) (
- const GeglPathItem *knot,
- gpointer data),
- gpointer data);
-
-/* iterate through only line_to / move_to commands approximating the
- * same path
- */
-void gegl_path_foreach_flat (GeglPath *path,
- void (*each_item) (
- const GeglPathItem *knot,
- gpointer data),
- gpointer data);
+/* XXX: LP and RP are nasty hacks because the GEGL docs code scanner gets
+ * confused, need to be fixed there
+ */
+#define LP (
+#define RP )
+typedef void LP *GeglNodeFunction RP LP const GeglPathItem *node,
+ gpointer user_data RP;
+#undef LP
+#undef RP
+
+/**
+ * gegl_path_foreach:
+ * @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 every node in the path (useful for
+ * drawing and otherwise traversing a path.)
+ */
+void gegl_path_foreach (GeglPath *path,
+ GeglNodeFunction each_item,
+ gpointer user_data);
+
+/**
+ * gegl_path_foreach_flat:
+ * @path: a #GeglPath
+ * @each_item: a function to call for each node in the path.
+ * @user_data: user data to pass to a node.
+ *
+ * Execute a provided function for the segments of a poly line approximating
+ * the path.
+ */
+void gegl_path_foreach_flat (GeglPath *path,
+ GeglNodeFunction each_item,
+ gpointer user_data);
+/**
+ * gegl_path_clear:
+ * @path: a #GeglPath
+ *
+ * Remove all nods from a @path.
+ */
void gegl_path_clear (GeglPath *path);
+
+/**
+ * gegl_path_insert_node:
+ * @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
+ *
+ * Insert the new node @node at position @pos in @path.
+ */
void gegl_path_insert_node (GeglPath *path,
gint pos,
- const GeglPathItem *knot);
+ const GeglPathItem *node);
+/**
+ * gegl_path_replace_node:
+ * @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.
+ */
void gegl_path_replace_node (GeglPath *path,
gint pos,
- const GeglPathItem *knot);
+ const GeglPathItem *node);
+/**
+ * gegl_path_remove_node:
+ * @path: a #GeglPath
+ * @pos: a node in the path.
+ *
+ * Removes the node number @pos in @path.
+ */
void gegl_path_remove_node (GeglPath *path,
gint pos);
+/**
+ * gegl_path_parse_string:
+ * @path: a #GeglPath
+ * @instructions: a string describing a path.
+ *
+ * Parses @instructions and appends corresponding nodes to path (call
+ * gegl_path_clean() first if you want to replace the existing path.
+ */
void gegl_path_parse_string (GeglPath *path,
- const gchar *path_string);
+ const gchar *instructions);
-/* convenience function for C */
-void gegl_path_append (GeglPath *self,
+/**
+ * gegl_path_append:
+ * @path: a #GeglPath
+ * @...: first instruction.
+ *
+ * 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.
+ *
+ */
+void gegl_path_append (GeglPath *path,
...);
+/**
+ * gegl_path_freeze:
+ * @path: a @GeglPath
+ *
+ * Make the @GeglPath stop firing signals as it changes must be paired with a
+ * gegl_path_thaw() for the signals to start again.
+ */
+void gegl_path_freeze (GeglPath *path);
-
+/**
+ * gegl_path_thaw:
+ * @path: a @GeglPath
+ *
+ * Restart firing signals (unless the path has been frozen multiple times).
+ */
+void gegl_path_thaw (GeglPath *path);
GParamSpec * gegl_param_spec_path (const gchar *name,
@@ -144,6 +370,14 @@
GType gegl_param_path_get_type (void) G_GNUC_CONST;
+/* add a new control point type to GeglPath, this new type works in everything
+ * from the _add () functions (number of arguments determined automatically)
+ * to the string parsing and serialization functions.
+ */
+void gegl_path_add_type (gchar type,
+ gint pairs,
+ const gchar *description);
+
/* Linked list used internally, and for the plug-in API for new path
* interpolators.
*/
@@ -159,14 +393,6 @@
GeglPathList * gegl_path_list_destroy (GeglPathList *path);
-/* add a new control point type to GeglPath, this new type works in everything
- * from the _add () functions (number of arguments determined automatically)
- * to the string parsing and serialization functions.
- */
-void gegl_path_add_type (gchar type,
- gint pairs,
- const gchar *description);
-
/* 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
@@ -174,29 +400,9 @@
*/
void gegl_path_add_flattener (GeglPathList *(*func) (GeglPathList *original));
-
-#include <gegl-buffer.h>
-
-/* this can and should be the responsiblity of cairo */
-void gegl_path_fill (GeglBuffer *buffer,
- GeglPath *path,
- GeglColor *color,
- gboolean winding);
-
-/* Stroke the path with a brush having the specified attributes
- * (code from horizon)
- */
-void gegl_path_stroke (GeglBuffer *buffer,
- const GeglRectangle *clip_rect,
- GeglPath *vector,
- GeglColor *color,
- gdouble linewidth,
- gdouble hardness,
- gdouble opacity);
-
-void gegl_path_freeze (GeglPath *path);
-void gegl_path_thaw (GeglPath *path);
-
+/**
+ * foo:
+ */
G_END_DECLS
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
