R: Create the definition of an opacity mask.

Opacity Masks {gridSVG} | R Documentation

## Create the definition of an opacity mask.

### Description

A feature of SVG is that elements can have an opacity mask applied to it. An opacity mask is an image that, for various levels of opacity, makes the object that is being masked inherit the same levels of opacity. The purpose of these functions is to define an opacity mask that will be applied until the current viewport (or context, see `popContext`) is popped. Alternatively it can also be applied to grobs.

### Usage

    mask(grob,
         x = unit(0.5, "npc"), y = unit(0.5, "npc"),
         width = unit(1, "npc"), height = unit(1, "npc"),
         default.units = "npc",
         just = "centre", hjust = NULL, vjust = NULL)
    registerMask(label, mask = NULL, ...)

### Arguments

`grob` | A grob or gTree that will be drawn as the opacity mask.
`x` | A numeric vector or unit object specifying x-location.
`y` | A numeric vector or unit object specifying y-location.
`width` | A numeric vector or unit object specifying width.
`height` | A numeric vector or unit object specifying height.
`default.units` | A string indicating the default units to use if `x`, `y`, `width`, or `height` are only given as numeric vectors.
`just` | The justification of the pattern relative to its (x, y) location. If there are two values, the first value specifies horizontal justification and the second value specifies vertical justification. Possible string values are: `"left"`, `"right"`, `"centre"`, `"center"`, `"bottom"`, and `"top"`. For numeric values, 0 means left alignment and 1 means right alignment.
`hjust` | A numeric vector specifying horizontal justification. If specified, overrides the `just` setting.
`vjust` | A numeric vector specifying vertical justification. If specified, overrides the `just` setting.
`label` | A character identifier that will be used to reference this definition.
`mask` | A `mask` object that defines the mask.
`...` | Arguments to be given to `mask`.

### Details

When registering the mask, the rectangular region that the mask applies to will become fixed.

When referring to an opacity mask, the masked content will be opaque at the same coordinates that the mask is opaque. The same applies when there is any level of transparency, as any transparency in the mask will also apply in the same corresponding region of the masked object.

The mask's opacity is defined as being the level of luminance present in the mask. This means anything black is fully transparent, while anything white is completely opaque. The background is assumed to be black (i.e. fully transparent). The `alpha` value in a mask will still be used, but its effect is combined with the computed opacity from the luminance of the mask.

By using an opacity mask it is possible to have a grob with non-uniform opacity. In other words, rather than specifying an opacity via `gpar`'s `alpha` parameter, which is uniform across the grob, we can define varying opacities on a grob via an opacity mask.

The `x`, `y`, `width`, `height` parameters determine the location and dimensions of the area to apply the mask to. This means we can apply a mask to any rectangular region, relative to the viewport in which it is defined (via `registerMask`).

### Value

For `mask`, a `mask` object.

### Author(s)

Simon Potter

### See Also

`grid.mask`, `pushMask`, `popContext`.

[Package gridSVG version 1.6-0 Index]