[cairo-commit] [cairo-www] src/operators.mdwn

[Carl Worth]

 src/operators.mdwn |  112 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 111 insertions(+), 1 deletion(-)

New commits:
commit a8b2e530beb1cd5581e00e67d1aae22252c8206a
Author: Carl Worth <cworth at freedesktop.org>
Date:   Thu Jul 3 13:19:05 2008 -0700

    web commit by jpihlaja: Added a section on clipping and masking

diff --git a/src/operators.mdwn b/src/operators.mdwn
index db75964..0fb842c 100644
--- a/src/operators.mdwn
+++ b/src/operators.mdwn
@@ -70,7 +70,8 @@ For some of the operators, both interpretations lead to the same result,
 for others they do not. In cairo, the actual interpretation depends on
 the operator.  The unbounded operators modify destination outside of the
 bounds of the mask.  However, their effect can still be limited by way
-of clipping.
+of clipping.  See the section on <a href="#clipmask">clipping and masking</a>
+for those details.
 
 The blue rectangle is drawn with the new operator in effect:
 
@@ -404,6 +405,115 @@ unbounded source interpretations.
 </tr>
 </table>
 
+<h1 id="clipmask">Clipping and masking</h1>
+
+This section augments the documentation of cairo's compositing model
+by describing how clipping and masking are taken into account when
+rendering.  In this context the <i>clip</i> and <i>mask</i> are treated as
+cairo surfaces with <a
+href=http://cairographics.org/manual/cairo-cairo-surface-t.html#cairo-content-t"">alpha
+content</a> that both default to full opaqueness when not explicitly given.
+The basic approach to clipping in cairo is to first perform the
+operation without clipping and then interpolating by the clip
+pointwise between the unclipped result and the destination.  In the
+descriptions below this is achieved using a ternary operator
+<i>A</i> LERP<i><sub>T</sub></i> <i>B</i> that is defined here as:
+
+<center>
+	<i>A</i> LERP<i><sub>T</sub></i> <i>B</i> := (<i>A</i> IN
+	<i>T</i>) ADD (<i>B</i> OUT <i>T</i>)
+</center>
+
+The approach to masking is to combine it using operator IN with either the <i>clip</i>, for
+the bounded operators, or with the source for the unbounded ones.
+
+There are three distinct rendering equations used within cairo to
+implement clipping and masking, which can be described using the
+(unclipped, unmasked) operators IN, OUT and ADD operators as primitives.
+
+<table align="center" border="1">
+ <tr>
+  <th>Kind</th>
+  <th>Equation</th>
+ </tr>
+ <tr>
+  <td>XRender</td>
+  <td align="right"> ((<i>src</i> IN <i>mask</i>) <i>OP</i> <i>dst</i>) LERP<sub><i>clip</i></sub> <i>dst</i></td>
+ </tr>
+ <tr>
+  <td>Bounded</td>
+  <td align="right"> (<i>src OP dst</i>) LERP<sub>(<i>clip</i> IN <i>mask</i>)</sub> <i>dst</i> </td>
+ </tr>
+ <tr>
+  <td>Simple</td>
+  <td align="right"> (<i>src</i> IN (<i>clip</i> IN <i>mask</i>)) <i>OP</i> <i>dst</i> </td>
+ </tr>
+</table>
+
+The XRender-kind definition most closely matches the letter of the
+XRender specification as it reduces to XRender's equation when
+<i>clip</i> is binary valued -- the only kind of clip talked about in
+the spec.  The Simple-kind definition is the fastest to execute and
+was conceived of as an optimisation of the XRender-kind
+definition to take advantage of the fact that for many operators the two coincide.
+The Bounded definition is a variation of the XRender-kind
+definition where the mask is considered to be a part of the clip.  It
+is used for the SOURCE and CLEAR operators only, and is used 
+to make those operators be explicitly bounded by <i>mask</i>.
+The following table gives the rendering equation used by each of cairo's
+operators.  The entries marked with Any are operators for
+which all three variants coincide.
+
+<table align="center" border="1">
+ <tr>
+  <th>Operator</th>
+  <th>Kind</th>
+  <th>Operator</th>
+  <th>Kind</th>
+ </tr>
+ <tr>
+  <td>CLEAR</td>
+  <td>Bounded</td>
+  <td>SOURCE</td>
+  <td>Bounded</td>
+ </tr>
+ <tr>
+  <td>OVER</td>
+  <td>Any</td>
+  <td>IN</td>
+  <td>XRender</td>
+ </tr>
+ <tr>
+  <td>OUT</td>
+  <td>XRender</td>
+  <td>ATOP</td>
+  <td>Any</td>
+ </tr>
+ <tr>
+  <td>DEST</td>
+  <td>Any</td>
+  <td>DEST_OVER</td>
+  <td>Any</td>
+ </tr>
+ <tr>
+  <td>DEST_IN</td>
+  <td>XRender</td>
+  <td>DEST_OUT</td>
+  <td>Any</td>
+ </tr>
+ <tr>
+  <td>DEST_ATOP</td>
+  <td>XRender</td>
+  <td>XOR</td>
+  <td>Any</td>
+ </tr>
+ <tr>
+  <td>ADD</td>
+  <td>Any</td>
+  <td>SATURATE</td>
+  <td>Simple</td>
+ </tr>
+</table>
 
 <h1 id="links">Links</h1>