docs: Updates to docs related to TypeGPU functions (#1882)

Author: iwoplaza

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

@@ -17,7 +17,7 @@ Imported functions from external sources are automatically resolved and embedded
 ## Defining a function
 
 :::note[WGSL enthusiasts!]
-Don't let the JavaScript scare you! TypeGPU functions can be implemented using either WGSL or JS, both being able to call one another.
+Don't let the JavaScript discourage you! TypeGPU functions can be implemented using either WGSL or JS, both being able to call one another.
 If you're planning on only using WGSL, you can skip right over to [Implementing functions in WGSL](#implementing-functions-in-wgsl),
 though we recommend reading through anyway.
 :::
@@ -53,7 +53,6 @@ const neighborhood = (a: number, r: number) => {
 // ---cut---
 const main = () => {
   'use gpu';
-  // Call from another function
   return neighborhood(1.1, 0.5);
 };
 
@@ -91,12 +90,27 @@ You can already notice a few things about TypeGPU functions:
 - TS types are properly inferred, feel free to hover over the variables to see their types.
 - The generated code closely matches your source code.
 
+:::caution[Using numeric literals]
+Be mindful when using numeric literals. Numbers with nothing after the decimal point (those that pass the `Number.isInteger` test) are inferred as integers, the rest as floats.
+```js
+const foo = 1.1; // generates: const foo = 1.1f;
+const bar = 1.0; // generates: const bar = 1i;
+const baz = 123; // generates: const baz = 123i;
+```
+To ensure that a literal will be coerced to a specific type, you can wrap them in a schema:
+```js
+const foo = d.u32(1.1); // generates: const foo = 1u;
+const bar = d.f32(1.0); // generates: const bar = 1f;
+const baz = d.f16(123); // generates: const baz = 123h;
+```
+:::
+
 ### Code transformation
 
-To make this all work, we perform a small transformation to functions marked with `'use gpu'`, leaving all other code untouched. Every project's setup is different, and we want to be as non-invasive as possible. The [unplugin-typegpu](/TypeGPU/tooling/unplugin-typegpu) package hooks into existing bundlers and build tools, extracts ASTs from TypeGPU functions and compacts them into our custom format called [tinyest](https://www.npmjs.com/package/tinyest). This metadata is injected into the final JS bundle, then used to efficiently generate equivalent WGSL at runtime.
+To make this all work, we perform a small transformation to functions marked with `'use gpu'`. Every project's setup is different, and we want to be as non-invasive as possible. The [unplugin-typegpu](/TypeGPU/tooling/unplugin-typegpu) package hooks into existing bundlers and build tools, extracts ASTs from TypeGPU functions and compacts them into our custom format called [tinyest](https://www.npmjs.com/package/tinyest). This metadata is injected into the final JS bundle, then used to efficiently generate equivalent WGSL at runtime.
 
 :::tip
-If you wish for all WGSL generation to happen at build time, combine [unplugin-macros](https://github.com/unplugin/unplugin-macros) and our [resolve API](/TypeGPU/fundamentals/resolve).
+If all your shader code is predetermined, or you want to precompute a set of variants ahead of time, you can combine [unplugin-macros](https://github.com/unplugin/unplugin-macros) and our [resolve API](/TypeGPU/fundamentals/resolve).
 :::
 
 
@@ -193,25 +207,6 @@ const double = <T extends d.v2f | d.v3f | d.v4f>(a: T): T => {
 };
 ```
 
-### Standard library
-
-TypeGPU provides a set of standard functions under `typegpu/std`, which you can use in your own TypeGPU functions. Our goal is for all functions to have matching
-behavior on the CPU and GPU, which unlocks many possibilities (shader unit testing, shared business logic, and more...).
-
-```ts twoslash
-import * as d from 'typegpu/data';
-import * as std from 'typegpu/std';
-
-function manhattanDistance(a: d.v3f, b: d.v3f) {
-  'use gpu';
-  const dx = std.abs(a.x - b.x);
-  const dy = std.abs(a.y - b.y);
-  const dz = std.abs(a.z - b.z);
-
-  return std.max(dx, std.max(dy, dz));
-}
-```
-
 You can explore the set of standard functions in the [API Reference](/TypeGPU/api/typegpu/std/functions/abs/).
 
 ### The outer scope
@@ -310,6 +305,27 @@ you have to use supplementary functions from `typegpu/std` (*add, mul, eq, lt, g
 
 * **Math.\*** --
 Utility functions on the `Math` object can't automatically run on the GPU, but can usually be swapped with functions exported from `typegpu/std`.
+Additionally, if you're able to pull the call to `Math.*` out of the function, you can store the result in a constant and use it in the function
+no problem.
+
+### Standard library
+
+TypeGPU provides a set of standard functions under `typegpu/std`, which you can use in your own TypeGPU functions. Our goal is for all functions to have matching
+behavior on the CPU and GPU, which unlocks many possibilities (shader unit testing, shared business logic, and more...).
+
+```ts twoslash
+import * as d from 'typegpu/data';
+import * as std from 'typegpu/std';
+
+function manhattanDistance(a: d.v3f, b: d.v3f) {
+  'use gpu';
+  const dx = std.abs(a.x - b.x);
+  const dy = std.abs(a.y - b.y);
+  const dz = std.abs(a.z - b.z);
+
+  return std.max(dx, std.max(dy, dz));
+}
+```
 
 ## Function shells
 

apps/typegpu-docs/src/content/docs/getting-started.mdx

@@ -27,23 +27,45 @@ Install TypeGPU using the package manager of your choice.
   </TabItem>
 </Tabs>
 
-You can then import it in JavaScript/TypeScript code.
+TypeScript doesn't yet ship WebGPU types by default, so we install them separately:
 
-```ts
-// main.ts
+<Tabs syncKey="package-manager">
+  <TabItem label="npm" icon="seti:npm">
+    ```sh frame=none
+    npm install --save-dev @webgpu/types
+    ```
+  </TabItem>
+  <TabItem label="pnpm" icon="pnpm">
+    ```sh frame=none
+    pnpm add -D @webgpu/types
+    ```
+  </TabItem>
+  <TabItem label="yarn" icon="seti:yarn">
+    ```sh frame=none
+    yarn add -D @webgpu/types
+    ```
+  </TabItem>
+</Tabs>
 
-import tgpu from 'typegpu';
+Then add the following to your `tsconfig.json`:
 
-// ...
+```json
+{
+  "compilerOptions": {
+    "types": ["@webgpu/types"],
+    // ...
+  },
+  // ...
+}
 ```
 
-## Live Examples
-
-Our [live examples](/TypeGPU/examples) showcase many use-cases of TypeGPU. Feel free to check them out! You can also open each of them on StackBlitz in order to edit the code and see the preview update live.
+:::note
+TypeGPU features related to writing shaders in JavaScript/TypeScript rely on an [additional build tool that hooks into existing bundlers called unplugin-typegpu](/TypeGPU/tooling/unplugin-typegpu). Make sure to set it up as well if you plan on using these features.
+:::
 
-## StackBlitz
+## Live Examples
 
-You can play with TypeGPU right in the browser using our [StackBlitz example](https://stackblitz.com/edit/typegpu-example?file=src%2Fmain.ts).
+Our [live examples](/TypeGPU/examples) showcase many use-cases of TypeGPU. Feel free to check them out! You can also open each of them on StackBlitz in order to edit the code and see the preview update live, or to bootstrap your own project.
 
 ## Troubleshooting
 

apps/typegpu-docs/src/content/docs/tooling/unplugin-typegpu.mdx

@@ -7,47 +7,23 @@ description: A guide on how to use the optional build plugin for TypeGPU
 
 The package includes the following functionalities:
 
-- **TGSL functions**
+- **TypeGPU functions implemented in JS/TS**
 
-  TypeGPU allows running a subset of JavaScript (which we call TGSL) on the GPU. It is achieved by transpiling JS functions into WGSL.
-  This can be done via a Just-In-Time compiler or at build time, using the plugin.
-  Transpiling at build time reduces the performance overhead at runtime,
-  and it is also the only possible approach on React Native, as the function code string is not available during runtime there.
-
-  _unplugin-typegpu_ scans the project files looking for the tgpu function shell implementations.
-  It transpiles the JS code into a compact AST format, called [tinyest](https://www.npmjs.com/package/tinyest).
-
-  When an implementation function is passed directly to the shell creation, the plugin should have no problem identifying and processing it.
+  The plugin allows transpiling a subset of JavaScript to WebGPU Shading Language (WGSL).
+  The parsing of JavaScript happens ahead of time, emitting a highly compact AST format, called [tinyest](https://www.npmjs.com/package/tinyest).
 
   ```ts
   import tgpu from 'typegpu';
   import * as d from 'typegpu/data';
 
-  const add = tgpu.fn([d.u32, d.u32], d.u32)((a, b) => a + b);
-  ```
-
-  However, if the implementation function, or the shell, is referenced via a variable, the plugin will not recognize it as TGSL,
-  thus to make it work, the function needs to be marked with a `'use gpu'` directive.
-
-  ```ts
-  const addFn = tgpu.fn([d.u32, d.u32], d.u32);
-
-  const add = addFn((a, b) => {
-    'use gpu';
-    return a + b;
-  });
-  ```
-
-  ```ts
-  const addImpl = (a, b) => {
+  // Found by the plugin and decorated with 'tinyest' metadata
+  const add = (a: number, b: number) => {
     'use gpu';
     return a + b;
   };
-
-  const add = tgpu.fn([d.u32, d.u32], d.u32)(addImpl);
   ```
 
-  Besides transpiling JS into AST, the plugin also collects external references, so it is not necessary to pass them to the `$uses` method anymore.
+  Besides parsing JS into an AST, the plugin also collects external references, so it is not necessary to pass them to the `$uses` method (as is required when implementing functions in WGSL).
 
 - **Automatic naming of tgpu objects**
 
@@ -96,7 +72,7 @@ import { defineConfig } from 'vite';
 import typegpuPlugin from 'unplugin-typegpu/vite';
 
 export default defineConfig({
-  plugins: [typegpuPlugin()],
+  plugins: [typegpuPlugin({})],
 });
 ```