[css-masking] Change compositing operators to add, subtract, interese…

…ct and exclude. Add more normative descriptions and better examples.

css-masking-1/Overview.src.html

@@ -714,8 +714,8 @@ <h3 id="the-mask-composite">Compositing mask layers: the 'mask-composite' proper
 
 <pre class='propdef'>
 Name: mask-composite
-Value: <<composite-mode>>#
-Initial: source-over
+Value: <<compositing-operator>>#
+Initial: add
 Applies to: All elements. In SVG, it applies to <a>container elements</a> without the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
 Percentages: n/a
@@ -724,38 +724,117 @@ <h3 id="the-mask-composite">Compositing mask layers: the 'mask-composite' proper
 Animatable: no
 </pre>
 
-Defines a Porter Duff compositing operator for each mask layer [[!COMPOSITING-1]].
+<pre class=prod><dfn>&lt;compositing-operator></dfn> = add | subtract | intersect | exclude</pre>
 
-A specified compositing operator defines the compositing operation for the current mask layer with the immediate mask layer below it. If there is no further mask layer, the compositing operator must be ignored. Mask layers must not composite with the element's content or the content behind the element, instead they must act as if they are rendered into an isolated group.
+Each keyword represents a Porter-Duff compositing operator [[!COMPOSITING-1]] which defines the compositing operation used on the current mask layer with the mask layers below it.
+
+In the following, the current mask layer is referred to <dfn>source</dfn>, all mask layers below it (with the corresponding compositing operators applied) are referred to <dfn>destination</dfn>.
+
+<dl dfn-for=mask-composite dfn-type=value>
+  <dt><dfn>add</dfn></dt>
+  <dd>The <i>source</i> is placed over the <i>destination</i>. (See Porter-Duff compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcover'>source over</a> for more details.)</dd>
+  <dt><dfn>subtract</dfn></dt>
+  <dd>The <i>source</i> is placed, where it falls outside of the <i>destination</i>. (See Porter-Duff compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcout'>source out</a> for more details.)</dd>
+  <dt><dfn>intersect</dfn></dt>
+  <dd>The parts of <i>source</i> that overlap the <i>destination</i>, replace the <i>destination</i>. (See Porter-Duff compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcin'>source in</a> .)</dd>
+  <dt><dfn>exclude</dfn></dt>
+  <dd>The non-overlapping regions of <i>source</i> and <i>destination</i> are combined. (See Porter-Duff compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_xor'>XOR</a>.)</dd>
+</dl>
+
+If there is no further mask layer, the compositing operator must be ignored. Mask layers must not composite with the element's content or the content behind the element, instead they must act as if they are rendered into an isolated group.
+
+All mask layers below the current mask layer must be composited before applying the compositing operation for the current mask layer.
 
 <div class=example>
-An example of the initial compositing operator <em>source-over</em>. Both mask layers will be drawn on top of each other. The result will be used to mask the content of the element.
+<p>This example uses two mask images: <var>circle.svg</var> and <var>rect.svg</var>.</p>
+
+<div class=figure>
+  <img src="images/mask-source-destination.svg" width="440" height="240" alt="Example of source-over compositing of mask layers">
+</div>
+
+<p>Both mask images are references with the 'mask-image' property:</p>
 
 <pre><code class=css>
 mask-image: circle.svg, rect.svg;
-mask-composite: source-over;
 </code></pre>
-<img src="images/mask-source-over.svg" width="665" height="260" alt="Example of source-over compositing of mask layers">
+
+<p>The mask layer with <var>rect.svg</var> is below the mask layer with <var>circle.svg</var>. That means <var>circle.svg</var> is closer to the user than <var>rect.svg</var>.</p>
+
+<p>With the property 'mask-composite' the author may choose different ways to combine multiple mask layers.</p>
+
+<ul>
+<li>
+<p><var>add</var> paints the <var>circle.svg</var> on top of <var>rect.svg</var>. The behavior is described by the compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcover'>source over</a>.</p>
+
+<pre><code class=css>
+mask-composite: add;
+</code></pre>
+
+<div class=figure>
+  <img src="images/mask-composite-add.svg" width="220" height="220" alt="Example of source-over compositing of mask layers">
+</div>
+</li>
+<li>
+<p><var>subtract</var> paints portions of <var>circle.svg</var> that do not overlap <var>rect.svg</var>. The behavior is described by the compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcout'>source out</a>.</p>
+
+<pre><code class=css>
+mask-composite: subtract;
+</code></pre>
+
+<div class=figure>
+  <img src="images/mask-composite-subtract.svg" width="220" height="220" alt="Example of source-over compositing of mask layers">
+</div>
+</li>
+<li>
+<p><var>intersect</var> paints portions of <var>circle.svg</var> that overlap <var>rect.svg</var>. The behavior is described by the compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcin'>source in</a>.</p>
+
+<pre><code class=css>
+mask-composite: intersect;
+</code></pre>
+
+<div class=figure>
+  <img src="images/mask-composite-intersect.svg" width="220" height="220" alt="Example of source-over compositing of mask layers">
+</div>
+</li>
+<li>
+<p><var>exclude</var> paints portions of <var>circle.svg</var> and <var>rect.svg</var> that do not overlap. The behavior is described by the compositing operator <a href='http://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_xor'>XOR</a>.</p>
+
+<pre><code class=css>
+mask-composite: exclude;
+</code></pre>
+
+<div class=figure>
+  <img src="images/mask-composite-exclude.svg" width="220" height="220" alt="Example of source-over compositing of mask layers">
+</div>
+</li>
+</ul>
 </div>
 
 <div class=example>
-An example of the compositing operator <em>destination-in</em>. The top layer “masks” the mask layer below. Just areas where both, <code>circle.svg</code> and <code>rect.svg</code> are visible will be used as mask.
+<p>The following example specifies two mask layers and two compositing operators.</p>
 
 <pre><code class=css>
-mask-image: circle.svg, rect.svg;
-mask-composite: destination-in;
+mask-image: rect.svg, circle.svg;
+mask-composite: add, exclude;
 </code></pre>
-<img src="images/mask-destination-in.svg" width="665" height="260" alt="Example of destination-in compositing of mask layers">
+
+<var>rect.svg</var> and <var>circle.svg</var> make use of the <var>add</var> compositing operator. There is no further mask layer to use <var>exclude</var> and therefore, <var>exclude</var> is ignored.
 </div>
 
 <div class=example>
-An example of the compositing operator <em>xor</em>. The resulting mask will be the visible areas of <code>circle.svg</code> and <code>rect.svg</code> where both do NOT overlap.
+<p>This is an example of 3 mask layers with different compositing operators.</p>
 
 <pre><code class=css>
-mask-image: circle.svg, rect.svg;
-mask-composite: xor;
+mask-image: trapeze.svg, circle.svg, rect.svg;
+mask-composite: subtract, add;
 </code></pre>
-<img src="images/mask-xor.svg" width="665" height="260" alt="Example of xor compositing of mask layers">
+
+<p>First, <var>circle.svg</var> is “added” to <var>rect.svg</var>. In a second step, <var>trapeze.svg</var> is “subtracted” from the previous two layers.</p>
+
+<div class=figure>
+  <img src="images/mask-composite-subtract-add.svg" width="440" height="240" alt="Example of source-over compositing of mask layers">
+</div>
+
 </div>
 
 See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-composite' interacts with other comma-separated mask properties to form each mask image layer.
@@ -775,7 +854,7 @@ <h3 id="the-mask">Mask Shorthand: the 'mask' property</h3>
 </pre>
 
 <pre class=prod><dfn>&lt;mask-layer></dfn> = <<mask-reference>> <<source-type>>? || <<position>> [ / <<bg-size>> ]? ||
-    <<repeat-style>> || <<geometry-box>> || [ <<geometry-box>> | no-clip ] || <<composite-mode>></pre>
+    <<repeat-style>> || <<geometry-box>> || [ <<geometry-box>> | no-clip ] || <<compositing-operator>></pre>
 
 If one <<geometry-box>> value is present then it sets both 'mask-origin' and 'mask-clip' to that value. If two <<geometry-box>> values are present, then the first sets 'mask-origin' and the second 'mask-clip'.
 
@@ -902,7 +981,7 @@ <h3 id="the-mask-box-slice">Mask Image Slicing: the 'mask-box-slice' property</h
 Animatable: no
 </pre>
 
-This property specifies inward offsets from the top, right, bottom, and left edges of the mask image, dividing it into nine regions: four corners, four edges and a middle. The middle image part is discarded (treated as fully transparent black) unless the <dfn dfn-for=mask-box-slice dfn-type=value>fill</dfn> keyword is present.
+This property specifies inward offsets from the top, right, bottom, and left edges of the mask image, dividing it into nine regions: four corners, four edges and a middle. The middle image part is discarded (treated as fully transparent white) unless the <dfn dfn-for=mask-box-slice dfn-type=value>fill</dfn> keyword is present.
 
 See the 'border-image-slice' property [[!CSS3BG]] for the definitions of the property values.