From fcecbc561058459edbbff60bb732b22c5f03fc4f Mon Sep 17 00:00:00 2001
From: Campbell Barton <campbell@blender.org>
Date: Thu, 25 Aug 2022 14:27:44 +1000
Subject: [PATCH] Cleanup: rename mat3_to_quat_is_ok to mat3_to_quat_legacy

Update comment, noting why this is kept.
---
 source/blender/blenkernel/intern/boids.c           | 2 +-
 source/blender/blenkernel/intern/particle.c        | 4 ++--
 source/blender/blenkernel/intern/particle_system.c | 2 +-
 source/blender/blenlib/BLI_math_rotation.h         | 5 +++--
 source/blender/blenlib/intern/math_rotation.c      | 8 ++++++--
 5 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/source/blender/blenkernel/intern/boids.c b/source/blender/blenkernel/intern/boids.c
index a86d6e25ee9..2e07b52c7bf 100644
--- a/source/blender/blenkernel/intern/boids.c
+++ b/source/blender/blenkernel/intern/boids.c
@@ -1567,7 +1567,7 @@ void boid_body(BoidBrainData *bbd, ParticleData *pa)
   cross_v3_v3v3(mat[1], mat[2], mat[0]);
 
   /* apply rotation */
-  mat3_to_quat_is_ok(q, mat);
+  mat3_to_quat_legacy(q, mat);
   copy_qt_qt(pa->state.rot, q);
 }
 
diff --git a/source/blender/blenkernel/intern/particle.c b/source/blender/blenkernel/intern/particle.c
index 85a8d6c817f..7a17e21d569 100644
--- a/source/blender/blenkernel/intern/particle.c
+++ b/source/blender/blenkernel/intern/particle.c
@@ -3494,7 +3494,7 @@ void psys_cache_paths(ParticleSimulationData *sim, float cfra, const bool use_re
      * initial tangent, but taking that in to account will allow
      * the possibility of flipping again. -jahka
      */
-    mat3_to_quat_is_ok(cache[p]->rot, rotmat);
+    mat3_to_quat_legacy(cache[p]->rot, rotmat);
   }
 
   psys->totcached = totpart;
@@ -3684,7 +3684,7 @@ static void psys_cache_edit_paths_iter(void *__restrict iter_data_v,
      * initial tangent, but taking that in to account will allow
      * the possibility of flipping again. -jahka
      */
-    mat3_to_quat_is_ok(cache[iter]->rot, rotmat);
+    mat3_to_quat_legacy(cache[iter]->rot, rotmat);
   }
 }
 
diff --git a/source/blender/blenkernel/intern/particle_system.c b/source/blender/blenkernel/intern/particle_system.c
index e9bbcea241e..abecb9f8d9d 100644
--- a/source/blender/blenkernel/intern/particle_system.c
+++ b/source/blender/blenkernel/intern/particle_system.c
@@ -837,7 +837,7 @@ void psys_get_birth_coords(
     cross_v3_v3v3(mat[1], mat[2], mat[0]);
 
     /* apply rotation */
-    mat3_to_quat_is_ok(q, mat);
+    mat3_to_quat_legacy(q, mat);
     copy_qt_qt(state->rot, q);
   }
   else {
diff --git a/source/blender/blenlib/BLI_math_rotation.h b/source/blender/blenlib/BLI_math_rotation.h
index 1fa088d7128..7fb7085360b 100644
--- a/source/blender/blenlib/BLI_math_rotation.h
+++ b/source/blender/blenlib/BLI_math_rotation.h
@@ -178,9 +178,10 @@ float angle_signed_qt(const float q[4]);
 float angle_signed_qtqt(const float q1[4], const float q2[4]);
 
 /**
- * TODO: don't what this is, but it's not the same as #mat3_to_quat.
+ * Legacy matrix to quaternion conversion, keep to prevent changes to existing
+ * boids & particle-system behavior. Use #mat3_to_quat for new code.
  */
-void mat3_to_quat_is_ok(float q[4], const float wmat[3][3]);
+void mat3_to_quat_legacy(float q[4], const float wmat[3][3]);
 
 /* Other. */
 
diff --git a/source/blender/blenlib/intern/math_rotation.c b/source/blender/blenlib/intern/math_rotation.c
index bbea95514e9..ae068e3fb19 100644
--- a/source/blender/blenlib/intern/math_rotation.c
+++ b/source/blender/blenlib/intern/math_rotation.c
@@ -176,7 +176,7 @@ void quat_to_compatible_quat(float q[4], const float a[4], const float old[4])
   }
 }
 
-/* skip error check, currently only needed by mat3_to_quat_is_ok */
+/* Skip error check, currently only needed by #mat3_to_quat_legacy. */
 static void quat_to_mat3_no_error(float m[3][3], const float q[4])
 {
   double q0, q1, q2, q3, qda, qdb, qdc, qaa, qab, qac, qbb, qbc, qcc;
@@ -376,8 +376,12 @@ void mat4_to_quat(float q[4], const float mat[4][4])
   mat3_normalized_to_quat_with_checks(q, unit_mat_abs);
 }
 
-void mat3_to_quat_is_ok(float q[4], const float wmat[3][3])
+void mat3_to_quat_legacy(float q[4], const float wmat[3][3])
 {
+  /* Legacy version of #mat3_to_quat which has slightly different behavior.
+   * Keep for particle-system & boids since replacing this will make subtle changes
+   * that impact hair in existing files. See: D15772. */
+
   float mat[3][3], matr[3][3], matn[3][3], q1[4], q2[4], angle, si, co, nor[3];
 
   /* work on a copy */