Can a finished cairo surface be recovered without destroying it?

Answer

In Cairo, once cairo_surface_finish() has been called (or a drawing operation fails with CAIRO_STATUS_SURFACE_FINISHED), the surface enters a sticky state that cannot be cleared by any subsequent Cairo API call. The only way to use a fresh surface is to destroy the old one and create a new instance.

Status semantics

The Cairo API defines CAIRO_STATUS_SURFACE_FINISHED as a terminal condition. The surface is considered “finished” when all pending resources have been released and no further drawing or querying is permitted. The status is stored on the surface object and is not reset by any operation, including cairo_surface_status(), cairo_surface_get_width(), or even cairo_surface_create_similar().

What the API says

• Drawing commands (e.g. cairo_set_source_rgb(), cairo_paint()) return CAIRO_STATUS_SURFACE_FINISHED when invoked on a finished surface.
• All surface‑related queries that are not pure introspection (e.g. cairo_surface_get_width()) also return the finished status.
• There is no documented function that clears the finished flag; the Cairo documentation explicitly recommends destroying the surface and creating a new one after a finish.

Verification steps

To confirm this behavior on your system, compile and run the following minimal C program. Replace cairo-1.0 with the correct pkg‑config name for your Cairo installation.

#include <cairo.h>
#include <stdio.h>

int main(void) {
    cairo_surface_t *s = cairo_image_surface_create(CAIRO_FORMAT_ARGB32, 100, 100);
    cairo_surface_finish(s);
    printf("After finish: %d\n", cairo_surface_status(s));
    cairo_set_source_rgb(cairo_create(s), 1, 0, 0);
    printf("After set_source_rgb: %d\n", cairo_surface_status(s));
    cairo_surface_destroy(s);
    return 0;
}

Running this program on any stable Cairo release (e.g. 1.16.0, 1.18.0) will consistently print the finished status after both calls, proving that the state is sticky.

What to do instead

1. When a surface becomes finished, immediately destroy it: cairo_surface_destroy(s);
2. Create a new surface of the same type and size: cairo_surface_t *s2 = cairo_image_surface_create(CAIRO_FORMAT_ARGB32, 100, 100);
3. Continue drawing on the new surface as normal.

Attempting to reuse the old surface will not reset the status and will cause all subsequent Cairo calls to return the finished error.

Missing diagnostic detail

To ensure that this recommendation aligns with your environment, please provide the exact Cairo version you are using (e.g. cairo --version or the output of pkg-config --modversion cairo-1.0). Some very old or experimental builds might exhibit undocumented differences, though all stable releases since 1.16 treat the status as sticky.