1.. _patterns: 2 3******** 4Patterns 5******** 6 7.. currentmodule:: cairo 8 9 10Patterns are the paint with which cairo draws. The primary use of patterns is 11as the source for all cairo drawing operations, although they can also be used 12as masks, that is, as the brush too. 13 14A cairo *Pattern* is created by using one of the *PatternType* constructors 15listed below, or implicitly through *Context.set_source_<type>()* methods. 16 17 18class Pattern() 19=============== 20 21*Pattern* is the abstract base class from which all the other pattern classes 22derive. It cannot be instantiated directly. 23 24.. class:: Pattern() 25 26 .. method:: get_extend() 27 28 :returns: the current extend strategy used for drawing the *Pattern*. 29 :rtype: cairo.Extend 30 31 Gets the current extend mode for the *Pattern*. See 32 :class:`cairo.Extend` attributes for details on the semantics of each 33 extend strategy. 34 35 .. method:: get_matrix() 36 37 :returns: a new :class:`Matrix` which stores a copy of the *Pattern's* transformation matrix 38 39 .. method:: get_filter() 40 41 :returns: the current filter used for 42 resizing the pattern. 43 :rtype: cairo.Filter 44 45 .. versionadded:: 1.12.0 46 47 Used to be a method of :class:`SurfacePattern` before 48 49 .. method:: set_filter(filter) 50 51 :param cairo.Filter filter: a filter describing the filter 52 to use for resizing the pattern 53 54 Note that you might want to control filtering even when you do not have 55 an explicit *Pattern* object, (for example when using 56 :meth:`Context.set_source_surface`). In these cases, it is convenient to 57 use :meth:`Context.get_source` to get access to the pattern that cairo 58 creates implicitly. For example:: 59 60 context.set_source_surface(image, x, y) 61 surfacepattern.set_filter(context.get_source(), cairo.FILTER_NEAREST) 62 63 .. versionadded:: 1.12.0 64 65 Used to be a method of :class:`SurfacePattern` before 66 67 .. method:: set_extend(extend) 68 69 :param cairo.Extend extend: an extend describing how the 70 area outside of the *Pattern* will be drawn 71 72 Sets the mode to be used for drawing outside the area of a *Pattern*. 73 74 The default extend mode is :attr:`cairo.Extend.NONE` for 75 :class:`SurfacePattern` and :attr:`cairo.Extend.PAD` for 76 :class:`Gradient` Patterns. 77 78 .. method:: set_matrix(matrix) 79 80 :param matrix: a :class:`Matrix` 81 82 Sets the *Pattern's* transformation matrix to *matrix*. This matrix is a 83 transformation from user space to pattern space. 84 85 When a *Pattern* is first created it always has the identity matrix for 86 its transformation matrix, which means that pattern space is initially 87 identical to user space. 88 89 Important: Please note that the direction of this transformation matrix 90 is from user space to pattern space. This means that if you imagine the 91 flow from a *Pattern* to user space (and on to device space), then 92 coordinates in that flow will be transformed by the inverse of the 93 *Pattern* matrix. 94 95 For example, if you want to make a *Pattern* appear twice as large as it 96 does by default the correct code to use is:: 97 98 matrix = cairo.Matrix(xx=0.5,yy=0.5) 99 pattern.set_matrix(matrix) 100 101 Meanwhile, using values of 2.0 rather than 0.5 in the code above would 102 cause the *Pattern* to appear at half of its default size. 103 104 Also, please note the discussion of the user-space locking semantics of 105 :class:`Context.set_source`. 106 107 108class SolidPattern(:class:`Pattern`) 109==================================== 110 111.. class:: SolidPattern(red, green, blue, alpha=1.0) 112 113 :param red: red component of the color 114 :type red: float 115 :param green: green component of the color 116 :type green: float 117 :param blue: blue component of the color 118 :type blue: float 119 :param alpha: alpha component of the color 120 :type alpha: float 121 :returns: a new *SolidPattern* 122 :raises: :exc:`MemoryError` in case of no memory 123 124 Creates a new *SolidPattern* corresponding to a translucent color. The 125 color components are floating point numbers in the range 0 to 1. If the 126 values passed in are outside that range, they will be clamped. 127 128 129 .. method:: get_rgba() 130 131 :returns: (red, green, blue, alpha) a tuple of float 132 133 Gets the solid color for a *SolidPattern*. 134 135 .. versionadded:: 1.4 136 137 138class SurfacePattern(:class:`Pattern`) 139====================================== 140 141.. class:: SurfacePattern(surface) 142 143 :param surface: a cairo :class:`Surface` 144 :returns: a newly created *SurfacePattern* for the given surface. 145 :raises: :exc:`MemoryError` in case of no memory. 146 147 .. method:: get_surface() 148 149 :returns: the :class:`Surface` of the *SurfacePattern*. 150 151 .. versionadded:: 1.4 152 153 154class Gradient(:class:`Pattern`) 155================================ 156 157*Gradient* is an abstract base class from which other *Pattern* classes 158derive. It cannot be instantiated directly. 159 160.. class:: Gradient() 161 162 .. method:: add_color_stop_rgb(offset, red, green, blue) 163 164 :param offset: an offset in the range [0.0 .. 1.0] 165 :type offset: float 166 :param red: red component of color 167 :type red: float 168 :param green: green component of color 169 :type green: float 170 :param blue: blue component of color 171 :type blue: float 172 173 Adds an opaque color stop to a *Gradient* pattern. The offset specifies 174 the location along the gradient's control vector. For example, a 175 *LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a 176 *RadialGradient's* control vector is from any point on the start circle 177 to the corresponding point on the end circle. 178 179 The color is specified in the same way as in :meth:`Context.set_source_rgb`. 180 181 If two (or more) stops are specified with identical offset values, they 182 will be sorted according to the order in which the stops are added, 183 (stops added earlier will compare less than stops added later). This can 184 be useful for reliably making sharp color transitions instead of the 185 typical blend. 186 187 .. method:: add_color_stop_rgba(offset, red, green, blue, alpha) 188 189 :param offset: an offset in the range [0.0 .. 1.0] 190 :type offset: float 191 :param red: red component of color 192 :type red: float 193 :param green: green component of color 194 :type green: float 195 :param blue: blue component of color 196 :type blue: float 197 :param alpha: alpha component of color 198 :type alpha: float 199 200 Adds an opaque color stop to a *Gradient* pattern. The offset specifies 201 the location along the gradient's control vector. For example, a 202 *LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a 203 *RadialGradient's* control vector is from any point on the start circle 204 to the corresponding point on the end circle. 205 206 The color is specified in the same way as in :meth:`Context.set_source_rgb`. 207 208 If two (or more) stops are specified with identical offset values, they 209 will be sorted according to the order in which the stops are added, 210 (stops added earlier will compare less than stops added later). This can 211 be useful for reliably making sharp color transitions instead of the 212 typical blend. 213 214 .. method:: get_color_stops_rgba() 215 216 :returns: a list of (offset, red, green, blue, alpha) tuples of float 217 :rtype: list 218 219 Gets the color and offset information for all color stops specified in 220 the given gradient pattern. 221 222 .. versionadded:: 1.14 223 224 225class LinearGradient(:class:`Gradient`) 226======================================= 227.. class:: LinearGradient(x0, y0, x1, y1) 228 229 :param x0: x coordinate of the start point 230 :type x0: float 231 :param y0: y coordinate of the start point 232 :type y0: float 233 :param x1: x coordinate of the end point 234 :type x1: float 235 :param y1: y coordinate of the end point 236 :type y1: float 237 :returns: a new *LinearGradient* 238 :raises: :exc:`MemoryError` in case of no memory 239 240 Create a new *LinearGradient* along the line defined by (x0, y0) and (x1, 241 y1). Before using the *Gradient* pattern, a number of color stops should 242 be defined using :meth:`Gradient.add_color_stop_rgb` or 243 :meth:`Gradient.add_color_stop_rgba` 244 245 Note: The coordinates here are in pattern space. For a new *Pattern*, 246 pattern space is identical to user space, but the relationship between the 247 spaces can be changed with :meth:`Pattern.set_matrix` 248 249 .. method:: get_linear_points() 250 251 :returns: (x0, y0, x1, y1) - a tuple of float 252 253 * x0: return value for the x coordinate of the first point 254 * y0: return value for the y coordinate of the first point 255 * x1: return value for the x coordinate of the second point 256 * y1: return value for the y coordinate of the second point 257 258 Gets the gradient endpoints for a *LinearGradient*. 259 260 .. versionadded:: 1.4 261 262 263class RadialGradient(:class:`Gradient`) 264======================================= 265.. class:: RadialGradient(cx0, cy0, radius0, cx1, cy1, radius1) 266 267 :param cx0: x coordinate for the center of the start circle 268 :type cx0: float 269 :param cy0: y coordinate for the center of the start circle 270 :type cy0: float 271 :param radius0: radius of the start circle 272 :type radius0: float 273 :param cx1: x coordinate for the center of the end circle 274 :type cx1: float 275 :param cy1: y coordinate for the center of the end circle 276 :type cy1: float 277 :param radius1: radius of the end circle 278 :type radius1: float 279 :returns: the newly created *RadialGradient* 280 :raises: :exc:`MemoryError` in case of no memory 281 282 Creates a new *RadialGradient* pattern between the two circles defined by 283 (cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the gradient 284 pattern, a number of color stops should be defined using 285 :meth:`Gradient.add_color_stop_rgb` or :meth:`Gradient.add_color_stop_rgba`. 286 287 Note: The coordinates here are in pattern space. For a new pattern, pattern 288 space is identical to user space, but the relationship between the spaces 289 can be changed with :meth:`Pattern.set_matrix`. 290 291 .. method:: get_radial_circles() 292 293 :returns: (x0, y0, r0, x1, y1, r1) - a tuple of float 294 295 * x0: return value for the x coordinate of the center of the first circle 296 * y0: return value for the y coordinate of the center of the first circle 297 * r0: return value for the radius of the first circle 298 * x1: return value for the x coordinate of the center of the second circle 299 * y1: return value for the y coordinate of the center of the second circle 300 * r1: return value for the radius of the second circle 301 302 Gets the *Gradient* endpoint circles for a *RadialGradient*, each 303 specified as a center coordinate and a radius. 304 305 .. versionadded:: 1.4 306 307 308class MeshPattern(:class:`Pattern`) 309=================================== 310 311.. class:: MeshPattern() 312 313 :raises Error: 314 :rtype: MeshPattern 315 316 .. versionadded:: 1.14 317 318 Create a new mesh pattern. 319 320 Mesh patterns are tensor-product patch meshes (type 7 shadings in PDF). 321 Mesh patterns may also be used to create other types of shadings that are 322 special cases of tensor-product patch meshes such as Coons patch meshes 323 (type 6 shading in PDF) and Gouraud-shaded triangle meshes (type 4 and 5 324 shadings in PDF). 325 326 Mesh patterns consist of one or more tensor-product patches, which should 327 be defined before using the mesh pattern. Using a mesh pattern with a 328 partially defined patch as source or mask will put the context in an error 329 status with a status of :attr:`cairo.Status.INVALID_MESH_CONSTRUCTION`. 330 331 A tensor-product patch is defined by 4 Bézier curves (side 0, 1, 2, 3) and 332 by 4 additional control points (P0, P1, P2, P3) that provide further 333 control over the patch and complete the definition of the tensor-product 334 patch. The corner C0 is the first point of the patch. 335 336 Degenerate sides are permitted so straight lines may be used. A zero 337 length line on one side may be used to create 3 sided patches. 338 339 :: 340 341 C1 Side 1 C2 342 +---------------+ 343 | | 344 | P1 P2 | 345 | | 346 Side 0 | | Side 2 347 | | 348 | | 349 | P0 P3 | 350 | | 351 +---------------+ 352 C0 Side 3 C3 353 354 Each patch is constructed by first calling :meth:`begin_patch`, then 355 :meth:`move_to` to specify the first point in the patch (C0). Then the 356 sides are specified with calls to :meth:`curve_to` and :meth:`line_to`. 357 358 The four additional control points (P0, P1, P2, P3) in a patch can be 359 specified with :meth:`set_control_point`. 360 361 At each corner of the patch (C0, C1, C2, C3) a color may be specified with 362 :meth:`set_corner_color_rgb` or :meth:`set_corner_color_rgba`. Any corner 363 whose color is not explicitly specified defaults to transparent black. 364 365 A Coons patch is a special case of the tensor-product patch where the 366 control points are implicitly defined by the sides of the patch. The 367 default value for any control point not specified is the implicit value 368 for a Coons patch, i.e. if no control points are specified the patch is a 369 Coons patch. 370 371 A triangle is a special case of the tensor-product patch where the control 372 points are implicitly defined by the sides of the patch, all the sides are 373 lines and one of them has length 0, i.e. if the patch is specified using 374 just 3 lines, it is a triangle. If the corners connected by the 0-length 375 side have the same color, the patch is a Gouraud-shaded triangle. 376 377 Patches may be oriented differently to the above diagram. For example the 378 first point could be at the top left. The diagram only shows the 379 relationship between the sides, corners and control points. Regardless of 380 where the first point is located, when specifying colors, corner 0 will 381 always be the first point, corner 1 the point between side 0 and side 1 382 etc. 383 384 Calling :meth:`end_patch` completes the current patch. If less than 4 385 sides have been defined, the first missing side is defined as a line from 386 the current point to the first point of the patch (C0) and the other sides 387 are degenerate lines from C0 to C0. The corners between the added sides 388 will all be coincident with C0 of the patch and their color will be set to 389 be the same as the color of C0. 390 391 Additional patches may be added with additional calls to 392 :meth:`begin_patch`/:meth:`end_patch`. 393 394 :: 395 396 # Add a Coons patch 397 pattern = cairo.MeshPattern() 398 pattern.begin_patch() 399 pattern.move_to(0, 0) 400 pattern.curve_to(30, -30, 60, 30, 100, 0) 401 pattern.curve_to(60, 30, 130, 60, 100, 100) 402 pattern.curve_to(60, 70, 30, 130, 0, 100) 403 pattern.curve_to(30, 70, -30, 30, 0, 0) 404 pattern.set_corner_color_rgb(0, 1, 0, 0) 405 pattern.set_corner_color_rgb(1, 0, 1, 0) 406 pattern.set_corner_color_rgb(2, 0, 0, 1) 407 pattern.set_corner_color_rgb(3, 1, 1, 0) 408 pattern.end_patch() 409 410 # Add a Gouraud-shaded triangle 411 pattern = cairo.MeshPattern() 412 pattern.begin_patch() 413 pattern.move_to(100, 100) 414 pattern.line_to(130, 130) 415 pattern.line_to(130, 70) 416 pattern.set_corner_color_rgb(0, 1, 0, 0) 417 pattern.set_corner_color_rgb(1, 0, 1, 0) 418 pattern.set_corner_color_rgb(2, 0, 0, 1) 419 pattern.end_patch() 420 421 When two patches overlap, the last one that has been added is drawn over 422 the first one. 423 424 When a patch folds over itself, points are sorted depending on their 425 parameter coordinates inside the patch. The v coordinate ranges from 0 to 426 1 when moving from side 3 to side 1; the u coordinate ranges from 0 to 1 427 when going from side 0 to side 428 429 Points with higher v coordinate hide points with lower v coordinate. When 430 two points have the same v coordinate, the one with higher u coordinate is 431 above. This means that points nearer to side 1 are above points nearer to 432 side 3; when this is not sufficient to decide which point is above (for 433 example when both points belong to side 1 or side 3) points nearer to side 434 2 are above points nearer to side 0. 435 436 For a complete definition of tensor-product patches, see the PDF 437 specification (ISO32000), which describes the parametrization in detail. 438 439 Note: The coordinates are always in pattern space. For a new pattern, 440 pattern space is identical to user space, but the relationship between the 441 spaces can be changed with :meth:`Pattern.set_matrix`. 442 443 .. method:: begin_patch() 444 445 :raises Error: 446 447 Begin a patch in a mesh pattern. 448 449 After calling this function, the patch shape should be defined with 450 :meth:`move_to`, :meth:`line_to` and :meth:`curve_to`. 451 452 After defining the patch, :meth:`end_patch` must be called before 453 using pattern as a source or mask. 454 455 .. method:: curve_to(x1, y1, x2, y2, x3, y3) 456 457 :param float x1: the X coordinate of the first control point 458 :param float y1: the Y coordinate of the first control point 459 :param float x2: the X coordinate of the second control point 460 :param float y2: the Y coordinate of the second control point 461 :param float x3: the X coordinate of the end of the curve 462 :param float y3: the Y coordinate of the end of the curve 463 :raises Error: 464 465 Adds a cubic Bézier spline to the current patch from the current point 466 to position (x3 , y3 ) in pattern-space coordinates, using (x1 , y1 ) 467 and (x2 , y2 ) as the control points. 468 469 If the current patch has no current point before the call to 470 :meth:`curve_to`, this function will behave as if 471 preceded by a call to ``pattern.move_to(x1, y1)``. 472 473 After this call the current point will be (x3 , y3 ). 474 475 .. method:: end_patch() 476 477 :raises Error: 478 479 Indicates the end of the current patch in a mesh pattern. 480 481 If the current patch has less than 4 sides, it is closed with a 482 straight line from the current point to the first point of the patch 483 as if :meth:`line_to` was used. 484 485 .. method:: get_control_point(patch_num, point_num) 486 487 :param int patch_num: the patch number to return data for 488 :param int point_num: he control point number to return data for 489 :returns: a (x, y) tuple of float - coordinates of the control point 490 :rtype: tuple 491 :raises Error: 492 493 Gets the control point point_num of patch patch_num for a mesh 494 pattern. 495 496 ``patch_num`` can range from 0 to n-1 where n is the number returned 497 by :meth:`get_patch_count`. 498 499 Valid values for ``point_num`` are from 0 to 3 and identify the control 500 points as explained in :class:`MeshPattern`. 501 502 .. method:: get_corner_color_rgba(patch_num, corner_num) 503 504 :param int patch_num: the patch number to return data for 505 :param int corner_num: the corner number to return data for 506 :returns: a (red, green, blue, alpha) tuple of float 507 :rtype: tuple 508 :raises Error: 509 510 Gets the color information in corner ``corner_num`` of patch 511 ``patch_num`` for a mesh pattern. 512 513 ``patch_num`` can range from 0 to n-1 where n is the number returned 514 by :meth:`get_patch_count`. 515 516 Valid values for ``corner_num`` are from 0 to 3 and identify the 517 corners as explained in :class:`MeshPattern`. 518 519 .. method:: get_patch_count() 520 521 :returns: number of patches 522 :rtype: int 523 524 Gets the number of patches specified in the given mesh pattern. 525 526 The number only includes patches which have been finished by calling 527 :meth:`end_patch`. For example it will be 0 during the definition of 528 the first patch. 529 530 .. method:: get_path(patch_num) 531 532 :param int patch_num: the patch number to return data for 533 :returns: the path defining the patch 534 :rtype: Path 535 :raises Error: 536 537 Gets path defining the patch ``patch_num`` for a mesh pattern. 538 539 ``patch_num`` can range from 0 to n-1 where n is the number returned 540 by :meth:`get_patch_count`. 541 542 .. method:: line_to(x, y) 543 544 :param float x: the X coordinate of the end of the new line 545 :param float y: the Y coordinate of the end of the new line 546 :raises Error: 547 548 Adds a line to the current patch from the current point to position (x 549 , y ) in pattern-space coordinates. 550 551 If there is no current point before the call to :meth:`line_to` this 552 function will behave as ``pattern.move_to(x ,y)``. 553 554 After this call the current point will be (x , y ). 555 556 .. method:: move_to(x, y) 557 558 :param float x: the X coordinate of the new position 559 :param float y: the Y coordinate of the new position 560 :raises Error: 561 562 Define the first point of the current patch in a mesh pattern. 563 564 After this call the current point will be (x , y ). 565 566 .. method:: set_control_point(point_num, x, y) 567 568 :param int point_num: the control point to set the position for 569 :param float x: the X coordinate of the control point 570 :param float y: the Y coordinate of the control point 571 :raises Error: 572 573 Set an internal control point of the current patch. 574 575 Valid values for point_num are from 0 to 3 and identify the control 576 points as explained in :class:`MeshPattern`. 577 578 .. method:: set_corner_color_rgb(corner_num, red, green, blue) 579 580 :param int corner_num: the corner to set the color for 581 :param float red: red component of color 582 :param float green: green component of color 583 :param float blue: blue component of color 584 :raises Error: 585 586 Sets the color of a corner of the current patch in a mesh pattern. 587 588 The color is specified in the same way as in 589 :meth:`Context.set_source_rgb`. 590 591 Valid values for corner_num are from 0 to 3 and identify the corners 592 as explained in :class:`MeshPattern`. 593 594 .. method:: set_corner_color_rgba(corner_num, red, green, blue, alpha) 595 596 :param int corner_num: the corner to set the color for 597 :param float red: red component of color 598 :param float green: green component of color 599 :param float blue: blue component of color 600 :param float alpha: alpha component of color 601 :raises Error: 602 603 Sets the color of a corner of the current patch in a mesh pattern. 604 605 The color is specified in the same way as in 606 :meth:`Context.set_source_rgba`. 607 608 Valid values for corner_num are from 0 to 3 and identify the corners 609 as explained in :class:`MeshPattern`. 610 611 612class RasterSourcePattern(:class:`Pattern`) 613=========================================== 614 615The raster source provides the ability to supply arbitrary pixel data whilst 616rendering. The pixels are queried at the time of rasterisation by means of 617user callback functions, allowing for the ultimate flexibility. For example, 618in handling compressed image sources, you may keep a MRU cache of decompressed 619images and decompress sources on the fly and discard old ones to conserve 620memory. 621 622For the raster source to be effective, you must at least specify the acquire 623and release callbacks which are used to retrieve the pixel data for the region 624of interest and demark when it can be freed afterwards. Other callbacks are 625provided for when the pattern is copied temporarily during rasterisation, or 626more permanently as a snapshot in order to keep the pixel data available for 627printing. 628 629 630.. class:: RasterSourcePattern(content, width, height) 631 632 :param Content content: 633 content type for the pixel data that will be returned. Knowing the 634 content type ahead of time is used for analysing the operation and 635 picking the appropriate rendering path. 636 :param int width: 637 maximum size of the sample area 638 :param int height: 639 maximum size of the sample area 640 :raises Error: 641 :rtype: RasterSourcePattern 642 643 Creates a new user pattern for providing pixel data. 644 645 Use the setter functions to associate callbacks with the returned pattern. 646 647 .. versionadded:: 1.15 648 649 .. method:: set_acquire(acquire, release) 650 651 :param acquire: 652 acquire callback or :obj:`None` to unset it 653 :type acquire: :obj:`callable` 654 :param release: 655 (optional) release callback or :obj:`None` 656 :type release: :obj:`callable` 657 :raises Error: 658 659 Specifies the callbacks used to generate the image surface for a 660 rendering operation (acquire) and the function used to cleanup that 661 surface afterwards. 662 663 The acquire callback should create a surface (preferably an image 664 surface created to match the target using 665 :meth:`Surface.create_similar_image`) that defines at least the region 666 of interest specified by extents. The surface is allowed to be the 667 entire sample area, but if it does contain a subsection of the sample 668 area, the surface extents should be provided by setting the device 669 offset (along with its width and height) using 670 :meth:`Surface.set_device_offset`. 671 672 .. function:: acquire(target, extents) 673 674 :param Surface target: 675 the rendering target surface 676 :param RectangleInt extents: 677 rectangular region of interest in pixels in sample space 678 :rtype: Surface 679 680 This function is called when a pattern is being rendered from. It 681 should create a surface that provides the pixel data for the 682 region of interest as defined by extents, though the surface 683 itself does not have to be limited to that area. For convenience 684 the surface should probably be of image type, created with 685 :meth:`Surface.create_similar_image` for the target (which enables 686 the number of copies to be reduced during transfer to the device). 687 Another option, might be to return a similar surface to the target 688 for explicit handling by the application of a set of cached 689 sources on the device. The region of sample data provided should 690 be defined using :meth:`Surface.set_device_offset` to specify the 691 top-left corner of the sample data (along with width and height of 692 the surface). 693 694 .. function:: release(surface) 695 696 :param Surface surface: 697 the surface created during acquire 698 699 This function is called when the pixel data is no longer being 700 accessed by the pattern for the rendering operation. 701 702 .. versionadded:: 1.15 703 704 .. method:: get_acquire() 705 706 :returns: a (acquire, release) tuple of callables or None as set 707 through :meth:`set_acquire` 708 709 Queries the current acquire and release callbacks. 710 711 .. versionadded:: 1.15 712