bevy/crates/bevy_math/src/ops.rs
Zachary Harrold a2b14983f4 Upgrade to Glam 0.29.3 and Simplify Feature Gating (#18638)
- Fixes #18397
- Supersedes #18474
- Simplifies 0.16 migration

- Upgrade to Glam 0.29.3, which has backported the `nostd-libm` feature.
- Expose a similar feature in `bevy_math` and enable it in
`bevy_internal`, allowing `bevy_math`, `bevy_input`, and
`bevy_transform` to be unconditional dependencies again.

- CI

---

- This includes `libm` as a dependency, but this was already the case in
the common scenario where `rand` or many other features were enabled.
Considering `libm` is an official Rust crate, it's a very low-risk
dependency to unconditionally include.
- For users who do not want `libm` included, simply import Bevy's
subcrates directly, since `bevy_math/nostd-libm` will not be enabled.
- I know we are _very_ late in the RC cycle for 0.16, but this has a
substantial impact on the usability of `bevy` that I consider worth
including.
2025-03-31 22:36:16 +02:00

647 lines
19 KiB
Rust

//! This mod re-exports the correct versions of floating-point operations with
//! unspecified precision in the standard library depending on whether the `libm`
//! crate feature is enabled.
//!
//! All the functions here are named according to their versions in the standard
//! library.
//!
//! It also provides `no_std` compatible alternatives to certain floating-point
//! operations which are not provided in the [`core`] library.
// Note: There are some Rust methods with unspecified precision without a `libm`
// equivalent:
// - `f32::powi` (integer powers)
// - `f32::log` (logarithm with specified base)
// - `f32::abs_sub` (actually unsure if `libm` has this, but don't use it regardless)
//
// Additionally, the following nightly API functions are not presently integrated
// into this, but they would be candidates once standardized:
// - `f32::gamma`
// - `f32::ln_gamma`
#[cfg(all(not(feature = "libm"), feature = "std"))]
#[expect(
clippy::disallowed_methods,
reason = "Many of the disallowed methods are disallowed to force code to use the feature-conditional re-exports from this module, but this module itself is exempt from that rule."
)]
mod std_ops {
/// Raises a number to a floating point power.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn powf(x: f32, y: f32) -> f32 {
f32::powf(x, y)
}
/// Returns `e^(self)`, (the exponential function).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn exp(x: f32) -> f32 {
f32::exp(x)
}
/// Returns `2^(self)`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn exp2(x: f32) -> f32 {
f32::exp2(x)
}
/// Returns the natural logarithm of the number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn ln(x: f32) -> f32 {
f32::ln(x)
}
/// Returns the base 2 logarithm of the number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn log2(x: f32) -> f32 {
f32::log2(x)
}
/// Returns the base 10 logarithm of the number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn log10(x: f32) -> f32 {
f32::log10(x)
}
/// Returns the cube root of a number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn cbrt(x: f32) -> f32 {
f32::cbrt(x)
}
/// Compute the distance between the origin and a point `(x, y)` on the Euclidean plane.
/// Equivalently, compute the length of the hypotenuse of a right-angle triangle with other sides having length `x.abs()` and `y.abs()`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn hypot(x: f32, y: f32) -> f32 {
f32::hypot(x, y)
}
/// Computes the sine of a number (in radians).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn sin(x: f32) -> f32 {
f32::sin(x)
}
/// Computes the cosine of a number (in radians).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn cos(x: f32) -> f32 {
f32::cos(x)
}
/// Computes the tangent of a number (in radians).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn tan(x: f32) -> f32 {
f32::tan(x)
}
/// Computes the arcsine of a number. Return value is in radians in
/// the range [-pi/2, pi/2] or NaN if the number is outside the range
/// [-1, 1].
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn asin(x: f32) -> f32 {
f32::asin(x)
}
/// Computes the arccosine of a number. Return value is in radians in
/// the range [0, pi] or NaN if the number is outside the range
/// [-1, 1].
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn acos(x: f32) -> f32 {
f32::acos(x)
}
/// Computes the arctangent of a number. Return value is in radians in the
/// range [-pi/2, pi/2];
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn atan(x: f32) -> f32 {
f32::atan(x)
}
/// Computes the four-quadrant arctangent of `y` and `x` in radians.
///
/// * `x = 0`, `y = 0`: `0`
/// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
/// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
/// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn atan2(y: f32, x: f32) -> f32 {
f32::atan2(y, x)
}
/// Simultaneously computes the sine and cosine of the number, `x`. Returns
/// `(sin(x), cos(x))`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn sin_cos(x: f32) -> (f32, f32) {
f32::sin_cos(x)
}
/// Returns `e^(self) - 1` in a way that is accurate even if the
/// number is close to zero.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn exp_m1(x: f32) -> f32 {
f32::exp_m1(x)
}
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
/// the operations were performed separately.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn ln_1p(x: f32) -> f32 {
f32::ln_1p(x)
}
/// Hyperbolic sine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn sinh(x: f32) -> f32 {
f32::sinh(x)
}
/// Hyperbolic cosine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn cosh(x: f32) -> f32 {
f32::cosh(x)
}
/// Hyperbolic tangent function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn tanh(x: f32) -> f32 {
f32::tanh(x)
}
/// Inverse hyperbolic sine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn asinh(x: f32) -> f32 {
f32::asinh(x)
}
/// Inverse hyperbolic cosine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn acosh(x: f32) -> f32 {
f32::acosh(x)
}
/// Inverse hyperbolic tangent function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn atanh(x: f32) -> f32 {
f32::atanh(x)
}
}
#[cfg(any(feature = "libm", all(feature = "nostd-libm", not(feature = "std"))))]
mod libm_ops {
/// Raises a number to a floating point power.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn powf(x: f32, y: f32) -> f32 {
libm::powf(x, y)
}
/// Returns `e^(self)`, (the exponential function).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn exp(x: f32) -> f32 {
libm::expf(x)
}
/// Returns `2^(self)`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn exp2(x: f32) -> f32 {
libm::exp2f(x)
}
/// Returns the natural logarithm of the number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn ln(x: f32) -> f32 {
// This isn't documented in `libm` but this is actually the base e logarithm.
libm::logf(x)
}
/// Returns the base 2 logarithm of the number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn log2(x: f32) -> f32 {
libm::log2f(x)
}
/// Returns the base 10 logarithm of the number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn log10(x: f32) -> f32 {
libm::log10f(x)
}
/// Returns the cube root of a number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn cbrt(x: f32) -> f32 {
libm::cbrtf(x)
}
/// Compute the distance between the origin and a point `(x, y)` on the Euclidean plane.
///
/// Equivalently, compute the length of the hypotenuse of a right-angle triangle with other sides having length `x.abs()` and `y.abs()`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn hypot(x: f32, y: f32) -> f32 {
libm::hypotf(x, y)
}
/// Computes the sine of a number (in radians).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn sin(x: f32) -> f32 {
libm::sinf(x)
}
/// Computes the cosine of a number (in radians).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn cos(x: f32) -> f32 {
libm::cosf(x)
}
/// Computes the tangent of a number (in radians).
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn tan(x: f32) -> f32 {
libm::tanf(x)
}
/// Computes the arcsine of a number. Return value is in radians in
/// the range [-pi/2, pi/2] or NaN if the number is outside the range
/// [-1, 1].
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn asin(x: f32) -> f32 {
libm::asinf(x)
}
/// Computes the arccosine of a number. Return value is in radians in
/// Hyperbolic tangent function.
///
/// Precision is specified when the `libm` feature is enabled.
/// the range [0, pi] or NaN if the number is outside the range
/// [-1, 1].
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn acos(x: f32) -> f32 {
libm::acosf(x)
}
/// Computes the arctangent of a number. Return value is in radians in the
/// range [-pi/2, pi/2];
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn atan(x: f32) -> f32 {
libm::atanf(x)
}
/// Computes the four-quadrant arctangent of `y` and `x` in radians.
///
/// * `x = 0`, `y = 0`: `0`
/// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
/// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
/// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn atan2(y: f32, x: f32) -> f32 {
libm::atan2f(y, x)
}
/// Simultaneously computes the sine and cosine of the number, `x`. Returns
/// `(sin(x), cos(x))`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn sin_cos(x: f32) -> (f32, f32) {
libm::sincosf(x)
}
/// Returns `e^(self) - 1` in a way that is accurate even if the
/// number is close to zero.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn exp_m1(x: f32) -> f32 {
libm::expm1f(x)
}
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
/// the operations were performed separately.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn ln_1p(x: f32) -> f32 {
libm::log1pf(x)
}
/// Hyperbolic sine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn sinh(x: f32) -> f32 {
libm::sinhf(x)
}
/// Hyperbolic cosine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn cosh(x: f32) -> f32 {
libm::coshf(x)
}
/// Hyperbolic tangent function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn tanh(x: f32) -> f32 {
libm::tanhf(x)
}
/// Inverse hyperbolic sine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn asinh(x: f32) -> f32 {
libm::asinhf(x)
}
/// Inverse hyperbolic cosine function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn acosh(x: f32) -> f32 {
libm::acoshf(x)
}
/// Inverse hyperbolic tangent function.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn atanh(x: f32) -> f32 {
libm::atanhf(x)
}
}
#[cfg(all(any(feature = "libm", feature = "nostd-libm"), not(feature = "std")))]
mod libm_ops_for_no_std {
//! Provides standardized names for [`f32`] operations which may not be
//! supported on `no_std` platforms.
//! On `no_std` platforms, this forwards to the implementations provided
//! by [`libm`].
/// Calculates the least nonnegative remainder of `self (mod rhs)`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn rem_euclid(x: f32, y: f32) -> f32 {
let result = libm::remainderf(x, y);
// libm::remainderf has a range of -y/2 to +y/2
if result < 0. {
result + y
} else {
result
}
}
/// Computes the absolute value of x.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn abs(x: f32) -> f32 {
libm::fabsf(x)
}
/// Returns the square root of a number.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn sqrt(x: f32) -> f32 {
libm::sqrtf(x)
}
/// Returns a number composed of the magnitude of `x` and the sign of `y`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn copysign(x: f32, y: f32) -> f32 {
libm::copysignf(x, y)
}
/// Returns the nearest integer to `x`. If a value is half-way between two integers, round away from `0.0`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn round(x: f32) -> f32 {
libm::roundf(x)
}
/// Returns the largest integer less than or equal to `x`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn floor(x: f32) -> f32 {
libm::floorf(x)
}
/// Returns the smallest integer greater than or equal to `x`.
///
/// Precision is specified when the `libm` feature is enabled.
#[inline(always)]
pub fn ceil(x: f32) -> f32 {
libm::ceilf(x)
}
/// Returns the fractional part of `x`.
///
/// This function always returns the precise result.
#[inline(always)]
pub fn fract(x: f32) -> f32 {
libm::modff(x).0
}
}
#[cfg(feature = "std")]
#[expect(
clippy::disallowed_methods,
reason = "Many of the disallowed methods are disallowed to force code to use the feature-conditional re-exports from this module, but this module itself is exempt from that rule."
)]
mod std_ops_for_no_std {
//! Provides standardized names for [`f32`] operations which may not be
//! supported on `no_std` platforms.
//! On `std` platforms, this forwards directly to the implementations provided
//! by [`std`].
/// Calculates the least nonnegative remainder of `x (mod y)`.
///
/// The result of this operation is guaranteed to be the rounded infinite-precision result.
#[inline(always)]
pub fn rem_euclid(x: f32, y: f32) -> f32 {
f32::rem_euclid(x, y)
}
/// Computes the absolute value of x.
///
/// This function always returns the precise result.
#[inline(always)]
pub fn abs(x: f32) -> f32 {
f32::abs(x)
}
/// Returns the square root of a number.
///
/// The result of this operation is guaranteed to be the rounded infinite-precision result.
/// It is specified by IEEE 754 as `squareRoot` and guaranteed not to change.
#[inline(always)]
pub fn sqrt(x: f32) -> f32 {
f32::sqrt(x)
}
/// Returns a number composed of the magnitude of `x` and the sign of `y`.
///
/// Equal to `x` if the sign of `x` and `y` are the same, otherwise equal to `-x`. If `x` is a
/// `NaN`, then a `NaN` with the sign bit of `y` is returned. Note, however, that conserving the
/// sign bit on `NaN` across arithmetical operations is not generally guaranteed.
#[inline(always)]
pub fn copysign(x: f32, y: f32) -> f32 {
f32::copysign(x, y)
}
/// Returns the nearest integer to `x`. If a value is half-way between two integers, round away from `0.0`.
///
/// This function always returns the precise result.
#[inline(always)]
pub fn round(x: f32) -> f32 {
f32::round(x)
}
/// Returns the largest integer less than or equal to `x`.
///
/// This function always returns the precise result.
#[inline(always)]
pub fn floor(x: f32) -> f32 {
f32::floor(x)
}
/// Returns the smallest integer greater than or equal to `x`.
///
/// This function always returns the precise result.
#[inline(always)]
pub fn ceil(x: f32) -> f32 {
f32::ceil(x)
}
/// Returns the fractional part of `x`.
///
/// This function always returns the precise result.
#[inline(always)]
pub fn fract(x: f32) -> f32 {
f32::fract(x)
}
}
#[cfg(any(feature = "libm", all(feature = "nostd-libm", not(feature = "std"))))]
pub use libm_ops::*;
#[cfg(all(not(feature = "libm"), feature = "std"))]
pub use std_ops::*;
#[cfg(feature = "std")]
pub use std_ops_for_no_std::*;
#[cfg(all(any(feature = "libm", feature = "nostd-libm"), not(feature = "std")))]
pub use libm_ops_for_no_std::*;
#[cfg(all(
not(feature = "libm"),
not(feature = "std"),
not(feature = "nostd-libm")
))]
compile_error!("Either the `libm`, `std`, or `nostd-libm` feature must be enabled.");
/// This extension trait covers shortfall in determinacy from the lack of a `libm` counterpart
/// to `f32::powi`. Use this for the common small exponents.
pub trait FloatPow {
/// Squares the f32
fn squared(self) -> Self;
/// Cubes the f32
fn cubed(self) -> Self;
}
impl FloatPow for f32 {
#[inline]
fn squared(self) -> Self {
self * self
}
#[inline]
fn cubed(self) -> Self {
self * self * self
}
}