Refactor: Snap-related. Clarified attribute names and refactored #defines into enums

The transformation snapping code contains a bunch of `#define`s, some ambiguously or incorrectly named attributes.  This patch contains refactored code to improve this.  This patch does (should) not change functionality of snapping.

Clarified ambiguously / incorrectly named attributes.

  - "Target" is used to refer to the part of the source that is to be snapped (Active, Median, Center, Closest), but several other areas of Blender use the term "target" to refer to the thing being snapped to and "source" to refer to the thing getting snapped.  Moreover, the implications of the previous terms do not match the descriptions.  For example: `SCE_SNAP_TARGET_CENTER` does not snap the grabbed geometry to the center of the target, but instead "Snap transforamtion center onto target".
  - "Select" refers to the condition for an object to be a possible target for snapping.
  - `SCE_SNAP_MODE_FACE` is renamed to `SCE_SNAP_MODE_FACE_RAYCAST` to better describe its affect and to make way for other face snapping methods (ex: nearest).

Refactored related `#define` into `enum`s.  In particular, constants relating to...

  - `ToolSettings.snap_flag` are now in `enum eSnapFlag`
  - `ToolSettings.snap_mode` are now in `enum eSnapMode`
  - `ToolSettings.snap_source` (was `snap_target`) are now in `enum eSnapSourceSelect`
  - `ToolSettings.snap_flag` (`SCE_SNAP_NO_SELF`) and `TransSnap.target_select` are now in `enum eSnapTargetSelect`

As the terms became more consistent and the constants were packed together into meaningful enumerations, some of the attribute names seemed ambiguous.  For example, it is unclear whether `SnapObjectParams.snap_select` referred to the target or the source.  This patch also adds a small amount of clarity.

This patch also swaps out generic types (ex: `char`, `short`, `ushort`) and unclear hard coded numbers (ex: `0`) used with snap-related enumerations with the actual `enum`s and values.

Note: I did leave myself some comments to follow-up with further refactoring.  Specifically, using "target" and "source" consistently will mean the Python API will need to change (ex: `ToolSettings.snap_target` is not `ToolSettings.snap_source`).  If the API is going to change, it would be good to make sure that the used terms are descriptive enough.  For example, `bpy.ops.transform.translate` uses a `snap` argument to determine if snapping should be enabled while transforming.  Perhaps `use_snap` might be an improvement that's more consistent with other conventions.

This patch is (mostly) a subset of D14591, as suggested by @mano-wii.

Task T69342 proposes to separate the `Absolute Grid Snap` option out from `Increment` snapping method into its own method.  Also, there might be reason to create additional snapping methods or options.  (Indeed, D14591 heads in this direction).  This patch can work along with these suggestions, as this patch is trying to clarify the snapping code and to prompt more work in this area.

Reviewed By: mano-wii

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

5 files changed, 24 insertions, 29 deletions

diff --git a/source/blender/editors/space_view3d/view3d_cursor_snap.c b/source/blender/editors/space_view3d/view3d_cursor_snap.c
index 1e54afe46f0..395df42b2cb 100644
--- a/source/blender/editors/space_view3d/view3d_cursor_snap.c
+++ b/source/blender/editors/space_view3d/view3d_cursor_snap.c
@@ -8,7 +8,6 @@
  */
 
 #include "DNA_object_types.h"
-#include "DNA_scene_types.h"
 
 #include "BLI_listbase.h"
 #include "BLI_rect.h"
@@ -53,7 +52,7 @@ typedef struct SnapCursorDataIntern {
 
   struct SnapObjectContext *snap_context_v3d;
   const Scene *scene;
-  short snap_elem_hidden;
+  eSnapMode snap_elem_hidden;
 
   float prevpoint_stack[3];
 
@@ -373,7 +372,7 @@ void ED_view3d_cursor_snap_draw_util(RegionView3D *rv3d,
                                      const float normal[3],
                                      const uchar color_line[4],
                                      const uchar color_point[4],
-                                     const short snap_elem_type)
+                                     const eSnapMode snap_elem_type)
 {
   if (!loc_prev && !loc_curr) {
     return;
@@ -538,9 +537,9 @@ static bool v3d_cursor_is_snap_invert(SnapCursorDataIntern *data_intern, const w
 /** \name Update
  * \{ */
 
-static short v3d_cursor_snap_elements(V3DSnapCursorState *snap_state, Scene *scene)
+static eSnapMode v3d_cursor_snap_elements(V3DSnapCursorState *snap_state, Scene *scene)
 {
-  short snap_elements = snap_state->snap_elem_force;
+  eSnapMode snap_elements = snap_state->snap_elem_force;
   if (!snap_elements) {
     return scene->toolsettings->snap_mode;
   }
@@ -586,7 +585,7 @@ static void v3d_cursor_snap_update(V3DSnapCursorState *state,
   v3d_cursor_snap_context_ensure(scene);
 
   float co[3], no[3], face_nor[3], obmat[4][4], omat[3][3];
-  short snap_elem = 0;
+  eSnapMode snap_elem = SCE_SNAP_MODE_NONE;
   int snap_elem_index[3] = {-1, -1, -1};
   int index = -1;
 
@@ -595,8 +594,8 @@ static void v3d_cursor_snap_update(V3DSnapCursorState *state,
   zero_v3(face_nor);
   unit_m3(omat);
 
-  ushort snap_elements = v3d_cursor_snap_elements(state, scene);
-  data_intern->snap_elem_hidden = 0;
+  eSnapMode snap_elements = v3d_cursor_snap_elements(state, scene);
+  data_intern->snap_elem_hidden = SCE_SNAP_MODE_NONE;
   const bool calc_plane_omat = v3d_cursor_snap_calc_plane();
   if (calc_plane_omat && !(snap_elements & SCE_SNAP_MODE_FACE)) {
     data_intern->snap_elem_hidden = SCE_SNAP_MODE_FACE;
@@ -612,7 +611,7 @@ static void v3d_cursor_snap_update(V3DSnapCursorState *state,
     if (snap_data->is_snap_invert != !(ts->snap_flag & SCE_SNAP)) {
       snap_data->is_enabled = false;
       if (!calc_plane_omat) {
-        snap_data->snap_elem = 0;
+        snap_data->snap_elem = SCE_SNAP_MODE_NONE;
         return;
       }
       snap_elements = data_intern->snap_elem_hidden = SCE_SNAP_MODE_FACE;
@@ -620,8 +619,7 @@ static void v3d_cursor_snap_update(V3DSnapCursorState *state,
   }
 #endif
 
-  if (snap_elements & (SCE_SNAP_MODE_VERTEX | SCE_SNAP_MODE_EDGE | SCE_SNAP_MODE_FACE |
-                       SCE_SNAP_MODE_EDGE_MIDPOINT | SCE_SNAP_MODE_EDGE_PERPENDICULAR)) {
+  if (snap_elements & SCE_SNAP_MODE_GEOM) {
     float prev_co[3] = {0.0f};
     if (state->prevpoint) {
       copy_v3_v3(prev_co, state->prevpoint);
@@ -647,7 +645,7 @@ static void v3d_cursor_snap_update(V3DSnapCursorState *state,
         v3d,
         snap_elements,
         &(const struct SnapObjectParams){
-            .snap_select = SNAP_ALL,
+            .snap_target_select = SCE_SNAP_TARGET_ALL,
             .edit_mode_type = edit_mode_type,
             .use_occlusion_test = use_occlusion_test,
         },
@@ -668,7 +666,8 @@ static void v3d_cursor_snap_update(V3DSnapCursorState *state,
 
   if (calc_plane_omat) {
     RegionView3D *rv3d = region->regiondata;
-    bool orient_surface = snap_elem && (state->plane_orient == V3D_PLACE_ORIENT_SURFACE);
+    bool orient_surface = (snap_elem != SCE_SNAP_MODE_NONE) &&
+                          (state->plane_orient == V3D_PLACE_ORIENT_SURFACE);
     if (orient_surface) {
       copy_m3_m4(omat, obmat);
     }
@@ -699,7 +698,7 @@ static void v3d_cursor_snap_update(V3DSnapCursorState *state,
     }
   }
 
-  float *co_depth = snap_elem ? co : scene->cursor.location;
+  float *co_depth = (snap_elem != SCE_SNAP_MODE_NONE) ? co : scene->cursor.location;
   snap_elem &= ~data_intern->snap_elem_hidden;
   if (snap_elem == 0) {
     RegionView3D *rv3d = region->regiondata;
@@ -815,7 +814,7 @@ static void v3d_cursor_snap_draw_fn(bContext *C, int x, int y, void *UNUSED(cust
   }
 
   const bool draw_plane = state->draw_plane || state->draw_box;
-  if (!snap_data->snap_elem && !draw_plane) {
+  if (snap_data->snap_elem == SCE_SNAP_MODE_NONE && !draw_plane) {
     return;
   }
 
@@ -833,7 +832,7 @@ static void v3d_cursor_snap_draw_fn(bContext *C, int x, int y, void *UNUSED(cust
     v3d_cursor_plane_draw(rv3d, state->plane_axis, matrix);
   }
 
-  if (snap_data->snap_elem && (state->draw_point || state->draw_box)) {
+  if (snap_data->snap_elem != SCE_SNAP_MODE_NONE && (state->draw_point || state->draw_box)) {
     const float *prev_point = (snap_data->snap_elem & SCE_SNAP_MODE_EDGE_PERPENDICULAR) ?
                                   state->prevpoint :
                                   NULL;
diff --git a/source/blender/editors/space_view3d/view3d_edit.c b/source/blender/editors/space_view3d/view3d_edit.c
index a65e9a8d506..5fbdbef676c 100644
--- a/source/blender/editors/space_view3d/view3d_edit.c
+++ b/source/blender/editors/space_view3d/view3d_edit.c
@@ -910,7 +910,7 @@ void ED_view3d_cursor3d_position_rotation(bContext *C,
                                                    v3d,
                                                    SCE_SNAP_MODE_FACE,
                                                    &(const struct SnapObjectParams){
-                                                       .snap_select = SNAP_ALL,
+                                                       .snap_target_select = SCE_SNAP_TARGET_ALL,
                                                        .edit_mode_type = SNAP_GEOM_FINAL,
                                                        .use_occlusion_test = true,
                                                    },
diff --git a/source/blender/editors/space_view3d/view3d_gizmo_ruler.c b/source/blender/editors/space_view3d/view3d_gizmo_ruler.c
index 567022cc9d1..9aae30c4a7e 100644
--- a/source/blender/editors/space_view3d/view3d_gizmo_ruler.c
+++ b/source/blender/editors/space_view3d/view3d_gizmo_ruler.c
@@ -359,7 +359,7 @@ static bool view3d_ruler_item_mousemove(const bContext *C,
                                                   v3d,
                                                   SCE_SNAP_MODE_FACE,
                                                   &(const struct SnapObjectParams){
-                                                      .snap_select = SNAP_ALL,
+                                                      .snap_target_select = SCE_SNAP_TARGET_ALL,
                                                       .edit_mode_type = SNAP_GEOM_CAGE,
                                                   },
                                                   mval_fl,
@@ -374,7 +374,7 @@ static bool view3d_ruler_item_mousemove(const bContext *C,
                                              depsgraph,
                                              v3d,
                                              &(const struct SnapObjectParams){
-                                                 .snap_select = SNAP_ALL,
+                                                 .snap_target_select = SCE_SNAP_TARGET_ALL,
                                                  .edit_mode_type = SNAP_GEOM_CAGE,
                                              },
                                              ray_start,
@@ -1228,11 +1228,7 @@ static void WIDGETGROUP_ruler_setup(const bContext *C, wmGizmoGroup *gzgroup)
     gzt_snap = WM_gizmotype_find("GIZMO_GT_snap_3d", true);
     gizmo = WM_gizmo_new_ptr(gzt_snap, gzgroup, NULL);
 
-    RNA_enum_set(gizmo->ptr,
-                 "snap_elements_force",
-                 (SCE_SNAP_MODE_VERTEX | SCE_SNAP_MODE_EDGE | SCE_SNAP_MODE_FACE |
-                  /* SCE_SNAP_MODE_VOLUME | SCE_SNAP_MODE_GRID | SCE_SNAP_MODE_INCREMENT | */
-                  SCE_SNAP_MODE_EDGE_PERPENDICULAR | SCE_SNAP_MODE_EDGE_MIDPOINT));
+    RNA_enum_set(gizmo->ptr, "snap_elements_force", SCE_SNAP_MODE_GEOM);
     ED_gizmotypes_snap_3d_flag_set(gizmo, V3D_SNAPCURSOR_SNAP_EDIT_GEOM_CAGE);
     WM_gizmo_set_color(gizmo, (float[4]){1.0f, 1.0f, 1.0f, 1.0f});
 
diff --git a/source/blender/editors/space_view3d/view3d_navigate_walk.c b/source/blender/editors/space_view3d/view3d_navigate_walk.c
index 19e064438fc..c4eff01375b 100644
--- a/source/blender/editors/space_view3d/view3d_navigate_walk.c
+++ b/source/blender/editors/space_view3d/view3d_navigate_walk.c
@@ -412,7 +412,7 @@ static bool walk_floor_distance_get(RegionView3D *rv3d,
       walk->depsgraph,
       walk->v3d,
       &(const struct SnapObjectParams){
-          .snap_select = SNAP_ALL,
+          .snap_target_select = SCE_SNAP_TARGET_ALL,
           /* Avoid having to convert the edit-mesh to a regular mesh. */
           .edit_mode_type = SNAP_GEOM_EDIT,
       },
@@ -454,7 +454,7 @@ static bool walk_ray_cast(RegionView3D *rv3d,
                                              walk->depsgraph,
                                              walk->v3d,
                                              &(const struct SnapObjectParams){
-                                                 .snap_select = SNAP_ALL,
+                                                 .snap_target_select = SCE_SNAP_TARGET_ALL,
                                              },
                                              ray_start,
                                              ray_normal,
diff --git a/source/blender/editors/space_view3d/view3d_placement.c b/source/blender/editors/space_view3d/view3d_placement.c
index eefc085bdf8..d3b82476d09 100644
--- a/source/blender/editors/space_view3d/view3d_placement.c
+++ b/source/blender/editors/space_view3d/view3d_placement.c
@@ -695,7 +695,7 @@ static bool view3d_interactive_add_calc_snap(bContext *UNUSED(C),
   if (r_is_snap_invert) {
     *r_is_snap_invert = snap_data->is_snap_invert;
   }
-  return snap_data->snap_elem != 0;
+  return snap_data->snap_elem != SCE_SNAP_MODE_NONE;
 }
 
 /** \} */
@@ -1303,7 +1303,7 @@ static int idp_rna_snap_target_get_fn(struct PointerRNA *UNUSED(ptr),
                                       struct PropertyRNA *UNUSED(prop))
 {
   V3DSnapCursorState *snap_state = ED_view3d_cursor_snap_state_get();
-  if (!snap_state->snap_elem_force) {
+  if (snap_state->snap_elem_force == SCE_SNAP_MODE_NONE) {
     return PLACE_SNAP_TO_DEFAULT;
   }
 
@@ -1316,7 +1316,7 @@ static void idp_rna_snap_target_set_fn(struct PointerRNA *UNUSED(ptr),
                                        struct PropertyRNA *UNUSED(prop),
                                        int value)
 {
-  short snap_mode = 0; /* #toolsettings->snap_mode. */
+  eSnapMode snap_mode = SCE_SNAP_MODE_NONE; /* #toolsettings->snap_mode. */
   const enum ePlace_SnapTo snap_to = value;
   if (snap_to == PLACE_SNAP_TO_GEOMETRY) {
     snap_mode = SCE_SNAP_MODE_GEOM;