Add multiple mask layers back to the spec. Add mask-composite property.

Author: dirkschulze

css-masking-1/Overview.src.html

@@ -76,6 +76,8 @@ <h2 id="placement">Module interactions</h2>
 
 The compositing model follows the SVG compositing model [[!SVG11]]: First the element is styled under absence of filter effects, masking, clipping and opacity. Then the element and its descendants are drawn on a temporary canvas. In a last step the following effects are applied to the element in order: filter effects [[FILTER-EFFECTS]], clipping, masking and opacity.
 
+This specification allows compositing multiple mask layers with the Porter Duff compositing operators defined in CSS Compositing and Blending [[!COMPOSITING-1]].
+
 The terms <i>object bounding box</i> and <i>stroke bounding box</i> follow the definitions in SVG 2 [[!SVG2]].
 
 <h2 id="values">Values</h2>
@@ -344,7 +346,7 @@ <h3 id="the-mask-image">Mask Image Source: the 'mask-image' property</h3>
 
 <pre class='propdef'>
 Name: mask-image
-Value: <<mask-reference>>
+Value: <<mask-reference>>#
 Initial: none
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
@@ -367,16 +369,20 @@ <h3 id="the-mask-image">Mask Image Source: the 'mask-image' property</h3>
   </dd>
   <dt>none</dt>
   <dd>
-    A value of ''none'' counts as an image layer but does not mask the element.
+    A value of ''none'' counts as a transparent black image layer.
   </dd>
 </dl>
 
 A computed value of other than ''none'' results in the creation of a <a spec="css21">stacking context</a> [[!CSS21]] the same way that CSS 'opacity' [[CSS3COLOR]] does for values other than ''1''.
 
-A mask reference that is an empty image (zero width or zero height), that fails to download, is not a reference to an <a element>mask</a> element, is non-existent, or that cannot be displayed (e.g. because it is not in a supported image format) is ignored. It still counts as an image layer but does not mask the element.
+A mask reference that is an empty image (zero width or zero height), that fails to download, is not a reference to an <a element>mask</a> element, is non-existent, or that cannot be displayed (e.g. because it is not in a supported image format) still counts as an image layer of transparent black.
 
 See the section <a href="#MaskValues">“Mask processing”</a> for how to process a mask image.
 
+Note: A value of ''none'' in a list of <<mask-reference>>s may influence the masking operation depending on the used compositing operator specified by 'mask-composite'.
+
+Note: A <<mask-source>> counts as mask layer and can be combined in a repeatable <<mask-reference>> list with <<image>> or further <<mask-source>> list items. 
+
 Note: An element can also be masked with 'mask-box-source'. See 'mask-box-source' for the interaction of that property with 'mask-image'.
 
 <div class="example">
@@ -387,11 +393,13 @@ <h3 id="the-mask-image">Mask Image Source: the 'mask-image' property</h3>
 div { mask-image: url(resources.svg#mask2) }</code></pre>
 </div>
 
+See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-image' interacts with other comma-separated mask properties to form each mask image layer.
+
 <h3 id="the-mask-type">Mask Image Interpretation: the 'mask-type' property</h3>
 
 <pre class='propdef'>
 Name: mask-type
-Value: <<source-type>>
+Value: <<source-type>>#
 Initial: auto
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
@@ -445,11 +453,13 @@ <h3 id="the-mask-type">Mask Image Interpretation: the 'mask-type' property</h3>
 &lt;rect width="200" height="200" fill="green"/&gt;</code></pre>
 </div>
 
+See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-type' interacts with other comma-separated mask properties to form each mask image layer.
+
 <h3 id="the-mask-repeat">Tiling Mask Images: The 'mask-repeat' property</h3>
 
 <pre class='propdef'>
 Name: mask-repeat
-Value: <<repeat-style>>
+Value: <<repeat-style>>#
 Initial: no-repeat
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
@@ -480,18 +490,20 @@ <h3 id="the-mask-repeat">Tiling Mask Images: The 'mask-repeat' property</h3>
   </div>
 </div>
 
+See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-repeat' interacts with other comma-separated mask properties to form each mask image layer.
+
 <h3 id="the-mask-position">Positioning Mask Images: the 'mask-position' property</h3>
 
 <pre class='propdef'>
 Name: mask-position
-Value: <<position>>
+Value: <<position>>#
 Initial: center
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
 Percentages: refer to size of <i>mask painting area</i> <em>minus</em> size of mask image; see text 'background-position' [[!CSS3BG]]
 Computed value: Consisting of: two keywords representing the origin and two offsets from that origin, each given as an absolute length (if given a <<length>>), otherwise as a percentage.
 Media: visual
-Animatable: as <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-simple-list">simple list</a> of <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-lpcalc">length, percentage, or calc
+Animatable: as <a href="http://www.w3.org/TR/css3-transitions/#animtype-repeatable-list">repeatable list</a> of <a href="http://www.w3.org/TR/css3-transitions/#animtype-simple-list">simple list</a> of <a href="http://www.w3.org/TR/css3-transitions/#animtype-lpcalc">length, percentage, or calc
 </pre>
 
 See the 'background-position' property [[!CSS3BG]] for the definitions of the property values.
@@ -513,11 +525,13 @@ <h3 id="the-mask-position">Positioning Mask Images: the 'mask-position' property
 <pre><code class=css>mask-position: right 3em bottom 10px</code></pre>
 </div>
 
+See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-position' interacts with other comma-separated mask properties to form each mask image layer.
+
 <h3 id="the-mask-clip">Masking Area: the 'mask-clip' property</h3>
 
 <pre class='propdef'>
 Name: mask-clip
-Value: <<geometry-box>> | no-clip
+Value: [ <<geometry-box>> | no-clip ]#
 Initial: border-box
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
@@ -576,11 +590,13 @@ <h3 id="the-mask-clip">Masking Area: the 'mask-clip' property</h3>
 
 For elements with associated CSS layout box, the values <a value for=mask-clip>fill-box</a>, <a value for=mask-clip>stroke-box</a> and <a value for=mask-clip>view-box</a> compute to the initial value of 'mask-clip'.
 
+See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-clip' interacts with other comma-separated mask properties to form each mask image layer.
+
 <h3 id="the-mask-origin">Positioning Area: the 'mask-origin' property</h3>
 
 <pre class='propdef'>
 Name: mask-origin
-Value: <<geometry-box>>
+Value: <<geometry-box>>#
 Initial: border-box
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
@@ -635,29 +651,83 @@ <h3 id="the-mask-origin">Positioning Area: the 'mask-origin' property</h3>
 
 Note: If 'mask-clip' is <a value for=mask-origin>padding-box</a>, 'mask-origin' is <a value for=mask-origin>border-box</a>, 'mask-position' is ''top left'' (the initial value), and the element has a non-zero border, then the top and left of the mask image will be clipped.
 
+See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-origin' interacts with other comma-separated mask properties to form each mask image layer.
+
 <h3 id="the-mask-size">Sizing Mask Images: the 'mask-size' property</h3>
 
 <pre class='propdef'>
 Name: mask-size
-Value: <<bg-size>>
+Value: <<bg-size>>#
 Initial: border-box
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
 Percentages: n/a
 Computed value: as specified, but with lengths made absolute
 Media: visual
-Animatable: as <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-simple-list">simple list</a> of <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-lpcalc">length, percentage, or calc</a> (<span class="note">This means keyword values are not animatable.</span>)
+Animatable: as <a href="http://www.w3.org/TR/css3-transitions/#animtype-repeatable-list">repeatable list</a> of <a href="http://www.w3.org/TR/css3-transitions/#animtype-simple-list">simple list</a> of <a href="http://www.w3.org/TR/css3-transitions/#animtype-lpcalc">length, percentage, or calc</a> (<span class="note">This means keyword values are not animatable.</span>)
 </pre>
 
 Specifies the size of the mask images.
 
 See 'background-size' property [[!CSS3BG]] for the definitions of the property values.
 
+See the section <a href="#layering">“Layering multiple mask images”</a> for how 'mask-size' interacts with other comma-separated mask properties to form each mask image layer.
+
+<h3 id="the-mask-composite">Compositing mask layers: the 'mask-composite' property</h3>
+
+<pre class='propdef'>
+Name: mask-composite
+Value: <<composite-mode>>#
+Initial: source-over
+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
+Computed value: as specified
+Media: visual
+Animatable: no
+</pre>
+
+Defines a Porter Duff compositing operator for each mask layer [[!COMPOSITING-1]].
+
+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.
+
+<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.
+
+<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">
+</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.
+
+<pre><code class=css>
+mask-image: circle.svg, rect.svg;
+mask-composite: destination-in;
+</code></pre>
+<img src="images/mask-destination-in.svg" width="665" height="260" alt="Example of destination-in compositing of mask layers">
+</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.
+
+<pre><code class=css>
+mask-image: circle.svg, rect.svg;
+mask-composite: xor;
+</code></pre>
+<img src="images/mask-xor.svg" width="665" height="260" alt="Example of xor compositing of mask layers">
+</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.
+
 <h3 id="the-mask">Mask Shorthand: the 'mask' property</h3>
 
 <pre class='propdef'>
 Name: mask
-Value: <<mask-layer>>
+Value: <<mask-layer>>#
 Initial: see individual properties
 Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a>'defs'</a> element and all <a>graphics elements</a>
 Inherited: no
@@ -668,7 +738,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 ]</pre>
+    <<repeat-style>> || <<geometry-box>> || [ <<geometry-box>> | no-clip ] || <<composite-mode>></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'.
 
@@ -718,6 +788,14 @@ <h4 id="MaskValues">Mask processing</h4>
 
 Note: Masks with repeating mask image tiles may have an offset to each other. The space between the mask images is treated as a transparent black mask.
 
+<h4 id="layering">Layering Multiple Mask Images</h4>
+
+The mask of a box can have multiple layers. The number of layers is determined by the number of comma-separated values for the 'mask-image' property. A value of ''none'' in a list of values with other <<mask-reference>>s still creates a layer.
+
+See <a href="http://www.w3.org/TR/css3-background/#layering">Layering Multiple Background Images</a> [[!CSS3BG]].
+
+All mask images are transformed to alpha masks (if necessary see <a href="#MaskValue">Mask processing</a>) and combined by compositing taking the compositing operators specified by 'mask-composite' into account.
+
 <h2 id="box-masks">Box Masks</h2>
 
 With 'mask-box' an image can be split into nine pieces: four corners, four edges and the middle piece as demonstrated in the figure below.