Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-12-25 20:43:07 +00:00
Code Issues Projects Releases Packages Wiki Activity
bevy/crates/bevy_math/src/lib.rs

67 lines
1.9 KiB
Rust
Raw Normal View History

Make `feature(doc_auto_cfg)` work (#12642) # Objective - In #12366 `![cfg_attr(docsrs, feature(doc_auto_cfg))] `was added. But to apply it it needs `--cfg=docsrs` in rustdoc-args. ## Solution - Apply `--cfg=docsrs` to all crates and CI. I also added `[package.metadata.docs.rs]` to all crates to avoid adding code behind a feature and forget adding the metadata. Before: ![Screenshot 2024-03-22 at 00 51 57](https://github.com/bevyengine/bevy/assets/104745335/6a9dfdaa-8710-4784-852b-5f9b74e3522c) After: ![Screenshot 2024-03-22 at 00 51 32](https://github.com/bevyengine/bevy/assets/104745335/c5bd6d8e-8ddb-45b3-b844-5ecf9f88961c)
2024-03-23 02:22:52 +00:00
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
Forbid unsafe in most crates in the engine (#12684) # Objective Resolves #3824. `unsafe` code should be the exception, not the norm in Rust. It's obviously needed for various use cases as it's interfacing with platforms and essentially running the borrow checker at runtime in the ECS, but the touted benefits of Bevy is that we are able to heavily leverage Rust's safety, and we should be holding ourselves accountable to that by minimizing our unsafe footprint. ## Solution Deny `unsafe_code` workspace wide. Add explicit exceptions for the following crates, and forbid it in almost all of the others. * bevy_ecs - Obvious given how much unsafe is needed to achieve performant results * bevy_ptr - Works with raw pointers, even more low level than bevy_ecs. * bevy_render - due to needing to integrate with wgpu * bevy_window - due to needing to integrate with raw_window_handle * bevy_utils - Several unsafe utilities used by bevy_ecs. Ideally moved into bevy_ecs instead of made publicly usable. * bevy_reflect - Required for the unsafe type casting it's doing. * bevy_transform - for the parallel transform propagation * bevy_gizmos - For the SystemParam impls it has. * bevy_assets - To support reflection. Might not be required, not 100% sure yet. * bevy_mikktspace - due to being a conversion from a C library. Pending safe rewrite. * bevy_dynamic_plugin - Inherently unsafe due to the dynamic loading nature. Several uses of unsafe were rewritten, as they did not need to be using them: * bevy_text - a case of `Option::unchecked` could be rewritten as a normal for loop and match instead of an iterator. * bevy_color - the Pod/Zeroable implementations were replaceable with bytemuck's derive macros.
2024-03-27 03:30:08 +00:00
#![forbid(unsafe_code)]
Set the logo and favicon for all of Bevy's published crates (#12696) # Objective Currently the built docs only shows the logo and favicon for the top level `bevy` crate. This makes views like https://docs.rs/bevy_ecs/latest/bevy_ecs/ look potentially unrelated to the project at first glance. ## Solution Reproduce the docs attributes for every crate that Bevy publishes. Ideally this would be done with some workspace level Cargo.toml control, but AFAICT, such support does not exist.
2024-03-25 18:52:50 +00:00
#![doc(
html_logo_url = "https://bevyengine.org/assets/icon.png",
html_favicon_url = "https://bevyengine.org/assets/icon.png"
)]
Make `feature(doc_auto_cfg)` work (#12642) # Objective - In #12366 `![cfg_attr(docsrs, feature(doc_auto_cfg))] `was added. But to apply it it needs `--cfg=docsrs` in rustdoc-args. ## Solution - Apply `--cfg=docsrs` to all crates and CI. I also added `[package.metadata.docs.rs]` to all crates to avoid adding code behind a feature and forget adding the metadata. Before: ![Screenshot 2024-03-22 at 00 51 57](https://github.com/bevyengine/bevy/assets/104745335/6a9dfdaa-8710-4784-852b-5f9b74e3522c) After: ![Screenshot 2024-03-22 at 00 51 32](https://github.com/bevyengine/bevy/assets/104745335/c5bd6d8e-8ddb-45b3-b844-5ecf9f88961c)
2024-03-23 02:22:52 +00:00
Document `bevy_math` (#4591) # Objective - Part of #3492 ## Solution - Document the `bevy_math` crate and add the `#![warn(missing_docs)]` lint.
2022-04-26 18:23:29 +00:00
//! Provides math types and functionality for the Bevy game engine.
//!
//! The commonly used types are vectors like [`Vec2`] and [`Vec3`],
Export and register `Mat2`. (#5324) Export and register a missing type from `glam`. Reflect impls were already present, but not registered. Co-authored-by: devil-ira <justthecooldude@gmail.com>
2022-07-15 22:37:06 +00:00
//! matrices like [`Mat2`], [`Mat3`] and [`Mat4`] and orientation representations
Document `bevy_math` (#4591) # Objective - Part of #3492 ## Solution - Document the `bevy_math` crate and add the `#![warn(missing_docs)]` lint.
2022-04-26 18:23:29 +00:00
//! like [`Quat`].
Reduce the size of MeshUniform to improve performance (#9416) # Objective - Significantly reduce the size of MeshUniform by only including necessary data. ## Solution Local to world, model transforms are affine. This means they only need a 4x3 matrix to represent them. `MeshUniform` stores the current, and previous model transforms, and the inverse transpose of the current model transform, all as 4x4 matrices. Instead we can store the current, and previous model transforms as 4x3 matrices, and we only need the upper-left 3x3 part of the inverse transpose of the current model transform. This change allows us to reduce the serialized MeshUniform size from 208 bytes to 144 bytes, which is over a 30% saving in data to serialize, and VRAM bandwidth and space. ## Benchmarks On an M1 Max, running `many_cubes -- sphere`, main is in yellow, this PR is in red: <img width="1484" alt="Screenshot 2023-08-11 at 02 36 43" src="https://github.com/bevyengine/bevy/assets/302146/7d99c7b3-f2bb-4004-a8d0-4c00f755cb0d"> A reduction in frame time of ~14%. --- ## Changelog - Changed: Redefined `MeshUniform` to improve performance by using 4x3 affine transforms and reconstructing 4x4 matrices in the shader. Helper functions were added to `bevy_pbr::mesh_functions` to unpack the data. `affine_to_square` converts the packed 4x3 in 3x4 matrix data to a 4x4 matrix. `mat2x4_f32_to_mat3x3` converts the 3x3 in mat2x4 + f32 matrix data back into a 3x3. ## Migration Guide Shader code before: ``` var model = mesh[instance_index].model; ``` Shader code after: ``` #import bevy_pbr::mesh_functions affine_to_square var model = affine_to_square(mesh[instance_index].model); ```
2023-08-15 06:00:23 +00:00
mod affine3;
Introduce AspectRatio struct (#10368) # Objective - Fix an inconsistency in the calculation of aspect ratio's. - Fixes #10288 ## Solution - Created an intermediate `AspectRatio` struct, as suggested in the issue. This is currently just used in any places where aspect ratio calculations happen, to prevent doing it wrong. In my and @mamekoro 's opinion, it would be better if this was used instead of a normal `f32` in various places, but I didn't want to make too many changes to begin with. ## Migration Guide - Anywhere where you are currently expecting a f32 when getting aspect ratios, you will now receive a `AspectRatio` struct. this still holds the same value. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-12-17 02:01:26 +00:00
mod aspect_ratio;
Implement bounding volume types (#10946) # Objective Implement bounding volume trait and the 4 types from https://github.com/bevyengine/bevy/issues/10570. I will add intersection tests in a future PR. ## Solution Implement mostly everything as written in the issue, except: - Intersection is no longer a method on the bounding volumes, but a separate trait. - I implemented a `visible_area` since it's the most common usecase to care about the surface that could collide with cast rays. - Maybe we want both? --- ## Changelog - Added bounding volume types to bevy_math --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-01-10 23:18:51 +00:00
pub mod bounding;
Make `bevy_math::common_traits` public (#14245) # Objective Fixes #14243 ## Solution `bevy_math::common_traits` is now a public module.
2024-07-09 17:16:47 +00:00
pub mod common_traits;
Added CompassQuadrant and CompassOctant as per #13647 (#13653) # Objective Implements #13647 ## Solution Created two enums, CompassQuadrant and CompassOctant inside compass.rs with impls To and From Dir2. Used dir.to_angle().to_degrees() and matched against the resulting value. I could have skipped to_degrees() and matched against the radian value, but I thought this was more readable. I'm probably wrong lol. ## Testing Tested various dirs to compass variations. --- --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-06-03 19:46:50 +00:00
mod compass;
Add generic cubic splines to `bevy_math` (#7683) # Objective - Make cubic splines more flexible and more performant - Remove the existing spline implementation that is generic over many degrees - This is a potential performance footgun and adds type complexity for negligible gain. - Add implementations of: - Bezier splines - Cardinal splines (inc. Catmull-Rom) - B-Splines - Hermite splines https://user-images.githubusercontent.com/2632925/221780519-495d1b20-ab46-45b4-92a3-32c46da66034.mp4 https://user-images.githubusercontent.com/2632925/221780524-2b154016-699f-404f-9c18-02092f589b04.mp4 https://user-images.githubusercontent.com/2632925/221780525-f934f99d-9ad4-4999-bae2-75d675f5644f.mp4 ## Solution - Implements the concept that splines are curve generators (e.g. https://youtu.be/jvPPXbo87ds?t=3488) via the `CubicGenerator` trait. - Common splines are bespoke data types that implement this trait. This gives us flexibility to add custom spline-specific methods on these types, while ultimately all generating a `CubicCurve`. - All splines generate `CubicCurve`s, which are a chain of precomputed polynomial coefficients. This means that all splines have the same evaluation cost, as the calculations for determining position, velocity, and acceleration are all identical. In addition, `CubicCurve`s are simply a list of `CubicSegment`s, which are evaluated from t=0 to t=1. This also means cubic splines of different type can be chained together, as ultimately they all are simply a collection of `CubicSegment`s. - Because easing is an operation on a singe segment of a Bezier curve, we can simply implement easing on `Beziers` that use the `Vec2` type for points. Higher level crates such as `bevy_ui` can wrap this in a more ergonomic interface as needed. ### Performance Measured on a desktop i5 8600K (6-year-old CPU): - easing: 2.7x faster (19ns) - cubic vec2 position sample: 1.5x faster (1.8ns) - cubic vec3 position sample: 1.5x faster (2.6ns) - cubic vec3a position sample: 1.9x faster (1.4ns) On a laptop i7 11800H: - easing: 16ns - cubic vec2 position sample: 1.6ns - cubic vec3 position sample: 2.3ns - cubic vec3a position sample: 1.2ns --- ## Changelog - Added a generic cubic curve trait, and implementation for Cardinal splines (including Catmull-Rom), B-Splines, Beziers, and Hermite Splines. 2D cubic curve segments also implement easing functionality for animation.
2023-03-03 22:06:42 +00:00
pub mod cubic_splines;
A Curve trait for general interoperation — Part I (#14630) # Objective This PR implements part of the [Curve RFC](https://github.com/bevyengine/rfcs/blob/main/rfcs/80-curve-trait.md). See that document for motivation, objectives, etc. ## Solution For purposes of reviewability, this PR excludes the entire part of the RFC related to taking multiple samples, resampling, and interpolation generally. (This means the entire `cores` submodule is also excluded.) On the other hand, the entire `Interval` type and all of the functional `Curve` adaptors are included. ## Testing Test modules are included and can be run locally (but they are also included in CI). --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-08-09 14:19:44 +00:00
pub mod curve;
Add `Direction3dA` and move direction types out of `primitives` (#12018) # Objective Split up from #12017, add an aligned version of `Direction3d` for SIMD, and move direction types out of `primitives`. ## Solution Add `Direction3dA` and move direction types into a new `direction` module. --- ## Migration Guide The `Direction2d`, `Direction3d`, and `InvalidDirectionError` types have been moved out of `bevy::math::primitives`. Before: ```rust use bevy::math::primitives::Direction3d; ``` After: ```rust use bevy::math::Direction3d; ``` --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-02-26 13:57:49 +00:00
mod direction;
Move FloatOrd into bevy_math (#12732) # Objective - Fixes #12712 ## Solution - Move the `float_ord.rs` file to `bevy_math` - Change any `bevy_utils::FloatOrd` statements to `bevy_math::FloatOrd` --- ## Changelog - Moved `FloatOrd` from `bevy_utils` to `bevy_math` ## Migration Guide - References to `bevy_utils::FloatOrd` should be changed to `bevy_math::FloatOrd`
2024-03-27 18:30:11 +00:00
mod float_ord;
Improve isometry docs (#14318) # Objective Fixes #14308. #14269 added the `Isometry2d` and `Isometry3d` types, but they don't have usage examples or much documentation on what the types actually represent or what they may be useful for. In addition, their module is public and the types are not re-exported at the crate root, unlike all the other core math types like Glam's types, direction types, and `Rot2`. ## Solution Improve the documentation of `Isometry2d` and `Isometry3d`, explaining what they represent and can be useful for, along with doc examples on common high-level usage. I also made the way the types are exported consistent with other core math types. This does add some duplication, but I personally think having good docs for this is valuable, and people are also less likely to look at the module-level docs than type-level docs.
2024-07-15 16:05:33 +00:00
mod isometry;
Make bevy_math's `libm` feature use `libm` for all `f32`methods with unspecified precision (#14693) # Objective Closes #14474 Previously, the `libm` feature of bevy_math would just pass the same feature flag down to glam. However, bevy_math itself had many uses of floating-point arithmetic with unspecified precision. For example, `f32::sin_cos` and `f32::powi` have unspecified precision, which means that the exact details of their output are not guaranteed to be stable across different systems and/or versions of Rust. This means that users of bevy_math could observe slightly different behavior on different systems if these methods were used. The goal of this PR is to make it so that the `libm` feature flag actually guarantees some degree of determinacy within bevy_math itself by switching to the libm versions of these functions when the `libm` feature is enabled. ## Solution bevy_math now has an internal module `bevy_math::ops`, which re-exports either the standard versions of the operations or the libm versions depending on whether the `libm` feature is enabled. For example, `ops::sin` compiles to `f32::sin` without the `libm` feature and to `libm::sinf` with it. This approach has a small shortfall, which is that `f32::powi` (integer powers of floating point numbers) does not have an equivalent in `libm`. On the other hand, this method is only used for squaring and cubing numbers in bevy_math. Accordingly, this deficit is covered by the introduction of a trait `ops::FloatPow`: ```rust pub(crate) trait FloatPow { fn squared(self) -> Self; fn cubed(self) -> Self; } ``` Next, each current usage of the unspecified-precision methods has been replaced by its equivalent in `ops`, so that when `libm` is enabled, the libm version is used instead. The exception, of course, is that `.powi(2)`/`.powi(3)` have been replaced with `.squared()`/`.cubed()`. Finally, the usage of the plain `f32` methods with unspecified precision is now linted out of bevy_math (and hence disallowed in CI). For example, using `f32::sin` within bevy_math produces a warning that tells the user to use the `ops::sin` version instead. ## Testing Ran existing tests. It would be nice to check some benchmarks on NURBS things once #14677 merges. I'm happy to wait until then if the rest of this PR is fine. --- ## Discussion In the future, it might make sense to actually expose `bevy_math::ops` as public if any downstream Bevy crates want to provide similar determinacy guarantees. For now, it's all just `pub(crate)`. This PR also only covers `f32`. If we find ourselves using `f64` internally in parts of bevy_math for better robustness, we could extend the module and lints to cover the `f64` versions easily enough. I don't know how feasible it is, but it would also be nice if we could standardize the bevy_math tests with the `libm` feature in CI, since their success is currently platform-dependent (e.g. 8 of them fail on my machine when run locally). --------- Co-authored-by: IQuick 143 <IQuick143cz@gmail.com>
2024-08-12 16:13:36 +00:00
mod ops;
Define a basic set of Primitives (#10466) # Objective - Implement a subset of https://github.com/bevyengine/rfcs/blob/main/rfcs/12-primitive-shapes.md#feature-name-primitive-shapes ## Solution - Define a very basic set of primitives in bevy_math - Assume a 0,0,0 origin for most shapes - Use radius and half extents to avoid unnecessary computational overhead wherever they get used - Provide both Boxed and const generics variants for shapes with variable sizes - Boxed is useful if a 3rd party crate wants to use something like enum-dispatch for all supported primitives - Const generics is useful when just working on a single primitive, as it causes no allocs #### Some discrepancies from the RFC: - Box was changed to Cuboid, because Box is already used for an alloc type - Skipped Cone because it's unclear where the origin should be for different uses - Skipped Wedge because it's too niche for an initial PR (we also don't implement Torus, Pyramid or a Death Star (there's an SDF for that!)) - Skipped Frustum because while it would be a useful math type, it's not really a common primitive - Skipped Triangle3d and Quad3d because those are just rotated 2D shapes ## Future steps - Add more primitives - Add helper methods to make primitives easier to construct (especially when half extents are involved) - Add methods to calculate AABBs for primitives (useful for physics, BVH construction, for the mesh AABBs, etc) - Add wrappers for common and cheap operations, like extruding 2D shapes and translating them - Use the primitives to generate meshes - Provide signed distance functions and gradients for primitives (maybe) --- ## Changelog - Added a collection of primitives to the bevy_math crate --------- Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
2023-11-15 16:51:03 +00:00
pub mod primitives;
Add `Camera::viewport_to_world` (#6126) # Objective Add a method for getting a world space ray from a viewport position. Opted to add a `Ray` type to `bevy_math` instead of returning a tuple of `Vec3`'s as this is clearer and easier to document The docs on `viewport_to_world` are okay, but I'm not super happy with them. ## Changelog * Add `Camera::viewport_to_world` * Add `Camera::ndc_to_world` * Add `Ray` to `bevy_math` * Some doc tweaks Co-authored-by: devil-ira <justthecooldude@gmail.com>
2022-10-05 22:16:26 +00:00
mod ray;
Add integer equivalents for `Rect` (#7984) ## Objective Add integer equivalents for the `Rect` type. Closes #7967 ## Solution - Add `IRect` and `URect` ## Changelog Added `IRect` and `URect` types.
2023-06-12 19:10:48 +00:00
mod rects;
Add `Rotation2d` (#11658) # Objective Rotating vectors is a very common task. It is required for a variety of things both within Bevy itself and in many third party plugins, for example all over physics and collision detection, and for things like Bevy's bounding volumes and several gizmo implementations. For 3D, we can do this using a `Quat`, but for 2D, we do not have a clear and efficient option. `Mat2` can be used for rotating vectors if created using `Mat2::from_angle`, but this is not obvious to many users, it doesn't have many rotation helpers, and the type does not give any guarantees that it represents a valid rotation. We should have a proper type for 2D rotations. In addition to allowing for potential optimization, it would allow us to have a consistent and explicitly documented representation used throughout the engine, i.e. counterclockwise and in radians. ## Representation The mathematical formula for rotating a 2D vector is the following: ``` new_x = x * cos - y * sin new_y = x * sin + y * cos ``` Here, `sin` and `cos` are the sine and cosine of the rotation angle. Computing these every time when a vector needs to be rotated can be expensive, so the rotation shouldn't be just an `f32` angle. Instead, it is often more efficient to represent the rotation using the sine and cosine of the angle instead of storing the angle itself. This can be freely passed around and reused without unnecessary computations. The two options are either a 2x2 rotation matrix or a unit complex number where the cosine is the real part and the sine is the imaginary part. These are equivalent for the most part, but the unit complex representation is a bit more memory efficient (two `f32`s instead of four), so I chose that. This is like Nalgebra's [`UnitComplex`](https://docs.rs/nalgebra/latest/nalgebra/geometry/type.UnitComplex.html) type, which can be used for the [`Rotation2`](https://docs.rs/nalgebra/latest/nalgebra/geometry/type.Rotation2.html) type. ## Implementation Add a `Rotation2d` type represented as a unit complex number: ```rust /// A counterclockwise 2D rotation in radians. /// /// The rotation angle is wrapped to be within the `]-pi, pi]` range. pub struct Rotation2d { /// The cosine of the rotation angle in radians. /// /// This is the real part of the unit complex number representing the rotation. pub cos: f32, /// The sine of the rotation angle in radians. /// /// This is the imaginary part of the unit complex number representing the rotation. pub sin: f32, } ``` Using it is similar to using `Quat`, but in 2D: ```rust let rotation = Rotation2d::radians(PI / 2.0); // Rotate vector (also works on Direction2d!) assert_eq!(rotation * Vec2::X, Vec2::Y); // Get angle as degrees assert_eq!(rotation.as_degrees(), 90.0); // Getting sin and cos is free let (sin, cos) = rotation.sin_cos(); // "Subtract" rotations let rotation2 = Rotation2d::FRAC_PI_4; // there are constants! let diff = rotation * rotation2.inverse(); assert_eq!(diff.as_radians(), PI / 4.0); // This is equivalent to the above assert_eq!(rotation2.angle_between(rotation), PI / 4.0); // Lerp let rotation1 = Rotation2d::IDENTITY; let rotation2 = Rotation2d::FRAC_PI_2; let result = rotation1.lerp(rotation2, 0.5); assert_eq!(result.as_radians(), std::f32::consts::FRAC_PI_4); // Slerp let rotation1 = Rotation2d::FRAC_PI_4); let rotation2 = Rotation2d::degrees(-180.0); // we can use degrees too! let result = rotation1.slerp(rotation2, 1.0 / 3.0); assert_eq!(result.as_radians(), std::f32::consts::FRAC_PI_2); ``` There's also a `From<f32>` implementation for `Rotation2d`, which means that methods can still accept radians as floats if the argument uses `impl Into<Rotation2d>`. This means that adding `Rotation2d` shouldn't even be a breaking change. --- ## Changelog - Added `Rotation2d` - Bounding volume methods now take an `impl Into<Rotation2d>` - Gizmo methods with rotation now take an `impl Into<Rotation2d>` ## Future use cases - Collision detection (a type like this is quite essential considering how common vector rotations are) - `Transform` helpers (e.g. return a 2D rotation about the Z axis from a `Transform`) - The rotation used for `Transform2d` (#8268) - More gizmos, maybe meshes... everything in 2D that uses rotation --------- Co-authored-by: Tristan Guichaoua <33934311+tguichaoua@users.noreply.github.com> Co-authored-by: Robert Walter <robwalter96@gmail.com> Co-authored-by: IQuick 143 <IQuick143cz@gmail.com>
2024-03-11 19:11:57 +00:00
mod rotation2d;
Uniform point sampling methods for some primitive shapes. (#12484) # Objective Give easy methods for uniform point sampling in a variety of primitive shapes (particularly useful for circles and spheres) because in a lot of cases its quite easy to get wrong (non-uniform). ## Solution Added the `ShapeSample` trait to `bevy_math` and implemented it for `Circle`, `Sphere`, `Rectangle`, `Cuboid`, `Cylinder`, `Capsule2d` and `Capsule3d`. There are a few other shapes it would be reasonable to implement for like `Triangle`, `Ellipse` and `Torus` but I'm not immediately sure how these would be implemented (other than rejection which could be the best method, and could be more performant than some of the solutions in this pr I'm not sure). This exposes the `sample_volume` and `sample_surface` methods to get both a random point from its interior or its surface. EDIT: Renamed `sample_volume` to `sample_interior` and `sample_surface` to `sample_boundary` This brings in `rand` as a default optional dependency (without default features), and the methods take `&mut impl Rng` which allows them to use any random source implementing `RngCore`. --- ## Changelog ### Added Added the methods `sample_interior` and `sample_boundary` to a variety of primitive shapes providing easy uniform point sampling.
2024-03-17 14:48:16 +00:00
#[cfg(feature = "rand")]
Random sampling of directions and quaternions (#12857) # Objective Augment Bevy's random sampling capabilities by providing good tools for producing random directions and rotations. ## Solution The `rand` crate has a natural tool for providing `Distribution`s whose output is a type that doesn't require any additional data to sample values — namely, [`Standard`](https://docs.rs/rand/latest/rand/distributions/struct.Standard.html). Here, our existing `ShapeSample` implementations have been put to good use in providing these, resulting in patterns like the following: ```rust // Using thread-local rng let random_direction1: Dir3 = random(); // Using an explicit rng let random_direction2: Dir3 = rng.gen(); // Using an explicit rng coupled explicitly with Standard let random_directions: Vec<Dir3> = rng.sample_iter(Standard).take(5).collect(); ``` Furthermore, we have introduced a trait `FromRng` which provides sugar for `rng.gen()` that is more namespace-friendly (in this author's opinion): ```rust let random_direction = Dir3::from_rng(rng); ``` The types this has been implemented for are `Dir2`, `Dir3`, `Dir3A`, and `Quat`. Notably, `Quat` uses `glam`'s implementation rather than an in-house one, and as a result, `bevy_math`'s "rand" feature now enables that of `glam`. --- ## Changelog - Created `standard` submodule in `sampling` to hold implementations and other items related to the `Standard` distribution. - "rand" feature of `bevy_math` now enables that of `glam`. --- ## Discussion From a quick glance at `Quat`'s distribution implementation in `glam`, I am a bit suspicious, since it is simple and doesn't match any algorithm that I came across in my research. I will do a little more digging as a follow-up to this and see if it's actually uniform (maybe even using those tools I wrote — what a thrill). As an aside, I'd also like to say that I think [`Distribution`](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html) is really, really good. It integrates with distributions provided externally (e.g. in `rand` itself and its extensions) along with doing a good job of isolating the source of randomness, so that output can be reliably reproduced if need be. Finally, `Distribution::sample_iter` is quite good for ergonomically acquiring lots of random values. At one point I found myself writing traits to describe random sampling and essentially reinvented this one. I just think it's good, and I think it's worth centralizing around to a significant extent.
2024-04-04 23:13:00 +00:00
pub mod sampling;
Added CompassQuadrant and CompassOctant as per #13647 (#13653) # Objective Implements #13647 ## Solution Created two enums, CompassQuadrant and CompassOctant inside compass.rs with impls To and From Dir2. Used dir.to_angle().to_degrees() and matched against the resulting value. I could have skipped to_degrees() and matched against the radian value, but I thought this was more readable. I'm probably wrong lol. ## Testing Tested various dirs to compass variations. --- --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-06-03 19:46:50 +00:00
pub use compass::{CompassOctant, CompassQuadrant};
Move `sprite::Rect` into `bevy_math` (#5686) # Objective Promote the `Rect` utility of `sprite::Rect`, which defines a rectangle by its minimum and maximum corners, to the `bevy_math` crate to make it available as a general math type to all crates without the need to depend on the `bevy_sprite` crate. Fixes #5575 ## Solution Move `sprite::Rect` into `bevy_math` and fix all uses. Implement `Reflect` for `Rect` directly into the `bevy_reflect` crate by having `bevy_reflect` depend on `bevy_math`. This looks like a new dependency, but the `bevy_reflect` was "cheating" for other math types by directly depending on `glam` to reflect other math types, thereby giving the illusion that there was no dependency on `bevy_math`. In practice conceptually Bevy's math types are reflected into the `bevy_reflect` crate to avoid a dependency of that crate to a "lower level" utility crate like `bevy_math` (which in turn would make `bevy_reflect` be a dependency of most other crates, and increase the risk of circular dependencies). So this change simply formalizes that dependency in `Cargo.toml`. The `Rect` struct is also augmented in this change with a collection of utility methods to improve its usability. A few uses cases are updated to use those new methods, resulting is more clear and concise syntax. --- ## Changelog ### Changed - Moved the `sprite::Rect` type into `bevy_math`. ### Added - Added several utility methods to the `math::Rect` type. ## Migration Guide The `bevy::sprite::Rect` type moved to the math utility crate as `bevy::math::Rect`. You should change your imports from `use bevy::sprite::Rect` to `use bevy::math::Rect`.
2022-09-02 12:35:23 +00:00
Reduce the size of MeshUniform to improve performance (#9416) # Objective - Significantly reduce the size of MeshUniform by only including necessary data. ## Solution Local to world, model transforms are affine. This means they only need a 4x3 matrix to represent them. `MeshUniform` stores the current, and previous model transforms, and the inverse transpose of the current model transform, all as 4x4 matrices. Instead we can store the current, and previous model transforms as 4x3 matrices, and we only need the upper-left 3x3 part of the inverse transpose of the current model transform. This change allows us to reduce the serialized MeshUniform size from 208 bytes to 144 bytes, which is over a 30% saving in data to serialize, and VRAM bandwidth and space. ## Benchmarks On an M1 Max, running `many_cubes -- sphere`, main is in yellow, this PR is in red: <img width="1484" alt="Screenshot 2023-08-11 at 02 36 43" src="https://github.com/bevyengine/bevy/assets/302146/7d99c7b3-f2bb-4004-a8d0-4c00f755cb0d"> A reduction in frame time of ~14%. --- ## Changelog - Changed: Redefined `MeshUniform` to improve performance by using 4x3 affine transforms and reconstructing 4x4 matrices in the shader. Helper functions were added to `bevy_pbr::mesh_functions` to unpack the data. `affine_to_square` converts the packed 4x3 in 3x4 matrix data to a 4x4 matrix. `mat2x4_f32_to_mat3x3` converts the 3x3 in mat2x4 + f32 matrix data back into a 3x3. ## Migration Guide Shader code before: ``` var model = mesh[instance_index].model; ``` Shader code after: ``` #import bevy_pbr::mesh_functions affine_to_square var model = affine_to_square(mesh[instance_index].model); ```
2023-08-15 06:00:23 +00:00
pub use affine3::*;
Introduce AspectRatio struct (#10368) # Objective - Fix an inconsistency in the calculation of aspect ratio's. - Fixes #10288 ## Solution - Created an intermediate `AspectRatio` struct, as suggested in the issue. This is currently just used in any places where aspect ratio calculations happen, to prevent doing it wrong. In my and @mamekoro 's opinion, it would be better if this was used instead of a normal `f32` in various places, but I didn't want to make too many changes to begin with. ## Migration Guide - Anywhere where you are currently expecting a f32 when getting aspect ratios, you will now receive a `AspectRatio` struct. this still holds the same value. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-12-17 02:01:26 +00:00
pub use aspect_ratio::AspectRatio;
Move `Point` out of cubic splines module and expand it (#12747) # Objective Previously, the `Point` trait, which abstracts all of the operations of a real vector space, was sitting in the submodule of `bevy_math` for cubic splines. However, the trait has broader applications than merely cubic splines, and we should use it when possible to avoid code duplication when performing vector operations. ## Solution `Point` has been moved into a new submodule in `bevy_math` named `common_traits`. Furthermore, it has been renamed to `VectorSpace`, which is more descriptive, and an additional trait `NormedVectorSpace` has been introduced to expand the API to cover situations involving geometry in addition to algebra. Additionally, `VectorSpace` itself now requires a `ZERO` constant and `Neg`. It also supports a `lerp` function as an automatic trait method. Here is what that looks like: ```rust /// A type that supports the mathematical operations of a real vector space, irrespective of dimension. /// In particular, this means that the implementing type supports: /// - Scalar multiplication and division on the right by elements of `f32` /// - Negation /// - Addition and subtraction /// - Zero /// /// Within the limitations of floating point arithmetic, all the following are required to hold: /// - (Associativity of addition) For all `u, v, w: Self`, `(u + v) + w == u + (v + w)`. /// - (Commutativity of addition) For all `u, v: Self`, `u + v == v + u`. /// - (Additive identity) For all `v: Self`, `v + Self::ZERO == v`. /// - (Additive inverse) For all `v: Self`, `v - v == v + (-v) == Self::ZERO`. /// - (Compatibility of multiplication) For all `a, b: f32`, `v: Self`, `v * (a * b) == (v * a) * b`. /// - (Multiplicative identity) For all `v: Self`, `v * 1.0 == v`. /// - (Distributivity for vector addition) For all `a: f32`, `u, v: Self`, `(u + v) * a == u * a + v * a`. /// - (Distributivity for scalar addition) For all `a, b: f32`, `v: Self`, `v * (a + b) == v * a + v * b`. /// /// Note that, because implementing types use floating point arithmetic, they are not required to actually /// implement `PartialEq` or `Eq`. pub trait VectorSpace: Mul<f32, Output = Self> + Div<f32, Output = Self> + Add<Self, Output = Self> + Sub<Self, Output = Self> + Neg + Default + Debug + Clone + Copy { /// The zero vector, which is the identity of addition for the vector space type. const ZERO: Self; /// Perform vector space linear interpolation between this element and another, based /// on the parameter `t`. When `t` is `0`, `self` is recovered. When `t` is `1`, `rhs` /// is recovered. /// /// Note that the value of `t` is not clamped by this function, so interpolating outside /// of the interval `[0,1]` is allowed. #[inline] fn lerp(&self, rhs: Self, t: f32) -> Self { *self * (1. - t) + rhs * t } } ``` ```rust /// A type that supports the operations of a normed vector space; i.e. a norm operation in addition /// to those of [`VectorSpace`]. Specifically, the implementor must guarantee that the following /// relationships hold, within the limitations of floating point arithmetic: /// - (Nonnegativity) For all `v: Self`, `v.norm() >= 0.0`. /// - (Positive definiteness) For all `v: Self`, `v.norm() == 0.0` implies `v == Self::ZERO`. /// - (Absolute homogeneity) For all `c: f32`, `v: Self`, `(v * c).norm() == v.norm() * c.abs()`. /// - (Triangle inequality) For all `v, w: Self`, `(v + w).norm() <= v.norm() + w.norm()`. /// /// Note that, because implementing types use floating point arithmetic, they are not required to actually /// implement `PartialEq` or `Eq`. pub trait NormedVectorSpace: VectorSpace { /// The size of this element. The return value should always be nonnegative. fn norm(self) -> f32; /// The squared norm of this element. Computing this is often faster than computing /// [`NormedVectorSpace::norm`]. #[inline] fn norm_squared(self) -> f32 { self.norm() * self.norm() } /// The distance between this element and another, as determined by the norm. #[inline] fn distance(self, rhs: Self) -> f32 { (rhs - self).norm() } /// The squared distance between this element and another, as determined by the norm. Note that /// this is often faster to compute in practice than [`NormedVectorSpace::distance`]. #[inline] fn distance_squared(self, rhs: Self) -> f32 { (rhs - self).norm_squared() } } ``` Furthermore, this PR also demonstrates the use of the `NormedVectorSpace` combined API to implement `ShapeSample` for `Triangle2d` and `Triangle3d` simultaneously. Such deduplication is one of the drivers for developing these APIs. --- ## Changelog - `Point` from `cubic_splines` becomes `VectorSpace`, exported as `bevy::math::VectorSpace`. - `VectorSpace` requires `Neg` and `VectorSpace::ZERO` in addition to its existing prerequisites. - Introduced public traits `bevy::math::NormedVectorSpace` for generic geometry tasks involving vectors. - Implemented `ShapeSample` for `Triangle2d` and `Triangle3d`. ## Migration Guide Since `Point` no longer exists, any projects using it must switch to `bevy::math::VectorSpace`. Additionally, third-party implementations of this trait now require the `Neg` trait; the constant `VectorSpace::ZERO` must be provided as well. --- ## Discussion ### Design considerations Originally, the `NormedVectorSpace::norm` method was part of a separate trait `Normed`. However, I think that was probably too broad and, more importantly, the semantics of having it in `NormedVectorSpace` are much clearer. As it currently stands, the API exposed here is pretty minimal, and there is definitely a lot more that we could do, but there are more questions to answer along the way. As a silly example, we could implement `NormedVectorSpace::length` as an alias for `NormedVectorSpace::norm`, but this overlaps with methods in all of the glam types, so we would want to make sure that the implementations are effectively identical (for what it's worth, I think they are already). ### Future directions One example of something that could belong in the `NormedVectorSpace` API is normalization. Actually, such a thing previously existed on this branch before I decided to shelve it because of concerns with namespace collision. It looked like this: ```rust /// This element, but normalized to norm 1 if possible. Returns an error when the reciprocal of /// the element's norm is not finite. #[inline] #[must_use] fn normalize(&self) -> Result<Self, NonNormalizableError> { let reciprocal = 1.0 / self.norm(); if reciprocal.is_finite() { Ok(*self * reciprocal) } else { Err(NonNormalizableError { reciprocal }) } } /// An error indicating that an element of a [`NormedVectorSpace`] was non-normalizable due to having /// non-finite norm-reciprocal. #[derive(Debug, Error)] #[error("Element with norm reciprocal {reciprocal} cannot be normalized")] pub struct NonNormalizableError { reciprocal: f32 } ``` With this kind of thing in hand, it might be worth considering eventually making the passage from vectors to directions fully generic by employing a wrapper type. (Of course, for our concrete types, we would leave the existing names in place as aliases.) That is, something like: ```rust pub struct NormOne<T> where T: NormedVectorSpace { //... } ``` Utterly separately, the reason that I implemented `ShapeSample` for `Triangle2d`/`Triangle3d` was to prototype uniform sampling of abstract meshes, so that's also a future direction. --------- Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-03-28 13:40:26 +00:00
pub use common_traits::*;
Add `Direction3dA` and move direction types out of `primitives` (#12018) # Objective Split up from #12017, add an aligned version of `Direction3d` for SIMD, and move direction types out of `primitives`. ## Solution Add `Direction3dA` and move direction types into a new `direction` module. --- ## Migration Guide The `Direction2d`, `Direction3d`, and `InvalidDirectionError` types have been moved out of `bevy::math::primitives`. Before: ```rust use bevy::math::primitives::Direction3d; ``` After: ```rust use bevy::math::Direction3d; ``` --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-02-26 13:57:49 +00:00
pub use direction::*;
Move FloatOrd into bevy_math (#12732) # Objective - Fixes #12712 ## Solution - Move the `float_ord.rs` file to `bevy_math` - Change any `bevy_utils::FloatOrd` statements to `bevy_math::FloatOrd` --- ## Changelog - Moved `FloatOrd` from `bevy_utils` to `bevy_math` ## Migration Guide - References to `bevy_utils::FloatOrd` should be changed to `bevy_math::FloatOrd`
2024-03-27 18:30:11 +00:00
pub use float_ord::*;
Improve isometry docs (#14318) # Objective Fixes #14308. #14269 added the `Isometry2d` and `Isometry3d` types, but they don't have usage examples or much documentation on what the types actually represent or what they may be useful for. In addition, their module is public and the types are not re-exported at the crate root, unlike all the other core math types like Glam's types, direction types, and `Rot2`. ## Solution Improve the documentation of `Isometry2d` and `Isometry3d`, explaining what they represent and can be useful for, along with doc examples on common high-level usage. I also made the way the types are exported consistent with other core math types. This does add some duplication, but I personally think having good docs for this is valuable, and people are also less likely to look at the module-level docs than type-level docs.
2024-07-15 16:05:33 +00:00
pub use isometry::{Isometry2d, Isometry3d};
Expose bevy math ops (#14863) # Objective - Fixes #14796 ## Solution - Copy docs for wrapper methods, make sure they are consistent with the original docs except for the section on precision.
2024-08-22 17:07:00 +00:00
pub use ops::*;
Split `Ray` into `Ray2d` and `Ray3d` and simplify plane construction (#10856) # Objective A better alternative version of #10843. Currently, Bevy has a single `Ray` struct for 3D. To allow better interoperability with Bevy's primitive shapes (#10572) and some third party crates (that handle e.g. spatial queries), it would be very useful to have separate versions for 2D and 3D respectively. ## Solution Separate `Ray` into `Ray2d` and `Ray3d`. These new structs also take advantage of the new primitives by using `Direction2d`/`Direction3d` for the direction: ```rust pub struct Ray2d { pub origin: Vec2, pub direction: Direction2d, } pub struct Ray3d { pub origin: Vec3, pub direction: Direction3d, } ``` and by using `Plane2d`/`Plane3d` in `intersect_plane`: ```rust impl Ray2d { // ... pub fn intersect_plane(&self, plane_origin: Vec2, plane: Plane2d) -> Option<f32> { // ... } } ``` --- ## Changelog ### Added - `Ray2d` and `Ray3d` - `Ray2d::new` and `Ray3d::new` constructors - `Plane2d::new` and `Plane3d::new` constructors ### Removed - Removed `Ray` in favor of `Ray3d` ### Changed - `direction` is now a `Direction2d`/`Direction3d` instead of a vector, which provides guaranteed normalization - `intersect_plane` now takes a `Plane2d`/`Plane3d` instead of just a vector for the plane normal - `Direction2d` and `Direction3d` now derive `Serialize` and `Deserialize` to preserve ray (de)serialization ## Migration Guide `Ray` has been renamed to `Ray3d`. ### Ray creation Before: ```rust Ray { origin: Vec3::ZERO, direction: Vec3::new(0.5, 0.6, 0.2).normalize(), } ``` After: ```rust // Option 1: Ray3d { origin: Vec3::ZERO, direction: Direction3d::new(Vec3::new(0.5, 0.6, 0.2)).unwrap(), } // Option 2: Ray3d::new(Vec3::ZERO, Vec3::new(0.5, 0.6, 0.2)) ``` ### Plane intersections Before: ```rust let result = ray.intersect_plane(Vec2::X, Vec2::Y); ``` After: ```rust let result = ray.intersect_plane(Vec2::X, Plane2d::new(Vec2::Y)); ```
2023-12-06 14:09:04 +00:00
pub use ray::{Ray2d, Ray3d};
Add integer equivalents for `Rect` (#7984) ## Objective Add integer equivalents for the `Rect` type. Closes #7967 ## Solution - Add `IRect` and `URect` ## Changelog Added `IRect` and `URect` types.
2023-06-12 19:10:48 +00:00
pub use rects::*;
Rename `Rotation2d` to `Rot2` (#13694) # Objective - `Rotation2d` is a very long name for a commonly used type. ## Solution - Rename it to `Rot2` to match `glam`'s naming convention (e.g. `Vec2`) I ran a poll, and `Rot2` was the favorite of the candidate names. This is not actually a breaking change, since `Rotation2d` has not been shipped yet. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-06-05 21:51:13 +00:00
pub use rotation2d::Rot2;
Uniform point sampling methods for some primitive shapes. (#12484) # Objective Give easy methods for uniform point sampling in a variety of primitive shapes (particularly useful for circles and spheres) because in a lot of cases its quite easy to get wrong (non-uniform). ## Solution Added the `ShapeSample` trait to `bevy_math` and implemented it for `Circle`, `Sphere`, `Rectangle`, `Cuboid`, `Cylinder`, `Capsule2d` and `Capsule3d`. There are a few other shapes it would be reasonable to implement for like `Triangle`, `Ellipse` and `Torus` but I'm not immediately sure how these would be implemented (other than rejection which could be the best method, and could be more performant than some of the solutions in this pr I'm not sure). This exposes the `sample_volume` and `sample_surface` methods to get both a random point from its interior or its surface. EDIT: Renamed `sample_volume` to `sample_interior` and `sample_surface` to `sample_boundary` This brings in `rand` as a default optional dependency (without default features), and the methods take `&mut impl Rng` which allows them to use any random source implementing `RngCore`. --- ## Changelog ### Added Added the methods `sample_interior` and `sample_boundary` to a variety of primitive shapes providing easy uniform point sampling.
2024-03-17 14:48:16 +00:00
#[cfg(feature = "rand")]
Random sampling of directions and quaternions (#12857) # Objective Augment Bevy's random sampling capabilities by providing good tools for producing random directions and rotations. ## Solution The `rand` crate has a natural tool for providing `Distribution`s whose output is a type that doesn't require any additional data to sample values — namely, [`Standard`](https://docs.rs/rand/latest/rand/distributions/struct.Standard.html). Here, our existing `ShapeSample` implementations have been put to good use in providing these, resulting in patterns like the following: ```rust // Using thread-local rng let random_direction1: Dir3 = random(); // Using an explicit rng let random_direction2: Dir3 = rng.gen(); // Using an explicit rng coupled explicitly with Standard let random_directions: Vec<Dir3> = rng.sample_iter(Standard).take(5).collect(); ``` Furthermore, we have introduced a trait `FromRng` which provides sugar for `rng.gen()` that is more namespace-friendly (in this author's opinion): ```rust let random_direction = Dir3::from_rng(rng); ``` The types this has been implemented for are `Dir2`, `Dir3`, `Dir3A`, and `Quat`. Notably, `Quat` uses `glam`'s implementation rather than an in-house one, and as a result, `bevy_math`'s "rand" feature now enables that of `glam`. --- ## Changelog - Created `standard` submodule in `sampling` to hold implementations and other items related to the `Standard` distribution. - "rand" feature of `bevy_math` now enables that of `glam`. --- ## Discussion From a quick glance at `Quat`'s distribution implementation in `glam`, I am a bit suspicious, since it is simple and doesn't match any algorithm that I came across in my research. I will do a little more digging as a follow-up to this and see if it's actually uniform (maybe even using those tools I wrote — what a thrill). As an aside, I'd also like to say that I think [`Distribution`](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html) is really, really good. It integrates with distributions provided externally (e.g. in `rand` itself and its extensions) along with doing a good job of isolating the source of randomness, so that output can be reliably reproduced if need be. Finally, `Distribution::sample_iter` is quite good for ergonomically acquiring lots of random values. At one point I found myself writing traits to describe random sampling and essentially reinvented this one. I just think it's good, and I think it's worth centralizing around to a significant extent.
2024-04-04 23:13:00 +00:00
pub use sampling::{FromRng, ShapeSample};
Move `sprite::Rect` into `bevy_math` (#5686) # Objective Promote the `Rect` utility of `sprite::Rect`, which defines a rectangle by its minimum and maximum corners, to the `bevy_math` crate to make it available as a general math type to all crates without the need to depend on the `bevy_sprite` crate. Fixes #5575 ## Solution Move `sprite::Rect` into `bevy_math` and fix all uses. Implement `Reflect` for `Rect` directly into the `bevy_reflect` crate by having `bevy_reflect` depend on `bevy_math`. This looks like a new dependency, but the `bevy_reflect` was "cheating" for other math types by directly depending on `glam` to reflect other math types, thereby giving the illusion that there was no dependency on `bevy_math`. In practice conceptually Bevy's math types are reflected into the `bevy_reflect` crate to avoid a dependency of that crate to a "lower level" utility crate like `bevy_math` (which in turn would make `bevy_reflect` be a dependency of most other crates, and increase the risk of circular dependencies). So this change simply formalizes that dependency in `Cargo.toml`. The `Rect` struct is also augmented in this change with a collection of utility methods to improve its usability. A few uses cases are updated to use those new methods, resulting is more clear and concise syntax. --- ## Changelog ### Changed - Moved the `sprite::Rect` type into `bevy_math`. ### Added - Added several utility methods to the `math::Rect` type. ## Migration Guide The `bevy::sprite::Rect` type moved to the math utility crate as `bevy::math::Rect`. You should change your imports from `use bevy::sprite::Rect` to `use bevy::math::Rect`.
2022-09-02 12:35:23 +00:00
Document `bevy_math` (#4591) # Objective - Part of #3492 ## Solution - Document the `bevy_math` crate and add the `#![warn(missing_docs)]` lint.
2022-04-26 18:23:29 +00:00
/// The `bevy_math` prelude.
math: simplify imports
2020-07-17 02:23:47 +00:00
pub mod prelude {
Uniform point sampling methods for some primitive shapes. (#12484) # Objective Give easy methods for uniform point sampling in a variety of primitive shapes (particularly useful for circles and spheres) because in a lot of cases its quite easy to get wrong (non-uniform). ## Solution Added the `ShapeSample` trait to `bevy_math` and implemented it for `Circle`, `Sphere`, `Rectangle`, `Cuboid`, `Cylinder`, `Capsule2d` and `Capsule3d`. There are a few other shapes it would be reasonable to implement for like `Triangle`, `Ellipse` and `Torus` but I'm not immediately sure how these would be implemented (other than rejection which could be the best method, and could be more performant than some of the solutions in this pr I'm not sure). This exposes the `sample_volume` and `sample_surface` methods to get both a random point from its interior or its surface. EDIT: Renamed `sample_volume` to `sample_interior` and `sample_surface` to `sample_boundary` This brings in `rand` as a default optional dependency (without default features), and the methods take `&mut impl Rng` which allows them to use any random source implementing `RngCore`. --- ## Changelog ### Added Added the methods `sample_interior` and `sample_boundary` to a variety of primitive shapes providing easy uniform point sampling.
2024-03-17 14:48:16 +00:00
#[doc(hidden)]
#[cfg(feature = "rand")]
Random sampling of directions and quaternions (#12857) # Objective Augment Bevy's random sampling capabilities by providing good tools for producing random directions and rotations. ## Solution The `rand` crate has a natural tool for providing `Distribution`s whose output is a type that doesn't require any additional data to sample values — namely, [`Standard`](https://docs.rs/rand/latest/rand/distributions/struct.Standard.html). Here, our existing `ShapeSample` implementations have been put to good use in providing these, resulting in patterns like the following: ```rust // Using thread-local rng let random_direction1: Dir3 = random(); // Using an explicit rng let random_direction2: Dir3 = rng.gen(); // Using an explicit rng coupled explicitly with Standard let random_directions: Vec<Dir3> = rng.sample_iter(Standard).take(5).collect(); ``` Furthermore, we have introduced a trait `FromRng` which provides sugar for `rng.gen()` that is more namespace-friendly (in this author's opinion): ```rust let random_direction = Dir3::from_rng(rng); ``` The types this has been implemented for are `Dir2`, `Dir3`, `Dir3A`, and `Quat`. Notably, `Quat` uses `glam`'s implementation rather than an in-house one, and as a result, `bevy_math`'s "rand" feature now enables that of `glam`. --- ## Changelog - Created `standard` submodule in `sampling` to hold implementations and other items related to the `Standard` distribution. - "rand" feature of `bevy_math` now enables that of `glam`. --- ## Discussion From a quick glance at `Quat`'s distribution implementation in `glam`, I am a bit suspicious, since it is simple and doesn't match any algorithm that I came across in my research. I will do a little more digging as a follow-up to this and see if it's actually uniform (maybe even using those tools I wrote — what a thrill). As an aside, I'd also like to say that I think [`Distribution`](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html) is really, really good. It integrates with distributions provided externally (e.g. in `rand` itself and its extensions) along with doing a good job of isolating the source of randomness, so that output can be reliably reproduced if need be. Finally, `Distribution::sample_iter` is quite good for ergonomically acquiring lots of random values. At one point I found myself writing traits to describe random sampling and essentially reinvented this one. I just think it's good, and I think it's worth centralizing around to a significant extent.
2024-04-04 23:13:00 +00:00
pub use crate::sampling::{FromRng, ShapeSample};
Revert "Show prelude re-exports in docs (#6448)" (#6449) This reverts commit 53d387f34039c5d369159a681b279793d71dbd6b. # Objective Reverts #6448. This didn't have the intended effect: we're now getting bevy::prelude shown in the docs again. Co-authored-by: Alejandro Pascual <alejandro.pascual.pozo@gmail.com>
2022-11-02 20:40:45 +00:00
#[doc(hidden)]
re-export integer vectors from glam (#1264)
2021-01-19 20:56:50 +00:00
pub use crate::{
Rename `Bezier` to `CubicBezier` for clarity (#9554) # Objective A Bezier curve is a curve defined by two or more control points. In the simplest form, it's just a line. The (arguably) most common type of Bezier curve is a cubic Bezier, defined by four control points. These are often used in animation, etc. Bevy has a Bezier curve struct called `Bezier`. However, this is technically a misnomer as it only represents cubic Bezier curves. ## Solution This PR changes the struct name to `CubicBezier` to more accurately reflect the struct's usage. Since it's exposed in Bevy's prelude, it can potentially collide with other `Bezier` implementations. While that might instead be an argument for removing it from the prelude, there's also something to be said for adding a more general `Bezier` into Bevy, in which case we'd likely want to use the name `Bezier`. As a final motivator, not only is the struct located in `cubic_spines.rs`, there are also several other spline-related structs which follow the `CubicXxx` naming convention where applicable. For example, `CubicSegment` represents a cubic Bezier curve (with coefficients pre-baked). --- ## Migration Guide - Change all `Bezier` references to `CubicBezier`
2023-08-28 17:37:42 +00:00
cubic_splines::{
Cubic splines overhaul (#10701) # Objective Improve the `bevy::math::cubic_splines` module by making it more flexible and adding new curve types. Closes #10220 ## Solution Added new spline types and improved existing --- ## Changelog ### Added - `CubicNurbs` rational cubic curve generator, allows setting the knot vector and weights associated with every point - `LinearSpline` curve generator, allows generating a linearly interpolated curve segment - Ability to push additional cubic segments to `CubicCurve` - `IntoIterator` and `Extend` implementations for `CubicCurve` ### Changed - `Point` trait has been implemented for more types: `Quat` and `Vec4`. - `CubicCurve::coefficients` was moved to `CubicSegment::coefficients` because the function returns `CubicSegment`, so it seems logical to be associated with `CubicSegment` instead. The method is still not public. ### Fixed - `CubicBSpline::new` was referencing Cardinal spline instead of B-Spline --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: IQuick 143 <IQuick143cz@gmail.com> Co-authored-by: Miles Silberling-Cook <nth.tensor@gmail.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
2024-02-28 17:18:42 +00:00
CubicBSpline, CubicBezier, CubicCardinalSpline, CubicCurve, CubicGenerator,
Cyclic splines (#14106) # Objective Fill a gap in the functionality of our curve constructions by allowing users to easily build cyclic curves from control data. ## Solution Here I opted for something lightweight and discoverable. There is a new `CyclicCubicGenerator` trait with a method `to_curve_cyclic` which uses splines' control data to create curves that are cyclic. For now, its signature is exactly like that of `CubicGenerator` — `to_curve_cyclic` just yields a `CubicCurve`: ```rust /// Implement this on cubic splines that can generate a cyclic cubic curve from their spline parameters. /// /// This makes sense only when the control data can be interpreted cyclically. pub trait CyclicCubicGenerator<P: VectorSpace> { /// Build a cyclic [`CubicCurve`] by computing the interpolation coefficients for each curve segment. fn to_curve_cyclic(&self) -> CubicCurve<P>; } ``` This trait has been implemented for `CubicHermite`, `CubicCardinalSpline`, `CubicBSpline`, and `LinearSpline`: <img width="753" alt="Screenshot 2024-07-01 at 8 58 27 PM" src="https://github.com/bevyengine/bevy/assets/2975848/69ae0802-3b78-4fb9-b73a-6f842cf3b33c"> <img width="628" alt="Screenshot 2024-07-01 at 9 00 14 PM" src="https://github.com/bevyengine/bevy/assets/2975848/2992175a-a96c-40fc-b1a1-5206c3572cde"> <img width="606" alt="Screenshot 2024-07-01 at 8 59 36 PM" src="https://github.com/bevyengine/bevy/assets/2975848/9e99eb3a-dbe6-42da-886c-3d3e00410d03"> <img width="603" alt="Screenshot 2024-07-01 at 8 59 01 PM" src="https://github.com/bevyengine/bevy/assets/2975848/d037bc0c-396a-43af-ab5c-fad9a29417ef"> (Each type pictured respectively with the control points rendered as green spheres; tangents not pictured in the case of the Hermite spline.) These curves are all parametrized so that the output of `to_curve` and the output of `to_curve_cyclic` are similar. For instance, in `CubicCardinalSpline`, the first output segment is a curve segment joining the first and second control points in each, although it is constructed differently. In the other cases, the segments from `to_curve` are a subset of those in `to_curve_cyclic`, with the new segments appearing at the end. ## Testing I rendered cyclic splines from control data and made sure they looked reasonable. Existing tests are intact for splines where previous code was modified. (Note that the coefficient computation for cyclic spline segments is almost verbatim identical to that of their non-cyclic counterparts.) The Bezier benchmarks also look fine. --- ## Changelog - Added `CyclicCubicGenerator` trait to `bevy_math::cubic_splines` for creating cyclic curves from control data. - Implemented `CyclicCubicGenerator` for `CubicHermite`, `CubicCardinalSpline`, `CubicBSpline`, and `LinearSpline`. - `bevy_math` now depends on `itertools`. --- ## Discussion ### Design decisions The biggest thing here is just the approach taken in the first place: namely, the cyclic constructions use new methods on the same old structs. This choice was made to reduce friction and increase discoverability but also because creating new ones just seemed unnecessary: the underlying data would have been the same, so creating something like "`CyclicCubicBSpline`" whose internally-held control data is regarded as cyclic in nature doesn't really accomplish much — the end result for the user is basically the same either way. Similarly, I don't presently see a pressing need for `to_curve_cyclic` to output something other than a `CubicCurve`, although changing this in the future may be useful. See below. A notable omission here is that `CyclicCubicGenerator` is not implemented for `CubicBezier`. This is not a gap waiting to be filled — `CubicBezier` just doesn't have enough data to join its start with its end without just making up the requisite control points wholesale. In all the cases where `CyclicCubicGenerator` has been implemented here, the fashion in which the ends are connected is quite natural and follows the semantics of the associated spline construction. ### Future direction There are two main things here: 1. We should investigate whether we should do something similar for NURBS. I just don't know that much about NURBS at the moment, so I regarded this as out of scope for the PR. 2. We may eventually want to change the output type of `CyclicCubicGenerator::to_curve_cyclic` to a type which reifies the cyclic nature of the curve output. This wasn't done in this PR because I'm unsure how much value a type-level guarantee of cyclicity actually has, but if some useful features make sense only in the case of cyclic curves, this might be worth pursuing.
2024-07-17 13:02:31 +00:00
CubicHermite, CubicNurbs, CubicNurbsError, CubicSegment, CyclicCubicGenerator,
RationalCurve, RationalGenerator, RationalSegment,
Rename `Bezier` to `CubicBezier` for clarity (#9554) # Objective A Bezier curve is a curve defined by two or more control points. In the simplest form, it's just a line. The (arguably) most common type of Bezier curve is a cubic Bezier, defined by four control points. These are often used in animation, etc. Bevy has a Bezier curve struct called `Bezier`. However, this is technically a misnomer as it only represents cubic Bezier curves. ## Solution This PR changes the struct name to `CubicBezier` to more accurately reflect the struct's usage. Since it's exposed in Bevy's prelude, it can potentially collide with other `Bezier` implementations. While that might instead be an argument for removing it from the prelude, there's also something to be said for adding a more general `Bezier` into Bevy, in which case we'd likely want to use the name `Bezier`. As a final motivator, not only is the struct located in `cubic_spines.rs`, there are also several other spline-related structs which follow the `CubicXxx` naming convention where applicable. For example, `CubicSegment` represents a cubic Bezier curve (with coefficients pre-baked). --- ## Migration Guide - Change all `Bezier` references to `CubicBezier`
2023-08-28 17:37:42 +00:00
},
Rename `Direction2d/3d` to `Dir2/3` (#12189) # Objective Split up from #12017, rename Bevy's direction types. Currently, Bevy has the `Direction2d`, `Direction3d`, and `Direction3dA` types, which provide a type-level guarantee that their contained vectors remain normalized. They can be very useful for a lot of APIs for safety, explicitness, and in some cases performance, as they can sometimes avoid unnecessary normalizations. However, many consider them to be inconvenient to use, and opt for standard vector types like `Vec3` because of this. One reason is that the direction type names are a bit long and can be annoying to write (of course you can use autocomplete, but just typing `Vec3` is still nicer), and in some intances, the extra characters can make formatting worse. The naming is also inconsistent with Glam's shorter type names, and results in names like `Direction3dA`, which (in my opinion) are difficult to read and even a bit ugly. This PR proposes renaming the types to `Dir2`, `Dir3`, and `Dir3A`. These names are nice and easy to write, consistent with Glam, and work well for variants like the SIMD aligned `Dir3A`. As a bonus, it can also result in nicer formatting in a lot of cases, which can be seen from the diff of this PR. Some examples of what it looks like: (copied from #12017) ```rust // Before let ray_cast = RayCast2d::new(Vec2::ZERO, Direction2d::X, 5.0); // After let ray_cast = RayCast2d::new(Vec2::ZERO, Dir2::X, 5.0); ``` ```rust // Before (an example using Bevy XPBD) let hit = spatial_query.cast_ray( Vec3::ZERO, Direction3d::X, f32::MAX, true, SpatialQueryFilter::default(), ); // After let hit = spatial_query.cast_ray( Vec3::ZERO, Dir3::X, f32::MAX, true, SpatialQueryFilter::default(), ); ``` ```rust // Before self.circle( Vec3::new(0.0, -2.0, 0.0), Direction3d::Y, 5.0, Color::TURQUOISE, ); // After (formatting is collapsed in this case) self.circle(Vec3::new(0.0, -2.0, 0.0), Dir3::Y, 5.0, Color::TURQUOISE); ``` ## Solution Rename `Direction2d`, `Direction3d`, and `Direction3dA` to `Dir2`, `Dir3`, and `Dir3A`. --- ## Migration Guide The `Direction2d` and `Direction3d` types have been renamed to `Dir2` and `Dir3`. ## Additional Context This has been brought up on the Discord a few times, and we had a small [poll](https://discord.com/channels/691052431525675048/1203087353850364004/1212465038711984158) on this. `Dir2`/`Dir3`/`Dir3A` was quite unanimously chosen as the best option, but of course it was a very small poll and inconclusive, so other opinions are certainly welcome too. --------- Co-authored-by: IceSentry <c.giguere42@gmail.com>
2024-02-28 22:48:43 +00:00
direction::{Dir2, Dir3, Dir3A},
Add geometric primitives to `bevy_math::prelude` (#11432) # Objective Currently, the `primitives` module is inside of the prelude for `bevy_math`, but the actual primitives are not. This requires either importing the shapes everywhere that uses them, or adding the `primitives::` prefix: ```rust let rectangle = meshes.add(primitives::Rectangle::new(5.0, 2.5)); ``` (Note: meshing isn't actually implemented yet, but it's in #11431) The primitives are meant to be used for a variety of tasks across several crates, like for meshing, bounding volumes, gizmos, colliders, and so on, so I think having them in the prelude is justified. It would make several common tasks a lot more ergonomic. ```rust let rectangle = meshes.add(Rectangle::new(5.0, 2.5)); ``` ## Solution Add `primitives::*` to `bevy_math::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-01-20 20:15:38 +00:00
primitives::*,
BVec2, BVec3, BVec4, EulerRot, FloatExt, IRect, IVec2, IVec3, IVec4, Mat2, Mat3, Mat4,
Stable interpolation and smooth following (#13741) # Objective Partially address #13408 Rework of #13613 Unify the very nice forms of interpolation specifically present in `bevy_math` under a shared trait upon which further behavior can be based. The ideas in this PR were prompted by [Lerp smoothing is broken by Freya Holmer](https://www.youtube.com/watch?v=LSNQuFEDOyQ). ## Solution There is a new trait `StableInterpolate` in `bevy_math::common_traits` which enshrines a quite-specific notion of interpolation with a lot of guarantees: ```rust /// A type with a natural interpolation that provides strong subdivision guarantees. /// /// Although the only required method is `interpolate_stable`, many things are expected of it: /// /// 1. The notion of interpolation should follow naturally from the semantics of the type, so /// that inferring the interpolation mode from the type alone is sensible. /// /// 2. The interpolation recovers something equivalent to the starting value at `t = 0.0` /// and likewise with the ending value at `t = 1.0`. /// /// 3. Importantly, the interpolation must be *subdivision-stable*: for any interpolation curve /// between two (unnamed) values and any parameter-value pairs `(t0, p)` and `(t1, q)`, the /// interpolation curve between `p` and `q` must be the *linear* reparametrization of the original /// interpolation curve restricted to the interval `[t0, t1]`. /// /// The last of these conditions is very strong and indicates something like constant speed. It /// is called "subdivision stability" because it guarantees that breaking up the interpolation /// into segments and joining them back together has no effect. /// /// Here is a diagram depicting it: /// ```text /// top curve = u.interpolate_stable(v, t) /// /// t0 => p t1 => q /// |-------------|---------|-------------| /// 0 => u / \ 1 => v /// / \ /// / \ /// / linear \ /// / reparametrization \ /// / t = t0 * (1 - s) + t1 * s \ /// / \ /// |-------------------------------------| /// 0 => p 1 => q /// /// bottom curve = p.interpolate_stable(q, s) /// ``` /// /// Note that some common forms of interpolation do not satisfy this criterion. For example, /// [`Quat::lerp`] and [`Rot2::nlerp`] are not subdivision-stable. /// /// Furthermore, this is not to be used as a general trait for abstract interpolation. /// Consumers rely on the strong guarantees in order for behavior based on this trait to be /// well-behaved. /// /// [`Quat::lerp`]: crate::Quat::lerp /// [`Rot2::nlerp`]: crate::Rot2::nlerp pub trait StableInterpolate: Clone { /// Interpolate between this value and the `other` given value using the parameter `t`. /// Note that the parameter `t` is not necessarily clamped to lie between `0` and `1`. /// When `t = 0.0`, `self` is recovered, while `other` is recovered at `t = 1.0`, /// with intermediate values lying between the two. fn interpolate_stable(&self, other: &Self, t: f32) -> Self; } ``` This trait has a blanket implementation over `NormedVectorSpace`, where `lerp` is used, along with implementations for `Rot2`, `Quat`, and the direction types using variants of `slerp`. Other areas may choose to implement this trait in order to hook into its functionality, but the stringent requirements must actually be met. This trait bears no direct relationship with `bevy_animation`'s `Animatable` trait, although they may choose to use `interpolate_stable` in their trait implementations if they wish, as both traits involve type-inferred interpolations of the same kind. `StableInterpolate` is not a supertrait of `Animatable` for a couple reasons: 1. Notions of interpolation in animation are generally going to be much more general than those allowed under these constraints. 2. Laying out these generalized interpolation notions is the domain of `bevy_animation` rather than of `bevy_math`. (Consider also that inferring interpolation from types is not universally desirable.) Similarly, this is not implemented on `bevy_color`'s color types, although their current mixing behavior does meet the conditions of the trait. As an aside, the subdivision-stability condition is of interest specifically for the [Curve RFC](https://github.com/bevyengine/rfcs/pull/80), where it also ensures a kind of stability for subsampling. Importantly, this trait ensures that the "smooth following" behavior defined in this PR behaves predictably: ```rust /// Smoothly nudge this value towards the `target` at a given decay rate. The `decay_rate` /// parameter controls how fast the distance between `self` and `target` decays relative to /// the units of `delta`; the intended usage is for `decay_rate` to generally remain fixed, /// while `delta` is something like `delta_time` from an updating system. This produces a /// smooth following of the target that is independent of framerate. /// /// More specifically, when this is called repeatedly, the result is that the distance between /// `self` and a fixed `target` attenuates exponentially, with the rate of this exponential /// decay given by `decay_rate`. /// /// For example, at `decay_rate = 0.0`, this has no effect. /// At `decay_rate = f32::INFINITY`, `self` immediately snaps to `target`. /// In general, higher rates mean that `self` moves more quickly towards `target`. /// /// # Example /// ``` /// # use bevy_math::{Vec3, StableInterpolate}; /// # let delta_time: f32 = 1.0 / 60.0; /// let mut object_position: Vec3 = Vec3::ZERO; /// let target_position: Vec3 = Vec3::new(2.0, 3.0, 5.0); /// // Decay rate of ln(10) => after 1 second, remaining distance is 1/10th /// let decay_rate = f32::ln(10.0); /// // Calling this repeatedly will move `object_position` towards `target_position`: /// object_position.smooth_nudge(&target_position, decay_rate, delta_time); /// ``` fn smooth_nudge(&mut self, target: &Self, decay_rate: f32, delta: f32) { self.interpolate_stable_assign(target, 1.0 - f32::exp(-decay_rate * delta)); } ``` As the documentation indicates, the intention is for this to be called in game update systems, and `delta` would be something like `Time::delta_seconds` in Bevy, allowing positions, orientations, and so on to smoothly follow a target. A new example, `smooth_follow`, demonstrates a basic implementation of this, with a sphere smoothly following a sharply moving target: https://github.com/bevyengine/bevy/assets/2975848/7124b28b-6361-47e3-acf7-d1578ebd0347 ## Testing Tested by running the example with various parameters.
2024-06-10 12:50:59 +00:00
Quat, Ray2d, Ray3d, Rect, Rot2, StableInterpolate, URect, UVec2, UVec3, UVec4, Vec2,
Vec2Swizzles, Vec3, Vec3Swizzles, Vec4, Vec4Swizzles,
re-export integer vectors from glam (#1264)
2021-01-19 20:56:50 +00:00
};
math: simplify imports
2020-07-17 02:23:47 +00:00
}
Document `bevy_math` (#4591) # Objective - Part of #3492 ## Solution - Document the `bevy_math` crate and add the `#![warn(missing_docs)]` lint.
2022-04-26 18:23:29 +00:00
pub use glam::*;
Reference in a new issue Copy permalink