[cairo] When Should You Call cairo_surface_flush?

[Uli Schlachter]

Am 18.03.2015 um 23:51 schrieb 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
>   **/

Well, what's the memory of an Xlib or XCB surface? I'd rather have this say "or
accessing its content outside of Cairo". Or perhaps "backing storage" instead of
"content"? "Underlying mechanism that cairo draws to"? I'm not sure.

But since this might go into bike-shedding territory:
Reviewed-by: Uli Schlachter <psychon at znc.in>

Cheers,
Uli
-- 
Bitte nicht mit dem verbleibenden Auge in den Laser gucken.
 - Vincent Ebert