[cairo] More docs

[Russell Shaw]

Owen Taylor wrote:
> On Mon, 2005-08-15 at 00:14 +1000, Russell Shaw wrote:
> 
>>Owen Taylor wrote:
>>
>>>On Sun, 2005-08-14 at 23:13 +1000, Russell Shaw wrote:
>>>
>>>
>>>>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:
>>>
>>>If you are doing this inline (and I don't think this should be inline;
>>>while what you have is a good start, there's quite a bit of more
>>>information that should be provided to the user: it needs pictures and
>>>descriptions of what the operators used for, so I'd put the stuff into a
>>>separate .sgml file and then just refer to it from the cairo_operator_t
>>>description), then the "trick" used in gtk-doc is, instead of using a
>>>blank line, to use a line with a single space on it.
>>
>>What do you mean by "instead of using a blank line" ? I tried all combinations
>>of adding and omitting blanklines without success. I even found that a pre-existing
>><programlisting> later in the same file causes the same problems.
> 
> An empty line - nothing on it - causes gtk-doc to add a <para>, but a
> line with a single space on it doesn't trigger this behavior.

Ok, i tried putting spaces in before and it didn't work. This time
it did work :-/
-------------- next part --------------
--- cairo-old/src/cairo.h	2005-08-14 15:30:08.000000000 +1000
+++ cairo/src/cairo.h	2005-08-15 01:15:37.000000000 +1000
@@ -260,6 +260,67 @@
 
 /* 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:
+ * 
+ * <programlisting>
+ * 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;
+ *   
+ * <emphasis>OP</emphasis>           <emphasis>Ao.Co</emphasis>
+ *   
+ * 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
+ * </programlisting>
+ * 
+ * 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,