fix(🪐): high bit depth for onscreen surfaces (#409)

Author: wcandillon

apps/docs/app/(content)/api/layout.tsx

@@ -14,6 +14,7 @@ export default function Layout({ children }: { children: ReactNode }) {
     <DocsLayout
       tree={apiSource.getPageTree()}
       {...sideBarOptions()}
+      searchToggle={{ enabled: false }}
       sidebar={docsLayoutSidebarOptions()}
       containerProps={{
         className: `${docsLayoutContainerClassName} ${apiReferenceSidebarWidthClassName}`,

apps/docs/app/(home)/page.tsx

@@ -47,7 +47,7 @@ export default function HomePage() {
           }`}
         >
           Powered by Dawn.<br />
-          Runs on iOS, Android, macOS, visionOS, and Web.
+          Built for iOS, Android, macOS, visionOS, and Web.
         </p>
         <div className="pointer-events-auto mt-10 flex flex-wrap items-center justify-center gap-3">
           <Link

apps/docs/content/api/gpu-device-extensions.mdx

@@ -121,3 +121,21 @@ device.queue.copyExternalImageToTexture(
 );
 bitmap.close();
 ```
+
+## getPreferredHighBitDepthCanvasFormat
+
+Returns the canvas texture format most likely to reach the display with more than 8 bits per channel on the current platform: `"rgba16float"` on iOS, `"rgb10a2unorm"` on Android.
+Unlike `getPreferredCanvasFormat()`, this helper is not part of the WebGPU standard, so it is exported as a regular function instead of a `navigator.gpu` method.
+
+```tsx twoslash
+import type { RNCanvasContext } from "react-native-webgpu";
+import { getPreferredHighBitDepthCanvasFormat } from "react-native-webgpu";
+declare const context: RNCanvasContext;
+declare const device: GPUDevice;
+// ---cut---
+const format = getPreferredHighBitDepthCanvasFormat();
+context.configure({ device, format, alphaMode: "opaque" });
+```
+
+The values you write stay sRGB-encoded exactly like on an 8-bit canvas: this is about precision, not HDR (no extended range).
+See [High bit depth](/docs/getting-started/native-api#high-bit-depth) for the platform details and banding comparison.

apps/docs/content/docs/getting-started/native-api.mdx

@@ -57,6 +57,25 @@ device.queue.copyExternalImageToTexture(
 
 See [`copyExternalImageToTexture`](https://developer.mozilla.org/en-US/docs/Web/API/GPUQueue/copyExternalImageToTexture) on MDN.
 
+## High bit depth
+
+By default a canvas is configured with an 8-bit format (`bgra8unorm` or `rgba8unorm`, the value returned by `navigator.gpu.getPreferredCanvasFormat()` depending on the platform).
+With only 256 levels per channel, subtle gradients quantize into visible bands, especially in dark tones and on OLED displays.
+
+To configure the canvas with a higher-precision format, use `getPreferredHighBitDepthCanvasFormat()` (currently it will return `rgba16float` on iOS and `rgb10a2unorm` on Android):
+
+```tsx twoslash
+import type { RNCanvasContext } from "react-native-webgpu";
+import { getPreferredHighBitDepthCanvasFormat } from "react-native-webgpu";
+declare const context: RNCanvasContext;
+declare const device: GPUDevice;
+// ---cut---
+// "rgba16float" on iOS, "rgb10a2unorm" on Android
+const format = getPreferredHighBitDepthCanvasFormat();
+
+context.configure({ device, format, alphaMode: "opaque" });
+```
+
 ## Native textures
 
 Beyond the standard API, react-native-webgpu exposes Dawn's native surface interop so you can sample camera and video frames with zero copies through the CPU:

apps/docs/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/docs/tsconfig.tsbuildinfo

@@ -1924,7 +1924,7 @@ PODS:
     - ReactCommon/turbomodule/core
     - SocketRocket
     - Yoga
-  - react-native-webgpu (0.5.15):
+  - react-native-webgpu (0.0.0):
     - boost
     - DoubleConversion
     - fast_float
@@ -3074,7 +3074,7 @@ SPEC CHECKSUMS:
   React-microtasksnativemodule: 75b6604b667d297292345302cc5bfb6b6aeccc1b
   react-native-safe-area-context: c00143b4823773bba23f2f19f85663ae89ceb460
   react-native-skia: fc73e9bdc46ebb420a98c9c2be29fee80f565e79
-  react-native-webgpu: 7a604a7936a2e3fdc93bd48813bcba0165ada8cc
+  react-native-webgpu: 3eb051bebe030f328725fc318a147599c4628e4e
   React-NativeModulesApple: 879fbdc5dcff7136abceb7880fe8a2022a1bd7c3
   React-oscompat: 93b5535ea7f7dff46aaee4f78309a70979bdde9d
   React-perflogger: 5536d2df3d18fe0920263466f7b46a56351c0510

apps/example/ios/Podfile.lock

@@ -41,7 +41,7 @@
     "react-native-vision-camera": "5.0.10",
     "react-native-vision-camera-worklets": "5.0.10",
     "react-native-web": "^0.21.2",
-    "react-native-webgpu": "*",
+    "react-native-webgpu": "workspace:*",
     "react-native-worklets": "0.8.3",
     "teapot": "^1.0.0",
     "three": "0.184.0",

apps/example/package.json

@@ -39,6 +39,7 @@ import { StorageBufferVertices } from "./StorageBufferVertices";
 import { SharedTextureMemory } from "./SharedTextureMemory";
 import { ImportExternalTexture } from "./ImportExternalTexture";
 import { VisionCamera } from "./VisionCamera";
+import { SixteenBitTextures } from "./SixteenBitTextures";
 
 // The two lines below are needed by three.js
 import "fast-text-encoding";
@@ -109,6 +110,10 @@ function App() {
             component={ImportExternalTexture}
           />
           <Stack.Screen name="VisionCamera" component={VisionCamera} />
+          <Stack.Screen
+            name="SixteenBitTextures"
+            component={SixteenBitTextures}
+          />
         </Stack.Navigator>
       </NavigationContainer>
     </GestureHandlerRootView>

apps/example/src/App.tsx

@@ -139,6 +139,10 @@ export const examples = [
     screen: "VisionCamera",
     title: "📷 VisionCamera integration",
   },
+  {
+    screen: "SixteenBitTextures",
+    title: "🎨 16bits Textures",
+  },
 ];
 
 const styles = StyleSheet.create({