doc: updated italian translations
[adg.git] / src / cpml / cpml-primitive.c
blob130e57dbe87e6b47bfb2dae04f1147bb59415aad
1 /* CPML - Cairo Path Manipulation Library
2 * Copyright (C) 2008,2009,2010,2011,2012 Nicola Fontana <ntd at entidi.it>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
21 /**
22 * SECTION:cpml-primitive
23 * @Section_Id:CpmlPrimitive
24 * @title: CpmlPrimitive
25 * @short_description: Basic component of segments
27 * A primitive is an atomic geometric element found inside #CpmlSegment.
28 * The available primitives are the same defined by #cairo_path_data_type_t
29 * with the additional #CPML_ARC type (check #CpmlPrimitiveType
30 * for further information) and without #CPML_MOVE as it is not
31 * considered a primitive and it is managed in different way: the move-to
32 * primitives are only used to define the origin of a segment.
34 * Since: 1.0
35 **/
37 /**
38 * CpmlPrimitiveType:
39 * @CPML_MOVE: equivalent to %CAIRO_PATH_MOVE_TO
40 * @CPML_LINE: equivalent to %CAIRO_PATH_LINE_TO
41 * @CPML_CURVE: equivalent to %CAIRO_PATH_CURVE_TO
42 * @CPML_CLOSE: equivalent to %CAIRO_PATH_CLOSE_PATH
43 * @CPML_ARC: an arc representation at CPML level
45 * This is a type compatible with #cairo_path_data_type_t type. It is
46 * basically the same enum but it embodies an important difference:
47 * it can be used to specify the special #CPML_ARC primitive. Having
48 * two different types is a good way to make clear when a function
49 * expect or not embedded #CPML_ARC primitives.
51 * Arcs are used extensively in technical drawing: some operations are
52 * trivials with arcs and a nightmare with cubic Bézier curves. Actually,
53 * at least up to version 1.10.2, the cairo library does not support arc
54 * primitives natively and there is no plan they will be ever supported.
56 * The CPML library supports arc natively, converting them to curves
57 * when the #CpmlSegment is returned to the cairo context, for instance
58 * when using cpml_segment_to_cairo().
60 * Since: 1.0
61 **/
63 /**
64 * CpmlPrimitive:
65 * @segment: the source #CpmlSegment
66 * @org: a pointer to the first point of the primitive
67 * @data: the array of the path data, prepended by the header
69 * As for #CpmlSegment, also the primitive is unobtrusive. This
70 * means CpmlPrimitive does not include any coordinates but instead
71 * keeps pointers to the original segment (and, by transition, to
72 * the underlying #CpmlPath struct).
74 * Since: 1.0
75 **/
78 #include "cpml-internal.h"
79 #include "cpml-extents.h"
80 #include "cpml-segment.h"
81 #include "cpml-primitive.h"
82 #include "cpml-primitive-private.h"
83 #include "cpml-arc.h"
84 #include "cpml-curve.h"
85 #include <string.h>
86 #include <stdio.h>
89 static const _CpmlPrimitiveClass *
90 _cpml_class_from_type (CpmlPrimitiveType type);
91 static const _CpmlPrimitiveClass *
92 _cpml_class_from_obj (const CpmlPrimitive *primitive);
93 static cairo_path_data_t *
94 _cpml_get_point (const CpmlPrimitive *primitive,
95 int n_point);
96 static void _cpml_dump_point (const cairo_path_data_t *path_data);
99 /**
100 * cpml_primitive_type_get_n_points:
101 * @type: a primitive type
103 * Gets the number of points required to identify the @type primitive.
105 * Returns: the number of points or %0 on errors
107 * Since: 1.0
109 size_t
110 cpml_primitive_type_get_n_points(CpmlPrimitiveType type)
112 const _CpmlPrimitiveClass *class_data = _cpml_class_from_type(type);
114 if (class_data == NULL)
115 return 0;
117 return class_data->n_points;
121 * cpml_primitive_from_segment:
122 * @primitive: (out): the destination #CpmlPrimitive struct
123 * @segment: (in): the source segment
125 * Initializes @primitive to the first primitive of @segment.
127 * Since: 1.0
129 void
130 cpml_primitive_from_segment(CpmlPrimitive *primitive, CpmlSegment *segment)
132 primitive->segment = segment;
134 /* The first element of a CpmlSegment is always a CPML_MOVE,
135 * as ensured by cpml_segment_from_cairo() and by the browsing APIs,
136 * so the origin is in the second data item */
137 primitive->org = segment->data + 1;
139 /* Also, the segment APIs ensure that @segment is prepended by
140 * only one CPML_MOVE */
141 primitive->data = segment->data + segment->data->header.length;
145 * cpml_primitive_copy:
146 * @primitive: (out): the destination #CpmlPrimitive
147 * @src: (in): the source #CpmlPrimitive
149 * Copies @src in @primitive. This is a shallow copy: the internal fields
150 * of @primitive refer to the same memory as the original @src primitive.
152 * Since: 1.0
154 void
155 cpml_primitive_copy(CpmlPrimitive *primitive, const CpmlPrimitive *src)
157 memcpy(primitive, src, sizeof(CpmlPrimitive));
161 * cpml_primitive_reset:
162 * @primitive: (inout): a #CpmlPrimitive
164 * Resets @primitive so it refers to the first primitive of the
165 * source segment.
167 * Since: 1.0
169 void
170 cpml_primitive_reset(CpmlPrimitive *primitive)
172 cpml_primitive_from_segment(primitive, primitive->segment);
176 * cpml_primitive_next:
177 * @primitive: (inout): a #CpmlPrimitive
179 * Changes @primitive so it refers to the next primitive on the
180 * source segment. If there are no more primitives, @primitive is
181 * not changed and 0 is returned.
183 * Returns: (type boolean): %1 on success,
184 * %0 if no next primitive found or errors
186 * Since: 1.0
189 cpml_primitive_next(CpmlPrimitive *primitive)
191 cairo_path_data_t *new_data;
192 const cairo_path_data_t *end_data;
194 new_data = primitive->data + primitive->data->header.length;
195 end_data = primitive->segment->data + primitive->segment->num_data;
197 if (new_data >= end_data)
198 return 0;
200 primitive->org = _cpml_get_point(primitive, -1);
201 primitive->data = new_data;
203 return 1;
207 * cpml_primitive_get_n_points:
208 * @primitive: a #CpmlPrimitive
210 * Gets the number of points required to identify @primitive.
211 * It is similar to cpml_primitive_type_get_n_points() but using
212 * a @primitive instance instead of a type.
214 * Returns: the number of points or %0 on errors
216 * <!-- Virtual: n_points -->
218 * Since: 1.0
220 size_t
221 cpml_primitive_get_n_points(const CpmlPrimitive *primitive)
223 return cpml_primitive_type_get_n_points(primitive->data->header.type);
227 * cpml_primitive_get_length:
228 * @primitive: a #CpmlPrimitive
230 * Abstracts the length() family functions by providing a common
231 * way to access the underlying primitive-specific implementation.
232 * The function returns the length of @primitive.
234 * Returns: the requested length or 0 on errors
236 * <!-- Virtual: get_length -->
238 * Since: 1.0
240 double
241 cpml_primitive_get_length(const CpmlPrimitive *primitive)
243 const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
245 if (class_data == NULL || class_data->get_length == NULL)
246 return 0;
248 return class_data->get_length(primitive);
252 * cpml_primitive_put_extents:
253 * @primitive: (in): a #CpmlPrimitive
254 * @extents: (out): where to store the extents
256 * Abstracts the extents() family functions by providing a common
257 * way to access the underlying primitive-specific implementation.
259 * This function stores in @extents the bounding box of @primitive.
261 * On errors, that is if the extents cannot be calculated for some
262 * reason, this function does nothing.
264 * <!-- Virtual: put_extents -->
266 * Since: 1.0
268 void
269 cpml_primitive_put_extents(const CpmlPrimitive *primitive,
270 CpmlExtents *extents)
272 const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
274 if (class_data == NULL || class_data->put_extents == NULL)
275 return;
277 class_data->put_extents(primitive, extents);
281 * cpml_primitive_set_point:
282 * @primitive: a #CpmlPrimitive
283 * @n_point: the index of the point to retrieve
284 * @pair: the source #CpmlPair
286 * Sets the specified @n_point of @primitive to @pair. The @n_point
287 * index starts from 0: if @n_point is 0, the start point (the origin)
288 * is changed, 1 for the second point and so on. If @n_point is
289 * negative, it is considered as a negative index from the end, so
290 * that -1 is the end point, -2 the point before the end point and
291 * so on.
293 * #CPML_CLOSE is managed in a special way: if @n_point
294 * is -1 or 1 and @primitive is a close-path, this function cycles
295 * the source #CpmlSegment and returns the first point. This is
296 * needed because requesting the end point (or the second point)
297 * of a close path is a valid operation and must returns the origin
298 * of the segment.
300 * Since: 1.0
302 void
303 cpml_primitive_set_point(CpmlPrimitive *primitive,
304 int n_point, const CpmlPair *pair)
306 cairo_path_data_t *point = _cpml_get_point(primitive, n_point);
308 if (point != NULL)
309 cpml_pair_to_cairo(pair, point);
313 * cpml_primitive_put_point:
314 * @primitive: (in): a #CpmlPrimitive
315 * @n_point: (in): the index of the point to retrieve
316 * @pair: (out): the destination #CpmlPair
318 * Gets the specified @n_point from @primitive and stores it into
319 * @pair. The @n_point index is subject to the same rules explained
320 * in the cpml_primitive_set_point() function.
322 * Since: 1.0
324 void
325 cpml_primitive_put_point(const CpmlPrimitive *primitive,
326 int n_point, CpmlPair *pair)
328 const cairo_path_data_t *point = _cpml_get_point(primitive, n_point);
330 if (point != NULL)
331 cpml_pair_from_cairo(pair, point);
335 * cpml_primitive_put_pair_at:
336 * @primitive: (in): a #CpmlPrimitive
337 * @pos: (in): the position value
338 * @pair: (out): the destination #CpmlPair
340 * Abstracts the put_pair_at() family functions by providing a common
341 * way to access the underlying primitive-specific implementation.
343 * It gets the coordinates of the point lying on @primitive
344 * at position @pos. @pos is an homogeneous factor where 0 is the
345 * start point, 1 the end point, 0.5 the mid point and so on.
346 * @pos can be less than 0 or greater than %1, in which case the
347 * coordinates of @pair are interpolated.
349 * On errors, that is if the coordinates cannot be calculated for
350 * some reason, this function does nothing.
352 * <!-- Virtual: put_pair_at -->
354 * Since: 1.0
356 void
357 cpml_primitive_put_pair_at(const CpmlPrimitive *primitive,
358 double pos, CpmlPair *pair)
360 const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
362 if (class_data == NULL || class_data->put_pair_at == NULL)
363 return;
365 class_data->put_pair_at(primitive, pos, pair);
369 * cpml_primitive_put_vector_at:
370 * @primitive: (in): a #CpmlPrimitive
371 * @pos: (in): the position value
372 * @vector: (out): the destination #CpmlVector
374 * Abstracts the put_vector_at() family functions by providing a common
375 * way to access the underlying primitive-specific implementation.
377 * It gets the steepness of the point at position @pos on @primitive.
378 * @pos is an homogeneous factor where 0 is the start point, 1 the
379 * end point, 0.5 the mid point and so on.
380 * @pos can be less than 0 or greater than %1, in which case the
381 * coordinates of @pair are interpolated.
383 * On errors, that is if the steepness cannot be calculated for
384 * some reason, this function does nothing.
386 * <!-- Virtual: put_vector_at -->
388 * Since: 1.0
390 void
391 cpml_primitive_put_vector_at(const CpmlPrimitive *primitive,
392 double pos, CpmlVector *vector)
394 const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
396 if (class_data == NULL || class_data->put_vector_at == NULL)
397 return;
399 class_data->put_vector_at(primitive, pos, vector);
403 * cpml_primitive_get_closest_pos:
404 * @primitive: a #CpmlPrimitive
405 * @pair: the coordinates of the subject point
407 * Returns the pos value of the point on @primitive nearest to @pair.
408 * The returned value is always clamped between %0 and %1.
410 * Returns: the requested pos value between %0 and %1, or %-1 on errors
412 * <!-- Virtual: get_closest_pos -->
414 * Since: 1.0
416 double
417 cpml_primitive_get_closest_pos(const CpmlPrimitive *primitive,
418 const CpmlPair *pair)
420 const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
422 if (class_data == NULL || class_data->get_closest_pos == NULL)
423 return -1;
425 return class_data->get_closest_pos(primitive, pair);
429 * cpml_primitive_put_intersections:
430 * @primitive: (in): the first #CpmlPrimitive
431 * @primitive2: (in): the second #CpmlPrimitive
432 * @n_dest: (in): maximum number of intersections to return
433 * @dest: (out): the destination buffer that can contain @n_dest #CpmlPair
435 * Finds the intersection points between the given primitives and
436 * returns the result in @dest. The size of @dest should be enough
437 * to store @n_dest #CpmlPair. The maximum number of intersections
438 * is dependent on the type of the primitive involved in the
439 * operation. If there are at least one Bézier curve involved, up to
440 * %4 intersections could be returned. Otherwise, if there is an arc
441 * the intersections will be %2 at maximum. For line primitives, there
442 * is only %1 point (or %0 if the lines are parallel).
444 * <note>
445 * <para>
446 * The convention used by the CPML library is that a primitive should
447 * implement only the intersection algorithms with lower degree
448 * primitives. This is required to avoid code duplication: intersection
449 * between arc and Bézier curves must be implemented by #CPML_CURVE and
450 * intersection between lines and arcs must be implemented by #CPML_ARC.
451 * cpml_primitive_put_intersections() will take care of swapping the
452 * arguments if they are not properly ordered.
453 * </para>
454 * </note>
456 * Returns: the number of intersection points found or 0 if the
457 * primitives do not intersect or on errors
459 * <!-- Virtual: put_intersections -->
461 * Since: 1.0
463 size_t
464 cpml_primitive_put_intersections(const CpmlPrimitive *primitive,
465 const CpmlPrimitive *primitive2,
466 size_t n_dest, CpmlPair *dest)
468 const _CpmlPrimitiveClass *class_data;
469 size_t n_points, n_points2;
471 class_data = _cpml_class_from_obj(primitive);
473 if (class_data == NULL || class_data->put_intersections == NULL)
474 return 0;
476 n_points = cpml_primitive_get_n_points(primitive);
477 n_points2 = cpml_primitive_get_n_points(primitive2);
479 if (n_points == 0 || n_points2 == 0)
480 return 0;
482 /* Primitives reordering: the first must be the more complex one */
483 if (n_points < n_points2) {
484 const CpmlPrimitive *old_primitive2 = primitive2;
485 primitive2 = primitive;
486 primitive = old_primitive2;
489 return class_data->put_intersections(primitive, primitive2, n_dest, dest);
493 * cpml_primitive_put_intersections_with_segment:
494 * @primitive: (in): a #CpmlPrimitive
495 * @segment: (in): a #CpmlSegment
496 * @n_dest: (in): maximum number of intersection pairs to return
497 * @dest: (out): the destination buffer of #CpmlPair
499 * Computes the intersections between @segment and @primitive by
500 * sequentially scanning the primitives in @segment and looking
501 * for their intersections with @primitive.
503 * If the intersections are more than @n_dest, only the first
504 * @n_dest pairs are stored.
506 * Returns: the number of intersections found
508 * Since: 1.0
510 size_t
511 cpml_primitive_put_intersections_with_segment(const CpmlPrimitive *primitive,
512 const CpmlSegment *segment,
513 size_t n_dest, CpmlPair *dest)
515 CpmlPrimitive portion;
516 size_t found;
518 cpml_primitive_from_segment(&portion, (CpmlSegment *) segment);
519 found = 0;
521 while (found < n_dest) {
522 found += cpml_primitive_put_intersections(&portion, primitive,
523 n_dest-found, dest+found);
524 if (!cpml_primitive_next(&portion))
525 break;
528 return found;
532 * cpml_primitive_offset:
533 * @primitive: (inout): a #CpmlPrimitive
534 * @offset: (in): distance for the computed offset primitive
536 * Given a primitive, computes the same (or approximated) parallel
537 * primitive distant @offset from the original one and returns
538 * the result by changing @primitive.
540 * On errors, that is if the offset primitive cannot be calculated
541 * for some reason, this function does nothing.
543 * <!-- Virtual: offset -->
545 * Since: 1.0
547 void
548 cpml_primitive_offset(CpmlPrimitive *primitive, double offset)
550 const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
552 if (class_data == NULL || class_data->offset == NULL)
553 return;
555 class_data->offset(primitive, offset);
559 * cpml_primitive_join:
560 * @primitive: (inout): the first #CpmlPrimitive
561 * @primitive2: (inout): the second #CpmlPrimitive
563 * Joins two primitive modifying the end point of @primitive and the
564 * start point of @primitive2 so that the resulting points will overlap.
566 * <important>
567 * <title>TODO</title>
568 * <itemizedlist>
569 * <listitem>Actually, the join is done by extending the end vector
570 * of @primitive and the start vector of @primitive2 and
571 * interpolating the intersection: this means no primitive
572 * dependent code is needed. Anyway, it is likely to change
573 * in the future because this approach is quite naive when
574 * curves are involved.</listitem>
575 * </itemizedlist>
576 * </important>
578 * Returns: (type boolean): %1 on success,
579 * %0 if the primitives cannot be joint
581 * <!-- Virtual: join -->
583 * Since: 1.0
586 cpml_primitive_join(CpmlPrimitive *primitive, CpmlPrimitive *primitive2)
588 cairo_path_data_t *end1, *start2;
589 CpmlPrimitive line1, line2;
590 cairo_path_data_t data1[2], data2[2];
591 CpmlPair joint;
593 end1 = _cpml_get_point(primitive, -1);
594 start2 = _cpml_get_point(primitive2, 0);
596 /* Check if the primitives are yet connected */
597 if (end1->point.x == start2->point.x && end1->point.y == start2->point.y)
598 return 1;
600 line1.org = _cpml_get_point(primitive, -2);
601 line1.data = data1;
602 data1[0].header.type = CPML_LINE;
603 data1[1] = *end1;
605 line2.org = start2;
606 line2.data = data2;
607 data2[0].header.type = CPML_LINE;
608 data2[1] = *_cpml_get_point(primitive2, 1);
610 if (!cpml_primitive_put_intersections(&line1, &line2, 1, &joint))
611 return 0;
613 cpml_pair_to_cairo(&joint, end1);
614 cpml_pair_to_cairo(&joint, start2);
616 return 1;
620 * cpml_primitive_to_cairo:
621 * @primitive: (in): a #CpmlPrimitive
622 * @cr: (inout): the destination cairo context
624 * Renders a single @primitive to the @cr cairo context.
625 * As a special case, if the primitive is a #CPML_CLOSE, an
626 * equivalent line is rendered, because a close path left alone
627 * is not renderable.
629 * Also a #CPML_ARC primitive is treated specially, as it is not
630 * natively supported by cairo and has its own rendering API.
632 * Since: 1.0
634 void
635 cpml_primitive_to_cairo(const CpmlPrimitive *primitive, cairo_t *cr)
637 CpmlPrimitiveType type;
638 cairo_path_t path;
639 cairo_path_data_t *path_data;
641 cairo_move_to(cr, primitive->org->point.x, primitive->org->point.y);
643 type = primitive->data->header.type;
645 if (type == CPML_CLOSE) {
646 path_data = _cpml_get_point(primitive, -1);
647 cairo_line_to(cr, path_data->point.x, path_data->point.y);
648 } else if (type == CPML_ARC) {
649 cpml_arc_to_cairo(primitive, cr);
650 } else {
651 path.status = CAIRO_STATUS_SUCCESS;
652 path.data = primitive->data;
653 path.num_data = primitive->data->header.length;
654 cairo_append_path(cr, &path);
659 * cpml_primitive_dump:
660 * @primitive: a #CpmlPrimitive
661 * @org_also: whether to output also the origin coordinates
663 * Dumps info on the specified @primitive to stdout: useful for
664 * debugging purposes. If @org_also is 1, a #CPML_MOVE to the
665 * origin is prepended to the data otherwise the
666 * <structfield>org</structfield> field is not used.
668 * Since: 1.0
670 void
671 cpml_primitive_dump(const CpmlPrimitive *primitive, int org_also)
673 const cairo_path_data_t *data;
674 int type;
675 const _CpmlPrimitiveClass *class_data;
676 size_t n, n_points;
678 data = primitive->data;
679 type = data->header.type;
680 class_data = _cpml_class_from_type(type);
682 if (class_data == NULL) {
683 printf("Unknown primitive type (%d)\n", type);
684 return;
687 /* Dump the origin, if requested */
688 if (org_also) {
689 printf("move to ");
690 _cpml_dump_point(primitive->org);
691 printf("\n");
694 printf("%s ", class_data->name);
696 n_points = cpml_primitive_get_n_points(primitive);
697 for (n = 1; n < n_points; ++n)
698 _cpml_dump_point(_cpml_get_point(primitive, n));
700 printf("\n");
704 static const _CpmlPrimitiveClass *
705 _cpml_class_from_type(CpmlPrimitiveType type)
707 if (type == CPML_LINE)
708 return _cpml_line_get_class();
709 else if (type == CPML_ARC)
710 return _cpml_arc_get_class();
711 else if (type == CPML_CURVE)
712 return _cpml_curve_get_class();
713 else if (type == CPML_CLOSE)
714 return _cpml_close_get_class();
716 return NULL;
719 static const _CpmlPrimitiveClass *
720 _cpml_class_from_obj(const CpmlPrimitive *primitive)
722 return _cpml_class_from_type(primitive->data->header.type);
726 * _cpml_get_point:
727 * @primitive: a #CpmlPrimitive
728 * @n_point: the index of the point to retrieve
730 * Gets the specified @n_point from @primitive. The index starts
731 * at 0: if @n_point is 0, the start point (the origin) is
732 * returned, 1 for the second point and so on. If @n_point is
733 * negative, it is considered as a negative index from the end,
734 * so that -1 is the end point, -2 the point before the end point
735 * and so on.
737 * #CPML_CLOSE is managed in a special way: if @n_point
738 * is -1 or 1 and @primitive is a close-path, this function cycles
739 * the source #CpmlSegment and returns the first point. This is
740 * needed because requesting the end point (or the second point)
741 * of a close path is a valid operation and must returns the start
742 * of the segment.
744 * Returns: a pointer to the requested point (in cairo format)
745 * or %NULL if the point is outside the valid range
747 * Since: 1.0
749 static cairo_path_data_t *
750 _cpml_get_point(const CpmlPrimitive *primitive, int n_point)
752 size_t n_points;
754 /* For a start point request, simply return the origin
755 * without further checking */
756 if (n_point == 0)
757 return primitive->org;
759 /* The CPML_CLOSE special case */
760 if (primitive->data->header.type == CAIRO_PATH_CLOSE_PATH &&
761 (n_point == 1 || n_point == -1))
762 return &primitive->segment->data[1];
764 n_points = cpml_primitive_get_n_points(primitive);
765 if (n_points == 0)
766 return NULL;
768 /* If n_point is negative, consider it as a negative index from the end */
769 if (n_point < 0)
770 n_point = n_points + n_point;
772 /* Out of range condition */
773 if (n_point < 0 || n_point >= n_points)
774 return NULL;
776 return n_point == 0 ? primitive->org : &primitive->data[n_point];
779 static void
780 _cpml_dump_point(const cairo_path_data_t *path_data)
782 printf("(%g %g) ", path_data->point.x, path_data->point.y);