Add unit structs for each ease function

[greeble-dev]

Objective

When a user wants a specific ease function, make it less verbose and more efficient.

Background

EaseFunction is a flexible and data-driven way to apply easing. But that has a price when a user only wants a specific ease function:

EaseFunction::SmoothStep.sample(t);

This is a little bit verbose, but the main problem is efficiency - it calls the general EaseFunction::eval, which won't be inlined. That means an unnecessary branch inside eval, and can increase code size since it pulls in all ease functions even though the user might only require one. As far as I can tell this is true even with opt-level = 3 and lto = "fat".

; EaseFunction::SmoothStep.sample_unchecked(t)
lea rcx, [rip + __unnamed_2] ; Load the disciminant for EaseFunction::SmoothStep.
movaps xmm1, xmm0
jmp bevy_math::curve::easing::EaseFunction::eval    

Solution

The PR adds unit structs that implement Curve<f32> for each ease function. This is less verbose, and the compiler can make accurate predictions about inlining.

SmoothStep.sample(t);

; SmoothStep.sample_unchecked(t)
movaps xmm1, xmm0
addss xmm1, xmm0
movss xmm2, dword ptr [rip + __real@40400000] ; 3.0
subss xmm2, xmm1
mulss xmm2, xmm0
mulss xmm0, xmm2

In a microbenchmark this is around 4x faster, but could be less in real code. If inlining permits auto-vectorization then it's 20-50x faster, but that's a niche case.

Adding unit structs is also a small boost to discoverability - the unit struct can be found in VS Code via "Go To Symbol" -> "smoothstep", which doesn't find EaseFunction::SmoothStep.

Concerns

• While the unit structs have advantages, they add a lot of API surface area.
• The unit structs can't be used with EasingCurve, which requires EaseFunction.
  • This might confuse users and limit optimisation.
    • Wrong: EasingCurve::new(a, b, SmoothStep).
    • Right: EasingCurve::new(a, b, EaseFunction::SmoothStep).
  • In theory EasingCurve could be changed to support any Curve<f32> or a more limited trait.
  • But that's likely to be a breaking change and raises questions around reflection and reliability.
• The unit structs don't have serialization.
  • I don't know much about the motivations/requirements for serialization.
• Each unit struct duplicates the documentation of EaseFunction.
  • This is convenient for the user, but awkward for anyone updating the code.
  • Maybe better if each unit struct points to the matching EaseFunction.
  • Might also make the module page less intimidating (see screenshot).

Testing

cargo test -p bevy_math

[ElliottjPierce]

This is pretty much exactly what I've been hoping for. Thanks for doing it!

As for the extra API surface, this is 100% worth it. It gives significant performance wins in my noise lib, basically for free. Also note that not all easing functions are zero-sized, differentiable, etc. We could build on this with enums like SmallEaseFunction, DifferentiableEaseFunction, and SmoothEaseFunction (where the derivative is 0 at t=0 and t=1). That's what I'd use ultimately for my noise lib to allow users to change the ease at runtime. It would also open up the possibility for a Smooth trait (WIP name).

So the API surface is not only worth it, but it's a blocker for these tools.

As for the docs, for now, I see no problem duplicating it. But if we add the other 3 enums above, this would become annoying. It doesn't have to be this pr, but I would either have the enum docs point back to the unit struct docs, or create a macro for each function that expands to the desired docs. Or just dump it all in module docs and refer to that. I've seen other crates do that sometimes.

Anyway, that's my thoughts. Excited to see this land!

[ElliottjPierce]

This isn't a bad thing to have, but all the functions just call each other, so I don't really see the need for this.

[greeble-dev]

I added it to defend against copy and paste errors, although in retrospect the test was vulnerable to the same error.

I've updated with a macro based test that should be less vulnerable. Also open to removing it if there's a consensus that it's unnecessary.