docs: Sdfs (#1977)

Author: aleksanderkatan

apps/typegpu-docs/astro.config.mjs

@@ -211,6 +211,10 @@ export default defineConfig({
               label: '@typegpu/noise',
               slug: 'ecosystem/typegpu-noise',
             },
+            {
+              label: '@typegpu/sdf',
+              slug: 'ecosystem/typegpu-sdf',
+            },
             DEV && {
               label: '@typegpu/color',
               slug: 'ecosystem/typegpu-color',

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

@@ -0,0 +1,50 @@
+---
+title: "@typegpu/sdf"
+---
+
+The `@typegpu/sdf` package offers a set of [signed distance function](https://en.wikipedia.org/wiki/Signed_distance_function) utilities for use in TypeGPU and WebGPU projects.
+
+## Example usage
+
+By definition, signed distance functions return a distance from the given point to the boundary of a shape.
+For example, the `sdf.sdDisk(point, radius)` returns the signed distance from the `point`, to a circle located at point (0, 0) of radius equal to `radius`.
+
+- `sdf.sdDisk(d.vec2f(2, 0), 1)` is equal to 1,
+- `sdf.sdDisk(d.vec2f(1, 0), 1)` is equal to 0,
+- `sdf.sdDisk(d.vec2f(0, 0), 1)` is equal to -1.
+
+:::note
+Every shape is assumed to be located at position (0, 0).
+
+Position, scale and translation of a shape can be adjusted by applying the inverse transformation to the position argument.
+:::
+
+Here is an example of a fragment shader that draws a disk of radius 0.25 on the center of a (presumably square) canvas:
+
+```ts twoslash
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+import * as sdf from '@typegpu/sdf';
+
+const mainFragment = tgpu['~unstable'].fragmentFn({
+  in: { uv: d.vec2f },
+  out: d.vec4f,
+})(({ uv }) => {
+  if (sdf.sdDisk(uv.sub(0.5), 0.25) < 0) {
+    return d.vec4f(0, 0, 0, 1);
+  }
+  return d.vec4f(1);
+});
+```
+
+## Implemented functions
+
+For the list of all implemented functions see [this file](https://github.com/software-mansion/TypeGPU/blob/release/packages/typegpu-sdf/src/index.ts).
+All functions are documented using JSDoc.
+
+For any missing SDFs or utilities, feel free to submit an issue at https://github.com/software-mansion/TypeGPU/issues.
+
+## Further Reading
+
+- [2D Distance Functions](https://iquilezles.org/articles/distfunctions2d/) by Íñigo Quílez
+- [3D Distance Functions](https://iquilezles.org/articles/distfunctions/) by Íñigo Quílez

packages/typegpu-sdf/README.md

@@ -5,3 +5,27 @@
 🚧 **Under Construction** 🚧
 
 </div>
+
+A set of signed distance functions and utilities for use in WebGPU/TypeGPU apps.
+
+```ts
+import tgpu from 'typegpu';
+import * as sdf from '@typegpu/sdf';
+import * as d from 'typegpu/data';
+
+const mainFragment = tgpu['~unstable'].fragmentFn({
+  in: { uv: d.vec2f },
+  out: d.vec4f,
+})(({ uv }) => {
+  const distance = sdf.opSmoothUnion(
+    sdf.sdDisk(uv.sub(0.5), 0.25),
+    sdf.sdBox2d(uv.sub(0.5), d.vec2f(0.8, 0.05)),
+    0.1,
+  );
+
+  if (distance < 0) {
+    return d.vec4f(0, 0, 0, 1);
+  }
+  return d.vec4f(1, 1, 1, 0);
+});
+```

packages/typegpu-sdf/src/2d.ts

@@ -21,44 +21,44 @@ import {
 
 /**
  * Signed distance function for a disk (filled circle)
- * @param p Point to evaluate
+ * @param point Point to evaluate
  * @param radius Radius of the disk
  */
-export const sdDisk = tgpu.fn([vec2f, f32], f32)((p, radius) => {
-  return length(p) - radius;
+export const sdDisk = tgpu.fn([vec2f, f32], f32)((point, radius) => {
+  return length(point) - radius;
 });
 
 /**
- * Signed distance function for a 2d box
- * @param p Point to evaluate
+ * Signed distance function for a 2d box (rectangle)
+ * @param point Point to evaluate
  * @param size Half-dimensions of the box
  */
-export const sdBox2d = tgpu.fn([vec2f, vec2f], f32)((p, size) => {
-  const d = sub(abs(p), size);
+export const sdBox2d = tgpu.fn([vec2f, vec2f], f32)((point, size) => {
+  const d = sub(abs(point), size);
   return length(max(d, vec2f(0))) + min(max(d.x, d.y), 0);
 });
 
 /**
  * Signed distance function for a rounded 2d box
- * @param p Point to evaluate
+ * @param point Point to evaluate
  * @param size Half-dimensions of the box
  * @param cornerRadius Box corner radius
  */
 export const sdRoundedBox2d = tgpu
-  .fn([vec2f, vec2f, f32], f32)((p, size, cornerRadius) => {
-    const d = add(sub(abs(p), size), vec2f(cornerRadius));
+  .fn([vec2f, vec2f, f32], f32)((point, size, cornerRadius) => {
+    const d = add(sub(abs(point), size), vec2f(cornerRadius));
     return length(max(d, vec2f(0))) + min(max(d.x, d.y), 0) - cornerRadius;
   });
 
 /**
  * Signed distance function for a line segment
- * @param p Point to evaluate
- * @param a First endpoint of the line
- * @param b Second endpoint of the line
+ * @param point Point to evaluate
+ * @param A First endpoint of the line
+ * @param B Second endpoint of the line
  */
-export const sdLine = tgpu.fn([vec2f, vec2f, vec2f], f32)((p, a, b) => {
-  const pa = sub(p, a);
-  const ba = sub(b, a);
+export const sdLine = tgpu.fn([vec2f, vec2f, vec2f], f32)((point, A, B) => {
+  const pa = sub(point, A);
+  const ba = sub(B, A);
   const h = max(0, min(1, dot(pa, ba) / dot(ba, ba)));
   return length(sub(pa, ba.mul(h)));
 });
@@ -70,17 +70,17 @@ const dot2 = (v: v2f) => {
 
 /**
  * Signed distance function for a quadratic Bezier curve
- * @param pos Point to evaluate
+ * @param point Point to evaluate
  * @param A First control point of the Bezier curve
  * @param B Second control point of the Bezier curve
  * @param C Third control point of the Bezier curve
  */
 export const sdBezier = tgpu.fn([vec2f, vec2f, vec2f, vec2f], f32)(
-  (pos, A, B, C) => {
+  (point, A, B, C) => {
     const a = B.sub(A);
     const b = A.sub(B.mul(2)).add(C);
     const c = a.mul(f32(2));
-    const d = A.sub(pos);
+    const d = A.sub(point);
 
     const dotB = max(dot(b, b), 0.0001);
     const kk = 1 / dotB;
@@ -121,27 +121,34 @@ export const sdBezier = tgpu.fn([vec2f, vec2f, vec2f, vec2f], f32)(
   },
 );
 
-const cro = (a: v2f, b: v2f) => {
+const cross = (a: v2f, b: v2f) => {
   'use gpu';
   return a.x * b.y - a.y * b.x;
 };
 
+/**
+ * A fast approximation of the signed distance function for a quadratic Bezier curve
+ * @param point Point to evaluate
+ * @param A First control point of the Bezier curve
+ * @param B Second control point of the Bezier curve
+ * @param C Third control point of the Bezier curve
+ */
 export const sdBezierApprox = tgpu.fn(
   [vec2f, vec2f, vec2f, vec2f],
   f32,
-)((pos, A, B, C) => {
+)((point, A, B, C) => {
   const i = A.sub(C);
   const j = C.sub(B);
   const k = B.sub(A);
   const w = j.sub(k);
 
-  const v0 = A.sub(pos);
-  const v1 = B.sub(pos);
-  const v2 = C.sub(pos);
+  const v0 = A.sub(point);
+  const v1 = B.sub(point);
+  const v2 = C.sub(point);
 
-  const x = cro(v0, v2);
-  const y = cro(v1, v0);
-  const z = cro(v2, v1);
+  const x = cross(v0, v2);
+  const y = cross(v1, v0);
+  const z = cross(v2, v1);
 
   const s = j.mul(y).add(k.mul(z)).mul(2).sub(i.mul(x));
 
@@ -152,10 +159,17 @@ export const sdBezierApprox = tgpu.fn(
   return length(d);
 });
 
-export const sdPie = tgpu.fn([vec2f, vec2f, f32], f32)((p, c, r) => {
-  const p_w = vec2f(p);
-  p_w.x = abs(p.x);
-  const l = length(p_w) - r;
-  const m = length(p_w.sub(c.mul(clamp(dot(p_w, c), 0, r))));
-  return max(l, m * sign(c.y * p_w.x - c.x * p_w.y));
+/**
+ * Computes the signed distance field for a pie shape (circular sector).
+ *
+ * @param point - The point to evaluate, in 2D space
+ * @param sc - The sine/cosine of the pie's half-angle (`d.vec2f(std.sin(angle/2), std.cos(angle/2))`)
+ * @param radius - The radius of the pie
+ */
+export const sdPie = tgpu.fn([vec2f, vec2f, f32], f32)((point, sc, radius) => {
+  const p_w = vec2f(point);
+  p_w.x = abs(point.x);
+  const l = length(p_w) - radius;
+  const m = length(p_w.sub(sc.mul(clamp(dot(p_w, sc), 0, radius))));
+  return max(l, m * sign(sc.y * p_w.x - sc.x * p_w.y));
 });

packages/typegpu-sdf/src/3d.ts

@@ -4,45 +4,45 @@ import { abs, add, dot, length, max, min, saturate, sub } from 'typegpu/std';
 
 /**
  * Signed distance function for a sphere
- * @param p Point to evaluate
+ * @param point Point to evaluate
  * @param radius Radius of the sphere
  */
-export const sdSphere = tgpu.fn([vec3f, f32], f32)((p, radius) => {
-  return length(p) - radius;
+export const sdSphere = tgpu.fn([vec3f, f32], f32)((point, radius) => {
+  return length(point) - radius;
 });
 
 /**
  * Signed distance function for a 3d box
- * @param p Point to evaluate
+ * @param point Point to evaluate
  * @param size Half-dimensions of the box
  */
-export const sdBox3d = tgpu.fn([vec3f, vec3f], f32)((p, size) => {
-  const d = sub(abs(p), size);
+export const sdBox3d = tgpu.fn([vec3f, vec3f], f32)((point, size) => {
+  const d = sub(abs(point), size);
   return length(max(d, vec3f(0))) + min(max(max(d.x, d.y), d.z), 0);
 });
 
 /**
  * Signed distance function for a rounded 3d box
- * @param p Point to evaluate
+ * @param point Point to evaluate
  * @param size Half-dimensions of the box
  * @param cornerRadius Box corner radius
  */
 export const sdRoundedBox3d = tgpu
-  .fn([vec3f, vec3f, f32], f32)((p, size, cornerRadius) => {
-    const d = add(sub(abs(p), size), vec3f(cornerRadius));
+  .fn([vec3f, vec3f, f32], f32)((point, size, cornerRadius) => {
+    const d = add(sub(abs(point), size), vec3f(cornerRadius));
     return length(max(d, vec3f(0))) + min(max(max(d.x, d.y), d.z), 0) -
       cornerRadius;
   });
 
 /**
  * Signed distance function for a hollow box frame
- * @param p Point to evaluate
+ * @param point Point to evaluate
  * @param size Half-dimensions of the box
  * @param thickness Frame thickness
  */
 export const sdBoxFrame3d = tgpu
-  .fn([vec3f, vec3f, f32], f32)((p, size, thickness) => {
-    const p1 = sub(abs(p), size);
+  .fn([vec3f, vec3f, f32], f32)((point, size, thickness) => {
+    const p1 = sub(abs(point), size);
     const q = sub(abs(add(p1, thickness)), vec3f(thickness));
 
     // Calculate three possible distances for each main axis being the outer one
@@ -61,38 +61,40 @@ export const sdBoxFrame3d = tgpu
 
 /**
  * Signed distance function for a 3D line segment
- * @param p Point to evaluate
- * @param a First endpoint of the line
- * @param b Second endpoint of the line
+ * @param point Point to evaluate
+ * @param A First endpoint of the line
+ * @param B Second endpoint of the line
  */
-export const sdLine3d = tgpu.fn([vec3f, vec3f, vec3f], f32)((p, a, b) => {
-  const pa = sub(p, a);
-  const ba = sub(b, a);
+export const sdLine3d = tgpu.fn([vec3f, vec3f, vec3f], f32)((point, A, B) => {
+  const pa = sub(point, A);
+  const ba = sub(B, A);
   const h = max(0, min(1, dot(pa, ba) / dot(ba, ba)));
   return length(sub(pa, ba.mul(h)));
 });
 
 /**
  * Signed distance function for an infinite plane
- * @param p Point to evaluate
- * @param n Normal vector of the plane (must be normalized)
- * @param h Height/offset of the plane along the normal
+ * @param point Point to evaluate
+ * @param normal Normal vector of the plane (must be normalized)
+ * @param height Height/offset of the plane along the normal
  */
-export const sdPlane = tgpu.fn([vec3f, vec3f, f32], f32)((p, n, h) => {
-  return dot(p, n) + h;
-});
+export const sdPlane = tgpu.fn([vec3f, vec3f, f32], f32)(
+  (point, normal, height) => {
+    return dot(point, normal) + height;
+  },
+);
 
 /**
  * Signed distance function for a 3D capsule
- * @param p Point to evaluate
- * @param a First endpoint of the capsule segment
- * @param b Second endpoint of the capsule segment
+ * @param point Point to evaluate
+ * @param A First endpoint of the capsule segment
+ * @param B Second endpoint of the capsule segment
  * @param radius Radius of the capsule
  */
 export const sdCapsule = tgpu
-  .fn([vec3f, vec3f, vec3f, f32], f32)((p, a, b, radius) => {
-    const pa = sub(p, a);
-    const ba = sub(b, a);
+  .fn([vec3f, vec3f, vec3f, f32], f32)((point, A, B, radius) => {
+    const pa = sub(point, A);
+    const ba = sub(B, A);
     const h = saturate(dot(pa, ba) / dot(ba, ba));
     return length(sub(pa, ba.mul(h))) - radius;
   });

packages/typegpu-sdf/src/index.ts

@@ -1,5 +1,3 @@
-export * from './operators.ts';
-
 export {
   sdBezier,
   sdBezierApprox,
@@ -9,6 +7,7 @@ export {
   sdPie,
   sdRoundedBox2d,
 } from './2d.ts';
+
 export {
   sdBox3d,
   sdBoxFrame3d,
@@ -18,3 +17,12 @@ export {
   sdRoundedBox3d,
   sdSphere,
 } from './3d.ts';
+
+export {
+  opExtrudeX,
+  opExtrudeY,
+  opExtrudeZ,
+  opSmoothDifference,
+  opSmoothUnion,
+  opUnion,
+} from './operators.ts';