Merge branch 'main' into feat/texture-unwrap

Author: lursz

README.md

@@ -8,11 +8,41 @@
 
 </div>
 
-**TypeGPU** is a TypeScript library that enhances the WebGPU API, allowing
-resource management in a type-safe, declarative way.
+**TypeGPU** is a modular and open-ended toolkit for WebGPU, with advanced type
+inference and the ability to write shaders in TypeScript.
+
+```ts
+const neighborhood = (a: number, r: number) => {
+  'use gpu';
+  return d.vec2f(a - r, a + r);
+};
+
+//
+// #1) Can be called in JS
+//
+const range = neighborhood(1.1, 0.5);
+//    ^? d.v2f
+
+//
+// #2) Used to generate WGSL
+//
+const main = () => {
+  'use gpu';
+  return neighborhood(1.1, 0.5);
+};
+
+const wgsl = tgpu.resolve({ externals: { main } });
+//    ^? string
+
+//
+// #3) Executed on the GPU (generates WGSL underneath)
+//
+root['~unstable']
+  .createGuardedComputePipeline(main)
+  .dispatchThreads();
+```
 
 <div align="center">
-<video width="512" autoplay muted loop playsinline src="https://github.com/user-attachments/assets/5bca716d-477d-44a1-a839-5df0c8d9044c"></video>
 
 <!-- automd:badges color="plum" license name="typegpu" bundlephobia no-npmDownloads -->
 

apps/typegpu-docs/astro.config.mjs

@@ -131,11 +131,6 @@ export default defineConfig({
               label: 'Functions',
               slug: 'fundamentals/functions',
             },
-            {
-              label: 'TGSL',
-              slug: 'fundamentals/tgsl',
-              badge: { text: 'new' },
-            },
             {
               label: 'Pipelines',
               slug: 'fundamentals/pipelines',
@@ -145,6 +140,11 @@ export default defineConfig({
               label: 'Buffers',
               slug: 'fundamentals/buffers',
             },
+            {
+              label: 'Textures',
+              slug: 'fundamentals/textures',
+              badge: { text: 'new' },
+            },
             {
               label: 'Variables',
               slug: 'fundamentals/variables',

apps/typegpu-docs/ec.config.mjs

@@ -8,6 +8,12 @@ export default {
       twoslashOptions: {
         strict: true,
         compilerOptions: { moduleResolution: ts.ModuleResolutionKind.Bundler },
+        extraFiles: {
+          'global.d.ts': `
+            /// <reference lib="dom" />
+            /// <reference types="@webgpu/types" />
+          `,
+        },
       },
     }),
   ],

apps/typegpu-docs/package.json

@@ -41,7 +41,7 @@
     "lz-string": "^1.5.0",
     "monaco-editor": "^0.53.0",
     "morphcharts": "^1.3.2",
-    "motion": "^12.23.7",
+    "motion": "^12.23.24",
     "pathe": "^2.0.3",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -50,10 +50,10 @@
     "remeda": "^2.21.2",
     "sharp": "^0.34.2",
     "starlight-blog": "^0.23.2",
-    "starlight-typedoc": "^0.21.4",
+    "starlight-typedoc": "^0.19.0",
     "tinybench": "^3.1.0",
-    "typedoc": "^0.28.13",
-    "typedoc-plugin-markdown": "^4.3.0",
+    "typedoc": "^0.27.9",
+    "typedoc-plugin-markdown": "4.3.0",
     "typegpu": "workspace:*",
     "typescript": "catalog:types",
     "unplugin-typegpu": "workspace:*",

apps/typegpu-docs/src/components/ExampleCard.tsx

@@ -20,6 +20,7 @@ export function ExampleCard({ example }: { example: Example }) {
                 src={example.thumbnails.large}
                 alt={example.metadata.title}
                 className='h-full w-full object-cover'
+                loading='lazy'
               />
             </picture>
           )

apps/typegpu-docs/src/components/shaderhunt/ChallengesSignupPopover.astro

@@ -36,11 +36,23 @@
       return;
     }
 
+    // Check if URL hash indicates popover should be open
+    if (window.location.hash === '#challenges-signup') {
+      dialogElement?.showModal();
+    }
+
     linkElement.addEventListener('click', (e) => {
       e.preventDefault();
+      window.location.hash = '#challenges-signup';
       dialogElement?.showModal();
      });
 
+    dialogElement.addEventListener('close', () => {
+      if (window.location.hash === '#challenges-signup') {
+        window.location.hash = '';
+      }
+    });
+
     formElement.addEventListener('submit', async (e) => {
       e.preventDefault();
       const formData = new FormData(formElement);

apps/typegpu-docs/src/content/docs/fundamentals/buffers.mdx

@@ -195,7 +195,7 @@ Since the buffer is already created, you are responsible for the buffer's lifecy
 
 ## Writing to a buffer
 
-To write data to a buffer, you can use the `.write(value)` method. The typed schema enables auto-complete as well as static validation of this
+To write data to a buffer from the CPU, you can use the `.write(value)` method. The typed schema enables auto-complete as well as static validation of this
 method's arguments.
 
 ```ts twoslash
@@ -285,7 +285,7 @@ backupParticleBuffer.copyFrom(particleBuffer);
 
 ## Reading from a buffer
 
-To read data from a buffer, you can use the `.read()` method.
+To read data from a buffer on the CPU, you can use the `.read()` method.
 It returns a promise that resolves to the data read from the buffer.
 
 ```ts twoslash
@@ -348,32 +348,25 @@ import * as d from 'typegpu/data';
 
 const root = await tgpu.init();
 // ---cut---
-const pointsBuffer = root
-  .createBuffer(d.arrayOf(d.vec2i, 100))
-  .$usage('storage');
-
-const bindGroupLayout = tgpu.bindGroupLayout({
-  points: { storage: d.arrayOf(d.vec2i, 100), access: 'mutable' },
+const layout = tgpu.bindGroupLayout({
+  points: { storage: d.arrayOf(d.vec2i), access: 'mutable' },
 });
 
-const bindGroup = root
-  .createBindGroup(bindGroupLayout, { points: pointsBuffer });
-
-const mainCompute = tgpu['~unstable'].computeFn({
-  in: { gid: d.builtin.globalInvocationId },
-  workgroupSize: [1],
-})((input) => {
+const pipeline = root['~unstable'].createGuardedComputePipeline((x) => {
+  'use gpu';
   // Access and modify the bound buffer via the layout
-  bindGroupLayout.$.points[input.gid[0]] = d.vec2i(1, 2);
+  layout.$.points[x] = d.vec2i(1, 2);
 });
 
-const pipeline = root['~unstable']
-  .withCompute(mainCompute)
-  .createPipeline();
+const pointsBuffer = root
+  .createBuffer(d.arrayOf(d.vec2i, 100))
+  .$usage('storage');
+
+const bindGroup = root.createBindGroup(layout, {
+  points: pointsBuffer
+});
 
-pipeline
-  .with(bindGroupLayout, bindGroup)
-  .dispatchWorkgroups(100);
+pipeline.with(bindGroup).dispatchThreads(100);
 ```
 
 ### Using fixed resources
@@ -394,18 +387,15 @@ import * as d from 'typegpu/data';
 
 const root = await tgpu.init();
 // ---cut---
-const pointsBuffer = root.createMutable(d.arrayOf(d.vec2i, 100));
+const pointsMutable = root.createMutable(d.arrayOf(d.vec2i, 100));
 
-const mainCompute = tgpu['~unstable'].computeFn({
-  in: { gid: d.builtin.globalInvocationId },
-  workgroupSize: [1],
-})((input) => {
+const pipeline = root['~unstable'].createGuardedComputePipeline((x) => {
+  'use gpu';
   // Access and modify the fixed buffer directly
-  pointsBuffer.$[input.gid[0]] = d.vec2i();
+  pointsMutable.$[x] = d.vec2i();
 });
 
-const pipeline = root['~unstable'].withCompute(mainCompute).createPipeline();
-pipeline.dispatchWorkgroups(100);
+pipeline.dispatchThreads(100);
 ```
 
 TypeGPU automatically generates a "catch-all" bind group and populates it with the fixed resources.

apps/typegpu-docs/src/content/docs/fundamentals/data-schemas.mdx

@@ -343,6 +343,116 @@ const array = ArrayPartialSchema(2)([1.2, 19.29]);
 //    ^?
 ```
 
+## Textures
+
+Texture schemas serve two main purposes:
+ - defining texture views (both fixed and in layouts)
+ - providing argument types for user defined functions
+
+```ts twoslash
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+import * as std from 'typegpu/std';
+
+const root = await tgpu.init();
+const texture = root['~unstable'].createTexture({
+  size: [256, 256],
+  format: 'rgba8unorm',
+}).$usage('sampled', 'storage');
+
+// ---cut---
+const storeOnes = (tex: d.textureStorage2d<'rgba8unorm'>, coords: d.v2u) => {
+  'use gpu';
+  std.textureStore(tex, coords, d.vec4f(1));
+};
+
+const storeOnesShelled = tgpu.fn([d.textureStorage2d('rgba8unorm'), d.vec2u])(
+  (tex, coords) => {
+    std.textureStore(tex, coords, d.vec4f(1));
+  },
+);
+
+const sampledView = texture.createView(d.texture2d(d.f32));
+//     ^?
+
+const storageView = texture.createView(d.textureStorage2d('rgba8unorm', 'read-only'));
+//     ^?
+
+const layout = tgpu.bindGroupLayout({
+  //     ^?
+  sampled: { texture: d.texture2d() },
+  storage: { storageTexture: d.textureStorage2d('rgba8unorm', 'read-only') },
+});
+```
+
+### Sampled Textures
+
+Sampled texture schemas are created using one of the following constructors:
+
+- **`d.texture1d(sampleType?)`** - A 1D texture
+- **`d.texture2d(sampleType?)`** - A 2D texture
+- **`d.texture2dArray(sampleType?)`** - A 2D array texture
+- **`d.texture3d(sampleType?)`** - A 3D texture
+- **`d.textureCube(sampleType?)`** - A cube texture
+- **`d.textureCubeArray(sampleType?)`** - A cube array texture
+- **`d.textureMultisampled2d(sampleType?)`** - A 2D multisampled texture
+
+The `sampleType` parameter can be `d.f32`, `d.i32`, or `d.u32`, determining how the texture data will be interpreted. If omitted, it defaults to `d.f32`.
+
+```ts twoslash
+import * as d from 'typegpu/data';
+// ---cut---
+const tex1 = d.texture2d(d.f32); // float texture (default)
+//    ^?
+
+const tex2 = d.texture2d(d.u32); // unsigned integer texture
+//    ^?
+
+const tex3 = d.texture2dArray(); // defaults to f32
+//    ^?
+```
+
+#### Depth Textures
+
+For depth comparison operations, TypeGPU provides specialized depth texture schemas:
+
+- **`d.textureDepth2d()`** - A 2D depth texture
+- **`d.textureDepthMultisampled2d()`** - A 2D multisampled depth texture
+- **`d.textureDepth2dArray()`** - A 2D array depth texture
+- **`d.textureDepthCube()`** - A cube depth texture
+- **`d.textureDepthCubeArray()`** - A cube array depth texture
+
+```ts twoslash
+import * as d from 'typegpu/data';
+// ---cut---
+const depthTex = d.textureDepth2d();
+//    ^?
+```
+
+### Storage Textures
+
+Storage texture schemas are created using dimension-specific constructors, with required `format` and optional `access` parameters:
+
+- **`d.textureStorage1d(format, access?)`** - A 1D storage texture
+- **`d.textureStorage2d(format, access?)`** - A 2D storage texture
+- **`d.textureStorage2dArray(format, access?)`** - A 2D array storage texture
+- **`d.textureStorage3d(format, access?)`** - A 3D storage texture
+
+The `format` parameter specifies the texture format (e.g., `'rgba8unorm'`, `'rgba16float'`, `'r32float'`), and the `access` parameter can be `'write-only'`, `'read-only'`, or `'read-write'`. If `access` is omitted, it defaults to `'write-only'`.
+
+```ts twoslash
+import * as d from 'typegpu/data';
+// ---cut---
+const storageTex1 = d.textureStorage2d('rgba8unorm');
+//    ^?
+
+const storageTex2 = d.textureStorage2d('rgba8unorm', 'read-only');
+//    ^?
+
+const storageTex3 = d.textureStorage3d('r32float', 'read-write');
+//    ^?
+```
+
 ## Atomics
 
 To create a schema corresponding to an atomic data type, wrap `d.i32` or `d.u32` with `d.atomic`.