masking/Masking.src.html

Wed, 13 Mar 2013 13:16:38 -0700

author
Dirk Schulze <dschulze@adobe.com>
date
Wed, 13 Mar 2013 13:16:38 -0700
changeset 746
f0bee7474714
parent 741
cd0593275768
child 805
f984d3d17e42
permissions
-rw-r--r--

http://lists.w3.org/Archives/Public/www-style/2013Mar/0228.html

dschulze@344 1 <!DOCTYPE html public '-//W3C//DTD HTML 4.01//EN'
dschulze@344 2 'http://www.w3.org/TR/html4/strict.dtd'>
dschulze@273 3 <html lang="en">
dschulze@273 4 <head>
dschulze@273 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
dschulze@273 6 <title>CSS Masking</title>
dschulze@273 7 <link rel=contents href="#contents">
dschulze@273 8 <link rel=index href="#index">
dschulze@273 9 <link rel="stylesheet" type="text/css" href="default.css">
dschulze@273 10 <link rel="stylesheet" type="text/css"
dschulze@273 11 href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
dschulze@696 12 <script defer=defer
dschulze@696 13 src="http://test.csswg.org/harness/annotate.js#CSS-MASKING_DEV"
dschulze@696 14 type="text/javascript"></script>
dschulze@273 15 </head>
dschulze@273 16
dschulze@273 17 <div class="head">
dschulze@273 18 <!--logo-->
dschulze@273 19
dschulze@273 20 <h1>CSS Masking</h1>
dschulze@273 21
dschulze@273 22 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
dschulze@273 23 <dl>
dschulze@273 24 <dt>This version:
dschulze@708 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>
dschulze@273 26 <!--http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]/-->
dschulze@273 27
dschulze@273 28 <dt>Latest version:
dschulze@273 29 <dd><a href="http://www.w3.org/TR/css-masking/">[LATEST]</a>
dschulze@273 30
dschulze@273 31 <dt>Editor's draft:
dschulze@708 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>
dschulze@273 33
dschulze@273 34 <dt>Editors:
dschulze@427 35 <dd class="vcard">
dschulze@427 36 <span class="fn">Dirk Schulze</span>,
dschulze@427 37 <span class="org">Adobe Systems</span>,
dschulze@427 38 <span class="email">dschulze@adobe.com</span>
dschulze@427 39 </dd>
dschulze@427 40 <dd class="vcard">
birtles@438 41 <span class="fn">Brian Birtles</span>,
birtles@438 42 <span class="org">Mozilla Japan</span>,
birtles@438 43 <span class="email">bbirtles@mozilla.com</span>
birtles@438 44 </dd>
dschulze@441 45 <dd class="vcard">
dschulze@441 46 <span class="fn"><a href="http://www.xanthir.com/contact/">Tab Atkins Jr.</a></span>,
dschulze@441 47 <span class="org">Google, Inc.</span>
dschulze@441 48 </dd>
dschulze@273 49 </dl>
dschulze@273 50
dschulze@273 51 <!--copyright-->
dschulze@273 52
dschulze@273 53 <hr title="Separator for header">
dschulze@273 54 </div>
dschulze@273 55
dschulze@273 56 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
dschulze@273 57
dschulze@453 58 <p>
birtles@466 59 CSS Masking provides two means for partially or fully hiding portions of
birtles@466 60 visual elements: masking and clipping.
dschulze@454 61 </p>
dschulze@454 62
dschulze@454 63 <p>
birtles@466 64 Masking describes how to use another graphical element or image as a luminance
birtles@466 65 or alpha mask.
dschulze@279 66 Typically, rendering an element via CSS or SVG can conceptually described as if the element,
birtles@466 67 including its children, are drawn into a buffer and then that buffer is composited
birtles@466 68 into the element's parent.
birtles@466 69 Luminance and alpha masks influence the transparency of this buffer before the
birtles@466 70 compositing stage.
dschulze@453 71 </p>
dschulze@273 72
dschulze@454 73 <p>
birtles@466 74 Clipping describes the visible region of visual elements.
birtles@466 75 The region can be described by using certain SVG graphics elements or basic
birtles@466 76 shapes.
birtles@466 77 Anything outside of this region is not rendered.
dschulze@454 78 </p>
dschulze@454 79
dschulze@273 80 <h2 class="no-num no-toc" id="status">Status of this document</h2>
dschulze@273 81
dschulze@273 82 <!--status-->
dschulze@273 83
dschulze@273 84 <h2 class="no-num no-toc" id="contents">
dschulze@273 85 Table of contents</h2>
dschulze@273 86
dschulze@273 87 <!--toc-->
dschulze@273 88
dschulze@273 89 <h2 id="intro">
dschulze@273 90 Introduction
dschulze@273 91 </h2>
dschulze@273 92
dschulze@273 93 <p>
dschulze@454 94 With CSS Masking it is possible to specify another graphics element, shape or file
dschulze@454 95 to be used as clipping region or an luminance or alpha mask for compositing the current object into the
dschulze@273 96 background.
dschulze@273 97 </p>
dschulze@273 98
dschulze@273 99 <p>
dschulze@454 100 A mask is applied using the 'mask', 'mask-image' or 'mask-box-image' properties.
dschulze@281 101 The mask source may be defined using a <a>'mask element'</a> element referenced
dschulze@281 102 by the 'mask' property.
dschulze@281 103 Alternatively, for many simple uses, the 'mask-image' property may
dschulze@281 104 refer directly to graphical elements or images to be used as mask
dschulze@281 105 forgoing the need for an explicit <a>'mask element'</a> element. The
dschulze@281 106 'mask' property is also a shorthand for other masking properties.
dschulze@486 107 'mask-box-image' splits a mask image into 9 pieces. The pieces may be sliced,
dschulze@454 108 scaled and stretched in various ways to fit the size of the mask image area.
dschulze@273 109 </p>
dschulze@273 110
dschulze@273 111 <p>
dschulze@281 112 The effect of applying a mask is as if the mask images or mask source elements are
dschulze@486 113 rendered into an off-screen image which has been initialized to transparent
dschulze@273 114 black.
dschulze@273 115 The graphical object to which the mask is applied
dschulze@273 116 will be painted onto the background through the
dschulze@273 117 mask, thus completely or partially masking out parts of the graphical
dschulze@273 118 object.
dschulze@273 119 </p>
dschulze@273 120
dschulze@454 121 <p>
dschulze@454 122 Clipping defines a visible region of a visual element. The region can be specified with SVG <a>graphics element</a> or
dschulze@454 123 basic shapes. Everything outside of a region does not get rendered.
dschulze@454 124 </p>
dschulze@454 125
dschulze@273 126 <div class="example">
dschulze@311 127 <div class=figure>
dschulze@311 128 <img src="images/luminance-mask.svg" width="655px" height="260px" alt="Example Mask">
dschulze@453 129 <p class=caption>
dschulze@453 130 A luminance mask (middle) is applied on a shape filled with a gradient (left). This results in a masked shape
dschulze@453 131 (right).
dschulze@453 132 </p>
dschulze@311 133 </div>
dschulze@273 134 </div>
dschulze@273 135
dschulze@279 136 <h2 id="placement">Module interactions</h2>
dschulze@273 137
dschulze@279 138 <p>This specification defines a set of CSS properties that affect the visual rendering of elements to which
dschulze@273 139 those properties are applied; these effects are applied after elements have been sized and positioned according
dschulze@273 140 to the <a href="http://www.w3.org/TR/CSS2/visuren.html" title="Visual formatting model">Visual formatting model</a>
dschulze@453 141 from [[!CSS21]]. Some values of these properties result in the creation of a
dschulze@453 142 <a href="http://www.w3.org/TR/CSS2/visuren.html#containing-block" title="Visual formatting model">containing block</a>,
dschulze@453 143 and/or the creation of a <a href="http://www.w3.org/TR/CSS2/visuren.html#z-index" title="Visual formatting model">stacking
dschulze@453 144 context</a>.
dschulze@273 145 </p>
dschulze@273 146
dschulze@746 147 <h2 id="values">Values</h2>
dschulze@746 148
dschulze@659 149 <p>
dschulze@746 150 This specification follows the <a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition
dschulze@746 151 conventions</a> from [[!CSS21]]. Value types not defined in this specification are defined in CSS Values and Units Module Level 3 [[!CSS3VAL]].
dschulze@746 152 </p>
dschulze@746 153
dschulze@746 154 <p>
dschulze@746 155 In addition to the property-specific values listed in their definitions, all properties defined in this specification
dschulze@746 156 also accept the <a href="http://www.w3.org/TR/CSS21/cascade.html#value-def-inherit">inherit</a> keyword as their
dschulze@746 157 property value. For readability it has not been repeated explicitly.
dschulze@746 158 </p>
dschulze@746 159
dschulze@746 160 <h2 id="terminology">Terminology</h2>
dschulze@746 161
dschulze@746 162 <p>
dschulze@746 163 When used in this specification, terms have the meanings assigned in this section.
dschulze@746 164 </p>
dschulze@746 165
dschulze@746 166 <dl>
dschulze@746 167 <dt id="TermClientBoundingRect"><dfn>bounding client rect</dfn></dt>
dschulze@746 168 <dd>
dschulze@746 169 <p>
dschulze@746 170 The union of all border boxes for the element that has an associated CSS layout box and is not
dschulze@746 171 in the <code>http://www.w3.org/2000/svg</code> namespace and its descendant elements. Or the
dschulze@746 172 object bounding box [[!SVG11]], if the element does not have
dschulze@746 173 an associated CSS layout box and is in the <code>http://www.w3.org/2000/svg</code> namespace
dschulze@746 174 (See <a href="http://www.w3.org/TR/cssom-view/#dom-element-getboundingclientrect">getBoundingClientRect</a>
dschulze@746 175 [[CSSOM-VIEW]]).
dschulze@746 176 </p>
dschulze@746 177 </dd>
dschulze@746 178 <dt id="TermLocalCoordinateSystem"><dfn>local coordinate system</dfn></dt>
dschulze@746 179 <dt id="TermUserCoordinateSystem"><dfn>user coordinate system</dfn></dt>
dschulze@746 180 <dd>
dschulze@746 181 <p>
dschulze@746 182 In general, a coordinate system defines locations and distances on the current
dschulze@746 183 canvas. The current local coordinate system (also user coordinate system) is the
dschulze@746 184 coordinate system that is currently active and which is used to define how
dschulze@746 185 coordinates and lengths are located and computed, respectively, on the current
dschulze@746 186 canvas [[CSS3-TRANSFORMS]].
dschulze@746 187 </p>
dschulze@746 188 <p>
dschulze@746 189 For elements that have an associated CSS layout box, the current user coordinate system has its origin at
dschulze@746 190 the top-left corner of the <span class="term">bounding client rect</span> and one unit equals one CSS pixel.
dschulze@746 191 The viewport for resolving percentage values is defined by the width and height of the
dschulze@746 192 <span class="term">bounding client rect</span>.
dschulze@746 193 </p>
dschulze@746 194 <p>
dschulze@746 195 If the element does not have an associated CSS layout box and is in the <code>http://www.w3.org/2000/svg</code>
dschulze@746 196 namespace, the current local coordinate system has its origin at the top-left corner of the element's
dschulze@746 197 nearest viewport.
dschulze@746 198 </p>
dschulze@746 199 </dd>
dschulze@746 200 <dt id="TermObjectBoundingBoxUnits"><dfn>object bounding box units</dfn></dt>
dschulze@746 201 <dd>
dschulze@746 202 The <span class="term">bounding client rect</span> defines the coordinate system in which to resolve values, as
dschulze@746 203 defined in <a>object bounding box units</a> [[!SVG11]].
dschulze@746 204 </dd>
dschulze@746 205 <dt id="TermMask"><dfn>mask</dfn></dt>
dschulze@746 206 <dd>
dschulze@746 207 An off-screen image which has been initialized to transparent
dschulze@746 208 black.
dschulze@746 209 The graphical object to which the mask is applied
dschulze@746 210 will be painted onto the background through the
dschulze@746 211 mask, thus completely or partially masking out parts of the graphical
dschulze@746 212 object.
dschulze@746 213 </dd>
dschulze@746 214 <dt id="TermMaskSource"><dfn>mask source</dfn></dt>
dschulze@746 215 <dd>
dschulze@746 216 A mask defined by a <a>'mask element'</a> element.
dschulze@746 217 </dd>
dschulze@746 218 <dt id="TermClippingPath">clipping path</dt>
dschulze@746 219 <dd>
dschulze@746 220 A combination of the SVG elements <a>'path'</a>, <a>'text'</a>
dschulze@746 221 and <a>basic shapes</a> which serve as the
dschulze@746 222 outline of a (in the absence of anti-aliasing) 1-bit <a href="#TermMask">mask</a>,
dschulze@746 223 where everything on the "inside" of the outline is allowed to
dschulze@746 224 show through but everything on the outside is masked out. See 'clip-path'.
dschulze@746 225 </dd>
dschulze@746 226 </dl>
dschulze@746 227
dschulze@746 228 <p>
dschulze@746 229 Definitions of CSS properties and values in this specification are analogous to definitions in CSS Backgrounds and Borders [[!CSS3BG]]. To avoid redundancy, this specification relies on descriptions and definitions of CSS Backgrounds and Borders. The following terms in CSS Backgrounds and Borders have the following meaning in this specification:
dschulze@659 230 </p>
dschulze@659 231
dschulze@659 232 <table class="data" id="term-matching">
dschulze@659 233 <thead>
dschulze@659 234 <tr>
dschulze@659 235 <th>Term in [[!CSS3BG]]
dschulze@659 236 <th>Term in CSS Masking
dschulze@659 237 </tr>
dschulze@659 238 </thead>
dschulze@659 239 <tbody>
dschulze@659 240 <tr>
dschulze@659 241 <th>background images
dschulze@659 242 <td>mask images
dschulze@659 243 </tr>
dschulze@659 244 <tr>
dschulze@659 245 <th>background painting area
dschulze@659 246 <td>mask painting area
dschulze@659 247 </tr>
dschulze@659 248 <tr>
dschulze@659 249 <th>background-size
dschulze@659 250 <td>mask-size
dschulze@659 251 </tr>
dschulze@659 252 <tr>
dschulze@659 253 <th>background-position
dschulze@659 254 <td>mask-position
dschulze@659 255 </tr>
dschulze@659 256 <tr>
dschulze@659 257 <th>background positioning area
dschulze@659 258 <td>mask positioning area
dschulze@659 259 </tr>
dschulze@659 260 <tr>
dschulze@659 261 <th>border image area
dschulze@659 262 <td>mask box image area
dschulze@659 263 </tr>
dschulze@659 264 </tbody>
dschulze@659 265 </table>
dschulze@279 266
dschulze@281 267 <h2>The Mask Rendering Model</h2>
dschulze@279 268
dschulze@453 269 <p>
dschulze@453 270 The application of the 'clip-path', 'mask' or 'mask-image' properties to an element formatted with the CSS box model
dschulze@734 271 establishes a stacking context in the same way that CSS 'opacity' does, and all the element's descendants are rendered
dschulze@453 272 together as a group with the masking applied to the group as a whole.
dschulze@453 273 </p>
dschulze@279 274
dschulze@453 275 <p>
dschulze@734 276 The 'mask' and 'mask-image' properties have no effect on the geometry of any element's CSS boxes.
dschulze@453 277 </p>
dschulze@279 278
dschulze@453 279 <p>
dschulze@453 280 The compositing model follows the SVG compositing model [[!SVG11]]: first any filter effect is applied, then any
dschulze@453 281 clipping, masking and opacity. These effects all apply after any other CSS effects such as 'border'. As per SVG, the
dschulze@453 282 application of 'mask' or 'mask-image' has no effect on hit-testing.
dschulze@453 283 </p>
dschulze@279 284
dschulze@279 285 <h3 id="layering">Layering Multiple Mask Images</h3>
dschulze@279 286
dschulze@279 287 <p>The mask of a box can have multiple <span
dschulze@279 288 class=index>layers</span>. The number
dschulze@279 289 of layers is determined by the number of comma-separated values in the
dschulze@279 290 'mask-image' property. Note that a value of 'none' still creates
dschulze@279 291 a layer.
dschulze@279 292
dschulze@698 293 See <a href="http://www.w3.org/TR/css3-background/#layering">Layering Multiple Background Images</a> [[!CSS3BG]].
dschulze@279 294
dschulze@698 295 <p>The first layer is the layer closest to the user,
dschulze@281 296 the next one is painted behind the first, and so on. All mask images
dschulze@443 297 are transformed to alpha masks (if necessary) and combined by compositing
dschulze@443 298 on the <a href="#TermMask">mask</a>.
dschulze@279 299
dschulze@279 300 <h3 id="MaskValues">Calculating mask values</h3>
dschulze@279 301
dschulze@279 302 <p>
dschulze@281 303 A mask may be interpreted using one of two different methods with regards
dschulze@279 304 to calculating the mask values that will be multiplied with the target alpha
dschulze@279 305 values.
dschulze@279 306 </p>
dschulze@279 307
dschulze@279 308 <p>
dschulze@279 309 The first and simplest method of calculating the mask values is to use the alpha
dschulze@279 310 channel of the mask source.
dschulze@279 311 In this case the mask value at a given point is simply the value of the alpha channel at that point.
dschulze@279 312 The color channels do not contribute to the mask value.
dschulze@279 313 </p>
dschulze@279 314
dschulze@279 315 <p>
dschulze@453 316 The second method of calculating the mask values is to use the luminance of the mask source.
dschulze@453 317 In this case the mask value at a given point is computed from the color channel values and alpha channel value using
dschulze@453 318 the following procedure.
dschulze@279 319 </p>
dschulze@279 320
dschulze@279 321 <ol>
dschulze@279 322 <li>Compute a luminance value from the color channel values.
dschulze@279 323 <ul>
dschulze@279 324 <li>
dschulze@279 325 If the computed value of 'color-interpolation' on the <a>'mask element'</a> element is 'linearRGB', convert the
dschulze@279 326 original image color values (potentially in the sRGB color space) to the linear
dschulze@343 327 RGB color space.
dschulze@279 328 </li>
dschulze@279 329 <li>Then, using non-premultiplied RGB color values, apply the
dschulze@279 330 luminance-to-alpha coefficients (as defined in the <a>'feColorMatrix'</a>
dschulze@452 331 filter primitive [[!SVG11]]) to convert the RGB color values to luminance
dschulze@279 332 values.
dschulze@279 333 </li>
dschulze@279 334 </ul>
dschulze@279 335 </li>
dschulze@279 336 <li>Multiply the computed luminance value by the corresponding alpha
dschulze@279 337 value to produce the mask value.</li>
dschulze@279 338 </ol>
dschulze@279 339
dschulze@279 340 <p>Regardless of the method used, the procedure for calculating
dschulze@279 341 mask values assumes the content of the mask is a four-channel RGBA graphics
dschulze@279 342 object.
dschulze@279 343 For other types of graphics objects, special handling is required as
dschulze@279 344 follows.</p>
dschulze@279 345
dschulze@279 346 <p>For a three-channel RGB graphics object that is used in a mask (e.g.,
dschulze@279 347 when referencing a three-channel image file), the effect is as if the object
dschulze@279 348 were converted into a four-channel RGBA image with the alpha channel
dschulze@279 349 uniformly set to 1.</p>
dschulze@279 350
dschulze@279 351 <p>For a single-channel image that is used in a mask (e.g., when
dschulze@279 352 referencing a single-channel grayscale image file), the effect is as if the
dschulze@279 353 object were converted into a four-channel RGBA image, where the single
dschulze@279 354 channel from the referenced object is used to compute the three color
dschulze@724 355 channels and the alpha channel is uniformly set to 1.</p>
dschulze@724 356 <p class="note">Note that when
dschulze@279 357 referencing a grayscale image file, the transfer curve relating the
dschulze@279 358 encoded grayscale values to linear light values must be taken into
dschulze@279 359 account when computing the color channels.</p>
dschulze@279 360
dschulze@281 361 <p class="note">Note that SVG <a>graphics elements</a> (e.g., <a>'circle'</a> or <a>'text'</a>)
dschulze@281 362 are all treated as four-channel RGBA images for the purposes
dschulze@279 363 of masking operations.</p>
dschulze@279 364
dschulze@279 365 <p>The effect of a mask is identical to what would have happened if
dschulze@279 366 there were no mask but instead the alpha channel of the given object
dschulze@279 367 were multiplied with the mask's resulting mask values.</p>
dschulze@279 368
dschulze@292 369 <h2 id="masking">Mask</h2>
dschulze@292 370 <h3 id="the-mask-image">The 'mask-image' property</h3>
dschulze@274 371
dschulze@274 372 <table class="propdef">
dschulze@274 373 <tr>
dschulze@274 374 <th>Name:
dschulze@274 375 <td><dfn>mask-image</dfn>
dschulze@274 376 <tr>
dschulze@274 377 <th><a href="#values">Value</a>:
dschulze@607 378 <td><var>&lt;mask-reference&gt;</var>
dschulze@274 379 <tr>
dschulze@274 380 <th>Initial:
dschulze@274 381 <td>none
dschulze@274 382 <tr>
dschulze@274 383 <th>Applies to:
dschulze@274 384 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>
dschulze@274 385 <tr>
dschulze@274 386 <th>Inherited:
dschulze@274 387 <td>no
dschulze@274 388 <tr>
dschulze@274 389 <th>Percentages:
dschulze@274 390 <td>N/A
dschulze@274 391 <tr>
dschulze@274 392 <th>Media:
dschulze@274 393 <td>visual
dschulze@274 394 <tr>
dschulze@274 395 <th>Computed value:
dschulze@274 396 <td>as specified, but with URIs made absolute
dschulze@274 397 <tr>
dschulze@274 398 <th>Animatable:
dschulze@274 399 <td>no
dschulze@274 400 </table>
dschulze@274 401
dschulze@536 402 <p>This property sets the mask image(s) or the mask source of an element. Images
dschulze@274 403 are drawn with the first specified one on top (closest to the user)
dschulze@274 404 and each subsequent image behind the previous one.
birtles@435 405 Where:
dschulze@274 406
dschulze@607 407 <pre class=prod><var><dfn>&lt;mask-reference&gt;</dfn></var> = <var>&lt;mask-image&gt;</var># | <var>&lt;mask-element&gt;</var></pre>
dschulze@536 408
dschulze@536 409 <pre class=prod><var><dfn>&lt;mask-image&gt;</dfn></var> = <var>&lt;image&gt;</var> | none </pre>
dschulze@536 410
dschulze@607 411 <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>
dschulze@536 412
dschulze@536 413 <pre class=prod><dfn>&lt;child-selector&gt;</dfn> = select(<var>&lt;compound-selector&gt;</var>#)</pre>
dschulze@536 414
dschulze@607 415 <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>
dschulze@274 416
dschulze@277 417 <dl>
dschulze@536 418 <dt>
dschulze@536 419 <dfn>'&lt;url&gt;'</dfn>
dschulze@536 420 </dt>
dschulze@536 421 <dd>
dschulze@731 422 A URL reference to a <a>'mask element'</a> element (for example ''url(commonmasks.svg#mask)'') or an <var>&lt;image&gt;</var>.
dschulze@536 423 </dd>
birtles@697 424 <dt>''child''</dt>
dschulze@536 425 <dd>
dschulze@698 426 A keyword to indicate that the last direct sibling <a>'mask element'</a>
dschulze@698 427 element of the element the 'mask-image' property is applied should be used as the mask source. It is equivalent to
dschulze@536 428 ''select(mask:last-of-type)''.</dd>
birtles@697 429 <dt>'&lt;child-selector&gt;'</dt>
dschulze@536 430 <dd>
dschulze@536 431 A comma-separated list of <a>compound selector</a>s scoped at the element to
dschulze@698 432 which the 'mask-image' property is applied.
dschulze@536 433 The first matching element in <a>tree order</a> (as defined in [[!DOM]]) as
dschulze@536 434 a result of evaluating the list of selectors is taken as the mask source.
dschulze@536 435 If there are no matching elements the mask source is invalid.
dschulze@536 436 </dd>
dschulze@536 437 <dt><dfn>'&lt;compound-selector&gt;'</dfn></dt>
dschulze@536 438 <dd>
dschulze@536 439 A <a>compound selector</a> as defined in [[!SELECTORS4]].
dschulze@536 440 <dd>
birtles@287 441 <dt><dfn>&lt;image&gt;</dfn></dt>
dschulze@277 442 <dd>
dschulze@277 443 A 2D image. (See [[!CSS3-IMAGES]].)
dschulze@277 444 </dd>
birtles@439 445 <dt><dfn>''none''</dfn></dt>
birtles@439 446 <dd>
birtles@439 447 A value of ''none'' counts as an image layer but does not mask the element.
birtles@439 448 </dd>
dschulze@277 449 </dl>
dschulze@277 450
dschulze@615 451 <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>
dschulze@536 452
dschulze@536 453 <p>An invalid or non-existent mask source is ignored and no masking is applied.</p>
dschulze@536 454
birtles@436 455 <p>A mask image that is empty (zero width or zero height), that fails to
birtles@436 456 download, is non-existent, or that cannot be displayed (e.g. because it is not
birtles@436 457 in a supported image format) is ignored. No masking is applied.
dschulze@274 458
dschulze@274 459 <p>See the section <a href="#layering">“Layering multiple mask
dschulze@274 460 images”</a> for how 'mask-image' interacts with other
dschulze@274 461 comma-separated mask properties to form each mask image
dschulze@274 462 layer.
dschulze@274 463
dschulze@274 464 <div class="example">
dschulze@274 465 <p>Some examples specifying mask images:</p>
dschulze@274 466 <pre>
dschulze@274 467 body { mask-image: linear-gradient(black 0%, transparent 100%) }
dschulze@274 468 p { mask-image: none }
dschulze@274 469 div { mask-image: url(tl.png), url(tr.png) }
dschulze@274 470 </pre>
dschulze@536 471
dschulze@536 472 <p>Some examples of a specified mask source:</p>
dschulze@536 473 <pre>
dschulze@536 474 img { mask-image: url(#mask) }
dschulze@536 475 span { mask-image: url(resources.svg#mask2) }
dschulze@536 476 </pre>
dschulze@536 477
dschulze@536 478 <p>Examples of <i>invalid</i> mask source usages:</p>
dschulze@536 479 <pre>
dschulze@536 480 p { mask-image: url(#mask), url(tl.png) }
dschulze@536 481 img { mask-image: url(#mask), url(resources.svg#mask2) }
dschulze@536 482 </pre>
dschulze@615 483 <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.
dschulze@274 484 </div>
dschulze@274 485
dschulze@551 486 <h3 id="the-mask-source-type">The 'mask-source-type' property</h3>
dschulze@551 487
dschulze@551 488 <table class="propdef">
dschulze@551 489 <tr>
dschulze@551 490 <th>Name:
dschulze@551 491 <td><dfn>mask-source-type</dfn>
dschulze@551 492 <tr>
dschulze@551 493 <th><a href="#values">Value</a>:
dschulze@551 494 <td><var>&lt;source-type&gt;</var>#
dschulze@551 495 <tr>
dschulze@551 496 <th>Initial:
dschulze@551 497 <td>auto
dschulze@551 498 <tr>
dschulze@551 499 <th>Applies to:
dschulze@551 500 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>
dschulze@551 501 <tr>
dschulze@551 502 <th>Inherited:
dschulze@551 503 <td>no
dschulze@551 504 <tr>
dschulze@551 505 <th>Percentages:
dschulze@551 506 <td>N/A
dschulze@551 507 <tr>
dschulze@551 508 <th>Media:
dschulze@551 509 <td>visual
dschulze@551 510 <tr>
dschulze@551 511 <th>Computed value:
dschulze@551 512 <td>as specified
dschulze@551 513 <tr>
dschulze@551 514 <th>Animatable:
dschulze@731 515 <td>no
dschulze@551 516 </table>
dschulze@551 517
dschulze@551 518 <p>The 'mask-source-type' property indicates whether the <var>&lt;mask-reference&gt;</var>
dschulze@551 519 is treated as luminance mask or alpha mask. (See <a href="#MaskValues">Calculating mask values</a>.)</p>
dschulze@551 520
dschulze@551 521 <pre class=prod><dfn><var>&lt;source-type&gt;</var></dfn> = alpha | luminance | auto</pre>
dschulze@551 522
dschulze@551 523 <p>Values have the following meanings:
dschulze@551 524
dschulze@551 525 <dl>
dschulze@551 526 <dt><dfn>''alpha''</dfn></dt>
dschulze@551 527 <dd>
dschulze@551 528 A value of ''alpha'' indicates that the alpha values of the mask
dschulze@551 529 image should be used as the mask values.
dschulze@551 530 See <a href="#MaskValues">Calculating mask values</a>.</p>
dschulze@551 531 </dd>
dschulze@551 532 <dt><dfn>''luminance''</dfn></dt>
dschulze@551 533 <dd>
dschulze@551 534 A value of ''luminance'' indicates that the luminance values of the mask
dschulze@551 535 image should be used as the mask values.
dschulze@551 536 See <a href="#MaskValues">Calculating mask values</a>.</p>
dschulze@551 537 </dd>
dschulze@551 538 <dt><dfn>''auto''</dfn></dt>
dschulze@551 539 <dd>
dschulze@551 540 <p>
dschulze@552 541 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
dschulze@551 542 image should be used as the mask values.
dschulze@551 543 <p>
dschulze@615 544 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
dschulze@551 545 image should be used as the mask values.
dschulze@551 546 </dd>
dschulze@551 547 </dl>
dschulze@551 548
dschulze@552 549 <div class="example">
dschulze@552 550 <p>
dschulze@552 551 In the following example, the 'mask-type' property sets the mask type value for the <a>'mask element'</a> element to
dschulze@552 552 ''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''.
dschulze@552 553 <pre>
dschulze@552 554 &lt;mask id="SVGMask" mask-type="alpha" maskContentUnits="objectBoundingBox"&gt;
dschulze@552 555 &lt;radialGradient id="radialFill"&gt;
dschulze@552 556 &lt;stop stop-color="white" offset="0"/&gt;
dschulze@552 557 &lt;stop stop-color="black" offset="1"/&gt;
dschulze@552 558 &lt;/radialGradient&gt;
dschulze@552 559 &lt;circle fill="url(#radialFill)" cx="0.5" cy="0.5" r="0.5"/&gt;
dschulze@552 560 &lt;/mask&gt;
dschulze@552 561
dschulze@552 562 &lt;style&gt;
dschulze@552 563 rect {
dschulze@552 564 mask-image: url(#SVGMask);
dschulze@552 565 mask-source-type: luminance;
dschulze@552 566 }
dschulze@552 567 &lt;/style&gt;
dschulze@552 568
dschulze@552 569 &lt;rect width="200" height="200" fill="green"/&gt;
dschulze@552 570 </pre>
dschulze@552 571 </div>
dschulze@551 572
dschulze@292 573 <h3 id="the-mask-repeat">The 'mask-repeat' property</h3>
dschulze@274 574
dschulze@274 575 <table class="propdef">
dschulze@274 576 <tr>
dschulze@274 577 <th>Name:
dschulze@274 578 <td><dfn>mask-repeat</dfn>
dschulze@274 579 <tr>
dschulze@274 580 <th><a href="#values">Value</a>:
dschulze@280 581 <td><var>&lt;repeat-style&gt;</var>#
dschulze@274 582 <tr>
dschulze@274 583 <th>Initial:
dschulze@274 584 <td>repeat
dschulze@274 585 <tr>
dschulze@274 586 <th>Applies to:
dschulze@274 587 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>
dschulze@274 588 <tr>
dschulze@274 589 <th>Inherited:
dschulze@274 590 <td>no
dschulze@274 591 <tr>
dschulze@274 592 <th>Percentages:
dschulze@274 593 <td>N/A
dschulze@274 594 <tr>
dschulze@274 595 <th>Media:
dschulze@274 596 <td>visual
dschulze@274 597 <tr>
dschulze@274 598 <th>Computed value:
dschulze@274 599 <td>A list, each item consisting of:
dschulze@274 600 two keywords, one per dimension
dschulze@274 601 <tr>
dschulze@274 602 <th>Animatable:
dschulze@274 603 <td>no
dschulze@274 604 </table>
dschulze@274 605
dschulze@274 606 <p>Specifies how mask images are tiled after they have been
dschulze@274 607 <a href="#the-mask-size">sized</a> and <a href="#the-mask-position">positioned</a>.
dschulze@274 608 Where
dschulze@274 609 <pre class=prod><dfn><var>&lt;repeat-style&gt;</var></dfn> = repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}</pre>
dschulze@274 610
dschulze@746 611 <p>See <a href="http://www.w3.org/TR/css3-background/#the-background-repeat">Tiling Images: the 'background-repeat' property</a> [[!CSS3BG]] for the definitions of the property values.
dschulze@274 612
dschulze@282 613 <div class=example>
dschulze@282 614 <p style="display:none">Example(s):
dschulze@282 615 <pre>
dschulze@282 616 body {
dschulze@282 617 background-color: blue;
birtles@435 618 mask-image: url(dot-mask.png) luminance;
dschulze@282 619 mask-repeat: space;
dschulze@282 620 }
dschulze@282 621 </pre>
dschulze@282 622
dschulze@282 623 <div class=figure>
dschulze@282 624 <p><img src="images/mask-repeat.svg" alt="Image of an element with a dotted mask." width="240" style="border: solid black 1px;">
dschulze@282 625
dschulze@282 626 <p class=caption>The effect of 'space': the mask image of a dot is
dschulze@282 627 tiled to cover the whole <span class=index>mask painting area</span> and the mask images are equally
dschulze@282 628 spaced.
dschulze@282 629 </div>
dschulze@282 630 </div>
dschulze@282 631
dschulze@274 632 <p>See the section <a href="#layering">“Layering multiple mask
dschulze@277 633 images”</a> for how 'mask-repeat' interacts with other
dschulze@274 634 comma-separated mask properties to form each mask image
dschulze@274 635 layer.
dschulze@274 636
dschulze@292 637 <h3 id="the-mask-position">The 'mask-position' property</h3>
dschulze@274 638
dschulze@274 639 <table class="propdef">
dschulze@274 640 <tr>
dschulze@274 641 <th>Name:
dschulze@274 642 <td><dfn>mask-position</dfn>
dschulze@274 643 <tr>
dschulze@274 644 <th><a href="#values">Value</a>:
dschulze@274 645
dschulze@280 646 <td><var>&lt;position&gt;</var>#
dschulze@274 647 <tr>
dschulze@274 648 <th>Initial:
dschulze@274 649 <td>0% 0%
dschulze@274 650 <tr>
dschulze@274 651 <th>Applies to:
dschulze@274 652 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>
dschulze@274 653 <tr>
dschulze@274 654 <th>Inherited:
dschulze@274 655 <td>no
dschulze@274 656 <tr>
dschulze@274 657 <th>Percentages:
dschulze@274 658 <td>refer to size of <span class=index>mask painting area</span> <em>minus</em> size of mask image; see text
dschulze@274 659 <tr>
dschulze@274 660 <th>Media:
dschulze@274 661 <td>visual
dschulze@274 662 <tr>
dschulze@274 663 <th>Computed value:
dschulze@274 664 <td>A list, each item consisting of:
dschulze@274 665 two keywords representing the origin and two offsets from that
dschulze@274 666 origin, each given as an absolute length (if given a &lt;length&gt;),
dschulze@274 667 otherwise as a percentage.
dschulze@274 668 <tr>
dschulze@274 669 <th>Animatable:
dschulze@731 670 <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>
dschulze@274 671 </table>
dschulze@274 672
dschulze@274 673 <p>Where
dschulze@274 674 <pre class=prod><dfn><var>&lt;position&gt;</var></dfn> = [
dschulze@274 675 [ left | center | right | top | bottom | <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]
dschulze@274 676 |
dschulze@274 677 [ left | center | right | <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]
dschulze@274 678 [ top | center | bottom | <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]
dschulze@274 679 |
dschulze@274 680 [ center | [ left | right ] [ <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]? ] &amp;&amp;
dschulze@274 681 [ center | [ top | bottom ] [ <var>&lt;percentage&gt;</var> | <var>&lt;length&gt;</var> ]? ]
dschulze@274 682 ]</pre>
dschulze@274 683
dschulze@746 684 <p>See <a href="http://www.w3.org/TR/css3-background/#the-background-position">Positioning Images: the 'background-position' property</a> [[!CSS3BG]] for the definitions of the property values.
dschulze@274 685
dschulze@274 686 <div class="example">
dschulze@274 687 <p>In the example below, the (single) image is placed in the lower-right
dschulze@274 688 corner of the viewport.
dschulze@274 689 <pre>
dschulze@274 690 body {
dschulze@274 691 mask-image: url("logo.png");
dschulze@274 692 mask-position: 100% 100%;
dschulze@274 693 mask-repeat: no-repeat;
dschulze@274 694 }
dschulze@274 695 </pre>
dschulze@274 696 </div>
dschulze@274 697
dschulze@274 698 <div class=example>
dschulze@274 699 <p>Mask positions can also be relative to other corners than the
dschulze@274 700 top left. E.g., the following puts the background image 10px from the
dschulze@274 701 bottom and 3em from the right:
dschulze@274 702
dschulze@274 703 <pre>mask-position: right 3em bottom 10px</pre>
dschulze@274 704 </div>
dschulze@274 705
dschulze@274 706 <p>See the section <a href="#layering">“Layering multiple mask
dschulze@277 707 images”</a> for how 'mask-position' interacts with other
dschulze@274 708 comma-separated mask properties to form each mask image
dschulze@274 709 layer.
dschulze@274 710
dschulze@292 711 <h3 id="the-mask-clip">The 'mask-clip' property</h3>
dschulze@274 712
dschulze@274 713 <table class="propdef">
dschulze@274 714 <tr>
dschulze@274 715 <th>Name:
dschulze@274 716 <td><dfn>mask-clip</dfn>
dschulze@274 717 <tr>
dschulze@274 718 <th><a href="#values">Value</a>:
dschulze@615 719 <td><var>&lt;clip-box&gt;</var>#
dschulze@274 720 <tr>
dschulze@274 721 <th>Initial:
dschulze@274 722 <td>border-box
dschulze@274 723 <tr>
dschulze@274 724 <th>Applies to:
dschulze@274 725 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>
dschulze@274 726 <tr>
dschulze@274 727 <th>Inherited:
dschulze@274 728 <td>no
dschulze@274 729 <tr>
dschulze@274 730 <th>Percentages:
dschulze@274 731 <td>N/A
dschulze@274 732 <tr>
dschulze@274 733 <th>Media:
dschulze@274 734 <td>visual
dschulze@274 735 <tr>
dschulze@274 736 <th>Computed value:
dschulze@274 737 <td>as specified
dschulze@274 738 <tr>
dschulze@274 739 <th>Animatable:
dschulze@274 740 <td>no
dschulze@274 741 </table>
dschulze@274 742
dschulze@274 743 <p>Determines the <dfn id="mask-painting-area">mask painting area</dfn>,
dschulze@474 744 which determines the area that is affected by the mask. The painted content
dschulze@474 745 of an element may be resricted to this area.
dschulze@274 746 The syntax of the property is given with
dschulze@274 747
dschulze@615 748 <pre class=prod><dfn><var>&lt;clip-box&gt;</var></dfn> = <var>&lt;box&gt;</var> | no-clip</pre>
dschulze@615 749 <pre class=prod><dfn><var>&lt;box&gt;</var></dfn> = border-box | padding-box | content-box</pre>
dschulze@274 750
dschulze@274 751 <p>Values have the following meanings:
dschulze@274 752
dschulze@274 753 <dl>
dschulze@274 754 <dt><dfn title="''border-box''!!'mask-clip' value">
dschulze@274 755 ''border-box''</dfn></dt>
dschulze@474 756 <dd>The painted content is rectricted to (clipped to) the
dschulze@432 757 <span>border box</span> respectively <span>painting box</span> for objects without associated layout box.
dschulze@274 758 <dt><dfn title="''padding-box''!!'mask-clip' value">
dschulze@274 759 ''padding-box''</dfn></dt>
dschulze@474 760 <dd>The painted content is rectricted to (clipped to) the
dschulze@274 761 <span>padding box.</span>
dschulze@274 762 <dt><dfn title="''content-box''!!'mask-clip' value">
dschulze@615 763 ''content-box''</dfn></dt>
dschulze@474 764 <dd>The painted content is rectricted to (clipped to) the
dschulze@615 765 <span>content box</span> respectively <span>object bounding box</span> [[!SVG11]] for objects without associated layout box.
dschulze@536 766 <dt><dfn title="''no-clip''!!'mask-clip' value">
dschulze@536 767 ''no-clip''</dfn></dt>
dschulze@474 768 <dd>The painted content is not restricted (not clipped). The <span>mask painting area</span> is set to
dschulze@474 769 the <span>bounding client rect</span>.
dschulze@274 770 </dl>
dschulze@274 771
dschulze@432 772 <p class="note">Note that there is no corresponding box for
dschulze@432 773 ''padding-box'' on objects without associated layout box
dschulze@432 774 and ''content-box'' is choosen instead.</p>
dschulze@274 775
dschulze@274 776 <p>See the section <a href="#layering">“Layering multiple mask
dschulze@277 777 images”</a> for how 'mask-clip' interacts with other
dschulze@274 778 comma-separated mask properties to form each mask image
dschulze@274 779 layer.
dschulze@274 780
dschulze@292 781 <h3 id="the-mask-origin">The 'mask-origin' property</h3>
dschulze@275 782
dschulze@275 783 <table class="propdef">
dschulze@275 784 <tr>
dschulze@275 785 <th>Name:
dschulze@275 786 <td><dfn>mask-origin</dfn>
dschulze@275 787 <tr>
dschulze@275 788 <th><a href="#values">Value</a>:
dschulze@280 789 <td><var>&lt;box&gt;</var>#
dschulze@275 790 <tr>
dschulze@275 791 <th>Initial:
dschulze@275 792 <td>padding-box
dschulze@275 793 <tr>
dschulze@275 794 <th>Applies to:
dschulze@277 795 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>
dschulze@275 796 <tr>
dschulze@275 797 <th>Inherited:
dschulze@275 798 <td>no
dschulze@275 799 <tr>
dschulze@275 800 <th>Percentages:
dschulze@275 801 <td>N/A
dschulze@275 802 <tr>
dschulze@275 803 <th>Media:
dschulze@275 804 <td>visual
dschulze@275 805 <tr>
dschulze@275 806 <th>Computed value:
dschulze@275 807 <td>as specified
dschulze@275 808 <tr>
dschulze@275 809 <th>Animatable:
dschulze@275 810 <td>no
dschulze@275 811 </table>
dschulze@275 812
dschulze@275 813 <p>For elements rendered as a single box, specifies the
dschulze@275 814 <dfn id="mask-positioning-area">mask positioning area</dfn>.
dschulze@275 815 For elements rendered as multiple boxes (e.g., inline boxes on several
dschulze@275 816 lines, boxes on several pages) specifies which boxes 'box-decoration-break'
dschulze@275 817 operates on to determine the mask positioning area(s).
dschulze@275 818
dschulze@275 819 <dl>
dschulze@275 820 <dt><dfn title="''padding-box''!!'mask-origin' value">
dschulze@275 821 ''padding-box''</dfn>
dschulze@275 822 <dd>The position is relative to the padding box. (For single boxes
dschulze@275 823 ''0 0'' is the upper left corner of the padding edge,
dschulze@275 824 ''100% 100%'' is the lower right corner.)
dschulze@275 825 <dt><dfn title="''border-box''!!'mask-origin' value">
dschulze@275 826 ''border-box''</dfn>
dschulze@432 827 <dd>The position is relative to the border box respectively <span>painting box</span> for objects without associated layout box.
dschulze@275 828 <dt><dfn>''content-box''</dfn>
dschulze@432 829 <dd>The position is relative to the content box respectively object bounding box [[!SVG11]] for objects without associated layout box.
dschulze@275 830 </dl>
dschulze@275 831
dschulze@432 832 <p class="note">Note that there is no corresponding box for
dschulze@432 833 ''padding-box'' on objects without associated layout box
dschulze@432 834 and ''content-box'' is choosen instead.</p>
dschulze@432 835
dschulze@275 836 <p class="note">Note that if 'mask-clip' is ''padding-box'',
dschulze@275 837 'mask-origin' is ''border-box'', 'mask-position' is
dschulze@275 838 ''top left'' (the initial value), and the element has a
dschulze@275 839 non-zero border, then the top and left of the mask image will be
dschulze@275 840 clipped.
dschulze@275 841
dschulze@275 842 <p>See the section <a href="#layering">“Layering multiple mask
dschulze@277 843 images”</a> for how 'mask-origin' interacts with other
dschulze@277 844 comma-separated mask properties to form each mask image
dschulze@277 845 layer.
dschulze@277 846
dschulze@292 847 <h3 id="the-mask-size">The 'mask-size' property</h3>
dschulze@277 848
dschulze@277 849 <table class="propdef">
dschulze@277 850 <tr>
dschulze@277 851 <th>Name:
dschulze@277 852 <td><dfn>mask-size</dfn>
dschulze@277 853 <tr>
dschulze@277 854 <th><a href="#values">Value</a>:
dschulze@280 855 <td><var>&lt;mask-size&gt;</var>#
dschulze@277 856 <tr>
dschulze@277 857 <th>Initial:
dschulze@277 858 <td>auto
dschulze@277 859 <tr>
dschulze@277 860 <th>Applies to:
dschulze@277 861 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>
dschulze@277 862 <tr>
dschulze@277 863 <th>Inherited:
dschulze@277 864 <td>no
dschulze@277 865 <tr>
dschulze@277 866 <th>Percentages:
dschulze@277 867 <td>see text
dschulze@277 868 <tr>
dschulze@277 869 <th>Media:
dschulze@277 870 <td>visual
dschulze@277 871 <tr>
dschulze@277 872 <th>Computed value:
dschulze@277 873 <td>as specified, but with lengths made absolute
dschulze@277 874 <tr>
dschulze@277 875 <th>Animatable:
dschulze@731 876 <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>
dschulze@731 877 (<span class="note">This means keyword values are not animatable.</span>)
dschulze@277 878 </table>
dschulze@277 879
dschulze@277 880 <p>Specifies the size of the mask images. Where
dschulze@277 881
dschulze@277 882 <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>
dschulze@277 883
dschulze@746 884 <p>See <a href="http://www.w3.org/TR/css3-background/#the-background-size">Sizing Images: the ‘background-size’ property</a> [[!CSS3BG]] for the definitions of the property values.
dschulze@277 885
dschulze@277 886 <p>See the section <a href="#layering">“Layering multiple mask
dschulze@277 887 images”</a> for how 'mask-size' interacts with other
dschulze@277 888 comma-separated mask properties to form each mask image
dschulze@277 889 layer.
dschulze@277 890
dschulze@292 891 <h3 id="mask-property">The 'mask' property</h3>
dschulze@273 892
dschulze@273 893 <table class="propdef">
dschulze@273 894 <tr>
dschulze@273 895 <th>Name:</th>
dschulze@273 896 <td><dfn id="MaskProperty">mask</dfn></td>
dschulze@273 897 </tr>
dschulze@273 898 <tr>
dschulze@273 899 <th>Value:</th>
dschulze@536 900 <td><var>&lt;mask-layer&gt;</var>#</td>
dschulze@273 901 </tr>
dschulze@273 902 <tr>
dschulze@273 903 <th>Initial:</th>
dschulze@277 904 <td>see individual properties</td>
dschulze@273 905 </tr>
dschulze@273 906 <tr>
dschulze@273 907 <th>Applies to:</th>
dschulze@273 908 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a></td>
dschulze@273 909 </tr>
dschulze@273 910 <tr>
dschulze@273 911 <th>Inherited:</th>
dschulze@273 912 <td>no</td>
dschulze@273 913 </tr>
dschulze@273 914 <tr>
dschulze@273 915 <th>Percentages:</th>
dschulze@277 916 <td>see individual properties</td>
dschulze@273 917 </tr>
dschulze@273 918 <tr>
dschulze@273 919 <th>Media:</th>
dschulze@273 920 <td>visual</td>
dschulze@273 921 </tr>
dschulze@273 922 <tr>
dschulze@273 923 <th>Computed&#160;value:</th>
dschulze@277 924 <td>see individual properties</td>
dschulze@273 925 </tr>
dschulze@273 926 <tr>
birtles@440 927 <th>Animatable:</th>
dschulze@277 928 <td>see individual properties</td>
dschulze@273 929 </tr>
dschulze@273 930 </table>
dschulze@277 931 <p>Where</p>
dschulze@273 932
dschulze@615 933 <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>
dschulze@615 934
dschulze@615 935 <p>
dschulze@615 936 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'.
dschulze@445 937
dschulze@445 938 <p class="note">
dschulze@445 939 Note that the properties 'mask-image', 'mask-repeat', 'mask-position', 'mask-clip', 'mask-origin' and
dschulze@446 940 'mask-size' have no affect on <a>'mask element'</a> elements.
dschulze@445 941 </p>
dschulze@273 942
dschulze@432 943 <h3 id="the-mask-type">The 'mask-type' property</h3>
dschulze@432 944
dschulze@432 945 <table class="propdef">
dschulze@432 946 <tr>
dschulze@432 947 <th>Name:
dschulze@432 948 <td><dfn>mask-type</dfn>
dschulze@432 949 <tr>
dschulze@432 950 <th><a href="#values">Value</a>:
dschulze@551 951 <td>luminance | alpha
dschulze@432 952 <tr>
dschulze@432 953 <th>Initial:
dschulze@432 954 <td>luminance
dschulze@432 955 <tr>
dschulze@432 956 <th>Applies to:
dschulze@451 957 <td><a>'mask element'</a> elements
dschulze@432 958 <tr>
dschulze@432 959 <th>Inherited:
dschulze@432 960 <td>no
dschulze@432 961 <tr>
dschulze@432 962 <th>Percentages:
dschulze@432 963 <td>N/A
dschulze@432 964 <tr>
dschulze@432 965 <th>Media:
dschulze@432 966 <td>visual
dschulze@432 967 <tr>
dschulze@432 968 <th>Computed value:
dschulze@432 969 <td>as specified
dschulze@432 970 <tr>
dschulze@432 971 <th>Animatable:
dschulze@731 972 <td>no
dschulze@432 973 </table>
dschulze@432 974
birtles@435 975 <p>The 'mask-type' property defines whether the content of the
birtles@435 976 <a>'mask element'</a> is treated as as luminance mask or alpha mask, as
birtles@435 977 described in <a href="#MaskValues">Calculating mask values</a>.</p>
dschulze@432 978
dschulze@432 979 <p>Values have the following meanings:
dschulze@432 980
dschulze@432 981 <dl>
birtles@447 982 <dt>''luminance''</dt>
dschulze@432 983 <dd>Indicates that the luminance values of the mask should be used.</dd>
dschulze@432 984
birtles@447 985 <dt>''alpha''</dt>
dschulze@432 986 <dd>Indicates that the alpha values of the mask should be used.</dd>
dschulze@432 987 </dl>
dschulze@432 988
dschulze@445 989 <p>The 'mask-type' property is a presentation attribute for SVG elements.</p>
dschulze@445 990
dschulze@292 991 <h3 id="MaskElement">The <span class="element-name">'mask'</span> element</h3>
dschulze@273 992
dschulze@273 993 <!--elementsummary mask-->
dschulze@273 994
dschulze@273 995 <div class="adef-list">
dschulze@273 996 <p><em>Attribute definitions:</em></p>
dschulze@273 997 <dl>
dschulze@273 998 <dt id="MaskElementMaskUnitsAttribute"><span
dschulze@273 999 class="adef">maskUnits</span> = "<em>userSpaceOnUse</em> |
dschulze@273 1000 <em>objectBoundingBox</em>"</dt>
dschulze@273 1001 <dd>Defines the coordinate system for attributes
dschulze@273 1002 <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>.<br />
dschulze@273 1003 If <span
dschulze@273 1004 class="attr-value">maskUnits="userSpaceOnUse"</span>,
dschulze@273 1005 <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>
dschulze@273 1006 represent values in the current user coordinate system in place at
dschulze@273 1007 the time when the <a>'mask element'</a>
dschulze@273 1008 element is referenced (i.e., the user coordinate system for
dschulze@273 1009 the element referencing the <a>'mask element'</a> element via the
dschulze@273 1010 'mask' property).<br />
dschulze@273 1011 If <span
dschulze@273 1012 class="attr-value">maskUnits="objectBoundingBox"</span>,
dschulze@273 1013 <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>
dschulze@273 1014 represent fractions or percentages of the bounding box of
dschulze@273 1015 the element to which the mask is applied. (See <span class="term">object bounding box
dschulze@273 1016 units</span>.)<br />
dschulze@273 1017 If attribute <a>'mask/maskUnits'</a> is
dschulze@273 1018 not specified, then the effect is as if a value of <span
dschulze@273 1019 class="attr-value">'objectBoundingBox'</span> were
dschulze@273 1020 specified.<br />
dschulze@343 1021 <span class="anim-target">Animatable:
dschulze@273 1022 yes.</span></dd>
dschulze@273 1023 <dt id="MaskElementMaskContentUnitsAttribute"><span
dschulze@273 1024 class="adef">maskContentUnits</span> =
dschulze@273 1025 "<em>userSpaceOnUse</em> | <em>objectBoundingBox</em>"</dt>
dschulze@273 1026 <dd>Defines the coordinate system for the contents of the
dschulze@273 1027 <a>'mask element'</a>.<br />
dschulze@273 1028 If <span
dschulze@273 1029 class="attr-value">maskContentUnits="userSpaceOnUse"</span>,
dschulze@273 1030 the user coordinate system for the contents of the
dschulze@273 1031 <a>'mask element'</a> element is the current
dschulze@273 1032 user coordinate system in place at the time when the
dschulze@273 1033 <a>'mask element'</a> element is referenced
dschulze@273 1034 (i.e., the user coordinate system for the element
dschulze@273 1035 referencing the <a>'mask element'</a>
dschulze@273 1036 element via the 'mask'
dschulze@273 1037 property).<br />
dschulze@273 1038 If <span
dschulze@273 1039 class="attr-value">maskContentUnits="objectBoundingBox"</span>,
dschulze@273 1040 the user coordinate system for the contents of the <a>'mask element'</a> is established using the
dschulze@273 1041 bounding box of the element to which the mask is applied.
dschulze@273 1042 (See <span class="term">object bounding box
dschulze@273 1043 units</span>.)<br />
dschulze@273 1044 If attribute <a>'maskContentUnits'</a> is not specified,
dschulze@273 1045 then the effect is as if a value of <span
dschulze@273 1046 class="attr-value">'userSpaceOnUse'</span> were
dschulze@273 1047 specified.<br />
dschulze@343 1048 <span class="anim-target">Animatable:
dschulze@273 1049 yes.</span></dd>
dschulze@273 1050 <dt id="MaskElementXAttribute"><span
dschulze@343 1051 class="adef">x</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>
dschulze@273 1052 <dd>The x-axis coordinate of one corner of the rectangle
dschulze@724 1053 for the largest possible offscreen buffer.
dschulze@726 1054 If the attribute is not specified but at least one of the attributes <a>'mask/y'</a>,
dschulze@726 1055 <a>'mask/width'</a> or <a>'mask/height'</a> are specified, the effect is as if a
dschulze@273 1056 value of <span class='attr-value'>'-10%'</span> were specified.<br />
dschulze@343 1057 <span class="anim-target">Animatable:
dschulze@273 1058 yes.</span></dd>
dschulze@273 1059 <dt id="MaskElementYAttribute"><span
dschulze@343 1060 class="adef">y</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>
dschulze@273 1061 <dd>The y-axis coordinate of one corner of the rectangle
dschulze@273 1062 for the largest possible offscreen buffer.<br />
dschulze@726 1063 If the attribute is not specified but at least one of the attributes <a>'mask/x'</a>,
dschulze@726 1064 <a>'mask/width'</a> or <a>'mask/height'</a> are specified, the effect is as if a
dschulze@273 1065 value of <span class='attr-value'>'-10%'</span> were specified.<br />
dschulze@726 1066 <span class="anim-target">Animatable:
dschulze@273 1067 yes.</span></dd>
dschulze@273 1068 <dt id="MaskElementWidthAttribute"><span
dschulze@343 1069 class="adef">width</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>
dschulze@273 1070 <dd>The width of the largest possible offscreen buffer.
dschulze@279 1071 A negative value or a value of zero disables rendering of the element.<br />
dschulze@726 1072 If the attribute is not specified but at least one of the attributes <a>'mask/x'</a>,
dschulze@726 1073 <a>'mask/y'</a> or <a>'mask/height'</a> are specified, the effect is as if a
dschulze@273 1074 value of <span class='attr-value'>'120%'</span> were specified.<br />
dschulze@343 1075 <span class="anim-target">Animatable:
dschulze@273 1076 yes.</span></dd>
dschulze@273 1077 <dt id="MaskElementHeightAttribute"><span
dschulze@343 1078 class="adef">height</span> = "<var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var>"</dt>
dschulze@273 1079 <dd>The height of the largest possible offscreen
dschulze@273 1080 buffer.<br />
dschulze@726 1081 A negative value or a value of zero disables rendering of the element.<br />
dschulze@726 1082 If the attribute is not specified but at least one of the attributes <a>'mask/x'</a>,
dschulze@726 1083 <a>'mask/y'</a> or <a>'mask/width'</a> are specified, the effect is as if a
dschulze@273 1084 value of <span class='attr-value'>'120%'</span> were specified.<br />
dschulze@343 1085 <span class="anim-target">Animatable:
dschulze@273 1086 yes.</span></dd>
dschulze@273 1087 </dl>
dschulze@273 1088 </div>
dschulze@734 1089 <p>If at least one of the attributes <a>'mask/x'</a>,
dschulze@726 1090 <a>'mask/y'</a>, <a>'mask/width'</a> or <a>'mask/height'</a> are specified,
dschulze@726 1091 the given object and the rectangle defined by
dschulze@726 1092 <a>'mask/x'</a>, <a>'mask/y'</a>, <a>'mask/width'</a> and <a>'mask/height'</a>
dschulze@727 1093 establish a current clipping path. The rendered content of the mask must be clipped
dschulze@726 1094 by this current clipping path.<p/>
dschulze@273 1095
dschulze@343 1096 <p>CSS properties inherit into the
dschulze@273 1097 <a>'mask element'</a> element from its ancestors; properties do <em>not</em>
dschulze@273 1098 inherit from the element referencing the <a>'mask element'</a> element.</p>
dschulze@273 1099
dschulze@273 1100 <p><a>'mask element'</a> elements are never rendered directly; their only
dschulze@273 1101 usage is as something that can be referenced using the 'mask'
dschulze@273 1102 property. The 'opacity', 'filter' and 'display' properties do not apply to the
dschulze@273 1103 <a>'mask element'</a> element; thus, <a>'mask element'</a> elements are not
dschulze@273 1104 directly rendered even if the 'display' property is set to a value
dschulze@273 1105 other than 'none', and <a>'mask element'</a>
dschulze@273 1106 elements are available for referencing even when the 'display' property
dschulze@273 1107 on the <a>'mask element'</a> element or any of its ancestors is set to
dschulze@273 1108 <span class="prop-value">none</span>.</p>
dschulze@273 1109
dschulze@292 1110 <h2>Mask Box Image</h2>
dschulze@292 1111
dschulze@342 1112 <p>
birtles@466 1113 With 'mask-box-image' a mask can be split into nine pieces: four corners, four
birtles@466 1114 edges and the middle piece as demonstrated in the figure below.
dschulze@342 1115 </p>
dschulze@342 1116
dschulze@342 1117 <div class=figure>
dschulze@342 1118 <img src="images/mask-box-image-mask.svg" alt="pieces of a mask box image" width="240">
dschulze@342 1119 <p class=caption>
dschulze@342 1120 Pieces of a mask box image.
dschulze@342 1121 </p>
dschulze@342 1122 </div>
dschulze@342 1123
dschulze@342 1124 <p>
dschulze@659 1125 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]].
dschulze@342 1126 </p>
dschulze@299 1127
dschulze@313 1128 <div class=example>
dschulze@342 1129 <p>
birtles@436 1130 The mask image in the following example is split into four corners with
birtles@436 1131 dimensions of 75 pixels, four edges and the middle piece that is stretched
birtles@436 1132 and scaled.
dschulze@342 1133 </p>
dschulze@342 1134
dschulze@313 1135 <div class=figure>
dschulze@313 1136 <img src="images/mask-box-image.svg" alt="Example for 'mask-box-image'" width="720" height="240">
dschulze@342 1137 <p class=caption>
dschulze@453 1138 Example for 'mask-box-image'. The object on the left is the object to mask. The second image is the alpha mask and
dschulze@453 1139 the last image the masked object.
dschulze@342 1140 </p>
dschulze@313 1141 </div>
dschulze@342 1142
dschulze@313 1143 <pre>
dschulze@342 1144 div {
dschulze@342 1145 background: linear-gradient(bottom, #F27BAA 0%, #FCC8AD 100%);
dschulze@342 1146 mask-box-image-slice: 25 fill;
dschulze@342 1147 mask-box-image-repeat: stretch;
dschulze@342 1148 mask-box-image-source: url(mask.png);
dschulze@313 1149 }</pre>
dschulze@313 1150 </div>
dschulze@313 1151
dschulze@299 1152 <h3 id="the-mask-box-image-source">The 'mask-box-image-source' property</h3>
dschulze@299 1153
dschulze@299 1154 <table class=propdef>
dschulze@299 1155 <tr>
dschulze@299 1156 <th>Name:
dschulze@299 1157 <td><dfn>mask-box-image-source</dfn>
dschulze@299 1158 <tr>
dschulze@299 1159 <th><a href="#values">Value</a>:
dschulze@299 1160 <td><var>&lt;mask-image&gt;</var>
dschulze@299 1161 <tr>
dschulze@299 1162 <th>Initial:
dschulze@299 1163 <td>none
dschulze@299 1164 <tr>
dschulze@299 1165 <th>Applies to:
dschulze@299 1166 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.
dschulze@299 1167 <tr>
dschulze@299 1168 <th>Inherited:
dschulze@299 1169 <td>no
dschulze@299 1170 <tr>
dschulze@299 1171 <th>Percentages:
dschulze@299 1172 <td>N/A
dschulze@299 1173 <tr>
dschulze@299 1174 <th>Media:
dschulze@299 1175 <td>visual
dschulze@299 1176 <tr>
dschulze@299 1177 <th>Computed value:
dschulze@299 1178 <td>''none'' or the image with its URI made absolute
dschulze@299 1179 <tr>
dschulze@299 1180 <th>Animatable:
dschulze@299 1181 <td>no
dschulze@299 1182 </table>
dschulze@299 1183
dschulze@301 1184 <p>Specifies an image to be used as mask. If the value is ''none'' or if the image cannot be displayed
dschulze@301 1185 (or the property doesn't apply), the content won't get masked.
dschulze@301 1186
dschulze@299 1187 <h3 id="the-mask-box-image-slice">The 'mask-box-image-slice' property</h3>
dschulze@299 1188
dschulze@299 1189 <table class=propdef>
dschulze@299 1190 <tr>
dschulze@299 1191 <th>Name:
dschulze@299 1192 <td><dfn>mask-box-image-slice</dfn>
dschulze@299 1193 <tr>
dschulze@299 1194 <th><a href="#values">Value</a>:
dschulze@299 1195 <td>[<var>&lt;number&gt;</var> | <var>&lt;percentage&gt;</var>]{1,4} &amp;&amp; fill?
dschulze@299 1196 <tr>
dschulze@299 1197 <th>Initial:
dschulze@301 1198 <td>0 fill
dschulze@299 1199 <tr>
dschulze@299 1200 <th>Applies to:
dschulze@299 1201 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.
dschulze@299 1202 <tr>
dschulze@299 1203 <th>Inherited:
dschulze@299 1204 <td>no
dschulze@299 1205 <tr>
dschulze@299 1206 <th>Percentages:
dschulze@451 1207 <td>refer to size of the mask image
dschulze@299 1208 <tr>
dschulze@299 1209 <th>Media:
dschulze@299 1210 <td>visual
dschulze@299 1211 <tr>
dschulze@299 1212 <th>Computed value:
dschulze@299 1213 <td>as specified
dschulze@299 1214 <tr>
dschulze@299 1215 <th>Animatable:
dschulze@299 1216 <td>no
dschulze@299 1217 </table>
dschulze@299 1218
dschulze@301 1219 <p>This property specifies inward offsets from the top, right, bottom,
dschulze@301 1220 and left edges of the mask image, dividing it into nine regions: four corners,
dschulze@301 1221 four edges and a middle.
dschulze@301 1222 The middle image part is discarded (treated as fully transparent black)
dschulze@301 1223 unless the ''fill'' keyword is present.
dschulze@301 1224
dschulze@746 1225 <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 definitions of the property values.
dschulze@301 1226
dschulze@299 1227 <h3 id="the-mask-box-image-width">The 'mask-box-image-width' property</h3>
dschulze@299 1228
dschulze@299 1229 <table class=propdef>
dschulze@299 1230 <tr>
dschulze@299 1231 <th>Name:
dschulze@299 1232 <td><dfn>mask-box-image-width</dfn>
dschulze@299 1233 <tr>
dschulze@299 1234 <th><a href="#values">Value</a>:
dschulze@299 1235 <td>[ <var>&lt;length&gt;</var> | <var>&lt;percentage&gt;</var> | <var>&lt;number&gt;</var> | auto ]{1,4}
dschulze@299 1236 <tr>
dschulze@299 1237 <th>Initial:
dschulze@301 1238 <td>auto
dschulze@299 1239 <tr>
dschulze@299 1240 <th>Applies to:
dschulze@299 1241 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.
dschulze@299 1242 <tr>
dschulze@299 1243 <th>Inherited:
dschulze@299 1244 <td>no
dschulze@299 1245 <tr>
dschulze@299 1246 <th>Percentages:
dschulze@451 1247 <td>relative to width/height of the <em>mask box image area</em>
dschulze@299 1248 <tr>
dschulze@299 1249 <th>Media:
dschulze@299 1250 <td>visual
dschulze@299 1251 <tr>
dschulze@299 1252 <th>Computed value:
dschulze@299 1253 <td>all <var>&lt;length&gt;</var>s made absolute, otherwise as specified
dschulze@299 1254 <tr>
dschulze@299 1255 <th>Animatable:
dschulze@299 1256 <td>no
dschulze@299 1257 </table>
dschulze@299 1258
dschulze@301 1259 <p>The mask image is drawn inside an area called the
dschulze@301 1260 <em>mask box image area</em>. This is an area whose boundaries
dschulze@301 1261 by default correspond to the mask box, see 'mask-box-image-outset'.
dschulze@301 1262
dschulze@746 1263 <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 definitions of the property values.
dschulze@301 1264
birtles@466 1265 <p class=note>
birtles@466 1266 Note that for SVG elements without an associated layout box the 'border-width'
birtles@466 1267 is considered to be ''0''.
birtles@466 1268 </p>
dschulze@301 1269
dschulze@299 1270 <h3 id="the-mask-box-image-outset">The 'mask-box-image-outset' property</h3>
dschulze@299 1271
dschulze@299 1272 <table class=propdef>
dschulze@299 1273 <tr>
dschulze@299 1274 <th>Name:
dschulze@299 1275 <td><dfn>mask-box-image-outset</dfn>
dschulze@299 1276 <tr>
dschulze@299 1277 <th><a href="#values">Value</a>:
dschulze@299 1278 <td>[ <var>&lt;length&gt;</var> | <var>&lt;number&gt;</var> ]{1,4}
dschulze@299 1279 <tr>
dschulze@299 1280 <th>Initial:
dschulze@299 1281 <td>0
dschulze@299 1282 <tr>
dschulze@299 1283 <th>Applies to:
dschulze@299 1284 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.
dschulze@299 1285 <tr>
dschulze@299 1286 <th>Inherited:
dschulze@299 1287 <td>no
dschulze@299 1288 <tr>
dschulze@299 1289 <th>Percentages:
dschulze@299 1290 <td>N/A
dschulze@299 1291 <tr>
dschulze@299 1292 <th>Media:
dschulze@299 1293 <td>visual
dschulze@299 1294 <tr>
dschulze@299 1295 <th>Computed value:
dschulze@299 1296 <td>all <var>&lt;length&gt;</var>s made absolute, otherwise as specified
dschulze@299 1297 <tr>
dschulze@299 1298 <th>Animatable:
dschulze@299 1299 <td>no
dschulze@299 1300 </table>
dschulze@299 1301
dschulze@301 1302 <p>The values specify the amount by which the <dfn>mask box image
dschulze@301 1303 area</dfn> extends beyond the border box.
dschulze@301 1304 If it has four values, they set the outsets on the top, right, bottom and
dschulze@301 1305 left sides in that order. If the left is missing, it is the same as the right;
dschulze@301 1306 if the bottom is missing, it is the same as the top; if the right is missing,
dschulze@301 1307 it is the same as the top.
dschulze@301 1308
dschulze@301 1309 <p>As with 'mask-box-image-width', a &lt;number&gt; represents a multiple of the
dschulze@343 1310 corresponding 'border-width'.
dschulze@301 1311 Negative values are not allowed for any of the 'mask-box-image-outset' values.
dschulze@301 1312
dschulze@453 1313 <p class=note>Note that for SVG elements without associated layout box the 'border-width' is considered to be ''0''.</p>
dschulze@301 1314
dschulze@299 1315 <h3 id="the-mask-box-image-repeat">The 'mask-box-image-repeat' property</h3>
dschulze@299 1316
dschulze@299 1317 <table class=propdef>
dschulze@299 1318 <tr>
dschulze@299 1319 <th>Name:
dschulze@299 1320 <td><dfn>mask-box-image-repeat</dfn>
dschulze@299 1321 <tr>
dschulze@299 1322 <th><a href="#values">Value</a>:
dschulze@299 1323 <td>[ stretch | repeat | round | space ]{1,2}
dschulze@299 1324 <tr>
dschulze@299 1325 <th>Initial:
dschulze@299 1326 <td>stretch
dschulze@299 1327 <tr>
dschulze@299 1328 <th>Applies to:
dschulze@299 1329 <td>All elements. In SVG, it applies to <a>container elements</a> and <a>graphics elements</a>.
dschulze@299 1330 <tr>
dschulze@299 1331 <th>Inherited:
dschulze@299 1332 <td>no
dschulze@299 1333 <tr>
dschulze@299 1334 <th>Percentages:
dschulze@299 1335 <td>N/A
dschulze@299 1336 <tr>
dschulze@299 1337 <th>Media:
dschulze@299 1338 <td>visual
dschulze@299 1339 <tr>
dschulze@299 1340 <th>Computed value:
dschulze@299 1341 <td>as specified
dschulze@299 1342 <tr>
dschulze@299 1343 <th>Animatable:
dschulze@299 1344 <td>no
dschulze@299 1345 </table>
dschulze@299 1346
dschulze@301 1347 <p>This property specifies how the images for the sides and the middle
dschulze@301 1348 part of the mask image are scaled and tiled. The first keyword applies
dschulze@301 1349 to the horizontal sides, the second to the vertical ones.
dschulze@301 1350 If the second keyword is absent, it is assumed to be the same as the first.
dschulze@301 1351
dschulze@746 1352 <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 definitions of the property values.
dschulze@659 1353
dschulze@659 1354 <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>.
dschulze@301 1355
dschulze@299 1356 <h3 id="the-mask-box-image">The 'mask-box-image' property</h3>
dschulze@299 1357
dschulze@299 1358 <table class=propdef>
dschulze@299 1359 <tr>
dschulze@299 1360 <th>Name:
dschulze@299 1361 <td><dfn>mask-box-image</dfn>
dschulze@299 1362 <tr>
dschulze@299 1363 <th><a href="#values">Value</a>:
dschulze@299 1364 <td> <var>&lt;'mask-box-image-source'&gt;</var>
dschulze@299 1365 || <var>&lt;'mask-box-image-slice'&gt;</var>
dschulze@299 1366 [ / <var>&lt;'mask-box-image-width'&gt;</var> |
dschulze@299 1367 / <var>&lt;'mask-box-image-width'&gt;</var>? / <var>&lt;'mask-box-image-outset'&gt;</var> ]?
dschulze@299 1368 || <var>&lt;'mask-box-image-repeat'&gt;</var>
dschulze@299 1369 <tr>
dschulze@299 1370 <th>Initial:
dschulze@299 1371 <td>See individual properties
dschulze@299 1372 <tr>
dschulze@299 1373 <th>Applies to:
dschulze@299 1374 <td>See individual properties
dschulze@299 1375 <tr>
dschulze@299 1376 <th>Inherited:
dschulze@299 1377 <td>no
dschulze@299 1378 <tr>
dschulze@299 1379 <th>Percentages:
dschulze@299 1380 <td>N/A
dschulze@299 1381 <tr>
dschulze@299 1382 <th>Media:
dschulze@299 1383 <td>visual
dschulze@299 1384 <tr>
dschulze@299 1385 <th>Computed value:
dschulze@299 1386 <td>See individual properties
dschulze@299 1387 <tr>
dschulze@299 1388 <th>Animatable:
dschulze@299 1389 <td>See individual properties
dschulze@299 1390 </table>
dschulze@292 1391
dschulze@301 1392 <p>This is a shorthand property for setting 'mask-box-image-source',
dschulze@301 1393 'mask-box-image-slice', 'mask-box-image-width', 'mask-box-image-outset' and
dschulze@301 1394 'mask-box-image-repeat'. Omitted values are set to their initial values.
dschulze@301 1395
dschulze@453 1396 <h3 id="masking-with-the-mask-box-image">Masking with the mask-box-image</h3>
dschulze@453 1397
dschulze@453 1398 <p>
dschulze@453 1399 After the mask-box-image given by 'mask-box-image-source' is sliced by
dschulze@453 1400 the 'mask-box-image-slice' values, the resulting nine images are scaled,
dschulze@453 1401 positioned, and tiled into their corresponding mask image regions
dschulze@659 1402 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]].
dschulze@453 1403
dschulze@301 1404
dschulze@298 1405 <h2>Clipping paths</h2>
dschulze@273 1406
dschulze@453 1407 <p>
birtles@466 1408 The clipping path restricts the region to which paint can be applied, the
birtles@466 1409 so-called clipping region.
birtles@466 1410 Conceptually, any parts of the drawing that lie outside of this region are not
birtles@466 1411 drawn.
birtles@466 1412 This includes any content, background, borders, text decoration, outline and
birtles@466 1413 visible scrolling mechanism of the element to which the clipping path is
birtles@466 1414 applied, and those of its descendants.
dschulze@460 1415 </p>
dschulze@460 1416
dschulze@460 1417 <p>
birtles@466 1418 An element's ancestors may also clip portions of their content (e.g., via
birtles@466 1419 their own 'clip' or 'clip-path' properties and/or if their 'overflow' property
birtles@466 1420 is not ''visible'').
birtles@466 1421 What is rendered is the cumulative intersection.
dschulze@460 1422 </p>
dschulze@460 1423
dschulze@460 1424 <p>
dschulze@460 1425 If the clipping region exceeds the bounds of the UA's document window, content may be clipped to that window by the
dschulze@460 1426 native operating environment.
dschulze@453 1427 </p>
dschulze@273 1428
dschulze@298 1429 <h3 id="the-clip-path">The 'clip-path' property</h3>
dschulze@298 1430 <table class="propdef">
dschulze@298 1431 <tr>
dschulze@298 1432 <th>Name:</th>
dschulze@298 1433 <td><dfn>clip-path</dfn></td>
dschulze@298 1434 </tr>
dschulze@298 1435 <tr>
dschulze@298 1436 <th>Value:</th>
dschulze@338 1437 <td><var>&lt;shape&gt;</var> | <var>&lt;clip-source&gt;</var> | none</td>
dschulze@298 1438 </tr>
dschulze@298 1439 <tr>
dschulze@298 1440 <th>Initial:</th>
dschulze@298 1441 <td>none</td>
dschulze@298 1442 </tr>
dschulze@298 1443 <tr>
dschulze@298 1444 <th>Applies to:</th>
dschulze@298 1445 <td>All elements. SVG <a>container elements</a>, <a>graphics elements</a>
dschulze@298 1446 and <a>'clipPath'</a></td>
dschulze@298 1447 </tr>
dschulze@298 1448 <tr>
dschulze@298 1449 <th>Inherited:</th>
dschulze@298 1450 <td>no</td>
dschulze@298 1451 </tr>
dschulze@298 1452 <tr>
dschulze@298 1453 <th>Percentages:</th>
dschulze@338 1454 <td>as specified</td>
dschulze@298 1455 </tr>
dschulze@298 1456 <tr>
dschulze@298 1457 <th>Media:</th>
dschulze@298 1458 <td>visual</td>
dschulze@298 1459 </tr>
dschulze@298 1460 <tr>
dschulze@342 1461 <th>Computed value:</th>
dschulze@452 1462 <td>as specified, but with <var>&lt;url&gt;</var> values made absolute</td>
dschulze@298 1463 </tr>
dschulze@298 1464 <tr>
birtles@440 1465 <th>Animatable:</th>
dschulze@731 1466 <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>
dschulze@298 1467 </tr>
dschulze@298 1468 </table>
dschulze@298 1469
dschulze@552 1470 <pre class=prod><dfn>&lt;clip-source&gt;</dfn> = <var>&lt;url&gt;</var> | <var>child</var> | <var>&lt;child-selector&gt;</var>
dschulze@453 1471 </pre>
dschulze@338 1472
dschulze@298 1473 <dl>
dschulze@338 1474 <dt>
dschulze@338 1475 <dfn>'&lt;shape&gt;'</dfn>
dschulze@338 1476 </dt>
dschulze@338 1477 <dd>
dschulze@552 1478 A basic shape function as defined in CSS3 Exclusions. The origin of clipping shapes is on the top left of the <span
dschulze@552 1479 class=index>bounding client rect</span>. Percentage values are resolved against the
dschulze@552 1480 <span class=index>bounding client rect</span> width and height. (See [[!CSS3-EXCLUSIONS]].)
dschulze@338 1481 </dd>
birtles@697 1482 <dt>''child''</dt>
birtles@697 1483 <dd>
dschulze@698 1484 A keyword to indicate that the last direct sibling <a>'clipPath element'</a>
dschulze@698 1485 element of the element the 'clip-path' property is applied should be used as the clip source. It is equivalent to
birtles@697 1486 ''select(clipPath:last-of-type)''.</dd>
birtles@697 1487 <dt>'&lt;child-selector&gt;'</dt>
birtles@697 1488 <dd>
birtles@697 1489 A comma-separated list of <a>compound selector</a>s scoped at the element to
birtles@697 1490 which the 'clip-path' property is applied.
birtles@697 1491 The first matching element in <a>tree order</a> (as defined in [[!DOM]]) as
birtles@697 1492 a result of evaluating the list of selectors is taken as the clip source.
birtles@697 1493 If there are no matching elements the clip source is invalid.
birtles@697 1494 </dd>
dschulze@298 1495 </dl>
dschulze@298 1496
dschulze@298 1497 <h3 id="the-clip-rule">The 'clip-rule' property</h3>
dschulze@298 1498
dschulze@298 1499 <table class="propdef">
dschulze@298 1500 <tr>
dschulze@298 1501 <th>Name:</th>
dschulze@298 1502 <td><dfn>clip-rule</dfn></td>
dschulze@298 1503 </tr>
dschulze@298 1504 <tr>
dschulze@298 1505 <th>Value:</th>
dschulze@298 1506 <td>nonzero | evenodd</td>
dschulze@298 1507 </tr>
dschulze@298 1508 <tr>
dschulze@298 1509 <th>Initial:</th>
dschulze@298 1510 <td>nonzero</td>
dschulze@298 1511 </tr>
dschulze@298 1512 <tr>
dschulze@298 1513 <th>Applies to:</th>
dschulze@298 1514 <td><a>graphics elements</a> within a <a>'clipPath'</a> element</td>
dschulze@298 1515 </tr>
dschulze@298 1516 <tr>
dschulze@298 1517 <th>Inherited:</th>
dschulze@298 1518 <td>yes</td>
dschulze@298 1519 </tr>
dschulze@298 1520 <tr>
dschulze@298 1521 <th>Percentages:</th>
dschulze@298 1522 <td>N/A</td>
dschulze@298 1523 </tr>
dschulze@298 1524 <tr>
dschulze@298 1525 <th>Media:</th>
dschulze@298 1526 <td>visual</td>
dschulze@298 1527 </tr>
dschulze@298 1528 <tr>
dschulze@298 1529 <th>Computed&#160;value:</th>
dschulze@298 1530 <td>as specified</td>
dschulze@298 1531 </tr>
dschulze@298 1532 <tr>
birtles@440 1533 <th>Animatable:</th>
dschulze@731 1534 <td>no</td>
dschulze@298 1535 </tr>
dschulze@298 1536 </table>
dschulze@298 1537
dschulze@298 1538 <dl>
dschulze@298 1539 <dt><dfn>''nonzero''</dfn></dt>
dschulze@465 1540 <dd>See description of <a>'fill-rule'</a> property [[SVG11]].</dd>
dschulze@298 1541
dschulze@298 1542 <dt><dfn>''evenodd''</dfn></dt>
dschulze@465 1543 <dd>See description of <a>'fill-rule'</a> property [[SVG11]].</dd>
dschulze@298 1544 </dl>
dschulze@298 1545
dschulze@298 1546 <p>The 'clip-rule' property only applies to graphics elements that are
dschulze@298 1547 contained within a <a>'clipPath'</a> element.
dschulze@298 1548
dschulze@298 1549 <div class=example>
dschulze@298 1550 The following fragment of code
dschulze@298 1551 will cause an evenodd clipping rule to be applied to the clipping path because
dschulze@298 1552 'clip-rule' is specified on the <a>'path'</a> element that defines the
dschulze@298 1553 clipping shape:</p>
dschulze@298 1554
dschulze@298 1555 <pre>
dschulze@298 1556 &lt;g clip-rule="nonzero"&gt;
dschulze@298 1557 &lt;clipPath id="MyClip"&gt;
dschulze@298 1558 &lt;path d="..." clip-rule="evenodd" /&gt;
dschulze@298 1559 &lt;/clipPath&gt;
dschulze@298 1560 &lt;rect clip-path="url(#MyClip)" ... /&gt;
dschulze@298 1561 &lt;/g&gt;
dschulze@298 1562 </pre>
dschulze@298 1563
dschulze@298 1564 <p>whereas the following fragment of code will <em>not</em> cause an
dschulze@298 1565 evenodd clipping rule to be applied because the 'clip-rule' is
dschulze@298 1566 specified on the referencing element, not on the object defining the
dschulze@298 1567 clipping shape:</p>
dschulze@298 1568
dschulze@298 1569 <pre>
dschulze@298 1570 &lt;g clip-rule="nonzero"&gt;
dschulze@298 1571 &lt;clipPath id="MyClip"&gt;
dschulze@298 1572 &lt;path d="..." /&gt;
dschulze@298 1573 &lt;/clipPath&gt;
dschulze@298 1574 &lt;rect clip-path="url(#MyClip)" clip-rule="evenodd" ... /&gt;
dschulze@298 1575 &lt;/g&gt;
dschulze@298 1576 </pre>
dschulze@298 1577 </div>
dschulze@298 1578
dschulze@451 1579 <h3 id="clip-property">The 'clip' property</h3>
dschulze@451 1580
dschulze@451 1581 <table class="propdef">
dschulze@451 1582 <tr>
dschulze@451 1583 <th>Name:</th>
dschulze@451 1584 <td><dfn id="ClipProperty">clip</dfn></td>
dschulze@451 1585 </tr>
dschulze@451 1586 <tr>
dschulze@451 1587 <th>Value:</th>
dschulze@451 1588 <td><var>&lt;shape&gt;</var> | auto</td>
dschulze@451 1589 </tr>
dschulze@451 1590 <tr>
dschulze@451 1591 <th>Initial:</th>
dschulze@451 1592 <td>see individual properties</td>
dschulze@451 1593 </tr>
dschulze@451 1594 <tr>
dschulze@451 1595 <th>Applies to:</th>
dschulze@451 1596 <td>Absolutely positioned elements. In SVG, it applies to <a
dschulze@451 1597 href="http://www.w3.org/TR/SVG2/coords.html#EstablishingANewViewport">elements which
dschulze@451 1598 establish a new viewport</a>, <a>'pattern element'</a> elements and <a>'marker element'</a> elements.</td>
dschulze@451 1599 </tr>
dschulze@451 1600 <tr>
dschulze@451 1601 <th>Inherited:</th>
dschulze@451 1602 <td>no</td>
dschulze@451 1603 </tr>
dschulze@451 1604 <tr>
dschulze@451 1605 <th>Percentages:</th>
dschulze@451 1606 <td>N/A</td>
dschulze@451 1607 </tr>
dschulze@451 1608 <tr>
dschulze@451 1609 <th>Media:</th>
dschulze@451 1610 <td>visual</td>
dschulze@451 1611 </tr>
dschulze@451 1612 <tr>
dschulze@451 1613 <th>Computed&#160;value:</th>
dschulze@451 1614 <td>as specified</td>
dschulze@451 1615 </tr>
dschulze@451 1616 <tr>
dschulze@451 1617 <th>Animatable:</th>
dschulze@731 1618 <td>as <a href="http://dev.w3.org/csswg/css3-transitions/#animtype-rect">rectangle</a></td>
dschulze@451 1619 </tr>
dschulze@451 1620 </table>
dschulze@451 1621
dschulze@474 1622 <p class=note>With this specification the 'clip' property is deprecated. Authors are encouraged to use the 'clip-path' property instead.
dschulze@474 1623 UAs must support the 'clip' property.
dschulze@474 1624 </p>
dschulze@474 1625
dschulze@451 1626 <p>
dschulze@451 1627 The 'clip' property applies only to absolutely positioned elements. In SVG, it applies to
dschulze@451 1628 <a href="http://www.w3.org/TR/SVG2/coords.html#EstablishingANewViewport">elements which establish a new viewport</a>,
dschulze@451 1629 <a>'pattern element'</a> elements and <a>'marker element'</a> elements</td>. Values have the following meanings:
dschulze@451 1630 </p>
dschulze@451 1631
dschulze@451 1632 <dl>
dschulze@451 1633 <dt>''auto''</dt>
dschulze@451 1634 <dd>The element does not clip.</dd>
dschulze@451 1635 <dt><var>&lt;shape&gt;</var></dt>
dschulze@451 1636 <dd>
dschulze@451 1637 <p>
dschulze@451 1638 In CSS 2.1, the only valid &lt;shape&gt; value is: rect(<var>&lt;top&gt;</var>, <var>&lt;right&gt;</var>,
dschulze@451 1639 <var>&lt;bottom&gt;</var>, <var>&lt;left&gt;</var>) where <var>&lt;top&gt;</var> and <var>&lt;bottom&gt;</var>
dschulze@451 1640 specify offsets from the top border edge of the box, and <var>&lt;right&gt;</var>, and <var>&lt;left&gt;</var>
dschulze@451 1641 specify offsets from the left border edge of the box. Authors should separate offset values with commas. User agents
dschulze@451 1642 must support separation with commas, but may also support separation without commas (but not a combination), because
dschulze@451 1643 a previous revision of this specification was ambiguous in this respect.
dschulze@451 1644 </p>
dschulze@451 1645
dschulze@451 1646 <p><dfn>&lt;top&gt;</dfn>,
dschulze@451 1647 <dfn>&lt;right&gt;</dfn>, <dfn>&lt;bottom&gt;</dfn>, and <dfn>&lt;left&gt;</dfn> may either have a
dschulze@451 1648 <var>&lt;length&gt;</var> value or ''auto''. Negative lengths are permitted. The value ''auto'' means that a given
dschulze@451 1649 edge of the clipping region will be the same as the edge of the element's generated border box (i.e., ''auto'' means
dschulze@451 1650 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
dschulze@451 1651 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
dschulze@451 1652 plus the sum of the horizontal padding and border widths for <var>&lt;right&gt;</var>, such that four 'auto' values result in
dschulze@451 1653 the clipping region being the same as the element's border box).
dschulze@451 1654 </p>
dschulze@451 1655
dschulze@451 1656 <p>
dschulze@451 1657 When coordinates are rounded to pixel coordinates, care should be taken that no pixels remain visible when
dschulze@451 1658 <var>&lt;left&gt;</var> and <var>&lt;right&gt;</var> have the same value (or <var>&lt;top&gt;</var> and
dschulze@451 1659 <var>&lt;bottom&gt;</var> have the same value), and conversely that no pixels within the element's border box
dschulze@451 1660 remain hidden when these values are ''auto''.
dschulze@451 1661 </p>
dschulze@451 1662 </dd>
dschulze@451 1663 </dl>
dschulze@451 1664
dschulze@451 1665 <div class="example">
dschulze@451 1666 <p>
dschulze@451 1667 Example: The following two rules:
dschulze@451 1668 </p>
dschulze@451 1669
dschulze@451 1670 <pre><code>
dschulze@451 1671 p#one { clip: rect(5px, 40px, 45px, 5px); }
dschulze@451 1672 p#two { clip: rect(5px, 55px, 45px, 5px); }</code></pre>
dschulze@451 1673
dschulze@451 1674 <p>
dschulze@451 1675 and assuming both Ps are 50 by 55 pixel, will create, respectively, the rectangular clipping regions delimited by
dschulze@451 1676 the dashed lines in the following illustrations:
dschulze@451 1677 </p>
dschulze@451 1678
dschulze@451 1679 <div class=figure>
dschulze@451 1680 <img src="images/clip.png" width="292" height="577" alt="Values for rect shape">
dschulze@453 1681 <p class=caption>This diagram illustrates two block boxes, one above the other, with rectangular clipping regions of
dschulze@453 1682 different dimensions. (See <a href="http://www.w3.org/TR/CSS2/images/longdesc/clip-desc.html">long description</a>.)
dschulze@451 1683 </div>
dschulze@451 1684 </div>
dschulze@451 1685
dschulze@298 1686 <h3 id="ClipPathElement">The <a>'clipPath element'</a> element</h3>
dschulze@298 1687
dschulze@298 1688 <!--elementsummary clipPath-->
dschulze@298 1689
dschulze@298 1690 <div class="adef-list">
dschulze@298 1691 <p><em>Attribute definitions:</em></p>
dschulze@298 1692 <dl>
dschulze@298 1693 <dt id="ClipPathElementClipPathUnitsAttribute"><span
dschulze@298 1694 class="adef">clipPathUnits</span> =
dschulze@298 1695 "<em>userSpaceOnUse</em> | <em>objectBoundingBox</em>"</dt>
dschulze@298 1696 <dd>Defines the coordinate system for the contents of the
dschulze@298 1697 <a>'clipPath'</a>.<br />
dschulze@298 1698 If <span class="attr-value">clipPathUnits="userSpaceOnUse"</span>,
dschulze@298 1699 the contents of the <a>'clipPath'</a> represent values in
dschulze@298 1700 the current user coordinate system in place at the time
dschulze@298 1701 when the <a>'clipPath'</a>
dschulze@298 1702 element is referenced (i.e., the user coordinate system for
dschulze@298 1703 the element referencing the <a>'clipPath'</a> element via the
dschulze@298 1704 <a>'clip-path'</a> property).<br />
dschulze@298 1705 If <span class="attr-value">clipPathUnits="objectBoundingBox"</span>,
dschulze@298 1706 then the user coordinate system for the contents of the
dschulze@298 1707 <a>'clipPath'</a> element is established using the bounding box of
dschulze@343 1708 the element to which the clipping path is applied (see <span class=index>object bounding box
dschulze@343 1709 units</span>).<br />
dschulze@298 1710 If attribute <a>'clipPathUnits'</a>
dschulze@298 1711 is not specified, then the effect is as if a value of <span
dschulze@298 1712 class="attr-value">'userSpaceOnUse'</span> were
dschulze@298 1713 specified.<br />
dschulze@343 1714 <span class="anim-target">Animatable:
dschulze@298 1715 yes.</span></dd>
dschulze@298 1716 </dl>
dschulze@298 1717 </div>
dschulze@298 1718
dschulze@343 1719 <p>CSS properties inherit into the
dschulze@298 1720 <a>'clipPath'</a> element from its ancestors; properties do <em>not</em>
dschulze@298 1721 inherit from the element referencing the <a>'clipPath'</a> element.</p>
dschulze@298 1722
dschulze@298 1723 <p><a>'clipPath'</a> elements are never rendered directly; their only usage is
dschulze@298 1724 as something that can be referenced using the <a>'clip-path'</a> property. The
dschulze@298 1725 <a>'display'</a> property does not apply to the <a>'clipPath'</a> element;
dschulze@298 1726 thus, <a>'clipPath'</a> elements are not directly rendered even if the
dschulze@298 1727 'display' property is set to a value other than
dschulze@298 1728 <span class="prop-value">none</span>, and <a>'clipPath'</a> elements are
dschulze@298 1729 available for referencing even when the <a>'display'</a> property on the
dschulze@298 1730 <a>'clipPath'</a> element or any of its ancestors is set to
dschulze@298 1731 <span class="prop-value">none</span>.</p>
dschulze@298 1732
dschulze@298 1733 <p>A <a>'clipPath'</a> element can contain <a>'path'</a> elements,
dschulze@298 1734 <a>'text'</a> elements, <a>basic shapes</a> (such as
dschulze@298 1735 <a>'circle'</a>) or a <a>'use'</a> element. If a <a>'use'</a> element is a
dschulze@298 1736 child of a <a>'clipPath'</a> element, it must directly reference
dschulze@451 1737 <a>'path'</a>, <a>'text'</a> or <a>basic shapes</a> elements.
birtles@437 1738 Indirect references are an error and the <a>'clipPath'</a> element must be
birtles@437 1739 ignored.</p>
dschulze@298 1740
dschulze@298 1741 <p>The raw geometry of each child element exclusive of rendering properties
dschulze@298 1742 such as 'fill', 'stroke', 'stroke-width' within a
dschulze@298 1743 <a>'clipPath'</a> conceptually defines a 1-bit mask (with the possible
dschulze@298 1744 exception of anti-aliasing along the edge of the geometry) which represents
dschulze@298 1745 the silhouette of the graphics associated with that element. Anything outside
dschulze@298 1746 the outline of the object is masked out. If a child element is
dschulze@298 1747 made invisible by 'display' or 'visibility' it does not contribute
dschulze@298 1748 to the clipping path. When the <a>'clipPath'</a> element
dschulze@298 1749 contains multiple child elements, the silhouettes of the child elements are
dschulze@298 1750 logically OR'd together to create a single silhouette which is then used to
dschulze@298 1751 restrict the region onto which paint can be applied. Thus, a point is inside
dschulze@298 1752 the clipping path if it is inside any of the children of the
dschulze@298 1753 <a>'clipPath'</a>.</p>
dschulze@298 1754
dschulze@298 1755 <p>For a given graphics element, the actual clipping path used
dschulze@298 1756 will be the intersection of the clipping path specified by its
dschulze@298 1757 'clip-path' property (if any) with any clipping paths on its
dschulze@298 1758 ancestors, as specified by the 'clip-path' property on the
dschulze@343 1759 elements
dschulze@343 1760 which establish a new viewport. (See [[SVG11]])</p>
dschulze@298 1761
dschulze@734 1762 <p>A couple of additions:</p>
dschulze@298 1763
dschulze@298 1764 <ul>
dschulze@298 1765 <li>The <a>'clipPath'</a> element itself and its child elements do
dschulze@298 1766 <em>not</em> inherit clipping paths from the ancestors of the
dschulze@298 1767 <a>'clipPath'</a> element.</li>
dschulze@298 1768
dschulze@298 1769 <li>The <a>'clipPath'</a> element or any of its children can specify
dschulze@298 1770 property 'clip-path'.<br /> If a valid 'clip-path' reference
dschulze@298 1771 is placed on a <a>'clipPath'</a> element, the resulting clipping path is the
dschulze@298 1772 intersection of the contents of the <a>'clipPath'</a> element with the
dschulze@298 1773 referenced clipping path.<br />
dschulze@298 1774 If a valid 'clip-path' reference is placed on one of the children of
dschulze@298 1775 a <a>'clipPath'</a> element, then the given child element is clipped by the
dschulze@298 1776 referenced clipping path before OR'ing the silhouette of the child element
dschulze@298 1777 with the silhouettes of the other child elements.</li>
dschulze@298 1778
dschulze@298 1779 <li>An empty clipping path will completely clip away the element that had the
dschulze@298 1780 'clip-path' property applied.</li>
dschulze@298 1781 </ul>
dschulze@298 1782
dschulze@298 1783 <h3 id="clipPath-geometry">Clipping paths, geometry, and pointer events</h3>
dschulze@298 1784
dschulze@298 1785 <p>A clipping path is conceptually equivalent to a custom viewport for
dschulze@298 1786 the referencing element. Thus, it affects the rendering of an element,
dschulze@298 1787 but not the element's inherent geometry. The <span class=index>bounding client rect</span> of a clipped
dschulze@298 1788 element (that is, an element which references a <a>'clipPath'</a>
dschulze@298 1789 element via a 'clip-path' property, or a child of the
dschulze@298 1790 referencing element) must remain the same as if it were not clipped.</p>
dschulze@298 1791
birtles@466 1792 <p>By default, <a>pointer events</a>
dschulze@298 1793 must not be dispatched on the clipped (non-visible) regions of a shape. For
dschulze@298 1794 example, a circle with a radius of 10 which is clipped to a circle with a radius
dschulze@298 1795 of 5 will not receive <span class="event-name">'click'</span> events outside the
dschulze@298 1796 smaller radius. Later versions of this specification may define new properties to enable
dschulze@298 1797 fine-grained control over the interactions between hit testing and clipping.</p>
dschulze@273 1798
dschulze@473 1799 <h2 id="security">Security</h2>
dschulze@473 1800
dschulze@473 1801 <h3 id="origin-restrictions">Origin Restrictions</h3>
dschulze@473 1802
dschulze@473 1803 <p>
dschulze@473 1804 External references to resources like <a>'mask element'</a> or <a>'clipPath element'</a>
dschulze@473 1805 must not violate the same origin restrictions [[!CORS]].
dschulze@473 1806 </p>
dschulze@473 1807
dschulze@473 1808 <p>This restriction includes:</p>
dschulze@473 1809
dschulze@473 1810 <ul>
dschulze@473 1811 <li>Any images, either as content or via styling, that are not exposed with CORS</li>
dschulze@473 1812 <li>Any tainted canvas</li>
dschulze@473 1813 <li>Any cross-origin content referenced by ''xlink:href'' or &lt;use&gt;</li>
dschulze@473 1814 </ul>
dschulze@473 1815
dschulze@473 1816 <p>
dschulze@473 1817 If content falls under this restriction, the resource must be rejected. The element is
dschulze@473 1818 drawn as if the resource was not specified (i.e. the 'clip-path' or 'mask' property were
dschulze@473 1819 set to ''none'').
dschulze@473 1820 </p>
dschulze@473 1821
dschulze@462 1822 <h2 id="DOMInterfaces">DOM interfaces</h2>
dschulze@462 1823
dschulze@462 1824 <h3 id="InterfaceSVGClipPathElement">Interface SVGClipPathElement</h3>
dschulze@462 1825
dschulze@462 1826 <p>The <a>SVGClipPathElement</a> interface corresponds to the <a>'clipPath'</a> element.</p>
dschulze@462 1827
dschulze@628 1828 <pre class="idl">interface <b>SVGClipPathElement</b> : <a>SVGElement</a> {
birtles@467 1829 readonly attribute <a>SVGAnimatedEnumeration</a> <a href="#SVGClipPathElement__clipPathUnits">clipPathUnits</a>;
dschulze@628 1830 readonly attribute <a>SVGAnimatedTransformList</a> <a href="#SVGClipPathElement__transform">transform</a>;
dschulze@462 1831 };
dschulze@462 1832
dschulze@462 1833 <a>SVGClipPathElement</a> implements <a>SVGUnitTypes</a>;</pre>
dschulze@462 1834
dschulze@462 1835 <dl class="interface">
dschulze@462 1836 <dt class="attributes-header">Attributes:</dt>
dschulze@462 1837 <dd>
dschulze@462 1838 <dl class="attributes">
dschulze@462 1839
birtles@467 1840 <dt id="SVGClipPathElement__clipPathUnits" class="attribute first-child"><b>clipPathUnits</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedEnumeration</a>)</span></dt>
dschulze@462 1841 <dd class="attribute">
dschulze@462 1842 <div>
dschulze@462 1843 Corresponds to attribute <a>'clipPathUnits'</a> on the given
dschulze@462 1844 <a>'clipPath'</a> element. Takes one of the constants defined in
dschulze@462 1845 <a>SVGUnitTypes</a>.
dschulze@628 1846 </div>
dschulze@628 1847 </dd>
dschulze@462 1848
dschulze@628 1849 <dt id="SVGClipPathElement__transform" class="attribute first-child"><b>transform</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedTransformList</a>)</span></dt>
dschulze@628 1850 <dd class="attribute">
dschulze@628 1851 <div>
dschulze@628 1852 Corresponds to attribute <a>'transform'</a> on the given element.
dschulze@462 1853 </div>
dschulze@462 1854 </dd>
dschulze@462 1855 </dl>
dschulze@462 1856 </dd>
dschulze@462 1857 </dl>
dschulze@462 1858
dschulze@462 1859 <h3 id="InterfaceSVGMaskElement">Interface SVGMaskElement</h3>
dschulze@462 1860
dschulze@462 1861 <p>The <a>SVGMaskElement</a> interface corresponds to the <a>'mask element'</a> element.</p>
dschulze@462 1862
dschulze@618 1863 <pre class="idl">interface <b>SVGMaskElement</b> : <a>SVGElement</a> {
birtles@467 1864 readonly attribute <a>SVGAnimatedEnumeration</a> <a href="#SVGMaskElement__maskUnits">maskUnits</a>;
birtles@467 1865 readonly attribute <a>SVGAnimatedEnumeration</a> <a href="#SVGMaskElement__maskContentUnits">maskContentUnits</a>;
birtles@467 1866 readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__x">x</a>;
birtles@467 1867 readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__y">y</a>;
birtles@467 1868 readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__width">width</a>;
birtles@467 1869 readonly attribute <a>SVGAnimatedLength</a> <a href="#SVGMaskElement__height">height</a>;
dschulze@462 1870 };
dschulze@462 1871
dschulze@462 1872 <a>SVGMaskElement</a> implements <a>SVGUnitTypes</a>;</pre>
dschulze@462 1873
dschulze@462 1874 <dl class="interface">
dschulze@462 1875 </dd>
dschulze@462 1876 <dt class="attributes-header">Attributes:</dt>
dschulze@462 1877 <dd>
dschulze@462 1878 <dl class="attributes">
dschulze@462 1879
birtles@467 1880 <dt id="SVGMaskElement__maskUnits" class="attribute first-child"><b>maskUnits</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedEnumeration</a>)</span></dt>
dschulze@462 1881 <dd class="attribute">
dschulze@462 1882 <div>
dschulze@462 1883 Corresponds to attribute <a>'maskUnits'</a> on the given
dschulze@462 1884 <a>'mask element'</a> element. Takes one of the constants defined in
dschulze@462 1885 <a>SVGUnitTypes</a>.
dschulze@462 1886 </div>
dschulze@462 1887 </dd>
dschulze@462 1888
birtles@467 1889 <dt id="SVGMaskElement__maskContentUnits" class="attribute"><b>maskContentUnits</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedEnumeration</a>)</span></dt>
dschulze@462 1890 <dd class="attribute">
dschulze@462 1891 <div>
dschulze@462 1892 Corresponds to attribute <a>'maskContentUnits'</a> on the given
dschulze@462 1893 <a>'mask element'</a> element. Takes one of the constants defined in
dschulze@462 1894 <a>SVGUnitTypes</a>.
dschulze@462 1895
dschulze@462 1896 </div>
dschulze@462 1897 </dd>
dschulze@462 1898
birtles@467 1899 <dt id="SVGMaskElement__x" class="attribute"><b>x</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>
dschulze@462 1900 <dd class="attribute">
dschulze@462 1901 <div>
dschulze@462 1902 Corresponds to attribute <a>'mask/x'</a> on the given <a>'mask element'</a>
dschulze@462 1903 element.
dschulze@462 1904
dschulze@462 1905 </div>
dschulze@462 1906 </dd>
dschulze@462 1907
birtles@467 1908 <dt id="SVGMaskElement__y" class="attribute"><b>y</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>
dschulze@462 1909 <dd class="attribute">
dschulze@462 1910 <div>
dschulze@462 1911 Corresponds to attribute <a>'mask/y'</a> on the given <a>'mask element'</a>
dschulze@462 1912 element.
dschulze@462 1913
dschulze@462 1914 </div>
dschulze@462 1915 </dd>
dschulze@462 1916
birtles@467 1917 <dt id="SVGMaskElement__width" class="attribute"><b>width</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>
dschulze@462 1918 <dd class="attribute">
dschulze@462 1919 <div>
dschulze@462 1920 Corresponds to attribute <a>'mask/width'</a> on the given
dschulze@462 1921 <a>'mask element'</a> element.
dschulze@462 1922
dschulze@462 1923 </div>
dschulze@462 1924 </dd>
dschulze@462 1925
birtles@467 1926 <dt id="SVGMaskElement__height" class="attribute"><b>height</b><span class="idl-type-parenthetical"> (readonly <a>SVGAnimatedLength</a>)</span></dt>
dschulze@462 1927 <dd class="attribute">
dschulze@462 1928 <div>
dschulze@462 1929 Corresponds to attribute <a>'mask/height'</a> on the given
dschulze@462 1930 <a>'mask element'</a> element.
dschulze@462 1931
dschulze@462 1932 </div>
dschulze@462 1933 </dd>
dschulze@462 1934 </dl>
dschulze@462 1935 </dd>
dschulze@462 1936 </dl>
dschulze@462 1937
dschulze@741 1938 <h2>Conformance</h2>
dschulze@734 1939
dschulze@746 1940 <h3 class="no-ref">Conformance to CSS Background and Borders</h3>
dschulze@746 1941
dschulze@746 1942 <p>
dschulze@746 1943 Some property and element definitions in this specification require an SVG 1.1 implementation [[!SVG11]]. UAs without
dschulze@746 1944 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
dschulze@746 1945 support for SVG, the 'mask' and 'clip-path' properties must neither support references to
dschulze@746 1946 <a>'mask element'</a> elements nor to <a>'clipPath element'</a> elements.
dschulze@746 1947 </p>
dschulze@746 1948
dschulze@741 1949 <!--conformance-->
dschulze@734 1950
dschulze@273 1951 <h2 class=no-num id="references">
dschulze@273 1952 References</h2>
dschulze@273 1953
dschulze@273 1954 <h3 class="no-num" id="normative-references">
dschulze@273 1955 Normative references</h3>
dschulze@273 1956 <!--normative-->
dschulze@470 1957 <dl>
dschulze@470 1958 <dt id="ref-svg2"><strong class="normref">[SVG2]</strong></dt>
dschulze@470 1959 <dd>
dschulze@731 1960 Cameron McCormack; et al. <a href="http://www.w3.org/TR/2012/WD-SVG2-20120828/"><cite>Scalable
dschulze@470 1961 Vector Graphics (SVG) 2</cite>.</a> 28 August 2012. W3C Working Draft. (Work in progress.) URL:
dschulze@470 1962 <a href="http://www.w3.org/TR/2012/WD-SVG2-20120828/">http://www.w3.org/TR/2012/WD-SVG2-20120828/</a>
dschulze@470 1963 </dd>
dschulze@470 1964 </dl>
dschulze@273 1965
dschulze@273 1966 <h3 class="no-num" id="other-references">
dschulze@273 1967 Other references</h3>
dschulze@273 1968 <!--informative-->
dschulze@273 1969
dschulze@273 1970 <h2 class="no-num" id="index">
dschulze@273 1971 Index</h2>
dschulze@273 1972 <!--index-->
dschulze@273 1973
dschulze@273 1974 <h2 class="no-num" id="property-index">
dschulze@273 1975 Property index</h2>
dschulze@273 1976 <!-- properties -->
dschulze@273 1977
dschulze@273 1978 </body>
dschulze@273 1979 </html>
dschulze@273 1980 <!-- Keep this comment at the end of the file
dschulze@273 1981 Local variables:
dschulze@273 1982 mode: sgml
dschulze@273 1983 sgml-declaration:"~/SGML/HTML4.decl"
dschulze@273 1984 sgml-default-doctype-name:"html"
dschulze@273 1985 sgml-minimize-attributes:t
dschulze@273 1986 sgml-nofill-elements:("pre" "style" "br")
dschulze@273 1987 sgml-live-element-indicator:t
dschulze@273 1988 sgml-omittag:nil
dschulze@273 1989 sgml-shorttag:nil
dschulze@273 1990 sgml-namecase-general:t
dschulze@273 1991 sgml-general-insert-case:lower
dschulze@273 1992 sgml-always-quote-attributes:t
dschulze@273 1993 sgml-indent-step:nil
dschulze@273 1994 sgml-indent-data:t
dschulze@273 1995 sgml-parent-document:nil
dschulze@273 1996 sgml-exposed-tags:nil
dschulze@273 1997 sgml-local-catalogs:nil
dschulze@273 1998 sgml-local-ecat-files:nil
dschulze@273 1999 End:
dschulze@273 2000 -->
dschulze@273 2001
dschulze@273 2002

mercurial