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