![]() |
![]() |
![]() |
adg-1 reference manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <adg-1/adg.h> struct AdgPath; struct AdgPathClass; AdgPath * adg_path_new (void
); const CpmlPair * adg_path_get_current_point (AdgPath *path
); gboolean adg_path_has_current_point (AdgPath *path
); const CpmlPrimitive * adg_path_last_primitive (AdgPath *path
); const CpmlPrimitive * adg_path_over_primitive (AdgPath *path
); void adg_path_append (AdgPath *path
,CpmlPrimitiveType type
,...
); void adg_path_append_valist (AdgPath *path
,CpmlPrimitiveType type
,va_list var_args
); void adg_path_append_array (AdgPath *path
,CpmlPrimitiveType type
,const CpmlPair **pairs
); void adg_path_append_primitive (AdgPath *path
,const CpmlPrimitive *primitive
); void adg_path_append_segment (AdgPath *path
,const CpmlSegment *segment
); void adg_path_append_cpml_path (AdgPath *path
,const cairo_path_t *cairo_path
); void adg_path_move_to (AdgPath *path
,const CpmlPair *pair
); void adg_path_move_to_explicit (AdgPath *path
,gdouble x
,gdouble y
); void adg_path_line_to (AdgPath *path
,const CpmlPair *pair
); void adg_path_line_to_explicit (AdgPath *path
,gdouble x
,gdouble y
); void adg_path_arc_to (AdgPath *path
,const CpmlPair *throught
,const CpmlPair *pair
); void adg_path_arc_to_explicit (AdgPath *path
,gdouble x1
,gdouble y1
,gdouble x2
,gdouble y2
); void adg_path_curve_to (AdgPath *path
,const CpmlPair *control1
,const CpmlPair *control2
,const CpmlPair *pair
); void adg_path_curve_to_explicit (AdgPath *path
,gdouble x1
,gdouble y1
,gdouble x2
,gdouble y2
,gdouble x3
,gdouble y3
); void adg_path_close (AdgPath *path
); void adg_path_arc (AdgPath *path
,const CpmlPair *center
,gdouble r
,gdouble start
,gdouble end
); void adg_path_arc_explicit (AdgPath *path
,gdouble xc
,gdouble yc
,gdouble r
,gdouble start
,gdouble end
); void adg_path_chamfer (AdgPath *path
,gdouble delta1
,gdouble delta2
); void adg_path_fillet (AdgPath *path
,gdouble radius
); void adg_path_reflect (AdgPath *path
,const CpmlVector *vector
); void adg_path_reflect_explicit (AdgPath *path
,gdouble x
,gdouble y
);
The AdgPath model represents a virtual cairo_path_t: this class implements methods to create the path and provides additional operations specific to technical drawings.
AdgPath overrides the get_cairo_path()
method of the parent
AdgTrail class, avoiding the need of an AdgTrailCallback.
The path is constructed programmaticaly: keep in mind any
method that modifies the path will invalidate the cairo_path_t
returned by adg_trail_get_cairo_path()
.
Although some of the provided methods are clearly based on the original cairo path manipulation API, their behavior could be sligthly different. This is intentional, because the ADG provides additional path manipulation algorithms, sometime quite complex, and a more restrictive filter on the path quality is required. Also, the ADG is designed to be used by technicians while cairo targets a broader range of developers.
As an example, following the rule of the less surprise, some
cairo functions guess the current point when it is not defined,
while the AdgPath methods trigger a warning without other effect.
Furthermore, after cairo_path_close_path()
a CPML_MOVE primitive
to the starting point of the segment is automatically added by
cairo; in ADG, after an adg_path_close()
the current point is unset.
struct AdgPath;
All fields are private and should not be used directly. Use its public methods instead.
Since 1.0
AdgPath * adg_path_new (void
);
Creates a new path model. The path should be constructed programmatically by using the methods provided by AdgPath.
Returns : |
the newly created path model |
Since 1.0
const CpmlPair * adg_path_get_current_point (AdgPath *path
);
Gets the current point of path
, which is conceptually the
final point reached by the path so far.
If there is no defined current point, NULL
is returned.
It is possible to check this in advance with
adg_path_has_current_point()
.
Most AdgPath methods alter the current point and most of them expect a current point to be defined otherwise will fail triggering a warning. Check the description of every method for specific details.
|
an AdgPath |
Returns : |
the current point or NULL on no current point set or errors. [transfer none]
|
Since 1.0
gboolean adg_path_has_current_point (AdgPath *path
);
Returns whether a current point is defined on path
.
See adg_path_get_current_point()
for details on the current point.
|
an AdgPath |
Returns : |
whether a current point is defined |
Since 1.0
const CpmlPrimitive * adg_path_last_primitive (AdgPath *path
);
Gets the last primitive appended to path
. The returned struct
is owned by path
and should not be freed or modified.
|
an AdgPath |
Returns : |
a pointer to the last appended primitive or NULL on errors. [transfer none]
|
Since 1.0
const CpmlPrimitive * adg_path_over_primitive (AdgPath *path
);
Gets the primitive before the last one appended to path
. The
"over" term comes from forth, where the OVER
operator works
on the stack in the same way as adg_path_over_primitive()
works
on path
. The returned struct is owned by path
and should not
be freed or modified.
|
an AdgPath |
Returns : |
a pointer to the primitive before the last appended one or NULL on errors. [transfer none]
|
Since 1.0
void adg_path_append (AdgPath *path
,CpmlPrimitiveType type
,...
);
Generic method to append a primitive to path
. The number of CpmlPair
pointers to pass as Varargs
depends on type
: CPML_CLOSE does not
require any pair, CPML_MOVE and CPML_LINE require one pair,
CPML_ARC two pairs, CPML_CURVE three pairs and so on.
All the needed pairs must be not NULL
pointers, otherwise the function
will fail. The pairs in excess, if any, will be ignored.
Since 1.0
void adg_path_append_valist (AdgPath *path
,CpmlPrimitiveType type
,va_list var_args
);
va_list version of adg_path_append()
.
|
an AdgPath |
|
a cairo_data_type_t value |
|
point data, specified as CpmlPair pointers |
Since 1.0
void adg_path_append_array (AdgPath *path
,CpmlPrimitiveType type
,const CpmlPair **pairs
);
A bindingable version of adg_path_append()
that uses a NULL
terminated
array of pairs instead of variable argument list and friends.
Furthermore, because of the list is NULL
terminated, an arbitrary
number of pairs can be passed in pairs
. This allows to embed in a
primitive element more data pairs than requested, something impossible
to do with adg_path_append()
and adg_path_append_valist()
.
Rename to: adg_path_append
|
an AdgPath |
|
a cairo_data_type_t value |
|
point data, specified as a NULL terminated array of CpmlPair pointers. [array zero-terminated=1][element-type Cpml.Pair][transfer none]
|
Since 1.0
void adg_path_append_primitive (AdgPath *path
,const CpmlPrimitive *primitive
);
Appends primitive
to path
. The primitive to add is considered the
continuation of the current path so the org
component of primitive
is not used. Anyway the current point is
checked against it: they must be equal or the function will fail
without further processing.
|
an AdgPath |
|
the CpmlPrimitive to append |
Since 1.0
void adg_path_append_segment (AdgPath *path
,const CpmlSegment *segment
);
Appends segment
to path
.
|
an AdgPath |
|
the CpmlSegment to append |
Since 1.0
void adg_path_append_cpml_path (AdgPath *path
,const cairo_path_t *cairo_path
);
void adg_path_move_to (AdgPath *path
,const CpmlPair *pair
);
Begins a new segment. After this call the current point will be pair
.
|
an AdgPath |
|
the destination coordinates |
Since 1.0
void adg_path_move_to_explicit (AdgPath *path
,gdouble x
,gdouble y
);
Convenient function to call adg_path_move_to()
using explicit
coordinates instead of CpmlPair.
|
an AdgPath |
|
the new x coordinate |
|
the new y coordinate |
Since 1.0
void adg_path_line_to (AdgPath *path
,const CpmlPair *pair
);
Adds a line to path
from the current point to pair
. After this
call the current point will be pair
.
If path
has no current point before this call, this function will
trigger a warning without other effect.
|
an AdgPath |
|
the destination coordinates |
Since 1.0
void adg_path_line_to_explicit (AdgPath *path
,gdouble x
,gdouble y
);
Convenient function to call adg_path_line_to()
using explicit
coordinates instead of CpmlPair.
|
an AdgPath |
|
the new x coordinate |
|
the new y coordinate |
Since 1.0
void adg_path_arc_to (AdgPath *path
,const CpmlPair *throught
,const CpmlPair *pair
);
Adds an arc to the path from the current point to pair
, passing
throught throught
. After this call the current point will be pair
.
If path
has no current point before this call, this function will
trigger a warning without other effect.
|
an AdgPath |
|
an arbitrary point on the arc |
|
the destination coordinates |
Since 1.0
void adg_path_arc_to_explicit (AdgPath *path
,gdouble x1
,gdouble y1
,gdouble x2
,gdouble y2
);
Convenient function to call adg_path_arc_to()
using explicit
coordinates instead of CpmlPair.
|
an AdgPath |
|
the x coordinate of an intermediate point |
|
the y coordinate of an intermediate point |
|
the x coordinate of the end of the arc |
|
the y coordinate of the end of the arc |
Since 1.0
void adg_path_curve_to (AdgPath *path
,const CpmlPair *control1
,const CpmlPair *control2
,const CpmlPair *pair
);
Adds a cubic Bézier curve to the path from the current point to
position pair
, using control1
and control2
as control points.
After this call the current point will be pair
.
If path
has no current point before this call, this function will
trigger a warning without other effect.
|
an AdgPath |
|
the first control point of the curve |
|
the second control point of the curve |
|
the destination coordinates |
Since 1.0
void adg_path_curve_to_explicit (AdgPath *path
,gdouble x1
,gdouble y1
,gdouble x2
,gdouble y2
,gdouble x3
,gdouble y3
);
Convenient function to call adg_path_curve_to()
using explicit
coordinates instead of CpmlPair.
|
an AdgPath |
|
the x coordinate of the first control point |
|
the y coordinate of the first control point |
|
the x coordinate of the second control point |
|
the y coordinate of the second control point |
|
the x coordinate of the end of the curve |
|
the y coordinate of the end of the curve |
Since 1.0
void adg_path_close (AdgPath *path
);
Adds a line segment to the path from the current point to the
beginning of the current segment, (the most recent point passed
to an adg_path_move_to()
), and closes this segment.
After this call the current point will be unset.
The behavior of adg_path_close()
is distinct from simply calling
adg_line_to()
with the coordinates of the segment starting point.
When a closed segment is stroked, there are no caps on the ends.
Instead, there is a line join connecting the final and initial
primitive of the segment.
If path
has no current point before this call, this function will
trigger a warning without other effect.
|
an AdgPath |
Since 1.0
void adg_path_arc (AdgPath *path
,const CpmlPair *center
,gdouble r
,gdouble start
,gdouble end
);
A more usual way to add an arc to path
. After this call, the current
point will be the computed end point of the arc. The arc will be
rendered in increasing angle, accordling to start
and end
. This means
if start
is less than end
, the arc will be rendered in clockwise
direction (accordling to the default cairo coordinate system) while if
start
is greather than end
, the arc will be rendered in couterclockwise
direction.
By explicitely setting the whole arc data, the start point could be
different from the current point. In this case, if path
has no
current point before the call a CPML_MOVE to the start point of
the arc will be automatically prepended to the arc. If path
has a
current point, a CPML_LINE to the start point of the arc will be
used instead of the "move to" primitive.
|
an AdgPath |
|
coordinates of the center of the arc |
|
the radius of the arc |
|
the start angle, in radians |
|
the end angle, in radians |
Since 1.0
void adg_path_arc_explicit (AdgPath *path
,gdouble xc
,gdouble yc
,gdouble r
,gdouble start
,gdouble end
);
Convenient function to call adg_path_arc()
using explicit
coordinates instead of CpmlPair.
|
an AdgPath |
|
x position of the center of the arc |
|
y position of the center of the arc |
|
the radius of the arc |
|
the start angle, in radians |
|
the end angle, in radians |
Since 1.0
void adg_path_chamfer (AdgPath *path
,gdouble delta1
,gdouble delta2
);
A binary action that generates a chamfer between two primitives.
The first primitive involved is the current primitive, the second will
be the next primitive appended to path
after this call. The second
primitive is required: if the chamfer operation is not properly
terminated (by not providing the second primitive), any API accessing
the path in reading mode will raise a warning.
An exception is a chamfer after a CPML_CLOSE primitive. In this case, the second primitive is not required: the current close path is used as first operand while the first primitive of the current segment is used as second operand.
The chamfer operation requires two lengths: delta1
specifies the
"quantity" to trim on the first primitive while delta2
is the same
applied on the second primitive. The term "quantity" means the length
of the portion to cut out from the original primitive (that is the
primitive as would be without the chamfer).
|
an AdgPath |
|
the distance from the intersection point of the current primitive |
|
the distance from the intersection point of the next primitive |
Since 1.0
void adg_path_fillet (AdgPath *path
,gdouble radius
);
A binary action that joins to primitives with an arc.
The first primitive involved is the current primitive, the second will
be the next primitive appended to path
after this call. The second
primitive is required: if the fillet operation is not properly
terminated (by not providing the second primitive), any API accessing
the path in reading mode will raise a warning.
An exception is a fillet after a CPML_CLOSE primitive. In this case, the second primitive is not required: the current close path is used as first operand while the first primitive of the current segment is used as second operand.
|
an AdgPath |
|
the radius of the fillet |
Since 1.0
void adg_path_reflect (AdgPath *path
,const CpmlVector *vector
);
Reflects the first segment or path
around the axis passing
throught (0, 0) and with a vector
slope. The internal segment
is duplicated and the proper transformation (computed from
vector
) to mirror the segment is applied on all its points.
The result is then reversed with cpml_segment_reverse()
and
appended to the original path with adg_path_append_segment()
.
For convenience, if vector
is NULL
the path is reversed
around the x axis (y=0).
|
an AdgPath |
|
the slope of the axis. [allow-none] |
Since 1.0
void adg_path_reflect_explicit (AdgPath *path
,gdouble x
,gdouble y
);
Convenient function to call adg_path_reflect()
using explicit
vector components instead of CpmlVector.
|
an AdgPath |
|
the vector x component |
|
the vector y component |
Since 1.0