cairomm: Cairo::RecordingSurface Class Reference

cairomm 1.19.1

Public Member Functions | Static Public Member Functions | List of all members
Cairo::RecordingSurface Class Reference

A recording surface is a surface that records all drawing operations at the highest level of the surface backend interface, (that is, the level of paint, mask, stroke, fill, and show_text_glyphs). More...

`#include <cairomm/surface.h>`

Inheritance diagram for Cairo::RecordingSurface:
[legend]

## Public Member Functions
| RecordingSurface (cairo_surface_t *cobject, bool has_reference=false)
| Create a C++ wrapper for the C instance.
virtual | ~RecordingSurface ()
Rectangle | ink_extents () const
| Measures the extents of the operations stored within the recording surface.
bool | get_extents (Rectangle & extents) const
| Get the extents of the recording surface, if the surface is bounded.
Public Member Functions inherited from Cairo::Surface
| Surface (cairo_surface_t *cobject, bool has_reference=false)
| Create a C++ wrapper for the C instance.
| Surface (const Surface &)=delete
Surface & | operator= (const Surface &)=delete
virtual | ~Surface ()
const unsigned char * | get_mime_data (const std::string & mime_type, unsigned long & length)
| Return mime data previously attached to surface using the specified mime type.
void | set_mime_data (const std::string & mime_type, unsigned char *data, unsigned long length, const SlotDestroy & slot_destroy)
| Attach an image in the format mime_type to surface.
void | unset_mime_data (const std::string & mime_type)
| Remove the data from a surface.
void | get_font_options (FontOptions & options) const
| Retrieves the default font rendering options for the surface.
void | finish ()
| This function finishes the surface and drops all references to external resources.
void | flush ()
| Do any pending drawing for the surface and also restore any temporary modifications cairo has made to the surface's state.
void | mark_dirty ()
| Tells cairo to consider the data buffer dirty.
void | mark_dirty (int x, int y, int width, int height)
| Marks a rectangular area of the given surface dirty.
void | set_device_offset (double x_offset, double y_offset)
| Sets an offset that is added to the device coordinates determined by the CTM when drawing to surface.
void | get_device_offset (double & x_offset, double & y_offset) const
| Returns a previous device offset set by set_device_offset().
void | set_device_scale (double x_scale, double y_scale)
| Sets a scale that is multiplied to the device coordinates determined by the CTM when drawing to surface.
void | set_device_scale (double scale)
| Sets x and y scale to the same value.
void | get_device_scale (double & x_scale, double & y_scale) const
| Returns a previous device scale set by set_device_scale().
double | get_device_scale () const
| Returns the x and y average of a previous device scale set by set_device_scale().
void | set_fallback_resolution (double x_pixels_per_inch, double y_pixels_per_inch)
| Set the horizontal and vertical resolution for image fallbacks.
void | get_fallback_resolution (double & x_pixels_per_inch, double & y_pixels_per_inch) const
| This function returns the previous fallback resolution set by set_fallback_resolution(), or default fallback resolution if never set.
Type | get_type () const
Content | get_content () const
| This function returns the content type of surface which indicates whether the surface contains color and/or alpha information.
void | copy_page ()
| Emits the current page for backends that support multiple pages, but doesn't clear it, so that the contents of the current page will be retained for the next page.
void | show_page ()
| Emits and clears the current page for backends that support multiple pages.
bool | has_show_text_glyphs () const
| Returns whether the surface supports sophisticated Context::show_text_glyphs() operations.
void | write_to_png (const std::string & filename)
| Writes the contents of surface to a new file filename as a PNG image.
void | write_to_png_stream (const SlotWriteFunc & write_func)
| Writes the Surface to the write function.
RefPtr< ImageSurface > | create_similar_image (Format format, int width, int height)
| Create a new image surface that is as compatible as possible for uploading to and the use in conjunction with an existing surface.
bool | supports_mime_type (const std::string & mime_type)
| Checks whether mime_type is supported by the surface.
RefPtr< MappedImageSurface > | map_to_image (const RectangleInt & extents)
| Returns an image surface that is the most efficient mechanism for modifying the backing store of the target surface.
RefPtr< MappedImageSurface > | map_to_image ()
| Returns an image surface that is the most efficient mechanism for modifying the backing store of the target surface.
RefPtr< Device > | get_device ()
| This function returns the device for a surface.
cobject * | cobj ()
| Provides acces to the underlying C cairo surface.
const cobject * | cobj () const
| Provides acces to the underlying C cairo surface.

## Static Public Member Functions
static RefPtr< RecordingSurface > | create (Content content=Content::CONTENT_COLOR_ALPHA)
| Creates a recording surface which can be used to record all drawing operations at the highest level (that is, the level of paint, mask, stroke, fill and show_text_glyphs).
static RefPtr< RecordingSurface > | create (const Rectangle & extents, Content content=Content::CONTENT_COLOR_ALPHA)
| Creates a recording surface which can be used to record all drawing operations at the highest level (that is, the level of paint, mask, stroke, fill and show_text_glyphs).
Static Public Member Functions inherited from Cairo::Surface
static RefPtr< Surface > | create (const RefPtr< Surface > other, Content content, int width, int height)
| Create a new surface that is as compatible as possible with an existing surface.
static RefPtr< Surface > | create (const RefPtr< Surface > & target, double x, double y, double width, double height)
| Create a new surface that is a rectangle within the target surface.

## Additional Inherited Members
Public Types inherited from Cairo::Surface
enum class | Type { IMAGE = CAIRO_SURFACE_TYPE_IMAGE , PDF = CAIRO_SURFACE_TYPE_PDF , PS = CAIRO_SURFACE_TYPE_PS , XLIB = CAIRO_SURFACE_TYPE_XLIB , XCB = CAIRO_SURFACE_TYPE_XCB , GLITZ = CAIRO_SURFACE_TYPE_GLITZ , QUARTZ = CAIRO_SURFACE_TYPE_QUARTZ , WIN32 = CAIRO_SURFACE_TYPE_WIN32 , WIN32_SURFACE = CAIRO_SURFACE_TYPE_WIN32 , BEOS = CAIRO_SURFACE_TYPE_BEOS , DIRECTFB = CAIRO_SURFACE_TYPE_DIRECTFB , SVG = CAIRO_SURFACE_TYPE_SVG , OS2 = CAIRO_SURFACE_TYPE_OS2 , WIN32_PRINTING = CAIRO_SURFACE_TYPE_WIN32_PRINTING , QUARTZ_IMAGE = CAIRO_SURFACE_TYPE_QUARTZ_IMAGE , SCRIPT = CAIRO_SURFACE_TYPE_SCRIPT , QT = CAIRO_SURFACE_TYPE_QT , RECORDING = CAIRO_SURFACE_TYPE_RECORDING , VG = CAIRO_SURFACE_TYPE_VG , GL = CAIRO_SURFACE_TYPE_GL , DRM = CAIRO_SURFACE_TYPE_DRM , TEE = CAIRO_SURFACE_TYPE_TEE , XML = CAIRO_SURFACE_TYPE_XML , SKIA = CAIRO_SURFACE_TYPE_SKIA , SUBSURFACE = CAIRO_SURFACE_TYPE_SUBSURFACE }
| Cairo::Surface::Type is used to describe the type of a given surface. More...
enum class | Format { ARGB32 = CAIRO_FORMAT_ARGB32 , RGB24 = CAIRO_FORMAT_RGB24 , A8 = CAIRO_FORMAT_A8 , A1 = CAIRO_FORMAT_A1 , RGB16_565 = CAIRO_FORMAT_RGB16_565 }
| Cairo::Surface::Format is used to identify the memory format of image data. More...
typedef sigc::slot< ErrorStatus(const unsigned char *, unsigned int)> | SlotWriteFunc
| For example: `ErrorStatus my_write_func(unsigned char* data, unsigned int length);` .
typedef sigc::slot< ErrorStatus(unsigned char *, unsigned int)> | SlotReadFunc
| This is the type of function which is called when a backend needs to read data from an input stream.
typedef sigc::slot< void()> | SlotDestroy
| For instance, void on_destroy();.
typedef cairo_surface_t | cobject
| The underlying C cairo surface type.
Protected Attributes inherited from Cairo::Surface
cobject * | m_cobject
| The underlying C cairo surface type that is wrapped by this Surface.

## Detailed Description

A recording surface is a surface that records all drawing operations at the highest level of the surface backend interface, (that is, the level of paint, mask, stroke, fill, and show_text_glyphs).

The recording surface can then be "replayed" against any target surface by using it as a source surface.

If you want to replay a surface so that the results in target will be identical to the results that would have been obtained if the original operations applied to the recording surface had instead been applied to the target surface, you can use code like this:

    Cairo::RefPtr<Cairo::Context> context = Cairo::Context::create(target);
    context->set_source(recording_surface, 0.0, 0.0);
    context->paint();

A recording surface is logically unbounded, i.e. it has no implicit constraint on the size of the drawing surface. However, in practice this is rarely useful as you wish to replay against a particular target surface with known bounds. For this case, it is more efficient to specify the target extents to the recording surface upon creation.

The recording phase of the recording surface is careful to snapshot all necessary objects (paths, patterns, etc.), in order to achieve accurate replay.

Note that like all surfaces, a RecordingSurface is a reference-counted object that should be used via Cairo::RefPtr.

## Constructor & Destructor Documentation

## ◆ RecordingSurface()

Cairo::RecordingSurface::RecordingSurface | ( | cairo_surface_t * | cobject,
|  | bool | has_reference = false )
| explicit

Create a C++ wrapper for the C instance.

This C++ instance should then be given to a RefPtr.

Parameters

  cobject | The C instance.
  has_reference | Whether we already have a reference. Otherwise, the constructor will take an extra reference.

## ◆ ~RecordingSurface()

virtual Cairo::RecordingSurface::~RecordingSurface | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ create() [1/2]

RefPtr< RecordingSurface > Cairo::RecordingSurface::create | ( | const Rectangle & | extents,
|  | Content | content = Content::CONTENT_COLOR_ALPHA )
| static

Creates a recording surface which can be used to record all drawing operations at the highest level (that is, the level of paint, mask, stroke, fill and show_text_glyphs).

The recording surface can then be "replayed" against any target surface by using it as a source to drawing operations. The recording surface will be bounded by the given rectangle.

The recording phase of the recording surface is careful to snapshot all necessary objects (paths, patterns, etc.), in order to achieve accurate replay.

Parameters

  extents | the extents to record
  content | the content of the recording surface; defaults to Cairo::Content::CONTENT_COLOR_ALPHA.

Returns
  a RefPtr to the newly created recording surface.

## ◆ create() [2/2]

RefPtr< RecordingSurface > Cairo::RecordingSurface::create | ( | Content | content = Content::CONTENT_COLOR_ALPHA | ) |
| static

Creates a recording surface which can be used to record all drawing operations at the highest level (that is, the level of paint, mask, stroke, fill and show_text_glyphs).

The recording surface can then be "replayed" against any target surface by using it as a source to drawing operations. The recording surface will be unbounded.

The recording phase of the recording surface is careful to snapshot all necessary objects (paths, patterns, etc.), in order to achieve accurate replay.

Parameters

  content | the content of the recording surface; defaults to Cairo::Content::CONTENT_COLOR_ALPHA.

Returns
  a RefPtr to the newly created recording surface.

## ◆ get_extents()

bool Cairo::RecordingSurface::get_extents | ( | Rectangle & | extents | ) | const

Get the extents of the recording surface, if the surface is bounded.

Parameters

  extents | the Rectangle in which to store the extents if the recording surface is bounded

Returns
  true if the recording surface is bounded, false if the recording surface is unbounded (in which case extents will not be set).

## ◆ ink_extents()

Rectangle Cairo::RecordingSurface::ink_extents | ( |  | ) | const

Measures the extents of the operations stored within the recording surface.

This is useful to compute the required size of an image surface (or equivalent) into which to replay the full sequence of drawing operations.

Returns
  a Rectangle with x and y set to the coordinates of the top-left of the ink bounding box, and width and height set to the width and height of the ink bounding box.

The documentation for this class was generated from the following file:

- cairomm/surface.h