drafts: masking/Masking.src.html@59236286d848

     1 <!DOCTYPE html public '-//W3C//DTD HTML 4.01//EN'

     2   'http://www.w3.org/TR/html4/strict.dtd'>

     3 <html lang="en">

     4 <head>

     5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

     6   <title>CSS Masking</title>

     7   <link rel=contents href="#contents">

     8   <link rel=index href="#index">

     9   <link rel="stylesheet" type="text/css" href="default.css">

    10   <link rel="stylesheet" type="text/css"

    11         href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">

    12   <script defer=defer

    13     src="http://test.csswg.org/harness/annotate.js#CSS-MASKING_DEV"

    14     type="text/javascript"></script>

    15 </head>

    17 <div class="head">

    18 <!--logo-->

    20 <h1>CSS Masking</h1>

    22 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>

    23 <dl>

    24   <dt>This version:

    25     <dd><a href="http://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html">http://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html</a>

    26     <!--http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]/-->

    28   <dt>Latest version:

    29     <dd><a href="http://www.w3.org/TR/css-masking/">[LATEST]</a>

    31   <dt>Editor's draft:

    32     <dd><a href="http://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html">http://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html</a>

    34   <dt>Editors:

    35   <dd class="vcard">

    36     <span class="fn">Dirk Schulze</span>,

    37     <span class="org">Adobe Systems</span>,

    38     <span class="email">dschulze@adobe.com</span>

    39   </dd>

    40   <dd class="vcard">

    41     <span class="fn">Brian Birtles</span>,

    42     <span class="org">Mozilla Japan</span>,

    43     <span class="email">bbirtles@mozilla.com</span>

    44   </dd>

    45   <dd class="vcard">

    46     <span class="fn"><a href="http://www.xanthir.com/contact/">Tab Atkins Jr.</a></span>,

    47     <span class="org">Google, Inc.</span>

    48   </dd>

    49 </dl>

    51 <!--copyright-->

    53 <hr title="Separator for header">

    54 </div>

    56 <h2 class="no-num no-toc" id="abstract">Abstract</h2>

    58 <p>

    59   CSS Masking provides two means for partially or fully hiding portions of

    60   visual elements: masking and clipping.

    61 </p>

    63 <p>

    64   Masking describes how to use another graphical element or image as a luminance

    65   or alpha mask.

    66   Typically, rendering an element via CSS or SVG can conceptually described as if the element,

    67   including its children, are drawn into a buffer and then that buffer is composited

    68   into the element's parent.

    69   Luminance and alpha masks influence the transparency of this buffer before the

    70   compositing stage.

    71 </p>

    73 <p>

    74   Clipping describes the visible region of visual elements.

    75   The region can be described by using certain SVG graphics elements or basic

    76   shapes.

    77   Anything outside of this region is not rendered.

    78 </p>

    80 <h2 class="no-num no-toc" id="status">Status of this document</h2>

    82 <!--status-->

    84 <h2 class="no-num no-toc" id="contents">

    85 Table of contents</h2>

    87 <!--toc-->

    89 <h2 id="intro">

    90   Introduction

    91 </h2>

    93 <p>

    94   With CSS Masking it is possible to specify another graphics element, shape or file

    95   to be used as clipping region or an luminance or alpha mask for compositing the current object into the

    96   background.

    97 </p>

    99 <p>

   100   A mask is applied using the 'mask', 'mask-image' or 'mask-box-image' properties.

   101   The mask source may be defined using a <a>'mask element'</a> element referenced

   102   by the 'mask' property.

   103   Alternatively, for many simple uses, the 'mask-image' property may

   104   refer directly to graphical elements or images to be used as mask

   105   forgoing the need for an explicit <a>'mask element'</a> element. The

   106   'mask' property is also a shorthand for other masking properties.

   107   'mask-box-image' splits a mask image into 9 pieces. The pieces may be sliced,

   108   scaled and stretched in various ways to fit the size of the mask image area.

   109 </p>

   111 <p>

   112   The effect of applying a mask is as if the mask images or mask source elements are

   113   rendered into an off-screen image which has been initialized to transparent

   114   black.

   115   The graphical object to which the mask is applied

   116   will be painted onto the background through the

   117   mask, thus completely or partially masking out parts of the graphical

   118   object.

   119 </p>

   121 <p>

   122   Clipping defines a visible region of a visual element. The region can be specified with SVG <a>graphics element</a> or

   123   basic shapes. Everything outside of a region does not get rendered.

   124 </p>

   126 <div class="example">

   127   <div class=figure>

   128     <img src="images/luminance-mask.svg" width="655px" height="260px" alt="Example Mask">

   129     <p class=caption>

   130       A luminance mask (middle) is applied on a shape filled with a gradient (left). This results in a masked shape

   131       (right).

   132     </p>

   133   </div>

   134 </div>

   136 <h2 id="placement">Module interactions</h2>

   138 <p>This specification defines a set of CSS properties that affect the visual rendering of elements to which

   139   those properties are applied; these effects are applied after elements have been sized and positioned according

   140   to the <a href="http://www.w3.org/TR/CSS2/visuren.html" title="Visual formatting model">Visual formatting model</a>

   141   from [[!CSS21]]. Some values of these properties result in the creation of a

   142   <a href="http://www.w3.org/TR/CSS2/visuren.html#containing-block" title="Visual formatting model">containing block</a>,

   143   and/or the creation of a <a href="http://www.w3.org/TR/CSS2/visuren.html#z-index" title="Visual formatting model">stacking

   144   context</a>.

   145 </p>

   147 <p>

   148   Definitions of CSS properties and values in this specification comply with defintions in CSS Backgrounds and Borders [[!CSS3BG]]. To avoid redundancy, this specification relies on descriptions and definitions of CSS Backgrounds and Borders. Every reference will be marked clearly. The following terms in CSS Backgrounds and Borders have the following meaning in this specification:

   149 </p>

   151 <table class="data" id="term-matching">

   152   <thead>

   153     <tr>

   154       <th>Term in [[!CSS3BG]]

   155       <th>Term in CSS Masking

   156     </tr>

   157   </thead>

   158   <tbody>

   159     <tr>

   160       <th>background images

   161       <td>mask images

   162     </tr>

   163     <tr>

   164       <th>background painting area

   165       <td>mask painting area

   166     </tr>

   167     <tr>

   168       <th>background-size

   169       <td>mask-size

   170     </tr>

   171     <tr>

   172       <th>background-position

   173       <td>mask-position

   174     </tr>

   175     <tr>

   176       <th>background positioning area

   177       <td>mask positioning area

   178     </tr>

   179     <tr>

   180       <th>border image area

   181       <td>mask box image area

   182     </tr>

   183   </tbody>

   184 </table>

   186 <p>

   187   Some property and element definitions in this specification require an SVG 1.1 implementation [[!SVG11]]. UAs without

   188   support for SVG must not implement any of the following properties and elements: 'mask-type', 'clip-rule', <a>'clipPath element'</a> element, <a>'mask element'</a> element. For UAs without

   189   support for SVG, the 'mask' and 'clip-path' properties must neither support references to

   190   <a>'mask element'</a> elements nor to <a>'clipPath element'</a> elements.

   191 </p>

   193 <h2 id="values">Values</h2>

   195 <p>

   196   This specification follows the <a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition

   197   conventions</a> from [[!CSS21]]. Value types not defined in this specification are defined in CSS Values and Units Module Level 3 [[!CSS3VAL]].

   198 </p>

   200 <p>

   201   In addition to the property-specific values listed in their definitions, all properties defined in this specification

   202   also accept the <a href="http://www.w3.org/TR/CSS21/cascade.html#value-def-inherit">inherit</a> keyword as their

   203   property value. For readability it has not been repeated explicitly.

   204 </p>

   206 <h2 id="definitions">Definitions</h2>

   208 <p>

   209   When used in this specification, terms have the meanings assigned in this section.

   210 </p>

   212 <dl>

   213 <dt id="TermClientBoundingRect"><dfn>bounding client rect</dfn></dt>

   214 <dd>

   215   <p>

   216     The union of all border boxes for the element that has an associated CSS layout box and is not

   217     in the <code>http://www.w3.org/2000/svg</code> namespace and its descendant elements. Or the

   218     object bounding box [[!SVG11]], if the element does not have

   219     an associated CSS layout box and is in the <code>http://www.w3.org/2000/svg</code> namespace

   220     (See <a href="http://www.w3.org/TR/cssom-view/#dom-element-getboundingclientrect">getBoundingClientRect</a>

   221     [[CSSOM-VIEW]]).

   222   </p>

   223 </dd>

   224 <dt id="TermLocalCoordinateSystem"><dfn>local coordinate system</dfn></dt>

   225 <dd>

   226   <p>

   227     In general, a coordinate system defines locations and distances on the current

   228     canvas. The current local coordinate system (also user coordinate system) is the

   229     coordinate system that is currently active and which is used to define how

   230     coordinates and lengths are located and computed, respectively, on the current

   231     canvas [[CSS3-TRANSFORMS]].

   232   </p>

   233   <p>

   234     For elements that have an associated CSS layout box, the current user coordinate system has its origin at

   235     the top-left corner of the <span class="term">bounding client rect</span> and one unit equals one CSS pixel.

   236     The viewport for resolving percentage values is defined by the width and height of the

   237     <span class="term">bounding client rect</span>.

   238   </p>

   239   <p>

   240     If the element does not have an associated CSS layout box and is in the <code>http://www.w3.org/2000/svg</code>

   241     namespace, the current local coordinate system has its origin at the top-left corner of the element's

   242     nearest viewport.

   243   </p>

   244 </dd>

   245 <dt id="TermUserCoordinateSystem"><dfn>user coordinate system</dfn></dt>

   246 <dd>

   247   The term <var>user coordinate system</var> is equivalent to the term <var>local coordinate system</var>.

   248 </dd>

   249 <dt id="TermObjectBoundingBoxUnits"><dfn>object bounding box units</dfn></dt>

   250 <dd>

   251   The <span class="term">bounding client rect</span> defines the coordinate system in which to resolve values, as

   252   defined in <a>object bounding box units</a> [[!SVG11]].

   253 </dd>

   254 <dt id="TermMask"><dfn>mask</dfn></dt>

   255 <dd>

   256   An off-screen image which has been initialized to transparent

   257   black.

   258   The graphical object to which the mask is applied

   259   will be painted onto the background through the

   260   mask, thus completely or partially masking out parts of the graphical

   261   object.

   262 </dd>

   263 <dt id="TermMaskSource"><dfn>mask source</dfn></dt>

   264 <dd>

   265   A mask defined by a <a>'mask element'</a> element.

   266 </dd>

   267 <dt id="TermClippingPath">clipping path</dt>

   268 <dd>

   269   A combination of the SVG elements <a>'path'</a>, <a>'text'</a>

   270   and <a>basic shapes</a> which serve as the

   271   outline of a (in the absence of anti-aliasing) 1-bit <a href="#TermMask">mask</a>,

   272   where everything on the "inside" of the outline is allowed to

   273   show through but everything on the outside is masked out. See 'clip-path'.

   274 </dd>

   275 </dl>

   277 <h2>The Mask Rendering Model</h2>

   279 <p>

   280   The application of the 'clip-path', 'mask' or 'mask-image' properties to an element formatted with the CSS box model

   281   establishes a stacking context in the same way that CSS 'opacity' does, and all the element's descendants are rendered

   282   together as a group with the masking applied to the group as a whole.

   283 </p>

   285 <p>

   286   The 'mask' and 'mask-image' properties have no effect on the geometry of any element's CSS boxes.

   287 </p>

   289 <p>

   290   The compositing model follows the SVG compositing model [[!SVG11]]: first any filter effect is applied, then any

   291   clipping, masking and opacity. These effects all apply after any other CSS effects such as 'border'. As per SVG, the

   292   application of 'mask' or 'mask-image' has no effect on hit-testing.

   293 </p>

   295 <h3 id="layering">Layering Multiple Mask Images</h3>

   297 <p>The mask of a box can have multiple <span

   298 class=index>layers</span>. The number

   299 of layers is determined by the number of comma-separated values in the

   300 'mask-image' property. Note that a value of 'none' still creates

   301 a layer.

   303 See <a href="http://www.w3.org/TR/css3-background/#layering">Layering Multiple Background Images</a> [[!CSS3BG]].

   305 <p>The first layer is the layer closest to the user,

   306 the next one is painted behind the first, and so on. All mask images

   307 are transformed to alpha masks (if necessary) and combined by compositing

   308 on the <a href="#TermMask">mask</a>.

   310 <h3 id="MaskValues">Calculating mask values</h3>

   312 <p>

   313 A mask may be interpreted using one of two different methods with regards

   314 to calculating the mask values that will be multiplied with the target alpha

   315 values.

   316 </p>

   318 <p>

   319 The first and simplest method of calculating the mask values is to use the alpha

   320 channel of the mask source.

   321 In this case the mask value at a given point is simply the value of the alpha channel at that point.

   322 The color channels do not contribute to the mask value.

   323 </p>

   325 <p>

   326   The second method of calculating the mask values is to use the luminance of the mask source.

   327   In this case the mask value at a given point is computed from the color channel values and alpha channel value using

   328   the following procedure.

   329 </p>

   331 <ol>

   332 <li>Compute a luminance value from the color channel values.

   333   <ul>

   334     <li>

   335     If the computed value of 'color-interpolation' on the <a>'mask element'</a> element is 'linearRGB', convert the

   336   original image color values (potentially in the sRGB color space) to the linear

   337   RGB color space.

   338     </li>

   339     <li>Then, using non-premultiplied RGB color values, apply the

   340     luminance-to-alpha coefficients (as defined in the <a>'feColorMatrix'</a>

   341     filter primitive [[!SVG11]]) to convert the RGB color values to luminance

   342     values.

   343     </li>

   344   </ul>

   345 </li>

   346 <li>Multiply the computed luminance value by the corresponding alpha

   347 value to produce the mask value.</li>

   348 </ol>

   350 <p>Regardless of the method used, the procedure for calculating

   351 mask values assumes the content of the mask is a four-channel RGBA graphics

   352 object.

   353 For other types of graphics objects, special handling is required as

   354 follows.</p>

   356 <p>For a three-channel RGB graphics object that is used in a mask (e.g.,

   357 when referencing a three-channel image file), the effect is as if the object

   358 were converted into a four-channel RGBA image with the alpha channel

   359 uniformly set to 1.</p>

   361 <p>For a single-channel image that is used in a mask (e.g., when

   362 referencing a single-channel grayscale image file), the effect is as if the

   363 object were converted into a four-channel RGBA image, where the single

   364 channel from the referenced object is used to compute the three color

   365 channels and the alpha channel is uniformly set to 1.</p>

   366 <p class="note">Note that when

   367 referencing a grayscale image file, the transfer curve relating the

   368 encoded grayscale values to linear light values must be taken into

   369 account when computing the color channels.</p>

   371 <p class="note">Note that SVG <a>graphics elements</a> (e.g., <a>'circle'</a> or <a>'text'</a>)

   372 are all treated as four-channel RGBA images for the purposes

   373 of masking operations.</p>

   375 <p>The effect of a mask is identical to what would have happened if

   376 there were no mask but instead the alpha channel of the given object

   377 were multiplied with the mask's resulting mask values.</p>

   379 <h2 id="masking">Mask</h2>

   380 <h3 id="the-mask-image">The 'mask-image' property</h3>

   382 <table class="propdef">

   383     <tr>

   384       <th>Name:

   385       <td><dfn>mask-image</dfn>

   386     <tr>

   387       <th><a href="#values">Value</a>:

   388       <td><var>&lt;mask-reference&gt;</var>

   389     <tr>

   390       <th>Initial:

   391       <td>none

   392     <tr>

   393       <th>Applies to:

   394       <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>

   395     <tr>

   396       <th>Inherited:

   397       <td>no

   398     <tr>

   399       <th>Percentages:

   400       <td>N/A

   401     <tr>

   402       <th>Media:

   403       <td>visual

   404     <tr>

   405       <th>Computed value:

   406       <td>as specified, but with URIs made absolute

   407     <tr>

   408       <th>Animatable:

   409       <td>no

   410 </table>

   412 <p>This property sets the mask image(s) or the mask source of an element. Images

   413 are drawn with the first specified one on top (closest to the user)

   414 and each subsequent image behind the previous one.

   415 Where:

   417 <pre class=prod><var><dfn>&lt;mask-reference&gt;</dfn></var> = <var>&lt;mask-image&gt;</var># | <var>&lt;mask-element&gt;</var></pre>

   419 <pre class=prod><var><dfn>&lt;mask-image&gt;</dfn></var> = <var>&lt;image&gt;</var> | none </pre>

   421 <pre class=prod><var><dfn>&lt;mask-element&gt;</dfn></var> = <var>&lt;url&gt;</var> | <var>child</var> | <var>&lt;child-selector&gt;</var></pre>

   423 <pre class=prod><dfn>&lt;child-selector&gt;</dfn> = select(<var>&lt;compound-selector&gt;</var>#)</pre>

   425 <p class="note">A <var>&lt;mask-element&gt;</var> can just be specified as a single value and can not contibute to a list of <var>&lt;mask-reference&gt;</var> values. Otherwise the specified value of the property is invalid. (See examples below.)</p>

   427 <dl>

   428   <dt>

   429     <dfn>'&lt;url&gt;'</dfn>

   430   </dt>

   431   <dd>

   432     A URL reference to a <a>'mask element'</a> element (for example ''url(commonmasks.svg#mask)'') or an <var>&lt;image&gt;</var>.

   433   </dd>

   434   <dt>''child''</dt>

   435   <dd>

   436     A keyword to indicate that the last direct sibling <a>'mask element'</a>

   437     element of the element the 'mask-image' property is applied should be used as the mask source. It is equivalent to

   438     ''select(mask:last-of-type)''.</dd>

   439   <dt>'&lt;child-selector&gt;'</dt>

   440   <dd>

   441     A comma-separated list of <a>compound selector</a>s scoped at the element to

   442     which the 'mask-image' property is applied.

   443     The first matching element in <a>tree order</a> (as defined in [[!DOM]]) as

   444     a result of evaluating the list of selectors is taken as the mask source.

   445     If there are no matching elements the mask source is invalid.

   446   </dd>

   447   <dt><dfn>'&lt;compound-selector&gt;'</dfn></dt>

   448   <dd>

   449     A <a>compound selector</a> as defined in [[!SELECTORS4]].

   450   <dd>

   451   <dt><dfn>&lt;image&gt;</dfn></dt>

   452   <dd>

   453     A 2D image. (See [[!CSS3-IMAGES]].)

   454   </dd>

   455   <dt><dfn>''none''</dfn></dt>

   456   <dd>

   457     A value of ''none'' counts as an image layer but does not mask the element.

   458   </dd>

   459 </dl>

   461 <p class="note">If the URI in the ''url()'' function has a fragment identifier, the <var>&lt;mask-reference&gt;</var> is treated as <var>&lt;mask-element&gt;</var>, otherwise as <var>&lt;mask-image&gt;</var>.</p>

   463 <p>An invalid or non-existent mask source is ignored and no masking is applied.</p>

   465 <p>A mask image that is empty (zero width or zero height), that fails to

   466 download, is non-existent, or that cannot be displayed (e.g. because it is not

   467 in a supported image format) is ignored. No masking is applied.

   469 <p>See the section <a href="#layering">“Layering multiple mask

   470 images”</a> for how 'mask-image' interacts with other

   471 comma-separated mask properties to form each mask image

   472 layer.

   474 <div class="example">

   475 <p>Some examples specifying mask images:</p>

   476 <pre>

   477 body { mask-image: linear-gradient(black 0%, transparent 100%) }

   478 p { mask-image: none }

   479 div { mask-image: url(tl.png), url(tr.png) }

   480 </pre>

   482 <p>Some examples of a specified mask source:</p>

   483 <pre>

   484 img { mask-image: url(#mask) }

   485 span { mask-image: url(resources.svg#mask2) }

   486 </pre>

   488 <p>Examples of <i>invalid</i> mask source usages:</p>

   489 <pre>

   490 p { mask-image: url(#mask), url(tl.png) }

   491 img { mask-image: url(#mask), url(resources.svg#mask2) }

   492 </pre>

   493 <p>A <var>&lt;mask-element&gt;</var> value that is either used together with another <var>&lt;mask-element&gt;</var> value or an <var>&lt;mask-image&gt;</var> value makes the whole specified 'mask-image' value list invalid.

   494 </div>

   496 <h3 id="the-mask-source-type">The 'mask-source-type' property</h3>

   498 <table class="propdef">

   499     <tr>

   500       <th>Name:

   501       <td><dfn>mask-source-type</dfn>

   502     <tr>

   503       <th><a href="#values">Value</a>:

   504       <td><var>&lt;source-type&gt;</var>#

   505     <tr>

   506       <th>Initial:

   507       <td>auto

   508     <tr>

   509       <th>Applies to:

   510       <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>

   511     <tr>

   512       <th>Inherited:

   513       <td>no

   514     <tr>

   515       <th>Percentages:

   516       <td>N/A

   517     <tr>

   518       <th>Media:

   519       <td>visual

   520     <tr>

   521       <th>Computed value:

   522       <td>as specified

   523     <tr>

   524       <th>Animatable:

   525       <td>no

   526 </table>

   528 <p>The 'mask-source-type' property indicates whether the <var>&lt;mask-reference&gt;</var>

   529 is treated as luminance mask or alpha mask. (See <a href="#MaskValues">Calculating mask values</a>.)</p>

   531 <pre class=prod><dfn><var>&lt;source-type&gt;</var></dfn> = alpha | luminance | auto</pre>

   533 <p>Values have the following meanings:

   535 <dl>

   536   <dt><dfn>''alpha''</dfn></dt>

   537   <dd>

   538     A value of ''alpha'' indicates that the alpha values of the mask

   539     image should be used as the mask values.

   540     See <a href="#MaskValues">Calculating mask values</a>.</p>

   541   </dd>

   542   <dt><dfn>''luminance''</dfn></dt>

   543   <dd>

   544     A value of ''luminance'' indicates that the luminance values of the mask

   545     image should be used as the mask values.

   546     See <a href="#MaskValues">Calculating mask values</a>.</p>

   547   </dd>

   548   <dt><dfn>''auto''</dfn></dt>

   549   <dd>

   550     <p>

   551       If the <var>&lt;mask-reference&gt;</var> of the 'mask-image' property is of type <var>&lt;mask-image&gt;</var> the luminance values of the mask

   552       image should be used as the mask values.

   553     <p>

   554       If the <var>&lt;mask-reference&gt;</var> of the 'mask-image' property is of type <var>&lt;mask-element&gt;</var> the alpha values of the mask

   555       image should be used as the mask values.

   556   </dd>

   557 </dl>

   559 <div class="example">

   560   <p>

   561     In the following example, the 'mask-type' property sets the mask type value for the <a>'mask element'</a> element to

   562     ''alpha''. The 'mask-image' property has a reference to this <a>'mask element'</a> element and the 'mask-source-type' property has a value of ''luminance''. The 'mask-source-type' property will override the definition of 'mask-type' to ''luminance''.

   563 <pre>

   564 &lt;mask id="SVGMask" mask-type="alpha" maskContentUnits="objectBoundingBox"&gt;

   565   &lt;radialGradient id="radialFill"&gt;

   566     &lt;stop stop-color="white" offset="0"/&gt;

   567     &lt;stop stop-color="black" offset="1"/&gt;

   568   &lt;/radialGradient&gt;

   569   &lt;circle fill="url(#radialFill)" cx="0.5" cy="0.5" r="0.5"/&gt;

   570 &lt;/mask&gt;

   572 &lt;style&gt;

   573   rect {

   574     mask-image: url(#SVGMask);

   575     mask-source-type: luminance;

   576   }

   577 &lt;/style&gt;

   579 &lt;rect width="200" height="200" fill="green"/&gt;

   580 </pre>

   581 </div>

   583 <h3 id="the-mask-repeat">The 'mask-repeat' property</h3>

   585 <table class="propdef">

   586     <tr>

   587       <th>Name:

   588       <td><dfn>mask-repeat</dfn>

   589     <tr>

   590       <th><a href="#values">Value</a>:

   591       <td><var>&lt;repeat-style&gt;</var>#

   592     <tr>

   593       <th>Initial:

   594       <td>repeat

   595     <tr>

   596       <th>Applies to:

   597       <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>

   598     <tr>

   599       <th>Inherited:

   600       <td>no

   601     <tr>

   602       <th>Percentages:

   603       <td>N/A

   604     <tr>

   605       <th>Media:

   606       <td>visual

   607     <tr>

   608       <th>Computed value:

   609       <td>A list, each item consisting of:

   610         two keywords, one per dimension

   611     <tr>

   612       <th>Animatable:

   613       <td>no

   614 </table>

   616 <p>Specifies how mask images are tiled after they have been

   617 <a href="#the-mask-size">sized</a> and <a href="#the-mask-position">positioned</a>.

   618 Where

   619 <pre class=prod><dfn><var>&lt;repeat-style&gt;</var></dfn> = repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}</pre>

   621 <p>See <a href="http://www.w3.org/TR/css3-background/#the-background-repeat">Tiling Images: the 'background-repeat' property</a> [[!CSS3BG]] for the defintions of the property values.

   623 <div class=example>

   624   <p style="display:none">Example(s):

   625   <pre>

   626 body {

   627   background-color: blue;

   628   mask-image: url(dot-mask.png) luminance;

   629   mask-repeat: space;

   630 }

   631 </pre>

   633   <div class=figure>

   634     <p><img src="images/mask-repeat.svg" alt="Image of an element with a dotted mask." width="240" style="border: solid black 1px;">

   636     <p class=caption>The effect of 'space': the mask image of a dot is

   637     tiled to cover the whole <span class=index>mask painting area</span> and the mask images are equally

   638     spaced.

   639   </div>

   640 </div>

   642 <p>See the section <a href="#layering">“Layering multiple mask

   643 images”</a> for how 'mask-repeat' interacts with other

   644 comma-separated mask properties to form each mask image

   645 layer.

   647 <h3 id="the-mask-position">The 'mask-position' property</h3>

   649 <table class="propdef">

   650     <tr>

   651       <th>Name:

   652       <td><dfn>mask-position</dfn>

   653     <tr>

   654       <th><a href="#values">Value</a>:

   656       <td><var>&lt;position&gt;</var>#

   657     <tr>

   658       <th>Initial:

   659       <td>0% 0%

   660     <tr>

   661       <th>Applies to:

   662       <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>

   663     <tr>

   664       <th>Inherited:

   665       <td>no

   666     <tr>

   667       <th>Percentages:

   668       <td>refer to size of <span class=index>mask painting area</span> <em>minus</em> size of mask image; see text

   669     <tr>

   670       <th>Media:

   671       <td>visual

   672     <tr>

   673       <th>Computed value:

   674       <td>A list, each item consisting of:

   675         two keywords representing the origin and two offsets from that

   676         origin, each given as an absolute length (if given a &lt;length&gt;),

   677         otherwise as a percentage.

   678     <tr>

   679       <th>Animatable:

   680       <td>as <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-repeatable-list">repeatable list</a> of <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>

   681 </table>

   683 <p>Where

   684 <pre class=prod><dfn><var>&lt;position&gt;</var></dfn> = [

   685   [ left | center | right | top | bottom | <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]

   686 |

   687   [ left | center | right | <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]

   688   [ top | center | bottom | <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]

   689 |

   690   [ center | [ left | right ] [ <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]? ] &amp;&amp;

   691   [ center | [ top | bottom ] [ <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]? ]

   692 ]</pre>

   694 <p>See <a href="http://www.w3.org/TR/css3-background/#the-background-position">Positioning Images: the 'background-position' property</a> [[!CSS3BG]] for the defintions of the property values.

   696 <div class="example">

   697   <p>In the example below, the (single) image is placed in the lower-right

   698   corner of the viewport.

   699   <pre>

   700 body {

   701   mask-image: url("logo.png");

   702   mask-position: 100% 100%;

   703   mask-repeat: no-repeat;

   704 }

   705 </pre>

   706 </div>

   708 <div class=example>

   709 <p>Mask positions can also be relative to other corners than the

   710 top left. E.g., the following puts the background image 10px from the

   711 bottom and 3em from the right:

   713 <pre>mask-position: right 3em bottom 10px</pre>

   714 </div>

   716 <p>See the section <a href="#layering">“Layering multiple mask

   717 images”</a> for how 'mask-position' interacts with other

   718 comma-separated mask properties to form each mask image

   719 layer.

   721 <h3 id="the-mask-clip">The 'mask-clip' property</h3>

   723 <table class="propdef">

   724     <tr>

   725       <th>Name:

   726       <td><dfn>mask-clip</dfn>

   727     <tr>

   728       <th><a href="#values">Value</a>:

   729       <td><var>&lt;clip-box&gt;</var>#

   730     <tr>

   731       <th>Initial:

   732       <td>border-box

   733     <tr>

   734       <th>Applies to:

   735       <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>

   736     <tr>

   737       <th>Inherited:

   738       <td>no

   739     <tr>

   740       <th>Percentages:

   741       <td>N/A

   742     <tr>

   743       <th>Media:

   744       <td>visual

   745     <tr>

   746       <th>Computed value:

   747       <td>as specified

   748     <tr>

   749       <th>Animatable:

   750       <td>no

   751 </table>

   753 <p>Determines the <dfn id="mask-painting-area">mask painting area</dfn>,

   754 which determines the area that is affected by the mask. The painted content

   755 of an element may be resricted to this area.

   756 The syntax of the property is given with

   758 <pre class=prod><dfn><var>&lt;clip-box&gt;</var></dfn> = <var>&lt;box&gt;</var> | no-clip</pre>

   759 <pre class=prod><dfn><var>&lt;box&gt;</var></dfn> = border-box | padding-box | content-box</pre>

   761 <p>Values have the following meanings:

   763 <dl>

   764   <dt><dfn title="''border-box''!!'mask-clip' value">

   765       ''border-box''</dfn></dt>

   766   <dd>The painted content is rectricted to (clipped to) the

   767     <span>border box</span> respectively <span>painting box</span> for objects without associated layout box.

   768   <dt><dfn title="''padding-box''!!'mask-clip' value">

   769       ''padding-box''</dfn></dt>

   770   <dd>The painted content is rectricted to (clipped to) the

   771     <span>padding box.</span>

   772   <dt><dfn title="''content-box''!!'mask-clip' value">

   773       ''content-box''</dfn></dt>

   774   <dd>The painted content is rectricted to (clipped to) the

   775     <span>content box</span> respectively <span>object bounding box</span> [[!SVG11]] for objects without associated layout box.

   776   <dt><dfn title="''no-clip''!!'mask-clip' value">

   777       ''no-clip''</dfn></dt>

   778   <dd>The painted content is not restricted (not clipped). The <span>mask painting area</span> is set to

   779     the <span>bounding client rect</span>.

   780 </dl>

   782 <p class="note">Note that there is no corresponding box for

   783 ''padding-box'' on objects without associated layout box

   784 and ''content-box'' is choosen instead.</p>

   786 <p>See the section <a href="#layering">“Layering multiple mask

   787 images”</a> for how 'mask-clip' interacts with other

   788 comma-separated mask properties to form each mask image

   789 layer.

   791 <h3 id="the-mask-origin">The 'mask-origin' property</h3>

   793 <table class="propdef">

   794     <tr>

   795       <th>Name:

   796       <td><dfn>mask-origin</dfn>

   797     <tr>

   798       <th><a href="#values">Value</a>:

   799       <td><var>&lt;box&gt;</var>#

   800     <tr>

   801       <th>Initial:

   802       <td>padding-box

   803     <tr>

   804       <th>Applies to:

   805       <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>

   806     <tr>

   807       <th>Inherited:

   808       <td>no

   809     <tr>

   810       <th>Percentages:

   811       <td>N/A

   812     <tr>

   813       <th>Media:

   814       <td>visual

   815     <tr>

   816       <th>Computed value:

   817       <td>as specified

   818     <tr>

   819       <th>Animatable:

   820       <td>no

   821 </table>

   823 <p>For elements rendered as a single box, specifies the

   824 <dfn id="mask-positioning-area">mask positioning area</dfn>.

   825 For elements rendered as multiple boxes (e.g., inline boxes on several

   826 lines, boxes on several pages) specifies which boxes 'box-decoration-break'

   827 operates on to determine the mask positioning area(s).

   829 <dl>

   830   <dt><dfn title="''padding-box''!!'mask-origin' value">

   831       ''padding-box''</dfn>

   832   <dd>The position is relative to the padding box. (For single boxes

   833     ''0 0'' is the upper left corner of the padding edge,

   834     ''100% 100%'' is the lower right corner.)

   835   <dt><dfn title="''border-box''!!'mask-origin' value">

   836       ''border-box''</dfn>

   837   <dd>The position is relative to the border box respectively <span>painting box</span> for objects without associated layout box.

   838   <dt><dfn>''content-box''</dfn>

   839   <dd>The position is relative to the content box respectively object bounding box [[!SVG11]] for objects without associated layout box.

   840 </dl>

   842 <p class="note">Note that there is no corresponding box for

   843 ''padding-box'' on objects without associated layout box

   844 and ''content-box'' is choosen instead.</p>

   846 <p class="note">Note that if 'mask-clip' is ''padding-box'',

   847 'mask-origin' is ''border-box'', 'mask-position' is

   848 ''top left'' (the initial value), and the element has a

   849 non-zero border, then the top and left of the mask image will be

   850 clipped.

   852 <p>See the section <a href="#layering">“Layering multiple mask

   853 images”</a> for how 'mask-origin' interacts with other

   854 comma-separated mask properties to form each mask image

   855 layer.

   857 <h3 id="the-mask-size">The 'mask-size' property</h3>

   859 <table class="propdef">

   860     <tr>

   861       <th>Name:

   862       <td><dfn>mask-size</dfn>

   863     <tr>

   864       <th><a href="#values">Value</a>:

   865       <td><var>&lt;mask-size&gt;</var>#

   866     <tr>

   867       <th>Initial:

   868       <td>auto

   869     <tr>

   870       <th>Applies to:

   871       <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>

   872     <tr>

   873       <th>Inherited:

   874       <td>no

   875     <tr>

   876       <th>Percentages:

   877       <td>see text

   878     <tr>

   879       <th>Media:

   880       <td>visual

   881     <tr>

   882       <th>Computed value:

   883       <td>as specified, but with lengths made absolute

   884     <tr>

   885       <th>Animatable:

   886       <td>as <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-repeatable-list">repeatable list</a> of <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>

   887       (<span class="note">This means keyword values are not animatable.</span>)

   888 </table>

   890 <p>Specifies the size of the mask images. Where

   892 <pre class=prod><dfn><var>&lt;mask-size&gt;</var></dfn> = [ <var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var> | auto ]{1,2} | cover | contain</pre>

   894 <p>See <a href="http://www.w3.org/TR/css3-background/#the-background-size">Sizing Images: the ‘background-size’ property</a> [[!CSS3BG]] for the defintions of the property values.

   896 <p>See the section <a href="#layering">“Layering multiple mask

   897 images”</a> for how 'mask-size' interacts with other

   898 comma-separated mask properties to form each mask image

   899 layer.

   901 <h3 id="mask-property">The 'mask' property</h3>

   903 <table class="propdef">

   904   <tr>

   905     <th>Name:</th>

   906     <td><dfn id="MaskProperty">mask</dfn></td>

   907   </tr>

   908   <tr>

   909     <th>Value:</th>

   910     <td><var>&lt;mask-layer&gt;</var>#</td>

   911   </tr>

   912   <tr>

   913     <th>Initial:</th>

   914     <td>see individual properties</td>

   915   </tr>

   916   <tr>

   917     <th>Applies to:</th>

   918     <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a></td>

   919   </tr>

   920   <tr>

   921     <th>Inherited:</th>

   922     <td>no</td>

   923   </tr>

   924   <tr>

   925     <th>Percentages:</th>

   926     <td>see individual properties</td>

   927   </tr>

   928   <tr>

   929     <th>Media:</th>

   930     <td>visual</td>

   931   </tr>

   932   <tr>

   933     <th>Computed&#160;value:</th>

   934     <td>see individual properties</td>

   935   </tr>

   936   <tr>

   937     <th>Animatable:</th>

   938     <td>see individual properties</td>

   939   </tr>

   940 </table>

   941 <p>Where</p>

   943 <pre class=prod><dfn>&lt;mask-layer&gt;</dfn> = <var>&lt;mask-reference&gt;</var> <var>&lt;source-type&gt;</var>? || <var>&lt;position&gt;</var> [ / <var>&lt;mask-size&gt;</var> ]? || <var>&lt;repeat-style&gt;</var> || <var>&lt;box&gt;</var> || <var>&lt;clip-box&gt;</var></pre>

   945 <p>

   946   If one <var>&lt;box&gt;</var> value is present then it sets both 'mask-origin' and 'mask-clip' to that value. If two <var>&lt;box&gt;</var> values are present, then the first sets 'mask-origin' and the second 'mask-clip'.

   948 <p class="note">

   949   Note that the properties 'mask-image', 'mask-repeat', 'mask-position', 'mask-clip', 'mask-origin' and

   950   'mask-size' have no affect on <a>'mask element'</a> elements.

   951 </p>

   953 <h3 id="the-mask-type">The 'mask-type' property</h3>

   955 <table class="propdef">

   956     <tr>

   957       <th>Name:

   958       <td><dfn>mask-type</dfn>

   959     <tr>

   960       <th><a href="#values">Value</a>:

   961       <td>luminance | alpha

   962     <tr>

   963       <th>Initial:

   964       <td>luminance

   965     <tr>

   966       <th>Applies to:

   967       <td><a>'mask element'</a> elements

   968     <tr>

   969       <th>Inherited:

   970       <td>no

   971     <tr>

   972       <th>Percentages:

   973       <td>N/A

   974     <tr>

   975       <th>Media:

   976       <td>visual

   977     <tr>

   978       <th>Computed value:

   979       <td>as specified

   980     <tr>

   981       <th>Animatable:

   982       <td>no

   983 </table>

   985 <p>The 'mask-type' property defines whether the content of the

   986 <a>'mask element'</a> is treated as as luminance mask or alpha mask, as

   987 described in <a href="#MaskValues">Calculating mask values</a>.</p>

   989 <p>Values have the following meanings:

   991 <dl>

   992   <dt>''luminance''</dt>

   993   <dd>Indicates that the luminance values of the mask should be used.</dd>

   995   <dt>''alpha''</dt>

   996   <dd>Indicates that the alpha values of the mask should be used.</dd>

   997 </dl>

   999 <p>The 'mask-type' property is a presentation attribute for SVG elements.</p>

  1001 <h3 id="MaskElement">The <span class="element-name">'mask'</span> element</h3>

  1003 <!--elementsummary mask-->

  1005     <div class="adef-list">

  1006       <p><em>Attribute definitions:</em></p>

  1007       <dl>

  1008         <dt id="MaskElementMaskUnitsAttribute"><span

  1009         class="adef">maskUnits</span> = "<em>userSpaceOnUse</em> |

  1010         <em>objectBoundingBox</em>"</dt>

  1011         <dd>Defines the coordinate system for attributes

  1012         <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>.<br />

  1013          If <span

  1014         class="attr-value">maskUnits="userSpaceOnUse"</span>,

  1015         <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>

  1016         represent values in the current user coordinate system in place at

  1017         the time when the <a>'mask element'</a>

  1018         element is referenced (i.e., the user coordinate system for

  1019         the element referencing the <a>'mask element'</a> element via the

  1020         'mask' property).<br />

  1021          If <span

  1022         class="attr-value">maskUnits="objectBoundingBox"</span>,

  1023         <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>

  1024         represent fractions or percentages of the bounding box of

  1025         the element to which the mask is applied. (See <span class="term">object bounding box

  1026         units</span>.)<br />

  1027          If attribute <a>'mask/maskUnits'</a> is

  1028         not specified, then the effect is as if a value of <span

  1029         class="attr-value">'objectBoundingBox'</span> were

  1030         specified.<br />

  1031          <span class="anim-target">Animatable:

  1032         yes.</span></dd>

  1033         <dt id="MaskElementMaskContentUnitsAttribute"><span

  1034         class="adef">maskContentUnits</span> =

  1035         "<em>userSpaceOnUse</em> | <em>objectBoundingBox</em>"</dt>

  1036         <dd>Defines the coordinate system for the contents of the

  1037         <a>'mask element'</a>.<br />

  1038          If <span

  1039         class="attr-value">maskContentUnits="userSpaceOnUse"</span>,

  1040         the user coordinate system for the contents of the

  1041         <a>'mask element'</a> element is the current

  1042         user coordinate system in place at the time when the

  1043         <a>'mask element'</a> element is referenced

  1044         (i.e., the user coordinate system for the element

  1045         referencing the <a>'mask element'</a>

  1046         element via the 'mask'

  1047         property).<br />

  1048          If <span

  1049         class="attr-value">maskContentUnits="objectBoundingBox"</span>,

  1050         the user coordinate system for the contents of the <a>'mask element'</a> is established using the

  1051         bounding box of the element to which the mask is applied.

  1052         (See <span class="term">object bounding box

  1053         units</span>.)<br />

  1054          If attribute <a>'maskContentUnits'</a> is not specified,

  1055         then the effect is as if a value of <span

  1056         class="attr-value">'userSpaceOnUse'</span> were

  1057         specified.<br />

  1058          <span class="anim-target">Animatable:

  1059         yes.</span></dd>

  1060         <dt id="MaskElementXAttribute"><span

  1061         class="adef">x</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>

  1062         <dd>The x-axis coordinate of one corner of the rectangle

  1063         for the largest possible offscreen buffer.

  1064         If the attribute is not specified but at least one of the attributes <a>'mask/y'</a>,

  1065         <a>'mask/width'</a> or <a>'mask/height'</a> are specified, the effect is as if a

  1066         value of <span class='attr-value'>'-10%'</span> were specified.<br />

  1067          <span class="anim-target">Animatable:

  1068         yes.</span></dd>

  1069         <dt id="MaskElementYAttribute"><span

  1070         class="adef">y</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>

  1071         <dd>The y-axis coordinate of one corner of the rectangle

  1072         for the largest possible offscreen buffer.<br />

  1073         If the attribute is not specified but at least one of the attributes <a>'mask/x'</a>,

  1074         <a>'mask/width'</a> or <a>'mask/height'</a> are specified, the effect is as if a

  1075         value of <span class='attr-value'>'-10%'</span> were specified.<br />

  1076         <span class="anim-target">Animatable:

  1077         yes.</span></dd>

  1078         <dt id="MaskElementWidthAttribute"><span

  1079         class="adef">width</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>

  1080         <dd>The width of the largest possible offscreen buffer.

  1081         A negative value or a value of zero disables rendering of the element.<br />

  1082         If the attribute is not specified but at least one of the attributes <a>'mask/x'</a>,

  1083         <a>'mask/y'</a> or <a>'mask/height'</a> are specified, the effect is as if a

  1084         value of <span class='attr-value'>'120%'</span> were specified.<br />

  1085          <span class="anim-target">Animatable:

  1086         yes.</span></dd>

  1087         <dt id="MaskElementHeightAttribute"><span

  1088         class="adef">height</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>

  1089         <dd>The height of the largest possible offscreen

  1090         buffer.<br />

  1091         A negative value or a value of zero disables rendering of the element.<br />

  1092         If the attribute is not specified but at least one of the attributes <a>'mask/x'</a>,

  1093         <a>'mask/y'</a> or <a>'mask/width'</a> are specified, the effect is as if a

  1094         value of <span class='attr-value'>'120%'</span> were specified.<br />

  1095          <span class="anim-target">Animatable:

  1096         yes.</span></dd>

  1097       </dl>

  1098     </div>

  1099 <p>If at least one of the attributes <a>'mask/x'</a>,

  1100 <a>'mask/y'</a>, <a>'mask/width'</a> or <a>'mask/height'</a> are specified,

  1101 the given object and the rectangle defined by

  1102 <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>

  1103 establish a current clipping path. The rendered content of the mask must be clipped

  1104 by this current clipping path.<p/>

  1106 <p>CSS properties inherit into the

  1107 <a>'mask element'</a> element from its ancestors; properties do <em>not</em>

  1108 inherit from the element referencing the <a>'mask element'</a> element.</p>

  1110 <p><a>'mask element'</a> elements are never rendered directly; their only

  1111 usage is as something that can be referenced using the 'mask'

  1112 property. The 'opacity', 'filter' and 'display' properties do not apply to the

  1113 <a>'mask element'</a> element; thus, <a>'mask element'</a> elements are not

  1114 directly rendered even if the 'display' property is set to a value

  1115 other than 'none', and <a>'mask element'</a>

  1116 elements are available for referencing even when the 'display' property

  1117 on the <a>'mask element'</a> element or any of its ancestors is set to

  1118 <span class="prop-value">none</span>.</p>

  1120 <h2>Mask Box Image</h2>

  1122 <p>

  1123   With 'mask-box-image' a mask can be split into nine pieces: four corners, four

  1124   edges and the middle piece as demonstrated in the figure below.

  1125 </p>

  1127 <div class=figure>

  1128   <img src="images/mask-box-image-mask.svg" alt="pieces of a mask box image" width="240">

  1129   <p class=caption>

  1130     Pieces of a mask box image.

  1131   </p>

  1132 </div>

  1134 <p>

  1135   These pieces may be sliced, scaled and stretched in various ways to fit the size of the <span class=index>mask image area</span>. The usage of 'mask-box-image' corresponds to the 'border-image' property of CSS Background and Borders [[!CSS3BG]].

  1136 </p>

  1138 <div class=example>

  1139   <p>

  1140     The mask image in the following example is split into four corners with

  1141     dimensions of 75 pixels, four edges and the middle piece that is stretched

  1142     and scaled.

  1143   </p>

  1145   <div class=figure>

  1146     <img src="images/mask-box-image.svg" alt="Example for 'mask-box-image'" width="720" height="240">

  1147     <p class=caption>

  1148       Example for 'mask-box-image'. The object on the left is the object to mask. The second image is the alpha mask and

  1149       the last image the masked object.

  1150     </p>

  1151   </div>

  1153   <pre>

  1154 div {

  1155   background: linear-gradient(bottom, #F27BAA 0%, #FCC8AD 100%);

  1156   mask-box-image-slice: 25 fill;

  1157   mask-box-image-repeat: stretch;

  1158   mask-box-image-source: url(mask.png);

  1159 }</pre>

  1160 </div>

  1162 <h3 id="the-mask-box-image-source">The 'mask-box-image-source' property</h3>

  1164 <table class=propdef>

  1165   <tr>

  1166     <th>Name:

  1167     <td><dfn>mask-box-image-source</dfn>

  1168   <tr>

  1169     <th><a href="#values">Value</a>:

  1170     <td><var>&lt;mask-image&gt;</var>

  1171   <tr>

  1172     <th>Initial:

  1173     <td>none

  1174   <tr>

  1175     <th>Applies to:

  1176     <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.

  1177   <tr>

  1178     <th>Inherited:

  1179     <td>no

  1180   <tr>

  1181     <th>Percentages:

  1182     <td>N/A

  1183   <tr>

  1184     <th>Media:

  1185     <td>visual

  1186   <tr>

  1187     <th>Computed value:

  1188     <td>''none'' or the image with its URI made absolute

  1189   <tr>

  1190     <th>Animatable:

  1191     <td>no

  1192 </table>

  1194 <p>Specifies an image to be used as mask. If the value is ''none'' or if the image cannot be displayed

  1195 (or the property doesn't apply), the content won't get masked.

  1197 <h3 id="the-mask-box-image-slice">The 'mask-box-image-slice' property</h3>

  1199 <table class=propdef>

  1200   <tr>

  1201     <th>Name:

  1202     <td><dfn>mask-box-image-slice</dfn>

  1203   <tr>

  1204     <th><a href="#values">Value</a>:

  1205     <td>[<var>&lt;number&gt;</var> | <var>&lt;percentage&gt;</var>]{1,4} &amp;&amp; fill?

  1206   <tr>

  1207     <th>Initial:

  1208     <td>0 fill

  1209   <tr>

  1210     <th>Applies to:

  1211     <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.

  1212   <tr>

  1213     <th>Inherited:

  1214     <td>no

  1215   <tr>

  1216     <th>Percentages:

  1217     <td>refer to size of the mask image

  1218   <tr>

  1219     <th>Media:

  1220     <td>visual

  1221   <tr>

  1222     <th>Computed value:

  1223     <td>as specified

  1224   <tr>

  1225     <th>Animatable:

  1226     <td>no

  1227 </table>

  1229 <p>This property specifies inward offsets from the top, right, bottom,

  1230 and left edges of the mask image, dividing it into nine regions: four corners,

  1231 four edges and a middle.

  1232 The middle image part is discarded (treated as fully transparent black)

  1233 unless the ''fill'' keyword is present.

  1235 <p>See <a href="http://www.w3.org/TR/css3-background/#the-border-image-slice">Image Slicing: the 'border-image-slice' property</a> [[!CSS3BG]] for the defintions of the property values.

  1237 <h3 id="the-mask-box-image-width">The 'mask-box-image-width' property</h3>

  1239 <table class=propdef>

  1240   <tr>

  1241     <th>Name:

  1242     <td><dfn>mask-box-image-width</dfn>

  1243   <tr>

  1244     <th><a href="#values">Value</a>:

  1245     <td>[ <var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var> | <var>&lt;number&gt;</var> | auto ]{1,4}

  1246   <tr>

  1247     <th>Initial:

  1248     <td>auto

  1249   <tr>

  1250     <th>Applies to:

  1251     <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.

  1252   <tr>

  1253     <th>Inherited:

  1254     <td>no

  1255   <tr>

  1256     <th>Percentages:

  1257     <td>relative to width/height of the <em>mask box image area</em>

  1258   <tr>

  1259     <th>Media:

  1260     <td>visual

  1261   <tr>

  1262     <th>Computed value:

  1263     <td>all <var>&lt;length&gt;</var>s made absolute, otherwise as specified

  1264   <tr>

  1265     <th>Animatable:

  1266     <td>no

  1267 </table>

  1269 <p>The mask image is drawn inside an area called the

  1270 <em>mask box image area</em>. This is an area whose boundaries

  1271 by default correspond to the mask box, see 'mask-box-image-outset'.

  1273 <p>See <a href="http://www.w3.org/TR/css3-background/#the-border-image-width">Drawing Areas: the ‘border-image-width’ property</a> [[!CSS3BG]] for the defintions of the property values.

  1275 <p class=note>

  1276   Note that for SVG elements without an associated layout box the 'border-width'

  1277   is considered to be ''0''.

  1278 </p>

  1280 <h3 id="the-mask-box-image-outset">The 'mask-box-image-outset' property</h3>

  1282 <table class=propdef>

  1283   <tr>

  1284     <th>Name:

  1285     <td><dfn>mask-box-image-outset</dfn>

  1286   <tr>

  1287     <th><a href="#values">Value</a>:

  1288     <td>[ <var>&lt;length&gt;</var> | <var>&lt;number&gt;</var> ]{1,4}

  1289   <tr>

  1290     <th>Initial:

  1291     <td>0

  1292   <tr>

  1293     <th>Applies to:

  1294     <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.

  1295   <tr>

  1296     <th>Inherited:

  1297     <td>no

  1298   <tr>

  1299     <th>Percentages:

  1300     <td>N/A

  1301   <tr>

  1302     <th>Media:

  1303     <td>visual

  1304   <tr>

  1305     <th>Computed value:

  1306     <td>all <var>&lt;length&gt;</var>s made absolute, otherwise as specified

  1307   <tr>

  1308     <th>Animatable:

  1309     <td>no

  1310 </table>

  1312 <p>The values specify the amount by which the <dfn>mask box image

  1313 area</dfn> extends beyond the border box.

  1314 If it has four values, they set the outsets on the top, right, bottom and

  1315 left sides in that order. If the left is missing, it is the same as the right;

  1316 if the bottom is missing, it is the same as the top; if the right is missing,

  1317 it is the same as the top.

  1319 <p>As with 'mask-box-image-width', a &lt;number&gt; represents a multiple of the

  1320 corresponding 'border-width'.

  1321 Negative values are not allowed for any of the 'mask-box-image-outset' values.

  1323 <p class=note>Note that for SVG elements without associated layout box the 'border-width' is considered to be ''0''.</p>

  1325 <h3 id="the-mask-box-image-repeat">The 'mask-box-image-repeat' property</h3>

  1327 <table class=propdef>

  1328   <tr>

  1329     <th>Name:

  1330     <td><dfn>mask-box-image-repeat</dfn>

  1331   <tr>

  1332     <th><a href="#values">Value</a>:

  1333     <td>[ stretch | repeat | round | space ]{1,2}

  1334   <tr>

  1335     <th>Initial:

  1336     <td>stretch

  1337   <tr>

  1338     <th>Applies to:

  1339     <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.

  1340   <tr>

  1341     <th>Inherited:

  1342     <td>no

  1343   <tr>

  1344     <th>Percentages:

  1345     <td>N/A

  1346   <tr>

  1347     <th>Media:

  1348     <td>visual

  1349   <tr>

  1350     <th>Computed value:

  1351     <td>as specified

  1352   <tr>

  1353     <th>Animatable:

  1354     <td>no

  1355 </table>

  1357 <p>This property specifies how the images for the sides and the middle

  1358 part of the mask image are scaled and tiled. The first keyword applies

  1359 to the horizontal sides, the second to the vertical ones.

  1360 If the second keyword is absent, it is assumed to be the same as the first.

  1362 <p>See <a href="http://www.w3.org/TR/css3-background/#the-border-image-repeat">Image Tiling: the 'border-image-repeat' property</a> [[!CSS3BG]] for the defintions of the property values.

  1364 <p>The exact process for scaling and tiling the mask box image parts is given in the section <a href="#masking-with-the-mask-box-image">Masking with the mask-box-image</a>.

  1366 <h3 id="the-mask-box-image">The 'mask-box-image' property</h3>

  1368 <table class=propdef>

  1369   <tr>

  1370     <th>Name:

  1371     <td><dfn>mask-box-image</dfn>

  1372   <tr>

  1373     <th><a href="#values">Value</a>:

  1374     <td>   <var>&lt;'mask-box-image-source'&gt;</var>

  1375         || <var>&lt;'mask-box-image-slice'&gt;</var>

  1376            [ / <var>&lt;'mask-box-image-width'&gt;</var> |

  1377              / <var>&lt;'mask-box-image-width'&gt;</var>? / <var>&lt;'mask-box-image-outset'&gt;</var> ]?

  1378         || <var>&lt;'mask-box-image-repeat'&gt;</var>

  1379   <tr>

  1380     <th>Initial:

  1381     <td>See individual properties

  1382   <tr>

  1383     <th>Applies to:

  1384     <td>See individual properties

  1385   <tr>

  1386     <th>Inherited:

  1387     <td>no

  1388   <tr>

  1389     <th>Percentages:

  1390     <td>N/A

  1391   <tr>

  1392     <th>Media:

  1393     <td>visual

  1394   <tr>

  1395     <th>Computed value:

  1396     <td>See individual properties

  1397   <tr>

  1398     <th>Animatable:

  1399     <td>See individual properties

  1400 </table>

  1402 <p>This is a shorthand property for setting 'mask-box-image-source',

  1403 'mask-box-image-slice', 'mask-box-image-width', 'mask-box-image-outset' and

  1404 'mask-box-image-repeat'. Omitted values are set to their initial values.

  1406 <h3 id="masking-with-the-mask-box-image">Masking with the mask-box-image</h3>

  1408 <p>

  1409   After the mask-box-image given by 'mask-box-image-source' is sliced by

  1410   the 'mask-box-image-slice' values, the resulting nine images are scaled,

  1411   positioned, and tiled into their corresponding mask image regions

  1412   in four steps as described in the section <a href="http://www.w3.org/TR/css3-background/#border-image-process">Drawing the Border Image</a> [[!CSS3BG]].

  1415 <h2>Clipping paths</h2>

  1417 <p>

  1418   The clipping path restricts the region to which paint can be applied, the

  1419   so-called clipping region.

  1420   Conceptually, any parts of the drawing that lie outside of this region are not

  1421   drawn.

  1422   This includes any content, background, borders, text decoration, outline and

  1423   visible scrolling mechanism of the element to which the clipping path is

  1424   applied, and those of its descendants.

  1425 </p>

  1427 <p>

  1428   An element's ancestors may also clip portions of their content (e.g., via

  1429   their own 'clip' or 'clip-path' properties and/or if their 'overflow' property

  1430   is not ''visible'').

  1431   What is rendered is the cumulative intersection.

  1432 </p>

  1434 <p>

  1435   If the clipping region exceeds the bounds of the UA's document window, content may be clipped to that window by the

  1436   native operating environment.

  1437 </p>

  1439 <h3 id="the-clip-path">The 'clip-path' property</h3>

  1440 <table class="propdef">

  1441   <tr>

  1442     <th>Name:</th>

  1443     <td><dfn>clip-path</dfn></td>

  1444   </tr>

  1445   <tr>

  1446     <th>Value:</th>

  1447     <td><var>&lt;shape&gt;</var> | <var>&lt;clip-source&gt;</var> | none</td>

  1448   </tr>

  1449   <tr>

  1450     <th>Initial:</th>

  1451     <td>none</td>

  1452   </tr>

  1453   <tr>

  1454     <th>Applies to:</th>

  1455     <td>All elements. SVG <a>container elements</a>, <a>graphics elements</a>

  1456     and <a>'clipPath'</a></td>

  1457   </tr>

  1458   <tr>

  1459     <th>Inherited:</th>

  1460     <td>no</td>

  1461   </tr>

  1462   <tr>

  1463     <th>Percentages:</th>

  1464     <td>as specified</td>

  1465   </tr>

  1466   <tr>

  1467     <th>Media:</th>

  1468     <td>visual</td>

  1469   </tr>

  1470   <tr>

  1471     <th>Computed value:</th>

  1472     <td>as specified, but with <var>&lt;url&gt;</var> values made absolute</td>

  1473   </tr>

  1474   <tr>

  1475     <th>Animatable:</th>

  1476     <td>See <a href="http://dev.w3.org/csswg/css3-exclusions/#shape-inside">'shape-inside'</a> and <a href="http://dev.w3.org/csswg/css3-exclusions/#shape-outside">'shape-outside'</a> [[!CSS3-EXCLUSIONS]]</td>

  1477   </tr>

  1478 </table>

  1480 <pre class=prod><dfn>&lt;clip-source&gt;</dfn> = <var>&lt;url&gt;</var> | <var>child</var> | <var>&lt;child-selector&gt;</var>

  1481 </pre>

  1483 <dl>

  1484   <dt>

  1485     <dfn>'&lt;shape&gt;'</dfn>

  1486   </dt>

  1487   <dd>

  1488     A basic shape function as defined in CSS3 Exclusions. The origin of clipping shapes is on the top left of the <span

  1489     class=index>bounding client rect</span>. Percentage values are resolved against the

  1490     <span class=index>bounding client rect</span> width and height. (See [[!CSS3-EXCLUSIONS]].)

  1491   </dd>

  1492   <dt>''child''</dt>

  1493   <dd>

  1494     A keyword to indicate that the last direct sibling <a>'clipPath element'</a>

  1495     element of the element the 'clip-path' property is applied should be used as the clip source. It is equivalent to

  1496     ''select(clipPath:last-of-type)''.</dd>

  1497   <dt>'&lt;child-selector&gt;'</dt>

  1498   <dd>

  1499     A comma-separated list of <a>compound selector</a>s scoped at the element to

  1500     which the 'clip-path' property is applied.

  1501     The first matching element in <a>tree order</a> (as defined in [[!DOM]]) as

  1502     a result of evaluating the list of selectors is taken as the clip source.

  1503     If there are no matching elements the clip source is invalid.

  1504   </dd>

  1505 </dl>

  1507 <h3 id="the-clip-rule">The 'clip-rule' property</h3>

  1509 <table class="propdef">

  1510   <tr>

  1511     <th>Name:</th>

  1512     <td><dfn>clip-rule</dfn></td>

  1513   </tr>

  1514   <tr>

  1515     <th>Value:</th>

  1516     <td>nonzero | evenodd</td>

  1517   </tr>

  1518   <tr>

  1519     <th>Initial:</th>

  1520     <td>nonzero</td>

  1521   </tr>

  1522   <tr>

  1523     <th>Applies to:</th>

  1524     <td><a>graphics elements</a> within a <a>'clipPath'</a> element</td>

  1525   </tr>

  1526   <tr>

  1527     <th>Inherited:</th>

  1528     <td>yes</td>

  1529   </tr>

  1530   <tr>

  1531     <th>Percentages:</th>

  1532     <td>N/A</td>

  1533   </tr>

  1534   <tr>

  1535     <th>Media:</th>

  1536     <td>visual</td>

  1537   </tr>

  1538   <tr>

  1539     <th>Computed&#160;value:</th>

  1540     <td>as specified</td>

  1541   </tr>

  1542   <tr>

  1543     <th>Animatable:</th>

  1544     <td>no</td>

  1545   </tr>

  1546 </table>

  1548 <dl>

  1549   <dt><dfn>''nonzero''</dfn></dt>

  1550   <dd>See description of <a>'fill-rule'</a> property [[SVG11]].</dd>

  1552   <dt><dfn>''evenodd''</dfn></dt>

  1553   <dd>See description of <a>'fill-rule'</a> property [[SVG11]].</dd>

  1554 </dl>

  1556 <p>The 'clip-rule' property only applies to graphics elements that are

  1557 contained within a <a>'clipPath'</a> element.

  1559 <div class=example>

  1560 The following fragment of code

  1561 will cause an evenodd clipping rule to be applied to the clipping path because

  1562 'clip-rule' is specified on the <a>'path'</a> element that defines the

  1563 clipping shape:</p>

  1565 <pre>

  1566 &lt;g clip-rule="nonzero"&gt;

  1567   &lt;clipPath id="MyClip"&gt;

  1568     &lt;path d="..." clip-rule="evenodd" /&gt;

  1569   &lt;/clipPath&gt;

  1570   &lt;rect clip-path="url(#MyClip)" ... /&gt;

  1571 &lt;/g&gt;

  1572 </pre>

  1574 <p>whereas the following fragment of code will <em>not</em> cause an

  1575 evenodd clipping rule to be applied because the 'clip-rule' is

  1576 specified on the referencing element, not on the object defining the

  1577 clipping shape:</p>

  1579 <pre>

  1580 &lt;g clip-rule="nonzero"&gt;

  1581   &lt;clipPath id="MyClip"&gt;

  1582     &lt;path d="..." /&gt;

  1583   &lt;/clipPath&gt;

  1584   &lt;rect clip-path="url(#MyClip)" clip-rule="evenodd" ... /&gt;

  1585 &lt;/g&gt;

  1586 </pre>

  1587 </div>

  1589 <h3 id="clip-property">The 'clip' property</h3>

  1591 <table class="propdef">

  1592   <tr>

  1593     <th>Name:</th>

  1594     <td><dfn id="ClipProperty">clip</dfn></td>

  1595   </tr>

  1596   <tr>

  1597     <th>Value:</th>

  1598     <td><var>&lt;shape&gt;</var> | auto</td>

  1599   </tr>

  1600   <tr>

  1601     <th>Initial:</th>

  1602     <td>see individual properties</td>

  1603   </tr>

  1604   <tr>

  1605     <th>Applies to:</th>

  1606     <td>Absolutely positioned elements. In SVG, it applies to <a

  1607       href="http://www.w3.org/TR/SVG2/coords.html#EstablishingANewViewport">elements which

  1608       establish a new viewport</a>, <a>'pattern element'</a> elements and <a>'marker element'</a> elements.</td>

  1609   </tr>

  1610   <tr>

  1611     <th>Inherited:</th>

  1612     <td>no</td>

  1613   </tr>

  1614   <tr>

  1615     <th>Percentages:</th>

  1616     <td>N/A</td>

  1617   </tr>

  1618   <tr>

  1619     <th>Media:</th>

  1620     <td>visual</td>

  1621   </tr>

  1622   <tr>

  1623     <th>Computed&#160;value:</th>

  1624     <td>as specified</td>

  1625   </tr>

  1626   <tr>

  1627     <th>Animatable:</th>

  1628     <td>as <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-rect">rectangle</a></td>

  1629   </tr>

  1630 </table>

  1632 <p class=note>With this specification the 'clip' property is deprecated. Authors are encouraged to use the 'clip-path' property instead.

  1633   UAs must support the 'clip' property.

  1634 </p>

  1636 <p>

  1637   The 'clip' property applies only to absolutely positioned elements. In SVG, it applies to

  1638   <a href="http://www.w3.org/TR/SVG2/coords.html#EstablishingANewViewport">elements which establish a new viewport</a>,

  1639   <a>'pattern element'</a> elements and <a>'marker element'</a> elements</td>. Values have the following meanings:

  1640 </p>

  1642 <dl>

  1643   <dt>''auto''</dt>

  1644   <dd>The element does not clip.</dd>

  1645   <dt><var>&lt;shape&gt;</var></dt>

  1646   <dd>

  1647     <p>

  1648       In CSS 2.1, the only valid &lt;shape&gt; value is: rect(<var>&lt;top&gt;</var>, <var>&lt;right&gt;</var>,

  1649       <var>&lt;bottom&gt;</var>, <var>&lt;left&gt;</var>) where <var>&lt;top&gt;</var> and <var>&lt;bottom&gt;</var>

  1650       specify offsets from the top border edge of the box, and <var>&lt;right&gt;</var>, and <var>&lt;left&gt;</var>

  1651       specify offsets from the left border edge of the box. Authors should separate offset values with commas. User agents

  1652       must support separation with commas, but may also support separation without commas (but not a combination), because

  1653       a previous revision of this specification was ambiguous in this respect.

  1654     </p>

  1656     <p><dfn>&lt;top&gt;</dfn>,

  1657       <dfn>&lt;right&gt;</dfn>, <dfn>&lt;bottom&gt;</dfn>, and <dfn>&lt;left&gt;</dfn> may either have a

  1658       <var>&lt;length&gt;</var> value or ''auto''. Negative lengths are permitted. The value ''auto'' means that a given

  1659       edge of the clipping region will be the same as the edge of the element's generated border box (i.e., ''auto'' means

  1660       the same as ''0'' for <var>&lt;top&gt;</var> and <var>&lt;left&gt;</var>, the same as the used value of the height

  1661       plus the sum of vertical padding and border widths for <var>&lt;bottom&gt;</var>, and the same as the used value of the width

  1662       plus the sum of the horizontal padding and border widths for <var>&lt;right&gt;</var>, such that four 'auto' values result in

  1663       the clipping region being the same as the element's border box).

  1664     </p>

  1666     <p>

  1667       When coordinates are rounded to pixel coordinates, care should be taken that no pixels remain visible when

  1668       <var>&lt;left&gt;</var> and <var>&lt;right&gt;</var> have the same value (or <var>&lt;top&gt;</var> and

  1669       <var>&lt;bottom&gt;</var> have the same value), and conversely that no pixels within the element's border box

  1670       remain hidden when these values are ''auto''.

  1671     </p>

  1672   </dd>

  1673 </dl>

  1675 <div class="example">

  1676   <p>

  1677     Example: The following two rules:

  1678   </p>

  1680   <pre><code>

  1681 p#one { clip: rect(5px, 40px, 45px, 5px); }

  1682 p#two { clip: rect(5px, 55px, 45px, 5px); }</code></pre>

  1684   <p>

  1685     and assuming both Ps are 50 by 55 pixel, will create, respectively, the rectangular clipping regions delimited by

  1686     the dashed lines in the following illustrations:

  1687   </p>

  1689   <div class=figure>

  1690     <img src="images/clip.png" width="292" height="577" alt="Values for rect shape">

  1691     <p class=caption>This diagram illustrates two block boxes, one above the other, with rectangular clipping regions of

  1692       different dimensions. (See <a href="http://www.w3.org/TR/CSS2/images/longdesc/clip-desc.html">long description</a>.)

  1693   </div>

  1694 </div>

  1696 <h3 id="ClipPathElement">The <a>'clipPath element'</a> element</h3>

  1698 <!--elementsummary clipPath-->

  1700 <div class="adef-list">

  1701   <p><em>Attribute definitions:</em></p>

  1702   <dl>

  1703     <dt id="ClipPathElementClipPathUnitsAttribute"><span

  1704     class="adef">clipPathUnits</span> =

  1705     "<em>userSpaceOnUse</em> | <em>objectBoundingBox</em>"</dt>

  1706     <dd>Defines the coordinate system for the contents of the

  1707     <a>'clipPath'</a>.<br />

  1708      If <span class="attr-value">clipPathUnits="userSpaceOnUse"</span>,

  1709     the contents of the <a>'clipPath'</a> represent values in

  1710     the current user coordinate system in place at the time

  1711     when the <a>'clipPath'</a>

  1712     element is referenced (i.e., the user coordinate system for

  1713     the element referencing the <a>'clipPath'</a> element via the

  1714     <a>'clip-path'</a> property).<br />

  1715      If <span class="attr-value">clipPathUnits="objectBoundingBox"</span>,

  1716     then the user coordinate system for the contents of the

  1717     <a>'clipPath'</a> element is established using the bounding box of

  1718     the element to which the clipping path is applied (see <span class=index>object bounding box

  1719     units</span>).<br />

  1720      If attribute <a>'clipPathUnits'</a>

  1721     is not specified, then the effect is as if a value of <span

  1722     class="attr-value">'userSpaceOnUse'</span> were

  1723     specified.<br />

  1724      <span class="anim-target">Animatable:

  1725     yes.</span></dd>

  1726   </dl>

  1727 </div>

  1729 <p>CSS properties inherit into the

  1730 <a>'clipPath'</a> element from its ancestors; properties do <em>not</em>

  1731 inherit from the element referencing the <a>'clipPath'</a> element.</p>

  1733 <p><a>'clipPath'</a> elements are never rendered directly; their only usage is

  1734 as something that can be referenced using the <a>'clip-path'</a> property. The

  1735 <a>'display'</a> property does not apply to the <a>'clipPath'</a> element;

  1736 thus, <a>'clipPath'</a> elements are not directly rendered even if the

  1737 'display' property is set to a value other than

  1738 <span class="prop-value">none</span>, and <a>'clipPath'</a> elements are

  1739 available for referencing even when the <a>'display'</a> property on the

  1740 <a>'clipPath'</a> element or any of its ancestors is set to

  1741 <span class="prop-value">none</span>.</p>

  1743 <p>A <a>'clipPath'</a> element can contain <a>'path'</a> elements,

  1744 <a>'text'</a> elements, <a>basic shapes</a> (such as

  1745 <a>'circle'</a>) or a <a>'use'</a> element. If a <a>'use'</a> element is a

  1746 child of a <a>'clipPath'</a> element, it must directly reference

  1747 <a>'path'</a>, <a>'text'</a> or <a>basic shapes</a> elements.

  1748 Indirect references are an error and the <a>'clipPath'</a> element must be

  1749 ignored.</p>

  1751 <p>The raw geometry of each child element exclusive of rendering properties

  1752 such as 'fill', 'stroke', 'stroke-width' within a

  1753 <a>'clipPath'</a> conceptually defines a 1-bit mask (with the possible

  1754 exception of anti-aliasing along the edge of the geometry) which represents

  1755 the silhouette of the graphics associated with that element. Anything outside

  1756 the outline of the object is masked out. If a child element is

  1757 made invisible by 'display' or 'visibility' it does not contribute

  1758 to the clipping path. When the <a>'clipPath'</a> element

  1759 contains multiple child elements, the silhouettes of the child elements are

  1760 logically OR'd together to create a single silhouette which is then used to

  1761 restrict the region onto which paint can be applied. Thus, a point is inside

  1762 the clipping path if it is inside any of the children of the

  1763 <a>'clipPath'</a>.</p>

  1765 <p>For a given graphics element, the actual clipping path used

  1766 will be the intersection of the clipping path specified by its

  1767 'clip-path' property (if any) with any clipping paths on its

  1768 ancestors, as specified by the 'clip-path' property on the

  1769 elements

  1770 which establish a new viewport. (See [[SVG11]])</p>

  1772 <p>A couple of additions:</p>

  1774 <ul>

  1775   <li>The <a>'clipPath'</a> element itself and its child elements do

  1776   <em>not</em> inherit clipping paths from the ancestors of the

  1777   <a>'clipPath'</a> element.</li>

  1779   <li>The <a>'clipPath'</a> element or any of its children can specify

  1780   property 'clip-path'.<br /> If a valid 'clip-path' reference

  1781   is placed on a <a>'clipPath'</a> element, the resulting clipping path is the

  1782   intersection of the contents of the <a>'clipPath'</a> element with the

  1783   referenced clipping path.<br />

  1784   If a valid 'clip-path' reference is placed on one of the children of

  1785   a <a>'clipPath'</a> element, then the given child element is clipped by the

  1786   referenced clipping path before OR'ing the silhouette of the child element

  1787   with the silhouettes of the other child elements.</li>

  1789   <li>An empty clipping path will completely clip away the element that had the

  1790   'clip-path' property applied.</li>

  1791 </ul>

  1793 <h3 id="clipPath-geometry">Clipping paths, geometry, and pointer events</h3>

  1795 <p>A clipping path is conceptually equivalent to a custom viewport for

  1796 the referencing element.  Thus, it affects the rendering of an element,

  1797 but not the element's inherent geometry. The <span class=index>bounding client rect</span> of a clipped

  1798 element (that is, an element which references a <a>'clipPath'</a>

  1799 element via a 'clip-path' property, or a child of the

  1800 referencing element) must remain the same as if it were not clipped.</p>

  1802 <p>By default, <a>pointer events</a>

  1803 must not be dispatched on the clipped (non-visible) regions of a shape.  For

  1804 example, a circle with a radius of 10 which is clipped to a circle with a radius

  1805 of 5 will not receive <span class="event-name">'click'</span> events outside the

  1806 smaller radius. Later versions of this specification may define new properties to enable

  1807 fine-grained control over the interactions between hit testing and clipping.</p>

  1809 <h2 id="security">Security</h2>

  1811 <h3 id="origin-restrictions">Origin Restrictions</h3>

  1813 <p>

  1814   External references to resources like <a>'mask element'</a> or <a>'clipPath element'</a>

  1815   must not violate the same origin restrictions [[!CORS]].

  1816 </p>

  1818 <p>This restriction includes:</p>

  1820 <ul>

  1821   <li>Any images, either as content or via styling, that are not exposed with CORS</li>

  1822   <li>Any tainted canvas</li>

  1823   <li>Any cross-origin content referenced by ''xlink:href'' or &lt;use&gt;</li>

  1824 </ul>

  1826 <p>

  1827   If content falls under this restriction, the resource must be rejected. The element is

  1828   drawn as if the resource was not specified (i.e. the 'clip-path' or 'mask' property were

  1829   set to ''none'').

  1830 </p>

  1832 <h2 id="DOMInterfaces">DOM interfaces</h2>

  1834 <h3 id="InterfaceSVGClipPathElement">Interface SVGClipPathElement</h3>

  1836 <p>The <a>SVGClipPathElement</a> interface corresponds to the <a>'clipPath'</a> element.</p>

  1838 <pre class="idl">interface <b>SVGClipPathElement</b> : <a>SVGElement</a> {

  1839   readonly attribute <a>SVGAnimatedEnumeration</a> <a href="#SVGClipPathElement__clipPathUnits">clipPathUnits</a>;

  1840   readonly attribute <a>SVGAnimatedTransformList</a> <a href="#SVGClipPathElement__transform">transform</a>;

  1841 };

  1843 <a>SVGClipPathElement</a> implements <a>SVGUnitTypes</a>;</pre>

  1845 <dl class="interface">

  1846 <dt class="attributes-header">Attributes:</dt>

  1847 <dd>

  1848 <dl class="attributes">

  1850 <dt id="SVGClipPathElement__clipPathUnits" class="attribute first-child"><b>clipPathUnits</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedEnumeration</a>)</span></dt>

  1851 <dd class="attribute">

  1852 <div>

  1853 Corresponds to attribute <a>'clipPathUnits'</a> on the given

  1854 <a>'clipPath'</a> element.  Takes one of the constants defined in

  1855 <a>SVGUnitTypes</a>.

  1856 </div>

  1857 </dd>

  1859 <dt id="SVGClipPathElement__transform" class="attribute first-child"><b>transform</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedTransformList</a>)</span></dt>

  1860 <dd class="attribute">

  1861 <div>

  1862 Corresponds to attribute <a>'transform'</a> on the given element.

  1863 </div>

  1864 </dd>

  1865 </dl>

  1866 </dd>

  1867 </dl>

  1869 <h3 id="InterfaceSVGMaskElement">Interface SVGMaskElement</h3>

  1871 <p>The <a>SVGMaskElement</a> interface corresponds to the <a>'mask element'</a> element.</p>

  1873 <pre class="idl">interface <b>SVGMaskElement</b> : <a>SVGElement</a> {

  1874   readonly attribute <a>SVGAnimatedEnumeration</a> <a href="#SVGMaskElement__maskUnits">maskUnits</a>;

  1875   readonly attribute <a>SVGAnimatedEnumeration</a> <a href="#SVGMaskElement__maskContentUnits">maskContentUnits</a>;

  1876   readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__x">x</a>;

  1877   readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__y">y</a>;

  1878   readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__width">width</a>;

  1879   readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__height">height</a>;

  1880 };

  1882 <a>SVGMaskElement</a> implements <a>SVGUnitTypes</a>;</pre>

  1884 <dl class="interface">

  1885 </dd>

  1886 <dt class="attributes-header">Attributes:</dt>

  1887 <dd>

  1888 <dl class="attributes">

  1890 <dt id="SVGMaskElement__maskUnits" class="attribute first-child"><b>maskUnits</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedEnumeration</a>)</span></dt>

  1891 <dd class="attribute">

  1892 <div>

  1893 Corresponds to attribute <a>'maskUnits'</a> on the given

  1894 <a>'mask element'</a> element.  Takes one of the constants defined in

  1895 <a>SVGUnitTypes</a>.

  1896 </div>

  1897 </dd>

  1899 <dt id="SVGMaskElement__maskContentUnits" class="attribute"><b>maskContentUnits</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedEnumeration</a>)</span></dt>

  1900 <dd class="attribute">

  1901 <div>

  1902 Corresponds to attribute <a>'maskContentUnits'</a> on the given

  1903 <a>'mask element'</a> element.  Takes one of the constants defined in

  1904 <a>SVGUnitTypes</a>.

  1906 </div>

  1907 </dd>

  1909 <dt id="SVGMaskElement__x" class="attribute"><b>x</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>

  1910 <dd class="attribute">

  1911 <div>

  1912 Corresponds to attribute <a>'mask/x'</a> on the given <a>'mask element'</a>

  1913 element.

  1915 </div>

  1916 </dd>

  1918 <dt id="SVGMaskElement__y" class="attribute"><b>y</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>

  1919 <dd class="attribute">

  1920 <div>

  1921 Corresponds to attribute <a>'mask/y'</a> on the given <a>'mask element'</a>

  1922 element.

  1924 </div>

  1925 </dd>

  1927 <dt id="SVGMaskElement__width" class="attribute"><b>width</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>

  1928 <dd class="attribute">

  1929 <div>

  1930 Corresponds to attribute <a>'mask/width'</a> on the given

  1931 <a>'mask element'</a> element.

  1933 </div>

  1934 </dd>

  1936 <dt id="SVGMaskElement__height" class="attribute"><b>height</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>

  1937 <dd class="attribute">

  1938 <div>

  1939 Corresponds to attribute <a>'mask/height'</a> on the given

  1940 <a>'mask element'</a> element.

  1942 </div>

  1943 </dd>

  1944 </dl>

  1945 </dd>

  1946 </dl>

  1948 <h2 id="conformance">

  1949 Conformance</h2>

  1951 <h3 id="conventions">

  1952 Document conventions</h3>

  1954   <p>Conformance requirements are expressed with a combination of

  1955   descriptive assertions and RFC 2119 terminology. The key words “MUST”,

  1956   “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,

  1957   “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this

  1958   document are to be interpreted as described in RFC 2119.

  1959   However, for readability, these words do not appear in all uppercase

  1960   letters in this specification.

  1962   <p>All of the text of this specification is normative except sections

  1963   explicitly marked as non-normative, examples, and notes. [[!RFC2119]]</p>

  1965   <p>Examples in this specification are introduced with the words “for example”

  1966   or are set apart from the normative text with <code>class="example"</code>,

  1967   like this:

  1969   <div class="example">

  1970     <p>This is an example of an informative example.</p>

  1971   </div>

  1973   <p>Informative notes begin with the word “Note” and are set apart from the

  1974   normative text with <code>class="note"</code>, like this:

  1976   <p class="note">Note, this is an informative note.</p>

  1978 <h3 id="conformance-classes">

  1979 Conformance classes</h3>

  1981   <p>Conformance to CSS Masking

  1982   is defined for three conformance classes:

  1983   <dl>

  1984     <dt><dfn title="style sheet!!as conformance class">style sheet</dfn>

  1985       <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS

  1986       style sheet</a>.

  1987     <dt><dfn>renderer</dfn></dt>

  1988       <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a>

  1989       that interprets the semantics of a style sheet and renders

  1990       documents that use them.

  1991     <dt><dfn id="authoring-tool">authoring tool</dfn></dt>

  1992       <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a>

  1993       that writes a style sheet.

  1994   </dl>

  1996   <p>A style sheet is conformant to CSS Masking

  1997   if all of its statements that use syntax defined in this module are valid

  1998   according to the generic CSS grammar and the individual grammars of each

  1999   feature defined in this module.

  2001   <p>A renderer is conformant to CSS Masking

  2002   if, in addition to interpreting the style sheet as defined by the

  2003   appropriate specifications, it supports all the features defined

  2004   by CSS Masking by parsing them correctly

  2005   and rendering the document accordingly. However, the inability of a

  2006   UA to correctly render a document due to limitations of the device

  2007   does not make the UA non-conformant. (For example, a UA is not

  2008   required to render color on a monochrome monitor.)

  2010   <p>An authoring tool is conformant to CSS Masking

  2011   if it writes style sheets that are syntactically correct according to the

  2012   generic CSS grammar and the individual grammars of each feature in

  2013   this module, and meet all other conformance requirements of style sheets

  2014   as described in this module.

  2016 <h3 id="partial">

  2017 Partial implementations</h3>

  2019   <p>So that authors can exploit the forward-compatible parsing rules to

  2020   assign fallback values, CSS renderers <strong>must</strong>

  2021   treat as invalid (and <a href="http://www.w3.org/TR/CSS21/conform.html#ignore">ignore

  2022   as appropriate</a>) any at-rules, properties, property values, keywords,

  2023   and other syntactic constructs for which they have no usable level of

  2024   support. In particular, user agents <strong>must not</strong> selectively

  2025   ignore unsupported component values and honor supported values in a single

  2026   multi-value property declaration: if any value is considered invalid

  2027   (as unsupported values must be), CSS requires that the entire declaration

  2028   be ignored.</p>

  2030 <h3 id="experimental">

  2031 Experimental implementations</h3>

  2033   <p>To avoid clashes with future CSS features, the CSS2.1 specification

  2034   reserves a <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed

  2035   syntax</a> for proprietary and experimental extensions to CSS.

  2037   <p>Prior to a specification reaching the Candidate Recommendation stage

  2038   in the W3C process, all implementations of a CSS feature are considered

  2039   experimental. The CSS Working Group recommends that implementations

  2040   use a vendor-prefixed syntax for such features, including those in

  2041   W3C Working Drafts. This avoids incompatibilities with future changes

  2042   in the draft.

  2043   </p>

  2045 <h3 id="testing">

  2046 Non-experimental implementations</h3>

  2048   <p>Once a specification reaches the Candidate Recommendation stage,

  2049   non-experimental implementations are possible, and implementors should

  2050   release an unprefixed implementation of any CR-level feature they

  2051   can demonstrate to be correctly implemented according to spec.

  2053   <p>To establish and maintain the interoperability of CSS across

  2054   implementations, the CSS Working Group requests that non-experimental

  2055   CSS renderers submit an implementation report (and, if necessary, the

  2056   testcases used for that implementation report) to the W3C before

  2057   releasing an unprefixed implementation of any CSS features. Testcases

  2058   submitted to W3C are subject to review and correction by the CSS

  2059   Working Group.

  2061   <p>Further information on submitting testcases and implementation reports

  2062   can be found from on the CSS Working Group's website at

  2063   <a href="http://www.w3.org/Style/CSS/Test/">http://www.w3.org/Style/CSS/Test/</a>.

  2064   Questions should be directed to the

  2065   <a href="http://lists.w3.org/Archives/Public/public-css-testsuite">public-css-testsuite@w3.org</a>

  2066   mailing list.

  2068 <h2 class=no-num id="references">

  2069 References</h2>

  2071 <h3 class="no-num" id="normative-references">

  2072 Normative references</h3>

  2073 <!--normative-->

  2074 <dl>

  2075   <dt id="ref-svg2"><strong class="normref">[SVG2]</strong></dt>

  2076     <dd>

  2077       Cameron McCormack; et al. <a href="http://www.w3.org/TR/2012/WD-SVG2-20120828/"><cite>Scalable

  2078       Vector Graphics (SVG) 2</cite>.</a> 28 August 2012. W3C Working Draft. (Work in progress.) URL:

  2079       <a href="http://www.w3.org/TR/2012/WD-SVG2-20120828/">http://www.w3.org/TR/2012/WD-SVG2-20120828/</a>

  2080     </dd>

  2081 </dl>

  2083 <h3 class="no-num" id="other-references">

  2084 Other references</h3>

  2085 <!--informative-->

  2087 <h2 class="no-num" id="index">

  2088 Index</h2>

  2089 <!--index-->

  2091 <h2 class="no-num" id="property-index">

  2092 Property index</h2>

  2093 <!-- properties -->

  2095 </body>

  2096 </html>

  2097 <!-- Keep this comment at the end of the file

  2098 Local variables:

  2099 mode: sgml

  2100 sgml-declaration:"~/SGML/HTML4.decl"

  2101 sgml-default-doctype-name:"html"

  2102 sgml-minimize-attributes:t

  2103 sgml-nofill-elements:("pre" "style" "br")

  2104 sgml-live-element-indicator:t

  2105 sgml-omittag:nil

  2106 sgml-shorttag:nil

  2107 sgml-namecase-general:t

  2108 sgml-general-insert-case:lower

  2109 sgml-always-quote-attributes:t

  2110 sgml-indent-step:nil

  2111 sgml-indent-data:t

  2112 sgml-parent-document:nil

  2113 sgml-exposed-tags:nil

  2114 sgml-local-catalogs:nil

  2115 sgml-local-ecat-files:nil

  2116 End:

  2117 -->

Mercurial > drafts / file revision

masking/Masking.src.html@59236286d848

masking/Masking.src.html