@symbiote-native/gl 0.0.0-stage → 0.0.0

package/src/core/gl-view.ts

@@ -0,0 +1,143 @@
+import {
+  Platform,
+  UnavailabilityError,
+  requireNativeViewManager,
+} from 'expo-modules-core';
+import { el } from '@symbiote-native/components';
+import type { IDescriptor } from '@symbiote-native/components';
+import {
+  defineExpoNativeView,
+  getNativeTag,
+  isDevBuild,
+  isSymbioteNode,
+} from '@symbiote-native/engine';
+import type { ISymbioteEvent, ISymbioteNode } from '@symbiote-native/engine';
+import { GL_MODULE_NAME, GL_PACKAGE_NAME } from './constants';
+import { getGl, takeSnapshotAsync, unregisterGLContext } from './gl-context';
+import { glNativeModule } from './native-module';
+import type {
+  IGLNodeOrTag,
+  IGLObject,
+  IGLSnapshotOptions,
+  IGLViewHandle,
+  IGLViewProps,
+} from './types';
+
+// Registered on render: a barrel side effect is lost in a release build
+const glView = defineExpoNativeView(requireNativeViewManager, GL_MODULE_NAME);
+
+export const glViewName = glView.name;
+
+export const ensureGLViewRegistered = glView.ensureRegistered;
+
+const DEFAULT_MSAA_SAMPLES = 4;
+
+export type IGLView = {
+  handle: IGLViewHandle;
+  /** `null` means the view cannot register and the caller renders nothing */
+  render(props: object): IDescriptor | null;
+  /** Forgets the context of the surface, called when the view unmounts */
+  dispose(): void;
+};
+
+type IGetNode = () => ISymbioteNode | null | undefined;
+
+function isSurfaceCreated(value: unknown): value is { exglCtxId: number } {
+  return typeof Reflect.get(Object(value), 'exglCtxId') === 'number';
+}
+
+function isContextCallback(value: unknown): value is IGLViewProps['onContextCreate'] {
+  return typeof value === 'function';
+}
+
+// Adapters hand over the props they hold, a missing callback is a view nobody listens to
+function toViewProps(props: object): IGLViewProps {
+  const onContextCreate: unknown = Reflect.get(props, 'onContextCreate');
+  return {
+    ...props,
+    onContextCreate: isContextCallback(onContextCreate) ? onContextCreate : () => undefined,
+  };
+}
+
+function nativeTagOf(camera: IGLNodeOrTag): number {
+  const tag = isSymbioteNode(camera) ? getNativeTag(camera) : camera;
+  if (typeof tag !== 'number') throw new Error('The camera view has no native tag yet');
+  return tag;
+}
+
+/** One per mounted view, `getNode` is kept for the shape the adapters share */
+export function createGLView(_getNode: IGetNode): IGLView {
+  let exglCtxId: number | undefined;
+  let latestProps: IGLViewProps | undefined;
+  let hasWorkletSupport: boolean | undefined;
+
+  const onSurfaceCreate = (event: ISymbioteEvent): void => {
+    if (!isSurfaceCreated(event.nativeEvent)) return;
+    exglCtxId = event.nativeEvent.exglCtxId;
+    latestProps?.onContextCreate(getGl(exglCtxId));
+  };
+
+  function warnOnWorkletChange(enabled: boolean): void {
+    if (hasWorkletSupport !== undefined && hasWorkletSupport !== enabled) {
+      console.warn('Updating prop enableExperimentalWorkletSupport is not supported');
+    }
+    hasWorkletSupport = enabled;
+  }
+
+  const handle: IGLViewHandle = {
+    get exglCtxId() {
+      return exglCtxId;
+    },
+    async createCameraTextureAsync(camera) {
+      if (!glNativeModule.createCameraTextureAsync) {
+        throw new UnavailabilityError(GL_PACKAGE_NAME, 'createCameraTextureAsync');
+      }
+      if (!exglCtxId) throw new Error("GLView's surface is not created yet!");
+      const { exglObjId } = await glNativeModule.createCameraTextureAsync(
+        exglCtxId,
+        nativeTagOf(camera),
+      );
+      const texture: WebGLTexture = { id: exglObjId };
+      return texture;
+    },
+    async destroyObjectAsync(glObject: IGLObject) {
+      if (!glNativeModule.destroyObjectAsync) {
+        throw new UnavailabilityError(GL_PACKAGE_NAME, 'destroyObjectAsync');
+      }
+      return glNativeModule.destroyObjectAsync(glObject.id);
+    },
+    takeSnapshotAsync: (options?: IGLSnapshotOptions) => takeSnapshotAsync(exglCtxId, options),
+  };
+
+  return {
+    handle,
+    dispose: () => {
+      if (exglCtxId) unregisterGLContext(exglCtxId);
+    },
+    render: props => {
+      if (!ensureGLViewRegistered()) {
+        if (isDevBuild()) console.warn("'GLView' is not available.");
+        return null;
+      }
+      latestProps = toViewProps(props);
+      const {
+        onContextCreate,
+        msaaSamples = DEFAULT_MSAA_SAMPLES,
+        enableExperimentalWorkletSupport = false,
+        ...viewProps
+      } = latestProps;
+      warnOnWorkletChange(enableExperimentalWorkletSupport);
+      return el('view', viewProps, [
+        el(glViewName(), {
+          style: {
+            flex: 1,
+            ...Platform.select({ ios: { backgroundColor: 'transparent' }, default: {} }),
+          },
+          onSurfaceCreate,
+          enableExperimentalWorkletSupport,
+          msaaSamples: Platform.select({ ios: msaaSamples, default: undefined }),
+        }),
+      ]);
+    },
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,21 @@
+export { GL_MODULE_NAME } from './constants';
+export {
+  createContextAsync,
+  destroyContextAsync,
+  getGl,
+  getWorkletContext,
+  takeSnapshotAsync,
+} from './gl-context';
+export { configureLogging } from './gl-utils';
+export { createGLView, ensureGLViewRegistered, glViewName, type IGLView } from './gl-view';
+export { GLLoggingOption } from './types';
+export type {
+  IExpoWebGLRenderingContext,
+  IGLNodeOrTag,
+  IGLObject,
+  IGLSnapshot,
+  IGLSnapshotOptions,
+  IGLSurfaceCreateEvent,
+  IGLViewHandle,
+  IGLViewProps,
+} from './types';

package/src/core/native-module.ts

@@ -0,0 +1,18 @@
+import { requireNativeModule } from 'expo-modules-core';
+import { GL_MODULE_NAME } from './constants';
+import type { IGLSnapshot, IGLSnapshotOptions } from './types';
+
+export type INativeGLModule = {
+  createContextAsync(): Promise<{ exglCtxId: number }>;
+  destroyContextAsync(exglCtxId: number): Promise<boolean>;
+  takeSnapshotAsync(exglCtxId: number, options: IGLSnapshotOptions): Promise<IGLSnapshot>;
+  /** Absent where there is no camera texture support */
+  createCameraTextureAsync?(
+    exglCtxId: number,
+    cameraTag: number,
+  ): Promise<{ exglObjId: number }>;
+  /** Absent where objects cannot be destroyed one by one */
+  destroyObjectAsync?(exglObjId: number): Promise<boolean>;
+};
+
+export const glNativeModule = requireNativeModule<INativeGLModule>(GL_MODULE_NAME);

package/src/core/types.ts

@@ -0,0 +1,95 @@
+import type {
+  IAccessibilityProps,
+  IAriaProps,
+  IResponderProps,
+} from '@symbiote-native/components';
+import type {
+  IStyleProp,
+  ISymbioteEvent,
+  ISymbioteNode,
+  IViewStyle,
+} from '@symbiote-native/engine';
+
+export type IGLObject = {
+  id: number;
+};
+
+export type IGLSurfaceCreateEvent = {
+  nativeEvent: {
+    exglCtxId: number;
+  };
+};
+
+export type IGLSnapshotOptions = {
+  /** @default false */
+  flip?: boolean;
+  /** Defaults to the framebuffer shown in the view, or the current one of a headless context */
+  framebuffer?: WebGLFramebuffer;
+  /** Passed to `glReadPixels` */
+  rect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** PNG is lossless but slower, iOS writes a PNG instead of WebP. @default 'jpeg' */
+  format?: 'jpeg' | 'png' | 'webp';
+  /** From `0` (most compressed) to `1.0` (none). @default 1.0 */
+  compress?: number;
+};
+
+export type IGLSnapshot = {
+  uri: string | Blob | null;
+  /** Same as `uri`, which makes a snapshot usable in `texImage2D` */
+  localUri: string;
+  width: number;
+  height: number;
+};
+
+export type IExpoWebGLRenderingContext = WebGL2RenderingContext & {
+  contextId: number;
+  endFrameEXP(): void;
+  flushEXP(): void;
+  __expoSetLogging(option: GLLoggingOption): void;
+};
+
+/** A native tag, or the host node of a view such as a camera */
+export type IGLNodeOrTag = number | ISymbioteNode | null;
+
+export type IGLViewProps = IAccessibilityProps &
+  IAriaProps &
+  IResponderProps & {
+  style?: IStyleProp<IViewStyle>;
+  testID?: string;
+  nativeID?: string;
+  onLayout?: (event: ISymbioteEvent) => void;
+  /** Called with the context once the surface exists */
+  onContextCreate(gl: IExpoWebGLRenderingContext): void;
+  /** Multisampling, `0` turns it off. @default 4 @platform ios */
+  msaaSamples?: number;
+  /** Lets the Reanimated worklet thread use the `gl` object. @default false */
+  enableExperimentalWorkletSupport?: boolean;
+};
+
+export enum GLLoggingOption {
+  DISABLED = 0,
+  /** Logs calls, their parameters and results */
+  METHOD_CALLS = 1,
+  /** Calls `getError` after each call, which blocks and slows drawing down */
+  GET_ERRORS = 2,
+  /** Prints the name of the constant a numeric parameter holds */
+  RESOLVE_CONSTANTS = 4,
+  /** Cuts long strings such as shaders */
+  TRUNCATE_STRINGS = 8,
+  ALL = METHOD_CALLS | GET_ERRORS | RESOLVE_CONSTANTS | TRUNCATE_STRINGS,
+}
+
+/** What a ref to the view hands out */
+export type IGLViewHandle = {
+  /** The id of the context of the view, `undefined` until the surface exists */
+  readonly exglCtxId: number | undefined;
+  createCameraTextureAsync(camera: IGLNodeOrTag): Promise<WebGLTexture>;
+  destroyObjectAsync(glObject: IGLObject): Promise<boolean>;
+  /** A snapshot of the context of this view */
+  takeSnapshotAsync(options?: IGLSnapshotOptions): Promise<IGLSnapshot>;
+};

package/src/core/worklet-context-manager.ts

@@ -0,0 +1,42 @@
+import { GL_CONTEXTS_GLOBAL } from './constants';
+import type { IExpoWebGLRenderingContext } from './types';
+
+export type IWorkletContextManager = {
+  getContext(contextId: number): IExpoWebGLRenderingContext | undefined;
+  unregister?(contextId: number): void;
+};
+
+type IRunOnUI = (worklet: (contextId: number) => void) => (contextId: number) => void;
+
+function isRunOnUI(value: unknown): value is IRunOnUI {
+  return typeof value === 'function';
+}
+
+// Reanimated stays optional, and an import of it in a try block in the module that also holds the
+// view breaks with `inlineRequires`, so the manager lives in its own file
+export function createWorkletContextManager(): IWorkletContextManager {
+  try {
+    // Reanimated has to load before any workletized code is created
+    const reanimated: unknown = require('react-native-reanimated');
+    const runOnUI = Reflect.get(Object(reanimated), 'runOnUI');
+    if (!isRunOnUI(runOnUI)) throw new Error('react-native-reanimated has no runOnUI');
+    return {
+      getContext: contextId => {
+        'worklet';
+        return Reflect.get(Object(Reflect.get(globalThis, GL_CONTEXTS_GLOBAL)), String(contextId));
+      },
+      unregister: contextId => {
+        runOnUI(id => {
+          'worklet';
+          Reflect.deleteProperty(Object(Reflect.get(globalThis, GL_CONTEXTS_GLOBAL)), String(id));
+        })(contextId);
+      },
+    };
+  } catch {
+    return {
+      getContext: () => {
+        throw new Error('Worklet runtime is not available');
+      },
+    };
+  }
+}

package/src/react/gl-view.ts

@@ -0,0 +1,14 @@
+import type { ReactElement, Ref } from 'react';
+import { useNativeViewController } from '@symbiote-native/react';
+import { createGLView } from '../core';
+import type { IGLViewHandle, IGLViewProps } from '../core';
+
+export type IGLViewReactProps = IGLViewProps & {
+  ref?: Ref<IGLViewHandle>;
+  className?: string;
+};
+
+/** React twin of `expo-gl`'s `GLView` */
+export function GLView({ ref, ...props }: IGLViewReactProps): ReactElement | null {
+  return useNativeViewController(ref, createGLView, props);
+}

package/src/react/index.ts

@@ -0,0 +1,5 @@
+// @symbiote-native/gl/react: a GLView that gives a WebGL context to draw into, on a shared core
+
+export { GLView } from './gl-view';
+export type { IGLViewReactProps } from './gl-view';
+export * from '../core';

package/src/solid/gl-view.ts

@@ -0,0 +1,6 @@
+import { defineNativeViewComponent } from '@symbiote-native/solid';
+import { createGLView } from '../core';
+import type { IGLViewHandle, IGLViewProps } from '../core';
+
+/** Solid twin of `expo-gl`'s `GLView`, `ref` gets the handle of the view */
+export const GLView = defineNativeViewComponent<IGLViewHandle, IGLViewProps>(createGLView);

package/src/solid/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/gl/solid: a GLView that gives a WebGL context to draw into, on a shared core
+
+export { GLView } from './gl-view';
+export * from '../core';

package/src/svelte/gl-view.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import DescriptorHost from '@symbiote-native/svelte/descriptor-host';
+  import { useNativeViewController } from '@symbiote-native/svelte/runes/use-native-view-controller';
+  import { createGLView } from '../core';
+  import type { IGLViewProps } from '../core';
+
+  const props: IGLViewProps = $props();
+  const view = useNativeViewController(createGLView, () => ({ ...props }));
+
+  // The functions of the view are instance members, `bind:this` reaches them
+  export const createCameraTextureAsync = view.handle.createCameraTextureAsync;
+  export const destroyObjectAsync = view.handle.destroyObjectAsync;
+  export const takeSnapshotAsync = view.handle.takeSnapshotAsync;
+  export const getContextId = (): number | undefined => view.handle.exglCtxId;
+</script>
+
+{#if view.descriptor}
+  <DescriptorHost descriptor={view.descriptor} />
+{/if}

package/src/svelte/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/gl/svelte: a GLView that gives a WebGL context to draw into, on a shared core
+
+export { default as GLView } from './gl-view.svelte';
+export * from '../core';

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,3 @@
+// Pulls in svelte's ambient globals ($state/$effect/...) for this package's tsc program
+// This package has no value import from 'svelte', so a triple-slash reference does it explicitly
+/// <reference types="svelte" />

package/src/svelte/svelte-compile.test-helper.ts

@@ -0,0 +1,6 @@
+// Re-exports the existing harness instead of another copy
+export {
+  createSvelteHarness,
+  loadComponent,
+  type ISvelteHarness,
+} from '../../../sqlite/src/svelte/svelte-compile.test-helper';

package/src/vue/gl-view.ts

@@ -0,0 +1,5 @@
+import { defineNativeViewComponent } from '@symbiote-native/vue';
+import { createGLView } from '../core';
+
+/** Vue twin of `expo-gl`'s `GLView`, `ref` gets the handle of the view */
+export const GLView = defineNativeViewComponent('GLView', createGLView);

package/src/vue/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/gl/vue: a GLView that gives a WebGL context to draw into, on a shared core
+
+export { GLView } from './gl-view';
+export * from '../core';