Merge pull request #2041 from Shopify/deprecation

Deprecation of `SkiaView` and `<Drawing />`

Author: wcandillon

docs/docs/shapes/pictures.md

@@ -11,7 +11,54 @@ A Picture renders a previously recorded list of drawing operations on the canvas
 | :------ | :---------- | :---------------- |
 | picture | `SkPicture` | Picture to render |
 
-### Example
+
+## Hello World
+
+```tsx twoslash
+import React, { useMemo } from "react";
+import {
+  createPicture,
+  Canvas,
+  Picture,
+  Skia,
+  Group,
+  BlendMode
+} from "@shopify/react-native-skia";
+
+const size = 256;
+
+export const HelloWorld = () => {
+  // Create a picture
+  const picture = useMemo(() => createPicture(
+    { width: size, height: size },
+    (canvas) => {
+      const r = 0.33 * size;
+      const paint = Skia.Paint();
+      paint.setBlendMode(BlendMode.Multiply);
+
+      paint.setColor(Skia.Color("cyan"));
+      canvas.drawCircle(r, r, r, paint);
+
+      paint.setColor(Skia.Color("magenta"));
+      canvas.drawCircle(size - r, r, r, paint);
+
+      paint.setColor(Skia.Color("yellow"));
+      canvas.drawCircle(size / 2, size - r, r, paint);
+    }
+  ), []);
+  return (
+    <Canvas style={{ flex: 1 }}>
+      <Picture picture={picture} />
+    </Canvas>
+  );
+};
+```
+
+## Serialization
+
+You can serialize a picture to a byte array.
+Serialized pictures are only compatible with the version of Skia it was created with.
+You can use serialized pictures with the [Skia debugger](https://skia.org/docs/dev/tools/debugger/).
 
 ```tsx twoslash
 import React, { useMemo } from "react";
@@ -26,7 +73,7 @@ import {
 export const PictureExample = () => {
   // Create picture
   const picture = useMemo(() => createPicture(
-    { x: 0, y: 0, width: 100, height: 100 },
+    { width: 100, height: 100 },
     (canvas) => {
       const paint = Skia.Paint();
       paint.setColor(Skia.Color("pink"));

package/src/__tests__/snapshots/pictures/hello-world.png

@@ -173,6 +173,10 @@ export class JsiSkDOM implements SkDOM {
   }
 
   CustomDrawing(props: CustomDrawingNodeProps) {
+    console.warn(
+      // eslint-disable-next-line max-len
+      "The <Drawing /> component is deprecated and will be removed in the next release. For custom drawings, please sure the <Picture /> component: https://shopify.github.io/react-native-skia/docs/shapes/pictures/"
+    );
     return NATIVE_DOM
       ? global.SkiaDomApi.CustomDrawingNode(props ?? {})
       : new CustomDrawingNode(this.ctx, props);

package/src/__tests__/snapshots/pictures/simple-picture.png

@@ -0,0 +1,50 @@
+import { importSkia, surface } from "../setup";
+import { checkImage } from "../../../__tests__/setup";
+import { BlendMode } from "../../../skia/types";
+
+describe("Pictures", () => {
+  it("Should draw a simple picture", async () => {
+    const { Skia } = importSkia();
+    const str = await surface.eval((Sk) => {
+      const size = 256;
+      const surf = Sk.Surface.MakeOffscreen(size, size)!;
+      const canvas = surf.getCanvas();
+      const recorder = Sk.PictureRecorder();
+      const canvas2 = recorder.beginRecording(Sk.XYWHRect(0, 0, size, size));
+      canvas2.drawColor(Sk.Color("cyan"));
+      const picture = recorder.finishRecordingAsPicture();
+      canvas.drawPicture(picture);
+      return surf.makeImageSnapshot().encodeToBase64();
+    });
+    const image = Skia.Image.MakeImageFromEncoded(Skia.Data.fromBase64(str))!;
+    checkImage(image, "snapshots/pictures/simple-picture.png");
+  });
+  it("Should draw the hello world example as picture", async () => {
+    const { Skia } = importSkia();
+    const str = await surface.eval(
+      (Sk, ctx) => {
+        const { size } = ctx;
+        const r = size * 0.33;
+        const surf = Sk.Surface.MakeOffscreen(size, size)!;
+        const canvas = surf.getCanvas();
+        const recorder = Sk.PictureRecorder();
+        const canvas2 = recorder.beginRecording(Sk.XYWHRect(0, 0, size, size));
+        const paint = Sk.Paint();
+        paint.setBlendMode(ctx.BlendMode);
+        paint.setColor(Sk.Color("cyan"));
+        canvas2.drawCircle(r, r, r, paint);
+        paint.setColor(Sk.Color("magenta"));
+        canvas2.drawCircle(size - r, r, r, paint);
+        paint.setColor(Sk.Color("yellow"));
+        canvas2.drawCircle(size / 2, size - r, r, paint);
+        const picture = recorder.finishRecordingAsPicture();
+        canvas.drawPicture(picture);
+        surf.flush();
+        return surf.makeImageSnapshot().encodeToBase64();
+      },
+      { BlendMode: BlendMode.Multiply, size: surface.width }
+    );
+    const image = Skia.Image.MakeImageFromEncoded(Skia.Data.fromBase64(str))!;
+    checkImage(image, "snapshots/pictures/hello-world.png");
+  });
+});

package/src/dom/nodes/JsiSkDOM.ts

@@ -2,6 +2,11 @@ import React from "react";
 
 import type { CustomDrawingNodeProps } from "../../dom/types";
 
+/**
+ * @deprecated If you are looking to use the Skia imperative API, you can use:
+ * The picture API: https://shopify.github.io/react-native-skia/docs/shapes/pictures/
+ * The offscreen API: https://shopify.github.io/react-native-skia/docs/animations/textures
+ */
 export const Drawing = (props: CustomDrawingNodeProps) => {
   return <skDrawing {...props} />;
 };

package/src/renderer/__tests__/e2e/Picture.spec.tsx

@@ -1,15 +1,20 @@
 import { Skia } from "../Skia";
-import type { SkCanvas, SkRect } from "../types";
+import { isRect, type SkCanvas, type SkRect, type SkSize } from "../types";
 
 /**
  * Memoizes and returns an SkPicture that can be drawn to another canvas.
  * @param rect Picture bounds
  * @param cb Callback for drawing to the canvas
  * @returns SkPicture
  */
-export const createPicture = (rect: SkRect, cb: (canvas: SkCanvas) => void) => {
+export const createPicture = (
+  rect: SkRect | SkSize,
+  cb: (canvas: SkCanvas) => void
+) => {
   const recorder = Skia.PictureRecorder();
-  const canvas = recorder.beginRecording(rect);
+  const canvas = recorder.beginRecording(
+    isRect(rect) ? rect : Skia.XYWHRect(0, 0, rect.width, rect.height)
+  );
   cb(canvas);
   return recorder.finishRecordingAsPicture();
 };

package/src/renderer/components/Drawing.tsx

@@ -4,3 +4,16 @@ export interface SkRect {
   readonly width: number;
   readonly height: number;
 }
+
+export const isRect = (def: unknown): def is SkRect => {
+  if (typeof def === "object" && def !== null) {
+    const rect = def as SkRect;
+    return (
+      typeof rect.x === "number" &&
+      typeof rect.y === "number" &&
+      typeof rect.width === "number" &&
+      typeof rect.height === "number"
+    );
+  }
+  return false;
+};

package/src/skia/core/Picture.ts

@@ -11,9 +11,20 @@ export const SkiaViewNativeId = { current: 1000 };
 
 const NativeSkiaView = SkiaDrawViewNativeComponent;
 
+/**
+ * @deprecated If you are looking to use the Skia imperative API, you can use:
+ * The picture API: https://shopify.github.io/react-native-skia/docs/shapes/pictures/
+ * The offscreen API: https://shopify.github.io/react-native-skia/docs/animations/textures
+ */
 export class SkiaView extends React.Component<SkiaDrawViewProps> {
   constructor(props: SkiaDrawViewProps) {
     super(props);
+    console.warn(
+      `The SkiaView component is deprecated and will be removed in the next release.
+If you are looking to use the Skia imperative API, you can use:
+* The picture API: https://shopify.github.io/react-native-skia/docs/shapes/pictures/
+* The offscreen API: https://shopify.github.io/react-native-skia/docs/animations/textures`
+    );
     this._nativeId = SkiaViewNativeId.current++;
     const { onDraw, onSize } = props;
     if (onDraw) {