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#
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#
Creates a surface that is a window onto part of another one.
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#
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#
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.