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

[Eric Anholt]

Since its inception, cairo-gl has been plagued by the "how am I really
supposed to use it?" problem.  This lays down my expectations for how
cairo-gl will interact with other usage of the GL API.  It covers the
common cases of "I want to paint some cairo UI on my GL app" or "I
want to use some GL texture as a cairo surface".  It does not provide
a satisfying solution to GStreamer's threading requirements, but the
proposed solution remains compatible with GStreamer's current direct
interaction with OpenGL.
---
 src/cairo-gl.h |   33 +++++++++++++++++++++++++++++++++
 1 files changed, 33 insertions(+), 0 deletions(-)

diff --git a/src/cairo-gl.h b/src/cairo-gl.h
index 131d114..ae24ac6 100644
--- a/src/cairo-gl.h
+++ b/src/cairo-gl.h
@@ -31,6 +31,39 @@
  * The Initial Developer of the Original Code is Eric Anholt.
  */
 
+/**
+ * @file cairo-gl.h
+ *
+ * The cairo-gl backend provides an implementation of possibly
+ * hardware-accelerated cairo rendering by targeting the OpenGL API.
+ * The goal of the cairo-gl backend is to provide better performance
+ * with equal functionality to cairo-image where possible.  It does
+ * not directly provide for applying additional OpenGL effects to
+ * cairo surfaces.
+ *
+ * Cairo-gl allows interoperability with other GL rendering through GL
+ * context sharing.  Cairo-gl surfaces are created in reference to a
+ * cairo_device_t, which represents an GL context created by the user.
+ * When that GL context is created with its sharePtr set to another
+ * context (or vice versa), its objects (textures backing cairo-gl
+ * surfaces) can be accessed in the other OpenGL context.  This allows
+ * cairo-gl to maintain its drawing state in one context while the
+ * user's 3D rendering occurs in the user's other context.
+ *
+ * However, as only one context can be current to a thread at a time,
+ * cairo-gl may make its context current to the thread on any cairo
+ * call which interacts with a cairo-gl surface or the cairo-gl
+ * device.  As a result, the user must make their own context current
+ * between any cairo calls and their own OpenGL rendering
+ *
+ * Cairo-gl does not unbind its context after its rendering, and
+ * OpenGL requires that a context being bound to a thread not
+ * currently be bound to a different thread .  Therefore, an
+ * application using cairo-gl surfaces from multiple threads must
+ * manually unbind the cairo_device_t's context from the leaving
+ * thread before calling cairo from the entering thread.
+ */
+
 #ifndef CAIRO_GL_H
 #define CAIRO_GL_H
 
-- 
1.7.2.3