@typegpu/geometry Improve line rendering APIs

Author: deluksic

apps/typegpu-docs/src/examples/geometry/lines-combinations/index.ts

@@ -5,9 +5,10 @@ import {
   joinSlot,
   lineSegmentIndices,
   lineSegmentLeftIndices,
-  lineSegmentVariableWidth,
+  polylineVariableWidth,
   lineSegmentWireframeIndices,
   startCapSlot,
+  arrowCapParamsSlot,
 } from '@typegpu/geometry';
 import tgpu, { type ColorAttachment } from 'typegpu';
 import {
@@ -140,7 +141,7 @@ const mainVertex = tgpu.vertexFn({
     return Out();
   }
 
-  const result = lineSegmentVariableWidth(vertexIndex, A, B, C, D, MAX_JOIN_COUNT);
+  const result = polylineVariableWidth(A, B, C, D, vertexIndex, MAX_JOIN_COUNT);
 
   return {
     outPos: vec4f(result.vertexPosition * result.w, 0, result.w),
@@ -287,6 +288,7 @@ function createPipelines() {
     .with(startCapSlot, startCap)
     .with(endCapSlot, endCap)
     .with(testCaseSlot, testCase)
+    .with(arrowCapParamsSlot, { length: 7.5, width: 1.75, slant: -0.8 })
     .createRenderPipeline({
       vertex: mainVertex,
       fragment: mainFragment,
@@ -303,6 +305,7 @@ function createPipelines() {
     .with(startCapSlot, startCap)
     .with(endCapSlot, endCap)
     .with(testCaseSlot, testCase)
+    .with(arrowCapParamsSlot, { length: 7.5, width: 1.75, slant: -0.8 })
     .createRenderPipeline({
       vertex: mainVertex,
       fragment: outlineFragment,

apps/typegpu-docs/src/examples/simulation/wind-map/index.ts

@@ -3,7 +3,7 @@ import {
   endCapSlot,
   LineControlPoint,
   lineSegmentIndices,
-  lineSegmentVariableWidth,
+  polylineVariableWidth,
   startCapSlot,
 } from '@typegpu/geometry';
 import tgpu from 'typegpu';
@@ -177,7 +177,7 @@ const mainVertex = tgpu.vertexFn({
     radius: lineWidth(f32(trailIndexOriginal + 3) / (TRAIL_LENGTH - 1)),
   });
 
-  const result = lineSegmentVariableWidth(vertexIndex, A, B, C, D, MAX_JOIN_COUNT);
+  const result = polylineVariableWidth(A, B, C, D, vertexIndex, MAX_JOIN_COUNT);
 
   return {
     outPos: vec4f(result.vertexPosition, 0, 1),

apps/typegpu-docs/tests/individual-example-tests/global-wind-map.test.ts

@@ -156,23 +156,22 @@ describe('global wind map example', () => {
         v: vec2f,
         d: vec2f,
         fw: vec2f,
+        cross: vec2f,
         start: vec2f,
         end: vec2f,
-        shouldJoin: bool,
-        isCap: bool,
       }
 
       fn rot90ccw(v: vec2f) -> vec2f {
         return vec2f(-(v.y), v.x);
       }
 
+      fn rot90cw(v: vec2f) -> vec2f {
+        return vec2f(v.y, -(v.x));
+      }
+
       fn arrow(join: JoinInput, joinVertexIndex: u32, _maxJoinCount: u32) -> vec2f {
-        var bw = -(normalize(join.fw));
-        var vert = rot90ccw(bw);
-        let sgn = sign(cross2d(bw, join.d));
-        var svert = (vert * sgn);
-        var v0 = (svert + (bw * 7.5f));
-        var v1 = (v0 + ((bw + svert) * 1.5f));
+        var v0 = (join.cross - (join.fw * 7.5f));
+        var v1 = (v0 + ((join.cross - (join.fw * 0.8f)) * 1.5f));
         if ((joinVertexIndex == 0u)) {
           return (join.C.position + (v0 * join.C.radius));
         }
@@ -183,15 +182,7 @@ describe('global wind map example', () => {
       }
 
       fn butt(join: JoinInput, _joinVertexIndex: u32, _maxJoinCount: u32) -> vec2f {
-        var fw = normalize(join.fw);
-        var vert = rot90ccw(fw);
-        let sgn = sign(cross2d(fw, join.d));
-        var svert = (vert * sgn);
-        return (join.C.position + (svert * join.C.radius));
-      }
-
-      fn rot90cw(v: vec2f) -> vec2f {
-        return vec2f(v.y, -(v.x));
+        return (join.C.position + (join.cross * join.C.radius));
       }
 
       fn bisectCcw(a: vec2f, b: vec2f) -> vec2f {
@@ -228,7 +219,7 @@ describe('global wind map example', () => {
         return (join.C.position + (dir * join.C.radius));
       }
 
-      fn lineSegmentVariableWidth(vertexIndex: u32, A: LineControlPoint, B: LineControlPoint, C: LineControlPoint, D: LineControlPoint, maxJoinCount: u32) -> LineSegmentOutput {
+      fn polylineVariableWidth(A: LineControlPoint, B: LineControlPoint, C: LineControlPoint, D: LineControlPoint, vertexIndex: u32, maxJoinCount: u32) -> LineSegmentOutput {
         var AB = (B.position - A.position);
         var BC = (C.position - B.position);
         var DC = (C.position - D.position);
@@ -271,24 +262,38 @@ describe('global wind map example', () => {
         let coreVertexIndex = ((vertexIndex - 2u) & 3u);
         let joinVertexIndex = ((vertexIndex - 2u) >> 2u);
         var join = JoinInput();
+        var isCap = false;
+        var shouldJoin = false;
+        var normBC = normalize(BC);
+        var normCB = -(normBC);
+        var crossL = rot90ccw(normBC);
+        var crossR = rot90cw(normBC);
         if ((coreVertexIndex == 0u)) {
-          join = JoinInput(B, v2, (*d2), CB, (*d2), select(eAB.nL, (*d3), (joinB.isHairpin || isCapB)), joinB.shouldJoinL, isCapB);
+          isCap = isCapB;
+          shouldJoin = joinB.shouldJoinL;
+          join = JoinInput(B, v2, (*d2), normCB, crossL, (*d2), select(eAB.nL, (*d3), (joinB.isHairpin || isCapB)));
         }
         else {
           if ((coreVertexIndex == 1u)) {
-            join = JoinInput(B, v3, (*d3), CB, select(eAB.nR, (*d2), (joinB.isHairpin || isCapB)), (*d3), joinB.shouldJoinR, isCapB);
+            isCap = isCapB;
+            shouldJoin = joinB.shouldJoinR;
+            join = JoinInput(B, v3, (*d3), normCB, crossR, select(eAB.nR, (*d2), (joinB.isHairpin || isCapB)), (*d3));
           }
           else {
             if ((coreVertexIndex == 2u)) {
-              join = JoinInput(C, v4, (*d4), BC, (*d4), select(eDC.nL, (*d5), (joinC.isHairpin || isCapC)), joinC.shouldJoinL, isCapC);
+              isCap = isCapC;
+              shouldJoin = joinC.shouldJoinL;
+              join = JoinInput(C, v4, (*d4), normBC, crossR, (*d4), select(eDC.nL, (*d5), (joinC.isHairpin || isCapC)));
             }
             else {
-              join = JoinInput(C, v5, (*d5), BC, select(eDC.nR, (*d4), (joinC.isHairpin || isCapC)), (*d5), joinC.shouldJoinR, isCapC);
+              isCap = isCapC;
+              shouldJoin = joinC.shouldJoinR;
+              join = JoinInput(C, v5, (*d5), normBC, crossL, select(eDC.nR, (*d4), (joinC.isHairpin || isCapC)), (*d5));
             }
           }
         }
         var vertexPosition = join.v;
-        if (join.isCap) {
+        if (isCap) {
           if ((coreVertexIndex < 2u)) {
             vertexPosition = arrow(join, joinVertexIndex, maxJoinCount);
           }
@@ -297,7 +302,7 @@ describe('global wind map example', () => {
           }
         }
         else {
-          if (join.shouldJoin) {
+          if (shouldJoin) {
             vertexPosition = round_1(join, joinVertexIndex, maxJoinCount);
           }
         }
@@ -323,7 +328,7 @@ describe('global wind map example', () => {
         var B = LineControlPoint((*particle).positions[iB], lineWidth((f32((trailIndexOriginal + 1u)) / 19f)));
         var C = LineControlPoint((*particle).positions[iC], lineWidth((f32((trailIndexOriginal + 2u)) / 19f)));
         var D = LineControlPoint((*particle).positions[iD], lineWidth((f32((trailIndexOriginal + 3u)) / 19f)));
-        var result = lineSegmentVariableWidth(vertexIndex, A, B, C, D, 3u);
+        var result = polylineVariableWidth(A, B, C, D, vertexIndex, 3u);
         return mainVertex_Output(vec4f(result.vertexPosition, 0f, 1f), result.vertexPosition, (f32(trailIndexOriginal) / 19f));
       }
 

apps/typegpu-docs/tests/individual-example-tests/lines-combinations.test.ts

@@ -129,10 +129,9 @@ describe('lines combinations example', () => {
         v: vec2f,
         d: vec2f,
         fw: vec2f,
+        cross: vec2f,
         start: vec2f,
         end: vec2f,
-        shouldJoin: bool,
-        isCap: bool,
       }
 
       fn rot90ccw(v: vec2f) -> vec2f {
@@ -177,7 +176,7 @@ describe('lines combinations example', () => {
         return (join.C.position + (dir * join.C.radius));
       }
 
-      fn lineSegmentVariableWidth(vertexIndex: u32, A: LineControlPoint, B: LineControlPoint, C: LineControlPoint, D: LineControlPoint, maxJoinCount: u32) -> LineSegmentOutput {
+      fn polylineVariableWidth(A: LineControlPoint, B: LineControlPoint, C: LineControlPoint, D: LineControlPoint, vertexIndex: u32, maxJoinCount: u32) -> LineSegmentOutput {
         var AB = (B.position - A.position);
         var BC = (C.position - B.position);
         var DC = (C.position - D.position);
@@ -220,24 +219,38 @@ describe('lines combinations example', () => {
         let coreVertexIndex = ((vertexIndex - 2u) & 3u);
         let joinVertexIndex = ((vertexIndex - 2u) >> 2u);
         var join = JoinInput();
+        var isCap = false;
+        var shouldJoin = false;
+        var normBC = normalize(BC);
+        var normCB = -(normBC);
+        var crossL = rot90ccw(normBC);
+        var crossR = rot90cw(normBC);
         if ((coreVertexIndex == 0u)) {
-          join = JoinInput(B, v2, (*d2), CB, (*d2), select(eAB.nL, (*d3), (joinB.isHairpin || isCapB)), joinB.shouldJoinL, isCapB);
+          isCap = isCapB;
+          shouldJoin = joinB.shouldJoinL;
+          join = JoinInput(B, v2, (*d2), normCB, crossL, (*d2), select(eAB.nL, (*d3), (joinB.isHairpin || isCapB)));
         }
         else {
           if ((coreVertexIndex == 1u)) {
-            join = JoinInput(B, v3, (*d3), CB, select(eAB.nR, (*d2), (joinB.isHairpin || isCapB)), (*d3), joinB.shouldJoinR, isCapB);
+            isCap = isCapB;
+            shouldJoin = joinB.shouldJoinR;
+            join = JoinInput(B, v3, (*d3), normCB, crossR, select(eAB.nR, (*d2), (joinB.isHairpin || isCapB)), (*d3));
           }
           else {
             if ((coreVertexIndex == 2u)) {
-              join = JoinInput(C, v4, (*d4), BC, (*d4), select(eDC.nL, (*d5), (joinC.isHairpin || isCapC)), joinC.shouldJoinL, isCapC);
+              isCap = isCapC;
+              shouldJoin = joinC.shouldJoinL;
+              join = JoinInput(C, v4, (*d4), normBC, crossR, (*d4), select(eDC.nL, (*d5), (joinC.isHairpin || isCapC)));
             }
             else {
-              join = JoinInput(C, v5, (*d5), BC, select(eDC.nR, (*d4), (joinC.isHairpin || isCapC)), (*d5), joinC.shouldJoinR, isCapC);
+              isCap = isCapC;
+              shouldJoin = joinC.shouldJoinR;
+              join = JoinInput(C, v5, (*d5), normBC, crossL, select(eDC.nR, (*d4), (joinC.isHairpin || isCapC)), (*d5));
             }
           }
         }
         var vertexPosition = join.v;
-        if (join.isCap) {
+        if (isCap) {
           if ((coreVertexIndex < 2u)) {
             vertexPosition = round_1(join, joinVertexIndex, maxJoinCount);
           }
@@ -246,7 +259,7 @@ describe('lines combinations example', () => {
           }
         }
         else {
-          if (join.shouldJoin) {
+          if (shouldJoin) {
             vertexPosition = round_1(join, joinVertexIndex, maxJoinCount);
           }
         }
@@ -263,7 +276,7 @@ describe('lines combinations example', () => {
         if (((((A.radius < 0f) || (B.radius < 0f)) || (C.radius < 0f)) || (D.radius < 0f))) {
           return mainVertex_Output();
         }
-        var result = lineSegmentVariableWidth(vertexIndex, A, B, C, D, 6u);
+        var result = polylineVariableWidth(A, B, C, D, vertexIndex, 6u);
         return mainVertex_Output(vec4f((result.vertexPosition * result.w), 0f, result.w), result.vertexPosition, vec2f(0f, select(0f, 1f, (vertexIndex > 1u))), instanceIndex, vertexIndex, 0u);
       }
 

packages/typegpu-geometry/LinesExplanation.md

@@ -11,13 +11,13 @@ limited. It allows only single pixel width lines! Good for debugging, but
 terrible for anything user-facing. With TypeGPU, it is easier than ever to
 create reusable, composable libraries. And now, high quality line rendering is
 just an `npm install` away! This article serves as documentation for the library
-source code. It should also give you an appreciation for how complex line
-rendering can actually get.
+source code. It should also give you an appreciation for just how complex line
+rendering can get!
 
 ## Goals
 
 As already described in many online articles, drawing lines using GPU can be
-notoriously difficult to do well. There are many different, sometimes
+quite involved. There are many different, sometimes
 conflicting, goals you might have when it comes to line rendering. Following
 goals are considered by this article and implementation:
 
@@ -34,74 +34,74 @@ goals are considered by this article and implementation:
 ### Non-goals
 
 - maximum performance
-- triangle counts
-- minimizing quad-overdraw (having max-area triangles)
+- minimizing triangle counts
+- minimizing quad-overdraw (producing max-area triangles)
 
-## Single Line Segment
+## Single Line
 
-We start with a single segment. Two vertices, `C1` and `C2` (C for center), and
-radii `r1` and `r2`.
+We start with a single line. Two control points, $A$ and $B$ with
+radii $r_A$ and $r_B$.
 
-![-](./assets/basic.svg)
+<img src="./assets/basic.svg" style="display: block; margin: 0 auto; width: 100%; max-width: 400px;" />
 
-Two most important directions to compute are `nL` and `nR`, left (CCW) and right
-(CW) external tangent **normals**.
+Two most important directions to compute are $\hat{n_L}$ and $\hat{n_R}$, left (CCW) and right
+(CW) external tangent **normals** (with respect to $\vec{AB}$).
 
-```ts
-x = (r1 - r2) / distance(C1, C2);
-y = sqrt(1 - x ^ 2);
-nL = vec2(x, y);
-nR = vec2(x, -y);
+```math
+x = \frac{r1 - r2}{\|{AB}\|} \\
+y = \sqrt{1 - x ^ 2} \\
+\hat{n_L} = (x, y) \\
+\hat{n_R} = (x, -y)
 ```
 
-NOTE: in `externalNormals.ts`, additional care is taken to return `nL` and `nR`
-rotated relative to the `distance` vector between the circles.
+NOTE: in `externalNormals.ts`, additional care is taken to return $\hat{n_L}$ and $\hat{n_R}$
+rotated relative to $\vec{AB}$.
 
 Using these two directions, it is trivial to compute all other points necessary
 for triangulation:
 
-![-](./assets/triangulation.svg)
+<img src="./assets/triangulation.svg" style="display: block; margin: 0 auto; width: 100%; max-width: 400px;" />
 
-**Core** (red) vertices 0-5 are:
+**Core** 🔴 vertices 0-5 are:
 
-```ts
-v0 = C1;
-v1 = C2;
-v2 = C1 + r1 * nL;
-v3 = C1 + r1 * nR;
-v4 = C2 + r2 * nR;
-v5 = C2 + r2 * nL;
+```math
+{\color{red} v_0} = A \\
+{\color{red} v_1} = B \\
+{\color{red} v_2} = A + r_A n_L \\
+{\color{red} v_3} = A + r_A n_R \\
+{\color{red} v_4} = B + r_B n_R \\
+{\color{red} v_5} = B + r_B n_L
 ```
 
-Vertices 6+ are called `join` vertices in the code, however they are used for
+Vertices 6+ are called `join` vertices in the code, but they are used for
 both `joins` and `caps`. Their computation will depend on the type of `join` or
-`cap` used. Here, a `round` cap is shown. It is important to note their
+`cap` used. Here, an (incomplete) `round` cap is shown. It is important to note their
 distribution. Just like the 4 core vertices 2-5, they are distributed CCW
 progressively further away from their respective core vertex. This makes it
 possible to dynamically vary the number of segments in the joins, while using
 the same index buffer. Each join vertex is identified by:
 
-- `coreVertexIndex` which core vertex it belongs to (`v2,v6,v10=0`,
-  `v3,v7,v11=1` etc.)
-- `joinVertexIndex` number of vertices away from the core vertex (`v2=0`,
-  `v6=1`, `v10=2`)
+- `coreVertexIndex` which core vertex it belongs to
+- `joinVertexIndex` number of vertices away from the core vertex
 
 ```ts
-coreVertexIndex = (vertexIndex - 2) % 4;
-joinVertexIndex = (vertexIndex - 2) / 4;
+const coreVertexIndex = (vertexIndex - 2) % 4;
+const joinVertexIndex = (vertexIndex - 2) / 4;
 ```
 
-NOTE: instead of the slow `% 4` and `/ 4`, real code uses `& 0b11` and `>> 2`.
-Probably can be optimized away by wgsl compilers, but you never know.
+NOTE: real code uses `& 0b11` and `>> 2` instead of div.
 
-Cap functions can then use `joinVertexIndex` and `maxJoinCount` to compute the
+Cap functions can then use `joinVertexIndex / MAX_JOIN_COUNT` to compute the
 final position of each join vertex.
 
 If all you want to do is render single line segments, you should use
-`singleLineSegmentVariableWidth(A, B)` function. It does exactly what we just
+`lineVariableWidth(A, B, vertexIndex, MAX_JOIN_COUNT)` function. It does exactly what we just
 discussed and nothing more.
 
-## Joining Line Segments
+## Polylines
+
+Easy part is done. Joining segments into polylines is what makes line rendering interesting! First, lets consider how in theory the joining should work. A polyline consists of many joined segments. Each segment's geometry depends on its two neighboring segments. This is why the function accepts 4 consecutive control points $A, B, C, D$ with radii $r_A, r_B, r_C, r_D$.
+
+<img src="./assets/polyline-basic.svg" style="display: block; margin: 0 auto; width: 100%; max-width: 400px;" />
 
-Easy part is done. Joining segments is where the difficulties and edge cases
-start. First, lets consider how in theory the joining should work:
+The segment that actually gets drawn is $BC$, shaded in $\color{blue} blue$. The function needs $A$ and $D$ in order to compute the join geometry, but it does not create the red shaded regions. Darker shaded regions highlight the join area. Notice that only half the join is handled by each segment.