docs, SkeletonData accessors, and changelog

changelog.md

@@ -4,13 +4,69 @@
 - Add `Physics` enum
   - Add `physics` parameter to `Skeleton::update_world_transform` and `Skeleton::update_world_transform_with`
   - Add `physics` parameter to `Controller::update`
-- Add methods:
+- Add constraint types:
+  - `IkConstraint`
+  - `IkConstraintData`
+  - `PathConstraint`
+  - `PathConstraintData`
+  - `PhysicsConstraint`
+  - `PhysicsConstraintData`
+  - `TransformConstraint`
+  - `TransformConstraintData`
+- Add IK constraint methods:
+  - `Skeleton::ik_constraints`
+  - `Skeleton::ik_constraints_mut`
+  - `Skeleton::ik_constraint_at_index`
+  - `Skeleton::ik_constraint_at_index_mut`
+  - `Skeleton::find_ik_constraint`
+  - `Skeleton::find_ik_constraint_mut`
+  - `SkeletonData::ik_constraints`
+  - `SkeletonData::ik_constraint_at_index`
+  - `SkeletonData::find_ik_constraint`
+- Add path constraint methods:
+  - `Skeleton::path_constraints`
+  - `Skeleton::path_constraints_mut`
+  - `Skeleton::path_constraint_at_index`
+  - `Skeleton::path_constraint_at_index_mut`
+  - `Skeleton::find_path_constraint`
+  - `Skeleton::find_path_constraint_mut`
+  - `SkeletonData::path_constraints`
+  - `SkeletonData::path_constraint_at_index`
+  - `SkeletonData::find_path_constraint`
+- Add physics constraint methods:
+  - `Skeleton::physics_constraints`
+  - `Skeleton::physics_constraints_mut`
+  - `Skeleton::physics_constraint_at_index`
+  - `Skeleton::physics_constraint_at_index_mut`
+  - `Skeleton::find_physics_constraint`
+  - `Skeleton::find_physics_constraint_mut`
+  - `Skeleton::physics_constraint_count`
+  - `SkeletonData::physics_constraints`
+  - `SkeletonData::physics_constraint_at_index`
+  - `SkeletonData::physics_constraint_count`
+  - `SkeletonData::find_physics_constraint`
+- Add transform constraint methods:
+  - `Skeleton::transform_constraints`
+  - `Skeleton::transform_constraints_mut`
+  - `Skeleton::transform_constraint_at_index`
+  - `Skeleton::transform_constraint_at_index_mut`
+  - `Skeleton::find_transform_constraint`
+  - `Skeleton::find_transform_constraint_mut`
+  - `SkeletonData::transform_constraints`
+  - `SkeletonData::transform_constraint_at_index`
+  - `SkeletonData::find_transform_constraint`
+- Add new enum types:
+  - `PositionMode`
+  - `SpacingMode`
+  - `RotateMode`
+- Add missing mutator:
   - `TrackEntry::set_track_time`
+- Add Spine 4.2 methods:
   - `TrackEntry::mix_attachment_threshold`
   - `TrackEntry::set_mix_attachment_threshold`
   - `TrackEntry::mix_draw_order_threshold`
   - `TrackEntry::set_mix_draw_order_threshold`
-- Remove methods:
+- Remove Spine 4.1 methods:
   - `TrackEntry::attachment_threshold`
   - `TrackEntry::set_attachment_threshold`
   - `TrackEntry::draw_order_threshold`

src/ik_constraint.rs

@@ -22,6 +22,7 @@ impl NewFromPtr<spIkConstraint> for IkConstraint {
 }
 
 impl IkConstraint {
+    /// Applies the constraint to the constrained bones.
     pub fn update(&self) {
         unsafe {
             spIkConstraint_update(self.c_ik_constraint.0);
@@ -34,17 +35,63 @@ impl IkConstraint {
         }
     }
 
-    c_accessor_tmp_ptr_mut!(data, data_mut, data, IkConstraintData, spIkConstraintData);
+    c_accessor_tmp_ptr_mut!(
+        /// The IK constraint's setup pose data.
+        data,
+        data_mut,
+        data,
+        IkConstraintData,
+        spIkConstraintData
+    );
 
     c_accessor_bool!(active, active);
-    c_accessor_mut!(bend_direction, set_bend_direction, bendDirection, i32);
-    c_accessor_bool_mut!(compress, set_compress, compress);
-    c_accessor_mut!(mix, set_mix, mix, f32);
-    c_accessor_mut!(softness, set_softness, softness, f32);
-    c_accessor_bool_mut!(stretch, set_stretch, stretch);
+    c_accessor_mut!(
+        /// For two bone IK, controls the bend direction of the IK bones, either 1 or -1.
+        bend_direction,
+        set_bend_direction,
+        bendDirection,
+        i32
+    );
+    c_accessor_bool_mut!(
+        /// For one bone IK, when true and the target is too close, the bone is scaled to reach it.
+        compress,
+        set_compress,
+        compress
+    );
+    c_accessor_mut!(
+        /// A percentage (0-1) that controls the mix between the constrained and unconstrained
+        /// rotation.
+        ///
+        /// For two bone IK: if the parent bone has local nonuniform scale, the child bone's local Y
+        /// translation is set to 0.
+        mix,
+        set_mix,
+        mix,
+        f32
+    );
+    c_accessor_mut!(
+        /// For two bone IK, the target bone's distance from the maximum reach of the bones where
+        /// rotation begins to slow. The bones will not straighten completely until the target is
+        /// this far out of range.
+        softness,
+        set_softness,
+        softness,
+        f32
+    );
+    c_accessor_bool_mut!(
+        /// When true and the target is out of range, the parent bone is scaled to reach it.
+        ///
+        /// For two bone IK: 1) the child bone's local Y translation is set to 0, 2) stretch is not
+        /// applied if [`softness`](`Self::softness`) is > 0, and 3) if the parent bone has local
+        /// nonuniform scale, stretch is not applied.
+        stretch,
+        set_stretch,
+        stretch
+    );
 
     c_accessor!(bones_count, bonesCount, usize);
     c_accessor_array!(
+        /// The bones that will be modified by this IK constraint.
         bones,
         bone_at_index,
         IkConstraint,
@@ -53,7 +100,14 @@ impl IkConstraint {
         bones,
         bones_count
     );
-    c_accessor_tmp_ptr_mut!(target, target_mut, target, Bone, spBone);
+    c_accessor_tmp_ptr_mut!(
+        /// The bone that is the IK target.
+        target,
+        target_mut,
+        target,
+        Bone,
+        spBone
+    );
 
     c_ptr!(c_ik_constraint, spIkConstraint);
 }

src/ik_constraint_data.rs

@@ -4,6 +4,8 @@ use crate::{
     BoneData,
 };
 
+/// Stores the setup pose for an [`IkConstraint`](`crate::IkConstraint`).
+///
 /// [Spine API Reference](https://esotericsoftware.com/spine-api-reference#IkConstraintData)
 #[derive(Debug)]
 pub struct IkConstraintData {
@@ -19,16 +21,71 @@ impl NewFromPtr<spIkConstraintData> for IkConstraintData {
 }
 
 impl IkConstraintData {
-    c_accessor_string!(name, name);
-    c_accessor!(order, order, i32);
-    c_accessor_bool!(skin_required, skinRequired);
+    c_accessor_string!(
+        /// The constraint's name, which is unique across all constraints in the skeleton of the
+        /// same type.
+        name,
+        name
+    );
+    c_accessor!(
+        /// The ordinal of this constraint for the order a skeleton's constraints will be applied by
+        /// [`Skeleton::update_world_transform`](`crate::Skeleton::update_world_transform`).
+        order,
+        order,
+        i32
+    );
+    c_accessor_bool!(
+        /// When true,
+        /// [`Skeleton::update_world_transform`](`crate::Skeleton::update_world_transform`) only
+        /// updates this constraint if the skin contains this constraint.
+        skin_required,
+        skinRequired
+    );
 
-    c_accessor!(bend_direction, bendDirection, i32);
-    c_accessor_bool!(compress, compress);
-    c_accessor!(mix, mix, f32);
-    c_accessor!(softness, softness, f32);
-    c_accessor_bool!(stretch, stretch);
-    c_accessor_bool!(uniform, uniform);
+    c_accessor!(
+        /// For two bone IK, controls the bend direction of the IK bones, either 1 or -1.
+        bend_direction,
+        bendDirection,
+        i32
+    );
+    c_accessor_bool!(
+        /// For one bone IK, when true and the target is too close, the bone is scaled to reach it.
+        compress,
+        compress
+    );
+    c_accessor!(
+        /// A percentage (0-1) that controls the mix between the constrained and unconstrained
+        /// rotation.
+        ///
+        /// For two bone IK: if the parent bone has local nonuniform scale, the child bone's local Y
+        /// translation is set to 0.
+        mix,
+        mix,
+        f32
+    );
+    c_accessor!(
+        /// For two bone IK, the target bone's distance from the maximum reach of the bones where
+        /// rotation begins to slow. The bones will not straighten completely until the target is this
+        /// far out of range.
+        softness,
+        softness,
+        f32
+    );
+    c_accessor_bool!(
+        /// When true and the target is out of range, the parent bone is scaled to reach it.
+        ///
+        /// For two bone IK: 1) the child bone's local Y translation is set to 0, 2) stretch is not
+        /// applied if [`softness`](`Self::softness`) is > 0, and 3) if the parent bone has local
+        /// nonuniform scale, stretch is not applied.
+        stretch,
+        stretch
+    );
+    c_accessor_bool!(
+        /// When true and [`compress`](`Self::compress`) or [`stretch`](`Self::stretch`) is used,
+        /// the bone is scaled on both the X and Y axes.
+        uniform,
+        uniform
+    );
 
     c_accessor!(bones_count, bonesCount, usize);
     c_accessor_array!(

src/path_constraint.rs

@@ -22,6 +22,7 @@ impl NewFromPtr<spPathConstraint> for PathConstraint {
 }
 
 impl PathConstraint {
+    /// Applies the constraint to the constrained bones.
     pub fn update(&self) {
         unsafe {
             spPathConstraint_update(self.c_path_constraint.0);
@@ -35,6 +36,7 @@ impl PathConstraint {
     }
 
     c_accessor_tmp_ptr_mut!(
+        /// The path constraint's setup pose data.
         data,
         data_mut,
         data,
@@ -43,14 +45,48 @@ impl PathConstraint {
     );
 
     c_accessor_bool!(active, active);
-    c_accessor_mut!(mix_rotate, set_mix_rotate, mixRotate, f32);
-    c_accessor_mut!(mix_x, set_mix_x, mixX, f32);
-    c_accessor_mut!(mix_y, set_mix_y, mixY, f32);
-    c_accessor_mut!(position, set_position, position, f32);
-    c_accessor_mut!(spacing, set_spacing, spacing, f32);
+    c_accessor_mut!(
+        /// A percentage (0-1) that controls the mix between the constrained and unconstrained
+        /// rotation.
+        mix_rotate,
+        set_mix_rotate,
+        mixRotate,
+        f32
+    );
+    c_accessor_mut!(
+        /// A percentage (0-1) that controls the mix between the constrained and unconstrained
+        /// translation X.
+        mix_x,
+        set_mix_x,
+        mixX,
+        f32
+    );
+    c_accessor_mut!(
+        /// A percentage (0-1) that controls the mix between the constrained and unconstrained
+        /// translation Y.
+        mix_y,
+        set_mix_y,
+        mixY,
+        f32
+    );
+    c_accessor_mut!(
+        /// The position along the path.
+        position,
+        set_position,
+        position,
+        f32
+    );
+    c_accessor_mut!(
+        /// The spacing between bones.
+        spacing,
+        set_spacing,
+        spacing,
+        f32
+    );
 
     c_accessor!(bones_count, bonesCount, usize);
     c_accessor_array!(
+        /// The bones that will be modified by this path constraint.
         bones,
         bone_at_index,
         PathConstraint,
@@ -59,7 +95,14 @@ impl PathConstraint {
         bones,
         bones_count
     );
-    c_accessor_tmp_ptr_mut!(target, target_mut, target, Slot, spSlot);
+    c_accessor_tmp_ptr_mut!(
+        /// The slot whose path attachment will be used to constrained the bones.
+        target,
+        target_mut,
+        target,
+        Slot,
+        spSlot
+    );
 
     c_ptr!(c_path_constraint, spPathConstraint);
 }