1 /* cairo - a vector graphics library with display and print output 2 * 3 * Copyright © 2002 University of Southern California 4 * Copyright © 2005 Red Hat, Inc. 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it either under the terms of the GNU Lesser General Public 8 * License version 2.1 as published by the Free Software Foundation 9 * (the "LGPL") or, at your option, under the terms of the Mozilla 10 * Public License Version 1.1 (the "MPL"). If you do not alter this 11 * notice, a recipient may use your version of this file under either 12 * the MPL or the LGPL. 13 * 14 * You should have received a copy of the LGPL along with this library 15 * in the file COPYING-LGPL-2.1; if not, write to the Free Software 16 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA 17 * You should have received a copy of the MPL along with this library 18 * in the file COPYING-MPL-1.1 19 * 20 * The contents of this file are subject to the Mozilla Public License 21 * Version 1.1 (the "License"); you may not use this file except in 22 * compliance with the License. You may obtain a copy of the License at 23 * http://www.mozilla.org/MPL/ 24 * 25 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY 26 * OF ANY KIND, either express or implied. See the LGPL or the MPL for 27 * the specific language governing rights and limitations. 28 * 29 * The Original Code is the cairo graphics library. 30 * 31 * The Initial Developer of the Original Code is University of Southern 32 * California. 33 * 34 * Contributor(s): 35 * Carl D. Worth <cworth@cworth.org> 36 */ 37 38 #ifndef CAIRO_H 39 #define CAIRO_H 40 41 #include "cairo-version.h" 42 #include "cairo-features.h" 43 #include "cairo-deprecated.h" 44 45 #ifdef __cplusplus 46 # define CAIRO_BEGIN_DECLS extern "C" { 47 # define CAIRO_END_DECLS } 48 #else 49 # define CAIRO_BEGIN_DECLS 50 # define CAIRO_END_DECLS 51 #endif 52 53 #ifndef cairo_public 54 # if defined (_MSC_VER) && ! defined (CAIRO_WIN32_STATIC_BUILD) 55 # define cairo_public __declspec(dllimport) 56 # else 57 # define cairo_public 58 # endif 59 #endif 60 61 CAIRO_BEGIN_DECLS 62 63 #define CAIRO_VERSION_ENCODE(major, minor, micro) ( \ 64 ((major) * 10000) \ 65 + ((minor) * 100) \ 66 + ((micro) * 1)) 67 68 #define CAIRO_VERSION CAIRO_VERSION_ENCODE( \ 69 CAIRO_VERSION_MAJOR, \ 70 CAIRO_VERSION_MINOR, \ 71 CAIRO_VERSION_MICRO) 72 73 74 #define CAIRO_VERSION_STRINGIZE_(major, minor, micro) \ 75 #major"."#minor"."#micro 76 #define CAIRO_VERSION_STRINGIZE(major, minor, micro) \ 77 CAIRO_VERSION_STRINGIZE_(major, minor, micro) 78 79 #define CAIRO_VERSION_STRING CAIRO_VERSION_STRINGIZE( \ 80 CAIRO_VERSION_MAJOR, \ 81 CAIRO_VERSION_MINOR, \ 82 CAIRO_VERSION_MICRO) 83 84 85 cairo_public int 86 cairo_version (void); 87 88 cairo_public const char* 89 cairo_version_string (void); 90 91 /** 92 * cairo_bool_t: 93 * 94 * #cairo_bool_t is used for boolean values. Returns of type 95 * #cairo_bool_t will always be either 0 or 1, but testing against 96 * these values explicitly is not encouraged; just use the 97 * value as a boolean condition. 98 * 99 * <informalexample><programlisting> 100 * if (cairo_in_stroke (cr, x, y)) { 101 * /<!-- -->* do something *<!-- -->/ 102 * } 103 * </programlisting></informalexample> 104 **/ 105 typedef int cairo_bool_t; 106 107 /** 108 * cairo_t: 109 * 110 * A #cairo_t contains the current state of the rendering device, 111 * including coordinates of yet to be drawn shapes. 112 * 113 * Cairo contexts, as #cairo_t objects are named, are central to 114 * cairo and all drawing with cairo is always done to a #cairo_t 115 * object. 116 * 117 * Memory management of #cairo_t is done with 118 * cairo_reference() and cairo_destroy(). 119 **/ 120 typedef struct _cairo cairo_t; 121 122 /** 123 * cairo_surface_t: 124 * 125 * A #cairo_surface_t represents an image, either as the destination 126 * of a drawing operation or as source when drawing onto another 127 * surface. To draw to a #cairo_surface_t, create a cairo context 128 * with the surface as the target, using cairo_create(). 129 * 130 * There are different subtypes of #cairo_surface_t for 131 * different drawing backends; for example, cairo_image_surface_create() 132 * creates a bitmap image in memory. 133 * The type of a surface can be queried with cairo_surface_get_type(). 134 * 135 * The initial contents of a surface after creation depend upon the manner 136 * of its creation. If cairo creates the surface and backing storage for 137 * the user, it will be initially cleared; for example, 138 * cairo_image_surface_create() and cairo_surface_create_similar(). 139 * Alternatively, if the user passes in a reference to some backing storage 140 * and asks cairo to wrap that in a #cairo_surface_t, then the contents are 141 * not modified; for example, cairo_image_surface_create_for_data() and 142 * cairo_xlib_surface_create(). 143 * 144 * Memory management of #cairo_surface_t is done with 145 * cairo_surface_reference() and cairo_surface_destroy(). 146 **/ 147 typedef struct _cairo_surface cairo_surface_t; 148 149 /** 150 * cairo_device_t: 151 * 152 * A #cairo_device_t represents the driver interface for drawing 153 * operations to a #cairo_surface_t. There are different subtypes of 154 * #cairo_device_t for different drawing backends; for example, 155 * cairo_xcb_device_create() creates a device that wraps the connection 156 * to an X Windows System using the XCB library. 157 * 158 * The type of a device can be queried with cairo_device_get_type(). 159 * 160 * Memory management of #cairo_device_t is done with 161 * cairo_device_reference() and cairo_device_destroy(). 162 * 163 * Since: 1.10 164 **/ 165 typedef struct _cairo_device cairo_device_t; 166 167 /** 168 * cairo_matrix_t: 169 * @xx: xx component of the affine transformation 170 * @yx: yx component of the affine transformation 171 * @xy: xy component of the affine transformation 172 * @yy: yy component of the affine transformation 173 * @x0: X translation component of the affine transformation 174 * @y0: Y translation component of the affine transformation 175 * 176 * A #cairo_matrix_t holds an affine transformation, such as a scale, 177 * rotation, shear, or a combination of those. The transformation of 178 * a point (x, y) is given by: 179 * <programlisting> 180 * x_new = xx * x + xy * y + x0; 181 * y_new = yx * x + yy * y + y0; 182 * </programlisting> 183 **/ 184 typedef struct _cairo_matrix { 185 double xx; double yx; 186 double xy; double yy; 187 double x0; double y0; 188 } cairo_matrix_t; 189 190 /** 191 * cairo_pattern_t: 192 * 193 * A #cairo_pattern_t represents a source when drawing onto a 194 * surface. There are different subtypes of #cairo_pattern_t, 195 * for different types of sources; for example, 196 * cairo_pattern_create_rgb() creates a pattern for a solid 197 * opaque color. 198 * 199 * Other than various cairo_pattern_create_<emphasis>type</emphasis>() 200 * functions, some of the pattern types can be implicitly created 201 * using various cairo_set_source_<emphasis>type</emphasis>() functions; 202 * for example cairo_set_source_rgb(). 203 * 204 * The type of a pattern can be queried with cairo_pattern_get_type(). 205 * 206 * Memory management of #cairo_pattern_t is done with 207 * cairo_pattern_reference() and cairo_pattern_destroy(). 208 **/ 209 typedef struct _cairo_pattern cairo_pattern_t; 210 211 /** 212 * cairo_destroy_func_t: 213 * @data: The data element being destroyed. 214 * 215 * #cairo_destroy_func_t the type of function which is called when a 216 * data element is destroyed. It is passed the pointer to the data 217 * element and should free any memory and resources allocated for it. 218 **/ 219 typedef void (*cairo_destroy_func_t) (void *data); 220 221 /** 222 * cairo_user_data_key_t: 223 * @unused: not used; ignore. 224 * 225 * #cairo_user_data_key_t is used for attaching user data to cairo 226 * data structures. The actual contents of the struct is never used, 227 * and there is no need to initialize the object; only the unique 228 * address of a #cairo_data_key_t object is used. Typically, you 229 * would just use the address of a static #cairo_data_key_t object. 230 **/ 231 typedef struct _cairo_user_data_key { 232 int unused; 233 } cairo_user_data_key_t; 234 235 /** 236 * cairo_status_t: 237 * @CAIRO_STATUS_SUCCESS: no error has occurred 238 * @CAIRO_STATUS_NO_MEMORY: out of memory 239 * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore() called without matching cairo_save() 240 * @CAIRO_STATUS_INVALID_POP_GROUP: no saved group to pop, i.e. cairo_pop_group() without matching cairo_push_group() 241 * @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined 242 * @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible) 243 * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input #cairo_status_t 244 * @CAIRO_STATUS_NULL_POINTER: %NULL pointer 245 * @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8 246 * @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid 247 * @CAIRO_STATUS_READ_ERROR: error while reading from input stream 248 * @CAIRO_STATUS_WRITE_ERROR: error while writing to output stream 249 * @CAIRO_STATUS_SURFACE_FINISHED: target surface has been finished 250 * @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: the surface type is not appropriate for the operation 251 * @CAIRO_STATUS_PATTERN_TYPE_MISMATCH: the pattern type is not appropriate for the operation 252 * @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input #cairo_content_t 253 * @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input #cairo_format_t 254 * @CAIRO_STATUS_INVALID_VISUAL: invalid value for an input Visual* 255 * @CAIRO_STATUS_FILE_NOT_FOUND: file not found 256 * @CAIRO_STATUS_INVALID_DASH: invalid value for a dash setting 257 * @CAIRO_STATUS_INVALID_DSC_COMMENT: invalid value for a DSC comment (Since 1.2) 258 * @CAIRO_STATUS_INVALID_INDEX: invalid index passed to getter (Since 1.4) 259 * @CAIRO_STATUS_CLIP_NOT_REPRESENTABLE: clip region not representable in desired format (Since 1.4) 260 * @CAIRO_STATUS_TEMP_FILE_ERROR: error creating or writing to a temporary file (Since 1.6) 261 * @CAIRO_STATUS_INVALID_STRIDE: invalid value for stride (Since 1.6) 262 * @CAIRO_STATUS_FONT_TYPE_MISMATCH: the font type is not appropriate for the operation (Since 1.8) 263 * @CAIRO_STATUS_USER_FONT_IMMUTABLE: the user-font is immutable (Since 1.8) 264 * @CAIRO_STATUS_USER_FONT_ERROR: error occurred in a user-font callback function (Since 1.8) 265 * @CAIRO_STATUS_NEGATIVE_COUNT: negative number used where it is not allowed (Since 1.8) 266 * @CAIRO_STATUS_INVALID_CLUSTERS: input clusters do not represent the accompanying text and glyph array (Since 1.8) 267 * @CAIRO_STATUS_INVALID_SLANT: invalid value for an input #cairo_font_slant_t (Since 1.8) 268 * @CAIRO_STATUS_INVALID_WEIGHT: invalid value for an input #cairo_font_weight_t (Since 1.8) 269 * @CAIRO_STATUS_INVALID_SIZE: invalid value (typically too big) for the size of the input (surface, pattern, etc.) (Since 1.10) 270 * @CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED: user-font method not implemented (Since 1.10) 271 * @CAIRO_STATUS_DEVICE_TYPE_MISMATCH: the device type is not appropriate for the operation (Since 1.10) 272 * @CAIRO_STATUS_DEVICE_ERROR: an operation to the device caused an unspecified error (Since 1.10) 273 * @CAIRO_STATUS_LAST_STATUS: this is a special value indicating the number of 274 * status values defined in this enumeration. When using this value, note 275 * that the version of cairo at run-time may have additional status values 276 * defined than the value of this symbol at compile-time. (Since 1.10) 277 * 278 * #cairo_status_t is used to indicate errors that can occur when 279 * using Cairo. In some cases it is returned directly by functions. 280 * but when using #cairo_t, the last error, if any, is stored in 281 * the context and can be retrieved with cairo_status(). 282 * 283 * New entries may be added in future versions. Use cairo_status_to_string() 284 * to get a human-readable representation of an error message. 285 **/ 286 typedef enum _cairo_status { 287 CAIRO_STATUS_SUCCESS = 0, 288 289 CAIRO_STATUS_NO_MEMORY, 290 CAIRO_STATUS_INVALID_RESTORE, 291 CAIRO_STATUS_INVALID_POP_GROUP, 292 CAIRO_STATUS_NO_CURRENT_POINT, 293 CAIRO_STATUS_INVALID_MATRIX, 294 CAIRO_STATUS_INVALID_STATUS, 295 CAIRO_STATUS_NULL_POINTER, 296 CAIRO_STATUS_INVALID_STRING, 297 CAIRO_STATUS_INVALID_PATH_DATA, 298 CAIRO_STATUS_READ_ERROR, 299 CAIRO_STATUS_WRITE_ERROR, 300 CAIRO_STATUS_SURFACE_FINISHED, 301 CAIRO_STATUS_SURFACE_TYPE_MISMATCH, 302 CAIRO_STATUS_PATTERN_TYPE_MISMATCH, 303 CAIRO_STATUS_INVALID_CONTENT, 304 CAIRO_STATUS_INVALID_FORMAT, 305 CAIRO_STATUS_INVALID_VISUAL, 306 CAIRO_STATUS_FILE_NOT_FOUND, 307 CAIRO_STATUS_INVALID_DASH, 308 CAIRO_STATUS_INVALID_DSC_COMMENT, 309 CAIRO_STATUS_INVALID_INDEX, 310 CAIRO_STATUS_CLIP_NOT_REPRESENTABLE, 311 CAIRO_STATUS_TEMP_FILE_ERROR, 312 CAIRO_STATUS_INVALID_STRIDE, 313 CAIRO_STATUS_FONT_TYPE_MISMATCH, 314 CAIRO_STATUS_USER_FONT_IMMUTABLE, 315 CAIRO_STATUS_USER_FONT_ERROR, 316 CAIRO_STATUS_NEGATIVE_COUNT, 317 CAIRO_STATUS_INVALID_CLUSTERS, 318 CAIRO_STATUS_INVALID_SLANT, 319 CAIRO_STATUS_INVALID_WEIGHT, 320 CAIRO_STATUS_INVALID_SIZE, 321 CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, 322 CAIRO_STATUS_DEVICE_TYPE_MISMATCH, 323 CAIRO_STATUS_DEVICE_ERROR, 324 325 CAIRO_STATUS_LAST_STATUS 326 } cairo_status_t; 327 328 /** 329 * cairo_content_t: 330 * @CAIRO_CONTENT_COLOR: The surface will hold color content only. 331 * @CAIRO_CONTENT_ALPHA: The surface will hold alpha content only. 332 * @CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content. 333 * 334 * #cairo_content_t is used to describe the content that a surface will 335 * contain, whether color information, alpha information (translucence 336 * vs. opacity), or both. 337 * 338 * Note: The large values here are designed to keep #cairo_content_t 339 * values distinct from #cairo_format_t values so that the 340 * implementation can detect the error if users confuse the two types. 341 **/ 342 typedef enum _cairo_content { 343 CAIRO_CONTENT_COLOR = 0x1000, 344 CAIRO_CONTENT_ALPHA = 0x2000, 345 CAIRO_CONTENT_COLOR_ALPHA = 0x3000 346 } cairo_content_t; 347 348 /** 349 * cairo_write_func_t: 350 * @closure: the output closure 351 * @data: the buffer containing the data to write 352 * @length: the amount of data to write 353 * 354 * #cairo_write_func_t is the type of function which is called when a 355 * backend needs to write data to an output stream. It is passed the 356 * closure which was specified by the user at the time the write 357 * function was registered, the data to write and the length of the 358 * data in bytes. The write function should return 359 * %CAIRO_STATUS_SUCCESS if all the data was successfully written, 360 * %CAIRO_STATUS_WRITE_ERROR otherwise. 361 * 362 * Returns: the status code of the write operation 363 **/ 364 typedef cairo_status_t (*cairo_write_func_t) (void *closure, 365 const unsigned char *data, 366 unsigned int length); 367 368 /** 369 * cairo_read_func_t: 370 * @closure: the input closure 371 * @data: the buffer into which to read the data 372 * @length: the amount of data to read 373 * 374 * #cairo_read_func_t is the type of function which is called when a 375 * backend needs to read data from an input stream. It is passed the 376 * closure which was specified by the user at the time the read 377 * function was registered, the buffer to read the data into and the 378 * length of the data in bytes. The read function should return 379 * %CAIRO_STATUS_SUCCESS if all the data was successfully read, 380 * %CAIRO_STATUS_READ_ERROR otherwise. 381 * 382 * Returns: the status code of the read operation 383 **/ 384 typedef cairo_status_t (*cairo_read_func_t) (void *closure, 385 unsigned char *data, 386 unsigned int length); 387 388 /* Functions for manipulating state objects */ 389 cairo_public cairo_t * 390 cairo_create (cairo_surface_t *target); 391 392 cairo_public cairo_t * 393 cairo_reference (cairo_t *cr); 394 395 cairo_public void 396 cairo_destroy (cairo_t *cr); 397 398 cairo_public unsigned int 399 cairo_get_reference_count (cairo_t *cr); 400 401 cairo_public void * 402 cairo_get_user_data (cairo_t *cr, 403 const cairo_user_data_key_t *key); 404 405 cairo_public cairo_status_t 406 cairo_set_user_data (cairo_t *cr, 407 const cairo_user_data_key_t *key, 408 void *user_data, 409 cairo_destroy_func_t destroy); 410 411 cairo_public void 412 cairo_save (cairo_t *cr); 413 414 cairo_public void 415 cairo_restore (cairo_t *cr); 416 417 cairo_public void 418 cairo_push_group (cairo_t *cr); 419 420 cairo_public void 421 cairo_push_group_with_content (cairo_t *cr, cairo_content_t content); 422 423 cairo_public cairo_pattern_t * 424 cairo_pop_group (cairo_t *cr); 425 426 cairo_public void 427 cairo_pop_group_to_source (cairo_t *cr); 428 429 /* Modify state */ 430 431 /** 432 * cairo_operator_t: 433 * @CAIRO_OPERATOR_CLEAR: clear destination layer (bounded) 434 * @CAIRO_OPERATOR_SOURCE: replace destination layer (bounded) 435 * @CAIRO_OPERATOR_OVER: draw source layer on top of destination layer 436 * (bounded) 437 * @CAIRO_OPERATOR_IN: draw source where there was destination content 438 * (unbounded) 439 * @CAIRO_OPERATOR_OUT: draw source where there was no destination 440 * content (unbounded) 441 * @CAIRO_OPERATOR_ATOP: draw source on top of destination content and 442 * only there 443 * @CAIRO_OPERATOR_DEST: ignore the source 444 * @CAIRO_OPERATOR_DEST_OVER: draw destination on top of source 445 * @CAIRO_OPERATOR_DEST_IN: leave destination only where there was 446 * source content (unbounded) 447 * @CAIRO_OPERATOR_DEST_OUT: leave destination only where there was no 448 * source content 449 * @CAIRO_OPERATOR_DEST_ATOP: leave destination on top of source content 450 * and only there (unbounded) 451 * @CAIRO_OPERATOR_XOR: source and destination are shown where there is only 452 * one of them 453 * @CAIRO_OPERATOR_ADD: source and destination layers are accumulated 454 * @CAIRO_OPERATOR_SATURATE: like over, but assuming source and dest are 455 * disjoint geometries 456 * @CAIRO_OPERATOR_MULTIPLY: source and destination layers are multiplied. 457 * This causes the result to be at least as dark as the darker inputs. 458 * @CAIRO_OPERATOR_SCREEN: source and destination are complemented and 459 * multiplied. This causes the result to be at least as light as the lighter 460 * inputs. 461 * @CAIRO_OPERATOR_OVERLAY: multiplies or screens, depending on the 462 * lightness of the destination color. 463 * @CAIRO_OPERATOR_DARKEN: replaces the destination with the source if it 464 * is darker, otherwise keeps the source. 465 * @CAIRO_OPERATOR_LIGHTEN: replaces the destination with the source if it 466 * is lighter, otherwise keeps the source. 467 * @CAIRO_OPERATOR_COLOR_DODGE: brightens the destination color to reflect 468 * the source color. 469 * @CAIRO_OPERATOR_COLOR_BURN: darkens the destination color to reflect 470 * the source color. 471 * @CAIRO_OPERATOR_HARD_LIGHT: Multiplies or screens, dependant on source 472 * color. 473 * @CAIRO_OPERATOR_SOFT_LIGHT: Darkens or lightens, dependant on source 474 * color. 475 * @CAIRO_OPERATOR_DIFFERENCE: Takes the difference of the source and 476 * destination color. 477 * @CAIRO_OPERATOR_EXCLUSION: Produces an effect similar to difference, but 478 * with lower contrast. 479 * @CAIRO_OPERATOR_HSL_HUE: Creates a color with the hue of the source 480 * and the saturation and luminosity of the target. 481 * @CAIRO_OPERATOR_HSL_SATURATION: Creates a color with the saturation 482 * of the source and the hue and luminosity of the target. Painting with 483 * this mode onto a gray area prduces no change. 484 * @CAIRO_OPERATOR_HSL_COLOR: Creates a color with the hue and saturation 485 * of the source and the luminosity of the target. This preserves the gray 486 * levels of the target and is useful for coloring monochrome images or 487 * tinting color images. 488 * @CAIRO_OPERATOR_HSL_LUMINOSITY: Creates a color with the luminosity of 489 * the source and the hue and saturation of the target. This produces an 490 * inverse effect to @CAIRO_OPERATOR_HSL_COLOR. 491 * 492 * #cairo_operator_t is used to set the compositing operator for all cairo 493 * drawing operations. 494 * 495 * The default operator is %CAIRO_OPERATOR_OVER. 496 * 497 * The operators marked as <firstterm>unbounded</firstterm> modify their 498 * destination even outside of the mask layer (that is, their effect is not 499 * bound by the mask layer). However, their effect can still be limited by 500 * way of clipping. 501 * 502 * To keep things simple, the operator descriptions here 503 * document the behavior for when both source and destination are either fully 504 * transparent or fully opaque. The actual implementation works for 505 * translucent layers too. 506 * For a more detailed explanation of the effects of each operator, including 507 * the mathematical definitions, see 508 * <ulink url="http://cairographics.org/operators/">http://cairographics.org/operators/</ulink>. 509 **/ 510 typedef enum _cairo_operator { 511 CAIRO_OPERATOR_CLEAR, 512 513 CAIRO_OPERATOR_SOURCE, 514 CAIRO_OPERATOR_OVER, 515 CAIRO_OPERATOR_IN, 516 CAIRO_OPERATOR_OUT, 517 CAIRO_OPERATOR_ATOP, 518 519 CAIRO_OPERATOR_DEST, 520 CAIRO_OPERATOR_DEST_OVER, 521 CAIRO_OPERATOR_DEST_IN, 522 CAIRO_OPERATOR_DEST_OUT, 523 CAIRO_OPERATOR_DEST_ATOP, 524 525 CAIRO_OPERATOR_XOR, 526 CAIRO_OPERATOR_ADD, 527 CAIRO_OPERATOR_SATURATE, 528 529 CAIRO_OPERATOR_MULTIPLY, 530 CAIRO_OPERATOR_SCREEN, 531 CAIRO_OPERATOR_OVERLAY, 532 CAIRO_OPERATOR_DARKEN, 533 CAIRO_OPERATOR_LIGHTEN, 534 CAIRO_OPERATOR_COLOR_DODGE, 535 CAIRO_OPERATOR_COLOR_BURN, 536 CAIRO_OPERATOR_HARD_LIGHT, 537 CAIRO_OPERATOR_SOFT_LIGHT, 538 CAIRO_OPERATOR_DIFFERENCE, 539 CAIRO_OPERATOR_EXCLUSION, 540 CAIRO_OPERATOR_HSL_HUE, 541 CAIRO_OPERATOR_HSL_SATURATION, 542 CAIRO_OPERATOR_HSL_COLOR, 543 CAIRO_OPERATOR_HSL_LUMINOSITY 544 } cairo_operator_t; 545 546 cairo_public void 547 cairo_set_operator (cairo_t *cr, cairo_operator_t op); 548 549 cairo_public void 550 cairo_set_source (cairo_t *cr, cairo_pattern_t *source); 551 552 cairo_public void 553 cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue); 554 555 cairo_public void 556 cairo_set_source_rgba (cairo_t *cr, 557 double red, double green, double blue, 558 double alpha); 559 560 cairo_public void 561 cairo_set_source_surface (cairo_t *cr, 562 cairo_surface_t *surface, 563 double x, 564 double y); 565 566 cairo_public void 567 cairo_set_tolerance (cairo_t *cr, double tolerance); 568 569 /** 570 * cairo_antialias_t: 571 * @CAIRO_ANTIALIAS_DEFAULT: Use the default antialiasing for 572 * the subsystem and target device 573 * @CAIRO_ANTIALIAS_NONE: Use a bilevel alpha mask 574 * @CAIRO_ANTIALIAS_GRAY: Perform single-color antialiasing (using 575 * shades of gray for black text on a white background, for example). 576 * @CAIRO_ANTIALIAS_SUBPIXEL: Perform antialiasing by taking 577 * advantage of the order of subpixel elements on devices 578 * such as LCD panels 579 * 580 * Specifies the type of antialiasing to do when rendering text or shapes. 581 **/ 582 typedef enum _cairo_antialias { 583 CAIRO_ANTIALIAS_DEFAULT, 584 CAIRO_ANTIALIAS_NONE, 585 CAIRO_ANTIALIAS_GRAY, 586 CAIRO_ANTIALIAS_SUBPIXEL 587 } cairo_antialias_t; 588 589 cairo_public void 590 cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias); 591 592 /** 593 * cairo_fill_rule_t: 594 * @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from 595 * left-to-right, counts +1. If the path crosses the ray 596 * from right to left, counts -1. (Left and right are determined 597 * from the perspective of looking along the ray from the starting 598 * point.) If the total count is non-zero, the point will be filled. 599 * @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of 600 * intersections, without regard to the orientation of the contour. If 601 * the total number of intersections is odd, the point will be 602 * filled. 603 * 604 * #cairo_fill_rule_t is used to select how paths are filled. For both 605 * fill rules, whether or not a point is included in the fill is 606 * determined by taking a ray from that point to infinity and looking 607 * at intersections with the path. The ray can be in any direction, 608 * as long as it doesn't pass through the end point of a segment 609 * or have a tricky intersection such as intersecting tangent to the path. 610 * (Note that filling is not actually implemented in this way. This 611 * is just a description of the rule that is applied.) 612 * 613 * The default fill rule is %CAIRO_FILL_RULE_WINDING. 614 * 615 * New entries may be added in future versions. 616 **/ 617 typedef enum _cairo_fill_rule { 618 CAIRO_FILL_RULE_WINDING, 619 CAIRO_FILL_RULE_EVEN_ODD 620 } cairo_fill_rule_t; 621 622 cairo_public void 623 cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule); 624 625 cairo_public void 626 cairo_set_line_width (cairo_t *cr, double width); 627 628 /** 629 * cairo_line_cap_t: 630 * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point 631 * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point 632 * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point 633 * 634 * Specifies how to render the endpoints of the path when stroking. 635 * 636 * The default line cap style is %CAIRO_LINE_CAP_BUTT. 637 **/ 638 typedef enum _cairo_line_cap { 639 CAIRO_LINE_CAP_BUTT, 640 CAIRO_LINE_CAP_ROUND, 641 CAIRO_LINE_CAP_SQUARE 642 } cairo_line_cap_t; 643 644 cairo_public void 645 cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap); 646 647 /** 648 * cairo_line_join_t: 649 * @CAIRO_LINE_JOIN_MITER: use a sharp (angled) corner, see 650 * cairo_set_miter_limit() 651 * @CAIRO_LINE_JOIN_ROUND: use a rounded join, the center of the circle is the 652 * joint point 653 * @CAIRO_LINE_JOIN_BEVEL: use a cut-off join, the join is cut off at half 654 * the line width from the joint point 655 * 656 * Specifies how to render the junction of two lines when stroking. 657 * 658 * The default line join style is %CAIRO_LINE_JOIN_MITER. 659 **/ 660 typedef enum _cairo_line_join { 661 CAIRO_LINE_JOIN_MITER, 662 CAIRO_LINE_JOIN_ROUND, 663 CAIRO_LINE_JOIN_BEVEL 664 } cairo_line_join_t; 665 666 cairo_public void 667 cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join); 668 669 cairo_public void 670 cairo_set_dash (cairo_t *cr, 671 const double *dashes, 672 int num_dashes, 673 double offset); 674 675 cairo_public void 676 cairo_set_miter_limit (cairo_t *cr, double limit); 677 678 cairo_public void 679 cairo_translate (cairo_t *cr, double tx, double ty); 680 681 cairo_public void 682 cairo_scale (cairo_t *cr, double sx, double sy); 683 684 cairo_public void 685 cairo_rotate (cairo_t *cr, double angle); 686 687 cairo_public void 688 cairo_transform (cairo_t *cr, 689 const cairo_matrix_t *matrix); 690 691 cairo_public void 692 cairo_set_matrix (cairo_t *cr, 693 const cairo_matrix_t *matrix); 694 695 cairo_public void 696 cairo_identity_matrix (cairo_t *cr); 697 698 cairo_public void 699 cairo_user_to_device (cairo_t *cr, double *x, double *y); 700 701 cairo_public void 702 cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy); 703 704 cairo_public void 705 cairo_device_to_user (cairo_t *cr, double *x, double *y); 706 707 cairo_public void 708 cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy); 709 710 /* Path creation functions */ 711 cairo_public void 712 cairo_new_path (cairo_t *cr); 713 714 cairo_public void 715 cairo_move_to (cairo_t *cr, double x, double y); 716 717 cairo_public void 718 cairo_new_sub_path (cairo_t *cr); 719 720 cairo_public void 721 cairo_line_to (cairo_t *cr, double x, double y); 722 723 cairo_public void 724 cairo_curve_to (cairo_t *cr, 725 double x1, double y1, 726 double x2, double y2, 727 double x3, double y3); 728 729 cairo_public void 730 cairo_arc (cairo_t *cr, 731 double xc, double yc, 732 double radius, 733 double angle1, double angle2); 734 735 cairo_public void 736 cairo_arc_negative (cairo_t *cr, 737 double xc, double yc, 738 double radius, 739 double angle1, double angle2); 740 741 /* XXX: NYI 742 cairo_public void 743 cairo_arc_to (cairo_t *cr, 744 double x1, double y1, 745 double x2, double y2, 746 double radius); 747 */ 748 749 cairo_public void 750 cairo_rel_move_to (cairo_t *cr, double dx, double dy); 751 752 cairo_public void 753 cairo_rel_line_to (cairo_t *cr, double dx, double dy); 754 755 cairo_public void 756 cairo_rel_curve_to (cairo_t *cr, 757 double dx1, double dy1, 758 double dx2, double dy2, 759 double dx3, double dy3); 760 761 cairo_public void 762 cairo_rectangle (cairo_t *cr, 763 double x, double y, 764 double width, double height); 765 766 /* XXX: NYI 767 cairo_public void 768 cairo_stroke_to_path (cairo_t *cr); 769 */ 770 771 cairo_public void 772 cairo_close_path (cairo_t *cr); 773 774 cairo_public void 775 cairo_path_extents (cairo_t *cr, 776 double *x1, double *y1, 777 double *x2, double *y2); 778 779 /* Painting functions */ 780 cairo_public void 781 cairo_paint (cairo_t *cr); 782 783 cairo_public void 784 cairo_paint_with_alpha (cairo_t *cr, 785 double alpha); 786 787 cairo_public void 788 cairo_mask (cairo_t *cr, 789 cairo_pattern_t *pattern); 790 791 cairo_public void 792 cairo_mask_surface (cairo_t *cr, 793 cairo_surface_t *surface, 794 double surface_x, 795 double surface_y); 796 797 cairo_public void 798 cairo_stroke (cairo_t *cr); 799 800 cairo_public void 801 cairo_stroke_preserve (cairo_t *cr); 802 803 cairo_public void 804 cairo_fill (cairo_t *cr); 805 806 cairo_public void 807 cairo_fill_preserve (cairo_t *cr); 808 809 cairo_public void 810 cairo_copy_page (cairo_t *cr); 811 812 cairo_public void 813 cairo_show_page (cairo_t *cr); 814 815 /* Insideness testing */ 816 cairo_public cairo_bool_t 817 cairo_in_stroke (cairo_t *cr, double x, double y); 818 819 cairo_public cairo_bool_t 820 cairo_in_fill (cairo_t *cr, double x, double y); 821 822 cairo_public cairo_bool_t 823 cairo_in_clip (cairo_t *cr, double x, double y); 824 825 /* Rectangular extents */ 826 cairo_public void 827 cairo_stroke_extents (cairo_t *cr, 828 double *x1, double *y1, 829 double *x2, double *y2); 830 831 cairo_public void 832 cairo_fill_extents (cairo_t *cr, 833 double *x1, double *y1, 834 double *x2, double *y2); 835 836 /* Clipping */ 837 cairo_public void 838 cairo_reset_clip (cairo_t *cr); 839 840 cairo_public void 841 cairo_clip (cairo_t *cr); 842 843 cairo_public void 844 cairo_clip_preserve (cairo_t *cr); 845 846 cairo_public void 847 cairo_clip_extents (cairo_t *cr, 848 double *x1, double *y1, 849 double *x2, double *y2); 850 851 /** 852 * cairo_rectangle_t: 853 * @x: X coordinate of the left side of the rectangle 854 * @y: Y coordinate of the the top side of the rectangle 855 * @width: width of the rectangle 856 * @height: height of the rectangle 857 * 858 * A data structure for holding a rectangle. 859 * 860 * Since: 1.4 861 **/ 862 typedef struct _cairo_rectangle { 863 double x, y, width, height; 864 } cairo_rectangle_t; 865 866 /** 867 * cairo_rectangle_list_t: 868 * @status: Error status of the rectangle list 869 * @rectangles: Array containing the rectangles 870 * @num_rectangles: Number of rectangles in this list 871 * 872 * A data structure for holding a dynamically allocated 873 * array of rectangles. 874 * 875 * Since: 1.4 876 **/ 877 typedef struct _cairo_rectangle_list { 878 cairo_status_t status; 879 cairo_rectangle_t *rectangles; 880 int num_rectangles; 881 } cairo_rectangle_list_t; 882 883 cairo_public cairo_rectangle_list_t * 884 cairo_copy_clip_rectangle_list (cairo_t *cr); 885 886 cairo_public void 887 cairo_rectangle_list_destroy (cairo_rectangle_list_t *rectangle_list); 888 889 /* Font/Text functions */ 890 891 /** 892 * cairo_scaled_font_t: 893 * 894 * A #cairo_scaled_font_t is a font scaled to a particular size and device 895 * resolution. A #cairo_scaled_font_t is most useful for low-level font 896 * usage where a library or application wants to cache a reference 897 * to a scaled font to speed up the computation of metrics. 898 * 899 * There are various types of scaled fonts, depending on the 900 * <firstterm>font backend</firstterm> they use. The type of a 901 * scaled font can be queried using cairo_scaled_font_get_type(). 902 * 903 * Memory management of #cairo_scaled_font_t is done with 904 * cairo_scaled_font_reference() and cairo_scaled_font_destroy(). 905 **/ 906 typedef struct _cairo_scaled_font cairo_scaled_font_t; 907 908 /** 909 * cairo_font_face_t: 910 * 911 * A #cairo_font_face_t specifies all aspects of a font other 912 * than the size or font matrix (a font matrix is used to distort 913 * a font by sheering it or scaling it unequally in the two 914 * directions) . A font face can be set on a #cairo_t by using 915 * cairo_set_font_face(); the size and font matrix are set with 916 * cairo_set_font_size() and cairo_set_font_matrix(). 917 * 918 * There are various types of font faces, depending on the 919 * <firstterm>font backend</firstterm> they use. The type of a 920 * font face can be queried using cairo_font_face_get_type(). 921 * 922 * Memory management of #cairo_font_face_t is done with 923 * cairo_font_face_reference() and cairo_font_face_destroy(). 924 **/ 925 typedef struct _cairo_font_face cairo_font_face_t; 926 927 /** 928 * cairo_glyph_t: 929 * @index: glyph index in the font. The exact interpretation of the 930 * glyph index depends on the font technology being used. 931 * @x: the offset in the X direction between the origin used for 932 * drawing or measuring the string and the origin of this glyph. 933 * @y: the offset in the Y direction between the origin used for 934 * drawing or measuring the string and the origin of this glyph. 935 * 936 * The #cairo_glyph_t structure holds information about a single glyph 937 * when drawing or measuring text. A font is (in simple terms) a 938 * collection of shapes used to draw text. A glyph is one of these 939 * shapes. There can be multiple glyphs for a single character 940 * (alternates to be used in different contexts, for example), or a 941 * glyph can be a <firstterm>ligature</firstterm> of multiple 942 * characters. Cairo doesn't expose any way of converting input text 943 * into glyphs, so in order to use the Cairo interfaces that take 944 * arrays of glyphs, you must directly access the appropriate 945 * underlying font system. 946 * 947 * Note that the offsets given by @x and @y are not cumulative. When 948 * drawing or measuring text, each glyph is individually positioned 949 * with respect to the overall origin 950 **/ 951 typedef struct { 952 unsigned long index; 953 double x; 954 double y; 955 } cairo_glyph_t; 956 957 cairo_public cairo_glyph_t * 958 cairo_glyph_allocate (int num_glyphs); 959 960 cairo_public void 961 cairo_glyph_free (cairo_glyph_t *glyphs); 962 963 /** 964 * cairo_text_cluster_t: 965 * @num_bytes: the number of bytes of UTF-8 text covered by cluster 966 * @num_glyphs: the number of glyphs covered by cluster 967 * 968 * The #cairo_text_cluster_t structure holds information about a single 969 * <firstterm>text cluster</firstterm>. A text cluster is a minimal 970 * mapping of some glyphs corresponding to some UTF-8 text. 971 * 972 * For a cluster to be valid, both @num_bytes and @num_glyphs should 973 * be non-negative, and at least one should be non-zero. 974 * Note that clusters with zero glyphs are not as well supported as 975 * normal clusters. For example, PDF rendering applications typically 976 * ignore those clusters when PDF text is being selected. 977 * 978 * See cairo_show_text_glyphs() for how clusters are used in advanced 979 * text operations. 980 * 981 * Since: 1.8 982 **/ 983 typedef struct { 984 int num_bytes; 985 int num_glyphs; 986 } cairo_text_cluster_t; 987 988 cairo_public cairo_text_cluster_t * 989 cairo_text_cluster_allocate (int num_clusters); 990 991 cairo_public void 992 cairo_text_cluster_free (cairo_text_cluster_t *clusters); 993 994 /** 995 * cairo_text_cluster_flags_t: 996 * @CAIRO_TEXT_CLUSTER_FLAG_BACKWARD: The clusters in the cluster array 997 * map to glyphs in the glyph array from end to start. 998 * 999 * Specifies properties of a text cluster mapping. 1000 * 1001 * Since: 1.8 1002 **/ 1003 typedef enum _cairo_text_cluster_flags { 1004 CAIRO_TEXT_CLUSTER_FLAG_BACKWARD = 0x00000001 1005 } cairo_text_cluster_flags_t; 1006 1007 /** 1008 * cairo_text_extents_t: 1009 * @x_bearing: the horizontal distance from the origin to the 1010 * leftmost part of the glyphs as drawn. Positive if the 1011 * glyphs lie entirely to the right of the origin. 1012 * @y_bearing: the vertical distance from the origin to the 1013 * topmost part of the glyphs as drawn. Positive only if the 1014 * glyphs lie completely below the origin; will usually be 1015 * negative. 1016 * @width: width of the glyphs as drawn 1017 * @height: height of the glyphs as drawn 1018 * @x_advance:distance to advance in the X direction 1019 * after drawing these glyphs 1020 * @y_advance: distance to advance in the Y direction 1021 * after drawing these glyphs. Will typically be zero except 1022 * for vertical text layout as found in East-Asian languages. 1023 * 1024 * The #cairo_text_extents_t structure stores the extents of a single 1025 * glyph or a string of glyphs in user-space coordinates. Because text 1026 * extents are in user-space coordinates, they are mostly, but not 1027 * entirely, independent of the current transformation matrix. If you call 1028 * <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will 1029 * be drawn twice as big, but the reported text extents will not be 1030 * doubled. They will change slightly due to hinting (so you can't 1031 * assume that metrics are independent of the transformation matrix), 1032 * but otherwise will remain unchanged. 1033 **/ 1034 typedef struct { 1035 double x_bearing; 1036 double y_bearing; 1037 double width; 1038 double height; 1039 double x_advance; 1040 double y_advance; 1041 } cairo_text_extents_t; 1042 1043 /** 1044 * cairo_font_extents_t: 1045 * @ascent: the distance that the font extends above the baseline. 1046 * Note that this is not always exactly equal to the maximum 1047 * of the extents of all the glyphs in the font, but rather 1048 * is picked to express the font designer's intent as to 1049 * how the font should align with elements above it. 1050 * @descent: the distance that the font extends below the baseline. 1051 * This value is positive for typical fonts that include 1052 * portions below the baseline. Note that this is not always 1053 * exactly equal to the maximum of the extents of all the 1054 * glyphs in the font, but rather is picked to express the 1055 * font designer's intent as to how the the font should 1056 * align with elements below it. 1057 * @height: the recommended vertical distance between baselines when 1058 * setting consecutive lines of text with the font. This 1059 * is greater than @ascent+@descent by a 1060 * quantity known as the <firstterm>line spacing</firstterm> 1061 * or <firstterm>external leading</firstterm>. When space 1062 * is at a premium, most fonts can be set with only 1063 * a distance of @ascent+@descent between lines. 1064 * @max_x_advance: the maximum distance in the X direction that 1065 * the the origin is advanced for any glyph in the font. 1066 * @max_y_advance: the maximum distance in the Y direction that 1067 * the the origin is advanced for any glyph in the font. 1068 * this will be zero for normal fonts used for horizontal 1069 * writing. (The scripts of East Asia are sometimes written 1070 * vertically.) 1071 * 1072 * The #cairo_font_extents_t structure stores metric information for 1073 * a font. Values are given in the current user-space coordinate 1074 * system. 1075 * 1076 * Because font metrics are in user-space coordinates, they are 1077 * mostly, but not entirely, independent of the current transformation 1078 * matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>, 1079 * text will be drawn twice as big, but the reported text extents will 1080 * not be doubled. They will change slightly due to hinting (so you 1081 * can't assume that metrics are independent of the transformation 1082 * matrix), but otherwise will remain unchanged. 1083 **/ 1084 typedef struct { 1085 double ascent; 1086 double descent; 1087 double height; 1088 double max_x_advance; 1089 double max_y_advance; 1090 } cairo_font_extents_t; 1091 1092 /** 1093 * cairo_font_slant_t: 1094 * @CAIRO_FONT_SLANT_NORMAL: Upright font style 1095 * @CAIRO_FONT_SLANT_ITALIC: Italic font style 1096 * @CAIRO_FONT_SLANT_OBLIQUE: Oblique font style 1097 * 1098 * Specifies variants of a font face based on their slant. 1099 **/ 1100 typedef enum _cairo_font_slant { 1101 CAIRO_FONT_SLANT_NORMAL, 1102 CAIRO_FONT_SLANT_ITALIC, 1103 CAIRO_FONT_SLANT_OBLIQUE 1104 } cairo_font_slant_t; 1105 1106 /** 1107 * cairo_font_weight_t: 1108 * @CAIRO_FONT_WEIGHT_NORMAL: Normal font weight 1109 * @CAIRO_FONT_WEIGHT_BOLD: Bold font weight 1110 * 1111 * Specifies variants of a font face based on their weight. 1112 **/ 1113 typedef enum _cairo_font_weight { 1114 CAIRO_FONT_WEIGHT_NORMAL, 1115 CAIRO_FONT_WEIGHT_BOLD 1116 } cairo_font_weight_t; 1117 1118 /** 1119 * cairo_subpixel_order_t: 1120 * @CAIRO_SUBPIXEL_ORDER_DEFAULT: Use the default subpixel order for 1121 * for the target device 1122 * @CAIRO_SUBPIXEL_ORDER_RGB: Subpixel elements are arranged horizontally 1123 * with red at the left 1124 * @CAIRO_SUBPIXEL_ORDER_BGR: Subpixel elements are arranged horizontally 1125 * with blue at the left 1126 * @CAIRO_SUBPIXEL_ORDER_VRGB: Subpixel elements are arranged vertically 1127 * with red at the top 1128 * @CAIRO_SUBPIXEL_ORDER_VBGR: Subpixel elements are arranged vertically 1129 * with blue at the top 1130 * 1131 * The subpixel order specifies the order of color elements within 1132 * each pixel on the display device when rendering with an 1133 * antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL. 1134 **/ 1135 typedef enum _cairo_subpixel_order { 1136 CAIRO_SUBPIXEL_ORDER_DEFAULT, 1137 CAIRO_SUBPIXEL_ORDER_RGB, 1138 CAIRO_SUBPIXEL_ORDER_BGR, 1139 CAIRO_SUBPIXEL_ORDER_VRGB, 1140 CAIRO_SUBPIXEL_ORDER_VBGR 1141 } cairo_subpixel_order_t; 1142 1143 /** 1144 * cairo_hint_style_t: 1145 * @CAIRO_HINT_STYLE_DEFAULT: Use the default hint style for 1146 * font backend and target device 1147 * @CAIRO_HINT_STYLE_NONE: Do not hint outlines 1148 * @CAIRO_HINT_STYLE_SLIGHT: Hint outlines slightly to improve 1149 * contrast while retaining good fidelity to the original 1150 * shapes. 1151 * @CAIRO_HINT_STYLE_MEDIUM: Hint outlines with medium strength 1152 * giving a compromise between fidelity to the original shapes 1153 * and contrast 1154 * @CAIRO_HINT_STYLE_FULL: Hint outlines to maximize contrast 1155 * 1156 * Specifies the type of hinting to do on font outlines. Hinting 1157 * is the process of fitting outlines to the pixel grid in order 1158 * to improve the appearance of the result. Since hinting outlines 1159 * involves distorting them, it also reduces the faithfulness 1160 * to the original outline shapes. Not all of the outline hinting 1161 * styles are supported by all font backends. 1162 * 1163 * New entries may be added in future versions. 1164 **/ 1165 typedef enum _cairo_hint_style { 1166 CAIRO_HINT_STYLE_DEFAULT, 1167 CAIRO_HINT_STYLE_NONE, 1168 CAIRO_HINT_STYLE_SLIGHT, 1169 CAIRO_HINT_STYLE_MEDIUM, 1170 CAIRO_HINT_STYLE_FULL 1171 } cairo_hint_style_t; 1172 1173 /** 1174 * cairo_hint_metrics_t: 1175 * @CAIRO_HINT_METRICS_DEFAULT: Hint metrics in the default 1176 * manner for the font backend and target device 1177 * @CAIRO_HINT_METRICS_OFF: Do not hint font metrics 1178 * @CAIRO_HINT_METRICS_ON: Hint font metrics 1179 * 1180 * Specifies whether to hint font metrics; hinting font metrics 1181 * means quantizing them so that they are integer values in 1182 * device space. Doing this improves the consistency of 1183 * letter and line spacing, however it also means that text 1184 * will be laid out differently at different zoom factors. 1185 **/ 1186 typedef enum _cairo_hint_metrics { 1187 CAIRO_HINT_METRICS_DEFAULT, 1188 CAIRO_HINT_METRICS_OFF, 1189 CAIRO_HINT_METRICS_ON 1190 } cairo_hint_metrics_t; 1191 1192 /** 1193 * cairo_font_options_t: 1194 * 1195 * An opaque structure holding all options that are used when 1196 * rendering fonts. 1197 * 1198 * Individual features of a #cairo_font_options_t can be set or 1199 * accessed using functions named 1200 * cairo_font_options_set_<emphasis>feature_name</emphasis> and 1201 * cairo_font_options_get_<emphasis>feature_name</emphasis>, like 1202 * cairo_font_options_set_antialias() and 1203 * cairo_font_options_get_antialias(). 1204 * 1205 * New features may be added to a #cairo_font_options_t in the 1206 * future. For this reason, cairo_font_options_copy(), 1207 * cairo_font_options_equal(), cairo_font_options_merge(), and 1208 * cairo_font_options_hash() should be used to copy, check 1209 * for equality, merge, or compute a hash value of 1210 * #cairo_font_options_t objects. 1211 **/ 1212 typedef struct _cairo_font_options cairo_font_options_t; 1213 1214 cairo_public cairo_font_options_t * 1215 cairo_font_options_create (void); 1216 1217 cairo_public cairo_font_options_t * 1218 cairo_font_options_copy (const cairo_font_options_t *original); 1219 1220 cairo_public void 1221 cairo_font_options_destroy (cairo_font_options_t *options); 1222 1223 cairo_public cairo_status_t 1224 cairo_font_options_status (cairo_font_options_t *options); 1225 1226 cairo_public void 1227 cairo_font_options_merge (cairo_font_options_t *options, 1228 const cairo_font_options_t *other); 1229 cairo_public cairo_bool_t 1230 cairo_font_options_equal (const cairo_font_options_t *options, 1231 const cairo_font_options_t *other); 1232 1233 cairo_public unsigned long 1234 cairo_font_options_hash (const cairo_font_options_t *options); 1235 1236 cairo_public void 1237 cairo_font_options_set_antialias (cairo_font_options_t *options, 1238 cairo_antialias_t antialias); 1239 cairo_public cairo_antialias_t 1240 cairo_font_options_get_antialias (const cairo_font_options_t *options); 1241 1242 cairo_public void 1243 cairo_font_options_set_subpixel_order (cairo_font_options_t *options, 1244 cairo_subpixel_order_t subpixel_order); 1245 cairo_public cairo_subpixel_order_t 1246 cairo_font_options_get_subpixel_order (const cairo_font_options_t *options); 1247 1248 cairo_public void 1249 cairo_font_options_set_hint_style (cairo_font_options_t *options, 1250 cairo_hint_style_t hint_style); 1251 cairo_public cairo_hint_style_t 1252 cairo_font_options_get_hint_style (const cairo_font_options_t *options); 1253 1254 cairo_public void 1255 cairo_font_options_set_hint_metrics (cairo_font_options_t *options, 1256 cairo_hint_metrics_t hint_metrics); 1257 cairo_public cairo_hint_metrics_t 1258 cairo_font_options_get_hint_metrics (const cairo_font_options_t *options); 1259 1260 /* This interface is for dealing with text as text, not caring about the 1261 font object inside the the cairo_t. */ 1262 1263 cairo_public void 1264 cairo_select_font_face (cairo_t *cr, 1265 const char *family, 1266 cairo_font_slant_t slant, 1267 cairo_font_weight_t weight); 1268 1269 cairo_public void 1270 cairo_set_font_size (cairo_t *cr, double size); 1271 1272 cairo_public void 1273 cairo_set_font_matrix (cairo_t *cr, 1274 const cairo_matrix_t *matrix); 1275 1276 cairo_public void 1277 cairo_get_font_matrix (cairo_t *cr, 1278 cairo_matrix_t *matrix); 1279 1280 cairo_public void 1281 cairo_set_font_options (cairo_t *cr, 1282 const cairo_font_options_t *options); 1283 1284 cairo_public void 1285 cairo_get_font_options (cairo_t *cr, 1286 cairo_font_options_t *options); 1287 1288 cairo_public void 1289 cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face); 1290 1291 cairo_public cairo_font_face_t * 1292 cairo_get_font_face (cairo_t *cr); 1293 1294 cairo_public void 1295 cairo_set_scaled_font (cairo_t *cr, 1296 const cairo_scaled_font_t *scaled_font); 1297 1298 cairo_public cairo_scaled_font_t * 1299 cairo_get_scaled_font (cairo_t *cr); 1300 1301 cairo_public void 1302 cairo_show_text (cairo_t *cr, const char *utf8); 1303 1304 cairo_public void 1305 cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs); 1306 1307 cairo_public void 1308 cairo_show_text_glyphs (cairo_t *cr, 1309 const char *utf8, 1310 int utf8_len, 1311 const cairo_glyph_t *glyphs, 1312 int num_glyphs, 1313 const cairo_text_cluster_t *clusters, 1314 int num_clusters, 1315 cairo_text_cluster_flags_t cluster_flags); 1316 1317 cairo_public void 1318 cairo_text_path (cairo_t *cr, const char *utf8); 1319 1320 cairo_public void 1321 cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs); 1322 1323 cairo_public void 1324 cairo_text_extents (cairo_t *cr, 1325 const char *utf8, 1326 cairo_text_extents_t *extents); 1327 1328 cairo_public void 1329 cairo_glyph_extents (cairo_t *cr, 1330 const cairo_glyph_t *glyphs, 1331 int num_glyphs, 1332 cairo_text_extents_t *extents); 1333 1334 cairo_public void 1335 cairo_font_extents (cairo_t *cr, 1336 cairo_font_extents_t *extents); 1337 1338 /* Generic identifier for a font style */ 1339 1340 cairo_public cairo_font_face_t * 1341 cairo_font_face_reference (cairo_font_face_t *font_face); 1342 1343 cairo_public void 1344 cairo_font_face_destroy (cairo_font_face_t *font_face); 1345 1346 cairo_public unsigned int 1347 cairo_font_face_get_reference_count (cairo_font_face_t *font_face); 1348 1349 cairo_public cairo_status_t 1350 cairo_font_face_status (cairo_font_face_t *font_face); 1351 1352 1353 /** 1354 * cairo_font_type_t: 1355 * @CAIRO_FONT_TYPE_TOY: The font was created using cairo's toy font api 1356 * @CAIRO_FONT_TYPE_FT: The font is of type FreeType 1357 * @CAIRO_FONT_TYPE_WIN32: The font is of type Win32 1358 * @CAIRO_FONT_TYPE_QUARTZ: The font is of type Quartz (Since: 1.6) 1359 * @CAIRO_FONT_TYPE_USER: The font was create using cairo's user font api (Since: 1.8) 1360 * 1361 * #cairo_font_type_t is used to describe the type of a given font 1362 * face or scaled font. The font types are also known as "font 1363 * backends" within cairo. 1364 * 1365 * The type of a font face is determined by the function used to 1366 * create it, which will generally be of the form 1367 * cairo_<emphasis>type</emphasis>_font_face_create(). The font face type can be queried 1368 * with cairo_font_face_get_type() 1369 * 1370 * The various #cairo_font_face_t functions can be used with a font face 1371 * of any type. 1372 * 1373 * The type of a scaled font is determined by the type of the font 1374 * face passed to cairo_scaled_font_create(). The scaled font type can 1375 * be queried with cairo_scaled_font_get_type() 1376 * 1377 * The various #cairo_scaled_font_t functions can be used with scaled 1378 * fonts of any type, but some font backends also provide 1379 * type-specific functions that must only be called with a scaled font 1380 * of the appropriate type. These functions have names that begin with 1381 * cairo_<emphasis>type</emphasis>_scaled_font() such as cairo_ft_scaled_font_lock_face(). 1382 * 1383 * The behavior of calling a type-specific function with a scaled font 1384 * of the wrong type is undefined. 1385 * 1386 * New entries may be added in future versions. 1387 * 1388 * Since: 1.2 1389 **/ 1390 typedef enum _cairo_font_type { 1391 CAIRO_FONT_TYPE_TOY, 1392 CAIRO_FONT_TYPE_FT, 1393 CAIRO_FONT_TYPE_WIN32, 1394 CAIRO_FONT_TYPE_QUARTZ, 1395 CAIRO_FONT_TYPE_USER 1396 } cairo_font_type_t; 1397 1398 cairo_public cairo_font_type_t 1399 cairo_font_face_get_type (cairo_font_face_t *font_face); 1400 1401 cairo_public void * 1402 cairo_font_face_get_user_data (cairo_font_face_t *font_face, 1403 const cairo_user_data_key_t *key); 1404 1405 cairo_public cairo_status_t 1406 cairo_font_face_set_user_data (cairo_font_face_t *font_face, 1407 const cairo_user_data_key_t *key, 1408 void *user_data, 1409 cairo_destroy_func_t destroy); 1410 1411 /* Portable interface to general font features. */ 1412 1413 cairo_public cairo_scaled_font_t * 1414 cairo_scaled_font_create (cairo_font_face_t *font_face, 1415 const cairo_matrix_t *font_matrix, 1416 const cairo_matrix_t *ctm, 1417 const cairo_font_options_t *options); 1418 1419 cairo_public cairo_scaled_font_t * 1420 cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font); 1421 1422 cairo_public void 1423 cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font); 1424 1425 cairo_public unsigned int 1426 cairo_scaled_font_get_reference_count (cairo_scaled_font_t *scaled_font); 1427 1428 cairo_public cairo_status_t 1429 cairo_scaled_font_status (cairo_scaled_font_t *scaled_font); 1430 1431 cairo_public cairo_font_type_t 1432 cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font); 1433 1434 cairo_public void * 1435 cairo_scaled_font_get_user_data (cairo_scaled_font_t *scaled_font, 1436 const cairo_user_data_key_t *key); 1437 1438 cairo_public cairo_status_t 1439 cairo_scaled_font_set_user_data (cairo_scaled_font_t *scaled_font, 1440 const cairo_user_data_key_t *key, 1441 void *user_data, 1442 cairo_destroy_func_t destroy); 1443 1444 cairo_public void 1445 cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font, 1446 cairo_font_extents_t *extents); 1447 1448 cairo_public void 1449 cairo_scaled_font_text_extents (cairo_scaled_font_t *scaled_font, 1450 const char *utf8, 1451 cairo_text_extents_t *extents); 1452 1453 cairo_public void 1454 cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font, 1455 const cairo_glyph_t *glyphs, 1456 int num_glyphs, 1457 cairo_text_extents_t *extents); 1458 1459 cairo_public cairo_status_t 1460 cairo_scaled_font_text_to_glyphs (cairo_scaled_font_t *scaled_font, 1461 double x, 1462 double y, 1463 const char *utf8, 1464 int utf8_len, 1465 cairo_glyph_t **glyphs, 1466 int *num_glyphs, 1467 cairo_text_cluster_t **clusters, 1468 int *num_clusters, 1469 cairo_text_cluster_flags_t *cluster_flags); 1470 1471 cairo_public cairo_font_face_t * 1472 cairo_scaled_font_get_font_face (cairo_scaled_font_t *scaled_font); 1473 1474 cairo_public void 1475 cairo_scaled_font_get_font_matrix (cairo_scaled_font_t *scaled_font, 1476 cairo_matrix_t *font_matrix); 1477 1478 cairo_public void 1479 cairo_scaled_font_get_ctm (cairo_scaled_font_t *scaled_font, 1480 cairo_matrix_t *ctm); 1481 1482 cairo_public void 1483 cairo_scaled_font_get_scale_matrix (cairo_scaled_font_t *scaled_font, 1484 cairo_matrix_t *scale_matrix); 1485 1486 cairo_public void 1487 cairo_scaled_font_get_font_options (cairo_scaled_font_t *scaled_font, 1488 cairo_font_options_t *options); 1489 1490 1491 /* Toy fonts */ 1492 1493 cairo_public cairo_font_face_t * 1494 cairo_toy_font_face_create (const char *family, 1495 cairo_font_slant_t slant, 1496 cairo_font_weight_t weight); 1497 1498 cairo_public const char * 1499 cairo_toy_font_face_get_family (cairo_font_face_t *font_face); 1500 1501 cairo_public cairo_font_slant_t 1502 cairo_toy_font_face_get_slant (cairo_font_face_t *font_face); 1503 1504 cairo_public cairo_font_weight_t 1505 cairo_toy_font_face_get_weight (cairo_font_face_t *font_face); 1506 1507 1508 /* User fonts */ 1509 1510 cairo_public cairo_font_face_t * 1511 cairo_user_font_face_create (void); 1512 1513 /* User-font method signatures */ 1514 1515 /** 1516 * cairo_user_scaled_font_init_func_t: 1517 * @scaled_font: the scaled-font being created 1518 * @cr: a cairo context, in font space 1519 * @extents: font extents to fill in, in font space 1520 * 1521 * #cairo_user_scaled_font_init_func_t is the type of function which is 1522 * called when a scaled-font needs to be created for a user font-face. 1523 * 1524 * The cairo context @cr is not used by the caller, but is prepared in font 1525 * space, similar to what the cairo contexts passed to the render_glyph 1526 * method will look like. The callback can use this context for extents 1527 * computation for example. After the callback is called, @cr is checked 1528 * for any error status. 1529 * 1530 * The @extents argument is where the user font sets the font extents for 1531 * @scaled_font. It is in font space, which means that for most cases its 1532 * ascent and descent members should add to 1.0. @extents is preset to 1533 * hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for 1534 * descent and max_y_advance members. 1535 * 1536 * The callback is optional. If not set, default font extents as described 1537 * in the previous paragraph will be used. 1538 * 1539 * Note that @scaled_font is not fully initialized at this 1540 * point and trying to use it for text operations in the callback will result 1541 * in deadlock. 1542 * 1543 * Returns: %CAIRO_STATUS_SUCCESS upon success, or an error status on error. 1544 * 1545 * Since: 1.8 1546 **/ 1547 typedef cairo_status_t (*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t *scaled_font, 1548 cairo_t *cr, 1549 cairo_font_extents_t *extents); 1550 1551 /** 1552 * cairo_user_scaled_font_render_glyph_func_t: 1553 * @scaled_font: user scaled-font 1554 * @glyph: glyph code to render 1555 * @cr: cairo context to draw to, in font space 1556 * @extents: glyph extents to fill in, in font space 1557 * 1558 * #cairo_user_scaled_font_render_glyph_func_t is the type of function which 1559 * is called when a user scaled-font needs to render a glyph. 1560 * 1561 * The callback is mandatory, and expected to draw the glyph with code @glyph to 1562 * the cairo context @cr. @cr is prepared such that the glyph drawing is done in 1563 * font space. That is, the matrix set on @cr is the scale matrix of @scaled_font, 1564 * The @extents argument is where the user font sets the font extents for 1565 * @scaled_font. However, if user prefers to draw in user space, they can 1566 * achieve that by changing the matrix on @cr. All cairo rendering operations 1567 * to @cr are permitted, however, the result is undefined if any source other 1568 * than the default source on @cr is used. That means, glyph bitmaps should 1569 * be rendered using cairo_mask() instead of cairo_paint(). 1570 * 1571 * Other non-default settings on @cr include a font size of 1.0 (given that 1572 * it is set up to be in font space), and font options corresponding to 1573 * @scaled_font. 1574 * 1575 * The @extents argument is preset to have <literal>x_bearing</literal>, 1576 * <literal>width</literal>, and <literal>y_advance</literal> of zero, 1577 * <literal>y_bearing</literal> set to <literal>-font_extents.ascent</literal>, 1578 * <literal>height</literal> to <literal>font_extents.ascent+font_extents.descent</literal>, 1579 * and <literal>x_advance</literal> to <literal>font_extents.max_x_advance</literal>. 1580 * The only field user needs to set in majority of cases is 1581 * <literal>x_advance</literal>. 1582 * If the <literal>width</literal> field is zero upon the callback returning 1583 * (which is its preset value), the glyph extents are automatically computed 1584 * based on the drawings done to @cr. This is in most cases exactly what the 1585 * desired behavior is. However, if for any reason the callback sets the 1586 * extents, it must be ink extents, and include the extents of all drawing 1587 * done to @cr in the callback. 1588 * 1589 * Returns: %CAIRO_STATUS_SUCCESS upon success, or 1590 * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error. 1591 * 1592 * Since: 1.8 1593 **/ 1594 typedef cairo_status_t (*cairo_user_scaled_font_render_glyph_func_t) (cairo_scaled_font_t *scaled_font, 1595 unsigned long glyph, 1596 cairo_t *cr, 1597 cairo_text_extents_t *extents); 1598 1599 /** 1600 * cairo_user_scaled_font_text_to_glyphs_func_t: 1601 * @scaled_font: the scaled-font being created 1602 * @utf8: a string of text encoded in UTF-8 1603 * @utf8_len: length of @utf8 in bytes 1604 * @glyphs: pointer to array of glyphs to fill, in font space 1605 * @num_glyphs: pointer to number of glyphs 1606 * @clusters: pointer to array of cluster mapping information to fill, or %NULL 1607 * @num_clusters: pointer to number of clusters 1608 * @cluster_flags: pointer to location to store cluster flags corresponding to the 1609 * output @clusters 1610 * 1611 * #cairo_user_scaled_font_text_to_glyphs_func_t is the type of function which 1612 * is called to convert input text to an array of glyphs. This is used by the 1613 * cairo_show_text() operation. 1614 * 1615 * Using this callback the user-font has full control on glyphs and their 1616 * positions. That means, it allows for features like ligatures and kerning, 1617 * as well as complex <firstterm>shaping</firstterm> required for scripts like 1618 * Arabic and Indic. 1619 * 1620 * The @num_glyphs argument is preset to the number of glyph entries available 1621 * in the @glyphs buffer. If the @glyphs buffer is %NULL, the value of 1622 * @num_glyphs will be zero. If the provided glyph array is too short for 1623 * the conversion (or for convenience), a new glyph array may be allocated 1624 * using cairo_glyph_allocate() and placed in @glyphs. Upon return, 1625 * @num_glyphs should contain the number of generated glyphs. If the value 1626 * @glyphs points at has changed after the call, the caller will free the 1627 * allocated glyph array using cairo_glyph_free(). 1628 * The callback should populate the glyph indices and positions (in font space) 1629 * assuming that the text is to be shown at the origin. 1630 * 1631 * If @clusters is not %NULL, @num_clusters and @cluster_flags are also 1632 * non-%NULL, and cluster mapping should be computed. The semantics of how 1633 * cluster array allocation works is similar to the glyph array. That is, 1634 * if @clusters initially points to a non-%NULL value, that array may be used 1635 * as a cluster buffer, and @num_clusters points to the number of cluster 1636 * entries available there. If the provided cluster array is too short for 1637 * the conversion (or for convenience), a new cluster array may be allocated 1638 * using cairo_text_cluster_allocate() and placed in @clusters. Upon return, 1639 * @num_clusters should contain the number of generated clusters. 1640 * If the value @clusters points at has changed after the call, the caller 1641 * will free the allocated cluster array using cairo_text_cluster_free(). 1642 * 1643 * The callback is optional. If @num_glyphs is negative upon 1644 * the callback returning or if the return value 1645 * is %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, the unicode_to_glyph callback 1646 * is tried. See #cairo_user_scaled_font_unicode_to_glyph_func_t. 1647 * 1648 * Note: While cairo does not impose any limitation on glyph indices, 1649 * some applications may assume that a glyph index fits in a 16-bit 1650 * unsigned integer. As such, it is advised that user-fonts keep their 1651 * glyphs in the 0 to 65535 range. Furthermore, some applications may 1652 * assume that glyph 0 is a special glyph-not-found glyph. User-fonts 1653 * are advised to use glyph 0 for such purposes and do not use that 1654 * glyph value for other purposes. 1655 * 1656 * Returns: %CAIRO_STATUS_SUCCESS upon success, 1657 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, 1658 * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error. 1659 * 1660 * Since: 1.8 1661 **/ 1662 typedef cairo_status_t (*cairo_user_scaled_font_text_to_glyphs_func_t) (cairo_scaled_font_t *scaled_font, 1663 const char *utf8, 1664 int utf8_len, 1665 cairo_glyph_t **glyphs, 1666 int *num_glyphs, 1667 cairo_text_cluster_t **clusters, 1668 int *num_clusters, 1669 cairo_text_cluster_flags_t *cluster_flags); 1670 1671 /** 1672 * cairo_user_scaled_font_unicode_to_glyph_func_t: 1673 * @scaled_font: the scaled-font being created 1674 * @unicode: input unicode character code-point 1675 * @glyph_index: output glyph index 1676 * 1677 * #cairo_user_scaled_font_unicode_to_glyph_func_t is the type of function which 1678 * is called to convert an input Unicode character to a single glyph. 1679 * This is used by the cairo_show_text() operation. 1680 * 1681 * This callback is used to provide the same functionality as the 1682 * text_to_glyphs callback does (see #cairo_user_scaled_font_text_to_glyphs_func_t) 1683 * but has much less control on the output, 1684 * in exchange for increased ease of use. The inherent assumption to using 1685 * this callback is that each character maps to one glyph, and that the 1686 * mapping is context independent. It also assumes that glyphs are positioned 1687 * according to their advance width. These mean no ligatures, kerning, or 1688 * complex scripts can be implemented using this callback. 1689 * 1690 * The callback is optional, and only used if text_to_glyphs callback is not 1691 * set or fails to return glyphs. If this callback is not set or if it returns 1692 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, an identity mapping from Unicode 1693 * code-points to glyph indices is assumed. 1694 * 1695 * Note: While cairo does not impose any limitation on glyph indices, 1696 * some applications may assume that a glyph index fits in a 16-bit 1697 * unsigned integer. As such, it is advised that user-fonts keep their 1698 * glyphs in the 0 to 65535 range. Furthermore, some applications may 1699 * assume that glyph 0 is a special glyph-not-found glyph. User-fonts 1700 * are advised to use glyph 0 for such purposes and do not use that 1701 * glyph value for other purposes. 1702 * 1703 * Returns: %CAIRO_STATUS_SUCCESS upon success, 1704 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, 1705 * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error. 1706 * 1707 * Since: 1.8 1708 **/ 1709 typedef cairo_status_t (*cairo_user_scaled_font_unicode_to_glyph_func_t) (cairo_scaled_font_t *scaled_font, 1710 unsigned long unicode, 1711 unsigned long *glyph_index); 1712 1713 /* User-font method setters */ 1714 1715 cairo_public void 1716 cairo_user_font_face_set_init_func (cairo_font_face_t *font_face, 1717 cairo_user_scaled_font_init_func_t init_func); 1718 1719 cairo_public void 1720 cairo_user_font_face_set_render_glyph_func (cairo_font_face_t *font_face, 1721 cairo_user_scaled_font_render_glyph_func_t render_glyph_func); 1722 1723 cairo_public void 1724 cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t *font_face, 1725 cairo_user_scaled_font_text_to_glyphs_func_t text_to_glyphs_func); 1726 1727 cairo_public void 1728 cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t *font_face, 1729 cairo_user_scaled_font_unicode_to_glyph_func_t unicode_to_glyph_func); 1730 1731 /* User-font method getters */ 1732 1733 cairo_public cairo_user_scaled_font_init_func_t 1734 cairo_user_font_face_get_init_func (cairo_font_face_t *font_face); 1735 1736 cairo_public cairo_user_scaled_font_render_glyph_func_t 1737 cairo_user_font_face_get_render_glyph_func (cairo_font_face_t *font_face); 1738 1739 cairo_public cairo_user_scaled_font_text_to_glyphs_func_t 1740 cairo_user_font_face_get_text_to_glyphs_func (cairo_font_face_t *font_face); 1741 1742 cairo_public cairo_user_scaled_font_unicode_to_glyph_func_t 1743 cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face); 1744 1745 1746 /* Query functions */ 1747 1748 cairo_public cairo_operator_t 1749 cairo_get_operator (cairo_t *cr); 1750 1751 cairo_public cairo_pattern_t * 1752 cairo_get_source (cairo_t *cr); 1753 1754 cairo_public double 1755 cairo_get_tolerance (cairo_t *cr); 1756 1757 cairo_public cairo_antialias_t 1758 cairo_get_antialias (cairo_t *cr); 1759 1760 cairo_public cairo_bool_t 1761 cairo_has_current_point (cairo_t *cr); 1762 1763 cairo_public void 1764 cairo_get_current_point (cairo_t *cr, double *x, double *y); 1765 1766 cairo_public cairo_fill_rule_t 1767 cairo_get_fill_rule (cairo_t *cr); 1768 1769 cairo_public double 1770 cairo_get_line_width (cairo_t *cr); 1771 1772 cairo_public cairo_line_cap_t 1773 cairo_get_line_cap (cairo_t *cr); 1774 1775 cairo_public cairo_line_join_t 1776 cairo_get_line_join (cairo_t *cr); 1777 1778 cairo_public double 1779 cairo_get_miter_limit (cairo_t *cr); 1780 1781 cairo_public int 1782 cairo_get_dash_count (cairo_t *cr); 1783 1784 cairo_public void 1785 cairo_get_dash (cairo_t *cr, double *dashes, double *offset); 1786 1787 cairo_public void 1788 cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix); 1789 1790 cairo_public cairo_surface_t * 1791 cairo_get_target (cairo_t *cr); 1792 1793 cairo_public cairo_surface_t * 1794 cairo_get_group_target (cairo_t *cr); 1795 1796 /** 1797 * cairo_path_data_type_t: 1798 * @CAIRO_PATH_MOVE_TO: A move-to operation 1799 * @CAIRO_PATH_LINE_TO: A line-to operation 1800 * @CAIRO_PATH_CURVE_TO: A curve-to operation 1801 * @CAIRO_PATH_CLOSE_PATH: A close-path operation 1802 * 1803 * #cairo_path_data_t is used to describe the type of one portion 1804 * of a path when represented as a #cairo_path_t. 1805 * See #cairo_path_data_t for details. 1806 **/ 1807 typedef enum _cairo_path_data_type { 1808 CAIRO_PATH_MOVE_TO, 1809 CAIRO_PATH_LINE_TO, 1810 CAIRO_PATH_CURVE_TO, 1811 CAIRO_PATH_CLOSE_PATH 1812 } cairo_path_data_type_t; 1813 1814 /** 1815 * cairo_path_data_t: 1816 * 1817 * #cairo_path_data_t is used to represent the path data inside a 1818 * #cairo_path_t. 1819 * 1820 * The data structure is designed to try to balance the demands of 1821 * efficiency and ease-of-use. A path is represented as an array of 1822 * #cairo_path_data_t, which is a union of headers and points. 1823 * 1824 * Each portion of the path is represented by one or more elements in 1825 * the array, (one header followed by 0 or more points). The length 1826 * value of the header is the number of array elements for the current 1827 * portion including the header, (ie. length == 1 + # of points), and 1828 * where the number of points for each element type is as follows: 1829 * 1830 * <programlisting> 1831 * %CAIRO_PATH_MOVE_TO: 1 point 1832 * %CAIRO_PATH_LINE_TO: 1 point 1833 * %CAIRO_PATH_CURVE_TO: 3 points 1834 * %CAIRO_PATH_CLOSE_PATH: 0 points 1835 * </programlisting> 1836 * 1837 * The semantics and ordering of the coordinate values are consistent 1838 * with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and 1839 * cairo_close_path(). 1840 * 1841 * Here is sample code for iterating through a #cairo_path_t: 1842 * 1843 * <informalexample><programlisting> 1844 * int i; 1845 * cairo_path_t *path; 1846 * cairo_path_data_t *data; 1847 * 1848 * path = cairo_copy_path (cr); 1849 * 1850 * for (i=0; i < path->num_data; i += path->data[i].header.length) { 1851 * data = &path->data[i]; 1852 * switch (data->header.type) { 1853 * case CAIRO_PATH_MOVE_TO: 1854 * do_move_to_things (data[1].point.x, data[1].point.y); 1855 * break; 1856 * case CAIRO_PATH_LINE_TO: 1857 * do_line_to_things (data[1].point.x, data[1].point.y); 1858 * break; 1859 * case CAIRO_PATH_CURVE_TO: 1860 * do_curve_to_things (data[1].point.x, data[1].point.y, 1861 * data[2].point.x, data[2].point.y, 1862 * data[3].point.x, data[3].point.y); 1863 * break; 1864 * case CAIRO_PATH_CLOSE_PATH: 1865 * do_close_path_things (); 1866 * break; 1867 * } 1868 * } 1869 * cairo_path_destroy (path); 1870 * </programlisting></informalexample> 1871 * 1872 * As of cairo 1.4, cairo does not mind if there are more elements in 1873 * a portion of the path than needed. Such elements can be used by 1874 * users of the cairo API to hold extra values in the path data 1875 * structure. For this reason, it is recommended that applications 1876 * always use <literal>data->header.length</literal> to 1877 * iterate over the path data, instead of hardcoding the number of 1878 * elements for each element type. 1879 **/ 1880 typedef union _cairo_path_data_t cairo_path_data_t; 1881 union _cairo_path_data_t { 1882 struct { 1883 cairo_path_data_type_t type; 1884 int length; 1885 } header; 1886 struct { 1887 double x, y; 1888 } point; 1889 }; 1890 1891 /** 1892 * cairo_path_t: 1893 * @status: the current error status 1894 * @data: the elements in the path 1895 * @num_data: the number of elements in the data array 1896 * 1897 * A data structure for holding a path. This data structure serves as 1898 * the return value for cairo_copy_path() and 1899 * cairo_copy_path_flat() as well the input value for 1900 * cairo_append_path(). 1901 * 1902 * See #cairo_path_data_t for hints on how to iterate over the 1903 * actual data within the path. 1904 * 1905 * The num_data member gives the number of elements in the data 1906 * array. This number is larger than the number of independent path 1907 * portions (defined in #cairo_path_data_type_t), since the data 1908 * includes both headers and coordinates for each portion. 1909 **/ 1910 typedef struct cairo_path { 1911 cairo_status_t status; 1912 cairo_path_data_t *data; 1913 int num_data; 1914 } cairo_path_t; 1915 1916 cairo_public cairo_path_t * 1917 cairo_copy_path (cairo_t *cr); 1918 1919 cairo_public cairo_path_t * 1920 cairo_copy_path_flat (cairo_t *cr); 1921 1922 cairo_public void 1923 cairo_append_path (cairo_t *cr, 1924 const cairo_path_t *path); 1925 1926 cairo_public void 1927 cairo_path_destroy (cairo_path_t *path); 1928 1929 /* Error status queries */ 1930 1931 cairo_public cairo_status_t 1932 cairo_status (cairo_t *cr); 1933 1934 cairo_public const char * 1935 cairo_status_to_string (cairo_status_t status); 1936 1937 /* Backend device manipulation */ 1938 1939 cairo_public cairo_device_t * 1940 cairo_device_reference (cairo_device_t *device); 1941 1942 /** 1943 * cairo_device_type_t: 1944 * @CAIRO_DEVICE_TYPE_DRM: The surface is of type Direct Render Manager 1945 * @CAIRO_DEVICE_TYPE_GL: The surface is of type OpenGL 1946 * @CAIRO_DEVICE_TYPE_SCRIPT: The surface is of type script 1947 * @CAIRO_DEVICE_TYPE_XCB: The surface is of type xcb 1948 * @CAIRO_DEVICE_TYPE_XLIB: The surface is of type xlib 1949 * @CAIRO_DEVICE_TYPE_XML: The surface is of type XML 1950 * cairo_surface_create_for_rectangle() 1951 * 1952 * #cairo_device_type_t is used to describe the type of a given 1953 * device. The devices types are also known as "backends" within cairo. 1954 * 1955 * The device type can be queried with cairo_device_get_type() 1956 * 1957 * The various #cairo_device_t functions can be used with surfaces of 1958 * any type, but some backends also provide type-specific functions 1959 * that must only be called with a device of the appropriate 1960 * type. These functions have names that begin with 1961 * cairo_<emphasis>type</emphasis>_device<!-- --> such as cairo_xcb_device_debug_set_render_version(). 1962 * 1963 * The behavior of calling a type-specific function with a surface of 1964 * the wrong type is undefined. 1965 * 1966 * New entries may be added in future versions. 1967 * 1968 * Since: 1.10 1969 **/ 1970 typedef enum _cairo_device_type { 1971 CAIRO_DEVICE_TYPE_DRM, 1972 CAIRO_DEVICE_TYPE_GL, 1973 CAIRO_DEVICE_TYPE_SCRIPT, 1974 CAIRO_DEVICE_TYPE_XCB, 1975 CAIRO_DEVICE_TYPE_XLIB, 1976 CAIRO_DEVICE_TYPE_XML 1977 } cairo_device_type_t; 1978 1979 cairo_public cairo_device_type_t 1980 cairo_device_get_type (cairo_device_t *device); 1981 1982 cairo_public cairo_status_t 1983 cairo_device_status (cairo_device_t *device); 1984 1985 cairo_public cairo_status_t 1986 cairo_device_acquire (cairo_device_t *device); 1987 1988 cairo_public void 1989 cairo_device_release (cairo_device_t *device); 1990 1991 cairo_public void 1992 cairo_device_flush (cairo_device_t *device); 1993 1994 cairo_public void 1995 cairo_device_finish (cairo_device_t *device); 1996 1997 cairo_public void 1998 cairo_device_destroy (cairo_device_t *device); 1999 2000 cairo_public unsigned int 2001 cairo_device_get_reference_count (cairo_device_t *device); 2002 2003 cairo_public void * 2004 cairo_device_get_user_data (cairo_device_t *device, 2005 const cairo_user_data_key_t *key); 2006 2007 cairo_public cairo_status_t 2008 cairo_device_set_user_data (cairo_device_t *device, 2009 const cairo_user_data_key_t *key, 2010 void *user_data, 2011 cairo_destroy_func_t destroy); 2012 2013 2014 /* Surface manipulation */ 2015 2016 cairo_public cairo_surface_t * 2017 cairo_surface_create_similar (cairo_surface_t *other, 2018 cairo_content_t content, 2019 int width, 2020 int height); 2021 2022 cairo_public cairo_surface_t * 2023 cairo_surface_create_for_rectangle (cairo_surface_t *target, 2024 double x, 2025 double y, 2026 double width, 2027 double height); 2028 2029 cairo_public cairo_surface_t * 2030 cairo_surface_reference (cairo_surface_t *surface); 2031 2032 cairo_public void 2033 cairo_surface_finish (cairo_surface_t *surface); 2034 2035 cairo_public void 2036 cairo_surface_destroy (cairo_surface_t *surface); 2037 2038 cairo_public cairo_device_t * 2039 cairo_surface_get_device (cairo_surface_t *surface); 2040 2041 cairo_public unsigned int 2042 cairo_surface_get_reference_count (cairo_surface_t *surface); 2043 2044 cairo_public cairo_status_t 2045 cairo_surface_status (cairo_surface_t *surface); 2046 2047 /** 2048 * cairo_surface_type_t: 2049 * @CAIRO_SURFACE_TYPE_IMAGE: The surface is of type image 2050 * @CAIRO_SURFACE_TYPE_PDF: The surface is of type pdf 2051 * @CAIRO_SURFACE_TYPE_PS: The surface is of type ps 2052 * @CAIRO_SURFACE_TYPE_XLIB: The surface is of type xlib 2053 * @CAIRO_SURFACE_TYPE_XCB: The surface is of type xcb 2054 * @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz 2055 * @CAIRO_SURFACE_TYPE_QUARTZ: The surface is of type quartz 2056 * @CAIRO_SURFACE_TYPE_WIN32: The surface is of type win32 2057 * @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos 2058 * @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb 2059 * @CAIRO_SURFACE_TYPE_SVG: The surface is of type svg 2060 * @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2 2061 * @CAIRO_SURFACE_TYPE_WIN32_PRINTING: The surface is a win32 printing surface 2062 * @CAIRO_SURFACE_TYPE_QUARTZ_IMAGE: The surface is of type quartz_image 2063 * @CAIRO_SURFACE_TYPE_SCRIPT: The surface is of type script, since 1.10 2064 * @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10 2065 * @CAIRO_SURFACE_TYPE_RECORDING: The surface is of type recording, since 1.10 2066 * @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10 2067 * @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10 2068 * @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10 2069 * @CAIRO_SURFACE_TYPE_TEE: The surface is of type 'tee' (a multiplexing surface), since 1.10 2070 * @CAIRO_SURFACE_TYPE_XML: The surface is of type XML (for debugging), since 1.10 2071 * @CAIRO_SURFACE_TYPE_SKIA: The surface is of type Skia, since 1.10 2072 * @CAIRO_SURFACE_TYPE_SUBSURFACE: The surface is a subsurface created with 2073 * cairo_surface_create_for_rectangle(), since 1.10 2074 * 2075 * #cairo_surface_type_t is used to describe the type of a given 2076 * surface. The surface types are also known as "backends" or "surface 2077 * backends" within cairo. 2078 * 2079 * The type of a surface is determined by the function used to create 2080 * it, which will generally be of the form cairo_<emphasis>type</emphasis>_surface_create(), 2081 * (though see cairo_surface_create_similar() as well). 2082 * 2083 * The surface type can be queried with cairo_surface_get_type() 2084 * 2085 * The various #cairo_surface_t functions can be used with surfaces of 2086 * any type, but some backends also provide type-specific functions 2087 * that must only be called with a surface of the appropriate 2088 * type. These functions have names that begin with 2089 * cairo_<emphasis>type</emphasis>_surface<!-- --> such as cairo_image_surface_get_width(). 2090 * 2091 * The behavior of calling a type-specific function with a surface of 2092 * the wrong type is undefined. 2093 * 2094 * New entries may be added in future versions. 2095 * 2096 * Since: 1.2 2097 **/ 2098 typedef enum _cairo_surface_type { 2099 CAIRO_SURFACE_TYPE_IMAGE, 2100 CAIRO_SURFACE_TYPE_PDF, 2101 CAIRO_SURFACE_TYPE_PS, 2102 CAIRO_SURFACE_TYPE_XLIB, 2103 CAIRO_SURFACE_TYPE_XCB, 2104 CAIRO_SURFACE_TYPE_GLITZ, 2105 CAIRO_SURFACE_TYPE_QUARTZ, 2106 CAIRO_SURFACE_TYPE_WIN32, 2107 CAIRO_SURFACE_TYPE_BEOS, 2108 CAIRO_SURFACE_TYPE_DIRECTFB, 2109 CAIRO_SURFACE_TYPE_SVG, 2110 CAIRO_SURFACE_TYPE_OS2, 2111 CAIRO_SURFACE_TYPE_WIN32_PRINTING, 2112 CAIRO_SURFACE_TYPE_QUARTZ_IMAGE, 2113 CAIRO_SURFACE_TYPE_SCRIPT, 2114 CAIRO_SURFACE_TYPE_QT, 2115 CAIRO_SURFACE_TYPE_RECORDING, 2116 CAIRO_SURFACE_TYPE_VG, 2117 CAIRO_SURFACE_TYPE_GL, 2118 CAIRO_SURFACE_TYPE_DRM, 2119 CAIRO_SURFACE_TYPE_TEE, 2120 CAIRO_SURFACE_TYPE_XML, 2121 CAIRO_SURFACE_TYPE_SKIA, 2122 CAIRO_SURFACE_TYPE_SUBSURFACE 2123 } cairo_surface_type_t; 2124 2125 cairo_public cairo_surface_type_t 2126 cairo_surface_get_type (cairo_surface_t *surface); 2127 2128 cairo_public cairo_content_t 2129 cairo_surface_get_content (cairo_surface_t *surface); 2130 2131 #if CAIRO_HAS_PNG_FUNCTIONS 2132 2133 cairo_public cairo_status_t 2134 cairo_surface_write_to_png (cairo_surface_t *surface, 2135 const char *filename); 2136 2137 cairo_public cairo_status_t 2138 cairo_surface_write_to_png_stream (cairo_surface_t *surface, 2139 cairo_write_func_t write_func, 2140 void *closure); 2141 2142 #endif 2143 2144 cairo_public void * 2145 cairo_surface_get_user_data (cairo_surface_t *surface, 2146 const cairo_user_data_key_t *key); 2147 2148 cairo_public cairo_status_t 2149 cairo_surface_set_user_data (cairo_surface_t *surface, 2150 const cairo_user_data_key_t *key, 2151 void *user_data, 2152 cairo_destroy_func_t destroy); 2153 2154 #define CAIRO_MIME_TYPE_JPEG "image/jpeg" 2155 #define CAIRO_MIME_TYPE_PNG "image/png" 2156 #define CAIRO_MIME_TYPE_JP2 "image/jp2" 2157 #define CAIRO_MIME_TYPE_URI "text/x-uri" 2158 2159 cairo_public void 2160 cairo_surface_get_mime_data (cairo_surface_t *surface, 2161 const char *mime_type, 2162 const unsigned char **data, 2163 unsigned long *length); 2164 2165 cairo_public cairo_status_t 2166 cairo_surface_set_mime_data (cairo_surface_t *surface, 2167 const char *mime_type, 2168 const unsigned char *data, 2169 unsigned long length, 2170 cairo_destroy_func_t destroy, 2171 void *closure); 2172 2173 cairo_public void 2174 cairo_surface_get_font_options (cairo_surface_t *surface, 2175 cairo_font_options_t *options); 2176 2177 cairo_public void 2178 cairo_surface_flush (cairo_surface_t *surface); 2179 2180 cairo_public void 2181 cairo_surface_mark_dirty (cairo_surface_t *surface); 2182 2183 cairo_public void 2184 cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface, 2185 int x, 2186 int y, 2187 int width, 2188 int height); 2189 2190 cairo_public void 2191 cairo_surface_set_device_offset (cairo_surface_t *surface, 2192 double x_offset, 2193 double y_offset); 2194 2195 cairo_public void 2196 cairo_surface_get_device_offset (cairo_surface_t *surface, 2197 double *x_offset, 2198 double *y_offset); 2199 2200 cairo_public void 2201 cairo_surface_set_fallback_resolution (cairo_surface_t *surface, 2202 double x_pixels_per_inch, 2203 double y_pixels_per_inch); 2204 2205 cairo_public void 2206 cairo_surface_get_fallback_resolution (cairo_surface_t *surface, 2207 double *x_pixels_per_inch, 2208 double *y_pixels_per_inch); 2209 2210 cairo_public void 2211 cairo_surface_copy_page (cairo_surface_t *surface); 2212 2213 cairo_public void 2214 cairo_surface_show_page (cairo_surface_t *surface); 2215 2216 cairo_public cairo_bool_t 2217 cairo_surface_has_show_text_glyphs (cairo_surface_t *surface); 2218 2219 /* Image-surface functions */ 2220 2221 /** 2222 * cairo_format_t: 2223 * @CAIRO_FORMAT_INVALID: no such format exists or is supported. 2224 * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with 2225 * alpha in the upper 8 bits, then red, then green, then blue. 2226 * The 32-bit quantities are stored native-endian. Pre-multiplied 2227 * alpha is used. (That is, 50% transparent red is 0x80800000, 2228 * not 0x80ff0000.) 2229 * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with 2230 * the upper 8 bits unused. Red, Green, and Blue are stored 2231 * in the remaining 24 bits in that order. 2232 * @CAIRO_FORMAT_A8: each pixel is a 8-bit quantity holding 2233 * an alpha value. 2234 * @CAIRO_FORMAT_A1: each pixel is a 1-bit quantity holding 2235 * an alpha value. Pixels are packed together into 32-bit 2236 * quantities. The ordering of the bits matches the 2237 * endianess of the platform. On a big-endian machine, the 2238 * first pixel is in the uppermost bit, on a little-endian 2239 * machine the first pixel is in the least-significant bit. 2240 * @CAIRO_FORMAT_RGB16_565: each pixel is a 16-bit quantity 2241 * with red in the upper 5 bits, then green in the middle 2242 * 6 bits, and blue in the lower 5 bits. 2243 * 2244 * #cairo_format_t is used to identify the memory format of 2245 * image data. 2246 * 2247 * New entries may be added in future versions. 2248 **/ 2249 typedef enum _cairo_format { 2250 CAIRO_FORMAT_INVALID = -1, 2251 CAIRO_FORMAT_ARGB32 = 0, 2252 CAIRO_FORMAT_RGB24 = 1, 2253 CAIRO_FORMAT_A8 = 2, 2254 CAIRO_FORMAT_A1 = 3, 2255 CAIRO_FORMAT_RGB16_565 = 4 2256 } cairo_format_t; 2257 2258 cairo_public cairo_surface_t * 2259 cairo_image_surface_create (cairo_format_t format, 2260 int width, 2261 int height); 2262 2263 cairo_public int 2264 cairo_format_stride_for_width (cairo_format_t format, 2265 int width); 2266 2267 cairo_public cairo_surface_t * 2268 cairo_image_surface_create_for_data (unsigned char *data, 2269 cairo_format_t format, 2270 int width, 2271 int height, 2272 int stride); 2273 2274 cairo_public unsigned char * 2275 cairo_image_surface_get_data (cairo_surface_t *surface); 2276 2277 cairo_public cairo_format_t 2278 cairo_image_surface_get_format (cairo_surface_t *surface); 2279 2280 cairo_public int 2281 cairo_image_surface_get_width (cairo_surface_t *surface); 2282 2283 cairo_public int 2284 cairo_image_surface_get_height (cairo_surface_t *surface); 2285 2286 cairo_public int 2287 cairo_image_surface_get_stride (cairo_surface_t *surface); 2288 2289 #if CAIRO_HAS_PNG_FUNCTIONS 2290 2291 cairo_public cairo_surface_t * 2292 cairo_image_surface_create_from_png (const char *filename); 2293 2294 cairo_public cairo_surface_t * 2295 cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func, 2296 void *closure); 2297 2298 #endif 2299 2300 /* Recording-surface functions */ 2301 2302 cairo_public cairo_surface_t * 2303 cairo_recording_surface_create (cairo_content_t content, 2304 const cairo_rectangle_t *extents); 2305 2306 cairo_public void 2307 cairo_recording_surface_ink_extents (cairo_surface_t *surface, 2308 double *x0, 2309 double *y0, 2310 double *width, 2311 double *height); 2312 2313 /* Pattern creation functions */ 2314 2315 cairo_public cairo_pattern_t * 2316 cairo_pattern_create_rgb (double red, double green, double blue); 2317 2318 cairo_public cairo_pattern_t * 2319 cairo_pattern_create_rgba (double red, double green, double blue, 2320 double alpha); 2321 2322 cairo_public cairo_pattern_t * 2323 cairo_pattern_create_for_surface (cairo_surface_t *surface); 2324 2325 cairo_public cairo_pattern_t * 2326 cairo_pattern_create_linear (double x0, double y0, 2327 double x1, double y1); 2328 2329 cairo_public cairo_pattern_t * 2330 cairo_pattern_create_radial (double cx0, double cy0, double radius0, 2331 double cx1, double cy1, double radius1); 2332 2333 cairo_public cairo_pattern_t * 2334 cairo_pattern_reference (cairo_pattern_t *pattern); 2335 2336 cairo_public void 2337 cairo_pattern_destroy (cairo_pattern_t *pattern); 2338 2339 cairo_public unsigned int 2340 cairo_pattern_get_reference_count (cairo_pattern_t *pattern); 2341 2342 cairo_public cairo_status_t 2343 cairo_pattern_status (cairo_pattern_t *pattern); 2344 2345 cairo_public void * 2346 cairo_pattern_get_user_data (cairo_pattern_t *pattern, 2347 const cairo_user_data_key_t *key); 2348 2349 cairo_public cairo_status_t 2350 cairo_pattern_set_user_data (cairo_pattern_t *pattern, 2351 const cairo_user_data_key_t *key, 2352 void *user_data, 2353 cairo_destroy_func_t destroy); 2354 2355 /** 2356 * cairo_pattern_type_t: 2357 * @CAIRO_PATTERN_TYPE_SOLID: The pattern is a solid (uniform) 2358 * color. It may be opaque or translucent. 2359 * @CAIRO_PATTERN_TYPE_SURFACE: The pattern is a based on a surface (an image). 2360 * @CAIRO_PATTERN_TYPE_LINEAR: The pattern is a linear gradient. 2361 * @CAIRO_PATTERN_TYPE_RADIAL: The pattern is a radial gradient. 2362 * 2363 * #cairo_pattern_type_t is used to describe the type of a given pattern. 2364 * 2365 * The type of a pattern is determined by the function used to create 2366 * it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba() 2367 * functions create SOLID patterns. The remaining 2368 * cairo_pattern_create<!-- --> functions map to pattern types in obvious 2369 * ways. 2370 * 2371 * The pattern type can be queried with cairo_pattern_get_type() 2372 * 2373 * Most #cairo_pattern_t functions can be called with a pattern of any 2374 * type, (though trying to change the extend or filter for a solid 2375 * pattern will have no effect). A notable exception is 2376 * cairo_pattern_add_color_stop_rgb() and 2377 * cairo_pattern_add_color_stop_rgba() which must only be called with 2378 * gradient patterns (either LINEAR or RADIAL). Otherwise the pattern 2379 * will be shutdown and put into an error state. 2380 * 2381 * New entries may be added in future versions. 2382 * 2383 * Since: 1.2 2384 **/ 2385 typedef enum _cairo_pattern_type { 2386 CAIRO_PATTERN_TYPE_SOLID, 2387 CAIRO_PATTERN_TYPE_SURFACE, 2388 CAIRO_PATTERN_TYPE_LINEAR, 2389 CAIRO_PATTERN_TYPE_RADIAL 2390 } cairo_pattern_type_t; 2391 2392 cairo_public cairo_pattern_type_t 2393 cairo_pattern_get_type (cairo_pattern_t *pattern); 2394 2395 cairo_public void 2396 cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern, 2397 double offset, 2398 double red, double green, double blue); 2399 2400 cairo_public void 2401 cairo_pattern_add_color_stop_rgba (cairo_pattern_t *pattern, 2402 double offset, 2403 double red, double green, double blue, 2404 double alpha); 2405 2406 cairo_public void 2407 cairo_pattern_set_matrix (cairo_pattern_t *pattern, 2408 const cairo_matrix_t *matrix); 2409 2410 cairo_public void 2411 cairo_pattern_get_matrix (cairo_pattern_t *pattern, 2412 cairo_matrix_t *matrix); 2413 2414 /** 2415 * cairo_extend_t: 2416 * @CAIRO_EXTEND_NONE: pixels outside of the source pattern 2417 * are fully transparent 2418 * @CAIRO_EXTEND_REPEAT: the pattern is tiled by repeating 2419 * @CAIRO_EXTEND_REFLECT: the pattern is tiled by reflecting 2420 * at the edges (Implemented for surface patterns since 1.6) 2421 * @CAIRO_EXTEND_PAD: pixels outside of the pattern copy 2422 * the closest pixel from the source (Since 1.2; but only 2423 * implemented for surface patterns since 1.6) 2424 * 2425 * #cairo_extend_t is used to describe how pattern color/alpha will be 2426 * determined for areas "outside" the pattern's natural area, (for 2427 * example, outside the surface bounds or outside the gradient 2428 * geometry). 2429 * 2430 * The default extend mode is %CAIRO_EXTEND_NONE for surface patterns 2431 * and %CAIRO_EXTEND_PAD for gradient patterns. 2432 * 2433 * New entries may be added in future versions. 2434 **/ 2435 typedef enum _cairo_extend { 2436 CAIRO_EXTEND_NONE, 2437 CAIRO_EXTEND_REPEAT, 2438 CAIRO_EXTEND_REFLECT, 2439 CAIRO_EXTEND_PAD 2440 } cairo_extend_t; 2441 2442 cairo_public void 2443 cairo_pattern_set_extend (cairo_pattern_t *pattern, cairo_extend_t extend); 2444 2445 cairo_public cairo_extend_t 2446 cairo_pattern_get_extend (cairo_pattern_t *pattern); 2447 2448 /** 2449 * cairo_filter_t: 2450 * @CAIRO_FILTER_FAST: A high-performance filter, with quality similar 2451 * to %CAIRO_FILTER_NEAREST 2452 * @CAIRO_FILTER_GOOD: A reasonable-performance filter, with quality 2453 * similar to %CAIRO_FILTER_BILINEAR 2454 * @CAIRO_FILTER_BEST: The highest-quality available, performance may 2455 * not be suitable for interactive use. 2456 * @CAIRO_FILTER_NEAREST: Nearest-neighbor filtering 2457 * @CAIRO_FILTER_BILINEAR: Linear interpolation in two dimensions 2458 * @CAIRO_FILTER_GAUSSIAN: This filter value is currently 2459 * unimplemented, and should not be used in current code. 2460 * 2461 * #cairo_filter_t is used to indicate what filtering should be 2462 * applied when reading pixel values from patterns. See 2463 * cairo_pattern_set_source() for indicating the desired filter to be 2464 * used with a particular pattern. 2465 */ 2466 typedef enum _cairo_filter { 2467 CAIRO_FILTER_FAST, 2468 CAIRO_FILTER_GOOD, 2469 CAIRO_FILTER_BEST, 2470 CAIRO_FILTER_NEAREST, 2471 CAIRO_FILTER_BILINEAR, 2472 CAIRO_FILTER_GAUSSIAN 2473 } cairo_filter_t; 2474 2475 cairo_public void 2476 cairo_pattern_set_filter (cairo_pattern_t *pattern, cairo_filter_t filter); 2477 2478 cairo_public cairo_filter_t 2479 cairo_pattern_get_filter (cairo_pattern_t *pattern); 2480 2481 cairo_public cairo_status_t 2482 cairo_pattern_get_rgba (cairo_pattern_t *pattern, 2483 double *red, double *green, 2484 double *blue, double *alpha); 2485 2486 cairo_public cairo_status_t 2487 cairo_pattern_get_surface (cairo_pattern_t *pattern, 2488 cairo_surface_t **surface); 2489 2490 2491 cairo_public cairo_status_t 2492 cairo_pattern_get_color_stop_rgba (cairo_pattern_t *pattern, 2493 int index, double *offset, 2494 double *red, double *green, 2495 double *blue, double *alpha); 2496 2497 cairo_public cairo_status_t 2498 cairo_pattern_get_color_stop_count (cairo_pattern_t *pattern, 2499 int *count); 2500 2501 cairo_public cairo_status_t 2502 cairo_pattern_get_linear_points (cairo_pattern_t *pattern, 2503 double *x0, double *y0, 2504 double *x1, double *y1); 2505 2506 cairo_public cairo_status_t 2507 cairo_pattern_get_radial_circles (cairo_pattern_t *pattern, 2508 double *x0, double *y0, double *r0, 2509 double *x1, double *y1, double *r1); 2510 2511 /* Matrix functions */ 2512 2513 cairo_public void 2514 cairo_matrix_init (cairo_matrix_t *matrix, 2515 double xx, double yx, 2516 double xy, double yy, 2517 double x0, double y0); 2518 2519 cairo_public void 2520 cairo_matrix_init_identity (cairo_matrix_t *matrix); 2521 2522 cairo_public void 2523 cairo_matrix_init_translate (cairo_matrix_t *matrix, 2524 double tx, double ty); 2525 2526 cairo_public void 2527 cairo_matrix_init_scale (cairo_matrix_t *matrix, 2528 double sx, double sy); 2529 2530 cairo_public void 2531 cairo_matrix_init_rotate (cairo_matrix_t *matrix, 2532 double radians); 2533 2534 cairo_public void 2535 cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty); 2536 2537 cairo_public void 2538 cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy); 2539 2540 cairo_public void 2541 cairo_matrix_rotate (cairo_matrix_t *matrix, double radians); 2542 2543 cairo_public cairo_status_t 2544 cairo_matrix_invert (cairo_matrix_t *matrix); 2545 2546 cairo_public void 2547 cairo_matrix_multiply (cairo_matrix_t *result, 2548 const cairo_matrix_t *a, 2549 const cairo_matrix_t *b); 2550 2551 cairo_public void 2552 cairo_matrix_transform_distance (const cairo_matrix_t *matrix, 2553 double *dx, double *dy); 2554 2555 cairo_public void 2556 cairo_matrix_transform_point (const cairo_matrix_t *matrix, 2557 double *x, double *y); 2558 2559 /* Region functions */ 2560 2561 /** 2562 * cairo_region_t: 2563 * 2564 * A #cairo_region_t represents a set of integer-aligned rectangles. 2565 * 2566 * It allows set-theoretical operations like cairo_region_union() and 2567 * cairo_region_intersect() to be performed on them. 2568 * 2569 * Memory management of #cairo_region_t is done with 2570 * cairo_region_reference() and cairo_region_destroy(). 2571 * 2572 * Since: 1.10 2573 **/ 2574 typedef struct _cairo_region cairo_region_t; 2575 2576 /** 2577 * cairo_rectangle_int_t: 2578 * @x: X coordinate of the left side of the rectangle 2579 * @y: Y coordinate of the the top side of the rectangle 2580 * @width: width of the rectangle 2581 * @height: height of the rectangle 2582 * 2583 * A data structure for holding a rectangle with integer coordinates. 2584 * 2585 * Since: 1.10 2586 **/ 2587 2588 typedef struct _cairo_rectangle_int { 2589 int x, y; 2590 int width, height; 2591 } cairo_rectangle_int_t; 2592 2593 typedef enum _cairo_region_overlap { 2594 CAIRO_REGION_OVERLAP_IN, /* completely inside region */ 2595 CAIRO_REGION_OVERLAP_OUT, /* completely outside region */ 2596 CAIRO_REGION_OVERLAP_PART /* partly inside region */ 2597 } cairo_region_overlap_t; 2598 2599 cairo_public cairo_region_t * 2600 cairo_region_create (void); 2601 2602 cairo_public cairo_region_t * 2603 cairo_region_create_rectangle (const cairo_rectangle_int_t *rectangle); 2604 2605 cairo_public cairo_region_t * 2606 cairo_region_create_rectangles (const cairo_rectangle_int_t *rects, 2607 int count); 2608 2609 cairo_public cairo_region_t * 2610 cairo_region_copy (const cairo_region_t *original); 2611 2612 cairo_public cairo_region_t * 2613 cairo_region_reference (cairo_region_t *region); 2614 2615 cairo_public void 2616 cairo_region_destroy (cairo_region_t *region); 2617 2618 cairo_public cairo_bool_t 2619 cairo_region_equal (const cairo_region_t *a, const cairo_region_t *b); 2620 2621 cairo_public cairo_status_t 2622 cairo_region_status (const cairo_region_t *region); 2623 2624 cairo_public void 2625 cairo_region_get_extents (const cairo_region_t *region, 2626 cairo_rectangle_int_t *extents); 2627 2628 cairo_public int 2629 cairo_region_num_rectangles (const cairo_region_t *region); 2630 2631 cairo_public void 2632 cairo_region_get_rectangle (const cairo_region_t *region, 2633 int nth, 2634 cairo_rectangle_int_t *rectangle); 2635 2636 cairo_public cairo_bool_t 2637 cairo_region_is_empty (const cairo_region_t *region); 2638 2639 cairo_public cairo_region_overlap_t 2640 cairo_region_contains_rectangle (const cairo_region_t *region, 2641 const cairo_rectangle_int_t *rectangle); 2642 2643 cairo_public cairo_bool_t 2644 cairo_region_contains_point (const cairo_region_t *region, int x, int y); 2645 2646 cairo_public void 2647 cairo_region_translate (cairo_region_t *region, int dx, int dy); 2648 2649 cairo_public cairo_status_t 2650 cairo_region_subtract (cairo_region_t *dst, const cairo_region_t *other); 2651 2652 cairo_public cairo_status_t 2653 cairo_region_subtract_rectangle (cairo_region_t *dst, 2654 const cairo_rectangle_int_t *rectangle); 2655 2656 cairo_public cairo_status_t 2657 cairo_region_intersect (cairo_region_t *dst, const cairo_region_t *other); 2658 2659 cairo_public cairo_status_t 2660 cairo_region_intersect_rectangle (cairo_region_t *dst, 2661 const cairo_rectangle_int_t *rectangle); 2662 2663 cairo_public cairo_status_t 2664 cairo_region_union (cairo_region_t *dst, const cairo_region_t *other); 2665 2666 cairo_public cairo_status_t 2667 cairo_region_union_rectangle (cairo_region_t *dst, 2668 const cairo_rectangle_int_t *rectangle); 2669 2670 cairo_public cairo_status_t 2671 cairo_region_xor (cairo_region_t *dst, const cairo_region_t *other); 2672 2673 cairo_public cairo_status_t 2674 cairo_region_xor_rectangle (cairo_region_t *dst, 2675 const cairo_rectangle_int_t *rectangle); 2676 2677 /* Functions to be used while debugging (not intended for use in production code) */ 2678 cairo_public void 2679 cairo_debug_reset_static_data (void); 2680 2681 2682 CAIRO_END_DECLS 2683 2684 #endif /* CAIRO_H */ 2685