Transform Snap: nearest face snap mode, snapping options, refactoring.

This commit adds a new face nearest snapping mode, adds new snapping
options, and (lightly) refactors code around snapping.

The new face nearest snapping mode will snap transformed geometry to the
nearest surface in world space. In contrast, the original face snapping
mode uses projection (raycasting) to snap source to target geometry.
Face snapping therefore only works with what is visible, while nearest
face snapping can snap geometry to occluded parts of the scene. This new
mode is critical for retopology work, where some of the target mesh
might be occluded (ex: sliding an edge loop that wraps around the
backside of target mesh).

The nearest face snapping mode has two options: "Snap to Same Target"
and "Face Nearest Steps". When the Snap to Same Object option is
enabled, the selected source geometry will stay near the target that it
is nearest before editing started, which prevents the source geometry
from snapping to other targets. The Face Nearest Steps divides the
overall transformation for each vertex into n smaller transformations,
then applies those n transformations with surface snapping interlacing
each step. This steps option handles transformations that cross U-shaped
targets better.

The new snapping options allow the artist to better control which target
objects (objects to which the edited geometry is snapped) are considered
when snapping. In particular, the only option for filtering target
objects was a "Project onto Self", which allowed the currently edited
mesh to be considered as a target. Now, the artist can choose any
combination of the following to be considered as a target: the active
object, any edited object that isn't active (see note below), any non-
edited object. Additionally, the artist has another snapping option to
exclude objects that are not selectable as potential targets.

The Snapping Options dropdown has been lightly reorganized to allow for
the additional options.

Included in this patch:

- Snap target selection is more controllable for artist with additional
  snapping options.
- Renamed a few of the snap-related functions to better reflect what
  they actually do now. For example, `applySnapping` implies that this
  handles the snapping, while `applyProject` implies something entirely
  different is done there. However, better names would be
  `applySnappingAsGroup` and `applySnappingIndividual`, respectively,
  where `applySnappingIndividual` previously only does Face snapping.
- Added an initial coordinate parameter to snapping functions so that
  the nearest target before transforming can be determined(for "Snap to
  Same Object"), and so the transformation can be broken into smaller
  steps (for "Face Nearest Steps").
- Separated the BVH Tree getter code from mesh/edit mesh to its own
  function to reduce code duplication.
- Added icon for nearest face snapping.
- The original "Project onto Self" was actually not correct! This option
  should be called "Project onto Active" instead, but that only matters
  when editing multiple meshes at the same time. This patch makes this
  change in the UI.

Reviewed By: Campbell Barton, Germano Cavalcante

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

2 files changed, 37 insertions, 8 deletions

diff --git a/source/blender/editors/include/ED_transform_snap_object_context.h b/source/blender/editors/include/ED_transform_snap_object_context.h
index 20353c21f93..db44d9af706 100644
--- a/source/blender/editors/include/ED_transform_snap_object_context.h
+++ b/source/blender/editors/include/ED_transform_snap_object_context.h
@@ -60,6 +60,10 @@ struct SnapObjectParams {
   bool use_occlusion_test : true;
   /* exclude back facing geometry from snapping */
   bool use_backface_culling : true;
+  /* Break nearest face snapping into steps to improve transformations across U-shaped targets. */
+  short face_nearest_steps;
+  /* Enable to force nearest face snapping to snap to target the source was initially near. */
+  bool keep_on_same_target;
 };
 
 typedef struct SnapObjectContext SnapObjectContext;
@@ -114,12 +118,33 @@ bool ED_transform_snap_object_project_ray_all(SnapObjectContext *sctx,
                                               bool sort,
                                               struct ListBase *r_hit_list);
 
+/**
+ * Perform snapping.
+ *
+ * Given a 2D region value, snap to vert/edge/face/grid.
+ *
+ * \param sctx: Snap context.
+ * \param snap_to: Target elements to snap source to.
+ * \param params: Addition snapping options.
+ * \param init_co: Initial world-space coordinate of source (optional).
+ * \param mval: Current transformed screen-space coordinate or mouse position (optional).
+ * \param prev_co: Current transformed world-space coordinate of source (optional).
+ * \param dist_px: Maximum distance to snap (in pixels).
+ * \param r_loc: Snapped world-space coordinate.
+ * \param r_no: Snapped world-space normal (optional).
+ * \param r_index: Index of snapped-to target element (optional).
+ * \param r_ob: Snapped-to target object (optional).
+ * \param r_obmat: Matrix of snapped-to target object (optional).
+ * \param r_face_nor: World-space normal of snapped-to target face (optional).
+ * \return Snapped-to element, #eSnapMode.
+ */
 eSnapMode ED_transform_snap_object_project_view3d_ex(struct SnapObjectContext *sctx,
                                                      struct Depsgraph *depsgraph,
                                                      const ARegion *region,
                                                      const View3D *v3d,
-                                                     eSnapMode snap_to,
+                                                     const eSnapMode snap_to,
                                                      const struct SnapObjectParams *params,
+                                                     const float init_co[3],
                                                      const float mval[2],
                                                      const float prev_co[3],
                                                      float *dist_px,
@@ -135,19 +160,23 @@ eSnapMode ED_transform_snap_object_project_view3d_ex(struct SnapObjectContext *s
  * Given a 2D region value, snap to vert/edge/face.
  *
  * \param sctx: Snap context.
- * \param mval: Screenspace coordinate.
- * \param prev_co: Coordinate for perpendicular point calculation (optional).
+ * \param snap_to: Target elements to snap source to.
+ * \param params: Addition snapping options.
+ * \param init_co: Initial world-space coordinate of source (optional).
+ * \param mval: Current transformed screen-space coordinate or mouse position (optional).
+ * \param prev_co: Current transformed world-space coordinate of source (optional).
  * \param dist_px: Maximum distance to snap (in pixels).
- * \param r_loc: hit location.
- * \param r_no: hit normal (optional).
- * \return Snap success.
+ * \param r_loc: Snapped world-space coordinate.
+ * \param r_no: Snapped world-space normal (optional).
+ * \return Snapped-to element, #eSnapMode.
  */
 eSnapMode ED_transform_snap_object_project_view3d(struct SnapObjectContext *sctx,
                                                   struct Depsgraph *depsgraph,
                                                   const ARegion *region,
                                                   const View3D *v3d,
-                                                  eSnapMode snap_to,
+                                                  const eSnapMode snap_to,
                                                   const struct SnapObjectParams *params,
+                                                  const float init_co[3],
                                                   const float mval[2],
                                                   const float prev_co[3],
                                                   float *dist_px,
diff --git a/source/blender/editors/include/UI_icons.h b/source/blender/editors/include/UI_icons.h
index f1c0acf43f7..09057fd846e 100644
--- a/source/blender/editors/include/UI_icons.h
+++ b/source/blender/editors/include/UI_icons.h
@@ -652,7 +652,7 @@ DEF_ICON(PARTICLE_TIP)
 DEF_ICON(PARTICLE_PATH)
 
 /* EDITING */
-DEF_ICON_BLANK(669)
+DEF_ICON(SNAP_FACE_NEAREST)
 DEF_ICON(SNAP_FACE_CENTER)
 DEF_ICON(SNAP_PERPENDICULAR)
 DEF_ICON(SNAP_MIDPOINT)