AdgTrail

AdgTrail — A bare model built around CpmlPath

Synopsis

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

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 CpmlPath 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

struct AdgTrail

struct AdgTrail;

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

Since 1.0


AdgTrailCallback ()

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

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

trail :

an AdgTrail

user_data :

the general purpose pointer set by adg_trail_new()

Returns :

the CpmlPath of this trail model

Since 1.0


struct AdgTrailClass

struct AdgTrailClass {
    CpmlPath *          (*get_cpml_path)        (AdgTrail       *trail);
};

adg_trail_cpml_path ()

CpmlPath *          adg_trail_cpml_path                 (AdgTrail *trail);

Gets the CPML path structure defined by trail. The returned value is managed by the AdgTrail implementation, that is this function directly calls the AdgTrailClass::get_cpml_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 CpmlPath could be relocated and the old CpmlPath will likely contain rubbish.

trail :

an AdgTrail

Returns :

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

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_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 CpmlPath of trail by calling adg_trail_cpml_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

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_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


adg_trail_new ()

AdgTrail *          adg_trail_new                       (AdgTrailCallback callback,
                                                         gpointer user_data);

Creates a new trail model. The CpmlPath 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 CpmlPath 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_put_segment ()

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

Convenient function to get a segment from trail. The segment is got from the CPML path: check out adg_trail_cpml_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 AdgSegment

Returns :

TRUE on success or FALSE on errors

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

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