This repository was archived by the owner on Aug 31, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 31
Expand file tree
/
Copy pathcairo.h
More file actions
1455 lines (1225 loc) · 46.4 KB
/
Copy pathcairo.h
File metadata and controls
1455 lines (1225 loc) · 46.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/* cairo - a vector graphics library with display and print output
*
* Copyright © 2002 University of Southern California
* Copyright © 2005 Red Hat, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it either under the terms of the GNU Lesser General Public
* License version 2.1 as published by the Free Software Foundation
* (the "LGPL") or, at your option, under the terms of the Mozilla
* Public License Version 1.1 (the "MPL"). If you do not alter this
* notice, a recipient may use your version of this file under either
* the MPL or the LGPL.
*
* You should have received a copy of the LGPL along with this library
* in the file COPYING-LGPL-2.1; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* You should have received a copy of the MPL along with this library
* in the file COPYING-MPL-1.1
*
* The contents of this file are subject to the Mozilla Public License
* Version 1.1 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
* OF ANY KIND, either express or implied. See the LGPL or the MPL for
* the specific language governing rights and limitations.
*
* The Original Code is the cairo graphics library.
*
* The Initial Developer of the Original Code is University of Southern
* California.
*
* Contributor(s):
* Carl D. Worth <cworth@cworth.org>
*/
#ifndef CAIRO_H
#define CAIRO_H
#include <cairo-features.h>
CAIRO_BEGIN_DECLS
#define CAIRO_VERSION_ENCODE(major, minor, micro) ( \
((major) * 10000) \
+ ((minor) * 100) \
+ ((micro) * 1))
#define CAIRO_VERSION CAIRO_VERSION_ENCODE( \
CAIRO_VERSION_MAJOR, \
CAIRO_VERSION_MINOR, \
CAIRO_VERSION_MICRO)
int
cairo_version (void);
const char*
cairo_version_string (void);
/**
* cairo_bool_t:
*
* #cairo_bool_t is used for boolean values. Returns of type
* #cairo_bool_t will always be either 0 or 1, but testing against
* these values explicitly is not encouraged; just use the
* value as a boolean condition.
*
* <informalexample><programlisting>
* if (cairo_in_stroke (cr, x, y)) {
* /<!-- -->* do something *<!-- -->/
* }
* </programlisting></informalexample>
*/
typedef int cairo_bool_t;
/**
* cairo_t:
*
* A #cairo_t contains the current state of the rendering device,
* including coordinates of yet to be drawn shapes.
**/
typedef struct _cairo cairo_t;
/**
* cairo_surface_t:
*
* A #cairo_surface_t represents an image, either as the destination
* of a drawing operation or as source when drawing onto another
* surface. There are different subtypes of cairo_surface_t for
* different drawing backends; for example, cairo_image_surface_create()
* creates a bitmap image in memory.
*
* Memory management of #cairo_surface_t is done with
* cairo_surface_reference() and cairo_surface_destroy().
*/
typedef struct _cairo_surface cairo_surface_t;
/**
* cairo_matrix_t:
* @xx: xx component of the affine transformation
* @yx: yx component of the affine transformation
* @xy: xy component of the affine transformation
* @yy: yy component of the affine transformation
* @x0: X translation component of the affine transformation
* @y0: Y translation component of the affine transformation
*
* A #cairo_matrix_t holds an affine transformation, such as a scale,
* rotation, shear, or a combination of those. The transformation of
* a point (x, y) is given by:
* <programlisting>
* x_new = xx * x + xy * y + x0;
* y_new = yx * x + yy * y + y0;
* </programlisting>
**/
typedef struct _cairo_matrix {
double xx; double yx;
double xy; double yy;
double x0; double y0;
} cairo_matrix_t;
typedef struct _cairo_pattern cairo_pattern_t;
/**
* cairo_destroy_func_t:
* @data: The data element being destroyed.
*
* #cairo_destroy_func_t the type of function which is called when a
* data element is destroyed. It is passed the pointer to the data
* element and should free any memory and resources allocated for it.
*/
typedef void (*cairo_destroy_func_t) (void *data);
/**
* cairo_user_data_key_t:
* @unused: not used; ignore.
*
* #cairo_user_data_key_t is used for attaching user data to cairo
* data structures. The actual contents of the struct is never used,
* and there is no need to initialize the object; only the unique
* address of a #cairo_data_key_t object is used. Typically, you
* would just use the address of a static #cairo_data_key_t object.
*/
typedef struct _cairo_user_data_key {
int unused;
} cairo_user_data_key_t;
/**
* cairo_status_t
* @CAIRO_STATUS_SUCCESS: no error has occurred
* @CAIRO_STATUS_NO_MEMORY: out of memory
* @CAIRO_STATUS_INVALID_RESTORE: cairo_restore without matching cairo_save
* @CAIRO_STATUS_INVALID_POP_GROUP: no saved group to pop
* @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined
* @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible)
* @CAIRO_STATUS_INVALID_STATUS: invalid value for an input cairo_status_t
* @CAIRO_STATUS_NULL_POINTER: NULL pointer
* @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8
* @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid
* @CAIRO_STATUS_READ_ERROR: error while reading from input stream
* @CAIRO_STATUS_WRITE_ERROR: error while writing to output stream
* @CAIRO_STATUS_SURFACE_FINISHED: target surface has been finished
* @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: the surface type is not appropriate for the operation
* @CAIRO_STATUS_PATTERN_TYPE_MISMATCH: the pattern type is not appropriate for the operation
* @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input cairo_content_t
* @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input cairo_format_t
* @CAIRO_STATUS_INVALID_VISUAL: invalid value for an input Visual*
* @CAIRO_STATUS_FILE_NOT_FOUND: file not found
* @CAIRO_STATUS_INVALID_DASH: invalid value for a dash setting
*
* #cairo_status_t is used to indicate errors that can occur when
* using Cairo. In some cases it is returned directly by functions.
* but when using #cairo_t, the last error, if any, is stored in
* the context and can be retrieved with cairo_status().
**/
typedef enum _cairo_status {
CAIRO_STATUS_SUCCESS = 0,
CAIRO_STATUS_NO_MEMORY,
CAIRO_STATUS_INVALID_RESTORE,
CAIRO_STATUS_INVALID_POP_GROUP,
CAIRO_STATUS_NO_CURRENT_POINT,
CAIRO_STATUS_INVALID_MATRIX,
CAIRO_STATUS_INVALID_STATUS,
CAIRO_STATUS_NULL_POINTER,
CAIRO_STATUS_INVALID_STRING,
CAIRO_STATUS_INVALID_PATH_DATA,
CAIRO_STATUS_READ_ERROR,
CAIRO_STATUS_WRITE_ERROR,
CAIRO_STATUS_SURFACE_FINISHED,
CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
CAIRO_STATUS_PATTERN_TYPE_MISMATCH,
CAIRO_STATUS_INVALID_CONTENT,
CAIRO_STATUS_INVALID_FORMAT,
CAIRO_STATUS_INVALID_VISUAL,
CAIRO_STATUS_FILE_NOT_FOUND,
CAIRO_STATUS_INVALID_DASH
} cairo_status_t;
/**
* cairo_write_func_t:
* @closure: the output closure
* @data: the buffer containing the data to write
* @length: the amount of data to write
*
* #cairo_write_func_t is the type of function which is called when a
* backend needs to write data to an output stream. It is passed the
* closure which was specified by the user at the time the write
* function was registered, the data to write and the length of the
* data in bytes. The write function should return
* CAIRO_STATUS_SUCCESS if all the data was successfully written,
* CAIRO_STATUS_WRITE_ERROR otherwise.
*
* Returns: the status code of the write operation
*/
typedef cairo_status_t (*cairo_write_func_t) (void *closure,
const unsigned char *data,
unsigned int length);
/**
* cairo_read_func_t:
* @closure: the input closure
* @data: the buffer into which to read the data
* @length: the amount of data to read
*
* #cairo_read_func_t is the type of function which is called when a
* backend needs to read data from an intput stream. It is passed the
* closure which was specified by the user at the time the read
* function was registered, the buffer to read the data into and the
* length of the data in bytes. The read function should return
* CAIRO_STATUS_SUCCESS if all the data was successfully read,
* CAIRO_STATUS_READ_ERROR otherwise.
*
* Returns: the status code of the read operation
*/
typedef cairo_status_t (*cairo_read_func_t) (void *closure,
unsigned char *data,
unsigned int length);
/* Functions for manipulating state objects */
cairo_t *
cairo_create (cairo_surface_t *target);
cairo_t *
cairo_reference (cairo_t *cr);
void
cairo_destroy (cairo_t *cr);
void
cairo_save (cairo_t *cr);
void
cairo_restore (cairo_t *cr);
/* XXX: I want to rethink this API
void
cairo_push_group (cairo_t *cr);
void
cairo_pop_group (cairo_t *cr);
*/
/* Modify state */
typedef enum _cairo_operator {
CAIRO_OPERATOR_CLEAR,
CAIRO_OPERATOR_SOURCE,
CAIRO_OPERATOR_OVER,
CAIRO_OPERATOR_IN,
CAIRO_OPERATOR_OUT,
CAIRO_OPERATOR_ATOP,
CAIRO_OPERATOR_DEST,
CAIRO_OPERATOR_DEST_OVER,
CAIRO_OPERATOR_DEST_IN,
CAIRO_OPERATOR_DEST_OUT,
CAIRO_OPERATOR_DEST_ATOP,
CAIRO_OPERATOR_XOR,
CAIRO_OPERATOR_ADD,
CAIRO_OPERATOR_SATURATE
} cairo_operator_t;
void
cairo_set_operator (cairo_t *cr, cairo_operator_t op);
void
cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
void
cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue);
void
cairo_set_source_rgba (cairo_t *cr,
double red, double green, double blue,
double alpha);
void
cairo_set_source_surface (cairo_t *cr,
cairo_surface_t *surface,
double x,
double y);
void
cairo_set_tolerance (cairo_t *cr, double tolerance);
/**
* cairo_antialias_t:
* @CAIRO_ANTIALIAS_DEFAULT: Use the default antialiasing for
* the subsystem and target device
* @CAIRO_ANTIALIAS_NONE: Use a bilevel alpha mask
* @CAIRO_ANTIALIAS_GRAY: Perform single-color antialiasing (using
* shades of gray for black text on a white background, for example).
* @CAIRO_ANTIALIAS_SUBPIXEL: Perform antialiasing by taking
* advantage of the order of subpixel elements on devices
* such as LCD panels
*
* Specifies the type of antialiasing to do when rendering text or shapes.
**/
typedef enum _cairo_antialias {
CAIRO_ANTIALIAS_DEFAULT,
CAIRO_ANTIALIAS_NONE,
CAIRO_ANTIALIAS_GRAY,
CAIRO_ANTIALIAS_SUBPIXEL
} cairo_antialias_t;
void
cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);
/**
* cairo_fill_rule_t
* @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from
* left-to-right, counts +1. If the path crosses the ray
* from right to left, counts -1. (Left and right are determined
* from the perspective of looking along the ray from the starting
* point.) If the total count is non-zero, the point will be filled.
* @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of
* intersections, without regard to the orientation of the contour. If
* the total number of intersections is odd, the point will be
* filled.
*
* #cairo_fill_rule_t is used to select how paths are filled. For both
* fill rules, whether or not a point is included in the fill is
* determined by taking a ray from that point to infinity and looking
* at intersections with the path. The ray can be in any direction,
* as long as it doesn't pass through the end point of a segment
* or have a tricky intersection such as intersecting tangent to the path.
* (Note that filling is not actually implemented in this way. This
* is just a description of the rule that is applied.)
**/
typedef enum _cairo_fill_rule {
CAIRO_FILL_RULE_WINDING,
CAIRO_FILL_RULE_EVEN_ODD
} cairo_fill_rule_t;
void
cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule);
void
cairo_set_line_width (cairo_t *cr, double width);
/**
* cairo_line_cap_t
* @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point
* @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point
* @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point
*
* enumeration for style of line-endings
**/
typedef enum _cairo_line_cap {
CAIRO_LINE_CAP_BUTT,
CAIRO_LINE_CAP_ROUND,
CAIRO_LINE_CAP_SQUARE
} cairo_line_cap_t;
void
cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
typedef enum _cairo_line_join {
CAIRO_LINE_JOIN_MITER,
CAIRO_LINE_JOIN_ROUND,
CAIRO_LINE_JOIN_BEVEL
} cairo_line_join_t;
void
cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join);
void
cairo_set_dash (cairo_t *cr,
double *dashes,
int num_dashes,
double offset);
void
cairo_set_miter_limit (cairo_t *cr, double limit);
void
cairo_translate (cairo_t *cr, double tx, double ty);
void
cairo_scale (cairo_t *cr, double sx, double sy);
void
cairo_rotate (cairo_t *cr, double angle);
void
cairo_transform (cairo_t *cr,
const cairo_matrix_t *matrix);
void
cairo_set_matrix (cairo_t *cr,
const cairo_matrix_t *matrix);
void
cairo_identity_matrix (cairo_t *cr);
void
cairo_user_to_device (cairo_t *cr, double *x, double *y);
void
cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
void
cairo_device_to_user (cairo_t *cr, double *x, double *y);
void
cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
/* Path creation functions */
void
cairo_new_path (cairo_t *cr);
void
cairo_move_to (cairo_t *cr, double x, double y);
void
cairo_line_to (cairo_t *cr, double x, double y);
void
cairo_curve_to (cairo_t *cr,
double x1, double y1,
double x2, double y2,
double x3, double y3);
void
cairo_arc (cairo_t *cr,
double xc, double yc,
double radius,
double angle1, double angle2);
void
cairo_arc_negative (cairo_t *cr,
double xc, double yc,
double radius,
double angle1, double angle2);
/* XXX: NYI
void
cairo_arc_to (cairo_t *cr,
double x1, double y1,
double x2, double y2,
double radius);
*/
void
cairo_rel_move_to (cairo_t *cr, double dx, double dy);
void
cairo_rel_line_to (cairo_t *cr, double dx, double dy);
void
cairo_rel_curve_to (cairo_t *cr,
double dx1, double dy1,
double dx2, double dy2,
double dx3, double dy3);
void
cairo_rectangle (cairo_t *cr,
double x, double y,
double width, double height);
/* XXX: NYI
void
cairo_stroke_to_path (cairo_t *cr);
*/
void
cairo_close_path (cairo_t *cr);
/* Painting functions */
void
cairo_paint (cairo_t *cr);
void
cairo_paint_with_alpha (cairo_t *cr,
double alpha);
void
cairo_mask (cairo_t *cr,
cairo_pattern_t *pattern);
void
cairo_mask_surface (cairo_t *cr,
cairo_surface_t *surface,
double surface_x,
double surface_y);
void
cairo_stroke (cairo_t *cr);
void
cairo_stroke_preserve (cairo_t *cr);
void
cairo_fill (cairo_t *cr);
void
cairo_fill_preserve (cairo_t *cr);
void
cairo_copy_page (cairo_t *cr);
void
cairo_show_page (cairo_t *cr);
/* Insideness testing */
cairo_bool_t
cairo_in_stroke (cairo_t *cr, double x, double y);
cairo_bool_t
cairo_in_fill (cairo_t *cr, double x, double y);
/* Rectangular extents */
void
cairo_stroke_extents (cairo_t *cr,
double *x1, double *y1,
double *x2, double *y2);
void
cairo_fill_extents (cairo_t *cr,
double *x1, double *y1,
double *x2, double *y2);
/* Clipping */
void
cairo_reset_clip (cairo_t *cr);
void
cairo_clip (cairo_t *cr);
void
cairo_clip_preserve (cairo_t *cr);
/* Font/Text functions */
/**
* cairo_scaled_font_t:
*
* A #cairo_scaled_font_t is a font scaled to a particular size and device
* resolution. A cairo_scaled_font_t is most useful for low-level font
* usage where a library or application wants to cache a reference
* to a scaled font to speed up the computation of metrics.
*/
typedef struct _cairo_scaled_font cairo_scaled_font_t;
/**
* cairo_font_face_t:
*
* A #cairo_font_face_t specifies all aspects of a font other
* than the size or font matrix (a font matrix is used to distort
* a font by sheering it or scaling it unequally in the two
* directions) . A font face can be set on a #cairo_t by using
* cairo_set_font_face(); the size and font matrix are set with
* cairo_set_font_size() and cairo_set_font_matrix().
*/
typedef struct _cairo_font_face cairo_font_face_t;
/**
* cairo_glyph_t:
* @index: glyph index in the font. The exact interpretation of the
* glyph index depends on the font technology being used.
* @x: the offset in the X direction between the origin used for
* drawing or measuring the string and the origin of this glyph.
* @y: the offset in the Y direction between the origin used for
* drawing or measuring the string and the origin of this glyph.
*
* The #cairo_glyph_t structure holds information about a single glyph
* when drawing or measuring text. A font is (in simple terms) a
* collection of shapes used to draw text. A glyph is one of these
* shapes. There can be multiple glyphs for a single character
* (alternates to be used in different contexts, for example), or a
* glyph can be a <firstterm>ligature</firstterm> of multiple
* characters. Cairo doesn't expose any way of converting input text
* into glyphs, so in order to use the Cairo interfaces that take
* arrays of glyphs, you must directly access the appropriate
* underlying font system.
*
* Note that the offsets given by @x and @y are not cumulative. When
* drawing or measuring text, each glyph is individually positioned
* with respect to the overall origin
**/
typedef struct {
unsigned long index;
double x;
double y;
} cairo_glyph_t;
/**
* cairo_text_extents_t:
* @x_bearing: the horizontal distance from the origin to the
* leftmost part of the glyphs as drawn. Positive if the
* glyphs lie entirely to the right of the origin.
* @y_bearing: the vertical distance from the origin to the
* topmost part of the glyphs as drawn. Positive only if the
* glyphs lie completely below the origin; will usually be
* negative.
* @width: width of the glyphs as drawn
* @height: height of the glyphs as drawn
* @x_advance:distance to advance in the X direction
* after drawing these glyphs
* @y_advance: distance to advance in the Y direction
* after drawing these glyphs. Will typically be zero except
* for vertical text layout as found in East-Asian languages.
*
* The #cairo_text_extents_t structure stores the extents of a single
* glyph or a string of glyphs in user-space coordinates. Because text
* extents are in user-space coordinates, they are mostly, but not
* entirely, independent of the current transformation matrix. If you call
* <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will
* be drawn twice as big, but the reported text extents will not be
* doubled. They will change slightly due to hinting (so you can't
* assume that metrics are independent of the transformation matrix),
* but otherwise will remain unchanged.
*/
typedef struct {
double x_bearing;
double y_bearing;
double width;
double height;
double x_advance;
double y_advance;
} cairo_text_extents_t;
/**
* cairo_font_extents_t:
* @ascent: the distance that the font extends above the baseline.
* Note that this is not always exactly equal to the maximum
* of the extents of all the glyphs in the font, but rather
* is picked to express the font designer's intent as to
* how the font should align with elements above it.
* @descent: the distance that the font extends below the baseline.
* This value is positive for typical fonts that include
* portions below the baseline. Note that this is not always
* exactly equal to the maximum of the extents of all the
* glyphs in the font, but rather is picked to express the
* font designer's intent as to how the the font should
* align with elements below it.
* @height: the recommended vertical distance between baselines when
* setting consecutive lines of text with the font. This
* is greater than @ascent+@descent by a
* quantity known as the <firstterm>line spacing</firstterm>
* or <firstterm>external leading</firstterm>. When space
* is at a premium, most fonts can be set with only
* a distance of @ascent+@descent between lines.
* @max_x_advance: the maximum distance in the X direction that
* the the origin is advanced for any glyph in the font.
* @max_y_advance: the maximum distance in the Y direction that
* the the origin is advanced for any glyph in the font.
* this will be zero for normal fonts used for horizontal
* writing. (The scripts of East Asia are sometimes written
* vertically.)
*
* The #cairo_text_extents_t structure stores metric information for
* a font. Values are given in the current user-space coordinate
* system.
*
* Because font metrics are in user-space coordinates, they are
* mostly, but not entirely, independent of the current transformation
* matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>,
* text will be drawn twice as big, but the reported text extents will
* not be doubled. They will change slightly due to hinting (so you
* can't assume that metrics are independent of the transformation
* matrix), but otherwise will remain unchanged.
*/
typedef struct {
double ascent;
double descent;
double height;
double max_x_advance;
double max_y_advance;
} cairo_font_extents_t;
typedef enum _cairo_font_slant {
CAIRO_FONT_SLANT_NORMAL,
CAIRO_FONT_SLANT_ITALIC,
CAIRO_FONT_SLANT_OBLIQUE
} cairo_font_slant_t;
typedef enum _cairo_font_weight {
CAIRO_FONT_WEIGHT_NORMAL,
CAIRO_FONT_WEIGHT_BOLD
} cairo_font_weight_t;
/**
* cairo_subpixel_order_t:
* @CAIRO_SUBPIXEL_ORDER_DEFAULT: Use the default subpixel order for
* for the target device
* @CAIRO_SUBPIXEL_ORDER_RGB: Subpixel elements are arranged horizontally
* with red at the left
* @CAIRO_SUBPIXEL_ORDER_BGR: Subpixel elements are arranged horizontally
* with blue at the left
* @CAIRO_SUBPIXEL_ORDER_VRGB: Subpixel elements are arranged vertically
* with red at the top
* @CAIRO_SUBPIXEL_ORDER_VBGR: Subpixel elements are arranged vertically
* with blue at the top
*
* The subpixel order specifies the order of color elements within
* each pixel on the display device when rendering with an
* antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL.
**/
typedef enum _cairo_subpixel_order {
CAIRO_SUBPIXEL_ORDER_DEFAULT,
CAIRO_SUBPIXEL_ORDER_RGB,
CAIRO_SUBPIXEL_ORDER_BGR,
CAIRO_SUBPIXEL_ORDER_VRGB,
CAIRO_SUBPIXEL_ORDER_VBGR
} cairo_subpixel_order_t;
/**
* cairo_hint_style_t:
* @CAIRO_HINT_STYLE_DEFAULT: Use the default hint style for
* for font backend and target device
* @CAIRO_HINT_STYLE_NONE: Do not hint outlines
* @CAIRO_HINT_STYLE_SLIGHT: Hint outlines slightly to improve
* contrast while retaining good fidelity to the original
* shapes.
* @CAIRO_HINT_STYLE_MEDIUM: Hint outlines with medium strength
* giving a compromise between fidelity to the original shapes
* and contrast
* @CAIRO_HINT_STYLE_FULL: Hint outlines to maximize contrast
*
* Specifies the type of hinting to do on font outlines. Hinting
* is the process of fitting outlines to the pixel grid in order
* to improve the appearance of the result. Since hinting outlines
* involves distorting them, it also reduces the faithfulness
* to the original outline shapes. Not all of the outline hinting
* styles are supported by all font backends.
*/
typedef enum _cairo_hint_style {
CAIRO_HINT_STYLE_DEFAULT,
CAIRO_HINT_STYLE_NONE,
CAIRO_HINT_STYLE_SLIGHT,
CAIRO_HINT_STYLE_MEDIUM,
CAIRO_HINT_STYLE_FULL
} cairo_hint_style_t;
/**
* cairo_hint_metrics_t:
* @CAIRO_HINT_METRICS_DEFAULT: Hint metrics in the default
* manner for the font backend and target device
* @CAIRO_HINT_METRICS_OFF: Do not hint font metrics
* @CAIRO_HINT_METRICS_ON: Hint font metrics
*
* Specifies whether to hint font metrics; hinting font metrics
* means quantizing them so that they are integer values in
* device space. Doing this improves the consistency of
* letter and line spacing, however it also means that text
* will be laid out differently at different zoom factors.
*/
typedef enum _cairo_hint_metrics {
CAIRO_HINT_METRICS_DEFAULT,
CAIRO_HINT_METRICS_OFF,
CAIRO_HINT_METRICS_ON
} cairo_hint_metrics_t;
typedef struct _cairo_font_options cairo_font_options_t;
cairo_font_options_t *
cairo_font_options_create (void);
cairo_font_options_t *
cairo_font_options_copy (const cairo_font_options_t *original);
void
cairo_font_options_destroy (cairo_font_options_t *options);
cairo_status_t
cairo_font_options_status (cairo_font_options_t *options);
void
cairo_font_options_merge (cairo_font_options_t *options,
const cairo_font_options_t *other);
cairo_bool_t
cairo_font_options_equal (const cairo_font_options_t *options,
const cairo_font_options_t *other);
unsigned long
cairo_font_options_hash (const cairo_font_options_t *options);
void
cairo_font_options_set_antialias (cairo_font_options_t *options,
cairo_antialias_t antialias);
cairo_antialias_t
cairo_font_options_get_antialias (const cairo_font_options_t *options);
void
cairo_font_options_set_subpixel_order (cairo_font_options_t *options,
cairo_subpixel_order_t subpixel_order);
cairo_subpixel_order_t
cairo_font_options_get_subpixel_order (const cairo_font_options_t *options);
void
cairo_font_options_set_hint_style (cairo_font_options_t *options,
cairo_hint_style_t hint_style);
cairo_hint_style_t
cairo_font_options_get_hint_style (const cairo_font_options_t *options);
void
cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
cairo_hint_metrics_t hint_metrics);
cairo_hint_metrics_t
cairo_font_options_get_hint_metrics (const cairo_font_options_t *options);
/* This interface is for dealing with text as text, not caring about the
font object inside the the cairo_t. */
void
cairo_select_font_face (cairo_t *cr,
const char *family,
cairo_font_slant_t slant,
cairo_font_weight_t weight);
void
cairo_set_font_size (cairo_t *cr, double size);
void
cairo_set_font_matrix (cairo_t *cr,
const cairo_matrix_t *matrix);
void
cairo_get_font_matrix (cairo_t *cr,
cairo_matrix_t *matrix);
void
cairo_set_font_options (cairo_t *cr,
const cairo_font_options_t *options);
void
cairo_get_font_options (cairo_t *cr,
cairo_font_options_t *options);
void
cairo_show_text (cairo_t *cr, const char *utf8);
void
cairo_show_glyphs (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);
cairo_font_face_t *
cairo_get_font_face (cairo_t *cr);
void
cairo_font_extents (cairo_t *cr,
cairo_font_extents_t *extents);
void
cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face);
void
cairo_text_extents (cairo_t *cr,
const char *utf8,
cairo_text_extents_t *extents);
void
cairo_glyph_extents (cairo_t *cr,
cairo_glyph_t *glyphs,
int num_glyphs,
cairo_text_extents_t *extents);
void
cairo_text_path (cairo_t *cr, const char *utf8);
void
cairo_glyph_path (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);
/* Generic identifier for a font style */
cairo_font_face_t *
cairo_font_face_reference (cairo_font_face_t *font_face);
void
cairo_font_face_destroy (cairo_font_face_t *font_face);
cairo_status_t
cairo_font_face_status (cairo_font_face_t *font_face);
void *
cairo_font_face_get_user_data (cairo_font_face_t *font_face,
const cairo_user_data_key_t *key);
cairo_status_t
cairo_font_face_set_user_data (cairo_font_face_t *font_face,
const cairo_user_data_key_t *key,
void *user_data,
cairo_destroy_func_t destroy);
/* Portable interface to general font features. */
cairo_scaled_font_t *
cairo_scaled_font_create (cairo_font_face_t *font_face,
const cairo_matrix_t *font_matrix,
const cairo_matrix_t *ctm,
const cairo_font_options_t *options);
cairo_scaled_font_t *
cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
void
cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);
cairo_status_t
cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
void
cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font,
cairo_font_extents_t *extents);
void
cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font,
cairo_glyph_t *glyphs,
int num_glyphs,
cairo_text_extents_t *extents);
/* Query functions */
cairo_operator_t
cairo_get_operator (cairo_t *cr);
cairo_pattern_t *
cairo_get_source (cairo_t *cr);
double
cairo_get_tolerance (cairo_t *cr);
cairo_antialias_t
cairo_get_antialias (cairo_t *cr);
void
cairo_get_current_point (cairo_t *cr, double *x, double *y);
cairo_fill_rule_t
cairo_get_fill_rule (cairo_t *cr);
double
cairo_get_line_width (cairo_t *cr);
cairo_line_cap_t
cairo_get_line_cap (cairo_t *cr);
cairo_line_join_t
cairo_get_line_join (cairo_t *cr);
double
cairo_get_miter_limit (cairo_t *cr);
/* XXX: How to do cairo_get_dash??? Do we want to switch to a cairo_dash object? */
void
cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix);
cairo_surface_t *
cairo_get_target (cairo_t *cr);
typedef enum _cairo_path_data_type {
CAIRO_PATH_MOVE_TO,
CAIRO_PATH_LINE_TO,
CAIRO_PATH_CURVE_TO,
CAIRO_PATH_CLOSE_PATH
} cairo_path_data_type_t;
/**
* cairo_path_data_t:
*
* #cairo_path_data_t is used to represent the path data inside a
* #cairo_path_t.
*
* The data structure is designed to try to balance the demands of
* efficiency and ease-of-use. A path is represented as an array of
* #cairo_path_data_t, which is a union of headers and points.
*
* Each portion of the path is represented by one or more elements in
* the array, (one header followed by 0 or more points). The length
* value of the header is the number of array elements for the current
* portion including the header, (ie. length == 1 + # of points), and
* where the number of points for each element type must be as
* follows:
*
* <programlisting>