bitshifter / glam-rs / 36109957285

99%

Build Type

push

github

Committed by web-flow

Commit Message

feat: add `lerp_monotonic` for float vector types (#854)

# Objective

- Fixes #823.

`lerp` keeps the form `self * (1 - s) + rhs * s` because that is the
linear blend used by GLSL and WGSL. It is exact at `s == 1` even for
inputs that differ greatly in magnitude, but it is not monotonic in `s`
for nearly equal inputs and does not preserve equal inputs exactly,
which causes jitter when interpolating between values that are at rest.

## Solution

- Add `lerp_monotonic` to `Vec2`/`Vec3`/`Vec3A`/`Vec4` and
`DVec2`/`DVec3`/`DVec4`, using the monotonic form `self + (rhs - self) *
s`.
- Use a fused multiply-add on SIMD back-ends where available: SSE2 via
`m128_mul_add` (when the target has FMA) and NEON via `vfmaq_f32`.
- Leave `lerp` unchanged so existing callers keep the current rounding;
#823 is addressed by opting into `lerp_monotonic`.
- Change `FloatExt::lerp` to the form used by the vector methods. This
changes `remap`/`inverse_lerp` for infinite `t` from infinite to NaN.
- Document the form used by both methods and when to prefer each.

`lerp_monotonic` preserves equal inputs exactly and is monotonic in `s`.
Because `rhs - self` is evaluated first, it is less accurate when the
inputs differ greatly in magnitude and overflows for opposite-sign
extremes.

Quaternions are unchanged. Normalisation already removes the equal-input
jitter, and a monotone blend measured no benefit for `Quat`/`DQuat`.

## Tests

- `test_lerp_monotonic` covers the endpoints, exact preservation of
equal inputs, monotonicity in `s`, and both tradeoffs above.
- Added `FloatExt::lerp` big-difference coverage and updated
`test_remap`.

Coverage Stats

65 of 65 new or added lines in 15 files covered. (100.0%)

56 existing lines in 10 files now uncovered.

93249 of 94197 relevant lines covered (98.99%)

123508.2 hits per line