[cairo] When Should You Call cairo_surface_flush?

[Uli Schlachter]

Hi,

Am 18.03.2015 um 10:46 schrieb Lawrence D'Oliveiro:
> Does cairo_surface_flush
> <http://cairographics.org/manual/cairo-cairo-surface-t.html#cairo-surface-flush>
> need to be called before making non-Cairo accesses to an image surface?

Yes.

> The docs say “This function must be called before switching from
> drawing on the surface with cairo to drawing on it directly with native
> APIs” -- of course “drawing ... with native APIs” has to mean “any kind
> of memory access”, so my guess is “yes”.
> 
> Currently in my Qahirah examples
> <https://github.com/ldo/qahirah_examples>, I am doing a flush before
> writing the images to PNG files. I would have thought Cairo would do
> this automatically, but I can find no sign of that in the source code
> (src/cairo-png.c).
> 
> Thanks for any clarification.

In the current implementation it is safe to *read* from an image surface's data
without calling flush. Writing does need a flush before, so that snapshots get
detached and surface snapshots can make a copy of the old contents.

However, this is an implementation detail and not guaranteed by the API. Later
versions of cairo might want to do "smart things". For example, the XCB backend
has a deferred_clear: If you fill the whole surface with a single color, this
operation is deferred until later. If you do something like this multiple times,
all but the last clear are skipped. This might make sense for the image backend
as well (but would just work around program "bugs", at least for the image
backend, I guess...).

Cheers,
Uli
-- 
"Do you know that books smell like nutmeg or some spice from a foreign land?"
                                                  -- Faber in Fahrenheit 451