adg/adg-trail.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007,2008,2009 Nicola Fontana <ntd at entidi.it>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19
  20
  21 /**
  22  * SECTION:adg-trail
  23  * @short_description: A bare model built around #CpmlPath
  24  *
  25  * The #AdgTrail model is a really basic model built around the #CpmlPath
  26  * struct: for a full fledged path model consider using #AdgPath.
  27  *
  28  * A trail is a path model that demands all the implementation details to
  29  * the caller: this requires a deep knowledge of the ADG details but
  30  * provides a great customization level. It should be used when an
  31  * #AdgPath is not enough, such as when a model is subject to change
  32  * dynamically and the global and local maps do not suffice to express
  33  * this alteration. A typical example is the path used to draw extension
  34  * lines and base line of #AdgLDim: every point is subject to different
  35  * constrains not applicable with a single affine transformation.
  36  **/
  37
  38 /**
  39  * AdgTrail:
  40  *
  41  * All fields are private and should not be used directly.
  42  * Use its public methods instead.
  43  **/
  44
  45 /**
  46  * AdgTrailCallback:
  47  * @trail: an #AdgTrail
  48  * @user_data: the general purpose pointer set by adg_trail_new()
  49  *
  50  * This is the callback used to generate the #CpmlPath and it is
  51  * called directly by adg_trail_get_cpml_path(). The caller owns
  52  * the returned path, that is the finalization of the returned
  53  * #CpmlPath should be made by the caller when appropriate.
  54  *
  55  * Returns: the #CpmlPath of this trail model
  56  **/
  57
  58
  59 #include "adg-trail.h"
  60 #include "adg-trail-private.h"
  61
  62 #define PARENT_OBJECT_CLASS  ((GObjectClass *) adg_trail_parent_class)
  63
  64
  65 static void             finalize                (GObject        *object);
  66 static cairo_path_t *   get_cairo_path          (AdgTrail       *trail);
  67 static CpmlPath *       get_cpml_path           (AdgTrail       *trail);
  68 static GArray *         arc_to_curves           (GArray         *array,
  69                                                  const cairo_path_data_t
  70                                                                 *src);
  71
  72
  73 G_DEFINE_TYPE(AdgTrail, adg_trail, ADG_TYPE_MODEL);
  74
  75
  76 static void
  77 adg_trail_class_init(AdgTrailClass *klass)
  78 {
  79     GObjectClass *gobject_class;
  80     AdgModelClass *model_class;
  81
  82     gobject_class = (GObjectClass *) klass;
  83     model_class = (AdgModelClass *) klass;
  84
  85     g_type_class_add_private(klass, sizeof(AdgTrailPrivate));
  86
  87     gobject_class->finalize = finalize;
  88
  89     klass->get_cpml_path = get_cpml_path;
  90 }
  91
  92 static void
  93 adg_trail_init(AdgTrail *trail)
  94 {
  95     AdgTrailPrivate *data = G_TYPE_INSTANCE_GET_PRIVATE(trail, ADG_TYPE_TRAIL,
  96                                                         AdgTrailPrivate);
  97
  98     data->cairo_path.status = CAIRO_STATUS_INVALID_PATH_DATA;
  99     data->cairo_path.data = NULL;
 100     data->cairo_path.num_data = 0;
 101
 102     data->callback = NULL;
 103     data->user_data = NULL;
 104
 105     trail->data = data;
 106 }
 107
 108 static void
 109 finalize(GObject *object)
 110 {
 111     AdgTrail *trail;
 112     AdgTrailPrivate *data;
 113
 114     trail = (AdgTrail *) object;
 115     data = trail->data;
 116
 117     adg_trail_clear_cairo_path(trail);
 118
 119     if (PARENT_OBJECT_CLASS->finalize != NULL)
 120         PARENT_OBJECT_CLASS->finalize(object);
 121 }
 122
 123
 124 /**
 125  * adg_trail_new:
 126  * @callback: the #CpmlPath constructor function
 127  * @user_data: generic pointer to pass to the callback
 128  *
 129  * Creates a new trail model. The #CpmlPath must be constructed by the
 130  * @callback function: #AdgTrail will not cache anything, so you should
 131  * implement any caching mechanism in the callback, if needed.
 132  *
 133  * Returns: a new trail model
 134  **/
 135 AdgTrail *
 136 adg_trail_new(AdgTrailCallback callback, gpointer user_data)
 137 {
 138     AdgTrail *trail;
 139     AdgTrailPrivate *data;
 140
 141     trail = g_object_new(ADG_TYPE_TRAIL, NULL);
 142     data = trail->data;
 143
 144     data->callback = callback;
 145     data->user_data = user_data;
 146
 147     return trail;
 148 }
 149
 150
 151 /**
 152  * adg_trail_get_cairo_path:
 153  * @trail: an #AdgTrail
 154  *
 155  * Gets a pointer to the cairo path structure of @trail. The return path
 156  * is owned by @trail and must be considered read-only.
 157  *
 158  * This function also converts %CAIRO_PATH_ARC_TO primitives, not
 159  * recognized by cairo, into approximated Bézier curves. The conversion
 160  * is cached so any furter request is O(1). This cache is cleared
 161  * only after adg_trail_clear_cairo_path() is called.
 162  *
 163  * <important>
 164  * <title>TODO</title>
 165  * <itemizedlist>
 166  * <listitem>Actually, the arcs are approximated to Bézier using the
 167  *           hardcoded max angle of PI/2. This should be customizable
 168  *           by adding, for instance, a property to the #AdgTrail class
 169  *           with a default value of PI/2.</listitem>
 170  * </itemizedlist>
 171  * </important>
 172  *
 173  * Returns: a pointer to the internal cairo path or %NULL on errors
 174  **/
 175 const cairo_path_t *
 176 adg_trail_get_cairo_path(AdgTrail *trail)
 177 {
 178     g_return_val_if_fail(ADG_IS_TRAIL(trail), NULL);
 179
 180     return get_cairo_path(trail);
 181 }
 182
 183 /**
 184  * adg_trail_clear_cairo_path:
 185  * @trail: an #AdgTrail
 186  *
 187  * Clears the internal cairo path of @trail so it will be recomputed
 188  * the next time is requested throught adg_trail_get_cairo_path().
 189  **/
 190 void
 191 adg_trail_clear_cairo_path(AdgTrail *trail)
 192 {
 193     AdgTrailPrivate *data;
 194     cairo_path_t *cairo_path;
 195
 196     g_return_if_fail(ADG_IS_TRAIL(trail));
 197
 198     data = trail->data;
 199     cairo_path = &data->cairo_path;
 200
 201     if (cairo_path->data == NULL)
 202         return;
 203
 204     g_free(cairo_path->data);
 205
 206     cairo_path->status = CAIRO_STATUS_INVALID_PATH_DATA;
 207     cairo_path->data = NULL;
 208     cairo_path->num_data = 0;
 209 }
 210
 211 /**
 212  * adg_trail_get_cpml_path:
 213  * @trail: an #AdgTrail
 214  *
 215  * Gets a pointer to the CPML path structure of @trail. The return
 216  * value is owned by @trail and must not be freed.
 217  *
 218  * This function is similar to adg_trail_get_cairo_path() but with
 219  * two important differences: firstly the arc primitives are not
 220  * expanded to Bézier curves and secondly the returned path is
 221  * not read-only. This means it is allowed to modify the returned
 222  * path as long as its size is retained and its data contains a
 223  * valid path (this is needed by the #AdgMarker infrastructure).
 224  *
 225  * Any further call to this method will probably make the pointer
 226  * previously returned useless because the internal #CpmlPath could
 227  * be relocated and the old #CpmlPath will likely contain rubbish.
 228  *
 229  * Returns: a pointer to the internal #CpmlPath or %NULL on errors
 230  **/
 231 CpmlPath *
 232 adg_trail_get_cpml_path(AdgTrail *trail)
 233 {
 234     g_return_val_if_fail(ADG_IS_TRAIL(trail), NULL);
 235
 236     return ADG_TRAIL_GET_CLASS(trail)->get_cpml_path(trail);
 237 }
 238
 239 /**
 240  * adg_trail_get_segment:
 241  * @trail: an #AdgTrail
 242  * @segment: the destination #AdgSegment
 243  * @n: the segment number to retrieve, where %1 is the first segment
 244  *
 245  * Convenient function to get a segment from @trail. The segment is
 246  * got from the CPML path: check out adg_trail_get_cpml_path() for
 247  * further information.
 248  *
 249  * Returns: %TRUE on success or %FALSE on errors
 250  **/
 251 gboolean
 252 adg_trail_get_segment(AdgTrail *trail, AdgSegment *segment, guint n)
 253 {
 254     CpmlPath *cpml_path;
 255     guint cnt;
 256
 257     g_return_val_if_fail(ADG_IS_TRAIL(trail), FALSE);
 258     g_return_val_if_fail(segment != NULL, FALSE);
 259
 260     if (n == 0) {
 261         g_warning("%s: requested undefined segment for type `%s'",
 262                   G_STRLOC, g_type_name(G_OBJECT_TYPE(trail)));
 263         return FALSE;
 264     }
 265
 266     cpml_path = adg_trail_get_cpml_path(trail);
 267
 268     cpml_segment_from_cairo(segment, cpml_path);
 269     for (cnt = 1; cnt < n; ++cnt)
 270         if (!cpml_segment_next(segment)) {
 271             g_warning("%s: segment `%u' out of range for type `%s'",
 272                       G_STRLOC, n, g_type_name(G_OBJECT_TYPE(trail)));
 273             return FALSE;
 274         }
 275
 276     return TRUE;
 277 }
 278
 279 /**
 280  * adg_trail_dump:
 281  * @trail: an #AdgTrail
 282  *
 283  * Dumps the data content of @trail to stdout in a human readable format.
 284  **/
 285 void
 286 adg_trail_dump(AdgTrail *trail)
 287 {
 288     CpmlSegment segment;
 289     cairo_path_t *cairo_path;
 290
 291     g_return_if_fail(ADG_IS_TRAIL(trail));
 292
 293     cairo_path = get_cairo_path(trail);
 294
 295     g_return_if_fail(cairo_path != NULL);
 296
 297     if (!cpml_segment_from_cairo(&segment, cairo_path)) {
 298         g_warning("Invalid path data to dump!\n");
 299     } else {
 300         do {
 301             cpml_segment_dump(&segment);
 302         } while (cpml_segment_next(&segment));
 303     }
 304 }
 305
 306
 307 static cairo_path_t *
 308 get_cairo_path(AdgTrail *trail)
 309 {
 310     AdgTrailPrivate *data;
 311     cairo_path_t *cairo_path;
 312     CpmlPath *src;
 313     GArray *dst;
 314     const cairo_path_data_t *p_src;
 315     int i;
 316
 317     data = trail->data;
 318     cairo_path = &data->cairo_path;
 319
 320     /* Check for cached result */
 321     if (cairo_path->data != NULL)
 322         return cairo_path;
 323
 324     src = adg_trail_get_cpml_path(trail);
 325     dst = g_array_sized_new(FALSE, FALSE,
 326                             sizeof(cairo_path_data_t), src->num_data);
 327
 328     /* Cycle the CpmlPath and convert arcs to Bézier curves */
 329     for (i = 0; i < src->num_data; i += p_src->header.length) {
 330         p_src = (const cairo_path_data_t *) src->data + i;
 331
 332         if (p_src->header.type == CAIRO_PATH_ARC_TO)
 333             dst = arc_to_curves(dst, p_src);
 334         else
 335             dst = g_array_append_vals(dst, p_src, p_src->header.length);
 336     }
 337
 338     cairo_path->status = CAIRO_STATUS_SUCCESS;
 339     cairo_path->num_data = dst->len;
 340     cairo_path->data = (cairo_path_data_t *) g_array_free(dst, FALSE);
 341
 342     return cairo_path;
 343 }
 344
 345 static CpmlPath *
 346 get_cpml_path(AdgTrail *trail)
 347 {
 348     AdgTrailPrivate *data = trail->data;
 349
 350     if (data->callback == NULL) {
 351         g_warning("%s: callback not defined for instance of type `%s'",
 352                   G_STRLOC, g_type_name(G_OBJECT_TYPE(trail)));
 353         return NULL;
 354     }
 355
 356     return data->callback(trail, data->user_data);
 357 }
 358
 359 static GArray *
 360 arc_to_curves(GArray *array, const cairo_path_data_t *src)
 361 {
 362     CpmlPrimitive arc;
 363     double start, end;
 364
 365     /* Build the arc primitive: the arc origin is supposed to be the previous
 366      * point (src-1): this means a primitive must exist before the arc */
 367     arc.segment = NULL;
 368     arc.org = (cairo_path_data_t *) (src-1);
 369     arc.data = (cairo_path_data_t *) src;
 370
 371     if (cpml_arc_info(&arc, NULL, NULL, &start, &end)) {
 372         CpmlSegment segment;
 373         int n_curves;
 374         cairo_path_data_t *curves;
 375
 376         n_curves = ceil(fabs(end-start) / M_PI_2);
 377         curves = g_new(cairo_path_data_t, n_curves * 4);
 378         segment.data = curves;
 379         cpml_arc_to_curves(&arc, &segment, n_curves);
 380
 381         array = g_array_append_vals(array, curves, n_curves * 4);
 382
 383         g_free(curves);
 384     }
 385
 386     return array;
 387 }