feat: Stabilize pipelines and entry functions (#2168)

Author: iwoplaza

README.md

@@ -37,9 +37,7 @@ const wgsl = tgpu.resolve([main]);
 //
 // #3) Executed on the GPU (generates WGSL underneath)
 //
-root['~unstable']
-  .createGuardedComputePipeline(main)
-  .dispatchThreads();
+root.createGuardedComputePipeline(main).dispatchThreads();
 ```
 
 <div align="center">

apps/typegpu-docs/src/content/docs/ecosystem/typegpu-noise.mdx

@@ -84,7 +84,7 @@ using a set of `randf.seedN` functions, where `N` is the number of components ou
 import tgpu, { d } from 'typegpu';
 import { randf } from '@typegpu/noise';
 
-const main = tgpu['~unstable'].fragmentFn({
+const main = tgpu.fragmentFn({
   in: { pos: d.builtin.position },
   out: d.vec4f,
 })(({ pos }) => {
@@ -148,7 +148,7 @@ import tgpu, { d } from 'typegpu';
 // ---cut---
 import { perlin2d } from '@typegpu/noise';
 
-const main = tgpu['~unstable'].fragmentFn({
+const main = tgpu.fragmentFn({
   in: { pos: d.builtin.position },
   out: d.vec4f,
 })(({ pos }) => {
@@ -169,15 +169,15 @@ import tgpu, { d } from 'typegpu';
 const root = await tgpu.init();
 import { perlin3d } from '@typegpu/noise';
 
-const main = tgpu['~unstable'].computeFn({ workgroupSize: [1] })(() => {
+const main = tgpu.computeFn({ workgroupSize: [1] })(() => {
   const value = perlin3d.sample(d.vec3f(0.5, 0, 0));
   const wrappedValue = perlin3d.sample(d.vec3f(10.5, 0, 0)); // the same as `value`!
 });
 
 // ---cut---
 const cache = perlin3d.staticCache({ root, size: d.vec3u(10, 10, 1) });
 
-const pipeline = root['~unstable']
+const pipeline = root
   // Plugging the cache into the pipeline
   .pipe(cache.inject())
   // ...
@@ -224,7 +224,7 @@ complex setup.
 import tgpu, { d } from 'typegpu';
 import { perlin3d } from '@typegpu/noise';
 
-const main = tgpu['~unstable'].computeFn({ workgroupSize: [1] })(() => {
+const main = tgpu.computeFn({ workgroupSize: [1] })(() => {
   const value = perlin3d.sample(d.vec3f(0.5, 0, 0));
   const wrappedValue = perlin3d.sample(d.vec3f(10.5, 0, 0)); // the same as `value`!
 });
@@ -235,7 +235,7 @@ const cacheConfig = perlin3d.dynamicCacheConfig();
 // Holds all resources the perlin cache needs access to
 const dynamicLayout = tgpu.bindGroupLayout({ ...cacheConfig.layout });
 
-const pipeline = root['~unstable']
+const pipeline = root
   // Plugging the cache into the pipeline
   .pipe(cacheConfig.inject(dynamicLayout.$))
   // ...
@@ -272,7 +272,7 @@ import { randf } from '@typegpu/noise';
 const root = await tgpu.init();
 
 const b = root.createMutable(d.f32);
-const f = tgpu['~unstable'].computeFn({ workgroupSize: [1] })(() => {
+const f = tgpu.computeFn({ workgroupSize: [1] })(() => {
   b.$ = randf.sample();
 });
 // ---cut---
@@ -304,8 +304,7 @@ const LCG: StatefulGenerator = (() => {
   };
 })();
 
-const pipeline = root['~unstable']
+const pipeline = root
   .with(randomGeneratorSlot, LCG)
-  .withCompute(f)
-  .createPipeline();
+  .createComputePipeline({ compute: f });
 ```

apps/typegpu-docs/src/content/docs/ecosystem/typegpu-sdf.mdx

@@ -25,7 +25,7 @@ Here is an example of a fragment shader that draws a disk of radius 0.25 on the
 import tgpu, { d } from 'typegpu';
 import * as sdf from '@typegpu/sdf';
 
-const mainFragment = tgpu['~unstable'].fragmentFn({
+const mainFragment = tgpu.fragmentFn({
   in: { uv: d.vec2f },
   out: d.vec4f,
 })(({ uv }) => {

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

@@ -338,7 +338,7 @@ const layout = tgpu.bindGroupLayout({
   points: { storage: d.arrayOf(d.vec2i), access: 'mutable' },
 });
 
-const pipeline = root['~unstable'].createGuardedComputePipeline((x) => {
+const pipeline = root.createGuardedComputePipeline((x) => {
   'use gpu';
   // Access and modify the bound buffer via the layout
   layout.$.points[x] = d.vec2i(1, 2);
@@ -374,7 +374,7 @@ const root = await tgpu.init();
 // ---cut---
 const pointsMutable = root.createMutable(d.arrayOf(d.vec2i, 100));
 
-const pipeline = root['~unstable'].createGuardedComputePipeline((x) => {
+const pipeline = root.createGuardedComputePipeline((x) => {
   'use gpu';
   // Access and modify the fixed buffer directly
   pointsMutable.$[x] = d.vec2i();

apps/typegpu-docs/src/content/docs/fundamentals/enabling-features.mdx

@@ -31,7 +31,7 @@ const root = await tgpu.init({
   },
   // …other TypeGPU options…
 });
-````
+```
 
 * **`requiredFeatures: GPUFeatureName[]`**
   All listed features must be supported by the GPU; otherwise `requestDevice()` rejects.

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

@@ -63,10 +63,8 @@ const wgsl = tgpu.resolve([main]);
 //    ^?
 
 // #3) Executed on the GPU (generates WGSL underneath)
-root['~unstable']
-  .createGuardedComputePipeline(main)
-  .dispatchThreads();
-````
+root.createGuardedComputePipeline(main).dispatchThreads();
+```
 
 The contents of the `wgsl` variable would contain the following:
 
@@ -81,7 +79,7 @@ fn main() -> vec2f {
 }
 
 // ...
-````
+```
 
 You can already notice a few things about TypeGPU functions:
 - Using operators like `+`, `-`, `*`, `/`, etc. is perfectly valid on numbers.
@@ -257,7 +255,7 @@ const settings = {
   speed: 1,
 };
 
-const pipeline = root['~unstable'].createGuardedComputePipeline(() => {
+const pipeline = root.createGuardedComputePipeline(() => {
   'use gpu';
   const speed = settings.speed;
   // ^ generates: var speed = 1;
@@ -456,9 +454,9 @@ Entry functions are an *unstable* feature. The API may be subject to change in t
 
 Instead of annotating a `TgpuFn` with attributes, entry functions are defined using dedicated shell constructors:
 
-- `tgpu['~unstable'].computeFn`,
-- `tgpu['~unstable'].vertexFn`,
-- `tgpu['~unstable'].fragmentFn`.
+- `tgpu.computeFn`,
+- `tgpu.vertexFn`,
+- `tgpu.fragmentFn`.
 
 ### Entry point function I/O
 
@@ -510,7 +508,7 @@ const deltaTime = root.createUniform(d.f32);
 const time = root.createMutable(d.f32);
 const particleDataStorage = particleDataBuffer.as('mutable');
 // ---cut---
-const mainCompute = tgpu['~unstable'].computeFn({
+const mainCompute = tgpu.computeFn({
   in: { gid: d.builtin.globalInvocationId },
   workgroupSize: [1],
 }) /* wgsl */`{
@@ -561,7 +559,7 @@ import tgpu, { d } from 'typegpu';
 
 const getGradientColor = tgpu.fn([d.f32], d.vec4f)``;
 // ---cut---
-const mainVertex = tgpu['~unstable'].vertexFn({
+const mainVertex = tgpu.vertexFn({
   in: { vertexIndex: d.builtin.vertexIndex },
   out: { outPos: d.builtin.position, uv: d.vec2f },
 }) /* wgsl */`{
@@ -580,7 +578,7 @@ const mainVertex = tgpu['~unstable'].vertexFn({
     return Out(vec4f(pos[in.vertexIndex], 0.0, 1.0), uv[in.vertexIndex]);
   }`;
 
-const mainFragment = tgpu['~unstable'].fragmentFn({
+const mainFragment = tgpu.fragmentFn({
   in: { uv: d.vec2f },
   out: d.vec4f,
 }) /* wgsl */`{
@@ -646,17 +644,17 @@ const root = await tgpu.init();
 
 const getGradientColor = tgpu.fn([d.f32], d.vec4f)/* wgsl */``;
 
-const mainVertex = tgpu['~unstable'].vertexFn({
+const mainVertex = tgpu.vertexFn({
   in: { vertexIndex: d.builtin.vertexIndex },
   out: { outPos: d.builtin.position, uv: d.vec2f },
 })``;
 
-const mainFragment = tgpu['~unstable'].fragmentFn({
+const mainFragment = tgpu.fragmentFn({
   in: { uv: d.vec2f },
   out: d.vec4f,
 })``;
 // ---cut---
-const pipeline = root['~unstable'].createRenderPipeline({
+const pipeline = root.createRenderPipeline({
   vertex: mainVertex,
   fragment: mainFragment,
   targets: { format: presentationFormat },

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

@@ -31,7 +31,7 @@ const root = await tgpu.init();
 
 const presentationFormat = 'rgba8unorm';
 
-const mainVertex = tgpu['~unstable'].vertexFn({
+const mainVertex = tgpu.vertexFn({
   in: { vertexIndex: d.builtin.vertexIndex },
   out: { pos: d.builtin.position },
 })((input) => {
@@ -42,27 +42,25 @@ const mainVertex = tgpu['~unstable'].vertexFn({
   };
 });
 
-const mainFragment = tgpu['~unstable']
-  .fragmentFn({ out: d.vec4f })(() => d.vec4f(1, 0, 0, 1));
+const mainFragment = tgpu.fragmentFn({ out: d.vec4f })(() => d.vec4f(1, 0, 0, 1));
 
-const mainCompute = tgpu['~unstable'].computeFn({ workgroupSize: [1] })(() => {});
+const mainCompute = tgpu.computeFn({ workgroupSize: [1] })(() => {});
 
 // ---cut---
-const renderPipeline = root['~unstable'].createRenderPipeline({
+const renderPipeline = root.createRenderPipeline({
   vertex: mainVertex,
   fragment: mainFragment,
   targets: { format: presentationFormat },
 });
 
-const computePipeline1 = root['~unstable'].createComputePipeline({
+const computePipeline1 = root.createComputePipeline({
   compute: mainCompute,
 });
 
-const computePipeline2 = root['~unstable']
-  .createGuardedComputePipeline((x, y, z) => {
-    'use gpu';
-    // ...
-  });
+const computePipeline2 = root.createGuardedComputePipeline((x, y, z) => {
+  'use gpu';
+  // ...
+});
 ```
 
 ### createRenderPipeline
@@ -84,7 +82,7 @@ import tgpu, { d } from 'typegpu';
 const root = await tgpu.init();
 const presentationFormat = 'rgba8unorm';
 
-const mainVertex = tgpu['~unstable'].vertexFn({
+const mainVertex = tgpu.vertexFn({
   in: { vertexIndex: d.builtin.vertexIndex, pos: d.vec2f },
   out: { pos: d.builtin.position },
 })((input) => {
@@ -95,12 +93,11 @@ const mainVertex = tgpu['~unstable'].vertexFn({
   };
 });
 
-const mainFragment = tgpu['~unstable']
-  .fragmentFn({ out: d.vec4f })(() => d.vec4f(1, 0, 0, 1));
+const mainFragment = tgpu.fragmentFn({ out: d.vec4f })(() => d.vec4f(1, 0, 0, 1));
 // ---cut---
 const vertexLayout = tgpu.vertexLayout(d.arrayOf(d.vec2f));
 
-const renderPipeline = root['~unstable'].createRenderPipeline({
+const renderPipeline = root.createRenderPipeline({
   attribs: { pos: vertexLayout.attrib },
   vertex: mainVertex,
   fragment: mainFragment,
@@ -132,18 +129,18 @@ as long as there is no conflict between vertex and fragment location values.
 ```ts twoslash
 import tgpu, { d } from 'typegpu';
 
-const vertex = tgpu['~unstable'].vertexFn({
+const vertex = tgpu.vertexFn({
   out: { pos: d.builtin.position },
 })`(...)`;
-const fragment = tgpu['~unstable'].fragmentFn({
+const fragment = tgpu.fragmentFn({
   in: { uv: d.vec2f },
   out: d.vec4f,
 })`(...)`;
 
 const root = await tgpu.init();
 
 // @errors: 2769
-root['~unstable'].createRenderPipeline({
+root.createRenderPipeline({
   vertex,
   fragment,
   targets: { format: 'bgra8unorm' },
@@ -163,10 +160,10 @@ import tgpu, { d } from 'typegpu';
 
 const root = await tgpu.init();
 
-const mainCompute = tgpu['~unstable'].computeFn({ workgroupSize: [1] })(() => {});
+const mainCompute = tgpu.computeFn({ workgroupSize: [1] })(() => {});
 
 // ---cut---
-const computePipeline = root['~unstable'].createComputePipeline({
+const computePipeline = root.createComputePipeline({
   compute: mainCompute,
 });
 ```
@@ -188,11 +185,10 @@ const root = await tgpu.init();
 // ---cut---
 const data = root.createMutable(d.arrayOf(d.u32, 8), [0, 1, 2, 3, 4, 5, 6, 7]);
 
-const doubleUpPipeline = root['~unstable']
-  .createGuardedComputePipeline((x) => {
-    'use gpu';
-    data.$[x] *= 2;
-  });
+const doubleUpPipeline = root.createGuardedComputePipeline((x) => {
+  'use gpu';
+  data.$[x] *= 2;
+});
 
 doubleUpPipeline.dispatchThreads(8);
 doubleUpPipeline.dispatchThreads(8);
@@ -229,7 +225,7 @@ const waterLevelMutable = root.createMutable(
   d.arrayOf(d.arrayOf(d.f32, 512), 1024),
 );
 
-root['~unstable'].createGuardedComputePipeline((x, y) => {
+root.createGuardedComputePipeline((x, y) => {
   'use gpu';
   randf.seed2(d.vec2f(x, y).div(1024));
   waterLevelMutable.$[x][y] = 10 + randf.sample();
@@ -368,7 +364,7 @@ const colorBuffer = root
   ])
   .$usage('vertex');
 
-const vertex = tgpu['~unstable'].vertexFn({
+const vertex = tgpu.vertexFn({
   in: {
     idx: d.builtin.vertexIndex,
     color: d.vec4f,
@@ -385,7 +381,7 @@ const vertex = tgpu['~unstable'].vertexFn({
 });
 
 const vertexLayout = tgpu.vertexLayout(d.arrayOf(d.vec4f));
-const mainFragment = tgpu['~unstable'].fragmentFn({
+const mainFragment = tgpu.fragmentFn({
   in: {
     color: d.vec4f,
   },
@@ -396,7 +392,7 @@ const indexBuffer = root
   .createBuffer(d.arrayOf(d.u16, 6), [0, 2, 1, 0, 3, 2])
   .$usage('index');
 
-const pipeline = root['~unstable']
+const pipeline = root
   .createRenderPipeline({
     attribs: { color: vertexLayout.attrib },
     vertex,
@@ -440,11 +436,11 @@ import tgpu, { d } from 'typegpu';
 
 const root = await tgpu.init();
 
-const mainVertex = tgpu['~unstable'].vertexFn({ out: { pos: d.builtin.position } })`...`;
-const mainFragment = tgpu['~unstable'].fragmentFn({ out: d.vec4f })`...`;
+const mainVertex = tgpu.vertexFn({ out: { pos: d.builtin.position } })`...`;
+const mainFragment = tgpu.fragmentFn({ out: d.vec4f })`...`;
 
 // ---cut---
-const pipeline = root['~unstable'].createRenderPipeline({
+const pipeline = root.createRenderPipeline({
   vertex: mainVertex,
   fragment: mainFragment,
   targets: { format: 'rg8unorm' },