@typegpu/react 0.10.0-alpha.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Software Mansion <swmansion.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+<div align="center">
+
+# @typegpu/react
+
+🚧 **Under Construction** 🚧
+
+</div>
+
+# Basic usage
+
+```ts
+import { d, common } from 'typegpu';
+import { hsvToRgb } from '@typegpu/color';
+import { useFrame, useRoot, useUniformValue, useMirroredUniform, useConfigureContext } from '@typegpu/react';
+
+const App = (props: Props) => {
+  const time = useUniformValue(d.f32, 0);
+  const color = useMirroredUniform(d.vec3f, props.color);
+
+  const root = useRoot();
+  const renderPipeline = useMemo(() => root.createRenderPipeline({
+    vertex: common.fullScreenTriangle,
+    // Runs each frame on the GPU 🌈
+    fragment: ({ uv }) => {
+      'use gpu';
+      return hsvToRgb(time.$, uv.x, uv.y) * color.$;
+    },
+  }), [root, time, color]);
+  
+  const { canvasRefCallback, ctxRef } = useConfigureContext();
+
+  // Runs each frame on the CPU 🤖
+  useFrame(({ elapsedSeconds }) => {
+    if (!ctxRef.current) return;
+    
+    time.value = elapsedSeconds;
+    renderPipeline.withColorAttachment({ view: ctxRef.current }).draw(3);
+  });
+
+  return <canvas ref={canvasRefCallback} />;
+};
+```

package/index.d.mts

@@ -0,0 +1,92 @@
+import { LayoutEntryToInput, TgpuBindGroup, TgpuBindGroupLayout, TgpuBuffer, TgpuMutable, TgpuRoot, ValidateBufferSchema, ValidateStorageSchema, ValidateUniformSchema, d } from "typegpu";
+import * as d$1 from "typegpu/data";
+
+//#region src/root-context.d.ts
+declare function useRoot(): TgpuRoot;
+//#endregion
+//#region src/use-frame.d.ts
+interface FrameCtx {
+  /**
+   * Time elapsed since the last frame
+   */
+  readonly deltaSeconds: number;
+  /**
+   * Time elapsed since the mounting of this hook
+   */
+  readonly elapsedSeconds: number;
+}
+declare function useFrame(cb: (ctx: FrameCtx) => void): void;
+//#endregion
+//#region src/use-mutable.d.ts
+declare function useMutable<TSchema extends d.AnyWgslData>(schema: ValidateStorageSchema<TSchema>, initialValue?: d.Infer<TSchema>): TgpuMutable<TSchema>;
+//#endregion
+//#region src/symbols.d.ts
+declare const $buffer: unique symbol;
+//#endregion
+//#region src/use-uniform-value.d.ts
+interface UniformValue<TSchema extends d$1.BaseData, TValue extends d$1.Infer<TSchema>> {
+  schema: TSchema;
+  value: TValue;
+  readonly $: d$1.InferGPU<TSchema>;
+  readonly [$buffer]: TgpuBuffer<TSchema>;
+}
+declare function useUniformValue<TSchema extends d$1.AnyWgslData, TValue extends d$1.Infer<TSchema>>(schema: ValidateUniformSchema<TSchema>, initialValue?: TValue): UniformValue<TSchema, TValue>;
+//#endregion
+//#region src/use-buffer.d.ts
+interface UseBufferOptions<TSchema extends d$1.AnyData> {
+  initial?: (() => d$1.Infer<NoInfer<TSchema>>) | d$1.Infer<NoInfer<TSchema>>;
+  onInit?: (buffer: TgpuBuffer<TSchema>) => void;
+}
+declare function useBuffer<TSchema extends d$1.AnyData>(schema: ValidateBufferSchema<TSchema>, options?: UseBufferOptions<TSchema>): TgpuBuffer<TSchema>;
+//#endregion
+//#region src/use-configure-context.d.ts
+interface UseConfigureContextOptions {
+  /**
+   * @default true
+   */
+  autoResize?: boolean;
+}
+interface UseConfigureContextResult {
+  canvasRefCallback: React.RefCallback<HTMLCanvasElement>;
+  canvasRef: Readonly<React.Ref<HTMLCanvasElement | null>>;
+  ctxRef: React.RefObject<GPUCanvasContext | null>;
+}
+declare function useConfigureContext(options?: UseConfigureContextOptions): UseConfigureContextResult;
+//#endregion
+//#region src/use-bind-group.d.ts
+type ExtractInputFromEntries<T extends TgpuBindGroupLayout['entries']> = { [Key in keyof T]: T[Key] extends {
+  uniform: d.BaseData;
+} ? LayoutEntryToInput<T[Key]> | UniformValue<T[Key]['uniform'], d.Infer<T[Key]['uniform']>> : LayoutEntryToInput<T[Key]> };
+/**
+ * Creates a group of resources that can be bound to a shader based on a specified layout.
+ *
+ * @remarks
+ * Typed wrapper around a GPUBindGroup.
+ *
+ * @example
+ * ```ts
+ * const fooLayout = tgpu.bindGroupLayout({
+ *  foo: { uniform: d.vec3f },
+ *  bar: { texture: 'float' },
+ * });
+ *
+ * function App() {
+ *   const fooBuffer = useBuffer(...);
+ *   const barTexture = useTexture(...);
+ *
+ *   const fooBindGroup = useBindGroup(fooLayout, {
+ *    foo: fooBuffer,
+ *    bar: barTexture,
+ *   });
+ *
+ *   // ...
+ * }
+ * ```
+ *
+ * @param layout Layout describing the bind group to be created.
+ * @param entries A record with values being the resources populating the bind group
+ * and keys being their associated names, matching the layout keys.
+ */
+declare function useBindGroup<TLayout extends TgpuBindGroupLayout>(layout: TLayout, entries: ExtractInputFromEntries<TLayout['entries']>): TgpuBindGroup<TLayout['entries']>;
+//#endregion
+export { type UniformValue, useBindGroup, useBuffer, useConfigureContext, useFrame, useMutable, useRoot, useUniformValue };

package/index.mjs

@@ -0,0 +1,269 @@
+import React, { createContext, use, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import tgpu from "typegpu";
+import "react/jsx-runtime";
+
+//#region src/root-context.tsx
+var RootContext = class {
+	#root;
+	#rootPromise;
+	initOrGetRoot() {
+		if (this.#root) return this.#root;
+		if (!this.#rootPromise) this.#rootPromise = tgpu.init().then((root) => {
+			this.#root = root;
+			return root;
+		});
+		return this.#rootPromise;
+	}
+};
+/**
+* Used in case no provider is mounted
+*/
+const globalRootContextValue = new RootContext();
+const rootContext = createContext(null);
+function useRoot() {
+	const maybeRoot = (useContext(rootContext) ?? globalRootContextValue).initOrGetRoot();
+	return maybeRoot instanceof Promise ? use(maybeRoot) : maybeRoot;
+}
+
+//#endregion
+//#region src/use-frame.ts
+function useFrame(cb) {
+	const latestCb = useRef(cb);
+	useEffect(() => {
+		latestCb.current = cb;
+	}, [cb]);
+	useEffect(() => {
+		let frameId;
+		let startTime;
+		let lastTime;
+		const loop = () => {
+			frameId = requestAnimationFrame(loop);
+			const now = performance.now();
+			if (lastTime === void 0 || startTime === void 0) {
+				startTime = now;
+				lastTime = now;
+			}
+			latestCb.current({
+				deltaSeconds: (now - lastTime) / 1e3,
+				elapsedSeconds: (now - startTime) / 1e3
+			});
+			lastTime = now;
+		};
+		loop();
+		return () => {
+			if (frameId !== void 0) cancelAnimationFrame(frameId);
+		};
+	}, []);
+}
+
+//#endregion
+//#region src/use-mutable.ts
+function useMutable(schema, initialValue) {
+	const root = useRoot();
+	const [mutable] = useState(() => {
+		return root.createMutable(schema, initialValue);
+	});
+	const cleanupRef = useRef(null);
+	useEffect(() => {
+		if (cleanupRef.current) clearTimeout(cleanupRef.current);
+		return () => {
+			cleanupRef.current = setTimeout(() => {
+				mutable.buffer.destroy();
+			}, 200);
+		};
+	}, [mutable]);
+	return mutable;
+}
+
+//#endregion
+//#region package.json
+var version = "0.10.0-alpha.1";
+
+//#endregion
+//#region src/symbols.ts
+const $buffer = Symbol(`@typegpu/react:${version}:$buffer`);
+
+//#endregion
+//#region src/use-uniform-value.ts
+function initialValueFromSchema(schema) {
+	if (typeof schema !== "function") throw new Error("Cannot use a non-callable schema with `useUniformValue`");
+	return schema();
+}
+function useUniformValue(schema, initialValue) {
+	const root = useRoot();
+	const [uniformBuffer] = useState(() => {
+		return root.createUniform(schema, initialValue);
+	});
+	const cleanupRef = useRef(null);
+	useEffect(() => {
+		if (cleanupRef.current) clearTimeout(cleanupRef.current);
+		return () => {
+			cleanupRef.current = setTimeout(() => {
+				uniformBuffer.buffer.destroy();
+			}, 200);
+		};
+	}, [uniformBuffer]);
+	return useMemo(() => {
+		let currentValue = initialValue ?? initialValueFromSchema(schema);
+		return {
+			schema,
+			[$buffer]: uniformBuffer.buffer,
+			get value() {
+				return currentValue;
+			},
+			set value(newValue) {
+				currentValue = newValue;
+				uniformBuffer.write(newValue);
+			},
+			get $() {
+				return uniformBuffer.$;
+			}
+		};
+	}, []);
+}
+
+//#endregion
+//#region src/use-buffer.ts
+function useBuffer(schema, options) {
+	const { initial, onInit } = options ?? {};
+	const root = useRoot();
+	const [buffer] = useState(() => {
+		const buffer = root.createBuffer(schema, typeof initial === "function" ? initial() : initial);
+		onInit?.(buffer);
+		return buffer;
+	});
+	const cleanupRef = useRef(null);
+	useEffect(() => {
+		if (cleanupRef.current) clearTimeout(cleanupRef.current);
+		return () => {
+			cleanupRef.current = setTimeout(() => {
+				buffer.buffer.destroy();
+			}, 200);
+		};
+	}, [buffer]);
+	return buffer;
+}
+
+//#endregion
+//#region src/use-effect-event.ts
+/**
+* Polyfill for the `useEffectEvent` React hook.
+* WARNING: Do not use in the render phase, nor in `useLayoutEffect` calls.
+* @param handler
+* @returns A stable reference of the passed in function.
+*/
+function useEffectEvent(handler) {
+	const handlerRef = useRef(handler);
+	useLayoutEffect(() => {
+		handlerRef.current = handler;
+	});
+	return useCallback((...args) => {
+		const fn = handlerRef.current;
+		return fn(...args);
+	}, []);
+}
+var use_effect_event_default = React.useEffectEvent ?? useEffectEvent;
+
+//#endregion
+//#region src/use-configure-context.ts
+function useConfigureContext(options) {
+	const { autoResize = true } = options ?? {};
+	const root = useRoot();
+	const canvasRef = useRef(null);
+	const resizeEffect = use_effect_event_default((entries) => {
+		const entry = entries[0];
+		if (!canvasRef.current || !entry) return;
+		const el = canvasRef.current;
+		const dpcb = entry.devicePixelContentBoxSize?.[0];
+		const dpr = dpcb ? 1 : window.devicePixelRatio || 1;
+		const box = dpcb ?? (Array.isArray(entry.contentBoxSize) ? entry.contentBoxSize[0] : entry.contentBoxSize);
+		if (!box) return;
+		el.width = Math.round(box.inlineSize * dpr);
+		el.height = Math.round(box.blockSize * dpr);
+	});
+	const ctxRef = useRef(null);
+	const resizeObserverRef = useRef(null);
+	const canvasRefCallback = useCallback((el) => {
+		if (el) {
+			canvasRef.current = el;
+			ctxRef.current = root.configureContext({
+				canvas: el,
+				alphaMode: "premultiplied"
+			});
+			if (autoResize) {
+				if (resizeObserverRef.current) resizeObserverRef.current.disconnect();
+				resizeObserverRef.current = new ResizeObserver(resizeEffect);
+				resizeObserverRef.current.observe(el);
+			}
+		} else {
+			canvasRef.current = null;
+			ctxRef.current = null;
+		}
+		return () => {
+			canvasRef.current = null;
+			ctxRef.current = null;
+			resizeObserverRef.current?.disconnect();
+			resizeObserverRef.current = null;
+		};
+	}, [root]);
+	useEffect(() => {
+		const el = canvasRef.current;
+		if (!el) return;
+		if (resizeObserverRef.current) resizeObserverRef.current.disconnect();
+		if (autoResize) {
+			resizeObserverRef.current = new ResizeObserver(resizeEffect);
+			resizeObserverRef.current.observe(el);
+		}
+		return () => {
+			resizeObserverRef.current?.disconnect();
+			resizeObserverRef.current = null;
+		};
+	}, [resizeEffect]);
+	return {
+		canvasRefCallback,
+		canvasRef,
+		ctxRef
+	};
+}
+
+//#endregion
+//#region src/use-bind-group.ts
+/**
+* Creates a group of resources that can be bound to a shader based on a specified layout.
+*
+* @remarks
+* Typed wrapper around a GPUBindGroup.
+*
+* @example
+* ```ts
+* const fooLayout = tgpu.bindGroupLayout({
+*  foo: { uniform: d.vec3f },
+*  bar: { texture: 'float' },
+* });
+*
+* function App() {
+*   const fooBuffer = useBuffer(...);
+*   const barTexture = useTexture(...);
+*
+*   const fooBindGroup = useBindGroup(fooLayout, {
+*    foo: fooBuffer,
+*    bar: barTexture,
+*   });
+*
+*   // ...
+* }
+* ```
+*
+* @param layout Layout describing the bind group to be created.
+* @param entries A record with values being the resources populating the bind group
+* and keys being their associated names, matching the layout keys.
+*/
+function useBindGroup(layout, entries) {
+	return useRoot().createBindGroup(layout, Object.fromEntries(Object.entries(entries).map(([key, value]) => {
+		if (value[$buffer]) return [key, value[$buffer]];
+		return [key, value];
+	})));
+}
+
+//#endregion
+export { useBindGroup, useBuffer, useConfigureContext, useFrame, useMutable, useRoot, useUniformValue };

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@typegpu/react",
+  "version": "0.10.0-alpha.1",
+  "description": "The best way to integrate TypeGPU into your React app.",
+  "keywords": [],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.mts",
+      "default": "./index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "typegpu": "^0.10.2"
+  },
+  "main": "./index.js",
+  "private": false,
+  "dependencies": {},
+  "scripts": {}
+}