### ----------------------------------------------------
### -- Gnome::Gtk3
### -- Licenses: Artistic-2.0
### -- Authors: Marcel Timmerman
### -- File: docs/content-docs/reference/Cairo/Cairo.md
### ----------------------------------------------------
### -- Chunk 2 of 2
 original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface.

Note that code meant to be reusable should not call `reset-clip()` as it will cause results unexpected by higher-level code which calls `clip()`. Consider using `save()` and `restore()` around `clip()` as a more robust means of temporarily restricting the clip region.

    method reset-clip ( )

restore
-------

Restores this context to the state saved by a preceding call to `save()` and removes that state from the stack of saved states.

    method restore ( )

rotate
------

Modifies the current transformation matrix (CTM) by rotating the user-space axes by *$angle* radians. The rotation of the axes takes place after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis.

    method rotate ( Num() $angle )

  * $angle; Angle to rotate in radians

save
----

Makes a copy of the current state of this context and saves it on an internal stack of saved states for this context. When `restore()` is called, this context will be restored to the saved state.

Multiple calls to `save()` and `restore()` can be nested; each call to `restore()` restores the state from the matching paired `save()`.

    method save ( )

scale
-----

Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by *sx* and *sy* respectively. The scaling of the axes takes place after any existing transformation of user space.

    method scale ( Num() $sx, Num() $sy )

  * $sx; scale factor for the X dimension

  * $sy; scale factor for the Y dimension

select-font-face
----------------

Note: The `select-font-face()` function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications.

Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a "toy", remember), but the standard CSS2 generic family names, ("serif", "sans-serif", "cursive", "fantasy", "monospace"), are likely to work as expected.

If *$family* starts with the string "`cairo:`", or if no native font backends are compiled in, cairo will use an internal font family. The internal font family recognizes many modifiers in the *$family* string, most notably, it recognizes the string "monospace". That is, the family name "*cairo*:monospace" will use the monospace version of the internal font family.

It is expected that most applications will need to use a more comprehensive font handling and text layout library, (for example, pango), in conjunction with cairo.

If text is drawn without a call to `select-font-face()`, (nor `set-font-face()` nor `set-scaled-font()`), the default family is platform-specific, but is essentially "sans-serif". Default slant is `CAIRO_FONT_SLANT_NORMAL`, and default weight is `CAIRO_FONT_WEIGHT_NORMAL`.

    method select-font-face (
      Str $family, cairo_font_slant_t $slant,
      cairo_font_weight_t $weight
    )

  * $family; a font family name, encoded in UTF-8

  * $slant; the slant for the font

  * $weight; the weight for the font

set-antialias
-------------

Set the antialiasing mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value.

At the current time, no backend supports `CAIRO_ANTIALIAS_SUBPIXEL` when drawing shapes.

Note that this option does not affect text rendering, instead see `font-options-set-antialias()`.

    method set-antialias ( cairo_antialias_t $antialias )

  * $antialias; the new antialiasing mode

set-dash
--------

Sets the dash pattern to be used by `stroke()`. A dash pattern is specified by *$dashes*, an array of positive values. Each value provides the length of alternate "on" and "off" portions of the stroke. The *$offset* specifies an offset into the pattern at which the stroke begins.

Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with `CAIRO_LINE_CAP_ROUND` or `CAIRO_LINE_CAP_SQUARE` in order to distributed dots or squares along a path.

Note: The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of `set-dash()`. If *$num_dashes* is 0 dashing is disabled. If *num_dashes* is 1 a symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in *$dashes*.

If any value in *$dashes* is negative, or if all values are 0, then this context will be put into an error state with a status of `CAIRO_STATUS_INVALID_DASH`.

    method set-dash ( Array $dashes, Num() $offset )

  * $dashes; an array specifying alternate lengths of on and off stroke portions

  * $offset; an offset into the dash pattern at which the stroke should start

set-fill-rule
-------------

Set the current fill rule within the cairo context. The fill rule is used to determine which regions are inside or outside a complex (potentially self-intersecting) path. The current fill rule affects both `fill()` and `clip()`. See **cairo_fill_rule_t** for details on the semantics of each available fill rule.

The default fill rule is `CAIRO_FILL_RULE_WINDING`.

    method set-fill-rule ( cairo_fill_rule_t $fill_rule )

  * $fill_rule; a fill rule type

set-font-face
-------------

Replaces the current **cairo_font_face_t** object in the **cairo_t** with *font_face*. The replaced font face in the **cairo_t** will be destroyed if there are no other references to it.

    method set-font-face ( cairo_font_face_t $font_face )

  * $font_face; a **font-face-t**, or `Any` to restore to the default font

set-font-matrix
---------------

Sets the current font matrix to *matrix*. The font matrix gives a transformation from the design space of the font (in this space, the em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is used (see `set-font-size()`), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes

    method set-font-matrix ( cairo_matrix_t $matrix )

  * $matrix; a **matrix-t** describing a transform to be applied to the current font.

set-font-options
----------------

Sets a set of custom font rendering options for the **cairo_t**. Rendering options are derived by merging these options with the options derived from underlying surface; if the value in *options* has a default value (like `CAIRO_ANTIALIAS_DEFAULT`), then the value from the surface is used.

    method set-font-options ( cairo_font_options_t $options )

  * $options; font options to use

set-font-size
-------------

Sets the current font matrix to a scale by a factor of *size*, replacing any font matrix previously set with `set-font-size()` or `set-font-matrix()`. This results in a font size of *size* user space units. (More precisely, this matrix will result in the font's em-square being a *$size* by *$size* square in user space.)

If text is drawn without a call to `set-font-size()`, (nor `set-font-matrix()` nor `cset-scaled-font()`), the default font size is 10.0.

    method set-font-size ( Num() $size )

  * $size; The size of the current font

set-line-cap
------------

Sets the current line cap style within the cairo context. See **cairo_line_cap_t** for details about how the available line cap styles are drawn. As with the other stroke parameters, the current line cap style is examined by `stroke()`, `stroke-extents()`, and `stroke-to-path()`, but does not have any effect during path construction. The default line cap style is `CAIRO_LINE_CAP_BUTT`.

    method set-line-cap ( Int $line_cap )

  * $line_cap; a line cap style

set-line-join
-------------

Sets the current line join style within the cairo context. See **cairo_line_join_t** for details about how the available line join styles are drawn. As with the other stroke parameters, the current line join style is examined by `stroke()`, `stroke-extents()`, and `stroke-to-path()`, but does not have any effect during path construction. The default line join style is `CAIRO_LINE_JOIN_MITER`.

    method set-line-join ( Int $line_join )

  * $line_join; a line join style

set-line-width
--------------

Sets the current line width within the cairo context. The line width value specifies the diameter of a pen that is circular in user space, (though device-space pen may be an ellipse in general due to scaling/shear/rotation of the CTM).

Note: When the description above refers to user space and CTM it refers to the user space and CTM in effect at the time of the stroking operation, not the user space and CTM in effect at the time of the call to `set-line-width()`. The simplest usage makes both of these spaces identical. That is, if there is no change to the CTM between a call to `set-line-width()` and the stroking operation, then one can just pass user-space values to `set-line-width()` and ignore this note.

As with the other stroke parameters, the current line width is examined by `stroke()`, `stroke-extents()`, and `stroke-to-path()`, but does not have any effect during path construction.

The default line width value is 2.0.

    method set-line-width ( Num() $width )

  * $width; a line width

set-matrix
----------

Modifies the current transformation matrix (CTM) by setting it equal to *matrix*.

    method set-matrix ( cairo_matrix_t $matrix )

  * $matrix; a transformation matrix from user space to device space

set-miter-limit
---------------

Sets the current miter limit within the cairo context.

If the current line join style is set to `CAIRO_LINE_JOIN_MITER` (see `set-line-join()`), the miter limit is used to determine whether the lines should be joined with a bevel instead of a miter. Cairo divides the length of the miter by the line width. If the result is greater than the miter limit, the style is converted to a bevel.

As with the other stroke parameters, the current line miter limit is examined by `stroke()`, `stroke-extents()`, and `stroke-to-path()`, but does not have any effect during path construction.

The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 degrees.

A miter limit for a desired angle can be computed as: `miter limit = 1/sin(angle/2)`.

    method set-miter-limit ( Num() $limit )

  * $limit; a cairo context

set-operator
------------

Sets the compositing operator to be used for all drawing operations. See **cairo_operator_t** for details on the semantics of each available compositing operator.

The default operator is `CAIRO_OPERATOR_OVER`.

    method set-operator ( cairo_operator_t $op )

  * $op; a compositing operator

set-scaled-font
---------------

Replaces the current font face, font matrix, and font options in the **cairo_t** with those of the **cairo_scaled_font_t**. Except for some translation, the current CTM of the **cairo_t** should be the same as that of the **cairo_scaled_font_t**, which can be accessed using `scaled-font-get-ctm()`.

    method set-scaled-font ( cairo_scaled_font_t $scaled_font )

  * $scaled_font; a scaled font

set-source
----------

Sets the source pattern within this context to *source*. This pattern will then be used for any subsequent drawing operation until a new source pattern is set.

Note: The pattern's transformation matrix will be locked to the user space in effect at the time of `set-source()`. This means that further modifications of the current transformation matrix will not affect the source pattern. See `pattern-set-matrix()`.

The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to `set-source-rgb( 0.0, 0.0, 0.0))`.

    method set-source ( cairo_pattern_t $source )

  * $source; a pattern type to be used as the source for subsequent drawing operations.

set-source-pixbuf
-----------------

Sets the given pixbuf as the source pattern for this context.

The image is aligned so that the origin of the *$pixbuf* is `($x, $y)`.

    method set-source-pixbuf( $pixbuf is copy, Num() $x, Num() $y ) {

  * $pixbuf; The pixel buffer

  * $x; x origin

  * $y; y origin

set-source-rgb
--------------

Sets the source pattern within this context to an opaque color. This opaque color will then be used for any subsequent drawing operation until a new source pattern is set.

The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

The default source pattern is opaque black, (that is, it is equivalent to `set-source-rgb( 0.0, 0.0, 0.0)`).

    method set-source-rgb ( Num() $red, Num() $green, Num() $blue )

  * $red; red component of color

  * $green; green component of color

  * $blue; blue component of color

set-source-rgba
---------------

Sets the source pattern within this context to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set.

The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

The default source pattern is opaque black, (that is, it is equivalent to `set-source-rgba( 0.0, 0.0, 0.0, 1.0))`.

    method set-source-rgba (
      Num() $red, Num() $green, Num() $blue, Num() $alpha
    )

  * $red; red component of color

  * $green; green component of color

  * $blue; blue component of color

  * $alpha; alpha component of color

set-source-surface
------------------

This is a convenience function for creating a pattern from *$surface* and setting it as the source in this context with `set-source()`.

The *$x* and *$y* parameters give the user-space coordinate at which the surface origin should appear. (The surface origin is its upper-left corner before any transformation has been applied). The *$x* and *$y* parameters are negated and then set as translation values in the pattern matrix.

Other than the initial translation pattern matrix, as described above, all other pattern attributes, (such as its extend mode), are set to the default values as in `Gnome::Cairo::Pattern.new(:surface)`. The resulting pattern can be queried with `get-source()` so that these attributes can be modified if desired, (eg. to create a repeating pattern with `Gnome::Cairo::Pattern.set-extend()`).

    method set-source-surface ( cairo_surface_t $surface, Num() $x, Num() $y )

  * $surface; a surface to be used to set the source pattern

  * $x; User-space X coordinate for surface origin

  * $y; User-space Y coordinate for surface origin

set-tolerance
-------------

Sets the tolerance used when converting paths into trapezoids. Curved segments of the path will be subdivided until the maximum deviation between the original path and the polygonal approximation is less than *$tolerance*. The default value is 0.1. A larger value will give better performance, a smaller value, better appearance. (Reducing the value from the default value of 0.1 is unlikely to improve appearance significantly.)

The accuracy of paths within Cairo is limited by the precision of its internal arithmetic, and the prescribed *$tolerance* is restricted to the smallest representable internal value.

    method set-tolerance ( Num() $tolerance )

  * $tolerance; the tolerance, in device units

show-glyphs
-----------

A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.

    method show-glyphs ( Array $glyphs )

  * $glyphs; array of glyphs to show

  * $num_glyphs; number of glyphs to show

show-page
---------

Emits and clears the current page for backends that support multiple pages. Use `copy-page()` if you don't want to clear the page.

This is a convenience function that simply calls `Gnome::Cairo::Surface.show-page()` on this context's target surface.

    method show-page ( )

show-text
---------

A drawing operator that generates the shape from a string of UTF-8 characters, rendered according to the current font_face, font_size (font_matrix), and font_options.

This function first computes a set of glyphs for the string of text. The first glyph is placed so that its origin is at the current point. The origin of each subsequent glyph is offset from that of the previous glyph by the advance values of the previous glyph.

After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for easy display of a single logical string with multiple calls to `show-text()`.

Note: The `show-text()` function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See `show-glyphs()` for the "real" text display API in cairo.

    method show-text ( Str $utf8-string )

  * $utf8-string; a string to show

show-text-glyphs
----------------

This operation has rendering effects similar to `show-glyphs()` but, if the target surface supports it, uses the provided text and cluster mapping to embed the text for the glyphs shown in the output. If the target does not support the extended attributes, this function acts like the basic `show-glyphs()` as if it had been passed *glyphs* and *num_glyphs*.

The mapping between *utf8* and *glyphs* is provided by an array of *clusters*. Each cluster covers a number of text bytes and glyphs, and neighboring clusters cover neighboring areas of *utf8* and *glyphs*.

The clusters should collectively cover *utf8* and *glyphs* in entirety.

The first cluster always covers bytes from the beginning of *utf8*. If *cluster_flags* do not have the `CAIRO_TEXT_CLUSTER_FLAG_BACKWARD` set, the first cluster also covers the beginning of *glyphs*, otherwise it covers the end of the *glyphs* array and following clusters move backward.

See **cairo_text_cluster_t** for constraints on valid clusters.

    method show-text-glyphs (
      Str $utf8, Array $glyphs, Array $clusters,
      cairo_text_cluster_flags_t $cluster_flags
    )

  * $utf8; a string of text encoded in UTF-8.

  * $glyphs; array of glyphs to show. Element type cairo_glyph_t.

  * $clusters; array of cluster mapping information. Element type cairo_text_cluster_t.

  * $cluster_flags; cluster mapping flags.

status
------

Checks whether an error has previously occurred for this context.

Returns: the current status of this context, see **cairo_status_t**

    method status ( --> cairo_status_t )

status-to-string
----------------

Provides a human-readable description of a cairo_status_t.

    method status-to-string ( cairo_status_t $status --> Str )

stroke
------

A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After `stroke()`, the current path will be cleared from the cairo context. See `set-line-width()`, `set-line-join()`, `cset-line-cap()`, `set-dash()`, and `stroke-preserve()`.

Note: Degenerate segments and sub-paths are treated specially and provide a useful result. These can result in two different situations:

  * Zero-length "on" segments set in `set-dash()`. If the cap style is `CAIRO_LINE_CAP_ROUND` or `CAIRO_LINE_CAP_SQUARE` then these segments will be drawn as circular dots or squares respectively. In the case of `CAIRO_LINE_CAP_SQUARE`, the orientation of the squares is determined by the direction of the underlying path.

  * A sub-path created by `move-to()` followed by either a `close-path()` or one or more calls to `line-to()` to the same coordinate as the `move-to()`. If the cap style is `CAIRO_LINE_CAP_ROUND` then these sub-paths will be drawn as circular dots.

Note that in the case of `CAIRO_LINE_CAP_SQUARE` a degenerate sub-path will not be drawn at all, (since the correct orientation is indeterminate). In no case will a cap style of `CAIRO_LINE_CAP_BUTT` cause anything to be drawn in the case of either degenerate segments or sub-paths.

    method stroke ( )

stroke-extents
--------------

Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a `stroke()` operation given the current path and stroke parameters. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account.

Note that if the line width is set to exactly zero, then `stroke-extents()` will return an empty rectangle. Contrast with `path-extents()` which can be used to compute the non-empty bounds as the line width approaches zero.

Note that `stroke-extents()` must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so `path-extents()` may be more desirable for sake of performance if non-inked path extents are desired. See `stroke()`, `set-line-width()`, `set-line-join()`, `set-line-cap()`, `set-dash()`, and `stroke-preserve()`.

    method stroke-extents ( --> List )

List returns;

  * Num; left of the resulting extents

  * Num; top of the resulting extents

  * Num; right of the resulting extents

  * Num; bottom of the resulting extents

stroke-preserve
---------------

A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike `stroke()`, `stroke-preserve()` preserves the path within the cairo context.

See `set-line-width()`, `set-line-join()`, `set-line-cap()`, `set-dash()`, and `stroke-preserve()`.

    method stroke-preserve ( )

tag-begin
---------

Marks the beginning of the *t$ag-name* structure. Call `tag-end()` with the same *$tag-name* to mark the end of the structure.

The `$attributes` string is of the form "key1=value2 key2=value2 ...". Values may be boolean (true/false or 1/0), integer, float, string, or an array. String values are enclosed in single quotes ('). Single quotes and backslashes inside the string should be escaped with a backslash. Boolean values may be set to true by only specifying the key. E.g. the attribute string "key" is the equivalent to "key=true". Arrays are enclosed in '[]'. E.g. "rect=[1.2 4.3 2.0 3.0]".

If no attributes are required, *attributes* can be an empty string or NULL. Invalid nesting of tags or invalid attributes will cause this context to shutdown with a status of `CAIRO_STATUS_TAG_ERROR`.

For example;

    with $cairo {
      .tag-begin( CAIRO_TAG_LINK, "uri='https://cairographics.org'");
      .move-to( 50, 50);
      .show-text('This is a link to the cairo website.');
      .tag-end(CAIRO_TAG_LINK);
    }

See `tag-end()`.

    method tag-begin ( Str $tag_name, Str $attributes )

  * $tag-name; The tag name. This can only be one of `CAIRO_TAG_LINK` or `CAIRO_TAG_DEST`.

  * $attributes; tag attributes.

tag-end
-------

Marks the end of the *tag_name* structure. Invalid nesting of tags will cause this context to shutdown with a status of `CAIRO_STATUS_TAG_ERROR`. See `tag-begin()`.

    method tag-end ( Str $tag_name )

  * $tag_name; tag name. This can only be one of `CAIRO_TAG_LINK` or `CAIRO_TAG_DEST`.

text-extents
------------

Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by `show-text()`). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by `show-text()`.

Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.

    method text-extents ( Str $utf-string --> cairo_text_extents_t )

  * $utf8;

  * cairo_text_extents_t $extents; a NUL-terminated string of text encoded in UTF-8, or `Any`

text-path
---------

Adds closed paths for text to the current path.

The generated path if filled, achieves an effect similar to that of `show-text()`.

Text conversion and positioning is done similar to `show-text()`.

Like `show-text()`, After this call the current point is moved to the origin of where the next glyph would be placed in this same progression.

That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to `text-path()` without having to set current point in between.

Note: The `text-path()` function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See `glyph-path()` for the "real" text path API in cairo.

    method text-path ( Str $utf8 )

  * $utf8; a string of text encoded in UTF-8.

transform
---------

Modifies the current transformation matrix (CTM) by applying *matrix* as an additional transformation. The new transformation of user space takes place after any existing transformation.

    method transform ( cairo_matrix_t $matrix )

  * $matrix; a transformation to be applied to the user-space axes

translate
---------

Modifies the current transformation matrix (CTM) by translating the user-space origin by (*tx*, *ty*). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to `translate()`. In other words, the translation of the user-space origin takes place after any existing transformation.

    method translate ( Num() $tx, Num() $ty )

  * $tx; amount to translate in the X direction

  * $ty; amount to translate in the Y direction

user-to-device
--------------

Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).

    method user-to-device ( Num() $x is rw, Num() $y is rw )

  * $x; X value of coordinate

  * $y; Y value of coordinate

user-to-device-distance
-----------------------

Transform a distance vector from user space to device space. This function is similar to `user-to-device()` except that the translation components of the CTM will be ignored when transforming (*dx*,*dy*).

    method user-to-device-distance ( Num() $dx is rw, Num() $dy is rw )

  * $dx; X component of a distance vector

  * $dy; Y component of a distance vector



