![]() |
![]() |
![]() |
adg-1 reference manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#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
);
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.
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.
|
an AdgTrail |
|
the general purpose pointer set by adg_trail_new()
|
Returns : |
the cairo_path_t of this trail model |
Since 1.0
struct AdgTrail;
All fields are private and should not be used directly. Use its public methods instead.
Since 1.0
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.
virtual method to get the cairo_path_t bound to the trail. |
Since 1.0
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.
|
the cairo_path_t constructor function. [scope notified] |
|
generic pointer to pass to the callback |
Returns : |
a new trail model. [transfer full] |
Since 1.0
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.
|
an AdgTrail |
Returns : |
a pointer to the internal cairo path or NULL on errors. [transfer none]
|
Since 1.0
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.
|
an AdgTrail |
Returns : |
a pointer to the cairo_path_t or NULL on errors. [transfer none]
|
Since 1.0
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
.
|
an AdgTrail |
|
the segment to retrieve, where 1 is the first segment |
|
the destination CpmlSegment |
Returns : |
TRUE on success or FALSE on errors |
Since 1.0
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.
|
an AdgTrail |
Returns : |
the requested extents or NULL on errors |
Since 1.0
void adg_trail_dump (AdgTrail *trail
);
Dumps the data content of trail
to stdout in a human readable format.
|
an AdgTrail |
Since 1.0
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
|
an AdgTrail |
|
the new angle (in radians) |
Since 1.0
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.
|
an AdgTrail |
Returns : |
the value (in radians) of the max angle |
Since 1.0