[cairo] When Should You Call cairo_surface_flush?

[Lawrence D'Oliveiro]

On Wed, 18 Mar 2015 22:27:32 +0100, Uli Schlachter wrote:

> 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.

Thank you for that. Perhaps this should be made clear in the docs
<http://cairographics.org/manual/cairo-cairo-surface-t.html#cairo-surface-flush>:
the sentence

	This function must be called before switching from drawing on
	the surface with cairo to drawing on it directly with native
	APIs.

should become more like

	This function must be called before switching from drawing on
	the surface with Cairo to making any kind of accesses to its
	memory outside Cairo.

Can we also take it as read that, if the implementation changes in
future, the cairo_write_to_pngxxx calls will be updated to do any
necessary flushing? Which means the flush() calls in my sample code can
go?