react-native-skia 3.0.0 → 3.0.2

package/src/renderer/Canvas.tsx

@@ -19,8 +19,9 @@ import type { SharedValue } from "react-native-reanimated";
 
 import Rea from "../external/reanimated/ReanimatedProxy";
 import { SkiaViewNativeId } from "../views/SkiaViewNativeId";
-import type { AndroidCanvasProps, AndroidSurfaceType } from "../views/types";
-import SkiaPictureViewNativeComponent from "../specs/SkiaPictureViewNativeComponent";
+import { androidNativeProps } from "../views/android";
+import type { AndroidCanvasProps } from "../views/types";
+import SkiaViewNativeComponent from "../specs/SkiaViewNativeComponent";
 import type { SkImage, SkRect, SkSize } from "../skia/types";
 import { SkiaSGRoot } from "../sksg/Reconciler";
 import { Skia } from "../skia";
@@ -61,7 +62,6 @@ export const useCanvasSize = (userRef?: RefObject<CanvasRef | null>) => {
 };
 
 export interface CanvasProps extends Omit<ViewProps, "onLayout"> {
-  debug?: boolean;
   /** @deprecated Not supported on native. Use `onSize` or `useCanvasSize()` instead. */
   onLayout?: ViewProps["onLayout"];
   /**
@@ -72,7 +72,6 @@ export interface CanvasProps extends Omit<ViewProps, "onLayout"> {
    */
   opaque?: boolean;
   onSize?: SharedValue<SkSize>;
-  colorSpace?: "p3" | "srgb";
   /**
    * Renders into a surface with more than 8 bits per channel (16-bit float on
    * iOS, 10-bit on Android) to avoid banding in subtle gradients. Colors are
@@ -85,25 +84,14 @@ export interface CanvasProps extends Omit<ViewProps, "onLayout"> {
   /** Android-only rendering options. Ignored on iOS and web. */
   android?: AndroidCanvasProps;
   ref?: React.Ref<CanvasRef>;
-  androidWarmup?: boolean;
   __destroyWebGLContextAfterRender?: boolean;
 }
 
-// Anything else reaching the native component would hit the generated
-// string-enum parser, which aborts on unknown values.
-const resolveSurfaceType = (
-  surfaceType: AndroidSurfaceType | undefined
-): "auto" | AndroidSurfaceType =>
-  surfaceType === "SurfaceView" || surfaceType === "TextureView"
-    ? surfaceType
-    : "auto";
-
 /**
- * What every canvas shares, whichever native view it renders into: the native
- * id, the scene graph root rendered into it, the `onSize` measurement and the
- * imperative handle of the ref.
+ * What the canvas owns: the native id, the scene graph root rendered into it,
+ * the `onSize` measurement and the imperative handle of the ref.
  */
-export const useCanvasRoot = ({
+const useCanvasRoot = ({
   children,
   onSize,
   ref,
@@ -186,14 +174,26 @@ export const useCanvasRoot = ({
   return { nativeId, viewRef };
 };
 
+/**
+ * The declarative canvas. Its children are rendered by Skia's own React
+ * renderer; the frames are produced off the JS thread:
+ *
+ * - the JS thread records the scene graph into a native recorder once per
+ *   React commit and hands it to the view;
+ * - the Reanimated UI runtime only reads the shared values into it (the one
+ *   step that needs a JS runtime), it never replays anything;
+ * - a dedicated native thread pool replays the recorder into a Graphite
+ *   recording whenever the content changed, at most once per presented frame;
+ * - the view presents the recording on the next vsync.
+ *
+ * On the web the scene is drawn into a picture on the JS thread and painted
+ * on a WebGL canvas.
+ */
 export const Canvas = ({
-  debug,
   opaque,
   children,
   onSize,
-  colorSpace = "p3",
   highBitDepth = false,
-  androidWarmup = false,
   android,
   ref,
   onLayout,
@@ -219,17 +219,13 @@ export const Canvas = ({
     [onLayout, onSize]
   );
   return (
-    <SkiaPictureViewNativeComponent
+    <SkiaViewNativeComponent
       ref={viewRef}
       collapsable={false}
       nativeID={`${nativeId}`}
-      debug={debug}
       opaque={opaque}
-      colorSpace={colorSpace}
       highBitDepth={highBitDepth}
-      androidWarmup={androidWarmup}
-      androidSurfaceType={resolveSurfaceType(android?.surfaceType)}
-      androidZOrderOnTop={!!android?.zOrderOnTop}
+      {...androidNativeProps(android)}
       onLayout={
         Platform.OS === "web" && (onSize || onLayout) ? onLayoutWeb : onLayout
       }

package/src/skia/types/Graphite.ts

@@ -2,13 +2,13 @@ import type { SkCanvas } from "./Canvas";
 import type { SkJSIInstance } from "./JsiInstance";
 
 /**
- * A frame recorded for a SkiaGraphiteView. Immutable once finished: submit it
- * to the view as many times as needed, from any runtime.
+ * A frame recorded for a view. Immutable once finished: submit it to the view
+ * as many times as needed, from any runtime.
  */
 export type SkGraphiteRecording = SkJSIInstance<"GraphiteRecording">;
 
 /**
- * The recording side of a SkiaGraphiteView, obtained from the view's ref.
+ * The recording side of a view, obtained from the ref of a SkiaGraphiteView.
  *
  * Frames are recorded on the calling thread and presented by the view on its
  * display link, so the context can be captured into a worklet and used from

package/src/skia/types/Image/ImageFactory.ts

@@ -106,7 +106,7 @@ export interface ImageFactory {
    * while the image is in use: destroy() releases the underlying GPU
    * resource regardless of reference counts.
    *
-   * Note: This method is only available when the Graphite backend is enabled.
+   * Native only.
    *
    * @param pointer - The WGPUTexture pointer (texture.nativePointer)
    * @returns An SkImage wrapping the texture, or throws if the texture is invalid
@@ -119,7 +119,7 @@ export interface ImageFactory {
    * returned pointer carries one reference and must be adopted exactly once
    * with react-native-webgpu's adoptTexture(), which owns it from then on.
    *
-   * Note: This method is only available when the Graphite backend is enabled.
+   * Native only.
    *
    * @param image - An SkImage to convert to a texture
    * @returns A WGPUTexture pointer for adoptTexture(), or throws on failure

package/src/skia/types/Skia.ts

@@ -106,8 +106,7 @@ export interface Skia {
   /**
    * Raw WGPUDevice pointer of Skia's Graphite device, as a BigInt. Pass it to
    * react-native-webgpu's importDevice() to get a GPUDevice sharing Skia's
-   * device (zero-copy interop). Only available on Graphite builds; throws
-   * otherwise.
+   * device (zero-copy interop). Native only.
    */
   getNativeDevice(): bigint;
 }

package/src/skia/types/Surface/SurfaceFactory.ts

@@ -43,7 +43,7 @@ export interface SurfaceFactory {
    * surface exists. Calling destroy() on the GPUTexture still invalidates
    * the surface.
    *
-   * Note: This method is only available when the Graphite backend is enabled.
+   * Native only.
    *
    * @param pointer - The WGPUTexture pointer (texture.nativePointer)
    * @returns An SkSurface rendering into the texture, or throws if the texture is invalid

package/src/specs/NativeSkiaModule.web.ts

@@ -7,8 +7,12 @@ import type {
 } from "../skia/types";
 import type { ISkiaViewApi } from "../views/types";
 
-/** What every web view registers under its native id. */
+/** What the web view registers under its native id. */
 export interface SkiaWebViewHandle {
+  /** Shows a picture: the frame of a <Canvas> or a <SkiaPictureView>. */
+  setPicture(picture: SkPicture): void;
+  /** The recording side of the view, see SkiaGraphiteView. */
+  getContext(): SkGraphiteContext;
   getSize(): { width: number; height: number };
   redraw(): void;
   makeImageSnapshot(rect?: SkRect): SkImage | null;
@@ -27,20 +31,6 @@ export interface SkiaWebViewHandle {
   ): void;
 }
 
-export interface SkiaGraphiteViewHandle extends SkiaWebViewHandle {
-  getContext(): SkGraphiteContext;
-}
-
-interface PictureHandle extends SkiaWebViewHandle {
-  setPicture(picture: SkPicture): void;
-}
-
-const hasPicture = (view: SkiaWebViewHandle): view is PictureHandle =>
-  "setPicture" in view;
-
-const hasContext = (view: SkiaWebViewHandle): view is SkiaGraphiteViewHandle =>
-  "getContext" in view;
-
 export type ISkiaViewApiWeb = ISkiaViewApi & {
   views: Record<string, SkiaWebViewHandle>;
   deferedPictures: Record<string, SkPicture>;
@@ -58,7 +48,7 @@ global.SkiaViewApi = {
   registerView(nativeId: string, view: SkiaWebViewHandle) {
     this.unregisteredViews.delete(nativeId);
     // Maybe a picture for this view was already set
-    if (this.deferedPictures[nativeId] && hasPicture(view)) {
+    if (this.deferedPictures[nativeId]) {
       view.setPicture(this.deferedPictures[nativeId] as SkPicture);
       delete this.deferedPictures[nativeId];
     }
@@ -77,9 +67,7 @@ global.SkiaViewApi = {
       const id = `${nativeId}`;
       const view = this.views[id];
       if (view) {
-        if (hasPicture(view)) {
-          view.setPicture(value);
-        }
+        view.setPicture(value);
       } else if (!this.unregisteredViews.has(id)) {
         this.deferedPictures[id] = value;
       }
@@ -114,9 +102,9 @@ global.SkiaViewApi = {
   },
   makeGraphiteContext(nativeId: number) {
     const view = this.views[`${nativeId}`];
-    if (!view || !hasContext(view)) {
+    if (!view) {
       throw new Error(
-        `Cannot make a Graphite context: no SkiaGraphiteView with nativeID ${nativeId} is mounted`
+        `Cannot make a Graphite context: no view with nativeID ${nativeId} is mounted`
       );
     }
     return view.getContext();

package/src/specs/{SkiaPictureViewNativeComponent.ts → SkiaViewNativeComponent.ts}

@@ -4,11 +4,8 @@ import type { WithDefault } from "react-native/Libraries/Types/CodegenTypes";
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore - pointerEvents needs to be redeclared for codegen to generate native bindings
 export interface NativeProps extends ViewProps {
-  debug?: boolean;
   opaque?: boolean;
-  colorSpace?: string;
   highBitDepth?: boolean;
-  androidWarmup?: boolean;
   androidSurfaceType?: WithDefault<
     "auto" | "SurfaceView" | "TextureView",
     "auto"
@@ -21,4 +18,4 @@ export interface NativeProps extends ViewProps {
 }
 
 // eslint-disable-next-line import/no-default-export
-export default codegenNativeComponent<NativeProps>("SkiaPictureView");
+export default codegenNativeComponent<NativeProps>("SkiaView");

package/src/specs/{SkiaPictureViewNativeComponent.web.ts → SkiaViewNativeComponent.web.ts}

@@ -1,33 +1,31 @@
 import type { ViewProps } from "react-native";
 import { createElement } from "react";
 
-import { SkiaPictureView } from "../views/SkiaPictureView.web";
+import { SkiaView } from "../views/SkiaView.web";
 
 export interface NativeProps extends ViewProps {
-  debug?: boolean;
   opaque?: boolean;
+  highBitDepth?: boolean;
   nativeID: string;
   androidSurfaceType?: "auto" | "SurfaceView" | "TextureView";
   androidZOrderOnTop?: boolean;
 }
 
-const SkiaPictureViewNativeComponent = ({
+const SkiaViewNativeComponent = ({
   nativeID,
-  debug,
-  opaque,
   onLayout,
-  // Android-only, never reaches the DOM
+  // Surface settings, never reach the DOM
+  opaque: _opaque,
+  highBitDepth: _highBitDepth,
   androidSurfaceType: _androidSurfaceType,
   androidZOrderOnTop: _androidZOrderOnTop,
   ...viewProps
 }: NativeProps) => {
-  return createElement(SkiaPictureView, {
+  return createElement(SkiaView, {
     nativeID,
-    debug,
-    opaque,
     onLayout,
     ...viewProps,
   });
 };
 // eslint-disable-next-line import/no-default-export
-export default SkiaPictureViewNativeComponent;
+export default SkiaViewNativeComponent;

package/src/views/SkiaGraphiteView.tsx

@@ -1,9 +1,11 @@
 import React, { useImperativeHandle, useMemo, useRef } from "react";
 
 import type { SkGraphiteContext } from "../skia/types";
-import SkiaGraphiteViewNativeComponent from "../specs/SkiaGraphiteViewNativeComponent";
+import SkiaViewNativeComponent from "../specs/SkiaViewNativeComponent";
+import { Platform } from "../Platform";
 
 import { SkiaViewApi } from "./api";
+import { androidNativeProps } from "./android";
 import type { SkiaGraphiteViewNativeProps } from "./types";
 import { SkiaViewNativeId } from "./SkiaViewNativeId";
 
@@ -20,40 +22,49 @@ export interface SkiaGraphiteViewProps extends SkiaGraphiteViewNativeProps {
   ref?: React.Ref<SkiaGraphiteViewRef>;
 }
 
+// The layout is known synchronously on the new architecture;
+// getBoundingClientRect became stable in React Native 0.83. On the web the
+// view measures itself (see SkiaView.web).
+const measureLayout = (view: unknown) => {
+  if (Platform.OS === "web") {
+    return { width: 0, height: 0 };
+  }
+  const host = view as {
+    getBoundingClientRect?: () => { width: number; height: number };
+    unstable_getBoundingClientRect: () => { width: number; height: number };
+  };
+  return host.getBoundingClientRect
+    ? host.getBoundingClientRect()
+    : host.unstable_getBoundingClientRect();
+};
+
 /**
- * A view presenting frames recorded with Skia Graphite. Requires the Graphite
- * backend (install-skia-graphite); with the default backend it renders
- * nothing. See {@link SkGraphiteContext}.
+ * A view whose frames are recorded from JavaScript, on any runtime, through
+ * the context of its ref. See {@link SkGraphiteContext}.
  */
 export const SkiaGraphiteView = ({
-  debug = false,
   opaque = false,
   highBitDepth = false,
+  android,
   ref,
   ...viewProps
 }: SkiaGraphiteViewProps) => {
   const nativeId = useMemo(() => SkiaViewNativeId.current++, []);
   const viewRef =
-    useRef<React.ComponentRef<typeof SkiaGraphiteViewNativeComponent>>(null);
+    useRef<React.ComponentRef<typeof SkiaViewNativeComponent>>(null);
   useImperativeHandle(
     ref,
     () => ({
       getNativeId: () => nativeId,
       getContext: () => {
         assertSkiaViewApi();
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const view = viewRef.current as any;
+        const view = viewRef.current;
         if (!view) {
           throw new Error(
             "SkiaGraphiteView: getContext() was called before the view was mounted."
           );
         }
-        // The layout is known synchronously on the new architecture;
-        // getBoundingClientRect became stable in React Native 0.83.
-        const size =
-          "getBoundingClientRect" in view
-            ? view.getBoundingClientRect()
-            : view.unstable_getBoundingClientRect();
+        const size = measureLayout(view);
         return SkiaViewApi.makeGraphiteContext(
           nativeId,
           size.width,
@@ -66,13 +77,13 @@ export const SkiaGraphiteView = ({
     [nativeId, opaque, highBitDepth]
   );
   return (
-    <SkiaGraphiteViewNativeComponent
+    <SkiaViewNativeComponent
       ref={viewRef}
       collapsable={false}
       nativeID={`${nativeId}`}
-      debug={debug}
       opaque={opaque}
       highBitDepth={highBitDepth}
+      {...androidNativeProps(android)}
       {...viewProps}
     />
   );

package/src/views/SkiaPictureView.tsx

@@ -1,19 +1,21 @@
 import React from "react";
 
 import type { SkRect } from "../skia/types";
-import SkiaPictureViewNativeComponent from "../specs/SkiaPictureViewNativeComponent";
+import SkiaViewNativeComponent from "../specs/SkiaViewNativeComponent";
 
 import { SkiaViewApi } from "./api";
+import { androidNativeProps } from "./android";
 import type { SkiaPictureViewNativeProps } from "./types";
 import { SkiaViewNativeId } from "./SkiaViewNativeId";
 
-const NativeSkiaPictureView = SkiaPictureViewNativeComponent;
-
 interface SkiaPictureViewProps extends SkiaPictureViewNativeProps {
   mode?: "default" | "continuous";
-  androidWarmup?: boolean;
 }
 
+/**
+ * A view showing a picture. The picture is handed to the native view, which
+ * records it once (and again on every redraw) for its surface.
+ */
 export class SkiaPictureView extends React.Component<SkiaPictureViewProps> {
   private requestId = 0;
 
@@ -76,21 +78,20 @@ export class SkiaPictureView extends React.Component<SkiaPictureViewProps> {
 
   render() {
     const {
-      mode,
-      debug = false,
+      mode: _mode,
+      picture: _picture,
       opaque = false,
       highBitDepth = false,
-      androidWarmup = false,
+      android,
       ...viewProps
     } = this.props;
     return (
-      <NativeSkiaPictureView
+      <SkiaViewNativeComponent
         collapsable={false}
         nativeID={`${this._nativeId}`}
-        debug={debug}
         opaque={opaque}
         highBitDepth={highBitDepth}
-        androidWarmup={androidWarmup}
+        {...androidNativeProps(android)}
         {...viewProps}
       />
     );