fn copy_page[link]

fn copy_page(surface: *cairo::surface_t) void;

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. Use show_page if you want to get an empty page after the emission.

There is a convenience function for this that takes a cairo::context_t, namely cairo::copy_page.

fn create_for_rectangle[link]

fn create_for_rectangle(target: *cairo::surface_t, x: f64, y: f64, width: f64, height: f64) (*cairo::surface_t | cairo::error);

Creates a new surface that is a rectangle within the target surface. All operations drawn to this surface are then clipped and translated onto the target surface. Nothing drawn via this sub-surface outside of its bounds is drawn onto the target surface, making this a useful method for passing constrained child surfaces to library routines that draw directly onto the parent surface, i.e. with no further backend allocations, double buffering or copies.

The semantics of subsurfaces have not been finalized yet unless the rectangle is in full device units, is contained within the extents of the target surface, and the target or subsurface's device transforms are not changed.

Parameters

• target: an existing surface for which the sub-surface will point to
• x: the x-origin of the sub-surface from the top-left of the target surface (in device-space units)
• y: the y-origin of the sub-surface from the top-left of the target surface (in device-space units)
• width: width of the sub-surface (in device-space units)
• height: height of the sub-surface (in device-space units)

Returns the newly allocated surface. The caller owns the surface and should call destroy when done with it. If an error occurs, cairo::error is returned instead.

fn create_similar[link]

fn create_similar(other: *cairo::surface_t, content: cairo::content_t, width: int, height: int) (*cairo::surface_t | cairo::error);

Creates a new surface that is as compatible as possible with an existing surface. For example the new surface will have the same device scale, fallback resolution and font options as other. Generally, the new surface will also use the same backend as other, unless that is not possible for some reason. The type of the returned surface may be examined with get_type.

Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)

Use create_similar_image if you need an image surface which can be painted quickly to the target surface.

Parameters

• other: an existing surface used to select the backend of the new surface
• content: the content for the new surface
• width: width of the new surface, (in device-space units)
• height: height of the new surface (in device-space units)

Returns the newly allocated surface. The caller owns the surface and should call destroy when done with it. If an error occurs, cairo::error is returned instead.

fn create_similar_image[link]

fn create_similar_image(other: *cairo::surface_t, format: cairo::format_t, width: int, height: int) (*cairo::surface_t | cairo::error);

Creates a new image surface that is as compatible as possible for uploading to and the use in conjunction with an existing surface. However, this surface can still be used like any normal image surface. Unlike create_similar the new image surface won't inherit the device scale from other.

Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)

Use create_similar if you don't need an image surface.

Parameters

• other: an existing surface used to select the preference of the new surface
• format: the format for the new surface
• width: width of the new surface, (in pixels)
• height: height of the new surface (in pixels)

Returns the newly allocated image surface. The caller owns the surface and should call destroy when done with it. If an error occurs, cairo::error is returned instead.

fn destroy[link]

fn destroy(surface: *cairo::surface_t) void;

Decreases the reference count on surface by one. If the result is zero, then surface and all associated resources are freed.

fn finish[link]

fn finish(surface: *cairo::surface_t) void;

This function finishes the surface and drops all references to external resources. For example, for the Xlib backend it means that cairo will no longer access the drawable, which can be freed. After calling finish the only valid operations on a surface are getting and setting user, referencing and destroying, and flushing and finishing it. Further drawing to the surface will not affect the surface but will instead trigger a cairo::status_t::SURFACE_FINISHED error.

When the last call to destroy decreases the reference count to zero, cairo will call finish if it hasn't been called already, before freeing the resources associated with the surface.

fn flush[link]

fn flush(surface: *cairo::surface_t) void;

Do any pending drawing for the surface and also restore any temporary modifications cairo has made to the surface's state. This function must be called before switching from drawing on the surface with cairo to drawing on it directly with native APIs, or accessing its memory outside of Cairo. If the surface doesn't support direct access, then this function does nothing.

fn get_content[link]

fn get_content(surface: *cairo::surface_t) cairo::content_t;

This function returns the content type of surface which indicates whether the surface contains color and/or alpha information. See cairo::content_t.

fn get_device[link]

fn get_device(surface: *cairo::surface_t) (*cairo::device_t | cairo::error);

This function returns the device for a surface. See cairo::device_t.

Returns the device for surface or cairo::error if the surface does not have an associated device.

fn get_device_scale[link]

fn get_device_scale(surface: *cairo::surface_t, x_scale: f64, y_scale: f64) void;

This function returns the previous device offset set by set_device_scale.

Parameters

• surface: a cairo::surface_t
• x_scale: the scale in the X direction, in device units
• y_scale: the scale in the Y direction, in device units

fn get_reference_count[link]

fn get_reference_count(surface: *cairo::surface_t) uint;

Returns the current reference count of surface. If the object is a nil object, 0 will be returned.

fn get_type[link]

fn get_type(surface: *cairo::surface_t) cairo::surface_type_t;

This function returns the type of the backend used to create a surface. See cairo::surface_type_t for available types.

fn map_to_image[link]

fn map_to_image(surface: *cairo::surface_t, extents: *const cairo::rectangle_int_t) (*cairo::surface_t | cairo::error);

Returns an image surface that is the most efficient mechanism for modifying the backing store of the target surface. The region retrieved may be limited to the extents or NULL for the whole surface.

Note, the use of the original surface as a target or source whilst it is mapped is undefined. The result of mapping the surface multiple times is undefined. Calling destroy or finish on the resulting image surface results in undefined behavior. Changing the device transform of the image surface or of surface before the image surface is unmapped results in undefined behavior.

Parameters

• surface: an existing surface used to extract the image from
• extents: limit the extraction to an rectangular region

Returns the newly allocated image surface. The caller must use unmap_image to destroy this image surface. If an error occurs, cairo::error is returned instead.

fn mark_dirty[link]

fn mark_dirty(surface: *cairo::surface_t) void;

Tells cairo that drawing has been done to surface using means other than cairo, and that cairo should reread any cached areas. Note that you must call flush() before doing such drawing.

fn mark_dirty_rectangle[link]

fn mark_dirty_rectangle(surface: *cairo::surface_t, x: int, y: int, width: int, height: int) void;

Like mark_dirty, but drawing has been done only to the specified rectangle, so that cairo can retain cached contents for other parts of the surface.

Any cached clip set on the surface will be reset by this function, to make sure that future cairo calls have the clip set that they expect.

Parameters

• surface: a cairo::surface_t
• x: X coordinate of dirty rectangle
• y: Y coordinate of dirty rectangle
• width: width of dirty rectangle
• height: height of dirty rectangle

fn reference[link]

fn reference(surface: *cairo::surface_t) *cairo::surface_t;

Increases the reference count on surface by one. This prevents surface from being destroyed until a matching call to destroy is made. Use get_reference_count to get the number of references to a cairo::surface_t.

Returns the referenced cairo::surface_t.

fn set_device_scale[link]

fn set_device_scale(surface: *cairo::surface_t, x_scale: f64, y_scale: f64) void;

Sets a scale that is multiplied to the device coordinates determined by the CTM when drawing to surface. One common use for this is to render to very high resolution display devices at a scale factor, so that code that assumes 1 pixel will be a certain size will still work. Setting a transformation via cairo::translate isn't sufficient to do this, since functions like cairo::device_to_user will expose the hidden scale.

Note that the scale affects drawing to the surface as well as using the surface in a source pattern.

Parameters

• surface: a cairo::surface_t
• x_scale: a scale factor in the X direction
• y_scale: a scale factor in the Y direction

fn show_page[link]

fn show_page(surface: *cairo::surface_t) void;

Emits and clears the current page for backends that support multiple pages. Use copy_page if you don't want to clear the page.

There is a convenience function for this that takes a cairo::context_t, namely cairo::show_page.

fn status[link]

fn status(surface: *cairo::surface_t) cairo::status_t;

Checks whether an error has previously occurred for this surface.

fn unmap_image[link]

fn unmap_image(surface: *cairo::surface_t, image: *cairo::surface_t) void;

Unmaps the image surface as returned from map_to_image. The content of the image will be uploaded to the target surface. Afterwards, the image is destroyed.

Using an image surface which wasn't returned by map_to_image results in undefined behavior.

Parameters

• surface: the surface passed to map_to_image.
• image: the currently mapped image

fn write_to_png[link]

fn write_to_png(surface: *cairo::surface_t, filename: str) (void | cairo::error);

Writes the contents of surface to a new file filename as a PNG image. Returns void if the PNG file was written successfully. If an error occurs, cairo::error is returned instead.