# Path contruction functions.

## Data Structures
struct | hpgs_path_point_st
| A point in a stored path. More...
struct | hpgs_paint_path_st
| A stored vector path. More...
struct | hpgs_bezier_length_st
| A structure for holding intermediate values for length calculations of a bezier spline. More...
## Defines
#define | HPGS_POINT_ROLE_MASK 0xF
| A mask for retrieving the role of a point in the path.
#define | HPGS_POINT_UNDEFINED 0x0
| point is undefined
#define | HPGS_POINT_LINE 0x1
| start of line
#define | HPGS_POINT_BEZIER 0x2
| start of bezier curve
#define | HPGS_POINT_CONTROL 0x3
| bezier control point
#define | HPGS_POINT_FILL_LINE 0x4
| line fill only (implicit closepath)
#define | HPGS_POINT_DOT 0x8
| indicates a moveto/lineto with the same coordinates at the start of a subpath.
#define | HPGS_POINT_SUBPATH_START 0x10
| a subpath starts at this point
#define | HPGS_POINT_SUBPATH_END 0x20
| a subpath ends at this point
#define | HPGS_POINT_SUBPATH_CLOSE 0x40
| indicates an explicit closepath at the end of a subpath
#define | HPGS_BEZIER_NSEGS 16
## Typedefs
typedef struct hpgs_path_point_st | hpgs_path_point
typedef struct hpgs_paint_path_st | hpgs_paint_path
typedef struct hpgs_bezier_length_st | hpgs_bezier_length
## Functions
HPGS_API hpgs_paint_path * | hpgs_new_paint_path (void)
HPGS_API void | hpgs_paint_path_destroy (hpgs_paint_path *_this)
HPGS_API void | hpgs_paint_path_truncate (hpgs_paint_path *_this)
HPGS_API int | hpgs_paint_path_moveto (hpgs_paint_path *_this, const hpgs_point *p)
HPGS_API int | hpgs_paint_path_lineto (hpgs_paint_path *_this, const hpgs_point *p)
HPGS_API int | hpgs_paint_path_curveto (hpgs_paint_path *_this, const hpgs_point *p1, const hpgs_point *p2, const hpgs_point *p3)
HPGS_API int | hpgs_paint_path_closepath (hpgs_paint_path *_this)
HPGS_API int | hpgs_paint_path_buldgeto (hpgs_paint_path *_this, const hpgs_point *p, double buldge)
HPGS_API hpgs_paint_path * | hpgs_paint_path_stroke_path (const hpgs_paint_path *_this, const hpgs_gstate *gstate)
HPGS_API hpgs_paint_path * | hpgs_paint_path_decompose_dashes (const hpgs_paint_path *_this, const hpgs_gstate *gstate)
HPGS_API double | hpgs_bezier_path_x (const hpgs_paint_path *path, int i, double t)
HPGS_API double | hpgs_bezier_path_y (const hpgs_paint_path *path, int i, double t)
HPGS_API double | hpgs_bezier_path_delta_x (const hpgs_paint_path *path, int i, double t)
HPGS_API double | hpgs_bezier_path_delta_y (const hpgs_paint_path *path, int i, double t)
HPGS_API double | hpgs_bezier_path_xmin (const hpgs_paint_path *path, int i)
HPGS_API double | hpgs_bezier_path_xmax (const hpgs_paint_path *path, int i)
HPGS_API double | hpgs_bezier_path_ymin (const hpgs_paint_path *path, int i)
HPGS_API double | hpgs_bezier_path_ymax (const hpgs_paint_path *path, int i)
HPGS_API void | hpgs_bezier_path_point (const hpgs_paint_path *path, int i, double t, hpgs_point *p)
HPGS_API void | hpgs_bezier_path_delta (const hpgs_paint_path *path, int i, double t, hpgs_point *p)
HPGS_API void | hpgs_bezier_path_tangent (const hpgs_paint_path *path, int i, double t, int orientation, double ytol, hpgs_point *p)
HPGS_API void | hpgs_bezier_path_singularities (const hpgs_paint_path *path, int i, double t0, double t1, int *nx, double *tx)
HPGS_API void | hpgs_bezier_path_to_quadratic (const hpgs_paint_path *path, int i, double t0, double t1, int *nx, hpgs_point *points)
HPGS_INTERNAL_API void | hpgs_bezier_length_init (hpgs_bezier_length *b, const hpgs_paint_path *path, int i)
HPGS_INTERNAL_API double | hpgs_bezier_length_param (const hpgs_bezier_length *b, double l)

## Detailed Description

This module contains the documentation of the path contruction layer of the vector renderer `hpgs_paint_device`.

The dcomumentation of `hpgs_paint_path_st` explains the most important parts of this module.

## Function Documentation

HPGS_INTERNAL_API void hpgs_bezier_length_init | ( | hpgs_bezier_length * | b,
|  | const hpgs_paint_path * | path,
|  | int | i |
| ) |  |  |

Calculates the curve lengths at an equidistant grid of curve parmeters by na numerical quadrature.

You must call this subroutine before using `hpgs_bezier_length_param`.

References hpgs_bezier_length_st::dl, and hpgs_bezier_length_st::l.

HPGS_INTERNAL_API double hpgs_bezier_length_param | ( | const hpgs_bezier_length * | b,
|  | double | l |
| ) |  |  |

Returns the curve parameter at the bezier curve `b` corresponding to a curve length `l`.

You must have called `hpgs_bezier_length_init` before using this function.

References hpgs_bezier_length_st::dl, and hpgs_bezier_length_st::l.

HPGS_API void hpgs_bezier_path_delta | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t,
|  | hpgs_point * | p |
| ) |  |  |

Calculates the derivation of the bezier curve starting at point `i` of `path` at curve parameter `t`.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

Referenced by hpgs_bezier_path_tangent().

HPGS_API double hpgs_bezier_path_delta_x | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t |
| ) |  |  |

Calculates the derivation of the bezier curve starting at point `i` of `path` at curve parameter `t`.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::x.

HPGS_API double hpgs_bezier_path_delta_y | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t |
| ) |  |  |

Calculates the derivation of the bezier curve starting at point `i` of `path` at curve parameter `t`.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::y.

HPGS_API void hpgs_bezier_path_point | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t,
|  | hpgs_point * | p |
| ) |  |  |

Calculates the point on the bezier curve starting at point `i` of `path` at curve parameter `t`.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

Referenced by hpgs_bezier_path_tangent(), and hpgs_bezier_path_to_quadratic().

HPGS_API void hpgs_bezier_path_singularities | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t0,
|  | double | t1,
|  | int * | nx,
|  | double * | tx |
| ) |  |  |

Calculates the singularities of the bezier curve in the parameter interval from `t0` to `t1`.

We calculate points, where the cross product of the first derivative and the second derivative vanishes. These points include points, where the first or second derivative vanishes. Additionally, turning points of the curve are also included.

`tx` is a pointer to an array of at least two double values, in which the position of the singularities is returned.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

HPGS_API void hpgs_bezier_path_tangent | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t,
|  | int | orientation,
|  | double | ytol,
|  | hpgs_point * | p |
| ) |  |  |

Calculates the tangent to the bezier curve starting at point `i` of `path` at curve parameter `t`.

If `orientation` is `1`, the tangent is calculated with increasing curve parameter, if we meet a singularity (right tangent).

If `orientation` is `-1`, the tangent is calculated with decreasing curve parameter, if we meet a singularity (left tangent).

If `orientation` is `0`, the tangent is calculated with decreased and increased curve parameter, if we meet a singularity (mid tangent).

References hpgs_bezier_path_delta(), hpgs_bezier_path_point(), hpgs_point_st::x, and hpgs_point_st::y.

Referenced by hpgs_bezier_path_to_quadratic().

HPGS_API void hpgs_bezier_path_to_quadratic | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t0,
|  | double | t1,
|  | int * | nx,
|  | hpgs_point * | points |
| ) |  |  |

Approximates the bezier curve segment in the parameter interval from `t0` to `t1` with quadratic bezier splines.

The array `points` is used to return the quadratic bezier segments and must have a dimension of at least 16 points.

`nx` returns the number of generated points, which is always an even number. The first point is the control point of the first quadratic spline, the second point the endpoint of the first quadratic spline and so on.

References hpgs_bezier_path_point(), hpgs_bezier_path_tangent(), hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

HPGS_API double hpgs_bezier_path_x | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t |
| ) |  |  |

Calculates the x component of a point on the bezier spline.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::x.

HPGS_API double hpgs_bezier_path_xmax | ( | const hpgs_paint_path * | path,
|  | int | i |
| ) |  |  |

Calculates the maximal x component of all four control points of the bezier spline.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::x.

HPGS_API double hpgs_bezier_path_xmin | ( | const hpgs_paint_path * | path,
|  | int | i |
| ) |  |  |

Calculates the minimal x component of all four control points of the bezier spline.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::x.

HPGS_API double hpgs_bezier_path_y | ( | const hpgs_paint_path * | path,
|  | int | i,
|  | double | t |
| ) |  |  |

Calculates the y component of a point on the bezier spline.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::y.

HPGS_API double hpgs_bezier_path_ymax | ( | const hpgs_paint_path * | path,
|  | int | i |
| ) |  |  |

Calculates the maximal y component of all four control points of the bezier spline.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::y.

HPGS_API double hpgs_bezier_path_ymin | ( | const hpgs_paint_path * | path,
|  | int | i |
| ) |  |  |

Calculates the minimal y component of all four control points of the bezier spline.

References hpgs_path_point_st::p, hpgs_paint_path_st::points, and hpgs_point_st::y.

HPGS_API hpgs_paint_path* hpgs_new_paint_path | ( | void |  | ) |

Returns a new, empty path created on the heap.

Use `hpgs_paint_path_destroy` in order to destroy the returned `hpgs_paint_path` from the heap.

Returns a null pointer, if the system is out of memory.

References hpgs_paint_path_st::bb, hpgs_bbox_null(), hpgs_paint_path_st::last_start, hpgs_paint_path_st::n_points, hpgs_paint_path_st::points, and hpgs_paint_path_st::points_malloc_size.

Referenced by hpgs_new_paint_device(), hpgs_paint_path_decompose_dashes(), and hpgs_paint_path_stroke_path().

HPGS_API int hpgs_paint_path_buldgeto | ( | hpgs_paint_path * | _this,
|  | const hpgs_point * | p,
|  | double | buldge |
| ) |  |  |

Adds a buldged arc segment to the path. Buldge is defined to be `tan`(alpha/4), where `alpha` is the turning angle of the arc.

References hpgs_paint_path_buldgeto(), hpgs_paint_path_curveto(), hpgs_paint_path_st::n_points, hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

Referenced by hpgs_paint_path_buldgeto().

HPGS_API int hpgs_paint_path_closepath | ( | hpgs_paint_path * | _this | ) |

Closes the current subpolygon. If the current point is distinct from the start point of the current subpolygon, a line is drawn from the start point of the current subpolygon to the last point.

References hpgs_path_point_st::flags, HPGS_POINT_LINE, HPGS_POINT_ROLE_MASK, HPGS_POINT_SUBPATH_CLOSE, HPGS_POINT_SUBPATH_END, HPGS_POINT_SUBPATH_START, hpgs_paint_path_st::last_start, hpgs_paint_path_st::n_points, hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

HPGS_API int hpgs_paint_path_curveto | ( | hpgs_paint_path * | _this,
|  | const hpgs_point * | p1,
|  | const hpgs_point * | p2,
|  | const hpgs_point * | p3 |
| ) |  |  |

Adds three new points to the path and mark the last segment as bezier spline.

References hpgs_path_point_st::flags, hpgs_log(), HPGS_POINT_BEZIER, HPGS_POINT_CONTROL, HPGS_POINT_ROLE_MASK, HPGS_POINT_SUBPATH_END, HPGS_POINT_SUBPATH_START, hpgs_paint_path_st::last_start, hpgs_paint_path_st::n_points, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

Referenced by hpgs_paint_path_buldgeto().

HPGS_API hpgs_paint_path* hpgs_paint_path_decompose_dashes | ( | const hpgs_paint_path * | _this,
|  | const hpgs_gstate * | gstate |
| ) |  |  |

Returns a new path on the heap, which represents a path which conists of solid line segments which should be drawn instead of _this, if your output device does not support dashed lines.

Use `hpgs_paint_path_destroy` in order to destroy the returned `hpgs_paint_path` from the heap.

Returns a null pointer, if the system is out of memory.

References hpgs_new_paint_path(), hpgs_paint_path_destroy(), and hpgs_gstate_st::n_dashes.

HPGS_API void hpgs_paint_path_destroy | ( | hpgs_paint_path * | _this | ) |

Destroys a path from the heap.

References hpgs_paint_path_st::points.

Referenced by hpgs_new_paint_device(), hpgs_paint_path_decompose_dashes(), and hpgs_paint_path_stroke_path().

HPGS_API int hpgs_paint_path_lineto | ( | hpgs_paint_path * | _this,
|  | const hpgs_point * | p |
| ) |  |  |

Adds a new point to the path and mark the last segment as line.

References hpgs_path_point_st::flags, hpgs_log(), HPGS_POINT_DOT, HPGS_POINT_LINE, HPGS_POINT_ROLE_MASK, HPGS_POINT_SUBPATH_END, HPGS_POINT_SUBPATH_START, hpgs_paint_path_st::last_start, hpgs_paint_path_st::n_points, hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

HPGS_API int hpgs_paint_path_moveto | ( | hpgs_paint_path * | _this,
|  | const hpgs_point * | p |
| ) |  |  |

Adds a new point to the path. If the path already has some points, the current subpolygon is implicitly closed.

References hpgs_paint_path_st::bb, hpgs_path_point_st::flags, hpgs_bbox_add(), hpgs_log(), HPGS_POINT_DOT, HPGS_POINT_FILL_LINE, HPGS_POINT_ROLE_MASK, HPGS_POINT_SUBPATH_END, HPGS_POINT_SUBPATH_START, hpgs_paint_path_st::last_start, hpgs_paint_path_st::n_points, hpgs_path_point_st::p, hpgs_paint_path_st::points, hpgs_point_st::x, and hpgs_point_st::y.

HPGS_API hpgs_paint_path* hpgs_paint_path_stroke_path | ( | const hpgs_paint_path * | _this,
|  | const hpgs_gstate * | gstate |
| ) |  |  |

Returns a new path on the heap, which represents the extruded border line of `_this`. The setting of `gstate` are applied accordingly.

Use `hpgs_paint_path_destroy` in order to destroy the returned `hpgs_paint_path` from the heap.

Returns a null pointer, if the system is out of memory.

References hpgs_log(), hpgs_new_paint_path(), hpgs_paint_path_destroy(), and hpgs_gstate_st::n_dashes.

HPGS_API void hpgs_paint_path_truncate | ( | hpgs_paint_path * | _this | ) |

Resets the given path to be empty.

References hpgs_paint_path_st::bb, hpgs_bbox_null(), hpgs_paint_path_st::last_start, and hpgs_paint_path_st::n_points.