Refactor: Rename Object->obmat to Object->object_to_world

Motivation is to disambiguate on the naming level what the matrix
actually means. It is very easy to understand the meaning backwards,
especially since in Python the name goes the opposite way (it is
called `world_matrix` in the Python API).

It is important to disambiguate the naming without making developers
to look into the comment in the header file (which is also not super
clear either). Additionally, more clear naming facilitates the unit
verification (or, in this case, space validation) when reading an
expression.

This patch calls the matrix `object_to_world` which makes it clear
from the local code what is it exactly going on. This is only done
on DNA level, and a lot of local variables still follow the old
naming.

A DNA rename is setup in a way that there is no change on the file
level, so there should be no regressions at all.

The possibility is to add `_matrix` or `_mat` suffix to the name
to make it explicit that it is a matrix. Although, not sure if it
really helps the readability, or is it something redundant.

Differential Revision: https://developer.blender.org/D16328

1 files changed, 47 insertions, 42 deletions

diff --git a/source/blender/blenkernel/intern/constraint.c b/source/blender/blenkernel/intern/constraint.c
index a6a6a1ca28f..1f288aef5ad 100644
--- a/source/blender/blenkernel/intern/constraint.c
+++ b/source/blender/blenkernel/intern/constraint.c
@@ -149,7 +149,7 @@ bConstraintOb *BKE_constraints_make_evalob(
           /* Quats/Axis-Angle, so Eulers should just use default order */
           cob->rotOrder = EULER_ORDER_DEFAULT;
         }
-        copy_m4_m4(cob->matrix, ob->obmat);
+        copy_m4_m4(cob->matrix, ob->object_to_world);
       }
       else {
         unit_m4(cob->matrix);
@@ -175,7 +175,7 @@ bConstraintOb *BKE_constraints_make_evalob(
         }
 
         /* matrix in world-space */
-        mul_m4_m4m4(cob->matrix, ob->obmat, cob->pchan->pose_mat);
+        mul_m4_m4m4(cob->matrix, ob->object_to_world, cob->pchan->pose_mat);
       }
       else {
         unit_m4(cob->matrix);
@@ -216,7 +216,7 @@ void BKE_constraints_clear_evalob(bConstraintOb *cob)
       /* cob->ob might not exist! */
       if (cob->ob) {
         /* copy new ob-matrix back to owner */
-        copy_m4_m4(cob->ob->obmat, cob->matrix);
+        copy_m4_m4(cob->ob->object_to_world, cob->matrix);
 
         /* copy inverse of delta back to owner */
         invert_m4_m4(cob->ob->constinv, delta);
@@ -276,7 +276,7 @@ void BKE_constraint_mat_convertspace(Object *ob,
         }
         else {
           /* World to pose. */
-          invert_m4_m4(imat, ob->obmat);
+          invert_m4_m4(imat, ob->object_to_world);
           mul_m4_m4m4(mat, imat, mat);
 
           /* Use pose-space as stepping stone for other spaces. */
@@ -319,7 +319,7 @@ void BKE_constraint_mat_convertspace(Object *ob,
         }
         else {
           /* Pose to world. */
-          mul_m4_m4m4(mat, ob->obmat, mat);
+          mul_m4_m4m4(mat, ob->object_to_world, mat);
           /* Use world-space as stepping stone for other spaces. */
           if (to != CONSTRAINT_SPACE_WORLD) {
             /* Call self with slightly different values. */
@@ -429,7 +429,7 @@ void BKE_constraint_mat_convertspace(Object *ob,
         /* Check if object has a parent. */
         if (ob->parent) {
           /* 'subtract' parent's effects from owner. */
-          mul_m4_m4m4(diff_mat, ob->parent->obmat, ob->parentinv);
+          mul_m4_m4m4(diff_mat, ob->parent->object_to_world, ob->parentinv);
           invert_m4_m4_safe(imat, diff_mat);
           mul_m4_m4m4(mat, imat, mat);
         }
@@ -465,7 +465,7 @@ void BKE_constraint_mat_convertspace(Object *ob,
       /* check that object has a parent - otherwise this won't work */
       if (ob->parent) {
         /* 'add' parent's effect back to owner */
-        mul_m4_m4m4(diff_mat, ob->parent->obmat, ob->parentinv);
+        mul_m4_m4m4(diff_mat, ob->parent->object_to_world, ob->parentinv);
         mul_m4_m4m4(mat, diff_mat, mat);
       }
       else {
@@ -518,7 +518,7 @@ static void contarget_get_mesh_mat(Object *ob, const char *substring, float mat[
   const int defgroup = BKE_object_defgroup_name_index(ob, substring);
 
   /* initialize target matrix using target matrix */
-  copy_m4_m4(mat, ob->obmat);
+  copy_m4_m4(mat, ob->object_to_world);
 
   /* get index of vertex group */
   if (defgroup == -1) {
@@ -584,7 +584,7 @@ static void contarget_get_mesh_mat(Object *ob, const char *substring, float mat[
    *   calc_gizmo_stats, V3D_ORIENT_NORMAL case */
 
   /* We need the transpose of the inverse for a normal. */
-  copy_m3_m4(imat, ob->obmat);
+  copy_m3_m4(imat, ob->object_to_world);
 
   invert_m3_m3(tmat, imat);
   transpose_m3(tmat);
@@ -605,7 +605,7 @@ static void contarget_get_mesh_mat(Object *ob, const char *substring, float mat[
   normalize_m4(mat);
 
   /* apply the average coordinate as the new location */
-  mul_v3_m4v3(mat[3], ob->obmat, vec);
+  mul_v3_m4v3(mat[3], ob->object_to_world, vec);
 }
 
 /* function that sets the given matrix based on given vertex group in lattice */
@@ -627,7 +627,7 @@ static void contarget_get_lattice_mat(Object *ob, const char *substring, float m
   const int defgroup = BKE_object_defgroup_name_index(ob, substring);
 
   /* initialize target matrix using target matrix */
-  copy_m4_m4(mat, ob->obmat);
+  copy_m4_m4(mat, ob->object_to_world);
 
   /* get index of vertex group */
   if (defgroup == -1) {
@@ -661,11 +661,11 @@ static void contarget_get_lattice_mat(Object *ob, const char *substring, float m
     }
   }
 
-  /* find average location, then multiply by ob->obmat to find world-space location */
+  /* find average location, then multiply by ob->object_to_world to find world-space location */
   if (grouped) {
     mul_v3_fl(vec, 1.0f / grouped);
   }
-  mul_v3_m4v3(tvec, ob->obmat, vec);
+  mul_v3_m4v3(tvec, ob->object_to_world, vec);
 
   /* copy new location to matrix */
   copy_v3_v3(mat[3], tvec);
@@ -684,7 +684,7 @@ static void constraint_target_to_mat4(Object *ob,
 {
   /* Case OBJECT */
   if (substring[0] == '\0') {
-    copy_m4_m4(mat, ob->obmat);
+    copy_m4_m4(mat, ob->object_to_world);
     BKE_constraint_mat_convertspace(ob, NULL, cob, mat, from, to, false);
   }
   /* Case VERTEXGROUP */
@@ -719,7 +719,7 @@ static void constraint_target_to_mat4(Object *ob,
 
       if (headtail < 0.000001f && !(is_bbone && full_bbone)) {
         /* skip length interpolation if set to head */
-        mul_m4_m4m4(mat, ob->obmat, pchan->pose_mat);
+        mul_m4_m4m4(mat, ob->object_to_world, pchan->pose_mat);
       }
       else if (is_bbone && pchan->bone->segments == pchan->runtime.bbone_segments) {
         /* use point along bbone */
@@ -745,7 +745,7 @@ static void constraint_target_to_mat4(Object *ob,
           mul_v3_m4v3(tempmat[3], pchan->pose_mat, loc);
         }
 
-        mul_m4_m4m4(mat, ob->obmat, tempmat);
+        mul_m4_m4m4(mat, ob->object_to_world, tempmat);
       }
       else {
         float tempmat[4][4], loc[3];
@@ -757,11 +757,11 @@ static void constraint_target_to_mat4(Object *ob,
         copy_m4_m4(tempmat, pchan->pose_mat);
         copy_v3_v3(tempmat[3], loc);
 
-        mul_m4_m4m4(mat, ob->obmat, tempmat);
+        mul_m4_m4m4(mat, ob->object_to_world, tempmat);
       }
     }
     else {
-      copy_m4_m4(mat, ob->obmat);
+      copy_m4_m4(mat, ob->object_to_world);
     }
 
     /* convert matrix space as required */
@@ -1069,7 +1069,7 @@ static void childof_evaluate(bConstraint *con, bConstraintOb *cob, ListBase *tar
   if (data->flag & CHILDOF_SET_INVERSE) {
     invert_m4_m4(data->invmat, parmat);
     if (cob->pchan != NULL) {
-      mul_m4_series(data->invmat, data->invmat, cob->ob->obmat);
+      mul_m4_series(data->invmat, data->invmat, cob->ob->object_to_world);
     }
 
     copy_m4_m4(inverse_matrix, data->invmat);
@@ -1388,8 +1388,8 @@ static void kinematic_get_tarmat(struct Depsgraph *UNUSED(depsgraph),
       else {
         float vec[3];
         /* move grabtarget into world space */
-        mul_v3_m4v3(vec, ob->obmat, data->grabtarget);
-        copy_m4_m4(ct->matrix, ob->obmat);
+        mul_v3_m4v3(vec, ob->object_to_world, data->grabtarget);
+        copy_m4_m4(ct->matrix, ob->object_to_world);
         copy_v3_v3(ct->matrix[3], vec);
       }
     }
@@ -1528,7 +1528,7 @@ static void followpath_get_tarmat(struct Depsgraph *UNUSED(depsgraph),
 
         copy_v3_v3(totmat[3], vec);
 
-        mul_m4_m4m4(ct->matrix, ct->tar->obmat, totmat);
+        mul_m4_m4m4(ct->matrix, ct->tar->object_to_world, totmat);
       }
     }
   }
@@ -2557,7 +2557,7 @@ static void armdef_get_tarmat(struct Depsgraph *UNUSED(depsgraph),
       bPoseChannel *pchan = BKE_pose_channel_find_name(ct->tar->pose, ct->subtarget);
 
       if (pchan != NULL) {
-        mul_m4_m4m4(ct->matrix, ct->tar->obmat, pchan->pose_mat);
+        mul_m4_m4m4(ct->matrix, ct->tar->object_to_world, pchan->pose_mat);
         return;
       }
     }
@@ -2613,7 +2613,7 @@ static void armdef_accumulate_bone(bConstraintTarget *ct,
   float weight = ct->weight;
 
   /* Our object's location in target pose space. */
-  invert_m4_m4(iobmat, ct->tar->obmat);
+  invert_m4_m4(iobmat, ct->tar->object_to_world);
   mul_v3_m4v3(co, iobmat, wco);
 
   /* Multiply by the envelope weight when appropriate. */
@@ -2644,7 +2644,7 @@ static void armdef_accumulate_bone(bConstraintTarget *ct,
       mul_m4_m4m4(basemat, bone->arm_mat, b_bone_rest_mats[index].mat);
     }
 
-    armdef_accumulate_matrix(ct->tar->obmat,
+    armdef_accumulate_matrix(ct->tar->object_to_world,
                              iobmat,
                              basemat,
                              b_bone_mats[index + 1].mat,
@@ -2657,7 +2657,7 @@ static void armdef_accumulate_bone(bConstraintTarget *ct,
       mul_m4_m4m4(basemat, bone->arm_mat, b_bone_rest_mats[index + 1].mat);
     }
 
-    armdef_accumulate_matrix(ct->tar->obmat,
+    armdef_accumulate_matrix(ct->tar->object_to_world,
                              iobmat,
                              basemat,
                              b_bone_mats[index + 2].mat,
@@ -2667,8 +2667,13 @@ static void armdef_accumulate_bone(bConstraintTarget *ct,
   }
   else {
     /* Simple bone. This requires DEG_OPCODE_BONE_DONE dependency due to chan_mat. */
-    armdef_accumulate_matrix(
-        ct->tar->obmat, iobmat, bone->arm_mat, pchan->chan_mat, weight, r_sum_mat, r_sum_dq);
+    armdef_accumulate_matrix(ct->tar->object_to_world,
+                             iobmat,
+                             bone->arm_mat,
+                             pchan->chan_mat,
+                             weight,
+                             r_sum_mat,
+                             r_sum_dq);
   }
 
   /* Accumulate the weight. */
@@ -2694,7 +2699,7 @@ static void armdef_evaluate(bConstraint *con, bConstraintOb *cob, ListBase *targ
     /* For constraints on bones, use the rest position to bind b-bone segments
      * and envelopes, to allow safely changing the bone location as if parented. */
     copy_v3_v3(input_co, cob->pchan->bone->arm_head);
-    mul_m4_v3(cob->ob->obmat, input_co);
+    mul_m4_v3(cob->ob->object_to_world, input_co);
   }
   else {
     copy_v3_v3(input_co, cob->matrix[3]);
@@ -3927,7 +3932,7 @@ static void clampto_evaluate(bConstraint *con, bConstraintOb *cob, ListBase *tar
         unit_m4(totmat);
         copy_v3_v3(totmat[3], vec);
 
-        mul_m4_m4m4(targetMatrix, ct->tar->obmat, totmat);
+        mul_m4_m4m4(targetMatrix, ct->tar->object_to_world, totmat);
       }
     }
 
@@ -4227,7 +4232,7 @@ static void shrinkwrap_get_tarmat(struct Depsgraph *UNUSED(depsgraph),
 
     if (BKE_shrinkwrap_init_tree(
             &tree, target_eval, scon->shrinkType, scon->shrinkMode, do_track_normal)) {
-      BLI_space_transform_from_matrices(&transform, cob->matrix, ct->tar->obmat);
+      BLI_space_transform_from_matrices(&transform, cob->matrix, ct->tar->object_to_world);
 
       switch (scon->shrinkType) {
         case MOD_SHRINKWRAP_NEAREST_SURFACE:
@@ -4902,7 +4907,7 @@ static void followtrack_evaluate_using_3d_position_object(FollowTrackContext *co
 
   /* Object matrix of the camera. */
   float camera_obmat[4][4];
-  copy_m4_m4(camera_obmat, camera_object->obmat);
+  copy_m4_m4(camera_obmat, camera_object->object_to_world);
 
   /* Calculate inverted matrix of the solved camera at the current time. */
   float reconstructed_camera_mat[4][4];
@@ -5054,10 +5059,10 @@ static void followtrack_project_to_depth_object_if_needed(FollowTrackContext *co
   }
 
   float depth_object_mat_inv[4][4];
-  invert_m4_m4(depth_object_mat_inv, depth_object->obmat);
+  invert_m4_m4(depth_object_mat_inv, depth_object->object_to_world);
 
   float ray_start[3], ray_end[3];
-  mul_v3_m4v3(ray_start, depth_object_mat_inv, context->camera_object->obmat[3]);
+  mul_v3_m4v3(ray_start, depth_object_mat_inv, context->camera_object->object_to_world[3]);
   mul_v3_m4v3(ray_end, depth_object_mat_inv, cob->matrix[3]);
 
   float ray_direction[3];
@@ -5080,7 +5085,7 @@ static void followtrack_project_to_depth_object_if_needed(FollowTrackContext *co
                                           &tree_data);
 
   if (result != -1) {
-    mul_v3_m4v3(cob->matrix[3], depth_object->obmat, hit.co);
+    mul_v3_m4v3(cob->matrix[3], depth_object->object_to_world, hit.co);
   }
 
   free_bvhtree_from_mesh(&tree_data);
@@ -5128,9 +5133,9 @@ static void followtrack_evaluate_using_2d_position(FollowTrackContext *context,
     }
 
     float disp[3];
-    mul_v3_m4v3(disp, camera_object->obmat, vec);
+    mul_v3_m4v3(disp, camera_object->object_to_world, vec);
 
-    copy_m4_m4(rmat, camera_object->obmat);
+    copy_m4_m4(rmat, camera_object->object_to_world);
     zero_v3(rmat[3]);
     mul_m4_m4m4(cob->matrix, cob->matrix, rmat);
 
@@ -5152,10 +5157,10 @@ static void followtrack_evaluate_using_2d_position(FollowTrackContext *context,
     }
 
     float disp[3];
-    mul_v3_m4v3(disp, camera_object->obmat, vec);
+    mul_v3_m4v3(disp, camera_object->object_to_world, vec);
 
     /* apply camera rotation so Z-axis would be co-linear */
-    copy_m4_m4(rmat, camera_object->obmat);
+    copy_m4_m4(rmat, camera_object->object_to_world);
     zero_v3(rmat[3]);
     mul_m4_m4m4(cob->matrix, cob->matrix, rmat);
 
@@ -5303,7 +5308,7 @@ static void objectsolver_evaluate(bConstraint *con, bConstraintOb *cob, ListBase
   BKE_tracking_camera_get_reconstructed_interpolate(tracking, object, framenr, mat);
 
   invert_m4_m4(imat, mat);
-  mul_m4_m4m4(parmat, camob->obmat, imat);
+  mul_m4_m4m4(parmat, camob->object_to_world, imat);
 
   copy_m4_m4(obmat, cob->matrix);
 
@@ -5650,7 +5655,7 @@ bool BKE_constraint_apply_for_object(Depsgraph *depsgraph,
   BLI_freelinkN(&single_con, new_con);
 
   /* Apply transform from matrix. */
-  BKE_object_apply_mat4(ob, ob_eval->obmat, true, true);
+  BKE_object_apply_mat4(ob, ob_eval->object_to_world, true, true);
 
   return true;
 }
@@ -6237,7 +6242,7 @@ void BKE_constraint_target_matrix_get(struct Depsgraph *depsgraph,
         cob->ob = (Object *)ownerdata;
         cob->pchan = NULL;
         if (cob->ob) {
-          copy_m4_m4(cob->matrix, cob->ob->obmat);
+          copy_m4_m4(cob->matrix, cob->ob->object_to_world);
           copy_m4_m4(cob->startmat, cob->matrix);
         }
         else {