Subversion Repositories Scribus

Rev

Rev 16124 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
14952 fschmid 1
/* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
2
/* cairo - a vector graphics library with display and print output
3
 *
4
 * Copyright © 2002 University of Southern California
5
 * Copyright © 2005 Red Hat, Inc.
6
 *
7
 * This library is free software; you can redistribute it and/or
8
 * modify it either under the terms of the GNU Lesser General Public
9
 * License version 2.1 as published by the Free Software Foundation
10
 * (the "LGPL") or, at your option, under the terms of the Mozilla
11
 * Public License Version 1.1 (the "MPL"). If you do not alter this
12
 * notice, a recipient may use your version of this file under either
13
 * the MPL or the LGPL.
14
 *
15
 * You should have received a copy of the LGPL along with this library
16
 * in the file COPYING-LGPL-2.1; if not, write to the Free Software
18122 mrdocs 17
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
14952 fschmid 18
 * You should have received a copy of the MPL along with this library
19
 * in the file COPYING-MPL-1.1
20
 *
21
 * The contents of this file are subject to the Mozilla Public License
22
 * Version 1.1 (the "License"); you may not use this file except in
23
 * compliance with the License. You may obtain a copy of the License at
24
 * http://www.mozilla.org/MPL/
25
 *
26
 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
27
 * OF ANY KIND, either express or implied. See the LGPL or the MPL for
28
 * the specific language governing rights and limitations.
29
 *
30
 * The Original Code is the cairo graphics library.
31
 *
32
 * The Initial Developer of the Original Code is University of Southern
33
 * California.
34
 *
35
 * Contributor(s):
36
 *      Carl D. Worth <cworth@cworth.org>
37
 */
38
 
39
#include "cairoint.h"
40
#include "cairo-private.h"
41
 
42
#include "cairo-arc-private.h"
43
#include "cairo-path-private.h"
44
 
45
#define CAIRO_TOLERANCE_MINIMUM _cairo_fixed_to_double(1)
46
 
47
#if !defined(INFINITY)
48
#define INFINITY HUGE_VAL
49
#endif
50
 
51
static const cairo_t _cairo_nil = {
52
  CAIRO_REFERENCE_COUNT_INVALID,        /* ref_count */
53
  CAIRO_STATUS_NO_MEMORY,       /* status */
54
  { 0, 0, 0, NULL },            /* user_data */
55
  NULL,                         /* gstate */
56
  {{ 0 }, { 0 }},               /* gstate_tail */
57
  NULL,                         /* gstate_freelist */
58
  {{                            /* path */
59
    { 0, 0 },                   /* last_move_point */
60
    { 0, 0 },                   /* current point */
61
    FALSE,                      /* has_current_point */
62
    FALSE,                      /* has_curve_to */
63
    FALSE,                      /* is_box */
64
    FALSE,                      /* maybe_fill_region */
65
    TRUE,                       /* is_empty_fill */
66
    {{{NULL,NULL}}}             /* link */
67
  }}
68
};
69
 
70
#include <assert.h>
71
 
72
/**
73
 * _cairo_error:
74
 * @status: a status value indicating an error, (eg. not
75
 * %CAIRO_STATUS_SUCCESS)
76
 *
77
 * Checks that status is an error status, but does nothing else.
78
 *
79
 * All assignments of an error status to any user-visible object
80
 * within the cairo application should result in a call to
81
 * _cairo_error().
82
 *
83
 * The purpose of this function is to allow the user to set a
84
 * breakpoint in _cairo_error() to generate a stack trace for when the
85
 * user causes cairo to detect an error.
86
 *
87
 * Return value: the error status.
88
 **/
89
cairo_status_t
90
_cairo_error (cairo_status_t status)
91
{
92
    assert (_cairo_status_is_error (status));
93
 
94
    return status;
95
}
96
 
97
/**
98
 * _cairo_set_error:
99
 * @cr: a cairo context
100
 * @status: a status value indicating an error
101
 *
102
 * Atomically sets cr->status to @status and calls _cairo_error;
103
 * Does nothing if status is %CAIRO_STATUS_SUCCESS.
104
 *
105
 * All assignments of an error status to cr->status should happen
106
 * through _cairo_set_error(). Note that due to the nature of the atomic
107
 * operation, it is not safe to call this function on the nil objects.
108
 *
109
 * The purpose of this function is to allow the user to set a
110
 * breakpoint in _cairo_error() to generate a stack trace for when the
111
 * user causes cairo to detect an error.
112
 **/
113
static void
114
_cairo_set_error (cairo_t *cr, cairo_status_t status)
115
{
116
    /* Don't overwrite an existing error. This preserves the first
117
     * error, which is the most significant. */
118
    _cairo_status_set_error (&cr->status, _cairo_error (status));
119
}
120
 
121
#if HAS_ATOMIC_OPS
122
/* We keep a small stash of contexts to reduce malloc pressure */
123
#define CAIRO_STASH_SIZE 4
124
static struct {
125
    cairo_t pool[CAIRO_STASH_SIZE];
126
    int occupied;
127
} _context_stash;
128
 
129
static cairo_t *
130
_context_get (void)
131
{
132
    int avail, old, new;
133
 
134
    do {
135
        old = _context_stash.occupied;
136
        avail = ffs (~old) - 1;
137
        if (avail >= CAIRO_STASH_SIZE)
138
            return malloc (sizeof (cairo_t));
139
 
140
        new = old | (1 << avail);
141
    } while (_cairo_atomic_int_cmpxchg (&_context_stash.occupied, old, new) != old);
142
 
143
    return &_context_stash.pool[avail];
144
}
145
 
146
static void
147
_context_put (cairo_t *cr)
148
{
149
    int old, new, avail;
150
 
151
    if (cr < &_context_stash.pool[0] ||
152
        cr >= &_context_stash.pool[CAIRO_STASH_SIZE])
153
    {
154
        free (cr);
155
        return;
156
    }
157
 
158
    avail = ~(1 << (cr - &_context_stash.pool[0]));
159
    do {
160
        old = _context_stash.occupied;
161
        new = old & avail;
162
    } while (_cairo_atomic_int_cmpxchg (&_context_stash.occupied, old, new) != old);
163
}
164
#else
165
#define _context_get() malloc (sizeof (cairo_t))
166
#define _context_put(cr) free (cr)
167
#endif
168
 
169
/**
170
 * cairo_create:
171
 * @target: target surface for the context
172
 *
173
 * Creates a new #cairo_t with all graphics state parameters set to
174
 * default values and with @target as a target surface. The target
175
 * surface should be constructed with a backend-specific function such
176
 * as cairo_image_surface_create() (or any other
177
 * cairo_<emphasis>backend</emphasis>_surface_create() variant).
178
 *
179
 * This function references @target, so you can immediately
180
 * call cairo_surface_destroy() on it if you don't need to
181
 * maintain a separate reference to it.
182
 *
183
 * Return value: a newly allocated #cairo_t with a reference
184
 *  count of 1. The initial reference count should be released
185
 *  with cairo_destroy() when you are done using the #cairo_t.
186
 *  This function never returns %NULL. If memory cannot be
187
 *  allocated, a special #cairo_t object will be returned on
188
 *  which cairo_status() returns %CAIRO_STATUS_NO_MEMORY.
189
 *  You can use this object normally, but no drawing will
190
 *  be done.
191
 **/
192
cairo_t *
193
cairo_create (cairo_surface_t *target)
194
{
195
    cairo_t *cr;
196
    cairo_status_t status;
197
 
198
    /* special case OOM in order to avoid another allocation */
199
    if (target && target->status == CAIRO_STATUS_NO_MEMORY)
200
        return (cairo_t *) &_cairo_nil;
201
 
202
    cr = _context_get ();
203
    if (unlikely (cr == NULL)) {
204
        status = _cairo_error (CAIRO_STATUS_NO_MEMORY);
205
        return (cairo_t *) &_cairo_nil;
206
    }
207
 
208
    CAIRO_REFERENCE_COUNT_INIT (&cr->ref_count, 1);
209
 
210
    cr->status = CAIRO_STATUS_SUCCESS;
211
 
212
    _cairo_user_data_array_init (&cr->user_data);
213
    _cairo_path_fixed_init (cr->path);
214
 
215
    cr->gstate = &cr->gstate_tail[0];
216
    cr->gstate_freelist = &cr->gstate_tail[1];
217
    cr->gstate_tail[1].next = NULL;
218
 
219
    status = _cairo_gstate_init (cr->gstate, target);
220
    if (unlikely (status))
221
        _cairo_set_error (cr, status);
222
 
223
    return cr;
224
}
225
slim_hidden_def (cairo_create);
226
 
227
/**
228
 * cairo_reference:
229
 * @cr: a #cairo_t
230
 *
231
 * Increases the reference count on @cr by one. This prevents
232
 * @cr from being destroyed until a matching call to cairo_destroy()
233
 * is made.
234
 *
235
 * The number of references to a #cairo_t can be get using
236
 * cairo_get_reference_count().
237
 *
238
 * Return value: the referenced #cairo_t.
239
 **/
240
cairo_t *
241
cairo_reference (cairo_t *cr)
242
{
243
    if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
244
        return cr;
245
 
246
    assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
247
 
248
    _cairo_reference_count_inc (&cr->ref_count);
249
 
250
    return cr;
251
}
252
 
253
/**
254
 * cairo_destroy:
255
 * @cr: a #cairo_t
256
 *
257
 * Decreases the reference count on @cr by one. If the result
258
 * is zero, then @cr and all associated resources are freed.
259
 * See cairo_reference().
260
 **/
261
void
262
cairo_destroy (cairo_t *cr)
263
{
264
    cairo_surface_t *surface;
265
 
266
    if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
267
        return;
268
 
269
    assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
270
 
271
    if (! _cairo_reference_count_dec_and_test (&cr->ref_count))
272
        return;
273
 
274
    while (cr->gstate != &cr->gstate_tail[0]) {
275
        if (_cairo_gstate_restore (&cr->gstate, &cr->gstate_freelist))
276
            break;
277
    }
278
 
279
    /* The context is expected (>99% of all use cases) to be held for the
280
     * duration of a single expose event/sequence of graphic operations.
281
     * Therefore, on destroy we explicitly flush the Cairo pipeline of any
282
     * pending operations.
283
     */
284
    surface = _cairo_gstate_get_original_target (cr->gstate);
285
    if (surface != NULL)
286
        cairo_surface_flush (surface);
287
 
288
    _cairo_gstate_fini (cr->gstate);
289
    cr->gstate_freelist = cr->gstate_freelist->next; /* skip over tail[1] */
290
    while (cr->gstate_freelist != NULL) {
291
        cairo_gstate_t *gstate = cr->gstate_freelist;
292
        cr->gstate_freelist = gstate->next;
293
        free (gstate);
294
    }
295
 
296
    _cairo_path_fixed_fini (cr->path);
297
 
298
    _cairo_user_data_array_fini (&cr->user_data);
299
 
300
    _context_put (cr);
301
}
302
slim_hidden_def (cairo_destroy);
303
 
304
/**
305
 * cairo_get_user_data:
306
 * @cr: a #cairo_t
307
 * @key: the address of the #cairo_user_data_key_t the user data was
308
 * attached to
309
 *
310
 * Return user data previously attached to @cr using the specified
311
 * key.  If no user data has been attached with the given key this
312
 * function returns %NULL.
313
 *
314
 * Return value: the user data previously attached or %NULL.
315
 *
316
 * Since: 1.4
317
 **/
318
void *
319
cairo_get_user_data (cairo_t                     *cr,
320
                     const cairo_user_data_key_t *key)
321
{
322
    return _cairo_user_data_array_get_data (&cr->user_data,
323
                                            key);
324
}
325
 
326
/**
327
 * cairo_set_user_data:
328
 * @cr: a #cairo_t
329
 * @key: the address of a #cairo_user_data_key_t to attach the user data to
330
 * @user_data: the user data to attach to the #cairo_t
331
 * @destroy: a #cairo_destroy_func_t which will be called when the
332
 * #cairo_t is destroyed or when new user data is attached using the
333
 * same key.
334
 *
335
 * Attach user data to @cr.  To remove user data from a surface,
336
 * call this function with the key that was used to set it and %NULL
337
 * for @data.
338
 *
339
 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
340
 * slot could not be allocated for the user data.
341
 *
342
 * Since: 1.4
343
 **/
344
cairo_status_t
345
cairo_set_user_data (cairo_t                     *cr,
346
                     const cairo_user_data_key_t *key,
347
                     void                        *user_data,
348
                     cairo_destroy_func_t        destroy)
349
{
350
    if (CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
351
        return cr->status;
352
 
353
    return _cairo_user_data_array_set_data (&cr->user_data,
354
                                            key, user_data, destroy);
355
}
356
 
357
/**
358
 * cairo_get_reference_count:
359
 * @cr: a #cairo_t
360
 *
361
 * Returns the current reference count of @cr.
362
 *
363
 * Return value: the current reference count of @cr.  If the
364
 * object is a nil object, 0 will be returned.
365
 *
366
 * Since: 1.4
367
 **/
368
unsigned int
369
cairo_get_reference_count (cairo_t *cr)
370
{
371
    if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
372
        return 0;
373
 
374
    return CAIRO_REFERENCE_COUNT_GET_VALUE (&cr->ref_count);
375
}
376
 
377
/**
378
 * cairo_save:
379
 * @cr: a #cairo_t
380
 *
381
 * Makes a copy of the current state of @cr and saves it
382
 * on an internal stack of saved states for @cr. When
383
 * cairo_restore() is called, @cr will be restored to
384
 * the saved state. Multiple calls to cairo_save() and
385
 * cairo_restore() can be nested; each call to cairo_restore()
386
 * restores the state from the matching paired cairo_save().
387
 *
388
 * It isn't necessary to clear all saved states before
389
 * a #cairo_t is freed. If the reference count of a #cairo_t
390
 * drops to zero in response to a call to cairo_destroy(),
391
 * any saved states will be freed along with the #cairo_t.
392
 **/
393
void
394
cairo_save (cairo_t *cr)
395
{
396
    cairo_status_t status;
397
 
398
    if (unlikely (cr->status))
399
        return;
400
 
401
    status = _cairo_gstate_save (&cr->gstate, &cr->gstate_freelist);
402
    if (unlikely (status))
403
        _cairo_set_error (cr, status);
404
}
405
slim_hidden_def(cairo_save);
406
 
407
/**
408
 * cairo_restore:
409
 * @cr: a #cairo_t
410
 *
411
 * Restores @cr to the state saved by a preceding call to
412
 * cairo_save() and removes that state from the stack of
413
 * saved states.
414
 **/
415
void
416
cairo_restore (cairo_t *cr)
417
{
418
    cairo_status_t status;
419
 
420
    if (unlikely (cr->status))
421
        return;
422
 
423
    status = _cairo_gstate_restore (&cr->gstate, &cr->gstate_freelist);
424
    if (unlikely (status))
425
        _cairo_set_error (cr, status);
426
}
427
slim_hidden_def(cairo_restore);
428
 
429
/**
430
 * cairo_push_group:
431
 * @cr: a cairo context
432
 *
433
 * Temporarily redirects drawing to an intermediate surface known as a
434
 * group. The redirection lasts until the group is completed by a call
435
 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
436
 * provide the result of any drawing to the group as a pattern,
437
 * (either as an explicit object, or set as the source pattern).
438
 *
439
 * This group functionality can be convenient for performing
440
 * intermediate compositing. One common use of a group is to render
441
 * objects as opaque within the group, (so that they occlude each
442
 * other), and then blend the result with translucence onto the
443
 * destination.
444
 *
445
 * Groups can be nested arbitrarily deep by making balanced calls to
446
 * cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new
447
 * target group onto/from a stack.
448
 *
449
 * The cairo_push_group() function calls cairo_save() so that any
450
 * changes to the graphics state will not be visible outside the
451
 * group, (the pop_group functions call cairo_restore()).
452
 *
453
 * By default the intermediate group will have a content type of
454
 * %CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for
455
 * the group by using cairo_push_group_with_content() instead.
456
 *
457
 * As an example, here is how one might fill and stroke a path with
458
 * translucence, but without any portion of the fill being visible
459
 * under the stroke:
460
 *
461
 * <informalexample><programlisting>
462
 * cairo_push_group (cr);
463
 * cairo_set_source (cr, fill_pattern);
464
 * cairo_fill_preserve (cr);
465
 * cairo_set_source (cr, stroke_pattern);
466
 * cairo_stroke (cr);
467
 * cairo_pop_group_to_source (cr);
468
 * cairo_paint_with_alpha (cr, alpha);
469
 * </programlisting></informalexample>
470
 *
471
 * Since: 1.2
472
 */
473
void
474
cairo_push_group (cairo_t *cr)
475
{
476
    cairo_push_group_with_content (cr, CAIRO_CONTENT_COLOR_ALPHA);
477
}
478
 
479
/**
480
 * cairo_push_group_with_content:
481
 * @cr: a cairo context
482
 * @content: a #cairo_content_t indicating the type of group that
483
 *           will be created
484
 *
485
 * Temporarily redirects drawing to an intermediate surface known as a
486
 * group. The redirection lasts until the group is completed by a call
487
 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
488
 * provide the result of any drawing to the group as a pattern,
489
 * (either as an explicit object, or set as the source pattern).
490
 *
491
 * The group will have a content type of @content. The ability to
492
 * control this content type is the only distinction between this
493
 * function and cairo_push_group() which you should see for a more
494
 * detailed description of group rendering.
495
 *
496
 * Since: 1.2
497
 */
498
void
499
cairo_push_group_with_content (cairo_t *cr, cairo_content_t content)
500
{
501
    cairo_status_t status;
502
    cairo_rectangle_int_t extents;
503
    const cairo_rectangle_int_t *clip_extents;
504
    cairo_surface_t *parent_surface, *group_surface = NULL;
505
    cairo_bool_t is_empty;
506
 
507
    if (unlikely (cr->status))
508
        return;
509
 
510
    parent_surface = _cairo_gstate_get_target (cr->gstate);
511
 
512
    /* Get the extents that we'll use in creating our new group surface */
513
    is_empty = _cairo_surface_get_extents (parent_surface, &extents);
514
    clip_extents = _cairo_clip_get_extents (_cairo_gstate_get_clip (cr->gstate));
515
    if (clip_extents != NULL)
516
        is_empty = _cairo_rectangle_intersect (&extents, clip_extents);
517
 
518
    group_surface = _cairo_surface_create_similar_solid (parent_surface,
519
                                                         content,
520
                                                         extents.width,
521
                                                         extents.height,
522
                                                         CAIRO_COLOR_TRANSPARENT,
523
                                                         TRUE);
524
    status = group_surface->status;
525
    if (unlikely (status))
526
        goto bail;
527
 
528
    /* Set device offsets on the new surface so that logically it appears at
529
     * the same location on the parent surface -- when we pop_group this,
530
     * the source pattern will get fixed up for the appropriate target surface
531
     * device offsets, so we want to set our own surface offsets from /that/,
532
     * and not from the device origin. */
533
    cairo_surface_set_device_offset (group_surface,
534
                                     parent_surface->device_transform.x0 - extents.x,
535
                                     parent_surface->device_transform.y0 - extents.y);
536
 
537
    /* If we have a current path, we need to adjust it to compensate for
538
     * the device offset just applied. */
539
    _cairo_path_fixed_transform (cr->path,
540
                                 &group_surface->device_transform);
541
 
542
    /* create a new gstate for the redirect */
543
    cairo_save (cr);
544
    if (unlikely (cr->status))
545
        goto bail;
546
 
547
    status = _cairo_gstate_redirect_target (cr->gstate, group_surface);
548
 
549
bail:
550
    cairo_surface_destroy (group_surface);
551
    if (unlikely (status))
552
        _cairo_set_error (cr, status);
553
}
554
slim_hidden_def(cairo_push_group_with_content);
555
 
556
/**
557
 * cairo_pop_group:
558
 * @cr: a cairo context
559
 *
560
 * Terminates the redirection begun by a call to cairo_push_group() or
561
 * cairo_push_group_with_content() and returns a new pattern
562
 * containing the results of all drawing operations performed to the
563
 * group.
564
 *
565
 * The cairo_pop_group() function calls cairo_restore(), (balancing a
566
 * call to cairo_save() by the push_group function), so that any
567
 * changes to the graphics state will not be visible outside the
568
 * group.
569
 *
570
 * Return value: a newly created (surface) pattern containing the
571
 * results of all drawing operations performed to the group. The
572
 * caller owns the returned object and should call
573
 * cairo_pattern_destroy() when finished with it.
574
 *
575
 * Since: 1.2
576
 **/
577
cairo_pattern_t *
578
cairo_pop_group (cairo_t *cr)
579
{
580
    cairo_surface_t *group_surface, *parent_target;
581
    cairo_pattern_t *group_pattern;
582
    cairo_matrix_t group_matrix;
583
    cairo_status_t status;
584
 
585
    if (unlikely (cr->status))
586
        return _cairo_pattern_create_in_error (cr->status);
587
 
588
    /* Grab the active surfaces */
589
    group_surface = _cairo_gstate_get_target (cr->gstate);
590
    parent_target = _cairo_gstate_get_parent_target (cr->gstate);
591
 
592
    /* Verify that we are at the right nesting level */
593
    if (parent_target == NULL) {
594
        _cairo_set_error (cr, CAIRO_STATUS_INVALID_POP_GROUP);
595
        return _cairo_pattern_create_in_error (CAIRO_STATUS_INVALID_POP_GROUP);
596
    }
597
 
598
    /* We need to save group_surface before we restore; we don't need
599
     * to reference parent_target and original_target, since the
600
     * gstate will still hold refs to them once we restore. */
601
    group_surface = cairo_surface_reference (group_surface);
602
 
603
    cairo_restore (cr);
604
 
605
    if (unlikely (cr->status)) {
606
        group_pattern = _cairo_pattern_create_in_error (cr->status);
607
        goto done;
608
    }
609
 
610
    group_pattern = cairo_pattern_create_for_surface (group_surface);
611
    status = group_pattern->status;
612
    if (unlikely (status)) {
613
        _cairo_set_error (cr, status);
614
        goto done;
615
    }
616
 
617
    _cairo_gstate_get_matrix (cr->gstate, &group_matrix);
618
    /* Transform by group_matrix centered around device_transform so that when
619
     * we call _cairo_gstate_copy_transformed_pattern the result is a pattern
620
     * with a matrix equivalent to the device_transform of group_surface. */
621
    if (_cairo_surface_has_device_transform (group_surface)) {
622
        cairo_pattern_set_matrix (group_pattern, &group_surface->device_transform);
623
        _cairo_pattern_transform (group_pattern, &group_matrix);
624
        _cairo_pattern_transform (group_pattern, &group_surface->device_transform_inverse);
625
    } else {
626
        cairo_pattern_set_matrix (group_pattern, &group_matrix);
627
    }
628
 
629
    /* If we have a current path, we need to adjust it to compensate for
630
     * the device offset just removed. */
631
    _cairo_path_fixed_transform (cr->path,
632
                                 &group_surface->device_transform_inverse);
633
 
634
done:
635
    cairo_surface_destroy (group_surface);
636
 
637
    return group_pattern;
638
}
639
slim_hidden_def(cairo_pop_group);
640
 
641
/**
642
 * cairo_pop_group_to_source:
643
 * @cr: a cairo context
644
 *
645
 * Terminates the redirection begun by a call to cairo_push_group() or
646
 * cairo_push_group_with_content() and installs the resulting pattern
647
 * as the source pattern in the given cairo context.
648
 *
649
 * The behavior of this function is equivalent to the sequence of
650
 * operations:
651
 *
652
 * <informalexample><programlisting>
653
 * #cairo_pattern_t *group = cairo_pop_group (cr);
654
 * cairo_set_source (cr, group);
655
 * cairo_pattern_destroy (group);
656
 * </programlisting></informalexample>
657
 *
658
 * but is more convenient as their is no need for a variable to store
659
 * the short-lived pointer to the pattern.
660
 *
661
 * The cairo_pop_group() function calls cairo_restore(), (balancing a
662
 * call to cairo_save() by the push_group function), so that any
663
 * changes to the graphics state will not be visible outside the
664
 * group.
665
 *
666
 * Since: 1.2
667
 **/
668
void
669
cairo_pop_group_to_source (cairo_t *cr)
670
{
671
    cairo_pattern_t *group_pattern;
672
 
673
    group_pattern = cairo_pop_group (cr);
674
    cairo_set_source (cr, group_pattern);
675
    cairo_pattern_destroy (group_pattern);
676
}
677
 
678
/**
679
 * cairo_set_operator:
680
 * @cr: a #cairo_t
681
 * @op: a compositing operator, specified as a #cairo_operator_t
682
 *
683
 * Sets the compositing operator to be used for all drawing
684
 * operations. See #cairo_operator_t for details on the semantics of
685
 * each available compositing operator.
686
 *
687
 * The default operator is %CAIRO_OPERATOR_OVER.
688
 **/
689
void
690
cairo_set_operator (cairo_t *cr, cairo_operator_t op)
691
{
692
    cairo_status_t status;
693
 
694
    if (unlikely (cr->status))
695
        return;
696
 
697
    status = _cairo_gstate_set_operator (cr->gstate, op);
698
    if (unlikely (status))
699
        _cairo_set_error (cr, status);
700
}
701
slim_hidden_def (cairo_set_operator);
702
 
703
 
704
static cairo_bool_t
705
_current_source_matches_solid (cairo_t *cr,
706
                               double red,
707
                               double green,
708
                               double blue,
709
                               double alpha)
710
{
711
    const cairo_pattern_t *current;
712
    cairo_color_t color;
713
 
714
    current = cr->gstate->source;
715
    if (current->type != CAIRO_PATTERN_TYPE_SOLID)
716
        return FALSE;
717
 
718
    red   = _cairo_restrict_value (red,   0.0, 1.0);
719
    green = _cairo_restrict_value (green, 0.0, 1.0);
720
    blue  = _cairo_restrict_value (blue,  0.0, 1.0);
721
    alpha = _cairo_restrict_value (alpha, 0.0, 1.0);
722
 
723
    _cairo_color_init_rgba (&color, red, green, blue, alpha);
724
    return _cairo_color_equal (&color,
725
                               &((cairo_solid_pattern_t *) current)->color);
726
}
727
/**
728
 * cairo_set_source_rgb
729
 * @cr: a cairo context
730
 * @red: red component of color
731
 * @green: green component of color
732
 * @blue: blue component of color
733
 *
734
 * Sets the source pattern within @cr to an opaque color. This opaque
735
 * color will then be used for any subsequent drawing operation until
736
 * a new source pattern is set.
737
 *
738
 * The color components are floating point numbers in the range 0 to
739
 * 1. If the values passed in are outside that range, they will be
740
 * clamped.
741
 *
742
 * The default source pattern is opaque black, (that is, it is
743
 * equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
744
 **/
745
void
746
cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
747
{
748
    cairo_pattern_t *pattern;
749
 
750
    if (unlikely (cr->status))
751
        return;
752
 
753
    if (_current_source_matches_solid (cr, red, green, blue, 1.))
754
        return;
755
 
756
    /* push the current pattern to the freed lists */
757
    cairo_set_source (cr, (cairo_pattern_t *) &_cairo_pattern_black);
758
 
759
    pattern = cairo_pattern_create_rgb (red, green, blue);
760
    cairo_set_source (cr, pattern);
761
    cairo_pattern_destroy (pattern);
762
}
763
slim_hidden_def (cairo_set_source_rgb);
764
 
765
/**
766
 * cairo_set_source_rgba:
767
 * @cr: a cairo context
768
 * @red: red component of color
769
 * @green: green component of color
770
 * @blue: blue component of color
771
 * @alpha: alpha component of color
772
 *
773
 * Sets the source pattern within @cr to a translucent color. This
774
 * color will then be used for any subsequent drawing operation until
775
 * a new source pattern is set.
776
 *
777
 * The color and alpha components are floating point numbers in the
778
 * range 0 to 1. If the values passed in are outside that range, they
779
 * will be clamped.
780
 *
781
 * The default source pattern is opaque black, (that is, it is
782
 * equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).
783
 **/
784
void
785
cairo_set_source_rgba (cairo_t *cr,
786
                       double red, double green, double blue,
787
                       double alpha)
788
{
789
    cairo_pattern_t *pattern;
790
 
791
    if (unlikely (cr->status))
792
        return;
793
 
794
    if (_current_source_matches_solid (cr, red, green, blue, alpha))
795
        return;
796
 
797
    /* push the current pattern to the freed lists */
798
    cairo_set_source (cr, (cairo_pattern_t *) &_cairo_pattern_black);
799
 
800
    pattern = cairo_pattern_create_rgba (red, green, blue, alpha);
801
    cairo_set_source (cr, pattern);
802
    cairo_pattern_destroy (pattern);
803
}
804
 
805
/**
806
 * cairo_set_source_surface:
807
 * @cr: a cairo context
808
 * @surface: a surface to be used to set the source pattern
809
 * @x: User-space X coordinate for surface origin
810
 * @y: User-space Y coordinate for surface origin
811
 *
812
 * This is a convenience function for creating a pattern from @surface
813
 * and setting it as the source in @cr with cairo_set_source().
814
 *
815
 * The @x and @y parameters give the user-space coordinate at which
816
 * the surface origin should appear. (The surface origin is its
817
 * upper-left corner before any transformation has been applied.) The
818
 * @x and @y patterns are negated and then set as translation values
819
 * in the pattern matrix.
820
 *
821
 * Other than the initial translation pattern matrix, as described
822
 * above, all other pattern attributes, (such as its extend mode), are
823
 * set to the default values as in cairo_pattern_create_for_surface().
824
 * The resulting pattern can be queried with cairo_get_source() so
825
 * that these attributes can be modified if desired, (eg. to create a
826
 * repeating pattern with cairo_pattern_set_extend()).
827
 **/
828
void
829
cairo_set_source_surface (cairo_t         *cr,
830
                          cairo_surface_t *surface,
831
                          double           x,
832
                          double           y)
833
{
834
    cairo_pattern_t *pattern;
835
    cairo_matrix_t matrix;
836
 
837
    if (unlikely (cr->status))
838
        return;
839
 
840
    /* push the current pattern to the freed lists */
841
    cairo_set_source (cr, (cairo_pattern_t *) &_cairo_pattern_black);
842
 
843
    pattern = cairo_pattern_create_for_surface (surface);
844
 
845
    cairo_matrix_init_translate (&matrix, -x, -y);
846
    cairo_pattern_set_matrix (pattern, &matrix);
847
 
848
    cairo_set_source (cr, pattern);
849
    cairo_pattern_destroy (pattern);
850
}
851
slim_hidden_def (cairo_set_source_surface);
852
 
853
/**
854
 * cairo_set_source
855
 * @cr: a cairo context
856
 * @source: a #cairo_pattern_t to be used as the source for
857
 * subsequent drawing operations.
858
 *
859
 * Sets the source pattern within @cr to @source. This pattern
860
 * will then be used for any subsequent drawing operation until a new
861
 * source pattern is set.
862
 *
863
 * Note: The pattern's transformation matrix will be locked to the
864
 * user space in effect at the time of cairo_set_source(). This means
865
 * that further modifications of the current transformation matrix
866
 * will not affect the source pattern. See cairo_pattern_set_matrix().
867
 *
868
 * The default source pattern is a solid pattern that is opaque black,
869
 * (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0,
870
 * 0.0)).
871
 **/
872
void
873
cairo_set_source (cairo_t *cr, cairo_pattern_t *source)
874
{
875
    cairo_status_t status;
876
 
877
    if (unlikely (cr->status))
878
        return;
879
 
880
    if (source == NULL) {
881
        _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
882
        return;
883
    }
884
 
885
    if (source->status) {
886
        _cairo_set_error (cr, source->status);
887
        return;
888
    }
889
 
890
    status = _cairo_gstate_set_source (cr->gstate, source);
891
    if (unlikely (status))
892
        _cairo_set_error (cr, status);
893
}
894
slim_hidden_def (cairo_set_source);
895
 
896
/**
897
 * cairo_get_source:
898
 * @cr: a cairo context
899
 *
900
 * Gets the current source pattern for @cr.
901
 *
902
 * Return value: the current source pattern. This object is owned by
903
 * cairo. To keep a reference to it, you must call
904
 * cairo_pattern_reference().
905
 **/
906
cairo_pattern_t *
907
cairo_get_source (cairo_t *cr)
908
{
909
    if (unlikely (cr->status))
910
        return _cairo_pattern_create_in_error (cr->status);
911
 
912
    return _cairo_gstate_get_source (cr->gstate);
913
}
914
 
915
/**
916
 * cairo_set_tolerance:
917
 * @cr: a #cairo_t
918
 * @tolerance: the tolerance, in device units (typically pixels)
919
 *
920
 * Sets the tolerance used when converting paths into trapezoids.
921
 * Curved segments of the path will be subdivided until the maximum
922
 * deviation between the original path and the polygonal approximation
923
 * is less than @tolerance. The default value is 0.1. A larger
924
 * value will give better performance, a smaller value, better
925
 * appearance. (Reducing the value from the default value of 0.1
926
 * is unlikely to improve appearance significantly.)  The accuracy of paths
927
 * within Cairo is limited by the precision of its internal arithmetic, and
928
 * the prescribed @tolerance is restricted to the smallest
929
 * representable internal value.
930
 **/
931
void
932
cairo_set_tolerance (cairo_t *cr, double tolerance)
933
{
934
    cairo_status_t status;
935
 
936
    if (unlikely (cr->status))
937
        return;
938
 
939
    if (tolerance < CAIRO_TOLERANCE_MINIMUM)
940
        tolerance = CAIRO_TOLERANCE_MINIMUM;
941
 
942
    status = _cairo_gstate_set_tolerance (cr->gstate, tolerance);
943
    if (unlikely (status))
944
        _cairo_set_error (cr, status);
945
}
946
slim_hidden_def (cairo_set_tolerance);
947
 
948
/**
949
 * cairo_set_antialias:
950
 * @cr: a #cairo_t
951
 * @antialias: the new antialiasing mode
952
 *
953
 * Set the antialiasing mode of the rasterizer used for drawing shapes.
954
 * This value is a hint, and a particular backend may or may not support
955
 * a particular value.  At the current time, no backend supports
956
 * %CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.
957
 *
958
 * Note that this option does not affect text rendering, instead see
959
 * cairo_font_options_set_antialias().
960
 **/
961
void
962
cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias)
963
{
964
    cairo_status_t status;
965
 
966
    if (unlikely (cr->status))
967
        return;
968
 
969
    status = _cairo_gstate_set_antialias (cr->gstate, antialias);
970
    if (unlikely (status))
971
        _cairo_set_error (cr, status);
972
}
973
 
974
/**
975
 * cairo_set_fill_rule:
976
 * @cr: a #cairo_t
977
 * @fill_rule: a fill rule, specified as a #cairo_fill_rule_t
978
 *
979
 * Set the current fill rule within the cairo context. The fill rule
980
 * is used to determine which regions are inside or outside a complex
981
 * (potentially self-intersecting) path. The current fill rule affects
982
 * both cairo_fill() and cairo_clip(). See #cairo_fill_rule_t for details
983
 * on the semantics of each available fill rule.
984
 *
985
 * The default fill rule is %CAIRO_FILL_RULE_WINDING.
986
 **/
987
void
988
cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
989
{
990
    cairo_status_t status;
991
 
992
    if (unlikely (cr->status))
993
        return;
994
 
995
    status = _cairo_gstate_set_fill_rule (cr->gstate, fill_rule);
996
    if (unlikely (status))
997
        _cairo_set_error (cr, status);
998
}
999
 
1000
/**
1001
 * cairo_set_line_width:
1002
 * @cr: a #cairo_t
1003
 * @width: a line width
1004
 *
1005
 * Sets the current line width within the cairo context. The line
1006
 * width value specifies the diameter of a pen that is circular in
1007
 * user space, (though device-space pen may be an ellipse in general
1008
 * due to scaling/shear/rotation of the CTM).
1009
 *
1010
 * Note: When the description above refers to user space and CTM it
1011
 * refers to the user space and CTM in effect at the time of the
1012
 * stroking operation, not the user space and CTM in effect at the
1013
 * time of the call to cairo_set_line_width(). The simplest usage
1014
 * makes both of these spaces identical. That is, if there is no
1015
 * change to the CTM between a call to cairo_set_line_width() and the
1016
 * stroking operation, then one can just pass user-space values to
1017
 * cairo_set_line_width() and ignore this note.
1018
 *
1019
 * As with the other stroke parameters, the current line width is
1020
 * examined by cairo_stroke(), cairo_stroke_extents(), and
1021
 * cairo_stroke_to_path(), but does not have any effect during path
1022
 * construction.
1023
 *
1024
 * The default line width value is 2.0.
1025
 **/
1026
void
1027
cairo_set_line_width (cairo_t *cr, double width)
1028
{
1029
    cairo_status_t status;
1030
 
1031
    if (unlikely (cr->status))
1032
        return;
1033
 
1034
    if (width < 0.)
1035
        width = 0.;
1036
 
1037
    status = _cairo_gstate_set_line_width (cr->gstate, width);
1038
    if (unlikely (status))
1039
        _cairo_set_error (cr, status);
1040
}
1041
slim_hidden_def (cairo_set_line_width);
1042
 
1043
/**
1044
 * cairo_set_line_cap:
1045
 * @cr: a cairo context
1046
 * @line_cap: a line cap style
1047
 *
1048
 * Sets the current line cap style within the cairo context. See
1049
 * #cairo_line_cap_t for details about how the available line cap
1050
 * styles are drawn.
1051
 *
1052
 * As with the other stroke parameters, the current line cap style is
1053
 * examined by cairo_stroke(), cairo_stroke_extents(), and
1054
 * cairo_stroke_to_path(), but does not have any effect during path
1055
 * construction.
1056
 *
1057
 * The default line cap style is %CAIRO_LINE_CAP_BUTT.
1058
 **/
1059
void
1060
cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
1061
{
1062
    cairo_status_t status;
1063
 
1064
    if (unlikely (cr->status))
1065
        return;
1066
 
1067
    status = _cairo_gstate_set_line_cap (cr->gstate, line_cap);
1068
    if (unlikely (status))
1069
        _cairo_set_error (cr, status);
1070
}
1071
slim_hidden_def (cairo_set_line_cap);
1072
 
1073
/**
1074
 * cairo_set_line_join:
1075
 * @cr: a cairo context
1076
 * @line_join: a line join style
1077
 *
1078
 * Sets the current line join style within the cairo context. See
1079
 * #cairo_line_join_t for details about how the available line join
1080
 * styles are drawn.
1081
 *
1082
 * As with the other stroke parameters, the current line join style is
1083
 * examined by cairo_stroke(), cairo_stroke_extents(), and
1084
 * cairo_stroke_to_path(), but does not have any effect during path
1085
 * construction.
1086
 *
1087
 * The default line join style is %CAIRO_LINE_JOIN_MITER.
1088
 **/
1089
void
1090
cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
1091
{
1092
    cairo_status_t status;
1093
 
1094
    if (unlikely (cr->status))
1095
        return;
1096
 
1097
    status = _cairo_gstate_set_line_join (cr->gstate, line_join);
1098
    if (unlikely (status))
1099
        _cairo_set_error (cr, status);
1100
}
1101
slim_hidden_def (cairo_set_line_join);
1102
 
1103
/**
1104
 * cairo_set_dash:
1105
 * @cr: a cairo context
1106
 * @dashes: an array specifying alternate lengths of on and off stroke portions
1107
 * @num_dashes: the length of the dashes array
1108
 * @offset: an offset into the dash pattern at which the stroke should start
1109
 *
1110
 * Sets the dash pattern to be used by cairo_stroke(). A dash pattern
1111
 * is specified by @dashes, an array of positive values. Each value
1112
 * provides the length of alternate "on" and "off" portions of the
1113
 * stroke. The @offset specifies an offset into the pattern at which
1114
 * the stroke begins.
1115
 *
1116
 * Each "on" segment will have caps applied as if the segment were a
1117
 * separate sub-path. In particular, it is valid to use an "on" length
1118
 * of 0.0 with %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE in order
1119
 * to distributed dots or squares along a path.
1120
 *
1121
 * Note: The length values are in user-space units as evaluated at the
1122
 * time of stroking. This is not necessarily the same as the user
1123
 * space at the time of cairo_set_dash().
1124
 *
1125
 * If @num_dashes is 0 dashing is disabled.
1126
 *
1127
 * If @num_dashes is 1 a symmetric pattern is assumed with alternating
1128
 * on and off portions of the size specified by the single value in
1129
 * @dashes.
1130
 *
1131
 * If any value in @dashes is negative, or if all values are 0, then
1132
 * @cr will be put into an error state with a status of
1133
 * %CAIRO_STATUS_INVALID_DASH.
1134
 **/
1135
void
1136
cairo_set_dash (cairo_t      *cr,
1137
                const double *dashes,
1138
                int           num_dashes,
1139
                double        offset)
1140
{
1141
    cairo_status_t status;
1142
 
1143
    if (unlikely (cr->status))
1144
        return;
1145
 
1146
    status = _cairo_gstate_set_dash (cr->gstate,
1147
                                     dashes, num_dashes, offset);
1148
    if (unlikely (status))
1149
        _cairo_set_error (cr, status);
1150
}
1151
 
1152
/**
1153
 * cairo_get_dash_count:
1154
 * @cr: a #cairo_t
1155
 *
1156
 * This function returns the length of the dash array in @cr (0 if dashing
1157
 * is not currently in effect).
1158
 *
1159
 * See also cairo_set_dash() and cairo_get_dash().
1160
 *
1161
 * Return value: the length of the dash array, or 0 if no dash array set.
1162
 *
1163
 * Since: 1.4
1164
 */
1165
int
1166
cairo_get_dash_count (cairo_t *cr)
1167
{
1168
    int num_dashes;
1169
 
1170
    if (unlikely (cr->status))
1171
        return 0;
1172
 
1173
    _cairo_gstate_get_dash (cr->gstate, NULL, &num_dashes, NULL);
1174
 
1175
    return num_dashes;
1176
}
1177
 
1178
/**
1179
 * cairo_get_dash:
1180
 * @cr: a #cairo_t
1181
 * @dashes: return value for the dash array, or %NULL
1182
 * @offset: return value for the current dash offset, or %NULL
1183
 *
1184
 * Gets the current dash array.  If not %NULL, @dashes should be big
1185
 * enough to hold at least the number of values returned by
1186
 * cairo_get_dash_count().
1187
 *
1188
 * Since: 1.4
1189
 **/
1190
void
1191
cairo_get_dash (cairo_t *cr,
1192
                double  *dashes,
1193
                double  *offset)
1194
{
1195
    if (unlikely (cr->status))
1196
        return;
1197
 
1198
    _cairo_gstate_get_dash (cr->gstate, dashes, NULL, offset);
1199
}
1200
 
1201
/**
1202
 * cairo_set_miter_limit:
1203
 * @cr: a cairo context
1204
 * @limit: miter limit to set
1205
 *
1206
 * Sets the current miter limit within the cairo context.
1207
 *
1208
 * If the current line join style is set to %CAIRO_LINE_JOIN_MITER
1209
 * (see cairo_set_line_join()), the miter limit is used to determine
1210
 * whether the lines should be joined with a bevel instead of a miter.
1211
 * Cairo divides the length of the miter by the line width.
1212
 * If the result is greater than the miter limit, the style is
1213
 * converted to a bevel.
1214
 *
1215
 * As with the other stroke parameters, the current line miter limit is
1216
 * examined by cairo_stroke(), cairo_stroke_extents(), and
1217
 * cairo_stroke_to_path(), but does not have any effect during path
1218
 * construction.
1219
 *
1220
 * The default miter limit value is 10.0, which will convert joins
1221
 * with interior angles less than 11 degrees to bevels instead of
1222
 * miters. For reference, a miter limit of 2.0 makes the miter cutoff
1223
 * at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90
1224
 * degrees.
1225
 *
1226
 * A miter limit for a desired angle can be computed as: miter limit =
1227
 * 1/sin(angle/2)
1228
 **/
1229
void
1230
cairo_set_miter_limit (cairo_t *cr, double limit)
1231
{
1232
    cairo_status_t status;
1233
 
1234
    if (unlikely (cr->status))
1235
        return;
1236
 
1237
    status = _cairo_gstate_set_miter_limit (cr->gstate, limit);
1238
    if (unlikely (status))
1239
        _cairo_set_error (cr, status);
1240
}
1241
 
1242
/**
1243
 * cairo_translate:
1244
 * @cr: a cairo context
1245
 * @tx: amount to translate in the X direction
1246
 * @ty: amount to translate in the Y direction
1247
 *
1248
 * Modifies the current transformation matrix (CTM) by translating the
1249
 * user-space origin by (@tx, @ty). This offset is interpreted as a
1250
 * user-space coordinate according to the CTM in place before the new
1251
 * call to cairo_translate(). In other words, the translation of the
1252
 * user-space origin takes place after any existing transformation.
1253
 **/
1254
void
1255
cairo_translate (cairo_t *cr, double tx, double ty)
1256
{
1257
    cairo_status_t status;
1258
 
1259
    if (unlikely (cr->status))
1260
        return;
1261
 
1262
    status = _cairo_gstate_translate (cr->gstate, tx, ty);
1263
    if (unlikely (status))
1264
        _cairo_set_error (cr, status);
1265
}
1266
slim_hidden_def (cairo_translate);
1267
 
1268
/**
1269
 * cairo_scale:
1270
 * @cr: a cairo context
1271
 * @sx: scale factor for the X dimension
1272
 * @sy: scale factor for the Y dimension
1273
 *
1274
 * Modifies the current transformation matrix (CTM) by scaling the X
1275
 * and Y user-space axes by @sx and @sy respectively. The scaling of
1276
 * the axes takes place after any existing transformation of user
1277
 * space.
1278
 **/
1279
void
1280
cairo_scale (cairo_t *cr, double sx, double sy)
1281
{
1282
    cairo_status_t status;
1283
 
1284
    if (unlikely (cr->status))
1285
        return;
1286
 
1287
    status = _cairo_gstate_scale (cr->gstate, sx, sy);
1288
    if (unlikely (status))
1289
        _cairo_set_error (cr, status);
1290
}
1291
slim_hidden_def (cairo_scale);
1292
 
1293
/**
1294
 * cairo_rotate:
1295
 * @cr: a cairo context
1296
 * @angle: angle (in radians) by which the user-space axes will be
1297
 * rotated
1298
 *
1299
 * Modifies the current transformation matrix (CTM) by rotating the
1300
 * user-space axes by @angle radians. The rotation of the axes takes
1301
 * places after any existing transformation of user space. The
1302
 * rotation direction for positive angles is from the positive X axis
1303
 * toward the positive Y axis.
1304
 **/
1305
void
1306
cairo_rotate (cairo_t *cr, double angle)
1307
{
1308
    cairo_status_t status;
1309
 
1310
    if (unlikely (cr->status))
1311
        return;
1312
 
1313
    status = _cairo_gstate_rotate (cr->gstate, angle);
1314
    if (unlikely (status))
1315
        _cairo_set_error (cr, status);
1316
}
1317
 
1318
/**
1319
 * cairo_transform:
1320
 * @cr: a cairo context
1321
 * @matrix: a transformation to be applied to the user-space axes
1322
 *
1323
 * Modifies the current transformation matrix (CTM) by applying
1324
 * @matrix as an additional transformation. The new transformation of
1325
 * user space takes place after any existing transformation.
1326
 **/
1327
void
1328
cairo_transform (cairo_t              *cr,
1329
                 const cairo_matrix_t *matrix)
1330
{
1331
    cairo_status_t status;
1332
 
1333
    if (unlikely (cr->status))
1334
        return;
1335
 
1336
    status = _cairo_gstate_transform (cr->gstate, matrix);
1337
    if (unlikely (status))
1338
        _cairo_set_error (cr, status);
1339
}
1340
slim_hidden_def (cairo_transform);
1341
 
1342
/**
1343
 * cairo_set_matrix:
1344
 * @cr: a cairo context
1345
 * @matrix: a transformation matrix from user space to device space
1346
 *
1347
 * Modifies the current transformation matrix (CTM) by setting it
1348
 * equal to @matrix.
1349
 **/
1350
void
1351
cairo_set_matrix (cairo_t              *cr,
1352
                  const cairo_matrix_t *matrix)
1353
{
1354
    cairo_status_t status;
1355
 
1356
    if (unlikely (cr->status))
1357
        return;
1358
 
1359
    status = _cairo_gstate_set_matrix (cr->gstate, matrix);
1360
    if (unlikely (status))
1361
        _cairo_set_error (cr, status);
1362
}
1363
slim_hidden_def (cairo_set_matrix);
1364
 
1365
/**
1366
 * cairo_identity_matrix:
1367
 * @cr: a cairo context
1368
 *
1369
 * Resets the current transformation matrix (CTM) by setting it equal
1370
 * to the identity matrix. That is, the user-space and device-space
1371
 * axes will be aligned and one user-space unit will transform to one
1372
 * device-space unit.
1373
 **/
1374
void
1375
cairo_identity_matrix (cairo_t *cr)
1376
{
1377
    if (unlikely (cr->status))
1378
        return;
1379
 
1380
    _cairo_gstate_identity_matrix (cr->gstate);
1381
}
1382
 
1383
/**
1384
 * cairo_user_to_device:
1385
 * @cr: a cairo context
1386
 * @x: X value of coordinate (in/out parameter)
1387
 * @y: Y value of coordinate (in/out parameter)
1388
 *
1389
 * Transform a coordinate from user space to device space by
1390
 * multiplying the given point by the current transformation matrix
1391
 * (CTM).
1392
 **/
1393
void
1394
cairo_user_to_device (cairo_t *cr, double *x, double *y)
1395
{
1396
    if (unlikely (cr->status))
1397
        return;
1398
 
1399
    _cairo_gstate_user_to_device (cr->gstate, x, y);
1400
}
1401
slim_hidden_def (cairo_user_to_device);
1402
 
1403
/**
1404
 * cairo_user_to_device_distance:
1405
 * @cr: a cairo context
1406
 * @dx: X component of a distance vector (in/out parameter)
1407
 * @dy: Y component of a distance vector (in/out parameter)
1408
 *
1409
 * Transform a distance vector from user space to device space. This
1410
 * function is similar to cairo_user_to_device() except that the
1411
 * translation components of the CTM will be ignored when transforming
1412
 * (@dx,@dy).
1413
 **/
1414
void
1415
cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy)
1416
{
1417
    if (unlikely (cr->status))
1418
        return;
1419
 
1420
    _cairo_gstate_user_to_device_distance (cr->gstate, dx, dy);
1421
}
1422
slim_hidden_def (cairo_user_to_device_distance);
1423
 
1424
/**
1425
 * cairo_device_to_user:
1426
 * @cr: a cairo
1427
 * @x: X value of coordinate (in/out parameter)
1428
 * @y: Y value of coordinate (in/out parameter)
1429
 *
1430
 * Transform a coordinate from device space to user space by
1431
 * multiplying the given point by the inverse of the current
1432
 * transformation matrix (CTM).
1433
 **/
1434
void
1435
cairo_device_to_user (cairo_t *cr, double *x, double *y)
1436
{
1437
    if (unlikely (cr->status))
1438
        return;
1439
 
1440
    _cairo_gstate_device_to_user (cr->gstate, x, y);
1441
}
1442
 
1443
/**
1444
 * cairo_device_to_user_distance:
1445
 * @cr: a cairo context
1446
 * @dx: X component of a distance vector (in/out parameter)
1447
 * @dy: Y component of a distance vector (in/out parameter)
1448
 *
1449
 * Transform a distance vector from device space to user space. This
1450
 * function is similar to cairo_device_to_user() except that the
1451
 * translation components of the inverse CTM will be ignored when
1452
 * transforming (@dx,@dy).
1453
 **/
1454
void
1455
cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy)
1456
{
1457
    if (unlikely (cr->status))
1458
        return;
1459
 
1460
    _cairo_gstate_device_to_user_distance (cr->gstate, dx, dy);
1461
}
1462
 
1463
/**
1464
 * cairo_new_path:
1465
 * @cr: a cairo context
1466
 *
1467
 * Clears the current path. After this call there will be no path and
1468
 * no current point.
1469
 **/
1470
void
1471
cairo_new_path (cairo_t *cr)
1472
{
1473
    if (unlikely (cr->status))
1474
        return;
1475
 
1476
    _cairo_path_fixed_fini (cr->path);
1477
    _cairo_path_fixed_init (cr->path);
1478
}
1479
slim_hidden_def(cairo_new_path);
1480
 
1481
/**
1482
 * cairo_move_to:
1483
 * @cr: a cairo context
1484
 * @x: the X coordinate of the new position
1485
 * @y: the Y coordinate of the new position
1486
 *
1487
 * Begin a new sub-path. After this call the current point will be (@x,
1488
 * @y).
1489
 **/
1490
void
1491
cairo_move_to (cairo_t *cr, double x, double y)
1492
{
1493
    cairo_status_t status;
1494
    cairo_fixed_t x_fixed, y_fixed;
1495
 
1496
    if (unlikely (cr->status))
1497
        return;
1498
 
1499
    _cairo_gstate_user_to_backend (cr->gstate, &x, &y);
1500
    x_fixed = _cairo_fixed_from_double (x);
1501
    y_fixed = _cairo_fixed_from_double (y);
1502
 
1503
    status = _cairo_path_fixed_move_to (cr->path, x_fixed, y_fixed);
1504
    if (unlikely (status))
1505
        _cairo_set_error (cr, status);
1506
}
1507
slim_hidden_def(cairo_move_to);
1508
 
1509
/**
1510
 * cairo_new_sub_path:
1511
 * @cr: a cairo context
1512
 *
1513
 * Begin a new sub-path. Note that the existing path is not
1514
 * affected. After this call there will be no current point.
1515
 *
1516
 * In many cases, this call is not needed since new sub-paths are
1517
 * frequently started with cairo_move_to().
1518
 *
1519
 * A call to cairo_new_sub_path() is particularly useful when
1520
 * beginning a new sub-path with one of the cairo_arc() calls. This
1521
 * makes things easier as it is no longer necessary to manually
1522
 * compute the arc's initial coordinates for a call to
1523
 * cairo_move_to().
1524
 *
1525
 * Since: 1.2
1526
 **/
1527
void
1528
cairo_new_sub_path (cairo_t *cr)
1529
{
1530
    if (unlikely (cr->status))
1531
        return;
1532
 
1533
    _cairo_path_fixed_new_sub_path (cr->path);
1534
}
1535
 
1536
/**
1537
 * cairo_line_to:
1538
 * @cr: a cairo context
1539
 * @x: the X coordinate of the end of the new line
1540
 * @y: the Y coordinate of the end of the new line
1541
 *
1542
 * Adds a line to the path from the current point to position (@x, @y)
1543
 * in user-space coordinates. After this call the current point
1544
 * will be (@x, @y).
1545
 *
1546
 * If there is no current point before the call to cairo_line_to()
1547
 * this function will behave as cairo_move_to(@cr, @x, @y).
1548
 **/
1549
void
1550
cairo_line_to (cairo_t *cr, double x, double y)
1551
{
1552
    cairo_status_t status;
1553
    cairo_fixed_t x_fixed, y_fixed;
1554
 
1555
    if (unlikely (cr->status))
1556
        return;
1557
 
1558
    _cairo_gstate_user_to_backend (cr->gstate, &x, &y);
1559
    x_fixed = _cairo_fixed_from_double (x);
1560
    y_fixed = _cairo_fixed_from_double (y);
1561
 
1562
    status = _cairo_path_fixed_line_to (cr->path, x_fixed, y_fixed);
1563
    if (unlikely (status))
1564
        _cairo_set_error (cr, status);
1565
}
1566
slim_hidden_def (cairo_line_to);
1567
 
1568
/**
1569
 * cairo_curve_to:
1570
 * @cr: a cairo context
1571
 * @x1: the X coordinate of the first control point
1572
 * @y1: the Y coordinate of the first control point
1573
 * @x2: the X coordinate of the second control point
1574
 * @y2: the Y coordinate of the second control point
1575
 * @x3: the X coordinate of the end of the curve
1576
 * @y3: the Y coordinate of the end of the curve
1577
 *
1578
 * Adds a cubic Bézier spline to the path from the current point to
1579
 * position (@x3, @y3) in user-space coordinates, using (@x1, @y1) and
1580
 * (@x2, @y2) as the control points. After this call the current point
1581
 * will be (@x3, @y3).
1582
 *
1583
 * If there is no current point before the call to cairo_curve_to()
1584
 * this function will behave as if preceded by a call to
1585
 * cairo_move_to(@cr, @x1, @y1).
1586
 **/
1587
void
1588
cairo_curve_to (cairo_t *cr,
1589
                double x1, double y1,
1590
                double x2, double y2,
1591
                double x3, double y3)
1592
{
1593
    cairo_status_t status;
1594
    cairo_fixed_t x1_fixed, y1_fixed;
1595
    cairo_fixed_t x2_fixed, y2_fixed;
1596
    cairo_fixed_t x3_fixed, y3_fixed;
1597
 
1598
    if (unlikely (cr->status))
1599
        return;
1600
 
1601
    _cairo_gstate_user_to_backend (cr->gstate, &x1, &y1);
1602
    _cairo_gstate_user_to_backend (cr->gstate, &x2, &y2);
1603
    _cairo_gstate_user_to_backend (cr->gstate, &x3, &y3);
1604
 
1605
    x1_fixed = _cairo_fixed_from_double (x1);
1606
    y1_fixed = _cairo_fixed_from_double (y1);
1607
 
1608
    x2_fixed = _cairo_fixed_from_double (x2);
1609
    y2_fixed = _cairo_fixed_from_double (y2);
1610
 
1611
    x3_fixed = _cairo_fixed_from_double (x3);
1612
    y3_fixed = _cairo_fixed_from_double (y3);
1613
 
1614
    status = _cairo_path_fixed_curve_to (cr->path,
1615
                                         x1_fixed, y1_fixed,
1616
                                         x2_fixed, y2_fixed,
1617
                                         x3_fixed, y3_fixed);
1618
    if (unlikely (status))
1619
        _cairo_set_error (cr, status);
1620
}
1621
slim_hidden_def (cairo_curve_to);
1622
 
1623
/**
1624
 * cairo_arc:
1625
 * @cr: a cairo context
1626
 * @xc: X position of the center of the arc
1627
 * @yc: Y position of the center of the arc
1628
 * @radius: the radius of the arc
1629
 * @angle1: the start angle, in radians
1630
 * @angle2: the end angle, in radians
1631
 *
1632
 * Adds a circular arc of the given @radius to the current path.  The
1633
 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1634
 * the direction of increasing angles to end at @angle2. If @angle2 is
1635
 * less than @angle1 it will be progressively increased by 2*M_PI
1636
 * until it is greater than @angle1.
1637
 *
1638
 * If there is a current point, an initial line segment will be added
1639
 * to the path to connect the current point to the beginning of the
1640
 * arc. If this initial line is undesired, it can be avoided by
1641
 * calling cairo_new_sub_path() before calling cairo_arc().
1642
 *
1643
 * Angles are measured in radians. An angle of 0.0 is in the direction
1644
 * of the positive X axis (in user space). An angle of %M_PI/2.0 radians
1645
 * (90 degrees) is in the direction of the positive Y axis (in
1646
 * user space). Angles increase in the direction from the positive X
1647
 * axis toward the positive Y axis. So with the default transformation
1648
 * matrix, angles increase in a clockwise direction.
1649
 *
1650
 * (To convert from degrees to radians, use <literal>degrees * (M_PI /
1651
 * 180.)</literal>.)
1652
 *
1653
 * This function gives the arc in the direction of increasing angles;
1654
 * see cairo_arc_negative() to get the arc in the direction of
1655
 * decreasing angles.
1656
 *
1657
 * The arc is circular in user space. To achieve an elliptical arc,
1658
 * you can scale the current transformation matrix by different
1659
 * amounts in the X and Y directions. For example, to draw an ellipse
1660
 * in the box given by @x, @y, @width, @height:
1661
 *
1662
 * <informalexample><programlisting>
1663
 * cairo_save (cr);
1664
 * cairo_translate (cr, x + width / 2., y + height / 2.);
1665
 * cairo_scale (cr, width / 2., height / 2.);
1666
 * cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
1667
 * cairo_restore (cr);
1668
 * </programlisting></informalexample>
1669
 **/
1670
void
1671
cairo_arc (cairo_t *cr,
1672
           double xc, double yc,
1673
           double radius,
1674
           double angle1, double angle2)
1675
{
1676
    if (unlikely (cr->status))
1677
        return;
1678
 
1679
    /* Do nothing, successfully, if radius is <= 0 */
1680
    if (radius <= 0.0)
1681
        return;
1682
 
1683
    while (angle2 < angle1)
1684
        angle2 += 2 * M_PI;
1685
 
1686
    cairo_line_to (cr,
1687
                   xc + radius * cos (angle1),
1688
                   yc + radius * sin (angle1));
1689
 
1690
    _cairo_arc_path (cr, xc, yc, radius,
1691
                     angle1, angle2);
1692
}
1693
 
1694
/**
1695
 * cairo_arc_negative:
1696
 * @cr: a cairo context
1697
 * @xc: X position of the center of the arc
1698
 * @yc: Y position of the center of the arc
1699
 * @radius: the radius of the arc
1700
 * @angle1: the start angle, in radians
1701
 * @angle2: the end angle, in radians
1702
 *
1703
 * Adds a circular arc of the given @radius to the current path.  The
1704
 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1705
 * the direction of decreasing angles to end at @angle2. If @angle2 is
1706
 * greater than @angle1 it will be progressively decreased by 2*M_PI
1707
 * until it is less than @angle1.
1708
 *
1709
 * See cairo_arc() for more details. This function differs only in the
1710
 * direction of the arc between the two angles.
1711
 **/
1712
void
1713
cairo_arc_negative (cairo_t *cr,
1714
                    double xc, double yc,
1715
                    double radius,
1716
                    double angle1, double angle2)
1717
{
1718
    if (unlikely (cr->status))
1719
        return;
1720
 
1721
    /* Do nothing, successfully, if radius is <= 0 */
1722
    if (radius <= 0.0)
1723
        return;
1724
 
1725
    while (angle2 > angle1)
1726
        angle2 -= 2 * M_PI;
1727
 
1728
    cairo_line_to (cr,
1729
                   xc + radius * cos (angle1),
1730
                   yc + radius * sin (angle1));
1731
 
1732
     _cairo_arc_path_negative (cr, xc, yc, radius,
1733
                               angle1, angle2);
1734
}
1735
 
1736
/* XXX: NYI
1737
void
1738
cairo_arc_to (cairo_t *cr,
1739
              double x1, double y1,
1740
              double x2, double y2,
1741
              double radius)
1742
{
1743
    cairo_status_t status;
1744
 
1745
    if (unlikely (cr->status))
1746
        return;
1747
 
1748
    status = _cairo_gstate_arc_to (cr->gstate,
1749
                                   x1, y1,
1750
                                   x2, y2,
1751
                                   radius);
1752
    if (unlikely (status))
1753
        _cairo_set_error (cr, status);
1754
}
1755
*/
1756
 
1757
/**
1758
 * cairo_rel_move_to:
1759
 * @cr: a cairo context
1760
 * @dx: the X offset
1761
 * @dy: the Y offset
1762
 *
1763
 * Begin a new sub-path. After this call the current point will offset
1764
 * by (@x, @y).
1765
 *
1766
 * Given a current point of (x, y), cairo_rel_move_to(@cr, @dx, @dy)
1767
 * is logically equivalent to cairo_move_to(@cr, x + @dx, y + @dy).
1768
 *
1769
 * It is an error to call this function with no current point. Doing
1770
 * so will cause @cr to shutdown with a status of
1771
 * %CAIRO_STATUS_NO_CURRENT_POINT.
1772
 **/
1773
void
1774
cairo_rel_move_to (cairo_t *cr, double dx, double dy)
1775
{
1776
    cairo_fixed_t dx_fixed, dy_fixed;
1777
    cairo_status_t status;
1778
 
1779
    if (unlikely (cr->status))
1780
        return;
1781
 
1782
    _cairo_gstate_user_to_device_distance (cr->gstate, &dx, &dy);
1783
 
1784
    dx_fixed = _cairo_fixed_from_double (dx);
1785
    dy_fixed = _cairo_fixed_from_double (dy);
1786
 
1787
    status = _cairo_path_fixed_rel_move_to (cr->path, dx_fixed, dy_fixed);
1788
    if (unlikely (status))
1789
        _cairo_set_error (cr, status);
1790
}
1791
 
1792
/**
1793
 * cairo_rel_line_to:
1794
 * @cr: a cairo context
1795
 * @dx: the X offset to the end of the new line
1796
 * @dy: the Y offset to the end of the new line
1797
 *
1798
 * Relative-coordinate version of cairo_line_to(). Adds a line to the
1799
 * path from the current point to a point that is offset from the
1800
 * current point by (@dx, @dy) in user space. After this call the
1801
 * current point will be offset by (@dx, @dy).
1802
 *
1803
 * Given a current point of (x, y), cairo_rel_line_to(@cr, @dx, @dy)
1804
 * is logically equivalent to cairo_line_to(@cr, x + @dx, y + @dy).
1805
 *
1806
 * It is an error to call this function with no current point. Doing
1807
 * so will cause @cr to shutdown with a status of
1808
 * %CAIRO_STATUS_NO_CURRENT_POINT.
1809
 **/
1810
void
1811
cairo_rel_line_to (cairo_t *cr, double dx, double dy)
1812
{
1813
    cairo_fixed_t dx_fixed, dy_fixed;
1814
    cairo_status_t status;
1815
 
1816
    if (unlikely (cr->status))
1817
        return;
1818
 
1819
    _cairo_gstate_user_to_device_distance (cr->gstate, &dx, &dy);
1820
 
1821
    dx_fixed = _cairo_fixed_from_double (dx);
1822
    dy_fixed = _cairo_fixed_from_double (dy);
1823
 
1824
    status = _cairo_path_fixed_rel_line_to (cr->path, dx_fixed, dy_fixed);
1825
    if (unlikely (status))
1826
        _cairo_set_error (cr, status);
1827
}
1828
slim_hidden_def(cairo_rel_line_to);
1829
 
1830
/**
1831
 * cairo_rel_curve_to:
1832
 * @cr: a cairo context
1833
 * @dx1: the X offset to the first control point
1834
 * @dy1: the Y offset to the first control point
1835
 * @dx2: the X offset to the second control point
1836
 * @dy2: the Y offset to the second control point
1837
 * @dx3: the X offset to the end of the curve
1838
 * @dy3: the Y offset to the end of the curve
1839
 *
1840
 * Relative-coordinate version of cairo_curve_to(). All offsets are
1841
 * relative to the current point. Adds a cubic Bézier spline to the
1842
 * path from the current point to a point offset from the current
1843
 * point by (@dx3, @dy3), using points offset by (@dx1, @dy1) and
1844
 * (@dx2, @dy2) as the control points. After this call the current
1845
 * point will be offset by (@dx3, @dy3).
1846
 *
1847
 * Given a current point of (x, y), cairo_rel_curve_to(@cr, @dx1,
1848
 * @dy1, @dx2, @dy2, @dx3, @dy3) is logically equivalent to
1849
 * cairo_curve_to(@cr, x+@dx1, y+@dy1, x+@dx2, y+@dy2, x+@dx3, y+@dy3).
1850
 *
1851
 * It is an error to call this function with no current point. Doing
1852
 * so will cause @cr to shutdown with a status of
1853
 * %CAIRO_STATUS_NO_CURRENT_POINT.
1854
 **/
1855
void
1856
cairo_rel_curve_to (cairo_t *cr,
1857
                    double dx1, double dy1,
1858
                    double dx2, double dy2,
1859
                    double dx3, double dy3)
1860
{
1861
    cairo_fixed_t dx1_fixed, dy1_fixed;
1862
    cairo_fixed_t dx2_fixed, dy2_fixed;
1863
    cairo_fixed_t dx3_fixed, dy3_fixed;
1864
    cairo_status_t status;
1865
 
1866
    if (unlikely (cr->status))
1867
        return;
1868
 
1869
    _cairo_gstate_user_to_device_distance (cr->gstate, &dx1, &dy1);
1870
    _cairo_gstate_user_to_device_distance (cr->gstate, &dx2, &dy2);
1871
    _cairo_gstate_user_to_device_distance (cr->gstate, &dx3, &dy3);
1872
 
1873
    dx1_fixed = _cairo_fixed_from_double (dx1);
1874
    dy1_fixed = _cairo_fixed_from_double (dy1);
1875
 
1876
    dx2_fixed = _cairo_fixed_from_double (dx2);
1877
    dy2_fixed = _cairo_fixed_from_double (dy2);
1878
 
1879
    dx3_fixed = _cairo_fixed_from_double (dx3);
1880
    dy3_fixed = _cairo_fixed_from_double (dy3);
1881
 
1882
    status = _cairo_path_fixed_rel_curve_to (cr->path,
1883
                                             dx1_fixed, dy1_fixed,
1884
                                             dx2_fixed, dy2_fixed,
1885
                                             dx3_fixed, dy3_fixed);
1886
    if (unlikely (status))
1887
        _cairo_set_error (cr, status);
1888
}
1889
 
1890
/**
1891
 * cairo_rectangle:
1892
 * @cr: a cairo context
1893
 * @x: the X coordinate of the top left corner of the rectangle
1894
 * @y: the Y coordinate to the top left corner of the rectangle
1895
 * @width: the width of the rectangle
1896
 * @height: the height of the rectangle
1897
 *
1898
 * Adds a closed sub-path rectangle of the given size to the current
1899
 * path at position (@x, @y) in user-space coordinates.
1900
 *
1901
 * This function is logically equivalent to:
1902
 * <informalexample><programlisting>
1903
 * cairo_move_to (cr, x, y);
1904
 * cairo_rel_line_to (cr, width, 0);
1905
 * cairo_rel_line_to (cr, 0, height);
1906
 * cairo_rel_line_to (cr, -width, 0);
1907
 * cairo_close_path (cr);
1908
 * </programlisting></informalexample>
1909
 **/
1910
void
1911
cairo_rectangle (cairo_t *cr,
1912
                 double x, double y,
1913
                 double width, double height)
1914
{
1915
    if (unlikely (cr->status))
1916
        return;
1917
 
1918
    cairo_move_to (cr, x, y);
1919
    cairo_rel_line_to (cr, width, 0);
1920
    cairo_rel_line_to (cr, 0, height);
1921
    cairo_rel_line_to (cr, -width, 0);
1922
    cairo_close_path (cr);
1923
}
1924
 
1925
#if 0
1926
/* XXX: NYI */
1927
void
1928
cairo_stroke_to_path (cairo_t *cr)
1929
{
1930
    cairo_status_t status;
1931
 
1932
    if (unlikely (cr->status))
1933
        return;
1934
 
1935
    /* The code in _cairo_meta_surface_get_path has a poorman's stroke_to_path */
1936
 
1937
    status = _cairo_gstate_stroke_path (cr->gstate);
1938
    if (unlikely (status))
1939
        _cairo_set_error (cr, status);
1940
}
1941
#endif
1942
 
1943
/**
1944
 * cairo_close_path:
1945
 * @cr: a cairo context
1946
 *
1947
 * Adds a line segment to the path from the current point to the
1948
 * beginning of the current sub-path, (the most recent point passed to
1949
 * cairo_move_to()), and closes this sub-path. After this call the
1950
 * current point will be at the joined endpoint of the sub-path.
1951
 *
1952
 * The behavior of cairo_close_path() is distinct from simply calling
1953
 * cairo_line_to() with the equivalent coordinate in the case of
1954
 * stroking. When a closed sub-path is stroked, there are no caps on
1955
 * the ends of the sub-path. Instead, there is a line join connecting
1956
 * the final and initial segments of the sub-path.
1957
 *
1958
 * If there is no current point before the call to cairo_close_path(),
1959
 * this function will have no effect.
1960
 *
1961
 * Note: As of cairo version 1.2.4 any call to cairo_close_path() will
1962
 * place an explicit MOVE_TO element into the path immediately after
1963
 * the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
1964
 * example). This can simplify path processing in some cases as it may
1965
 * not be necessary to save the "last move_to point" during processing
1966
 * as the MOVE_TO immediately after the CLOSE_PATH will provide that
1967
 * point.
1968
 **/
1969
void
1970
cairo_close_path (cairo_t *cr)
1971
{
1972
    cairo_status_t status;
1973
 
1974
    if (unlikely (cr->status))
1975
        return;
1976
 
1977
    status = _cairo_path_fixed_close_path (cr->path);
1978
    if (unlikely (status))
1979
        _cairo_set_error (cr, status);
1980
}
1981
slim_hidden_def(cairo_close_path);
1982
 
1983
/**
1984
 * cairo_path_extents:
1985
 * @cr: a cairo context
1986
 * @x1: left of the resulting extents
1987
 * @y1: top of the resulting extents
1988
 * @x2: right of the resulting extents
1989
 * @y2: bottom of the resulting extents
1990
 *
1991
 * Computes a bounding box in user-space coordinates covering the
1992
 * points on the current path. If the current path is empty, returns
1993
 * an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,
1994
 * surface dimensions and clipping are not taken into account.
1995
 *
1996
 * Contrast with cairo_fill_extents() and cairo_stroke_extents() which
1997
 * return the extents of only the area that would be "inked" by
1998
 * the corresponding drawing operations.
1999
 *
2000
 * The result of cairo_path_extents() is defined as equivalent to the
2001
 * limit of cairo_stroke_extents() with %CAIRO_LINE_CAP_ROUND as the
2002
 * line width approaches 0.0, (but never reaching the empty-rectangle
2003
 * returned by cairo_stroke_extents() for a line width of 0.0).
2004
 *
2005
 * Specifically, this means that zero-area sub-paths such as
2006
 * cairo_move_to();cairo_line_to() segments, (even degenerate cases
2007
 * where the coordinates to both calls are identical), will be
2008
 * considered as contributing to the extents. However, a lone
2009
 * cairo_move_to() will not contribute to the results of
2010
 * cairo_path_extents().
2011
 *
2012
 * Since: 1.6
2013
 **/
2014
void
2015
cairo_path_extents (cairo_t *cr,
2016
                    double *x1, double *y1, double *x2, double *y2)
2017
{
2018
    if (unlikely (cr->status)) {
2019
        if (x1)
2020
            *x1 = 0.0;
2021
        if (y1)
2022
            *y1 = 0.0;
2023
        if (x2)
2024
            *x2 = 0.0;
2025
        if (y2)
2026
            *y2 = 0.0;
2027
 
2028
        return;
2029
    }
2030
 
2031
    _cairo_gstate_path_extents (cr->gstate,
2032
                                cr->path,
2033
                                x1, y1, x2, y2);
2034
}
2035
 
2036
/**
2037
 * cairo_paint:
2038
 * @cr: a cairo context
2039
 *
2040
 * A drawing operator that paints the current source everywhere within
2041
 * the current clip region.
2042
 **/
2043
void
2044
cairo_paint (cairo_t *cr)
2045
{
2046
    cairo_status_t status;
2047
 
2048
    if (unlikely (cr->status))
2049
        return;
2050
 
2051
    status = _cairo_gstate_paint (cr->gstate);
2052
    if (unlikely (status))
2053
        _cairo_set_error (cr, status);
2054
}
2055
slim_hidden_def (cairo_paint);
2056
 
2057
/**
2058
 * cairo_paint_with_alpha:
2059
 * @cr: a cairo context
2060
 * @alpha: alpha value, between 0 (transparent) and 1 (opaque)
2061
 *
2062
 * A drawing operator that paints the current source everywhere within
2063
 * the current clip region using a mask of constant alpha value
2064
 * @alpha. The effect is similar to cairo_paint(), but the drawing
2065
 * is faded out using the alpha value.
2066
 **/
2067
void
2068
cairo_paint_with_alpha (cairo_t *cr,
2069
                        double   alpha)
2070
{
2071
    cairo_status_t status;
2072
    cairo_color_t color;
2073
    cairo_solid_pattern_t pattern;
2074
 
2075
    if (unlikely (cr->status))
2076
        return;
2077
 
2078
    if (CAIRO_ALPHA_IS_OPAQUE (alpha)) {
2079
        cairo_paint (cr);
2080
        return;
2081
    }
2082
 
2083
    if (CAIRO_ALPHA_IS_ZERO (alpha)) {
2084
        return;
2085
    }
2086
 
2087
    _cairo_color_init_rgba (&color, 1., 1., 1., alpha);
2088
    _cairo_pattern_init_solid (&pattern, &color, CAIRO_CONTENT_ALPHA);
2089
 
2090
    status = _cairo_gstate_mask (cr->gstate, &pattern.base);
2091
    if (unlikely (status))
2092
        _cairo_set_error (cr, status);
2093
 
2094
    _cairo_pattern_fini (&pattern.base);
2095
}
2096
 
2097
/**
2098
 * cairo_mask:
2099
 * @cr: a cairo context
2100
 * @pattern: a #cairo_pattern_t
2101
 *
2102
 * A drawing operator that paints the current source
2103
 * using the alpha channel of @pattern as a mask. (Opaque
2104
 * areas of @pattern are painted with the source, transparent
2105
 * areas are not painted.)
2106
 */
2107
void
2108
cairo_mask (cairo_t         *cr,
2109
            cairo_pattern_t *pattern)
2110
{
2111
    cairo_status_t status;
2112
 
2113
    if (unlikely (cr->status))
2114
        return;
2115
 
2116
    if (pattern == NULL) {
2117
        _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
2118
        return;
2119
    }
2120
 
2121
    if (pattern->status) {
2122
        _cairo_set_error (cr, pattern->status);
2123
        return;
2124
    }
2125
 
2126
    status = _cairo_gstate_mask (cr->gstate, pattern);
2127
    if (unlikely (status))
2128
        _cairo_set_error (cr, status);
2129
}
2130
slim_hidden_def (cairo_mask);
2131
 
2132
/**
2133
 * cairo_mask_surface:
2134
 * @cr: a cairo context
2135
 * @surface: a #cairo_surface_t
2136
 * @surface_x: X coordinate at which to place the origin of @surface
2137
 * @surface_y: Y coordinate at which to place the origin of @surface
2138
 *
2139
 * A drawing operator that paints the current source
2140
 * using the alpha channel of @surface as a mask. (Opaque
2141
 * areas of @surface are painted with the source, transparent
2142
 * areas are not painted.)
2143
 */
2144
void
2145
cairo_mask_surface (cairo_t         *cr,
2146
                    cairo_surface_t *surface,
2147
                    double           surface_x,
2148
                    double           surface_y)
2149
{
2150
    cairo_pattern_t *pattern;
2151
    cairo_matrix_t matrix;
2152
 
2153
    if (unlikely (cr->status))
2154
        return;
2155
 
2156
    pattern = cairo_pattern_create_for_surface (surface);
2157
 
2158
    cairo_matrix_init_translate (&matrix, - surface_x, - surface_y);
2159
    cairo_pattern_set_matrix (pattern, &matrix);
2160
 
2161
    cairo_mask (cr, pattern);
2162
 
2163
    cairo_pattern_destroy (pattern);
2164
}
2165
 
2166
/**
2167
 * cairo_stroke:
2168
 * @cr: a cairo context
2169
 *
2170
 * A drawing operator that strokes the current path according to the
2171
 * current line width, line join, line cap, and dash settings. After
2172
 * cairo_stroke(), the current path will be cleared from the cairo
2173
 * context. See cairo_set_line_width(), cairo_set_line_join(),
2174
 * cairo_set_line_cap(), cairo_set_dash(), and
2175
 * cairo_stroke_preserve().
2176
 *
2177
 * Note: Degenerate segments and sub-paths are treated specially and
2178
 * provide a useful result. These can result in two different
2179
 * situations:
2180
 *
2181
 * 1. Zero-length "on" segments set in cairo_set_dash(). If the cap
2182
 * style is %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE then these
2183
 * segments will be drawn as circular dots or squares respectively. In
2184
 * the case of %CAIRO_LINE_CAP_SQUARE, the orientation of the squares
2185
 * is determined by the direction of the underlying path.
2186
 *
2187
 * 2. A sub-path created by cairo_move_to() followed by either a
2188
 * cairo_close_path() or one or more calls to cairo_line_to() to the
2189
 * same coordinate as the cairo_move_to(). If the cap style is
2190
 * %CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular
2191
 * dots. Note that in the case of %CAIRO_LINE_CAP_SQUARE a degenerate
2192
 * sub-path will not be drawn at all, (since the correct orientation
2193
 * is indeterminate).
2194
 *
2195
 * In no case will a cap style of %CAIRO_LINE_CAP_BUTT cause anything
2196
 * to be drawn in the case of either degenerate segments or sub-paths.
2197
 **/
2198
void
2199
cairo_stroke (cairo_t *cr)
2200
{
2201
    cairo_stroke_preserve (cr);
2202
 
2203
    cairo_new_path (cr);
2204
}
2205
slim_hidden_def(cairo_stroke);
2206
 
2207
/**
2208
 * cairo_stroke_preserve:
2209
 * @cr: a cairo context
2210
 *
2211
 * A drawing operator that strokes the current path according to the
2212
 * current line width, line join, line cap, and dash settings. Unlike
2213
 * cairo_stroke(), cairo_stroke_preserve() preserves the path within the
2214
 * cairo context.
2215
 *
2216
 * See cairo_set_line_width(), cairo_set_line_join(),
2217
 * cairo_set_line_cap(), cairo_set_dash(), and
2218
 * cairo_stroke_preserve().
2219
 **/
2220
void
2221
cairo_stroke_preserve (cairo_t *cr)
2222
{
2223
    cairo_status_t status;
2224
 
2225
    if (unlikely (cr->status))
2226
        return;
2227
 
2228
    status = _cairo_gstate_stroke (cr->gstate, cr->path);
2229
    if (unlikely (status))
2230
        _cairo_set_error (cr, status);
2231
}
2232
slim_hidden_def(cairo_stroke_preserve);
2233
 
2234
/**
2235
 * cairo_fill:
2236
 * @cr: a cairo context
2237
 *
2238
 * A drawing operator that fills the current path according to the
2239
 * current fill rule, (each sub-path is implicitly closed before being
2240
 * filled). After cairo_fill(), the current path will be cleared from
2241
 * the cairo context. See cairo_set_fill_rule() and
2242
 * cairo_fill_preserve().
2243
 **/
2244
void
2245
cairo_fill (cairo_t *cr)
2246
{
2247
    cairo_fill_preserve (cr);
2248
 
2249
    cairo_new_path (cr);
2250
}
2251
 
2252
/**
2253
 * cairo_fill_preserve:
2254
 * @cr: a cairo context
2255
 *
2256
 * A drawing operator that fills the current path according to the
2257
 * current fill rule, (each sub-path is implicitly closed before being
2258
 * filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the
2259
 * path within the cairo context.
2260
 *
2261
 * See cairo_set_fill_rule() and cairo_fill().
2262
 **/
2263
void
2264
cairo_fill_preserve (cairo_t *cr)
2265
{
2266
    cairo_status_t status;
2267
 
2268
    if (unlikely (cr->status))
2269
        return;
2270
 
2271
    status = _cairo_gstate_fill (cr->gstate, cr->path);
2272
    if (unlikely (status))
2273
        _cairo_set_error (cr, status);
2274
}
2275
slim_hidden_def(cairo_fill_preserve);
2276
 
2277
/**
2278
 * cairo_copy_page:
2279
 * @cr: a cairo context
2280
 *
2281
 * Emits the current page for backends that support multiple pages, but
2282
 * doesn't clear it, so, the contents of the current page will be retained
2283
 * for the next page too.  Use cairo_show_page() if you want to get an
2284
 * empty page after the emission.
2285
 *
2286
 * This is a convenience function that simply calls
2287
 * cairo_surface_copy_page() on @cr's target.
2288
 **/
2289
void
2290
cairo_copy_page (cairo_t *cr)
2291
{
2292
    cairo_status_t status;
2293
 
2294
    if (unlikely (cr->status))
2295
        return;
2296
 
2297
    status = _cairo_gstate_copy_page (cr->gstate);
2298
    if (unlikely (status))
2299
        _cairo_set_error (cr, status);
2300
}
2301
 
2302
/**
2303
 * cairo_show_page:
2304
 * @cr: a cairo context
2305
 *
2306
 * Emits and clears the current page for backends that support multiple
2307
 * pages.  Use cairo_copy_page() if you don't want to clear the page.
2308
 *
2309
 * This is a convenience function that simply calls
2310
 * cairo_surface_show_page() on @cr's target.
2311
 **/
2312
void
2313
cairo_show_page (cairo_t *cr)
2314
{
2315
    cairo_status_t status;
2316
 
2317
    if (unlikely (cr->status))
2318
        return;
2319
 
2320
    status = _cairo_gstate_show_page (cr->gstate);
2321
    if (unlikely (status))
2322
        _cairo_set_error (cr, status);
2323
}
2324
 
2325
/**
2326
 * cairo_in_stroke:
2327
 * @cr: a cairo context
2328
 * @x: X coordinate of the point to test
2329
 * @y: Y coordinate of the point to test
2330
 *
2331
 * Tests whether the given point is inside the area that would be
2332
 * affected by a cairo_stroke() operation given the current path and
2333
 * stroking parameters. Surface dimensions and clipping are not taken
2334
 * into account.
2335
 *
2336
 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2337
 * cairo_set_line_cap(), cairo_set_dash(), and
2338
 * cairo_stroke_preserve().
2339
 *
2340
 * Return value: A non-zero value if the point is inside, or zero if
2341
 * outside.
2342
 **/
2343
cairo_bool_t
2344
cairo_in_stroke (cairo_t *cr, double x, double y)
2345
{
2346
    cairo_status_t status;
2347
    cairo_bool_t inside = FALSE;
2348
 
2349
    if (unlikely (cr->status))
2350
        return FALSE;
2351
 
2352
    status = _cairo_gstate_in_stroke (cr->gstate,
2353
                                      cr->path,
2354
                                      x, y, &inside);
2355
    if (unlikely (status))
2356
        _cairo_set_error (cr, status);
2357
 
2358
    return inside;
2359
}
2360
 
2361
/**
2362
 * cairo_in_fill:
2363
 * @cr: a cairo context
2364
 * @x: X coordinate of the point to test
2365
 * @y: Y coordinate of the point to test
2366
 *
2367
 * Tests whether the given point is inside the area that would be
2368
 * affected by a cairo_fill() operation given the current path and
2369
 * filling parameters. Surface dimensions and clipping are not taken
2370
 * into account.
2371
 *
2372
 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2373
 *
2374
 * Return value: A non-zero value if the point is inside, or zero if
2375
 * outside.
2376
 **/
2377
cairo_bool_t
2378
cairo_in_fill (cairo_t *cr, double x, double y)
2379
{
2380
    if (unlikely (cr->status))
2381
        return FALSE;
2382
 
2383
    return _cairo_gstate_in_fill (cr->gstate, cr->path, x, y);
2384
}
2385
 
2386
/**
2387
 * cairo_stroke_extents:
2388
 * @cr: a cairo context
2389
 * @x1: left of the resulting extents
2390
 * @y1: top of the resulting extents
2391
 * @x2: right of the resulting extents
2392
 * @y2: bottom of the resulting extents
2393
 *
2394
 * Computes a bounding box in user coordinates covering the area that
2395
 * would be affected, (the "inked" area), by a cairo_stroke()
2396
 * operation given the current path and stroke parameters.
2397
 * If the current path is empty, returns an empty rectangle ((0,0), (0,0)).
2398
 * Surface dimensions and clipping are not taken into account.
2399
 *
2400
 * Note that if the line width is set to exactly zero, then
2401
 * cairo_stroke_extents() will return an empty rectangle. Contrast with
2402
 * cairo_path_extents() which can be used to compute the non-empty
2403
 * bounds as the line width approaches zero.
2404
 *
2405
 * Note that cairo_stroke_extents() must necessarily do more work to
2406
 * compute the precise inked areas in light of the stroke parameters,
2407
 * so cairo_path_extents() may be more desirable for sake of
2408
 * performance if non-inked path extents are desired.
2409
 *
2410
 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2411
 * cairo_set_line_cap(), cairo_set_dash(), and
2412
 * cairo_stroke_preserve().
2413
 **/
2414
void
2415
cairo_stroke_extents (cairo_t *cr,
2416
                      double *x1, double *y1, double *x2, double *y2)
2417
{
2418
    cairo_status_t status;
2419
 
2420
    if (unlikely (cr->status)) {
2421
        if (x1)
2422
            *x1 = 0.0;
2423
        if (y1)
2424
            *y1 = 0.0;
2425
        if (x2)
2426
            *x2 = 0.0;
2427
        if (y2)
2428
            *y2 = 0.0;
2429
 
2430
        return;
2431
    }
2432
 
2433
    status = _cairo_gstate_stroke_extents (cr->gstate,
2434
                                           cr->path,
2435
                                           x1, y1, x2, y2);
2436
    if (unlikely (status))
2437
        _cairo_set_error (cr, status);
2438
}
2439
 
2440
/**
2441
 * cairo_fill_extents:
2442
 * @cr: a cairo context
2443
 * @x1: left of the resulting extents
2444
 * @y1: top of the resulting extents
2445
 * @x2: right of the resulting extents
2446
 * @y2: bottom of the resulting extents
2447
 *
2448
 * Computes a bounding box in user coordinates covering the area that
2449
 * would be affected, (the "inked" area), by a cairo_fill() operation
2450
 * given the current path and fill parameters. If the current path is
2451
 * empty, returns an empty rectangle ((0,0), (0,0)). Surface
2452
 * dimensions and clipping are not taken into account.
2453
 *
2454
 * Contrast with cairo_path_extents(), which is similar, but returns
2455
 * non-zero extents for some paths with no inked area, (such as a
2456
 * simple line segment).
2457
 *
2458
 * Note that cairo_fill_extents() must necessarily do more work to
2459
 * compute the precise inked areas in light of the fill rule, so
2460
 * cairo_path_extents() may be more desirable for sake of performance
2461
 * if the non-inked path extents are desired.
2462
 *
2463
 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2464
 **/
2465
void
2466
cairo_fill_extents (cairo_t *cr,
2467
                    double *x1, double *y1, double *x2, double *y2)
2468
{
2469
    cairo_status_t status;
2470
 
2471
    if (unlikely (cr->status)) {
2472
        if (x1)
2473
            *x1 = 0.0;
2474
        if (y1)
2475
            *y1 = 0.0;
2476
        if (x2)
2477
            *x2 = 0.0;
2478
        if (y2)
2479
            *y2 = 0.0;
2480
 
2481
        return;
2482
    }
2483
 
2484
    status = _cairo_gstate_fill_extents (cr->gstate,
2485
                                         cr->path,
2486
                                         x1, y1, x2, y2);
2487
    if (unlikely (status))
2488
        _cairo_set_error (cr, status);
2489
}
2490
 
2491
/**
2492
 * cairo_clip:
2493
 * @cr: a cairo context
2494
 *
2495
 * Establishes a new clip region by intersecting the current clip
2496
 * region with the current path as it would be filled by cairo_fill()
2497
 * and according to the current fill rule (see cairo_set_fill_rule()).
2498
 *
2499
 * After cairo_clip(), the current path will be cleared from the cairo
2500
 * context.
2501
 *
2502
 * The current clip region affects all drawing operations by
2503
 * effectively masking out any changes to the surface that are outside
2504
 * the current clip region.
2505
 *
2506
 * Calling cairo_clip() can only make the clip region smaller, never
2507
 * larger. But the current clip is part of the graphics state, so a
2508
 * temporary restriction of the clip region can be achieved by
2509
 * calling cairo_clip() within a cairo_save()/cairo_restore()
2510
 * pair. The only other means of increasing the size of the clip
2511
 * region is cairo_reset_clip().
2512
 **/
2513
void
2514
cairo_clip (cairo_t *cr)
2515
{
2516
    cairo_clip_preserve (cr);
2517
 
2518
    cairo_new_path (cr);
2519
}
2520
 
2521
/**
2522
 * cairo_clip_preserve:
2523
 * @cr: a cairo context
2524
 *
2525
 * Establishes a new clip region by intersecting the current clip
2526
 * region with the current path as it would be filled by cairo_fill()
2527
 * and according to the current fill rule (see cairo_set_fill_rule()).
2528
 *
2529
 * Unlike cairo_clip(), cairo_clip_preserve() preserves the path within
2530
 * the cairo context.
2531
 *
2532
 * The current clip region affects all drawing operations by
2533
 * effectively masking out any changes to the surface that are outside
2534
 * the current clip region.
2535
 *
2536
 * Calling cairo_clip_preserve() can only make the clip region smaller, never
2537
 * larger. But the current clip is part of the graphics state, so a
2538
 * temporary restriction of the clip region can be achieved by
2539
 * calling cairo_clip_preserve() within a cairo_save()/cairo_restore()
2540
 * pair. The only other means of increasing the size of the clip
2541
 * region is cairo_reset_clip().
2542
 **/
2543
void
2544
cairo_clip_preserve (cairo_t *cr)
2545
{
2546
    cairo_status_t status;
2547
 
2548
    if (unlikely (cr->status))
2549
        return;
2550
 
2551
    status = _cairo_gstate_clip (cr->gstate, cr->path);
2552
    if (unlikely (status))
2553
        _cairo_set_error (cr, status);
2554
}
2555
slim_hidden_def(cairo_clip_preserve);
2556
 
2557
/**
2558
 * cairo_reset_clip:
2559
 * @cr: a cairo context
2560
 *
2561
 * Reset the current clip region to its original, unrestricted
2562
 * state. That is, set the clip region to an infinitely large shape
2563
 * containing the target surface. Equivalently, if infinity is too
2564
 * hard to grasp, one can imagine the clip region being reset to the
2565
 * exact bounds of the target surface.
2566
 *
2567
 * Note that code meant to be reusable should not call
2568
 * cairo_reset_clip() as it will cause results unexpected by
2569
 * higher-level code which calls cairo_clip(). Consider using
2570
 * cairo_save() and cairo_restore() around cairo_clip() as a more
2571
 * robust means of temporarily restricting the clip region.
2572
 **/
2573
void
2574
cairo_reset_clip (cairo_t *cr)
2575
{
2576
    cairo_status_t status;
2577
 
2578
    if (unlikely (cr->status))
2579
        return;
2580
 
2581
    status = _cairo_gstate_reset_clip (cr->gstate);
2582
    if (unlikely (status))
2583
        _cairo_set_error (cr, status);
2584
}
2585
 
2586
/**
2587
 * cairo_clip_extents:
2588
 * @cr: a cairo context
2589
 * @x1: left of the resulting extents
2590
 * @y1: top of the resulting extents
2591
 * @x2: right of the resulting extents
2592
 * @y2: bottom of the resulting extents
2593
 *
2594
 * Computes a bounding box in user coordinates covering the area inside the
2595
 * current clip.
2596
 *
2597
 * Since: 1.4
2598
 **/
2599
void
2600
cairo_clip_extents (cairo_t *cr,
2601
                    double *x1, double *y1,
2602
                    double *x2, double *y2)
2603
{
2604
    if (unlikely (cr->status)) {
2605
        if (x1)
2606
            *x1 = 0.0;
2607
        if (y1)
2608
            *y1 = 0.0;
2609
        if (x2)
2610
            *x2 = 0.0;
2611
        if (y2)
2612
            *y2 = 0.0;
2613
 
2614
        return;
2615
    }
2616
 
2617
    if (! _cairo_gstate_clip_extents (cr->gstate, x1, y1, x2, y2)) {
2618
        *x1 = -INFINITY;
2619
        *y1 = -INFINITY;
2620
        *x2 = +INFINITY;
2621
        *y2 = +INFINITY;
2622
    }
2623
}
2624
 
2625
/**
2626
 * cairo_in_clip:
2627
 * @cr: a cairo context
2628
 * @x: X coordinate of the point to test
2629
 * @y: Y coordinate of the point to test
2630
 *
2631
 * Tests whether the given point is inside the area that would be
2632
 * visible through the current clip, i.e. the area that would be filled by
2633
 * a cairo_paint() operation.
2634
 *
2635
 * See cairo_clip(), and cairo_clip_preserve().
2636
 *
2637
 * Return value: A non-zero value if the point is inside, or zero if
2638
 * outside.
2639
 *
2640
 * Since: 1.10
2641
 **/
2642
cairo_bool_t
2643
cairo_in_clip (cairo_t *cr, double x, double y)
2644
{
2645
    if (unlikely (cr->status))
2646
        return FALSE;
2647
 
2648
    return _cairo_gstate_in_clip (cr->gstate, x, y);
2649
}
2650
 
2651
static cairo_rectangle_list_t *
2652
_cairo_rectangle_list_create_in_error (cairo_status_t status)
2653
{
2654
    cairo_rectangle_list_t *list;
2655
 
2656
    if (status == CAIRO_STATUS_NO_MEMORY)
2657
        return (cairo_rectangle_list_t*) &_cairo_rectangles_nil;
2658
 
2659
    list = malloc (sizeof (cairo_rectangle_list_t));
2660
    if (unlikely (list == NULL)) {
2661
        status = _cairo_error (CAIRO_STATUS_NO_MEMORY);
2662
        return (cairo_rectangle_list_t*) &_cairo_rectangles_nil;
2663
    }
2664
 
2665
    list->status = status;
2666
    list->rectangles = NULL;
2667
    list->num_rectangles = 0;
2668
    return list;
2669
}
2670
 
2671
/**
2672
 * cairo_copy_clip_rectangle_list:
2673
 * @cr: a cairo context
2674
 *
2675
 * Gets the current clip region as a list of rectangles in user coordinates.
2676
 * Never returns %NULL.
2677
 *
2678
 * The status in the list may be %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
2679
 * indicate that the clip region cannot be represented as a list of
2680
 * user-space rectangles. The status may have other values to indicate
2681
 * other errors.
2682
 *
2683
 * Returns: the current clip region as a list of rectangles in user coordinates,
2684
 * which should be destroyed using cairo_rectangle_list_destroy().
2685
 *
2686
 * Since: 1.4
2687
 **/
2688
cairo_rectangle_list_t *
2689
cairo_copy_clip_rectangle_list (cairo_t *cr)
2690
{
2691
    if (unlikely (cr->status))
2692
        return _cairo_rectangle_list_create_in_error (cr->status);
2693
 
2694
    return _cairo_gstate_copy_clip_rectangle_list (cr->gstate);
2695
}
2696
 
2697
/**
2698
 * cairo_select_font_face:
2699
 * @cr: a #cairo_t
2700
 * @family: a font family name, encoded in UTF-8
2701
 * @slant: the slant for the font
2702
 * @weight: the weight for the font
2703
 *
2704
 * Note: The cairo_select_font_face() function call is part of what
2705
 * the cairo designers call the "toy" text API. It is convenient for
2706
 * short demos and simple programs, but it is not expected to be
2707
 * adequate for serious text-using applications.
2708
 *
2709
 * Selects a family and style of font from a simplified description as
2710
 * a family name, slant and weight. Cairo provides no operation to
2711
 * list available family names on the system (this is a "toy",
2712
 * remember), but the standard CSS2 generic family names, ("serif",
2713
 * "sans-serif", "cursive", "fantasy", "monospace"), are likely to
2714
 * work as expected.
2715
 *
2716
 * If @family starts with the string "@cairo:", or if no native font
2717
 * backends are compiled in, cairo will use an internal font family.
2718
 * The internal font family recognizes many modifiers in the @family
2719
 * string, most notably, it recognizes the string "monospace".  That is,
2720
 * the family name "@cairo:monospace" will use the monospace version of
2721
 * the internal font family.
2722
 *
2723
 * For "real" font selection, see the font-backend-specific
2724
 * font_face_create functions for the font backend you are using. (For
2725
 * example, if you are using the freetype-based cairo-ft font backend,
2726
 * see cairo_ft_font_face_create_for_ft_face() or
2727
 * cairo_ft_font_face_create_for_pattern().) The resulting font face
2728
 * could then be used with cairo_scaled_font_create() and
2729
 * cairo_set_scaled_font().
2730
 *
2731
 * Similarly, when using the "real" font support, you can call
2732
 * directly into the underlying font system, (such as fontconfig or
2733
 * freetype), for operations such as listing available fonts, etc.
2734
 *
2735
 * It is expected that most applications will need to use a more
2736
 * comprehensive font handling and text layout library, (for example,
2737
 * pango), in conjunction with cairo.
2738
 *
2739
 * If text is drawn without a call to cairo_select_font_face(), (nor
2740
 * cairo_set_font_face() nor cairo_set_scaled_font()), the default
2741
 * family is platform-specific, but is essentially "sans-serif".
2742
 * Default slant is %CAIRO_FONT_SLANT_NORMAL, and default weight is
2743
 * %CAIRO_FONT_WEIGHT_NORMAL.
2744
 *
2745
 * This function is equivalent to a call to cairo_toy_font_face_create()
2746
 * followed by cairo_set_font_face().
2747
 **/
2748
void
2749
cairo_select_font_face (cairo_t              *cr,
2750
                        const char           *family,
2751
                        cairo_font_slant_t    slant,
2752
                        cairo_font_weight_t   weight)
2753
{
2754
    cairo_status_t status;
2755
 
2756
    if (unlikely (cr->status))
2757
        return;
2758
 
2759
    status = _cairo_gstate_select_font_face (cr->gstate, family, slant, weight);
2760
    if (unlikely (status))
2761
        _cairo_set_error (cr, status);
2762
}
2763
 
2764
/**
2765
 * cairo_font_extents:
2766
 * @cr: a #cairo_t
2767
 * @extents: a #cairo_font_extents_t object into which the results
2768
 * will be stored.
2769
 *
2770
 * Gets the font extents for the currently selected font.
2771
 **/
2772
void
2773
cairo_font_extents (cairo_t              *cr,
2774
                    cairo_font_extents_t *extents)
2775
{
2776
    cairo_status_t status;
2777
 
2778
    extents->ascent = 0.0;
2779
    extents->descent = 0.0;
2780
    extents->height = 0.0;
2781
    extents->max_x_advance = 0.0;
2782
    extents->max_y_advance = 0.0;
2783
 
2784
    if (unlikely (cr->status))
2785
        return;
2786
 
2787
    status = _cairo_gstate_get_font_extents (cr->gstate, extents);
2788
    if (unlikely (status))
2789
        _cairo_set_error (cr, status);
2790
}
2791
 
2792
/**
2793
 * cairo_set_font_face:
2794
 * @cr: a #cairo_t
2795
 * @font_face: a #cairo_font_face_t, or %NULL to restore to the default font
2796
 *
2797
 * Replaces the current #cairo_font_face_t object in the #cairo_t with
2798
 * @font_face. The replaced font face in the #cairo_t will be
2799
 * destroyed if there are no other references to it.
2800
 **/
2801
void
2802
cairo_set_font_face (cairo_t           *cr,
2803
                     cairo_font_face_t *font_face)
2804
{
2805
    cairo_status_t status;
2806
 
2807
    if (unlikely (cr->status))
2808
        return;
2809
 
2810
    status = _cairo_gstate_set_font_face (cr->gstate, font_face);
2811
    if (unlikely (status))
2812
        _cairo_set_error (cr, status);
2813
}
2814
 
2815
/**
2816
 * cairo_get_font_face:
2817
 * @cr: a #cairo_t
2818
 *
2819
 * Gets the current font face for a #cairo_t.
2820
 *
2821
 * Return value: the current font face.  This object is owned by
2822
 * cairo. To keep a reference to it, you must call
2823
 * cairo_font_face_reference().
2824
 *
2825
 * This function never returns %NULL. If memory cannot be allocated, a
2826
 * special "nil" #cairo_font_face_t object will be returned on which
2827
 * cairo_font_face_status() returns %CAIRO_STATUS_NO_MEMORY. Using
2828
 * this nil object will cause its error state to propagate to other
2829
 * objects it is passed to, (for example, calling
2830
 * cairo_set_font_face() with a nil font will trigger an error that
2831
 * will shutdown the #cairo_t object).
2832
 **/
2833
cairo_font_face_t *
2834
cairo_get_font_face (cairo_t *cr)
2835
{
2836
    cairo_status_t status;
2837
    cairo_font_face_t *font_face;
2838
 
2839
    if (unlikely (cr->status))
2840
        return (cairo_font_face_t*) &_cairo_font_face_nil;
2841
 
2842
    status = _cairo_gstate_get_font_face (cr->gstate, &font_face);
2843
    if (unlikely (status)) {
2844
        _cairo_set_error (cr, status);
2845
        return (cairo_font_face_t*) &_cairo_font_face_nil;
2846
    }
2847
 
2848
    return font_face;
2849
}
2850
 
2851
/**
2852
 * cairo_set_font_size:
2853
 * @cr: a #cairo_t
2854
 * @size: the new font size, in user space units
2855
 *
2856
 * Sets the current font matrix to a scale by a factor of @size, replacing
2857
 * any font matrix previously set with cairo_set_font_size() or
2858
 * cairo_set_font_matrix(). This results in a font size of @size user space
2859
 * units. (More precisely, this matrix will result in the font's
2860
 * em-square being a @size by @size square in user space.)
2861
 *
2862
 * If text is drawn without a call to cairo_set_font_size(), (nor
2863
 * cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
2864
 * font size is 10.0.
2865
 **/
2866
void
2867
cairo_set_font_size (cairo_t *cr, double size)
2868
{
2869
    cairo_status_t status;
2870
 
2871
    if (unlikely (cr->status))
2872
        return;
2873
 
2874
    status = _cairo_gstate_set_font_size (cr->gstate, size);
2875
    if (unlikely (status))
2876
        _cairo_set_error (cr, status);
2877
}
2878
slim_hidden_def (cairo_set_font_size);
2879
 
2880
/**
2881
 * cairo_set_font_matrix
2882
 * @cr: a #cairo_t
2883
 * @matrix: a #cairo_matrix_t describing a transform to be applied to
2884
 * the current font.
2885
 *
2886
 * Sets the current font matrix to @matrix. The font matrix gives a
2887
 * transformation from the design space of the font (in this space,
2888
 * the em-square is 1 unit by 1 unit) to user space. Normally, a
2889
 * simple scale is used (see cairo_set_font_size()), but a more
2890
 * complex font matrix can be used to shear the font
2891
 * or stretch it unequally along the two axes
2892
 **/
2893
void
2894
cairo_set_font_matrix (cairo_t              *cr,
2895
                       const cairo_matrix_t *matrix)
2896
{
2897
    cairo_status_t status;
2898
 
2899
    if (unlikely (cr->status))
2900
        return;
2901
 
2902
    status = _cairo_gstate_set_font_matrix (cr->gstate, matrix);
2903
    if (unlikely (status))
2904
        _cairo_set_error (cr, status);
2905
}
2906
 
2907
/**
2908
 * cairo_get_font_matrix
2909
 * @cr: a #cairo_t
2910
 * @matrix: return value for the matrix
2911
 *
2912
 * Stores the current font matrix into @matrix. See
2913
 * cairo_set_font_matrix().
2914
 **/
2915
void
2916
cairo_get_font_matrix (cairo_t *cr, cairo_matrix_t *matrix)
2917
{
2918
    if (unlikely (cr->status)) {
2919
        cairo_matrix_init_identity (matrix);
2920
        return;
2921
    }
2922
 
2923
    _cairo_gstate_get_font_matrix (cr->gstate, matrix);
2924
}
2925
 
2926
/**
2927
 * cairo_set_font_options:
2928
 * @cr: a #cairo_t
2929
 * @options: font options to use
2930
 *
2931
 * Sets a set of custom font rendering options for the #cairo_t.
2932
 * Rendering options are derived by merging these options with the
2933
 * options derived from underlying surface; if the value in @options
2934
 * has a default value (like %CAIRO_ANTIALIAS_DEFAULT), then the value
2935
 * from the surface is used.
2936
 **/
2937
void
2938
cairo_set_font_options (cairo_t                    *cr,
2939
                        const cairo_font_options_t *options)
2940
{
2941
    cairo_status_t status;
2942
 
2943
    if (unlikely (cr->status))
2944
        return;
2945
 
2946
    status = cairo_font_options_status ((cairo_font_options_t *) options);
2947
    if (unlikely (status)) {
2948
        _cairo_set_error (cr, status);
2949
        return;
2950
    }
2951
 
2952
    _cairo_gstate_set_font_options (cr->gstate, options);
2953
}
2954
slim_hidden_def (cairo_set_font_options);
2955
 
2956
/**
2957
 * cairo_get_font_options:
2958
 * @cr: a #cairo_t
2959
 * @options: a #cairo_font_options_t object into which to store
2960
 *   the retrieved options. All existing values are overwritten
2961
 *
2962
 * Retrieves font rendering options set via #cairo_set_font_options.
2963
 * Note that the returned options do not include any options derived
2964
 * from the underlying surface; they are literally the options
2965
 * passed to cairo_set_font_options().
2966
 **/
2967
void
2968
cairo_get_font_options (cairo_t              *cr,
2969
                        cairo_font_options_t *options)
2970
{
2971
    /* check that we aren't trying to overwrite the nil object */
2972
    if (cairo_font_options_status (options))
2973
        return;
2974
 
2975
    if (unlikely (cr->status)) {
2976
        _cairo_font_options_init_default (options);
2977
        return;
2978
    }
2979
 
2980
    _cairo_gstate_get_font_options (cr->gstate, options);
2981
}
2982
 
2983
/**
2984
 * cairo_set_scaled_font:
2985
 * @cr: a #cairo_t
2986
 * @scaled_font: a #cairo_scaled_font_t
2987
 *
2988
 * Replaces the current font face, font matrix, and font options in
2989
 * the #cairo_t with those of the #cairo_scaled_font_t.  Except for
2990
 * some translation, the current CTM of the #cairo_t should be the
2991
 * same as that of the #cairo_scaled_font_t, which can be accessed
2992
 * using cairo_scaled_font_get_ctm().
2993
 *
2994
 * Since: 1.2
2995
 **/
2996
void
2997
cairo_set_scaled_font (cairo_t                   *cr,
2998
                       const cairo_scaled_font_t *scaled_font)
2999
{
3000
    cairo_status_t status;
3001
    cairo_bool_t was_previous;
3002
 
3003
    if (unlikely (cr->status))
3004
        return;
3005
 
3006
    if (scaled_font == NULL) {
3007
        status = _cairo_error (CAIRO_STATUS_NULL_POINTER);
3008
        goto BAIL;
3009
    }
3010
 
3011
    status = scaled_font->status;
3012
    if (unlikely (status))
3013
        goto BAIL;
3014
 
3015
    if (scaled_font == cr->gstate->scaled_font)
3016
        return;
3017
 
3018
    was_previous = scaled_font == cr->gstate->previous_scaled_font;
3019
 
3020
    status = _cairo_gstate_set_font_face (cr->gstate, scaled_font->font_face);
3021
    if (unlikely (status))
3022
        goto BAIL;
3023
 
3024
    status = _cairo_gstate_set_font_matrix (cr->gstate, &scaled_font->font_matrix);
3025
    if (unlikely (status))
3026
        goto BAIL;
3027
 
3028
    _cairo_gstate_set_font_options (cr->gstate, &scaled_font->options);
3029
 
3030
    if (was_previous)
3031
        cr->gstate->scaled_font = cairo_scaled_font_reference ((cairo_scaled_font_t *) scaled_font);
3032
 
3033
    return;
3034
 
3035
BAIL:
3036
    _cairo_set_error (cr, status);
3037
}
3038
 
3039
/**
3040
 * cairo_get_scaled_font:
3041
 * @cr: a #cairo_t
3042
 *
3043
 * Gets the current scaled font for a #cairo_t.
3044
 *
3045
 * Return value: the current scaled font. This object is owned by
3046
 * cairo. To keep a reference to it, you must call
3047
 * cairo_scaled_font_reference().
3048
 *
3049
 * This function never returns %NULL. If memory cannot be allocated, a
3050
 * special "nil" #cairo_scaled_font_t object will be returned on which
3051
 * cairo_scaled_font_status() returns %CAIRO_STATUS_NO_MEMORY. Using
3052
 * this nil object will cause its error state to propagate to other
3053
 * objects it is passed to, (for example, calling
3054
 * cairo_set_scaled_font() with a nil font will trigger an error that
3055
 * will shutdown the #cairo_t object).
3056
 *
3057
 * Since: 1.4
3058
 **/
3059
cairo_scaled_font_t *
3060
cairo_get_scaled_font (cairo_t *cr)
3061
{
3062
    cairo_status_t status;
3063
    cairo_scaled_font_t *scaled_font;
3064
 
3065
    if (unlikely (cr->status))
3066
        return _cairo_scaled_font_create_in_error (cr->status);
3067
 
3068
    status = _cairo_gstate_get_scaled_font (cr->gstate, &scaled_font);
3069
    if (unlikely (status)) {
3070
        _cairo_set_error (cr, status);
3071
        return _cairo_scaled_font_create_in_error (status);
3072
    }
3073
 
3074
    return scaled_font;
3075
}
3076
 
3077
/**
3078
 * cairo_text_extents:
3079
 * @cr: a #cairo_t
3080
 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3081
 * @extents: a #cairo_text_extents_t object into which the results
3082
 * will be stored
3083
 *
3084
 * Gets the extents for a string of text. The extents describe a
3085
 * user-space rectangle that encloses the "inked" portion of the text,
3086
 * (as it would be drawn by cairo_show_text()). Additionally, the
3087
 * x_advance and y_advance values indicate the amount by which the
3088
 * current point would be advanced by cairo_show_text().
3089
 *
3090
 * Note that whitespace characters do not directly contribute to the
3091
 * size of the rectangle (extents.width and extents.height). They do
3092
 * contribute indirectly by changing the position of non-whitespace
3093
 * characters. In particular, trailing whitespace characters are
3094
 * likely to not affect the size of the rectangle, though they will
3095
 * affect the x_advance and y_advance values.
3096
 **/
3097
void
3098
cairo_text_extents (cairo_t              *cr,
3099
                    const char           *utf8,
3100
                    cairo_text_extents_t *extents)
3101
{
3102
    cairo_status_t status;
3103
    cairo_glyph_t *glyphs = NULL;
3104
    int num_glyphs;
3105
    double x, y;
3106
 
3107
    extents->x_bearing = 0.0;
3108
    extents->y_bearing = 0.0;
3109
    extents->width  = 0.0;
3110
    extents->height = 0.0;
3111
    extents->x_advance = 0.0;
3112
    extents->y_advance = 0.0;
3113
 
3114
    if (unlikely (cr->status))
3115
        return;
3116
 
3117
    if (utf8 == NULL)
3118
        return;
3119
 
3120
    cairo_get_current_point (cr, &x, &y);
3121
 
3122
    status = _cairo_gstate_text_to_glyphs (cr->gstate,
3123
                                           x, y,
3124
                                           utf8, strlen (utf8),
3125
                                           &glyphs, &num_glyphs,
3126
                                           NULL, NULL,
3127
                                           NULL);
3128
 
3129
    if (status == CAIRO_STATUS_SUCCESS)
3130
        status = _cairo_gstate_glyph_extents (cr->gstate,
3131
                                              glyphs, num_glyphs,
3132
                                              extents);
3133
    cairo_glyph_free (glyphs);
3134
 
3135
    if (unlikely (status))
3136
        _cairo_set_error (cr, status);
3137
}
3138
 
3139
/**
3140
 * cairo_glyph_extents:
3141
 * @cr: a #cairo_t
3142
 * @glyphs: an array of #cairo_glyph_t objects
3143
 * @num_glyphs: the number of elements in @glyphs
3144
 * @extents: a #cairo_text_extents_t object into which the results
3145
 * will be stored
3146
 *
3147
 * Gets the extents for an array of glyphs. The extents describe a
3148
 * user-space rectangle that encloses the "inked" portion of the
3149
 * glyphs, (as they would be drawn by cairo_show_glyphs()).
3150
 * Additionally, the x_advance and y_advance values indicate the
3151
 * amount by which the current point would be advanced by
3152
 * cairo_show_glyphs().
3153
 *
3154
 * Note that whitespace glyphs do not contribute to the size of the
3155
 * rectangle (extents.width and extents.height).
3156
 **/
3157
void
3158
cairo_glyph_extents (cairo_t                *cr,
3159
                     const cairo_glyph_t    *glyphs,
3160
                     int                    num_glyphs,
3161
                     cairo_text_extents_t   *extents)
3162
{
3163
    cairo_status_t status;
3164
 
3165
    extents->x_bearing = 0.0;
3166
    extents->y_bearing = 0.0;
3167
    extents->width  = 0.0;
3168
    extents->height = 0.0;
3169
    extents->x_advance = 0.0;
3170
    extents->y_advance = 0.0;
3171
 
3172
    if (unlikely (cr->status))
3173
        return;
3174
 
3175
    if (num_glyphs == 0)
3176
        return;
3177
 
3178
    if (num_glyphs < 0) {
3179
        _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3180
        return;
3181
    }
3182
 
3183
    if (glyphs == NULL) {
3184
        _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3185
        return;
3186
    }
3187
 
3188
    status = _cairo_gstate_glyph_extents (cr->gstate, glyphs, num_glyphs,
3189
                                          extents);
3190
    if (unlikely (status))
3191
        _cairo_set_error (cr, status);
3192
}
3193
 
3194
/**
3195
 * cairo_show_text:
3196
 * @cr: a cairo context
3197
 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3198
 *
3199
 * A drawing operator that generates the shape from a string of UTF-8
3200
 * characters, rendered according to the current font_face, font_size
3201
 * (font_matrix), and font_options.
3202
 *
3203
 * This function first computes a set of glyphs for the string of
3204
 * text. The first glyph is placed so that its origin is at the
3205
 * current point. The origin of each subsequent glyph is offset from
3206
 * that of the previous glyph by the advance values of the previous
3207
 * glyph.
3208
 *
3209
 * After this call the current point is moved to the origin of where
3210
 * the next glyph would be placed in this same progression. That is,
3211
 * the current point will be at the origin of the final glyph offset
3212
 * by its advance values. This allows for easy display of a single
3213
 * logical string with multiple calls to cairo_show_text().
3214
 *
3215
 * Note: The cairo_show_text() function call is part of what the cairo
3216
 * designers call the "toy" text API. It is convenient for short demos
3217
 * and simple programs, but it is not expected to be adequate for
3218
 * serious text-using applications. See cairo_show_glyphs() for the
3219
 * "real" text display API in cairo.
3220
 **/
3221
void
3222
cairo_show_text (cairo_t *cr, const char *utf8)
3223
{
3224
    cairo_text_extents_t extents;
3225
    cairo_status_t status;
3226
    cairo_glyph_t *glyphs, *last_glyph;
3227
    cairo_text_cluster_t *clusters;
3228
    int utf8_len, num_glyphs, num_clusters;
3229
    cairo_text_cluster_flags_t cluster_flags;
3230
    double x, y;
3231
    cairo_bool_t has_show_text_glyphs;
3232
    cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3233
    cairo_text_cluster_t stack_clusters[CAIRO_STACK_ARRAY_LENGTH (cairo_text_cluster_t)];
3234
 
3235
    if (unlikely (cr->status))
3236
        return;
3237
 
3238
    if (utf8 == NULL)
3239
        return;
3240
 
3241
    cairo_get_current_point (cr, &x, &y);
3242
 
3243
    utf8_len = strlen (utf8);
3244
 
3245
    has_show_text_glyphs =
3246
        cairo_surface_has_show_text_glyphs (cairo_get_target (cr));
3247
 
3248
    glyphs = stack_glyphs;
3249
    num_glyphs = ARRAY_LENGTH (stack_glyphs);
3250
 
3251
    if (has_show_text_glyphs) {
3252
        clusters = stack_clusters;
3253
        num_clusters = ARRAY_LENGTH (stack_clusters);
3254
    } else {
3255
        clusters = NULL;
3256
        num_clusters = 0;
3257
    }
3258
 
3259
    status = _cairo_gstate_text_to_glyphs (cr->gstate,
3260
                                           x, y,
3261
                                           utf8, utf8_len,
3262
                                           &glyphs, &num_glyphs,
3263
                                           has_show_text_glyphs ? &clusters : NULL, &num_clusters,
3264
                                           &cluster_flags);
3265
    if (unlikely (status))
3266
        goto BAIL;
3267
 
3268
    if (num_glyphs == 0)
3269
        return;
3270
 
3271
    status = _cairo_gstate_show_text_glyphs (cr->gstate,
3272
                                             utf8, utf8_len,
3273
                                             glyphs, num_glyphs,
3274
                                             clusters, num_clusters,
3275
                                             cluster_flags);
3276
    if (unlikely (status))
3277
        goto BAIL;
3278
 
3279
    last_glyph = &glyphs[num_glyphs - 1];
3280
    status = _cairo_gstate_glyph_extents (cr->gstate,
3281
                                          last_glyph, 1,
3282
                                          &extents);
3283
    if (unlikely (status))
3284
        goto BAIL;
3285
 
3286
    x = last_glyph->x + extents.x_advance;
3287
    y = last_glyph->y + extents.y_advance;
3288
    cairo_move_to (cr, x, y);
3289
 
3290
 BAIL:
3291
    if (glyphs != stack_glyphs)
3292
        cairo_glyph_free (glyphs);
3293
    if (clusters != stack_clusters)
3294
        cairo_text_cluster_free (clusters);
3295
 
3296
    if (unlikely (status))
3297
        _cairo_set_error (cr, status);
3298
}
3299
 
3300
/**
3301
 * cairo_show_glyphs:
3302
 * @cr: a cairo context
3303
 * @glyphs: array of glyphs to show
3304
 * @num_glyphs: number of glyphs to show
3305
 *
3306
 * A drawing operator that generates the shape from an array of glyphs,
3307
 * rendered according to the current font face, font size
3308
 * (font matrix), and font options.
3309
 **/
3310
void
3311
cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
3312
{
3313
    cairo_status_t status;
3314
 
3315
    if (unlikely (cr->status))
3316
        return;
3317
 
3318
    if (num_glyphs == 0)
3319
        return;
3320
 
3321
    if (num_glyphs < 0) {
3322
        _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3323
        return;
3324
    }
3325
 
3326
    if (glyphs == NULL) {
3327
        _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3328
        return;
3329
    }
3330
 
3331
    status = _cairo_gstate_show_text_glyphs (cr->gstate,
3332
                                             NULL, 0,
3333
                                             glyphs, num_glyphs,
3334
                                             NULL, 0,
3335
                                             FALSE);
3336
    if (unlikely (status))
3337
        _cairo_set_error (cr, status);
3338
}
3339
 
3340
/**
3341
 * cairo_show_text_glyphs:
3342
 * @cr: a cairo context
3343
 * @utf8: a string of text encoded in UTF-8
3344
 * @utf8_len: length of @utf8 in bytes, or -1 if it is NUL-terminated
3345
 * @glyphs: array of glyphs to show
3346
 * @num_glyphs: number of glyphs to show
3347
 * @clusters: array of cluster mapping information
3348
 * @num_clusters: number of clusters in the mapping
3349
 * @cluster_flags: cluster mapping flags
3350
 *
3351
 * This operation has rendering effects similar to cairo_show_glyphs()
3352
 * but, if the target surface supports it, uses the provided text and
3353
 * cluster mapping to embed the text for the glyphs shown in the output.
3354
 * If the target does not support the extended attributes, this function
3355
 * acts like the basic cairo_show_glyphs() as if it had been passed
3356
 * @glyphs and @num_glyphs.
3357
 *
3358
 * The mapping between @utf8 and @glyphs is provided by an array of
3359
 * <firstterm>clusters</firstterm>.  Each cluster covers a number of
3360
 * text bytes and glyphs, and neighboring clusters cover neighboring
3361
 * areas of @utf8 and @glyphs.  The clusters should collectively cover @utf8
3362
 * and @glyphs in entirety.
3363
 *
3364
 * The first cluster always covers bytes from the beginning of @utf8.
3365
 * If @cluster_flags do not have the %CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
3366
 * set, the first cluster also covers the beginning
3367
 * of @glyphs, otherwise it covers the end of the @glyphs array and
3368
 * following clusters move backward.
3369
 *
3370
 * See #cairo_text_cluster_t for constraints on valid clusters.
3371
 *
3372
 * Since: 1.8
3373
 **/
3374
void
3375
cairo_show_text_glyphs (cairo_t                    *cr,
3376
                        const char                 *utf8,
3377
                        int                         utf8_len,
3378
                        const cairo_glyph_t        *glyphs,
3379
                        int                         num_glyphs,
3380
                        const cairo_text_cluster_t *clusters,
3381
                        int                         num_clusters,
3382
                        cairo_text_cluster_flags_t  cluster_flags)
3383
{
3384
    cairo_status_t status;
3385
 
3386
    if (unlikely (cr->status))
3387
        return;
3388
 
3389
    /* A slew of sanity checks */
3390
 
3391
    /* Special case for NULL and -1 */
3392
    if (utf8 == NULL && utf8_len == -1)
3393
        utf8_len = 0;
3394
 
3395
    /* No NULLs for non-zeros */
3396
    if ((num_glyphs   && glyphs   == NULL) ||
3397
        (utf8_len     && utf8     == NULL) ||
3398
        (num_clusters && clusters == NULL)) {
3399
        _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3400
        return;
3401
    }
3402
 
3403
    /* A -1 for utf8_len means NUL-terminated */
3404
    if (utf8_len == -1)
3405
        utf8_len = strlen (utf8);
3406
 
3407
    /* Apart from that, no negatives */
3408
    if (num_glyphs < 0 || utf8_len < 0 || num_clusters < 0) {
3409
        _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3410
        return;
3411
    }
3412
 
3413
    /* Make sure clusters cover the entire glyphs and utf8 arrays,
3414
     * and that cluster boundaries are UTF-8 boundaries. */
3415
    status = _cairo_validate_text_clusters (utf8, utf8_len,
3416
                                            glyphs, num_glyphs,
3417
                                            clusters, num_clusters, cluster_flags);
3418
    if (status == CAIRO_STATUS_INVALID_CLUSTERS) {
3419
        /* Either got invalid UTF-8 text, or cluster mapping is bad.
3420
         * Differentiate those. */
3421
 
3422
        cairo_status_t status2;
3423
 
3424
        status2 = _cairo_utf8_to_ucs4 (utf8, utf8_len, NULL, NULL);
3425
        if (status2)
3426
            status = status2;
3427
 
3428
        _cairo_set_error (cr, status);
3429
        return;
3430
    }
3431
 
3432
    if (num_glyphs == 0 && utf8_len == 0)
3433
        return;
3434
 
3435
    status = _cairo_gstate_show_text_glyphs (cr->gstate,
3436
                                             utf8, utf8_len,
3437
                                             glyphs, num_glyphs,
3438
                                             clusters, num_clusters, cluster_flags);
3439
    if (unlikely (status))
3440
        _cairo_set_error (cr, status);
3441
}
3442
 
3443
/**
3444
 * cairo_text_path:
3445
 * @cr: a cairo context
3446
 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3447
 *
3448
 * Adds closed paths for text to the current path.  The generated
3449
 * path if filled, achieves an effect similar to that of
3450
 * cairo_show_text().
3451
 *
3452
 * Text conversion and positioning is done similar to cairo_show_text().
3453
 *
3454
 * Like cairo_show_text(), After this call the current point is
3455
 * moved to the origin of where the next glyph would be placed in
3456
 * this same progression.  That is, the current point will be at
3457
 * the origin of the final glyph offset by its advance values.
3458
 * This allows for chaining multiple calls to to cairo_text_path()
3459
 * without having to set current point in between.
3460
 *
3461
 * Note: The cairo_text_path() function call is part of what the cairo
3462
 * designers call the "toy" text API. It is convenient for short demos
3463
 * and simple programs, but it is not expected to be adequate for
3464
 * serious text-using applications. See cairo_glyph_path() for the
3465
 * "real" text path API in cairo.
3466
 **/
3467
void
3468
cairo_text_path  (cairo_t *cr, const char *utf8)
3469
{
3470
    cairo_status_t status;
3471
    cairo_text_extents_t extents;
3472
    cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3473
    cairo_glyph_t *glyphs, *last_glyph;
3474
    int num_glyphs;
3475
    double x, y;
3476
 
3477
    if (unlikely (cr->status))
3478
        return;
3479
 
3480
    if (utf8 == NULL)
3481
        return;
3482
 
3483
    cairo_get_current_point (cr, &x, &y);
3484
 
3485
    glyphs = stack_glyphs;
3486
    num_glyphs = ARRAY_LENGTH (stack_glyphs);
3487
 
3488
    status = _cairo_gstate_text_to_glyphs (cr->gstate,
3489
                                           x, y,
3490
                                           utf8, strlen (utf8),
3491
                                           &glyphs, &num_glyphs,
3492
                                           NULL, NULL,
3493
                                           NULL);
3494
 
3495
    if (unlikely (status))
3496
        goto BAIL;
3497
 
3498
    if (num_glyphs == 0)
3499
        return;
3500
 
3501
    status = _cairo_gstate_glyph_path (cr->gstate,
3502
                                       glyphs, num_glyphs,
3503
                                       cr->path);
3504
 
3505
    if (unlikely (status))
3506
        goto BAIL;
3507
 
3508
    last_glyph = &glyphs[num_glyphs - 1];
3509
    status = _cairo_gstate_glyph_extents (cr->gstate,
3510
                                          last_glyph, 1,
3511
                                          &extents);
3512
 
3513
    if (unlikely (status))
3514
        goto BAIL;
3515
 
3516
    x = last_glyph->x + extents.x_advance;
3517
    y = last_glyph->y + extents.y_advance;
3518
    cairo_move_to (cr, x, y);
3519
 
3520
 BAIL:
3521
    if (glyphs != stack_glyphs)
3522
        cairo_glyph_free (glyphs);
3523
 
3524
    if (unlikely (status))