The libart library
<<< Previous Page | Home | Up | Next Page >>>

# Core Construction APIs

## Name

Core Construction APIs -- Core construction API.

## Synopsis

    struct      ArtPoint;
    enum        ArtPathcode;
    struct      ArtVpath;
    struct      ArtBpath;
    void        art_vpath_add_point             (ArtVpath **p_vpath,
                                                 int *pn_points,
                                                 int *pn_points_max,
                                                 ArtPathcode code,
                                                 double x,
                                                 double y);
    ArtVpath*   art_bez_path_to_vec             (const ArtBpath *bez,
                                                 double flatness);

## Description

This section details the API for the construction of user-visible data structure, namely: ArtVpath and ArtBpath.

## Details

### struct ArtPoint

    struct ArtPoint {
      /*< public >*/
      double x, y;
    };

This structure is used here and there in the API: there is no general rule about its use. It simply represents a point with its x and y coordinates in the libart 2D space.

The libart 2D space is not a direct cartesian 2D space: it is an indirect cartesian space (that is, its direction is the invert of the standard trigonometric direction). The 2D space used by libart is inspired by the X coordinate space:

Figure 1. LibArt's 2D space

double `x` | the x coordinate of the point.
double `y` | the y cordinate of the point.

### enum ArtPathcode

    typedef enum {
      ART_MOVETO,
      ART_MOVETO_OPEN,
      ART_CURVETO,
      ART_LINETO,
      ART_END
    } ArtPathcode;

This enum contains the list of the possible drawing commands understood by ArtVpath and ArtBpath. These commands are described there. They can be summarized by the folowing figure:

Figure 2. Drawing commands

`ART_MOVETO` | move to a given point, without drawing pixels.
`ART_MOVETO_OPEN` | move to a given point, without drawing pixels. Do not close the vector path at the end.
`ART_CURVETO` | move to a given point along a given bezier path while drawing pixels.
`ART_LINETO` | move to a given point along a staright line while drawing pixels.
`ART_END` | the end of the vector path.

### struct ArtVpath

    struct ArtVpath {
      ArtPathcode code;
      double x;
      double y;
    };

A vector path is an array of `ArtVpath` (short for vector path) data structures. Each of those describes a given vector along the vector path. `ArtVpath`s can contain `ART_MOVETO`, `ART_MOVETO_OPEN`, `ART_LINETO` and `ART_END` commands. Of course, the `x` and `y` members of this data structure have no meaning when `code` is `ART_END`.

ArtPathcode `code` | the drawing command to execute for this vector.
double `x` | the x coordinate of the associated control point.
double `y` | the y coordinate of the associated control point.

### struct ArtBpath

    struct ArtBpath {
      /*< public >*/
      ArtPathcode code;
      double x1;
      double y1;
      double x2;
      double y2;
      double x3;
      double y3;
    };

A vector path can also be an array of `ArtBpath` (short for bézier path) data structures. Bézier paths can hold all the possible drawing commands present in an `ArtPathCode`. XXX: is this true ?

ArtPathcode `code` | the drawing command to execute for this vector.
double `x1` | the x coordinate of the first control point of the bézier path.
double `y1` | the y coordinate of the first control point of the bézier path.
double `x2` | the x coordinate of the second control point of the bézier path.
double `y2` | the xy coordinate of the second control point of the bézier path.
double `x3` | the x coordinate of the end point of the bézier path.
double `y3` | the y coordinate of the end point of the bézier path.

### art_vpath_add_point ()

    void        art_vpath_add_point             (ArtVpath **p_vpath,
                                                 int *pn_points,
                                                 int *pn_points_max,
                                                 ArtPathcode code,
                                                 double x,
                                                 double y);

Adds a new point to *`p_vpath`, reallocating and updating *`p_vpath` and *`pn_points_max` as necessary. *`pn_points` is incremented.

This routine always adds the point after all points already in the vpath. Thus, it should be called in the order the points are desired.

`p_vpath` : | Where the pointer to the ArtVpath structure is stored.
`pn_points` : | Pointer to the number of points in *`p_vpath`.
`pn_points_max` : | Pointer to the number of points allocated.
`code` : | The pathcode for the new point.
`x` : | The X coordinate of the new point.
`y` : | The Y coordinate of the new point.

### art_bez_path_to_vec ()

    ArtVpath*   art_bez_path_to_vec             (const ArtBpath *bez,
                                                 double flatness);

Creates a vector path closely approximating the bezier path defined by `bez`. The `flatness` argument controls the amount of subdivision. In general, the resulting vpath deviates by at most `flatness` pixels from the "ideal" path described by `bez`.

`bez` : | Bezier path.
`flatness` : | Flatness control.
Returns : | Newly allocated vpath.

<<< Previous Page | Home | Up | Next Page >>>
Construction APIs | Extended Construction APIs