Instead of abusing CAIRO_STATUS_SURFACE_FINISHED to indicate the use
of a finished device, define and use the new error status
CAIRO_STATUS_DEVICE_FINISHED.
The problem is that the finish callback might still have to work with the
device, so it can't be made unusable yet. This is in contrast to what
cairo_surface_finish() does, but when finishing a surface it's quite unlikely
that its cairo_surface_t still has to be passed around to functions outside of
the backend.
This "fixes" some problems with the xcb-surface-source test where
_cairo_surface_snapshot()-style snapshots break when the underlying
cairo_device_t is finished. (In the following backtrace, cairo_device_acquire
fails because the device's ->finished member is already TRUE)
#0 cairo_device_acquire (device=0x690f70) at cairo-device.c:414
#1 0x00007ffff7b884fb in _cairo_xcb_connection_acquire (surface=0x69c610, use_shm=<value optimized out>, image_out=0x7fffffffcc58) at cairo-xcb-private.h:246
#2 _get_image (surface=0x69c610, use_shm=<value optimized out>, image_out=0x7fffffffcc58) at cairo-xcb-surface.c:425
#3 0x00007ffff7b893cf in _cairo_xcb_surface_acquire_source_image (abstract_surface=0x69c610, image_out=0x7fffffffcce8, image_extra=0x7fffffffcce0)
at cairo-xcb-surface.c:561
#4 0x00007ffff7b601d4 in _cairo_surface_acquire_source_image (surface=0x690f70, image_out=0x7fffffffcce8, image_extra=0x0) at cairo-surface.c:1458
#5 0x00007ffff7b65dcf in _cairo_surface_snapshot_copy_on_write (surface=<value optimized out>) at cairo-surface-snapshot.c:125
#6 0x00007ffff7b609b1 in _cairo_surface_detach_snapshot (snapshot=0x690f70) at cairo-surface.c:330
#7 0x00007ffff7b606dc in _cairo_surface_detach_snapshots (surface=0x69c610) at cairo-surface.c:315
#8 cairo_surface_flush (surface=0x69c610) at cairo-surface.c:1126
#9 0x00007ffff7b6074d in cairo_surface_finish (surface=0x690f70) at cairo-surface.c:718
#10 0x00007ffff7b881ff in _cairo_xcb_screen_finish (screen=0x691920) at cairo-xcb-screen.c:61
#11 0x00007ffff7b8629c in _device_finish (device=0x690f70) at cairo-xcb-connection.c:546
#12 0x0000000000446f7c in cleanup (data=0x69c370) at xcb-surface-source.c:47
#13 0x00007ffff7b1e56a in _cairo_user_data_array_fini (array=0x693628) at cairo-array.c:390
#14 0x00007ffff7b60868 in cairo_surface_destroy (surface=0x693600) at cairo-surface.c:651
#15 0x0000000000447599 in draw (cr=0x7ffff7ddc288, width=<value optimized out>, height=<value optimized out>) at surface-source.c:149
#16 0x000000000040c1c3 in cairo_test_for_target (ctx=0x7fffffffe640, target=0x669668, dev_offset=<value optimized out>, similar=<value optimized out>)
at cairo-test.c:984
#17 0x000000000040d997 in _cairo_test_context_run_for_target (ctx=<value optimized out>, target=<value optimized out>, similar=<value optimized out>,
dev_offset=<value optimized out>) at cairo-test.c:1617
#18 0x000000000040ee09 in _cairo_test_runner_draw (argc=<value optimized out>, argv=<value optimized out>) at cairo-test-runner.c:269
#19 main (argc=<value optimized out>, argv=<value optimized out>) at cairo-test-runner.c:924
Signed-off-by: Uli Schlachter <psychon@znc.in>
Add the mesh pattern type and an error status to be used to report an
incorrect construction of the pattern.
Update the backends to make them ready to handle the new pattern type,
even if it cannot be created yet.
The exact semantics of the device API can't be spelled out
out in the device API docs since the effects are so tied
to the specific backend. To use a particular device in
practice the user should refer to the backend docs.
Add general docs and document acquire/release. I'm not happy with the
documentation yet. In particular, I have 2 issues:
1) The threading guarantees Cairo provides are missing.
2) There's no docs on which Cairo functions do acquire devices.
I guess I'll have to fix them later.
As the user is likely to attach the underlying resources to the device
for automatic collection upon finalization, it is important that the
user data is then destroy last (so that those resources are still
available in the surface and device cleanup routines).
I updated the Free Software Foundation address using the following script.
for i in $(git grep Temple | cut -d: -f1 )
do
sed -e 's/59 Temple Place[, -]* Suite 330, Boston, MA *02111-1307[, ]* USA/51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA/' -i "$i"
done
Fixes http://bugs.freedesktop.org/show_bug.cgi?id=21356
Damien Carbonne reported that cairo_device_t lacked the language binding
hooks normally associated with cairo objects. So add the missing
get_reference_count, get_user_data and set_user_data.
The device is a generic method for accessing the underlying interface
with the native graphics subsystem, typically the X connection or
perhaps the GL context. By exposing a cairo_device_t on a surface and
its various methods we enable finer control over interoperability with
external interactions of the device by applications. The use case in
mind is, for example, a multi-threaded gstreamer which needs to serialise
its own direct access to the device along with Cairo's across many
threads.
Secondly, the cairo_device_t is a unifying API for the mismash of
backend specific methods for controlling creation of surfaces with
explicit devices and a convenient hook for debugging and introspection.
The principal components of the API are the memory management of:
cairo_device_reference(),
cairo_device_finish() and
cairo_device_destroy();
along with a pair of routines for serialising interaction:
cairo_device_acquire() and
cairo_device_release()
and a method to flush any outstanding accesses:
cairo_device_flush().
The device for a particular surface may be retrieved using:
cairo_surface_get_device().
The device returned is owned by the surface.
