🎭 Masks (#221)

Author: wcandillon

docs/docs/assets/mask/alpha.png

@@ -37,9 +37,10 @@ const Filter = () => {
         height={256}
         fit="cover"
       />
-      <BackdropFilter clip={{ x: 0, y: 128, width: 256, height: 128 }}>
-        <ColorMatrix matrix={BLACK_AND_WHITE} />
-      </BackdropFilter>
+      <BackdropFilter
+        clip={{ x: 0, y: 128, width: 256, height: 128 }}
+        filter={<ColorMatrix matrix={BLACK_AND_WHITE} />}
+      />
     </Canvas>
   );
 };

docs/docs/assets/mask/luminance.png

@@ -9,7 +9,7 @@ Images can be draw by specifying the output rectangle and how the image should f
 
 | Name   | Type                  | Description                                                                                                                                                   |
 | :----- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| image  | `IImage`              | Image instance.                                                                                                                     |
+| image  | `SkImage`              | Image instance.                                                                                                                     |
 | x      | `number`              | Left position of the destination image.                                                                                                                       |
 | y      | `number`              | Right position of the destination image.                                                                                                                      |
 | width  | `number`              | Width of the destination image.                                                                                                                               |

docs/docs/backdrop-filters.md

@@ -0,0 +1,77 @@
+---
+id: mask
+title: Mask
+sidebar_label: Mask
+slug: /mask
+---
+
+The `Mask` component hides an element by masking the content at specific points.
+Just like its [CSS counterpart](https://developer.mozilla.org/en-US/docs/Web/CSS/mask), there are two modes available:
+* `alpha`: This mode indicates that the transparency (alpha channel) values of the mask layer image should be used as the mask values. This is how masks work in Figma.
+* `luminance`: This mode indicates that the luminance values of the mask layer image should be used as the mask values. This is how masks work in SVG.
+
+The first child of `Mask` is the drawing to be used as a mask, and the remaining children are the drawings to mask.
+
+By default, the mask is not clipped. If you want to clip the mask with the bounds of the content it is masking, use the `bounds` property. 
+
+| Name      | Type                      | Description                                                   |
+|:----------|:--------------------------|:--------------------------------------------------------------|
+| mode?     | `alpha` or `luminance`    | Is it a luminance or alpha mask (default is `alpha`)          |
+| bounds?   | `SkRect`                  | Optional rectangle to clip the mask with                      |
+| mask      | `ReactNode[] | ReactNode` | Mask definition | 
+| children  | `ReactNode[] | ReactNode` | Content to mask |
+
+## Alpha Mask
+
+Opaque pixels will be visible and transparent pixels invisible.
+
+```tsx twoslash
+import {Canvas, Mask, Group, Circle, Rect} from "@shopify/react-native-skia";
+
+const Demo = () => (
+  <Canvas style={{ width: 256, height: 256 }}>
+    <Mask
+      mask={
+        <Group>
+          <Circle cx={128} cy={128} r={128} opacity={0.5} />
+          <Circle cx={128} cy={128} r={64} />
+        </Group>
+      }
+    >
+      <Rect x={0} y={0} width={256} height={256} color="lightblue" />
+    </Mask>
+  </Canvas>
+);
+```
+
+### Result
+
+![Alpha Mask](assets/mask/alpha.png)
+
+## Luminance Mask
+
+White pixels will be visible and black pixels invisible.
+
+```tsx twoslash
+import {Canvas, Mask, Group, Circle, Rect} from "@shopify/react-native-skia";
+
+const Demo = () => (
+  <Canvas style={{ width: 256, height: 256 }}>
+    <Mask
+      mode="luminance"
+      mask={
+        <Group>
+          <Circle cx={128} cy={128} r={128} color="white" />
+          <Circle cx={128} cy={128} r={64} color="black" />
+        </Group>
+      }
+    >
+      <Rect x={0} y={0} width={256} height={256} color="lightblue" />
+    </Mask>
+  </Canvas>
+);
+```
+
+### Result
+
+![Luminance Mask](assets/mask/luminance.png)

docs/docs/image.md

@@ -159,7 +159,7 @@ Stamp the specified path to fill the shape, using the matrix to define the latic
 | Name      | Type         |  Description                  |
 |:----------|:-------------|:------------------------------|
 | path      | `PathDef`    | The path to use               |
-| matrix    | `IMatrix`    |  Matrix to be applied         |
+| matrix    | `SkMatrix`    |  Matrix to be applied         |
 | children? | `PathEffect` | Optional path effect to apply |
 
 ### Example

docs/docs/mask.md

@@ -12,13 +12,13 @@ It will use cubic sampling.
 
 | Name       | Type           |  Description                       |
 |:-----------|:---------------|:-----------------------------------|
-| image      | `IImage`       | Image instance. |
+| image      | `SkImage`       | Image instance. |
 | tx?        | `TileMode`     | Can be `clamp`, `repeat`, `mirror`, or `decal`. |
 | ty?        | `TileMode`     | Can be `clamp`, `repeat`, `mirror`, or `decal`. |
 | fm?        | `FilterMode`.  | Can be `linear` or `nearest`. |
 | mm?        | `MipmapMode`   | Can be `none`, `linear` or `nearest`. |
 | fit?       | `Fit`.         | Calculate the transformation matrix to fit the rectangle defined by `fitRect`. See [images](images). |
-| rect?      | `IRect`        | The destination reactangle to calculate the transformation matrix via the `fit` property. |
+| rect?      | SkRect`        | The destination reactangle to calculate the transformation matrix via the `fit` property. |
 | transform? | `Transforms2d` | see [transformations](/docs/group#transformations). |
 
 ### Example

docs/docs/path-effects.md

@@ -37,6 +37,11 @@ const sidebars = {
       label: "Group",
       id: "group",
     },
+    {
+      type: "doc",
+      label: "Mask",
+      id: "mask",
+    },
     {
       collapsed: true,
       type: "category",

docs/docs/shaders/images.md

@@ -1,6 +1,13 @@
 /* eslint-disable max-len */
 import React from "react";
-import { Canvas, Circle, Group, Path, Skia } from "@shopify/react-native-skia";
+import {
+  Canvas,
+  Circle,
+  Group,
+  Path,
+  Skia,
+  Text,
+} from "@shopify/react-native-skia";
 import { Dimensions } from "react-native";
 
 const { width } = Dimensions.get("window");
@@ -72,8 +79,17 @@ export const BlendModes = () => {
             ]}
             key={blendMode}
           >
-            <Path path={src} color="lightblue" blendMode={blendMode} />
-            <Path path={dst} color="pink" blendMode={blendMode} />
+            <Group blendMode={blendMode}>
+              <Path path={src} color="lightblue" />
+              <Path path={dst} color="pink" />
+            </Group>
+            <Text
+              text={blendMode}
+              x={0}
+              y={0}
+              familyName="source-sans-pro-semi-bold"
+              size={50}
+            />
           </Group>
         ))}
       </Group>

docs/sidebars.js

@@ -2,22 +2,17 @@ import React from "react";
 import { StyleSheet, Dimensions, ScrollView } from "react-native";
 import {
   Skia,
-  PaintStyle,
   Canvas,
   Image,
   Group,
+  Circle,
+  Rect,
+  Mask,
   useImage,
 } from "@shopify/react-native-skia";
 
 const { width } = Dimensions.get("window");
 const SIZE = width / 4;
-const paint = Skia.Paint();
-paint.setAntiAlias(true);
-paint.setColor(Skia.Color("#61DAFB"));
-
-const strokePaint = paint.copy();
-strokePaint.setStyle(PaintStyle.Stroke);
-strokePaint.setStrokeWidth(2);
 
 const star = Skia.Path.MakeFromSVGString(
   // eslint-disable-next-line max-len
@@ -72,6 +67,30 @@ export const Clipping = () => {
           />
         </Group>
       </Canvas>
+      <Canvas style={{ width, height: 200 }}>
+        <Mask
+          mode="alpha"
+          mask={
+            <Group>
+              <Circle cx={100} cy={100} r={100} color="#00000066" />
+              <Circle cx={100} cy={100} r={50} color="black" />
+            </Group>
+          }
+        >
+          <Rect x={0} y={0} width={256} height={256} color="lightblue" />
+        </Mask>
+        <Mask
+          mode="luminance"
+          mask={
+            <Group>
+              <Circle cx={300} cy={100} r={100} color="white" />
+              <Circle cx={300} cy={100} r={50} color="black" />
+            </Group>
+          }
+        >
+          <Rect x={200} y={0} width={200} height={200} color="lightblue" />
+        </Mask>
+      </Canvas>
     </ScrollView>
   );
 };