Linear interpolation

[clarfonthey]

#71016 is a previous attempt at implementation that was closed by the author. I decided to reuse the feature request issue (#71015) as a tracking issue. A member of the rust-lang org will have to edit the original post to be formatted correctly as I am not the issue's original author.

The common name lerp is used because it is the term used by most code in a wide variety of contexts; it also happens to be the recently chosen name of the function that was added to C++20.

To ensure symmetry as a method, this breaks the usual ordering of the method from lerp(a, b, t) to t.lerp(a, b). This makes the most sense to me personally, and there will definitely be discussion before stabilisation anyway.

Implementing lerp "correctly" is very dififcult even though it's a very common building-block used in all sorts of applications. A good prior reading is this proposal for the C++20 lerp which talks about the various guarantees, which I've simplified down to:

1. Exactness: (0.0).lerp(start, end) == start and (1.0).lerp(start, end) == end
2. Consistency: anything.lerp(x, x) == x
3. Monotonicity: once you go up don't go down

Fun story: the version provided in that proposal, from what I understand, isn't actually monotonic.

I messed around with a lot of different lerp implementations because I kind of got a bit obsessed and I ultimately landed on one that uses the fused mul_add instruction. Floating-point lerp lore is hard to come by, so, just trust me when I say that this ticks all the boxes. I'm only 90% certain that it's monotonic, but I'm sure that people who care deeply about this will be there to discuss before stabilisation.

The main reason for using mul_add is that, in general, it ticks more boxes with fewer branches to be "correct." Although it will be slower on architectures without the fused mul_add, that's becoming more and more rare and I have a feeling that most people who will find themselves needing lerp will also have an efficient mul_add instruction available.

[rust-highfive]

r? @m-ou-se

(rust-highfive has picked a reviewer for you, use r? to override)

[the8472]

Implementing lerp "correctly" is very dififcult

Then it could benefit from a bunch of test-cases. Are there existing libraries which have collected tricky edge-cases?

[clarfonthey]

You're right about adding tests. I'll try and add a couple over the course of the next week.

[m-ou-se]

To ensure symmetry as a method, this breaks the usual ordering of the method from lerp(a, b, t) to t.lerp(a, b). This makes the most sense to me personally, and there will definitely be discussion before stabilisation anyway.

I'm not entirely convinced of the t.lerp(a, b) signature. But other signatures (lerp(a, b, t), (a, b).lerp(t), a.lerp(b, t), etc.) also have their problems. So I'd be okay with adding this as unstable, so we can try out how this signature works and get some more feedback.

I decided to reuse the feature request issue (#71015) as a tracking issue. A member of the rust-lang org will have to edit the original post to be formatted correctly as I am not the issue's original author.

Can you open a new tracking issue? Re-using existing issues has some downsides (including the one you mentioned).

[m-ou-se]

Can we give any guarantees about non-finite values? E.g. that any nan wil result in a nan result, and/or that if only one of the values is infinite, the result will be that infinite value.

[clarfonthey]

So, I was considering doing the full list of guarantees that C++ provides, which are:

• If isfinite(a) && isfinite(b):
  • If t == 0, the result is equal to a.
  • If t == 1, the result is equal to b.
  • If t >= 0 && t <= 1, the result is finite.
• If isfinite(t) && a == b, the result is equal to a.
• If isfinite(t) || (!isnan(t) && b-a != 0), the result is not NaN.
• Let CMP(x,y) be 1 if x > y, -1 if x < y, and 0 otherwise. For any t1 and t2, the product of CMP(lerp(a, b, t2), lerp(a, b, t1)), CMP(t2, t1), and CMP(b, a) is non-negative. (That is, lerp is monotonic.)

But I figured that it might potentially limit what kinds of implementations we allow. I'll try adding tests for these (and comment them out if they don't work) and maybe we can hash it out in the tracking issue.

[clarfonthey]

So, I added another tracking issue, included potential topics of discussion (including calling convention, guarantees), added some extra tests for the C++ guarantees, and modified the docs. Hopefully everything should be good to merge now, but let me know if you think we should have something else!

[m-ou-se]

@clarfonthey I see you marked the comments as resolved, but the code doesn't seem to be updated. Did your changes not get pushed?

[clarfonthey]

I… did not. Now it is.

@rustbot label -S-waiting-on-author +S-waiting-on-review

[m-ou-se]

Thanks!

@bors r+

[bors]

📌 Commit 525d760 has been approved by m-ou-se

[jethrogb]

This test fails on targets that use Rust's libm

[dependencies]
libm = "0.2"

mod libc {
    extern "C" {
        pub fn fma(x: f64, y: f64, z: f64) -> f64;
    }
}
fn main() {
    let x = -(1.0 - f64::EPSILON);
    println!("{:?}", libm::fma(x, f64::MIN, f64::MIN));
    println!("{:?}", unsafe { libc::fma(x, f64::MIN, f64::MIN) });
}

Notice you get two different results

Not sure if the test failure is a result of a bug in libm or an implementation error in lerp.

[tmandry]

This PR caused crater regressions in the following projects (that were already using lerp via an extension trait):

• rainbows
• ai-race
• rayn
• bestagon
• lininterp
• uints

cc #87749

Not planning to open an issue since we allow this sort of breakage, and it's a small number of crates.

[clarfonthey]

cc #86269 since that's the tracking issue for this feature, where such incompatibilities were being discussed.

[mqudsi]

For posterity, this was reverted in 6b449b4 (IMHO, the commit should have included a mention of this PR to help those of us chasing down ghosts) as it was causing unstable_name_collisions warnings while there was no consensus on what the final api should look like.

[topolarity]

A quick note to anyone who might come through here (like me) on a lerp-implementation search.

This implementation is not monotonic after all. A counter example:

f32::lerp(3.6e-07, 0.723387479, 0.929327905) = 0.7233876
f32::lerp(4.8e-07, 0.723387479, 0.929327905) = 0.72338754

[clarfonthey]

@topolarity FWIW @CAD97 also was testing this out and had been experimenting in the original tracking issue, if you're curious. It turns out that a proper lerp implementation is quite hard to do; makes you wish that there were just an instruction for it that did the whole thing correctly.