[cairo] cairo_surface_map_to_image () -- for what is it used?

[Uli Schlachter]

Hi Stefan,

On 12.10.2017 19:21, Stefan Salewski wrote:
> https://www.cairographics.org/manual/cairo-cairo-surface-t.html#cairo-surface-map-to-image
> 
> I was working yesterday on the cairo Nim high level wrapper and found this function.
> 
> After reading the doc page, I have still no idea what it is.
> 
> Can you give me a hint for what it may be used?

Short version: Efficiency.

Cairo can do lots of different drawing operations, but not all the
targets that it has backends for can do all of them. For example, an X11
(older) server might not have the PDF blending modes. Thus, cairo has to
download the image data, do the operation locally (with the image
backend) and upload the result again to the server. This is called a
fallback. Doing this for every single drawing operation is obviously
slow (lots of useless copies), so after a fallback it is benefical to
continue doing operations locally with the image backend.

If the program using cairo wants to e.g. grab a screenshot, it can do so
by using cairo to copy the X11 surface to an image surface. However,
after a fallback, cairo already has an image surface with the surface's
content, so why not use that directly? Well, how can one access this
fallback surface? cairo_surface_map_to_image() gives it to you!

This is one example. There are other possibilities, but this would be one.

I hope this helps,
Uli
-- 
- He made himself, me nothing, you nothing out of the dust
- Er machte sich mir nichts, dir nichts aus dem Staub