[Mesa-dev] [PATCH 1/2] gl: Add a first bit of general documentation on cairo-gl usage.
eric at anholt.net
Mon Feb 21 14:36:23 PST 2011
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.
src/cairo-gl.h | 26 ++++++++++++++++++++++++++
1 files changed, 26 insertions(+), 0 deletions(-)
diff --git a/src/cairo-gl.h b/src/cairo-gl.h
index 131d114..9efde43 100644
@@ -31,6 +31,32 @@
* 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.
More information about the mesa-dev