[cairo] More docs

[Russell Shaw]

I had to put in ugly extra blank lines because gtkdoc-mkdb seems to have
bugs. If you have:

<programlisting>
Ao.Co = Aa.Ca &lt;OP&gt; Ab.Cb
...

then the xml generated has:

<para>
<programlisting>
Ao.Co = Aa.Ca &lt;OP&gt; Ab.Cb
</para>
...

I spent far more time trying to debug gtkdoc than it took to find all the
cairo papers on the net, understand them, and make this doc:


--- cairo-old/src/cairo.h       2005-08-14 15:30:08.000000000 +1000
+++ cairo/src/cairo.h   2005-08-14 22:49:30.000000000 +1000
@@ -260,6 +260,76 @@

  /* Modify state */

+/**
+ * cairo_operator_t
+ *
+ * Colour in Cairo is represented as a C = (R,G,B,A) quadruple, where R,G, and B
+ * are the red, green, and blue components of a pixel (not to be confused with
+ * Xlib notation of a pixel as a colormap index). &quot;A&quot; is the alpha component (or
+ * channel) that represents the strength of the pixel.
+ *
+ * With A=0, the pixel is clear, and with A=1, the pixel is opaque, letting none
+ * of the background show through. Any intermediate opacity is represented as
+ * A.C = (A.R, A.G, A.B, A).  Note that it is not C = (R,G,B,A). This
+ * pre-multiplication saves that operation from being performed in later
+ * compositing steps.
+ *
+ * The foregoing assumed the pixel is fully covered by the object in question.
+ * When a sharp edge that partially overlaps pixels is considered, an averaged
+ * alpha (equivalent opacity strength) can be inferred. The resulting colour is
+ * calculated by:
+ *
+ * dest = (source OP_IN mask) &lt;OP&gt; dest
+ *
+ * where &quot;source&quot;, &quot;mask&quot;, and &quot;dest&quot; are objects
+ * partially overlapping a pixel and &lt;OP&gt; are types of overlap as defined
+ * in a paper by Porter and Duff[1].
+ *
+ * Consider an object &quot;A&quot; of colour Ca, covering a pixel by a factor of Fa. The
+ * resulting averaged colour of the pixel is Fa.Ca. If another object &quot;B&quot; also
+ * partially overlaps the pixel, the resultant average colour depends on how the
+ * objects overlap.  The resultant average colour of the pixel is calculated as:
+ *
+ * Ao.Co = Aa.Ca &lt;OP&gt; Ab.Cb
+ *
+ * Ao.Co = (Ao.Ro, Ao.Go, Ao.Bo, Ao)
+ *
+ * Aa.Ca = (Aa.Ra, Aa.Ga, Aa.Ba, Aa)
+ *
+ * Ab.Cb = (Ab.Rb, Ab.Gb, Ab.Bb, Ab)
+ *
+ * Rx: red component of colour &quot;x&quot;
+ *
+ * Gx: green component of colour &quot;x&quot;
+ *
+ * Bx: blue component of colour &quot;x&quot;
+ *
+ * Ax: alpha of colour &quot;x&quot;
+ *
+ *
+ * &lt;OP&gt;  Ao.Co
+ *
+ * OP_CLEAR    (0,0,0,0)
+ *
+ * OP_SOURCE   Fa.Ca = (Fa.Aa.Ra, Fa.Aa.Ga, Fa.Aa.Ba, Fa)
+ *
+ * OP_OVER     Fa.Ca + (Fb-Fo).Cb
+ *
+ * OP_IN       Fo.Ca
+ *
+ * OP_OUT      (Fa-Fo).Ca
+ *
+ * OP_ATOP     Fo.Ca + (Fb-Fo).Cb
+ *
+ * where Fo is the fraction of the pixel that is overlapped by both objects A
+ * and B.
+ *
+ * [1]
+ * Compositing Digital Images
+ * Thomas Porter, Tom Duff
+ * Computer Graphics, Vol.18, No.3, July 1984.
+ */
+
  typedef enum _cairo_operator {
      CAIRO_OPERATOR_CLEAR,