```{index} single: Cairo::Pattern ``` # Cairo::Pattern ```{pperl-module-badges} Cairo::Pattern ``` `Cairo::Pattern` and its subclasses - the sources a context paints with. A pattern is what `Cairo::Context` draws with: a flat color (`Cairo::SolidPattern`), another surface used as an image or a tile (`Cairo::SurfacePattern`), or a color ramp - `Cairo::LinearGradient` and `Cairo::RadialGradient`, which take their color-stop methods from the abstract `Cairo::Gradient`. Settings shared by all of them (the pattern matrix, the extend mode, the filter) live on the base `Cairo::Pattern`. ## Constructors return the concrete subclass A constructor blesses its result into the class matching what cairo actually built, not into the class you called it on: `Cairo::SolidPattern->create_rgb` hands back a `Cairo::SolidPattern`, `Cairo::LinearGradient->create` a `Cairo::LinearGradient`, and anything cairo reports as some other kind comes back as the base `Cairo::Pattern`. `get_surface` behaves the same way, returning the surface blessed into its own class (`Cairo::ImageSurface`, `Cairo::PdfSurface` and so on). ## Object lifetime Patterns are reference-counted by cairo. A pattern you create owns its reference, and the surface `get_surface` returns takes one of its own, so it stays alive for as long as you hold it. Every object drops its reference when Perl destroys it; nothing has to be freed by hand. ## Gradient dithering (cairo 1.18) `set_dither` and `get_dither` control the dithering cairo applies to a gradient to hide banding. They need libcairo 1.18 or newer; on anything older they croak with `requires cairo >= 1.18`. ## Functions ### Other Functions #### `set_matrix` Sets the pattern's transformation matrix (cairo_pattern_set_matrix). `$matrix` is a `Cairo::Matrix`, and it maps user space to pattern space. Returns nothing. #### `get_matrix` Returns the pattern's transformation matrix as a fresh `Cairo::Matrix`. It is a copy: changing it does not change the pattern, which needs a `set_matrix` call. #### `status` Returns the pattern's error status as a nickname string, `success` when the pattern is usable. #### `set_dither` Sets how a gradient is dithered, to hide banding: `none`, `default`, `fast`, `good` or `best`. Needs libcairo 1.18 or newer, and croaks with `Cairo: set_dither requires cairo >= 1.18` on anything older. #### `get_dither` Returns the pattern's dither setting as a nickname string. Needs libcairo 1.18 or newer, and croaks with `Cairo: get_dither requires cairo >= 1.18` on anything older.