```{index} single: Cairo::Surface ``` # Cairo::Surface ```{pperl-module-badges} Cairo::Surface ``` `Cairo::Surface` and its subclasses - the things cairo draws onto. A surface is where drawing ends up, and its class decides in what form: `Cairo::ImageSurface` for pixels in memory, `Cairo::PdfSurface`, `Cairo::PsSurface` and `Cairo::SvgSurface` for the corresponding file formats, and `Cairo::RecordingSurface` for a replayable record of the drawing operations themselves. All of them inherit from `Cairo::Surface`, which carries the methods common to every backend. Every constructor returns the concrete subclass, never the bare `Cairo::Surface`, so the surface you get back from `create_similar` or from `$cr->get_target` already responds to the methods of whatever kind of surface it turned out to be. Draw on a surface by creating a context for it with `Cairo::Context->create($surface)`. Methods that name a string constant - `status`, `get_type`, `get_content`, `get_format` - return a short name such as `'success'`, `'image'`, `'color-alpha'` or `'argb32'`, never a number. ## When a backend is missing Which backends exist depends on how the cairo installed on this machine was built. A cairo without PDF, PostScript, SVG or PNG support still loads, but the methods belonging to the missing backend die with a message saying so, for example "libcairo was built without PDF support". `Cairo::HAS_PNG_FUNCTIONS` reports the PNG case up front. The PDF metadata and outline methods additionally need cairo 1.16 or newer. ## Constants The MIME types `set_mime_data` and `supports_mime_type` take are constants of `Cairo::Surface`: `MIME_TYPE_JPEG` (`"image/jpeg"`), `MIME_TYPE_PNG`, `MIME_TYPE_JP2`, `MIME_TYPE_URI`, `MIME_TYPE_UNIQUE_ID`, `MIME_TYPE_JBIG2`, `MIME_TYPE_JBIG2_GLOBAL`, `MIME_TYPE_JBIG2_GLOBAL_ID`, `MIME_TYPE_CCITT_FAX`, `MIME_TYPE_CCITT_FAX_PARAMS`, `MIME_TYPE_EPS` and `MIME_TYPE_EPS_PARAMS`. `Cairo::PdfSurface::OUTLINE_ROOT` (0) is the parent id to give `add_outline` for a top-level bookmark. ## Functions ### Other Functions #### `status` Returns the surface's error state as a status name such as `'success'`, `'file-not-found'` or `'no-memory'`. #### `get_type` Returns the kind of surface this is, as a name such as `'image'`, `'pdf'`, `'ps'`, `'svg'` or `'recording'`. #### `get_content` Returns what the surface stores, as one of `'color'`, `'alpha'` or `'color-alpha'`. #### `write_to_png` Writes the surface to `$filename` as a PNG and returns a status name. #### [`create_similar`](Surface/create_similar) Creates a new surface of the same backend as an existing one, sized `$width` by `$height`, and returns it as the concrete subclass. #### `set_device_offset` Shifts the surface's origin, so that user-space point (0, 0) lands at device point `($x, $y)` instead. #### `get_device_offset` Returns the surface's device offset as the two-element list `($x_offset, $y_offset)`. #### `set_fallback_resolution` Sets the resolution, in pixels per inch, at which a vector backend rasterises anything it cannot express directly. #### `get_fallback_resolution` Returns the surface's fallback resolution as the two-element list `($x_ppi, $y_ppi)`. #### `get_font_options` Returns the font rendering options this surface prefers, as a fresh `Cairo::FontOptions`. #### `mark_dirty_rectangle` Tells cairo that the given rectangle of the surface was changed behind its back, so that any cached copy of that area is discarded. #### `has_show_text_glyphs` Returns 1 if this surface can record the character-to-glyph mapping that `$cr->show_text_glyphs` supplies, and 0 if it cannot. #### [`create_for_rectangle`](Surface/create_for_rectangle) Creates a surface that is a window onto part of another one. #### [`supports_mime_type`](Surface/supports_mime_type) Returns 1 if the surface can embed data of the given MIME type unchanged in its output, and 0 if it cannot. #### [`write_to_png_stream`](Surface/write_to_png_stream) Writes the surface as a PNG by handing successive chunks of it to a callback of yours, and returns a status name. #### [`set_mime_data`](Surface/set_mime_data) Attaches the original compressed form of an image to the surface, so that a backend able to embed it does so instead of re-encoding the pixels, and returns a status name. #### `get_mime_data` Returns the data previously attached with `set_mime_data` for the given MIME type, or `undef` if the surface carries none. ```{toctree} :hidden: :maxdepth: 1 Surface/create_similar Surface/create_for_rectangle Surface/supports_mime_type Surface/write_to_png_stream Surface/set_mime_data ```