Core Construction APIs

Name

Core Construction APIs -- Core construction API.

Synopsis



            ArtPoint;
enum        ArtPathcode;
            ArtVpath;
            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

ArtPoint

typedef struct {
  double x, y;
} ArtPoint;

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.


ArtVpath

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

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


ArtBpath

typedef struct {
  ArtPathcode code;
  double x1;
  double y1;
  double x2;
  double y2;
  double x3;
  double y3;
} ArtBpath;

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.