RNA Armature: Improve the description of AxisRollFromMatrix

The roll value may not be as expected when a matrix is not orthogonal
or has a negative determinant.

This can lead to confusion as seen in T82930.

Therefore, make it clear that this is a limitation and that a value for
the roll is somewhat indeterminable in these cases.

This fixes T82930

1 files changed, 3 insertions, 1 deletions

diff --git a/source/blender/makesrna/intern/rna_armature_api.c b/source/blender/makesrna/intern/rna_armature_api.c
index a9d39b7eda8..36aa0401c7d 100644
--- a/source/blender/makesrna/intern/rna_armature_api.c
+++ b/source/blender/makesrna/intern/rna_armature_api.c
@@ -196,7 +196,9 @@ void RNA_api_bone(StructRNA *srna)
 
   func = RNA_def_function(srna, "AxisRollFromMatrix", "rna_Bone_AxisRollFromMatrix");
   RNA_def_function_ui_description(func,
-                                  "Convert a rotational matrix to the axis + roll representation");
+                                  "Convert a rotational matrix to the axis + roll representation. "
+                                  "Note that the resulting value of the roll may not be as "
+                                  "expected if the matrix has shear or negative determinant.");
   RNA_def_function_flag(func, FUNC_NO_SELF);
   parm = RNA_def_property(func, "matrix", PROP_FLOAT, PROP_MATRIX);
   RNA_def_property_multi_array(parm, 2, rna_matrix_dimsize_3x3);