[cairo] When Should You Call cairo_surface_flush?

[Bryce Harrington]

On Thu, Mar 19, 2015 at 10:57:08AM +1300, Lawrence D'Oliveiro wrote:
> 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?
> -- 
> cairo mailing list
> cairo at cairographics.org
> http://lists.cairographics.org/mailman/listinfo/cairo


>From 904f1fdc1d7f13d4443bafd760db7395c5030ca7 Mon Sep 17 00:00:00 2001
From: Bryce Harrington <bryce at osg.samsung.com>
Date: Wed, 18 Mar 2015 15:49:41 -0700
Subject: [PATCH] surface: Clarify flush documentation

Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
---
 src/cairo-surface.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 89345f5..bfe3fa1 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -1554,12 +1554,12 @@ _cairo_surface_flush (cairo_surface_t *surface, unsigned flags)
  * cairo_surface_flush:
  * @surface: a #cairo_surface_t
  *
- * 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. If the surface doesn't support direct access,
- * then this function does nothing.
+ * 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.
  *
  * Since: 1.0
  **/
-- 
1.9.1