Build polish (#18)
Improve build process and documentation. Improved ray versus capsule accuracy. UI improvements
This commit is contained in:
parent
0c8ef46931
commit
69037feaba
19 changed files with 1719 additions and 158 deletions
65
docs/images/rc_parallel_crosssection.svg
Normal file
65
docs/images/rc_parallel_crosssection.svg
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 500" font-family="Segoe UI, Helvetica, Arial, sans-serif">
|
||||
<defs>
|
||||
<marker id="cBlue" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#1f6feb"/></marker>
|
||||
<marker id="cRed" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#d1242f"/></marker>
|
||||
<marker id="cGreen" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#1a7f37"/></marker>
|
||||
</defs>
|
||||
<rect width="640" height="500" fill="#ffffff"/>
|
||||
|
||||
<text x="24" y="32" font-size="17" font-weight="bold" fill="#222">Reduction to 2D: ray vs circle in the plane ⊥ to the axis</text>
|
||||
<text x="24" y="54" font-size="13" fill="#555">Project out the axis component. The infinite cylinder becomes a circle of radius r.</text>
|
||||
|
||||
<!-- cylinder cross-section -->
|
||||
<circle cx="270" cy="270" r="110" fill="#eaf1f8" stroke="#7fa8cc" stroke-width="1.8"/>
|
||||
<text x="270" y="408" font-size="12.5" fill="#3b6790" text-anchor="middle">circle of radius r</text>
|
||||
|
||||
<!-- axis point (out of page) -->
|
||||
<circle cx="270" cy="270" r="6" fill="none" stroke="#555" stroke-width="1.5"/>
|
||||
<circle cx="270" cy="270" r="1.6" fill="#555"/>
|
||||
<text x="284" y="287" font-size="12.5" fill="#555">a₁ (out of page)</text>
|
||||
|
||||
<!-- radius -->
|
||||
<line x1="270" y1="270" x2="380" y2="270" stroke="#333" stroke-width="1" stroke-dasharray="4 3"/>
|
||||
<text x="320" y="263" font-size="13" fill="#333">r</text>
|
||||
|
||||
<!-- sc: from axis to projected origin -->
|
||||
<line x1="270" y1="270" x2="68" y2="97" stroke="#d1242f" stroke-width="1.8" marker-end="url(#cRed)"/>
|
||||
<text x="150" y="166" font-size="13" fill="#d1242f">sc</text>
|
||||
|
||||
<!-- projected origin -->
|
||||
<circle cx="60" cy="90" r="4" fill="#1f6feb"/>
|
||||
<text x="40" y="80" font-size="12.5" fill="#1f6feb">projected origin</text>
|
||||
|
||||
<!-- perp: ray velocity in this plane -->
|
||||
<line x1="60" y1="90" x2="102" y2="158" stroke="#1a7f37" stroke-width="1.8" marker-end="url(#cGreen)"/>
|
||||
<text x="108" y="140" font-size="13" fill="#1a7f37">perp</text>
|
||||
|
||||
<!-- projected ray line through the circle -->
|
||||
<line x1="60" y1="90" x2="250" y2="402" stroke="#1f6feb" stroke-width="1.6" stroke-dasharray="6 4"/>
|
||||
|
||||
<!-- intersections -->
|
||||
<circle cx="161" cy="256" r="5" fill="#d1242f"/>
|
||||
<text x="36" y="262" font-size="12" fill="#d1242f">near root → tr</text>
|
||||
<circle cx="233" cy="373" r="5" fill="none" stroke="#333" stroke-width="1.6"/>
|
||||
<text x="243" y="380" font-size="12" fill="#555">far root</text>
|
||||
|
||||
<!-- legend / formulas panel -->
|
||||
<line x1="420" y1="118" x2="420" y2="402" stroke="#e2e2e2" stroke-width="1"/>
|
||||
<text x="440" y="135" font-size="12.5" fill="#333">Quantities used by the branch</text>
|
||||
<text x="440" y="165" font-size="12.5" fill="#d1242f">sc</text>
|
||||
<text x="462" y="165" font-size="12.5" fill="#444">= origin offset ⊥ axis, sc2 = |sc|²</text>
|
||||
<text x="440" y="190" font-size="12.5" fill="#1a7f37">perp</text>
|
||||
<text x="478" y="190" font-size="12.5" fill="#444">= a₂ − a₁₂ a₁ (ray dir ⊥ axis)</text>
|
||||
<text x="440" y="215" font-size="12.5" fill="#444">perp2 = |perp|² = det</text>
|
||||
<text x="440" y="240" font-size="12.5" fill="#444">β = sc · perp (signed, length)</text>
|
||||
<text x="440" y="265" font-size="12.5" fill="#444">γ = sc2 − r² ≥ 0 (origin outside)</text>
|
||||
<text x="440" y="290" font-size="12.5" fill="#444">disc = β² − perp2·γ</text>
|
||||
|
||||
<text x="440" y="325" font-size="12.5" fill="#8a5300">β ≥ 0 → moving away → miss</text>
|
||||
<text x="440" y="348" font-size="12.5" fill="#8a5300">disc < 0 → never reaches r → miss</text>
|
||||
<text x="440" y="378" font-size="12.5" fill="#1a7f37">otherwise: near root is the entry tr</text>
|
||||
|
||||
<!-- caption -->
|
||||
<text x="24" y="452" font-size="12.5" fill="#444">In this plane the axis is a single point, so the problem is exactly “ray from an outside point hits a circle.”</text>
|
||||
<text x="24" y="472" font-size="12.5" fill="#444">Solving here never divides by the tiny det, which is what made the general solve fail.</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 4.2 KiB |
55
docs/images/rc_parallel_quadratic.svg
Normal file
55
docs/images/rc_parallel_quadratic.svg
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 660 560" font-family="Segoe UI, Helvetica, Arial, sans-serif">
|
||||
<defs>
|
||||
<marker id="qEnd" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#333"/></marker>
|
||||
</defs>
|
||||
<rect width="660" height="560" fill="#ffffff"/>
|
||||
|
||||
<text x="24" y="32" font-size="17" font-weight="bold" fill="#222">The quadratic in tr, and the stable root</text>
|
||||
<text x="24" y="54" font-size="13" fill="#555">Squared distance from the moving ray point to the axis, as a function of ray distance tr.</text>
|
||||
|
||||
<!-- axes -->
|
||||
<line x1="100" y1="355" x2="610" y2="355" stroke="#333" stroke-width="1.4" marker-end="url(#qEnd)"/>
|
||||
<line x1="100" y1="355" x2="100" y2="70" stroke="#333" stroke-width="1.4" marker-end="url(#qEnd)"/>
|
||||
<text x="592" y="378" font-size="13" fill="#333">tr</text>
|
||||
<text x="60" y="80" font-size="12.5" fill="#333">dist²</text>
|
||||
|
||||
<!-- inside-cylinder shaded region -->
|
||||
<path d="M233,250 L280,284 L340,300 L400,284 L447,250 Z" fill="#fdecef"/>
|
||||
|
||||
<!-- r^2 level -->
|
||||
<line x1="100" y1="250" x2="590" y2="250" stroke="#d1242f" stroke-width="1.3" stroke-dasharray="6 4"/>
|
||||
<text x="596" y="254" font-size="13" fill="#d1242f">r²</text>
|
||||
|
||||
<!-- parabola -->
|
||||
<polyline points="120,90 160,159 200,215 233,250 280,284 340,300 400,284 447,250 480,215 520,159 560,90"
|
||||
fill="none" stroke="#1f6feb" stroke-width="2.2"/>
|
||||
|
||||
<!-- tr = 0 marker -->
|
||||
<line x1="120" y1="90" x2="120" y2="355" stroke="#bbb" stroke-width="1" stroke-dasharray="3 3"/>
|
||||
<circle cx="120" cy="90" r="4" fill="#1f6feb"/>
|
||||
<text x="70" y="92" font-size="12" fill="#1f6feb">sc2</text>
|
||||
<text x="104" y="372" font-size="12" fill="#555">tr = 0</text>
|
||||
|
||||
<!-- near root -->
|
||||
<line x1="233" y1="250" x2="233" y2="355" stroke="#d1242f" stroke-width="1" stroke-dasharray="3 3"/>
|
||||
<circle cx="233" cy="250" r="5" fill="#d1242f"/>
|
||||
<text x="206" y="372" font-size="12.5" fill="#d1242f">tr (entry)</text>
|
||||
|
||||
<!-- far root -->
|
||||
<circle cx="447" cy="250" r="5" fill="none" stroke="#333" stroke-width="1.6"/>
|
||||
<text x="455" y="246" font-size="12" fill="#555">far root (exit)</text>
|
||||
|
||||
<!-- vertex -->
|
||||
<circle cx="340" cy="300" r="3" fill="#1f6feb"/>
|
||||
<text x="300" y="320" font-size="11.5" fill="#555">closest approach</text>
|
||||
|
||||
<text x="150" y="205" font-size="11.5" fill="#a23">inside the cylinder (dist² < r²)</text>
|
||||
|
||||
<!-- explanation panel -->
|
||||
<rect x="40" y="405" width="580" height="138" rx="6" fill="#f6f8fa" stroke="#e2e6ea" stroke-width="1"/>
|
||||
<text x="56" y="428" font-size="13" font-weight="bold" fill="#222">Why tr = γ / (−β + √disc) rather than the textbook root</text>
|
||||
<text x="56" y="452" font-size="12.5" fill="#333">quadratic: perp2·tr² + 2β·tr + γ = 0 ( β = sc·perp, γ = sc2 − r², perp2 = det )</text>
|
||||
<text x="56" y="474" font-size="12.5" fill="#333">textbook near root: tr = (−β − √disc) / perp2</text>
|
||||
<text x="56" y="496" font-size="12.5" fill="#8a5300">ray → parallel: perp2 → 0 and √disc → |β| = −β ⇒ −β − √disc → 0 (cancellation), ÷ tiny perp2 → 0/0</text>
|
||||
<text x="56" y="520" font-size="12.5" fill="#1a7f37">used form: tr = γ / (−β + √disc) — denominator is a sum of two positives: no cancellation, no divide by det</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.5 KiB |
64
docs/images/rc_parallel_setup.svg
Normal file
64
docs/images/rc_parallel_setup.svg
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 410" font-family="Segoe UI, Helvetica, Arial, sans-serif">
|
||||
<defs>
|
||||
<marker id="mBlue" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#1f6feb"/></marker>
|
||||
<marker id="mGray" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#555"/></marker>
|
||||
<marker id="mRed" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#d1242f"/></marker>
|
||||
<marker id="mEnd" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#333"/></marker>
|
||||
<marker id="mStart" viewBox="0 0 10 10" refX="2" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M10,0 L0,5 L10,10 z" fill="#333"/></marker>
|
||||
</defs>
|
||||
<rect width="760" height="410" fill="#ffffff"/>
|
||||
|
||||
<text x="24" y="32" font-size="17" font-weight="bold" fill="#222">Near-parallel branch — side view (plane through the axis)</text>
|
||||
<text x="24" y="54" font-size="13" fill="#555">Ray almost parallel to the capsule axis; origin outside the infinite cylinder.</text>
|
||||
|
||||
<!-- infinite cylinder: walls and fill -->
|
||||
<rect x="60" y="185" width="645" height="130" fill="#eaf1f8"/>
|
||||
<line x1="60" y1="185" x2="705" y2="185" stroke="#7fa8cc" stroke-width="1.6"/>
|
||||
<line x1="60" y1="315" x2="705" y2="315" stroke="#7fa8cc" stroke-width="1.6"/>
|
||||
<text x="568" y="178" font-size="12.5" fill="#3b6790">infinite cylinder wall</text>
|
||||
|
||||
<!-- faint hemispherical caps to show the full capsule -->
|
||||
<path d="M120,185 A65,65 0 0 0 120,315" fill="none" stroke="#c4d2e0" stroke-width="1.4" stroke-dasharray="4 3"/>
|
||||
<path d="M600,185 A65,65 0 0 1 600,315" fill="none" stroke="#c4d2e0" stroke-width="1.4" stroke-dasharray="4 3"/>
|
||||
|
||||
<!-- capsule axis -->
|
||||
<line x1="60" y1="250" x2="120" y2="250" stroke="#555" stroke-width="1.5" stroke-dasharray="5 4"/>
|
||||
<line x1="120" y1="250" x2="600" y2="250" stroke="#555" stroke-width="2"/>
|
||||
<line x1="600" y1="250" x2="705" y2="250" stroke="#555" stroke-width="1.5" stroke-dasharray="5 4"/>
|
||||
<line x1="515" y1="250" x2="560" y2="250" stroke="#555" stroke-width="2" marker-end="url(#mGray)"/>
|
||||
<text x="520" y="242" font-size="12.5" fill="#555">a₁ (axis dir)</text>
|
||||
|
||||
<!-- endpoints -->
|
||||
<circle cx="120" cy="250" r="3.5" fill="#333"/>
|
||||
<text x="110" y="272" font-size="13" fill="#333">c₁</text>
|
||||
<circle cx="600" cy="250" r="3.5" fill="#333"/>
|
||||
<text x="592" y="272" font-size="13" fill="#333">c₂</text>
|
||||
|
||||
<!-- radius dimension -->
|
||||
<line x1="300" y1="250" x2="300" y2="185" stroke="#333" stroke-width="1" marker-start="url(#mStart)" marker-end="url(#mEnd)"/>
|
||||
<text x="306" y="222" font-size="13" fill="#333">r</text>
|
||||
|
||||
<!-- ray origin -->
|
||||
<circle cx="150" cy="110" r="4" fill="#1f6feb"/>
|
||||
<text x="86" y="103" font-size="12.5" fill="#1f6feb">ray origin</text>
|
||||
|
||||
<!-- sc: perpendicular offset axis -> origin -->
|
||||
<line x1="150" y1="250" x2="150" y2="116" stroke="#d1242f" stroke-width="1.6" marker-end="url(#mRed)"/>
|
||||
<text x="156" y="172" font-size="13" fill="#d1242f">sc</text>
|
||||
<text x="156" y="190" font-size="11.5" fill="#d1242f">|sc| > r</text>
|
||||
|
||||
<!-- the ray: origin (150,110) -> (690,235), grazes top wall at (474,185) -->
|
||||
<line x1="150" y1="110" x2="690" y2="235" stroke="#1f6feb" stroke-width="2" marker-end="url(#mBlue)"/>
|
||||
<text x="244" y="120" font-size="12.5" fill="#1f6feb">a₂ (ray dir), nearly ∥ a₁</text>
|
||||
|
||||
<!-- near hit on the cylinder wall -->
|
||||
<circle cx="474" cy="185" r="4.5" fill="#d1242f"/>
|
||||
<text x="430" y="170" font-size="12.5" fill="#d1242f">near hit on cylinder</text>
|
||||
|
||||
<!-- tr label along the ray -->
|
||||
<text x="392" y="150" font-size="13" fill="#1f6feb">tr (ray distance)</text>
|
||||
|
||||
<!-- captions -->
|
||||
<text x="24" y="384" font-size="12.5" fill="#444">det = 1 − (a₁·a₂)² ≈ 0 here, so the Cramer's-rule closest-point solve divides by ~0 and loses all precision.</text>
|
||||
<text x="24" y="402" font-size="12.5" fill="#444">Fix: intersect the ray with the infinite cylinder using only the parts perpendicular to the axis (next figure).</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 4.2 KiB |
283
docs/raycast_capsule_parallel.md
Normal file
283
docs/raycast_capsule_parallel.md
Normal file
|
|
@ -0,0 +1,283 @@
|
|||
# Ray vs capsule: the near-parallel branch
|
||||
|
||||
This note explains the `det < FLT_EPSILON` block inside `b3RayCastCapsule`
|
||||
(`src/capsule.c`). That block is the fallback used when the ray is almost parallel
|
||||
to the capsule axis, where the normal closest-point solve falls apart numerically.
|
||||
|
||||
```c
|
||||
float det = 1.0f - a12 * a12;
|
||||
if ( det < FLT_EPSILON )
|
||||
{
|
||||
// Ray nearly parallel to the capsule axis...
|
||||
b3Vec3 perp = b3MulSub( a2, a12, a1 ); // a2 - a12*a1
|
||||
float perp2 = b3LengthSquared( perp );
|
||||
|
||||
float beta = b3Dot( sc, perp );
|
||||
float gamma = sc2 - r * r;
|
||||
|
||||
float disc = beta * beta - perp2 * gamma;
|
||||
if ( beta >= 0.0f || disc < 0.0f )
|
||||
{
|
||||
return output; // miss
|
||||
}
|
||||
|
||||
tr = gamma / ( -beta + sqrtf( disc ) ); // near intersection distance
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. What is already known when we reach this block
|
||||
|
||||
`b3RayCastCapsule` casts a ray against a capsule (a cylinder capped by two
|
||||
hemispheres). By the time we reach line 232, several things are settled:
|
||||
|
||||
| symbol | meaning | code |
|
||||
|---|---|---|
|
||||
| `c1`, `c2` | the two capsule centers (ends of the core segment) | `shape->center1/2` |
|
||||
| `r` | capsule radius | `shape->radius` |
|
||||
| `axis` = `a1` | **unit** vector along the capsule axis, `c2 − c1` normalized | line 127 |
|
||||
| `s` | ray origin relative to `c1` | line 123 |
|
||||
| `u` | how far the origin projects along the axis, `dot(s, a1)` | line 130 |
|
||||
| `sc` | the part of `s` **perpendicular** to the axis (axis → origin) | line 136 |
|
||||
| `sc2` | `|sc|²`, squared distance from origin to the infinite axis | line 139 |
|
||||
| `a2` = `rayAxis` | **unit** ray direction | line 177 |
|
||||
| `a12` | `dot(a1, a2)`, the cosine of the angle between ray and axis | line 226 |
|
||||
|
||||
Two facts from the code above this branch matter a lot here:
|
||||
|
||||
- **The origin is outside the infinite cylinder.** The earlier `sc2 < r*r` test
|
||||
(line 142) already handled the inside case and returned. So here `sc2 ≥ r²`.
|
||||
- **The ray has nonzero length** and was not rejected by the projected-extent early
|
||||
out (line 187).
|
||||
|
||||
`det = 1 − a12²`. Since `a12` is the cosine of the angle between the two unit axes,
|
||||
`det = 1 − cos²θ = sin²θ`. It is the squared sine of the angle between the ray and
|
||||
the capsule axis.
|
||||
|
||||
---
|
||||
|
||||
## 2. Why a special case at all
|
||||
|
||||
The general path (the `else` branch, lines 258–288) solves for the closest points
|
||||
between the infinite ray and the infinite axis with Cramer's rule, dividing by
|
||||
`det`:
|
||||
|
||||
```c
|
||||
float invDet = 1.0f / det;
|
||||
float t1 = ( sa1 - a12 * sa2 ) * invDet;
|
||||
float t2 = ( a12 * sa1 - sa2 ) * invDet;
|
||||
```
|
||||
|
||||
When the ray is nearly parallel to the axis, `θ → 0`, so `det = sin²θ → 0` and
|
||||
`1/det → ∞`. Every quantity computed through `invDet` is multiplied by a huge,
|
||||
rounding-amplified number. The "closest point on the axis" becomes meaningless, and
|
||||
a ray that is slowly closing in on the capsule side can be missed entirely.
|
||||
|
||||
`FLT_EPSILON` (≈ 1.19e-7) is the cutoff, and the threshold is not arbitrary. `det`
|
||||
is computed as `1 − a12*a12` with `a12 ≈ 1`, a subtraction of two nearly-equal
|
||||
numbers. Its absolute rounding error is about one ulp of 1.0, i.e. `FLT_EPSILON`. So
|
||||
once the true `det` shrinks to `~FLT_EPSILON`, the *computed* `det` has essentially no
|
||||
correct bits left, and `1/det` (> 8 million here) faithfully amplifies that garbage.
|
||||
Below the cutoff we branch to a method that **never forms `1/det`**.
|
||||
|
||||

|
||||
|
||||
---
|
||||
|
||||
## 3. The idea: collapse the axis and solve ray-vs-circle
|
||||
|
||||
When the ray is almost parallel to the axis, the interesting motion is not *along*
|
||||
the axis, it is the slow drift *across* it. So drop the axis component entirely and
|
||||
work in the 2D plane perpendicular to the axis.
|
||||
|
||||
In that plane:
|
||||
|
||||
- The infinite cylinder becomes a **circle of radius `r`**.
|
||||
- The capsule axis collapses to a **single point** (the circle's center).
|
||||
- The ray origin projects to a point at distance `√sc2 > r` (outside the circle).
|
||||
- The ray's direction projects to the in-plane velocity `perp`.
|
||||
|
||||
The 3D "ray vs infinite cylinder" problem becomes the flat "ray from an outside
|
||||
point hits a circle" problem, which has no `det` in it.
|
||||
|
||||

|
||||
|
||||
---
|
||||
|
||||
## 4. Line by line
|
||||
|
||||
### `perp = b3MulSub( a2, a12, a1 )` → `a2 − a12·a1`
|
||||
|
||||
This is the ray direction with its along-axis part removed: the component of `a2`
|
||||
perpendicular to the axis. The comment notes you could also get a perpendicular
|
||||
vector with a cross product, but subtracting the parallel part is cheaper and is
|
||||
exactly the in-plane velocity we want. It is dimensionless (built from unit vectors).
|
||||
|
||||
A useful identity: because `a1` and `a2` are unit vectors,
|
||||
|
||||
```
|
||||
|perp|² = |a2 − a12·a1|²
|
||||
= 1 − 2·a12² + a12²
|
||||
= 1 − a12²
|
||||
= det
|
||||
```
|
||||
|
||||
So **`perp2` is mathematically the same tiny number as `det`.** That is fine — we
|
||||
never *divide* by it in the end (see §6); it only appears multiplied into `disc`,
|
||||
where being tiny does no harm.
|
||||
|
||||
### `perp2 = b3LengthSquared( perp )`
|
||||
|
||||
The squared length of that in-plane velocity. Equal to `det`, as just shown.
|
||||
|
||||
### `beta = b3Dot( sc, perp )`
|
||||
|
||||
Project the origin's perpendicular offset `sc` onto the in-plane velocity `perp`.
|
||||
`sc` has length units and `perp` is dimensionless, so **`beta` carries length units.**
|
||||
|
||||
Its sign is what matters: `beta` is half the rate of change of the squared distance
|
||||
to the axis at the start of the ray. `beta < 0` means the projected point is moving
|
||||
**toward** the axis; `beta ≥ 0` means it is moving **away** (or tangent).
|
||||
|
||||
### `gamma = sc2 − r*r`
|
||||
|
||||
How far outside the cylinder the origin sits, in squared-length units. Because the
|
||||
origin is outside, **`gamma ≥ 0`.**
|
||||
|
||||
### `disc = beta*beta − perp2*gamma`
|
||||
|
||||
The discriminant of the quadratic derived in §5. Sign units are length². If it is
|
||||
negative, the (infinite) ray never gets within `r` of the axis.
|
||||
|
||||
### The early out: `if ( beta >= 0.0f || disc < 0.0f ) return`
|
||||
|
||||
Two distinct ways to miss:
|
||||
|
||||
- **`beta ≥ 0`** — the origin is already outside and the ray is heading away from the
|
||||
axis (or running tangent to it). It will never come back, so no side hit.
|
||||
- **`disc < 0`** — the ray's closest approach to the axis is still more than `r` away.
|
||||
The infinite cylinder is never reached.
|
||||
|
||||
### `tr = gamma / ( -beta + sqrtf( disc ) )`
|
||||
|
||||
The distance along the ray (in length units, since `a2` is a unit vector) to the
|
||||
**near** intersection with the infinite cylinder — where the ray first crosses into
|
||||
the circle. The unusual algebraic form is deliberate; §6 explains it.
|
||||
|
||||
---
|
||||
|
||||
## 5. Where the quadratic comes from
|
||||
|
||||
Walk a point along the ray and ask when its perpendicular distance to the axis equals
|
||||
`r`. Relative to `c1`, the ray point at distance `tr` is `s + tr·a2`. Its component
|
||||
perpendicular to the axis is the sum of the perpendicular parts of each term:
|
||||
|
||||
```
|
||||
perp_offset(tr) = sc + tr·perp
|
||||
```
|
||||
|
||||
(`sc` is the perpendicular part of `s`; `perp` is the perpendicular part of `a2`.)
|
||||
Set its squared length equal to `r²`:
|
||||
|
||||
```
|
||||
|sc + tr·perp|² = r²
|
||||
sc2 + 2·tr·(sc·perp) + tr²·|perp|² = r²
|
||||
perp2·tr² + 2·beta·tr + gamma = 0 (gamma = sc2 − r²)
|
||||
```
|
||||
|
||||
A plain quadratic `A·tr² + B·tr + C = 0` with `A = perp2`, `B = 2·beta`, `C = gamma`.
|
||||
Its discriminant (over 4) is `beta² − perp2·gamma`, i.e. `disc`. The two roots are the
|
||||
entry and exit distances of the ray through the infinite cylinder; we want the near
|
||||
(entry) one.
|
||||
|
||||

|
||||
|
||||
---
|
||||
|
||||
## 6. Why the root is written `gamma / (−beta + √disc)`
|
||||
|
||||
The textbook near root of `perp2·tr² + 2·beta·tr + gamma = 0` is
|
||||
|
||||
```
|
||||
tr = (−beta − √disc) / perp2
|
||||
```
|
||||
|
||||
This is a trap exactly in the regime we are in:
|
||||
|
||||
- `perp2 = det` is tiny, so dividing by it amplifies error.
|
||||
- As the ray approaches parallel, `perp2·gamma → 0`, so `disc → beta²` and
|
||||
`√disc → |beta|`. Since we already passed the `beta ≥ 0` test, here `beta < 0`, so
|
||||
`|beta| = −beta`. The numerator `−beta − √disc → −beta − (−beta) = 0`: a
|
||||
**catastrophic cancellation**. The expression collapses to `0 / 0`.
|
||||
|
||||
Multiply numerator and denominator by the conjugate `(−beta + √disc)` (equivalently,
|
||||
use the product-of-roots identity `tr_near · tr_far = gamma / perp2`):
|
||||
|
||||
```
|
||||
tr = gamma / (−beta + √disc)
|
||||
```
|
||||
|
||||
Now the denominator is a **sum of two positive quantities** (`−beta > 0` and
|
||||
`√disc ≥ 0`), so there is no cancellation, and `perp2` has vanished from the
|
||||
expression — no division by the tiny determinant. Because `gamma ≥ 0` and the
|
||||
denominator is `> 0`, the result satisfies `tr ≥ 0` automatically.
|
||||
|
||||
This mirrors the same trick used elsewhere in the file: `b3RayCastSphere` and the
|
||||
`else` branch here both intersect relative to the closest point precisely to dodge
|
||||
this kind of round-off.
|
||||
|
||||
**Limiting sanity check.** If the ray is *exactly* parallel (`a12 = 1`), then
|
||||
`perp = a2 − a1 = 0`, so `perp2 = 0` and `beta = dot(sc, 0) = 0`. The `beta ≥ 0`
|
||||
test fires and we return a miss — the correct answer, since a parallel ray that
|
||||
starts outside the cylinder can only ever hit an endcap, never the side. The
|
||||
division is never reached, so `perp2 = 0` is harmless.
|
||||
|
||||
---
|
||||
|
||||
## 7. Units recap
|
||||
|
||||
Everything stays dimensionally consistent, which is a quick way to sanity-check the
|
||||
algebra:
|
||||
|
||||
| quantity | units |
|
||||
|---|---|
|
||||
| `perp`, `perp2`, `a12`, `det` | dimensionless |
|
||||
| `beta = sc·perp` | length |
|
||||
| `gamma = sc2 − r²` | length² |
|
||||
| `disc = beta² − perp2·gamma` | length² |
|
||||
| `tr = gamma / (−beta + √disc)` | length² / length = **length** |
|
||||
|
||||
`tr` is a true distance along the ray, not a fraction — the same convention the rest
|
||||
of the function uses before the final `fraction` is formed.
|
||||
|
||||
---
|
||||
|
||||
## 8. What happens to `tr` afterward
|
||||
|
||||
Both branches (parallel and general) converge on the same tail code, which treats
|
||||
`tr` as a candidate hit distance on the **infinite** cylinder and then decides what
|
||||
the capsule actually does there:
|
||||
|
||||
1. **Range check** (line 291): reject if `tr < 0` or beyond the ray's max length.
|
||||
2. **Map to the axis** (line 297): `tc = u + tr·a12` is where the hit projects along
|
||||
the axis, measured from `c1`.
|
||||
3. **Endcap handoff**: if `tc < 0` the hit is past the `c1` end, so cast against the
|
||||
sphere at `c1`; if `tc > length`, cast against the sphere at `c2`. This is how the
|
||||
near-parallel case still reports endcap hits correctly.
|
||||
4. **Side hit** (lines 324–333): otherwise the hit is genuinely on the cylindrical
|
||||
wall. Compute the point `c1 + s + tr·a2`, the outward normal (the point minus its
|
||||
projection onto the axis, normalized), and the fraction.
|
||||
|
||||
So this whole block has one job: produce a numerically trustworthy `tr` for the
|
||||
cylinder intersection when the ray is nearly parallel. The shared tail does the rest.
|
||||
|
||||
---
|
||||
|
||||
## Figures
|
||||
|
||||
The three SVGs referenced above live in `docs/images/`:
|
||||
|
||||
- `rc_parallel_setup.svg` — side view: why the parallel case is hard.
|
||||
- `rc_parallel_crosssection.svg` — the 2D reduction to ray-vs-circle.
|
||||
- `rc_parallel_quadratic.svg` — the quadratic, its roots, and the cancellation fix.
|
||||
Loading…
Reference in a new issue