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

1 files changed, 9 insertions, 6 deletions

diff --git a/source/blender/makesrna/intern/rna_scene.c b/source/blender/makesrna/intern/rna_scene.c
index 9b8e94db081..3b739561f9a 100644
--- a/source/blender/makesrna/intern/rna_scene.c
+++ b/source/blender/makesrna/intern/rna_scene.c
@@ -92,11 +92,11 @@ static const EnumPropertyItem uv_sculpt_relaxation_items[] = {
 };
 #endif
 
-const EnumPropertyItem rna_enum_snap_target_items[] = {
-    {SCE_SNAP_TARGET_CLOSEST, "CLOSEST", 0, "Closest", "Snap closest point onto target"},
-    {SCE_SNAP_TARGET_CENTER, "CENTER", 0, "Center", "Snap transformation center onto target"},
-    {SCE_SNAP_TARGET_MEDIAN, "MEDIAN", 0, "Median", "Snap median onto target"},
-    {SCE_SNAP_TARGET_ACTIVE, "ACTIVE", 0, "Active", "Snap active onto target"},
+const EnumPropertyItem rna_enum_snap_source_items[] = {
+    {SCE_SNAP_SOURCE_CLOSEST, "CLOSEST", 0, "Closest", "Snap closest point onto target"},
+    {SCE_SNAP_SOURCE_CENTER, "CENTER", 0, "Center", "Snap transformation center onto target"},
+    {SCE_SNAP_SOURCE_MEDIAN, "MEDIAN", 0, "Median", "Snap median onto target"},
+    {SCE_SNAP_SOURCE_ACTIVE, "ACTIVE", 0, "Active", "Snap active onto target"},
     {0, NULL, 0, NULL, NULL},
 };
 
@@ -3306,9 +3306,12 @@ static void rna_def_tool_settings(BlenderRNA *brna)
       "Absolute grid alignment while translating (based on the pivot center)");
   RNA_def_property_update(prop, NC_SCENE | ND_TOOLSETTINGS, NULL); /* header redraw */
 
+  /* TODO(@gfxcoder): Rename `snap_target` to `snap_source` to avoid
+   * previous ambiguity of "target" (now, "source" is geometry to be moved and "target" is
+   * geometry to which moved geometry is snapped). */
   prop = RNA_def_property(srna, "snap_target", PROP_ENUM, PROP_NONE);
   RNA_def_property_enum_sdna(prop, NULL, "snap_target");
-  RNA_def_property_enum_items(prop, rna_enum_snap_target_items);
+  RNA_def_property_enum_items(prop, rna_enum_snap_source_items);
   RNA_def_property_ui_text(prop, "Snap Target", "Which part to snap onto the target");
   RNA_def_property_update(prop, NC_SCENE | ND_TOOLSETTINGS, NULL); /* header redraw */