![]() |
![]() |
![]() |
CPML reference manual |
![]() |
---|---|---|---|---|
Top | Description |
typedef CpmlPath; struct CpmlSegment;int cpml_path_is_empty (const CpmlPath *path
);void cpml_segment_copy (CpmlSegment *segment
,const CpmlSegment *src
);void cpml_segment_dump (const CpmlSegment *segment
);int cpml_segment_from_cairo (CpmlSegment *segment
,CpmlPath *path
);double cpml_segment_get_length (const CpmlSegment *segment
);int cpml_segment_next (CpmlSegment *segment
);void cpml_segment_offset (CpmlSegment *segment
,);
double offsetvoid cpml_segment_put_extents (const CpmlSegment *segment
,CpmlExtents *extents
);size_t cpml_segment_put_intersections (const CpmlSegment *segment
,const CpmlSegment *segment2
,,
size_t n_destCpmlPair *dest
);void cpml_segment_put_pair_at (const CpmlSegment *segment
,,
double posCpmlPair *pair
);void cpml_segment_put_vector_at (const CpmlSegment *segment
,,
double posCpmlVector *vector
);void cpml_segment_reset (CpmlSegment *segment
);void cpml_segment_reverse (CpmlSegment *segment
);void cpml_segment_to_cairo (const CpmlSegment *segment
,);
cairo_t *crvoid cpml_segment_transform (CpmlSegment *segment
,const
);cairo_matrix_t *matrix
A segment is a single contiguous line got from a cairo path. The
CPML library relies on one assumption to let the data be independent
from the current point (and thus from the cairo context): any segment
MUST be preceded by at least one CPML_MOVE
primitive.
This means a valid segment in cairo could be rejected by CPML.
CpmlSegment provides an unobtrusive way to access a cairo path.
This means CpmlSegment itsself does not hold any coordinates but
instead a bunch of pointers to the original
Every CpmlPath struct can contain more than one segment: the CPML
library provides iteration APIs to browse the segments of a path.
Use cpml_segment_reset()
to reset the iterator at the start of the
cairo path (will point the first segment) and cpml_segment_next()
to get the next segment. Getting the previous segment is not provided
as the underlying cairo struct is not accessible in reverse order.
When initialized, CpmlSegment yet refers to the first segment so the initial reset is not required.
typedef cairo_path_t CpmlPath;
This is another name for the CPML_ARC
primitives.
This is not a native cairo primitive and having two different data
types is a good way to make clear when a function expect or not
embedded arc-to primitives.
Since 1.0
struct CpmlSegment { CpmlPath *path; cairo_path_data_t *data; int num_data; };
This is an unobtrusive struct to identify a segment inside a
cairo path. Unobtrusive means that the real coordinates are
still stored in path
: CpmlSegment only provides a way to
access them.
CpmlPath * |
the source CpmlPath struct |
the data points of the segment; the first primitive
will always be a CPML_MOVE |
|
size of data |
Since 1.0
int cpml_path_is_empty (const CpmlPath *path
);
Checks if path
is empty. An invalid path is considered empty.
|
a CpmlPath (or a |
Returns : |
1 0 |
Since 1.0
void cpml_segment_copy (CpmlSegment *segment
,const CpmlSegment *src
);
Makes a shallow copy of src
into segment
.
|
a CpmlSegment |
|
the source segment to copy |
Since 1.0
void cpml_segment_dump (const CpmlSegment *segment
);
Dumps the specified segment
to stdout. Useful for debugging purposes.
|
a CpmlSegment |
Since 1.0
int cpml_segment_from_cairo (CpmlSegment *segment
,CpmlPath *path
);
Builds a CpmlSegment from a CpmlPath structure. This operation
involves stripping the duplicate CPML_MOVE
primitives at the
start of the path and setting num_data
field to the end of the contiguous line, that is when another
CPML_MOVE
primitive is found or at the end of the path.
A pointer to the source cairo path is kept though.
This function will fail if path
is null, empty or if its
status
member is not CAIRO_STATUS_SUCCESS
CPML_MOVE
, so no
dependency on the cairo context is needed.
|
a CpmlSegment. [out] |
|
the source CpmlPath. [in] |
Returns : |
1 segment has been succesfully computed,
0 |
Since 1.0
double cpml_segment_get_length (const CpmlSegment *segment
);
Gets the whole length of segment
.
|
a CpmlSegment |
Returns : |
the requested length |
Since 1.0
int cpml_segment_next (CpmlSegment *segment
);
Modifies segment
to point to the next segment of the source cairo path.
|
a CpmlSegment |
Returns : |
1 0 |
Since 1.0
void cpml_segment_offset (CpmlSegment *segment
,);
double offset
Offsets a segment of the specified amount, that is builds a "parallel"
segment at the offset
distance from the original one and returns the
result by replacing the original segment
.
cpml_close_offset()
|
a CpmlSegment |
|
the offset distance |
Since 1.0
void cpml_segment_put_extents (const CpmlSegment *segment
,CpmlExtents *extents
);
Gets the whole extents of segment
.
|
a CpmlSegment |
|
where to store the extents |
Since 1.0
size_t cpml_segment_put_intersections (const CpmlSegment *segment
,const CpmlSegment *segment2
,,
size_t n_destCpmlPair *dest
);
Computes the intersections between segment
and segment2
and
returns the found points in dest
. If the intersections are more
than n_dest
, only the first n_dest
pairs are stored in dest
.
To get the job done, the primitives of segment
are sequentially
scanned for intersections with any primitive in segment2
. This
means segment
has a higher precedence over segment2
.
|
the first CpmlSegment |
|
the second CpmlSegment |
|
maximum number of intersections to return |
|
the destination vector of CpmlPair |
Returns : |
the number of intersections found |
Since 1.0
void cpml_segment_put_pair_at (const CpmlSegment *segment
,,
double posCpmlPair *pair
);
Gets the coordinates of the point lying on segment
at position
pos
. pos
is an homogeneous factor where 0
1
0
0
pos
< 1
pos
is 0
1
|
a CpmlSegment |
|
the position value |
|
the destination CpmlPair |
Since 1.0
void cpml_segment_put_vector_at (const CpmlSegment *segment
,,
double posCpmlVector *vector
);
Gets the steepness of the point lying on segment
at position
pos
. pos
is an homogeneous factor where 0
1
0
0
pos
< 1
pos
is 0
1
|
a CpmlSegment |
|
the position value |
|
the destination CpmlVector |
Since 1.0
void cpml_segment_reset (CpmlSegment *segment
);
Modifies segment
to point to the first segment of the source cairo path.
|
a CpmlSegment |
Since 1.0
void cpml_segment_reverse (CpmlSegment *segment
);
Reverses segment
in-place. The resulting rendering will be the same,
but with the primitives generated in reverse order.
It is assumed that segment
has yet been sanitized, that is returned
by some CPML API function or it is a path yet conforming to the
segment rules described by the cpml_segment_from_cairo()
function.
|
a CpmlSegment |
Since 1.0
void cpml_segment_to_cairo (const CpmlSegment *segment
,);
cairo_t *cr
Appends the path of segment
to cr
. The segment is "flattened",
that is CPML_ARC
primitives are approximated by one or more
CPML_CURVE
using cpml_arc_to_cairo()
. Check its documentation
for further details.
|
a CpmlSegment |
|
the destination cairo context |
Since 1.0
void cpml_segment_transform (CpmlSegment *segment
,const
);cairo_matrix_t *matrix
Applies matrix
on all the points of segment
.
|
a CpmlSegment |
|
the matrix to be applied |
Since 1.0