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

15 files changed, 38 insertions, 37 deletions

diff --git a/source/blender/io/alembic/exporter/abc_writer_hair.cc b/source/blender/io/alembic/exporter/abc_writer_hair.cc
index f872943ad5c..13136372c56 100644
--- a/source/blender/io/alembic/exporter/abc_writer_hair.cc
+++ b/source/blender/io/alembic/exporter/abc_writer_hair.cc
@@ -118,7 +118,7 @@ void ABCHairWriter::write_hair_sample(const HierarchyContext &context,
 {
   /* Get untransformed vertices, there's a xform under the hair. */
   float inv_mat[4][4];
-  invert_m4_m4_safe(inv_mat, context.object->obmat);
+  invert_m4_m4_safe(inv_mat, context.object->object_to_world);
 
   MTFace *mtface = (MTFace *)CustomData_get_layer(&mesh->fdata, CD_MTFACE);
   MFace *mface = (MFace *)CustomData_get_layer(&mesh->fdata, CD_MFACE);
@@ -241,7 +241,7 @@ void ABCHairWriter::write_hair_child_sample(const HierarchyContext &context,
 {
   /* Get untransformed vertices, there's a xform under the hair. */
   float inv_mat[4][4];
-  invert_m4_m4_safe(inv_mat, context.object->obmat);
+  invert_m4_m4_safe(inv_mat, context.object->object_to_world);
 
   MFace *mface = (MFace *)CustomData_get_layer(&mesh->fdata, CD_MFACE);
   MTFace *mtface = (MTFace *)CustomData_get_layer(&mesh->fdata, CD_MTFACE);
diff --git a/source/blender/io/alembic/intern/abc_axis_conversion.cc b/source/blender/io/alembic/intern/abc_axis_conversion.cc
index 00e5890e9d3..35a19d0fbc0 100644
--- a/source/blender/io/alembic/intern/abc_axis_conversion.cc
+++ b/source/blender/io/alembic/intern/abc_axis_conversion.cc
@@ -134,15 +134,15 @@ void create_transform_matrix(Object *obj,
   if (mode == ABC_MATRIX_LOCAL && obj->parent) {
     /* Note that this produces another matrix than the local matrix, due to
      * constraints and modifiers as well as the obj->parentinv matrix. */
-    invert_m4_m4(obj->parent->imat, obj->parent->obmat);
-    mul_m4_m4m4(zup_mat, obj->parent->imat, obj->obmat);
+    invert_m4_m4(obj->parent->imat, obj->parent->object_to_world);
+    mul_m4_m4m4(zup_mat, obj->parent->imat, obj->object_to_world);
   }
   else {
-    copy_m4_m4(zup_mat, obj->obmat);
+    copy_m4_m4(zup_mat, obj->object_to_world);
   }
 
   if (proxy_from) {
-    mul_m4_m4m4(zup_mat, proxy_from->obmat, zup_mat);
+    mul_m4_m4m4(zup_mat, proxy_from->object_to_world, zup_mat);
   }
 
   copy_m44_axis_swap(r_yup_mat, zup_mat, ABC_YUP_FROM_ZUP);
diff --git a/source/blender/io/alembic/intern/abc_reader_object.cc b/source/blender/io/alembic/intern/abc_reader_object.cc
index af26565f8d6..f3a07eaad3f 100644
--- a/source/blender/io/alembic/intern/abc_reader_object.cc
+++ b/source/blender/io/alembic/intern/abc_reader_object.cc
@@ -165,7 +165,7 @@ void AbcObjectReader::setupObjectTransform(const chrono_t time)
 
   /* Apply the matrix to the object. */
   BKE_object_apply_mat4(m_object, transform_from_alembic, true, false);
-  BKE_object_to_mat4(m_object, m_object->obmat);
+  BKE_object_to_mat4(m_object, m_object->object_to_world);
 
   if (!is_constant || m_settings->always_add_cache_reader) {
     bConstraint *con = BKE_constraint_add_for_object(
diff --git a/source/blender/io/collada/AnimationImporter.cpp b/source/blender/io/collada/AnimationImporter.cpp
index 2d872377bbf..826d7864067 100644
--- a/source/blender/io/collada/AnimationImporter.cpp
+++ b/source/blender/io/collada/AnimationImporter.cpp
@@ -332,8 +332,8 @@ void AnimationImporter::read_node_transform(COLLADAFW::Node *node, Object *ob)
   float mat[4][4];
   TransformReader::get_node_mat(mat, node, &uid_animated_map, ob);
   if (ob) {
-    copy_m4_m4(ob->obmat, mat);
-    BKE_object_apply_mat4(ob, ob->obmat, false, false);
+    copy_m4_m4(ob->object_to_world, mat);
+    BKE_object_apply_mat4(ob, ob->object_to_world, false, false);
   }
 }
 
@@ -2097,7 +2097,7 @@ Object *AnimationImporter::get_joint_object(COLLADAFW::Node *root,
 
     if (par_job) {
       float temp[4][4], ipar[4][4];
-      invert_m4_m4(ipar, par_job->obmat);
+      invert_m4_m4(ipar, par_job->object_to_world);
       copy_m4_m4(temp, mat);
       mul_m4_m4m4(mat, ipar, temp);
     }
diff --git a/source/blender/io/collada/ArmatureImporter.cpp b/source/blender/io/collada/ArmatureImporter.cpp
index 1310337f501..7de08f89b7d 100644
--- a/source/blender/io/collada/ArmatureImporter.cpp
+++ b/source/blender/io/collada/ArmatureImporter.cpp
@@ -114,7 +114,7 @@ int ArmatureImporter::create_bone(SkinInfo *skin,
       Object *ob_arm = skin->BKE_armature_from_object();
       if (ob_arm) {
         float invmat[4][4];
-        invert_m4_m4(invmat, ob_arm->obmat);
+        invert_m4_m4(invmat, ob_arm->object_to_world);
         mul_m4_m4m4(mat, invmat, mat);
       }
 
@@ -708,7 +708,7 @@ void ArmatureImporter::set_pose(Object *ob_arm,
 
     copy_m4_m4(mat, obmat);
     float invObmat[4][4];
-    invert_m4_m4(invObmat, ob_arm->obmat);
+    invert_m4_m4(invObmat, ob_arm->object_to_world);
     mul_m4_m4m4(pchan->pose_mat, invObmat, mat);
   }
 
diff --git a/source/blender/io/collada/ControllerExporter.cpp b/source/blender/io/collada/ControllerExporter.cpp
index 6bf8d904a41..62bcdc5bf4c 100644
--- a/source/blender/io/collada/ControllerExporter.cpp
+++ b/source/blender/io/collada/ControllerExporter.cpp
@@ -406,7 +406,7 @@ void ControllerExporter::add_bind_shape_mat(Object *ob)
     bc_add_global_transform(f_obmat, export_settings.get_global_transform());
   }
 
-  // UnitConverter::mat4_to_dae_double(bind_mat, ob->obmat);
+  // UnitConverter::mat4_to_dae_double(bind_mat, ob->object_to_world);
   UnitConverter::mat4_to_dae_double(bind_mat, f_obmat);
   if (this->export_settings.get_limit_precision()) {
     BCMatrix::sanitize(bind_mat, LIMITTED_PRECISION);
@@ -523,7 +523,7 @@ std::string ControllerExporter::add_inv_bind_mats_source(Object *ob_arm,
       }
 
       /* make world-space matrix (bind_mat is armature-space) */
-      mul_m4_m4m4(world, ob_arm->obmat, bind_mat);
+      mul_m4_m4m4(world, ob_arm->object_to_world, bind_mat);
 
       if (!has_bindmat) {
         if (export_settings.get_apply_global_orientation()) {
diff --git a/source/blender/io/collada/DocumentImporter.cpp b/source/blender/io/collada/DocumentImporter.cpp
index 5e432682564..dae1c4ba894 100644
--- a/source/blender/io/collada/DocumentImporter.cpp
+++ b/source/blender/io/collada/DocumentImporter.cpp
@@ -412,8 +412,8 @@ Object *DocumentImporter::create_instance_node(Object *source_ob,
         }
       }
       /* calc new matrix and apply */
-      mul_m4_m4m4(obn->obmat, obn->obmat, mat);
-      BKE_object_apply_mat4(obn, obn->obmat, false, false);
+      mul_m4_m4m4(obn->object_to_world, obn->object_to_world, mat);
+      BKE_object_apply_mat4(obn, obn->object_to_world, false, false);
     }
   }
   else {
diff --git a/source/blender/io/collada/SkinInfo.cpp b/source/blender/io/collada/SkinInfo.cpp
index 0654bae3730..b4615635318 100644
--- a/source/blender/io/collada/SkinInfo.cpp
+++ b/source/blender/io/collada/SkinInfo.cpp
@@ -214,12 +214,12 @@ void SkinInfo::link_armature(bContext *C,
   ob->partype = PAROBJECT;
 
   BKE_object_workob_calc_parent(scene, ob, &workob);
-  invert_m4_m4(ob->parentinv, workob.obmat);
+  invert_m4_m4(ob->parentinv, workob.object_to_world);
 
   DEG_id_tag_update(&obn->id, ID_RECALC_TRANSFORM | ID_RECALC_GEOMETRY);
 #endif
-  copy_m4_m4(ob->obmat, bind_shape_matrix);
-  BKE_object_apply_mat4(ob, ob->obmat, false, false);
+  copy_m4_m4(ob->object_to_world, bind_shape_matrix);
+  BKE_object_apply_mat4(ob, ob->object_to_world, false, false);
 
   amd->deformflag = ARM_DEF_VGROUP;
 
diff --git a/source/blender/io/collada/collada_utils.cpp b/source/blender/io/collada/collada_utils.cpp
index 22a73cd7db2..96ff78a715a 100644
--- a/source/blender/io/collada/collada_utils.cpp
+++ b/source/blender/io/collada/collada_utils.cpp
@@ -129,7 +129,7 @@ bool bc_set_parent(Object *ob, Object *par, bContext *C, bool is_parent_space)
   const bool keep_transform = false;
 
   if (par && is_parent_space) {
-    mul_m4_m4m4(ob->obmat, par->obmat, ob->obmat);
+    mul_m4_m4m4(ob->object_to_world, par->object_to_world, ob->object_to_world);
   }
 
   bool ok = ED_object_parent_set(
@@ -348,10 +348,10 @@ std::string bc_replace_string(std::string data,
 void bc_match_scale(Object *ob, UnitConverter &bc_unit, bool scale_to_scene)
 {
   if (scale_to_scene) {
-    mul_m4_m4m4(ob->obmat, bc_unit.get_scale(), ob->obmat);
+    mul_m4_m4m4(ob->object_to_world, bc_unit.get_scale(), ob->object_to_world);
   }
-  mul_m4_m4m4(ob->obmat, bc_unit.get_rotation(), ob->obmat);
-  BKE_object_apply_mat4(ob, ob->obmat, false, false);
+  mul_m4_m4m4(ob->object_to_world, bc_unit.get_rotation(), ob->object_to_world);
+  BKE_object_apply_mat4(ob, ob->object_to_world, false, false);
 }
 
 void bc_match_scale(std::vector<Object *> *objects_done,
diff --git a/source/blender/io/common/intern/abstract_hierarchy_iterator.cc b/source/blender/io/common/intern/abstract_hierarchy_iterator.cc
index 03c1ba94d94..d559b0efe82 100644
--- a/source/blender/io/common/intern/abstract_hierarchy_iterator.cc
+++ b/source/blender/io/common/intern/abstract_hierarchy_iterator.cc
@@ -416,7 +416,7 @@ void AbstractHierarchyIterator::visit_object(Object *object,
   context->original_export_path = "";
   context->higher_up_export_path = "";
 
-  copy_m4_m4(context->matrix_world, object->obmat);
+  copy_m4_m4(context->matrix_world, object->object_to_world);
 
   ExportGraph::key_type graph_index = determine_graph_index_object(context);
   context_update_for_graph_index(context, graph_index);
diff --git a/source/blender/io/gpencil/intern/gpencil_io_base.cc b/source/blender/io/gpencil/intern/gpencil_io_base.cc
index b9d7b6719b1..6cc977bfced 100644
--- a/source/blender/io/gpencil/intern/gpencil_io_base.cc
+++ b/source/blender/io/gpencil/intern/gpencil_io_base.cc
@@ -79,7 +79,7 @@ void GpencilIO::prepare_camera_params(Scene *scene, const GpencilIOParams *ipara
     BKE_camera_params_compute_matrix(&params);
 
     float viewmat[4][4];
-    invert_m4_m4(viewmat, cam_ob->obmat);
+    invert_m4_m4(viewmat, cam_ob->object_to_world);
 
     mul_m4_m4m4(persmat_, params.winmat, viewmat);
   }
@@ -152,7 +152,7 @@ void GpencilIO::create_object_list()
 
     /* Save z-depth from view to sort from back to front. */
     if (is_camera_) {
-      float camera_z = dot_v3v3(camera_z_axis, object->obmat[3]);
+      float camera_z = dot_v3v3(camera_z_axis, object->object_to_world[3]);
       ObjectZ obz = {camera_z, object};
       ob_list_.append(obz);
     }
@@ -160,10 +160,10 @@ void GpencilIO::create_object_list()
       float zdepth = 0;
       if (rv3d_) {
         if (rv3d_->is_persp) {
-          zdepth = ED_view3d_calc_zfac(rv3d_, object->obmat[3]);
+          zdepth = ED_view3d_calc_zfac(rv3d_, object->object_to_world[3]);
         }
         else {
-          zdepth = -dot_v3v3(rv3d_->viewinv[2], object->obmat[3]);
+          zdepth = -dot_v3v3(rv3d_->viewinv[2], object->object_to_world[3]);
         }
         ObjectZ obz = {zdepth * -1.0f, object};
         ob_list_.append(obz);
diff --git a/source/blender/io/gpencil/intern/gpencil_io_export_pdf.cc b/source/blender/io/gpencil/intern/gpencil_io_export_pdf.cc
index ddd72f816b0..c042ca597c8 100644
--- a/source/blender/io/gpencil/intern/gpencil_io_export_pdf.cc
+++ b/source/blender/io/gpencil/intern/gpencil_io_export_pdf.cc
@@ -177,7 +177,7 @@ void GpencilExporterPDF::export_gpencil_layers()
         /* Apply layer thickness change. */
         gps_duplicate->thickness += gpl->line_change;
         /* Apply object scale to thickness. */
-        gps_duplicate->thickness *= mat4_to_scale(ob->obmat);
+        gps_duplicate->thickness *= mat4_to_scale(ob->object_to_world);
         CLAMP_MIN(gps_duplicate->thickness, 1.0f);
         /* Fill. */
         if ((is_fill) && (params_.flag & GP_EXPORT_FILL)) {
diff --git a/source/blender/io/gpencil/intern/gpencil_io_export_svg.cc b/source/blender/io/gpencil/intern/gpencil_io_export_svg.cc
index 58f12e9b8b1..8acb87f8e58 100644
--- a/source/blender/io/gpencil/intern/gpencil_io_export_svg.cc
+++ b/source/blender/io/gpencil/intern/gpencil_io_export_svg.cc
@@ -197,7 +197,7 @@ void GpencilExporterSVG::export_gpencil_layers()
         /* Apply layer thickness change. */
         gps_duplicate->thickness += gpl->line_change;
         /* Apply object scale to thickness. */
-        gps_duplicate->thickness *= mat4_to_scale(ob->obmat);
+        gps_duplicate->thickness *= mat4_to_scale(ob->object_to_world);
         CLAMP_MIN(gps_duplicate->thickness, 1.0f);
 
         const bool is_normalized = ((params_.flag & GP_EXPORT_NORM_THICKNESS) != 0) ||
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc b/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc
index d00c09b9013..f5a94b1fc8a 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc
@@ -124,10 +124,11 @@ void OBJMesh::set_world_axes_transform(const eIOAxis forward, const eIOAxis up)
   unit_m3(axes_transform);
   /* +Y-forward and +Z-up are the default Blender axis settings. */
   mat3_from_axis_conversion(forward, up, IO_AXIS_Y, IO_AXIS_Z, axes_transform);
-  mul_m4_m3m4(world_and_axes_transform_, axes_transform, export_object_eval_.obmat);
+  mul_m4_m3m4(world_and_axes_transform_, axes_transform, export_object_eval_.object_to_world);
   /* mul_m4_m3m4 does not transform last row of obmat, i.e. location data. */
-  mul_v3_m3v3(world_and_axes_transform_[3], axes_transform, export_object_eval_.obmat[3]);
-  world_and_axes_transform_[3][3] = export_object_eval_.obmat[3][3];
+  mul_v3_m3v3(
+      world_and_axes_transform_[3], axes_transform, export_object_eval_.object_to_world[3]);
+  world_and_axes_transform_[3][3] = export_object_eval_.object_to_world[3][3];
 
   /* Normals need inverse transpose of the regular matrix to handle non-uniform scale. */
   float normal_matrix[3][3];
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc b/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc
index 812c3e7b5d4..1b1ee5f8386 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc
@@ -31,10 +31,10 @@ void OBJCurve::set_world_axes_transform(const eIOAxis forward, const eIOAxis up)
   unit_m3(axes_transform);
   /* +Y-forward and +Z-up are the Blender's default axis settings. */
   mat3_from_axis_conversion(forward, up, IO_AXIS_Y, IO_AXIS_Z, axes_transform);
-  mul_m4_m3m4(world_axes_transform_, axes_transform, export_object_eval_->obmat);
-  /* #mul_m4_m3m4 does not transform last row of #Object.obmat, i.e. location data. */
-  mul_v3_m3v3(world_axes_transform_[3], axes_transform, export_object_eval_->obmat[3]);
-  world_axes_transform_[3][3] = export_object_eval_->obmat[3][3];
+  mul_m4_m3m4(world_axes_transform_, axes_transform, export_object_eval_->object_to_world);
+  /* #mul_m4_m3m4 does not transform last row of #Object.object_to_world, i.e. location data. */
+  mul_v3_m3v3(world_axes_transform_[3], axes_transform, export_object_eval_->object_to_world[3]);
+  world_axes_transform_[3][3] = export_object_eval_->object_to_world[3][3];
 }
 
 const char *OBJCurve::get_curve_name() const