[cairo] [PATCH 1/2] gl: Add a first bit of general documentation on cairo-gl usage.

[Bill Spitzak]

Proposed rules which I tried to make a strict as possible while still 
allowing useful multithreaded cairo programs to be written. If you 
disobey these rules results are undefined, though it is recommended that 
backgrounds abort the program if the overhead of the test is considered 
cheap enough:

1. A cairo_t can only be used by a single thread and that thread has to 
be the one that creates and destroys it.

2. A surface can have at most one cairo_t attached to it as a destination.

3. If no cairo_t is using a surface as a destination, it can then have 
*any* number of cairo_t's using it as a source.

4. Cairo backends assume that the state of any objects remains unchanged 
between calls to cairo in the same thread. Backends may provide some 
optional "reset" functions that can be called to indicate that a program 
did mess with things and cairo should put them back the way it expects.

Rule 2 moves the test to the creation/destruction of a cairo_t for a 
surface. I think this will result in much less overhead than putting 
protection around each drawing call.

Rule 3 I think is a requirement for useful Cairo programs. You must be 
able to use a source surface without worrying about multithreading. 
However the implementation knows nobody is altering the surface.

Benjamin Otte wrote:
> Well, the other option is to rethink cairo's threading guarantees and
> say "cairo requires that every device is used in the same thread only"
> or "threading guarantees depend on the backend". Which does not look
> like a problem as it seems that
> - nobody bothered fixing the image backend to make it threadsafe yet
> - it looks like GStreamer will not go the cairo route
> So it seems there is nobody wanting to use a cairo that allows using the
> same surface in multiple threads at once. And everybody can bind
> textures into multiple GL contexts manually, so it's still possible to
> use cairo + GL + multithreading. It'll just be more work for the people
> that want to do it.