feat: rename AxisMask to AxesMask + enable LIN_Z only in 3D (#805)

Author: sebcrozet

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 - Add `PdController` and `PidController` for making it easier to control dynamic rigid-bodies at the velocity level.
   This can for example be used as a building block for a dynamic character controller.
-- Add `RigidBodyPosition::pose_errors` which computes the translational and rotational delta between
+- Add `RigidBodyPosition::pose_errors` to compute the translational and rotational delta between
   `RigidBodyPosition::position` and `::next_position`.
 - Implement `Sub` for `RigidBodyVelocity`.
 - Add `RigidBody::local_center_of_mass()` to get its center-of-mass in the rigid-body’s local-space.
@@ -103,9 +103,9 @@ This release introduces two new crates:
 
 ### Modified
 
-- Renamed `JointAxesMask::X/Y/Z` to `::LIN_X/LIN_Y/LIN_Z`; and renamed `JointAxisMask::X/Y/Z` to `::LinX/LinY/LynZ` to
+- Renamed `JointAxesMask::X/Y/Z` to `::LIN_X/LIN_Y/LIN_Z`; and renamed `JointAxesMask::X/Y/Z` to `::LinX/LinY/LynZ` to
   make it clear it is not to be used as angular axes (the angular axis are `JointAxesMask::ANG_X/ANG_Y/AngZ` and
-  `JointAxisMask::AngX/AngY/AngZ`).
+  `JointAxesMask::AngX/AngY/AngZ`).
 - The contact constraints regularization parameters have been changed from `erp/damping_ratio` to
   `natural_frequency/damping_ratio`. This helps define them in a timestep-length independent way. The new variables
   are named `IntegrationParameters::contact_natural_frequency` and `IntegrationParameters::contact_damping_ratio`.

examples2d/utils/character.rs

@@ -95,13 +95,13 @@ fn update_pid_controller(
     // - If the user is jumping, enable control over Y.
     // - If the user isn’t pressing any key, disable all linear controls to let
     //   gravity/collision do their thing freely.
-    let mut axes = AxisMask::ANG_Z;
+    let mut axes = AxesMask::ANG_Z;
 
     if desired_movement.norm() != 0.0 {
         axes |= if desired_movement.y == 0.0 {
-            AxisMask::LIN_X
+            AxesMask::LIN_X
         } else {
-            AxisMask::LIN_X | AxisMask::LIN_Y
+            AxesMask::LIN_X | AxesMask::LIN_Y
         }
     };
 

examples3d/utils/character.rs

@@ -106,13 +106,13 @@ fn update_pid_controller(
     // - If the user is jumping, enable control over Y.
     // - If the user isn’t pressing any key, disable all linear controls to let
     //   gravity/collision do their thing freely.
-    let mut axes = AxisMask::ANG_X | AxisMask::ANG_Y | AxisMask::ANG_Z;
+    let mut axes = AxesMask::ANG_X | AxesMask::ANG_Y | AxesMask::ANG_Z;
 
     if desired_movement.norm() != 0.0 {
         axes |= if desired_movement.y == 0.0 {
-            AxisMask::LIN_X | AxisMask::LIN_Z
+            AxesMask::LIN_X | AxesMask::LIN_Z
         } else {
-            AxisMask::LIN_X | AxisMask::LIN_Z | AxisMask::LIN_Y
+            AxesMask::LIN_X | AxesMask::LIN_Z | AxesMask::LIN_Y
         }
     };
 

src/control/pid_controller.rs

@@ -1,4 +1,4 @@
-use crate::dynamics::{AxisMask, RigidBody, RigidBodyPosition, RigidBodyVelocity};
+use crate::dynamics::{AxesMask, RigidBody, RigidBodyPosition, RigidBodyVelocity};
 use crate::math::{Isometry, Point, Real, Rotation, Vector};
 use parry::math::AngVector;
 
@@ -38,12 +38,12 @@ pub struct PdController {
     ///
     /// Only coordinate axes with a bit flags set to `true` will be taken into
     /// account when calculating the errors and corrections.
-    pub axes: AxisMask,
+    pub axes: AxesMask,
 }
 
 impl Default for PdController {
     fn default() -> Self {
-        Self::new(60.0, 0.8, AxisMask::all())
+        Self::new(60.0, 0.8, AxesMask::all())
     }
 }
 
@@ -67,7 +67,7 @@ pub struct PidController {
 
 impl Default for PidController {
     fn default() -> Self {
-        Self::new(60.0, 1.0, 0.8, AxisMask::all())
+        Self::new(60.0, 1.0, 0.8, AxesMask::all())
     }
 }
 
@@ -96,7 +96,7 @@ impl PdController {
     ///
     /// Only the axes specified in `axes` will be enabled (but the gain values are set
     /// on all axes regardless).
-    pub fn new(kp: Real, kd: Real, axes: AxisMask) -> PdController {
+    pub fn new(kp: Real, kd: Real, axes: AxesMask) -> PdController {
         #[cfg(feature = "dim2")]
         return Self {
             lin_kp: Vector::repeat(kp),
@@ -189,27 +189,27 @@ impl PdController {
     fn lin_mask(&self) -> Vector<Real> {
         #[cfg(feature = "dim2")]
         return Vector::new(
-            self.axes.contains(AxisMask::LIN_X) as u32 as Real,
-            self.axes.contains(AxisMask::LIN_Y) as u32 as Real,
+            self.axes.contains(AxesMask::LIN_X) as u32 as Real,
+            self.axes.contains(AxesMask::LIN_Y) as u32 as Real,
         );
         #[cfg(feature = "dim3")]
         return Vector::new(
-            self.axes.contains(AxisMask::LIN_X) as u32 as Real,
-            self.axes.contains(AxisMask::LIN_Y) as u32 as Real,
-            self.axes.contains(AxisMask::LIN_Z) as u32 as Real,
+            self.axes.contains(AxesMask::LIN_X) as u32 as Real,
+            self.axes.contains(AxesMask::LIN_Y) as u32 as Real,
+            self.axes.contains(AxesMask::LIN_Z) as u32 as Real,
         );
     }
 
     /// Mask where each component is 1.0 or 0.0 depending on whether
     /// the corresponding angular axis is enabled.
     fn ang_mask(&self) -> AngVector<Real> {
         #[cfg(feature = "dim2")]
-        return self.axes.contains(AxisMask::ANG_Z) as u32 as Real;
+        return self.axes.contains(AxesMask::ANG_Z) as u32 as Real;
         #[cfg(feature = "dim3")]
         return Vector::new(
-            self.axes.contains(AxisMask::ANG_X) as u32 as Real,
-            self.axes.contains(AxisMask::ANG_Y) as u32 as Real,
-            self.axes.contains(AxisMask::ANG_Z) as u32 as Real,
+            self.axes.contains(AxesMask::ANG_X) as u32 as Real,
+            self.axes.contains(AxesMask::ANG_Y) as u32 as Real,
+            self.axes.contains(AxesMask::ANG_Z) as u32 as Real,
         );
     }
 
@@ -245,7 +245,7 @@ impl PidController {
     ///
     /// Only the axes specified in `axes` will be enabled (but the gain values are set
     /// on all axes regardless).
-    pub fn new(kp: Real, ki: Real, kd: Real, axes: AxisMask) -> PidController {
+    pub fn new(kp: Real, ki: Real, kd: Real, axes: AxesMask) -> PidController {
         #[cfg(feature = "dim2")]
         return Self {
             pd: PdController::new(kp, kd, axes),
@@ -268,12 +268,12 @@ impl PidController {
     /// Set the axes errors and corrections are computed for.
     ///
     /// This doesn’t modify any of the gains.
-    pub fn set_axes(&mut self, axes: AxisMask) {
+    pub fn set_axes(&mut self, axes: AxesMask) {
         self.pd.axes = axes;
     }
 
     /// Get the axes errors and corrections are computed for.
-    pub fn axes(&self) -> AxisMask {
+    pub fn axes(&self) -> AxesMask {
         self.pd.axes
     }
 

src/dynamics/rigid_body_components.rs

@@ -228,12 +228,13 @@ bitflags::bitflags! {
     #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
     #[derive(Copy, Clone, PartialEq, Eq, Debug)]
     /// Flags affecting the behavior of the constraints solver for a given contact manifold.
-    pub struct AxisMask: u8 {
+    pub struct AxesMask: u8 {
         /// The translational X axis.
         const LIN_X = 1 << 0;
         /// The translational Y axis.
         const LIN_Y = 1 << 1;
         /// The translational Z axis.
+        #[cfg(feature = "dim3")]
         const LIN_Z = 1 << 2;
         /// The rotational X axis.
         #[cfg(feature = "dim3")]
@@ -246,9 +247,9 @@ bitflags::bitflags! {
     }
 }
 
-impl Default for AxisMask {
+impl Default for AxesMask {
     fn default() -> Self {
-        AxisMask::empty()
+        AxesMask::empty()
     }
 }