Synopsis

#include <adg-1/adg.h>

cairo_path_t *      (*AdgTrailCallback)                 (AdgTrail *trail,
                                                         gpointer user_data);
struct              AdgTrail;
struct              AdgTrailClass;
AdgTrail *          adg_trail_new                       (AdgTrailCallback callback,
                                                         gpointer user_data);
const cairo_path_t * adg_trail_get_cairo_path           (AdgTrail *trail);
cairo_path_t *      adg_trail_cairo_path                (AdgTrail *trail);
gboolean            adg_trail_put_segment               (AdgTrail *trail,
                                                         guint n_segment,
                                                         CpmlSegment *segment);
const CpmlExtents * adg_trail_get_extents               (AdgTrail *trail);
void                adg_trail_dump                      (AdgTrail *trail);
void                adg_trail_set_max_angle             (AdgTrail *trail,
                                                         gdouble angle);
gdouble             adg_trail_get_max_angle             (AdgTrail *trail);

Object Hierarchy

  GObject
   +----AdgModel
         +----AdgTrail
               +----AdgEdges
               +----AdgPath

Properties

  "max-angle"                gdouble               : Read / Write

Description

The AdgTrail model is a really basic model built around the cairo_path_t struct: for a full fledged path model consider using AdgPath.

A trail is a path model that demands all the implementation details to the caller: this requires a deep knowledge of the ADG details but provides a great customization level. It should be used when an AdgPath is not enough, such as when a model is subject to change dynamically and the global and local maps do not suffice to express this alteration. A typical example is the path used to draw extension lines and base line of AdgLDim: every point is subject to different constrains not expressible with a single affine transformation.

Details

AdgTrailCallback ()

cairo_path_t *      (*AdgTrailCallback)                 (AdgTrail *trail,
                                                         gpointer user_data);

This is the callback used to generate the cairo_path_t and it is called directly by adg_trail_cairo_path(). The caller owns the returned path, that is the finalization of the returned cairo_path_t should be made by the caller when appropriate.

trail :

an AdgTrail

user_data :

the general purpose pointer set by adg_trail_new()

Returns :

the cairo_path_t of this trail model

Since 1.0


struct AdgTrail

struct AdgTrail;

All fields are private and should not be used directly. Use its public methods instead.

Since 1.0


struct AdgTrailClass

struct AdgTrailClass {
    /* Virtual table */
    cairo_path_t *  (*get_cairo_path)           (AdgTrail        *trail);
};

The default get_cairo_path calls the AdgTrailCallback callback passed to adg_trail_new() during construction. No caching is performed in between.

get_cairo_path ()

virtual method to get the cairo_path_t bound to the trail.

Since 1.0


adg_trail_new ()

AdgTrail *          adg_trail_new                       (AdgTrailCallback callback,
                                                         gpointer user_data);

Creates a new trail model. The cairo_path_t must be constructed by the callback function: AdgTrail will not cache anything, so you should implement any caching mechanism in the callback, if needed.

callback :

the cairo_path_t constructor function. [scope notified]

user_data :

generic pointer to pass to the callback

Returns :

a new trail model. [transfer full]

Since 1.0


adg_trail_get_cairo_path ()

const cairo_path_t * adg_trail_get_cairo_path           (AdgTrail *trail);

Gets a pointer to the cairo path of trail. The returned path is owned by trail and must be considered read-only.

This function gets the cairo_path_t of trail by calling adg_trail_cairo_path() and converts its CPML_ARC primitives, not recognized by cairo, into approximated Bézier curves primitives (CPML_CURVE). The conversion is cached, so any further request is O(1). This cache is cleared only by the adg_model_clear() method.

trail :

an AdgTrail

Returns :

a pointer to the internal cairo path or NULL on errors. [transfer none]

Since 1.0


adg_trail_cairo_path ()

cairo_path_t *      adg_trail_cairo_path                (AdgTrail *trail);

Gets the cairo path structure defined by trail. The returned value is managed by the AdgTrail implementation, that is this function directly calls the AdgTrailClass::get_cairo_path() virtual method that any trail instance must have.

Whenever used internally by the ADG project, the returned path is (by convention) owned by trail and so it should not be freed. Anyway, callers are allowed to modify it as long as its size is retained and its data contains a valid path: this is needed to let the AdgMarker infrastructure work properly (the markers should be able to modify the trail where they are applied).

Any further call to this method will probably make the pointer previously returned useless because the cairo_path_t could be relocated and the old cairo_path_t will likely contain rubbish.

trail :

an AdgTrail

Returns :

a pointer to the cairo_path_t or NULL on errors. [transfer none]

Since 1.0


adg_trail_put_segment ()

gboolean            adg_trail_put_segment               (AdgTrail *trail,
                                                         guint n_segment,
                                                         CpmlSegment *segment);

Convenient function to get a segment from trail. The segment is got from the cairo path: check out adg_trail_cairo_path() for further information.

When the segment is not found, either because n_segment is out of range or because there is still no path bound to trail, this function will return FALSE leaving segment untouched. If the segment is found and segment is not NULL, the resulting segment is copied in segment.

trail :

an AdgTrail

n_segment :

the segment to retrieve, where 1 is the first segment

segment :

the destination CpmlSegment

Returns :

TRUE on success or FALSE on errors

Since 1.0


adg_trail_get_extents ()

const CpmlExtents * adg_trail_get_extents               (AdgTrail *trail);

Gets the extents of trail. The returned pointer is owned by trail and should not be freed nor modified.

trail :

an AdgTrail

Returns :

the requested extents or NULL on errors

Since 1.0


adg_trail_dump ()

void                adg_trail_dump                      (AdgTrail *trail);

Dumps the data content of trail to stdout in a human readable format.

trail :

an AdgTrail

Since 1.0


adg_trail_set_max_angle ()

void                adg_trail_set_max_angle             (AdgTrail *trail,
                                                         gdouble angle);

Sets the max angle of trail to angle, basically setting the "max-angle" property.

This property is used to specify the maximum ciruclar arc that will be approximated by a single Bézier curve in the adg_trail_get_cairo_path() method. Basically this can be used to fine tune the fitting algorithm: lower values mean an arc will be approximated with more curves, lowering the error but incrementing time and memory needed. The default value of G_PI_2 is usually good in most cases.

Check the cairo-arc.c source file (part of the cairo project) for mathematical details. A copy can probably be consulted online at the cairo repository on freedesktop. Here is a link to the 1.10.2 version:

http://cgit.freedesktop.org/cairo/tree/src/cairo-arc.c?id=1.10.2

trail :

an AdgTrail

angle :

the new angle (in radians)

Since 1.0


adg_trail_get_max_angle ()

gdouble             adg_trail_get_max_angle             (AdgTrail *trail);

Gets the "max-angle" property value of trail. Refer to adg_trail_set_max_angle() for details of what this parameter is used for.

trail :

an AdgTrail

Returns :

the value (in radians) of the max angle

Since 1.0

Property Details

The "max-angle" property

  "max-angle"                gdouble               : Read / Write

Max arc angle to approximate with a single Bezier curve: check adg_trail_set_max_angle() for details.

Allowed values: [0,3.14159]

Default value: 1.5708