## Masks and track mattes

`hasMask: true` turns on a layer's masks: with any other value, the layer draws without them. Each `masksProperties` entry is one mask:

```json
{"nm":"Window","mode":"a","inv":false,"pt":{"a":0,"k":{"c":true,"v":[[0,0],[200,0],[200,100],[0,100]],"i":[[0,0],[0,0],[0,0],[0,0]],"o":[[0,0],[0,0],[0,0],[0,0]]}},"o":{"a":0,"k":100},"f":{"a":0,"k":[0,0]}}
```

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `mode` | text | Required | `a` add, `s` subtract, `i` intersect, `f` difference. `n` (none), lighten `l`, darken `d` and other values are skipped. |
| `inv` | boolean | `false` | `true` inverts the mask |
| `pt` | property: path | Empty | The path, with the same tangent and topology rules as a [shape path](#paths). It may animate. |
| `o` | property: number | 0, transparent | Opacity, 0–100. Fixed, a plain number: `{"a":0,"k":100}`. Animated, a list such as `[100]` in each key's `s`. |
| `f` | property: `[x,y]` | Required | Feather in pixels, drawn as a static blur. When animated, it keeps its first value. |
| `x` | property | None | Expansion. Ignored (`warnings`). |

- Mask coordinates are local to the masked layer.
- Keep one entry per mask, in authored order. A layer can have any number of masks: use the fewest that express the region, since each add, subtract, intersect or difference mask counts toward the [path limit](#vector-paths).
- A layer whose masks are all skipped draws unmasked.
- Write an explicit numeric `a:0` or `a:1`, and complete path and opacity objects.
- To animate a mask path, replace `pt` with path keyframes that keep the vertex topology. Masks don't run expressions.
- An image, solid, video or precomposition layer is masked before its effects run ([effects](#effects)).

### Track mattes

A track matte uses two layers in the same composition. The receiver, the content, has `tt` and a `tp` equal to the caster's `ind`. The caster has `td: 1`. `tt` is `1` alpha, `2` inverted alpha, `3` luma or `4` inverted luma.

- For video inside a shape, the shape is the caster and the video is the receiver.
- Always give a `tt` layer a whole-number `tp`, or remove `tt`. Don't rely on adjacency, chain receivers and casters, or leave a dangling `tp`.
- Mattes don't chain: a caster's own blend mode and track matte are ignored.
- The receiver is matted only while its caster draws. The caster does not draw when it is hidden (`hd: true`), outside its `ip` and `op`, entirely off screen, or a null or camera. Then, or when `tp` names no layer, an alpha or luma matte hides the receiver. An inverted matte draws it unmatted.
- Any `td`, whatever its value (`td: 0` too), makes its layer draw only as a matte. A `td` layer no receiver points at is never drawn (`warnings`).
- Don't use a precomposition collapsed with `cp` as a matte: giving it `td` stops the collapse.
- To clear or move a matte role, remove the obsolete `tt`, `tp` and `td`: zero is not the same as removing them. Change both sides together.
- Keep the caster's geometry, transforms and opacity aligned with the content throughout the animation.

### Edge cases

- A missing `mode`, or one that is not text: `problems`.
- `inv` other than the boolean `true` reads as `false`.
- A missing `pt` draws an empty mask, so an add mask hides the layer (`warnings`).
- A fixed `o` written as a list is misread (`warnings`).
- A feather of one number reads its second from beyond the list (`warnings`).
- A `pt`, `o` or `f` the engine cannot read, such as a bare whole number: `problems`. So is a feather that is `null` or has no `k`.
- A `masksProperties` that is not a list of mask objects while `hasMask` is `true`: `problems`.
- `tt` written `1.0` reads as 0, no matte. The receiver is still hidden whenever its caster does not draw.
- A caster that does not draw for part of the receiver's visible span: `warnings`.
- `warnings` name the other cases the engine drops or misreads.
