This page is In Progress

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

mask

Overview Table

DOM Interface
SVGElement

Examples

In the following code example, an alpha mask is used to filter text. A linear gradient is defined that runs from magenta to cyan. A mask is then defined that will use the gradient to filter defined text. Alpha masking uses the image brightness to define the opacity of the final image. Magenta is less “bright” than cyan, so the resulting masked image will be less opaque on the left and more opaque on the right.

Copy this sample to a text file and save it with the .html file extension. Run it in Internet Explorer 9 to see the alpha-masked text.

The masked text will look like this:



<!DOCTYPE HTML>
<html>
  <head></head>
  <body>
    <svg width="400" height="400">
      <defs>
        <!-- Define linear gradient for magenta to cyan. -->
        <linearGradient id="magenta2cyan" >
          <!-- First color is magenta. -->
          <stop offset="0%" style="stop-color:magenta"/>
          <!-- Second color is cyan. -->
          <stop offset="100%" style="stop-color:cyan"/>
        </linearGradient>
        <!-- Define mask. -->
        <mask id="myMask" x="0" y="0" width="400" height="400">
          <rect x="0" y="0" width="400" height="400" fill="url(#magenta2cyan)" />
        </mask>
        <!-- Define text. -->
        <text id="myText" x="50" y="50" font-family="Verdana" font-size="32"  >
         SVG forever!
        </text>
      </defs>
      <!-- Use text with mask and gradient. -->
      <use xlink:href="#myText" fill="navy" mask="url(#myMask)" />
    </svg>
  </body>
</html>

Notes

Remarks

Note: In addition to the attributes, properties, events, methods, and styles listed above, SVG elements also inherent core HTML attributes, properties, events, methods, and styles.

In SVG, you can use any graphical object or g element as an alpha mask for compositing that object into the background.

You can define a mask by using a mask element. You can use or reference a mask by using the mask attribute within an appropriate element (for example, <rect mask="url(#myMask)"/>). A mask element can contain any graphical elements or container elements, such as a g element.

The mask attribute cannot reference a non-existent object, and the referenced object must be a mask element.

The effect is the same as if the child elements of the mask element are rendered into an off-screen image that has been initialized to transparent black. Any graphical object that uses or references the given mask element is painted onto the background through the mask, which completely or partially masks parts of the graphical object.

For any graphical object that is used as a mask, the mask value at any point is computed from the color channel values and alpha channel value as follows:

  1. Compute a linear luminance value from the color channel values. For example, convert the original image color values (potentially in the sRGB color space) to the linear RGB color space. Then, by using non-premultiplied linear RGB color values, apply the luminance-to-alpha coefficients to convert the linear RGB color values to linear luminance values.
  2. If the graphics object also includes an alpha channel, multiply the computed linear luminance value by the corresponding alpha value to produce the mask value.

For a four-channel RGBA graphics object that is used as a mask, both the color channels and the alpha channel of the mask contribute to the masking operation. The alpha mask that is used to composite the current object into the background represents the product of the luminance of the color channels and the alpha channel from the mask.

For a three-channel RGB graphics object that is used as a mask (for example, when you reference a 3-channel image file), the effect is the same as if the object is converted into a 4-channel RGBA image with the alpha channel uniformly set to 1.

For a single-channel image that is used as a mask (for example, when you reference a 1-channel grayscale image file), the effect is the same as if the object is converted into a 4-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.

Note: When you reference a grayscale image file, you must consider the transfer curve that relates the encoded grayscale values to linear light values when you compute the color channels.

The effect of a mask is the same as if there is no mask, but the alpha channel of the given object is multiplied by the mask’s resulting alpha values (that is, the product of the mask’s luminance from its color channels multiplied by the mask’s alpha channel).

Note: The paths, shapes (for example, circle), and text in SVG are all treated as four-channel RGBA images for the purposes of masking operations.

Standards information

Members

The SVGMaskElement object has these events:

  • onload: Occurs when the browser has fully parsed the element and all of its descendants.

The SVGMaskElement object has these methods:

  • hasExtension: Determines if the specified extension is supported.

The SVGMaskElement object has these properties:

  • className: Gets the names of the classes that are assigned to this object.
  • clipPath: Sets or retrieves a reference to the SVG graphical object that will be used as the clipping path.
  • externalResourcesRequired: Gets a value that indicates whether referenced resources that are not in the current document are required to correctly render a given element.
  • focusable: Determines if an element can acquire keyboard focus (that is, receive keyboard events) and be a target for field-to-field navigation actions (such as when a user presses the Tab key).
  • height: Gets or sets the height of an element.
  • mask: Sets or retrieves a value that indicates a SVG mask.
  • maskContentUnits: Gets the maskContentUnits attribute of the mask element.
  • maskUnits: Gets the maskUnits attribute of the mask element.
  • ownerSVGElement: Gets the nearest ancestor svg element.
  • requiredExtensions: Gets a white space-delimited list of required language extensions.
  • requiredFeatures: Gets or sets a white space-delimited list of feature strings.
  • style: Gets a style object.
  • systemLanguage: Gets or sets a comma-separated list of language names.
  • viewportElement: Gets the element that established the current viewport.
  • width: Defines the width of an element.
  • x: Gets or sets the x-coordinate value.
  • xmlbase: Gets or sets the base attribute on the element.
  • xmllang: Gets or sets a value that specifies the language that is used in the contents and attribute values of an element.
  • xmlspace: Gets or sets a value that indicates whether white space is preserved in character data.
  • y: Gets or sets the y-coordinate value.

Attributions