docs: Refresh docs for 0.10 (#2211)

* docs: Refresh docs for 0.10

* More changes to docs for 0.10

Author: iwoplaza

apps/typegpu-docs/astro.config.mjs

@@ -152,7 +152,6 @@ export default defineConfig({
             {
               label: 'Variables',
               slug: 'fundamentals/variables',
-              badge: { text: 'new' },
             },
             {
               label: 'Data Schemas',
@@ -173,17 +172,14 @@ export default defineConfig({
             {
               label: 'Enabling Features',
               slug: 'fundamentals/enabling-features',
-              badge: { text: 'new' },
             },
             {
               label: 'Timing Your Pipelines',
               slug: 'fundamentals/timestamp-queries',
-              badge: { text: 'new' },
             },
             {
               label: 'Slots',
               slug: 'fundamentals/slots',
-              badge: { text: 'new' },
             },
             {
               label: 'Utilities',
@@ -214,12 +210,10 @@ export default defineConfig({
             {
               label: '@typegpu/three',
               slug: 'ecosystem/typegpu-three',
-              badge: { text: 'new' },
             },
             {
               label: '@typegpu/sdf',
               slug: 'ecosystem/typegpu-sdf',
-              badge: { text: 'new' },
             },
             DEV && {
               label: '@typegpu/color',
@@ -241,7 +235,6 @@ export default defineConfig({
             {
               label: 'React Native',
               slug: 'integration/react-native',
-              badge: { text: 'new' },
             },
             {
               label: 'WESL Interoperability',
@@ -259,7 +252,6 @@ export default defineConfig({
             {
               label: 'Build Plugin',
               slug: 'tooling/unplugin-typegpu',
-              badge: { text: 'new' },
             },
             {
               label: 'Generator CLI',

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

@@ -13,7 +13,7 @@ TypeGPU does this automatically during buffer writes and reads.
 :::
 
 The primary usage for data schemas is to define buffer and function signatures.
-Schemas can also be called in JS or TGSL to create instances of the types they represent.
+Schemas can also be called to create instances of the types they represent.
 
 TypeGPU provides data schemas for scalar, vector and matrix types, as well as constructors for struct and array schemas.
 
@@ -23,7 +23,7 @@ TypeGPU provides data schemas for scalar, vector and matrix types, as well as co
 
 For scalar WGSL types `f32`, `u32`, `i32`, `f16` and `bool`, TypeGPU provides `d.f32`, `d.u32`, `d.i32`, `d.f16` and `d.bool` schemas respectively.
 Schemas can be called to cast a value to a given type.
-This works both in TGSL, and in plain JavaScript.
+This works both inside and outside 'use gpu' functions.
 
 ```ts twoslash
 import { d } from 'typegpu';
@@ -36,7 +36,7 @@ d.bool(0.01); // true
 ```
 
 :::caution
-On JavaScript side, the type of any number remains a number regardless of any casts.
+In JavaScript, the type of any number remains a number regardless of casts.
 
 ```ts twoslash
 import { d } from 'typegpu';
@@ -46,7 +46,7 @@ const myUnsignedInt = d.u32(1);
 const result = d.u32(3)/d.u32(2); // 1.5
 ```
 
-For the WGSL and JS functions to return consistent results, during WGSL resolution TypeGPU wraps all divisions in `f32` casts.
+To achieve consistent behavior of 'use gpu' functions in JS and on the GPU, TypeGPU wraps all divisions in `f32` casts implicitly.
 :::
 
 For each of the scalar types, there is a vector schema of 2, 3 and 4 elements of that type.
@@ -106,7 +106,7 @@ to a seamless integration with `wgpu-matrix`, which you can [read more about her
 
 :::caution
 For `wgpu-matrix` integration, matrix instances implement array access.
-Matrix array access is not supported in TGSL.
+Matrix array access is not supported in 'use gpu' functions.
 
 ```ts twoslash
 import { d } from 'typegpu';
@@ -474,16 +474,17 @@ const AtomicI32 = d.atomic(d.i32);
 ```
 
 :::tip
-The `std` module provides functions for manipulating atomic data in TGSL.
+The `std` module provides functions for manipulating atomic data in 'use gpu' functions.
 
 ```ts twoslash
 import tgpu, { d, std } from 'typegpu';
 // ---cut---
 const count = tgpu.workgroupVar(d.atomic(d.u32));
 
-const incrementAndGet = tgpu.fn([], d.u32)(() => {
+function incrementAndGet() {
+  'use gpu';
   return std.atomicAdd(count.$, 1);
-});
+}
 ```
 
 :::
@@ -514,19 +515,19 @@ This extension is enabled automatically when available.
 ## Copy constructors
 
 One of the biggest differences between JavaScript and WGSL is the existence of value/reference types.
-Let's take a look at a simple TGSL function and the WGSL code it resolves to.
+Let's take a look at a simple TypeGPU function and the WGSL code it resolves to.
 
 ```ts twoslash
 import tgpu, { d } from 'typegpu';
 // ---cut---
-// TGSL
 const MyStruct = d.struct({ n: d.u32 });
 
-const myFn = tgpu.fn([])(() => {
+function myFn() {
+  'use gpu';
   const s1 = MyStruct({ n: 0 });
   const s2 = s1;
   s2.n = 1; // s1 is modified
-});
+}
 ```
 
 ```wgsl
@@ -537,29 +538,31 @@ struct MyStruct {
 
 fn myFn(){
   var s1 = MyStruct(0);
-  var s2 = s1;
-  s2.n = 1; // s1 is not modified
+  let s2 = &s1;
+  (*s2).n = 1; // s1 is modified
 }
 ```
 
-On the JS side, s2 is a reference to s1 and therefore s1 is modified when s2 is modified.
-On the WGSL side, the assignment operator copies the value of s1, and thus s1 is not modified later on.
+In JavaScript, `s2` is a reference to `s1` and therefore `s1` is modified when `s2` is modified.
+On the WGSL side, we make `s2` a reference to `s1` and modifying `s2.n` is translated to modifying `(*s2).n`.
 
-To help with this issue, schema calls can be used as "copy constructors", that copy the value on the JS side, and disappear on the WGSL side:
+Schemas can be used to create deep copies of values.
 
 ```ts twoslash
 import tgpu, { d } from 'typegpu';
 // ---cut---
-// TGSL
 const MyStruct = d.struct({ n: d.u32 });
 
-const myFn = tgpu.fn([])(() => {
+function myFn() {
+  'use gpu';
   const s1 = MyStruct({ n: 0 });
   const s2 = MyStruct(s1); // deep copy of s1
   s2.n = 1; // s1 is not modified
-});
+}
 ```
 
+The TypeGPU shader generator understands this and generates a simple assignment, which copies the value of `s1` into `s2`.
+
 ```wgsl
 // WGSL
 struct MyStruct {

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

@@ -444,10 +444,6 @@ However, there are cases where WGSL might be more suitable. Writing WGSL becomes
 
 ## Entry functions
 
-:::caution[Experimental]
-Entry functions are an *unstable* feature. The API may be subject to change in the near future.
-:::
-
 Instead of annotating a `TgpuFn` with attributes, entry functions are defined using dedicated shell constructors:
 
 - `tgpu.computeFn`,

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

@@ -3,10 +3,6 @@ title: Pipelines
 description: A guide on how to use TypeGPU render and compute pipelines.
 ---
 
-:::caution[Experimental]
-Pipelines are an *unstable* feature. The API may be subject to change in the near future.
-:::
-
 :::note[Recommended reading]
 It is assumed that you are familiar with the following concepts:
 - <a href="https://webgpufundamentals.org/webgpu/lessons/webgpu-fundamentals.html" target="_blank" rel="noopener noreferrer">WebGPU Fundamentals</a>
@@ -404,6 +400,10 @@ const pipeline = root
 
 ## Low-level render pipeline execution API
 
+:::caution[Experimental]
+`root.beginRenderPass` is an *unstable* feature. The API may be subject to change in the near future.
+:::
+
 The higher-level API has several limitations, therefore another way of executing pipelines is exposed, for some custom, more demanding scenarios. For example, with the high-level API, it is not possible to execute multiple pipelines per one render pass. It also may be missing some more niche features of the WebGPU API.
 
 `root['~unstable'].beginRenderPass` is a method that mirrors the WebGPU API, but enriches it with a direct TypeGPU resource support.

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

@@ -258,7 +258,7 @@ Sometimes, it may not be clear which bind group layouts were used in a given res
 This may occur especially when using:
 
 - Buffer usages/shorthands, which use a hidden, automatically created "catchall" bind group,
-- TypeGPU functions implemented in TGSL, which generate their externals automatically.
+- TypeGPU functions implemented in JavaScript/TypeScript, which generate their externals automatically.
 
 For these cases, you can use `tgpu.resolveWithContext`, which has the same input API as `tgpu.resolve`, but in addition to the resolved code, it also returns information about the layouts used. `tgpu.resolveWithContext` returns an object with 3 props:
 
@@ -290,7 +290,7 @@ console.log(catchall?.[0]); // 0 - the group index of the catchall bind group
 console.log(catchall?.[1]); // the catchall bind group
 ```
 
-An example, where a bind group layout is automatically included via a TGSL function:
+An example, where a bind group layout is automatically included via a TypeScript function:
 
 ```ts twoslash
 import tgpu, { d } from 'typegpu';
@@ -299,9 +299,10 @@ const root = await tgpu.init();
 // ---cut---
 const myLayout = tgpu.bindGroupLayout({ count: { uniform: d.u32 } });
 
-const exampleFn = tgpu.fn([])(() => {
+function exampleFn() {
+  'use gpu';
   myLayout.$.count += 1;
-});
+}
 
 const { code, usedBindGroupLayouts, catchall } = tgpu.resolveWithContext({
   externals: { exampleFn },

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

@@ -7,7 +7,7 @@ Similarly to bind group layouts, you can think of slots as of typed "holes" in T
 The main differences between slots and bound resources include the following:
 
 - Slots are filled in before the shader module compile time, instead of just before the shader execution starts.
-- Slots can contain not only buffers, but also basically anything that is allowed in TGSL, even TypeGPU functions.
+- Slots can contain not only buffers, but also basically any JavaScript value, even TypeGPU functions.
 
 Main use cases for slots include:
 

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

@@ -140,6 +140,10 @@ const ctx = canvas.getContext('2d');
 texture.write(canvas);
 ```
 
+:::tip
+If image dimensions don't match the texture size, the image will be automatically resampled to fit (requires 'render' usage).
+:::
+
 ### Writing arrays of images
 
 For 3D textures or texture arrays, you can write multiple images:
@@ -188,10 +192,6 @@ const mipData = new Uint8Array(4 * 128 * 128); // Data for 128x128
 texture.write(mipData, 1); // Write to mip level 1
 ```
 
-:::tip
-If image dimensions don't match the texture size, the image will be automatically resampled to fit.
-:::
-
 You can also copy from another texture:
 
 ```ts twoslash

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

@@ -262,7 +262,7 @@ Other supported `console` functionalities include `console.debug`, `console.info
 
 There are some limitations (some of which we intend to alleviate in the future):
 
-- `console.log` only works when used in TGSL, when calling or resolving a TypeGPU pipeline.
+- `console.log` only works when used in TypeGPU functions that are transitively called in a TypeGPU pipeline.
 Otherwise, for example when using `tgpu.resolve` on a WGSL template, logs are ignored.
 - `console.log` only works in fragment and compute shaders.
 This is due to a [WebGPU limitation](https://www.w3.org/TR/WGSL/#address-space) that does not allow modifying buffers during the vertex shader stage.

apps/typegpu-docs/src/content/docs/integration/react-native/index.mdx

@@ -59,7 +59,7 @@ npm i --save-dev @webgpu/types
 }
 ```
 
-If you want to be able to use the TGSL functions feature of TypeGPU (JS functions transpiled to WGSL), you need to install the [unplugin-typegpu](https://www.npmjs.com/package/unplugin-typegpu) package.
+If you want to be able to implement TypeGPU functions in JavaScript/TypeScript, you need to install the [unplugin-typegpu](https://www.npmjs.com/package/unplugin-typegpu) package.
 
 ```sh
 npm install --save-dev unplugin-typegpu

apps/typegpu-docs/src/examples/rendering/xor-dev-runner/index.ts

@@ -1,7 +1,7 @@
 /**
  * This is a port of XorDev's "Runner" example using TypeGPU. Most of the shader is
- * written in TGSL (TypeScript + Standard Library), but parts of it are implemented
- * in WGSL to showcase the flexibility of TypeGPU.
+ * written in TypeScript, but parts of it are implemented in WGSL to showcase the
+ * flexibility of TypeGPU.
  *
  * ## Credits
  * XorDev (xordev.com) for the idea and original implementation