Merge pull request #18099 from peppy/snapping-tidy

Add xmldoc and rename methods in `IPositionSnapProvider` for legibility

osu.Game.Rulesets.Catch/Edit/CatchHitObjectComposer.cs

@@ -89,9 +89,9 @@ namespace osu.Game.Rulesets.Catch.Edit
             new TernaryButton(distanceSnapToggle, "Distance Snap", () => new SpriteIcon { Icon = FontAwesome.Solid.Ruler })
         });
 
-        public override SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition)
+        public override SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition)
         {
-            var result = base.SnapScreenSpacePositionToValidTime(screenSpacePosition);
+            var result = base.FindSnappedPositionAndTime(screenSpacePosition);
             result.ScreenSpacePosition.X = screenSpacePosition.X;
 
             if (distanceSnapGrid.IsPresent && distanceSnapGrid.GetSnappedPosition(result.ScreenSpacePosition) is SnapResult snapResult &&

osu.Game.Rulesets.Mania.Tests/Editor/TestSceneManiaBeatSnapGrid.cs

@@ -97,12 +97,12 @@ namespace osu.Game.Rulesets.Mania.Tests.Editor
             set => InternalChild = value;
         }
 
-        public override SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition)
+        public override SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition)
         {
             throw new System.NotImplementedException();
         }
 
-        public override SnapResult SnapScreenSpacePositionToValidPosition(Vector2 screenSpacePosition)
+        public override SnapResult FindSnappedPosition(Vector2 screenSpacePosition)
         {
             throw new System.NotImplementedException();
         }

osu.Game.Rulesets.Mania/Edit/ManiaHitObjectComposer.cs

@@ -56,9 +56,9 @@ namespace osu.Game.Rulesets.Mania.Edit
         protected override Playfield PlayfieldAtScreenSpacePosition(Vector2 screenSpacePosition) =>
             Playfield.GetColumnByPosition(screenSpacePosition);
 
-        public override SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition)
+        public override SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition)
         {
-            var result = base.SnapScreenSpacePositionToValidTime(screenSpacePosition);
+            var result = base.FindSnappedPositionAndTime(screenSpacePosition);
 
             switch (ScrollingInfo.Direction.Value)
             {
@@ -112,7 +112,7 @@ namespace osu.Game.Rulesets.Mania.Edit
             }
             else
             {
-                var result = SnapScreenSpacePositionToValidTime(inputManager.CurrentState.Mouse.Position);
+                var result = FindSnappedPositionAndTime(inputManager.CurrentState.Mouse.Position);
                 if (result.Time is double time)
                     beatSnapGrid.SelectionTimeRange = (time, time);
                 else

osu.Game.Rulesets.Osu.Tests/Editor/TestSceneOsuDistanceSnapGrid.cs

@@ -182,10 +182,10 @@ namespace osu.Game.Rulesets.Osu.Tests.Editor
 
         private class SnapProvider : IDistanceSnapProvider
         {
-            public SnapResult SnapScreenSpacePositionToValidPosition(Vector2 screenSpacePosition) =>
+            public SnapResult FindSnappedPosition(Vector2 screenSpacePosition) =>
                 new SnapResult(screenSpacePosition, null);
 
-            public SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition) => new SnapResult(screenSpacePosition, 0);
+            public SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition) => new SnapResult(screenSpacePosition, 0);
 
             public IBindable<double> DistanceSpacingMultiplier { get; } = new BindableDouble(1);
 

osu.Game.Rulesets.Osu/Edit/Blueprints/Sliders/Components/PathControlPointVisualiser.cs

@@ -255,7 +255,7 @@ namespace osu.Game.Rulesets.Osu.Edit.Blueprints.Sliders.Components
             {
                 // Special handling for selections containing head control point - the position of the slider changes which means the snapped position and time have to be taken into account
                 Vector2 newHeadPosition = Parent.ToScreenSpace(e.MousePosition + (dragStartPositions[0] - dragStartPositions[draggedControlPointIndex]));
-                var result = snapProvider?.SnapScreenSpacePositionToValidTime(newHeadPosition);
+                var result = snapProvider?.FindSnappedPositionAndTime(newHeadPosition);
 
                 Vector2 movementDelta = Parent.ToLocalSpace(result?.ScreenSpacePosition ?? newHeadPosition) - slider.Position;
 

osu.Game.Rulesets.Osu/Edit/OsuHitObjectComposer.cs

@@ -123,7 +123,7 @@ namespace osu.Game.Rulesets.Osu.Edit
             }
         }
 
-        public override SnapResult SnapScreenSpacePositionToValidPosition(Vector2 screenSpacePosition)
+        public override SnapResult FindSnappedPosition(Vector2 screenSpacePosition)
         {
             if (snapToVisibleBlueprints(screenSpacePosition, out var snapResult))
                 return snapResult;
@@ -131,9 +131,9 @@ namespace osu.Game.Rulesets.Osu.Edit
             return new SnapResult(screenSpacePosition, null);
         }
 
-        public override SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition)
+        public override SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition)
         {
-            var positionSnap = SnapScreenSpacePositionToValidPosition(screenSpacePosition);
+            var positionSnap = FindSnappedPosition(screenSpacePosition);
             if (positionSnap.ScreenSpacePosition != screenSpacePosition)
                 return positionSnap;
 
@@ -149,7 +149,7 @@ namespace osu.Game.Rulesets.Osu.Edit
                 return new SnapResult(rectangularPositionSnapGrid.ToScreenSpace(pos), null, PlayfieldAtScreenSpacePosition(screenSpacePosition));
             }
 
-            return base.SnapScreenSpacePositionToValidTime(screenSpacePosition);
+            return base.FindSnappedPositionAndTime(screenSpacePosition);
         }
 
         private bool snapToVisibleBlueprints(Vector2 screenSpacePosition, out SnapResult snapResult)

osu.Game.Tests/Visual/Editing/TestSceneDistanceSnapGrid.cs

@@ -162,10 +162,10 @@ namespace osu.Game.Tests.Visual.Editing
 
         private class SnapProvider : IDistanceSnapProvider
         {
-            public SnapResult SnapScreenSpacePositionToValidPosition(Vector2 screenSpacePosition) =>
+            public SnapResult FindSnappedPosition(Vector2 screenSpacePosition) =>
                 new SnapResult(screenSpacePosition, null);
 
-            public SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition) => new SnapResult(screenSpacePosition, 0);
+            public SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition) => new SnapResult(screenSpacePosition, 0);
 
             public IBindable<double> DistanceSpacingMultiplier { get; } = new BindableDouble(1);
 

osu.Game/Rulesets/Edit/HitObjectComposer.cs

@@ -362,7 +362,7 @@ namespace osu.Game.Rulesets.Edit
         /// <returns>The most relevant <see cref="Playfield"/>.</returns>
         protected virtual Playfield PlayfieldAtScreenSpacePosition(Vector2 screenSpacePosition) => drawableRulesetWrapper.Playfield;
 
-        public override SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition)
+        public override SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition)
         {
             var playfield = PlayfieldAtScreenSpacePosition(screenSpacePosition);
             double? targetTime = null;
@@ -416,9 +416,9 @@ namespace osu.Game.Rulesets.Edit
 
         #region IPositionSnapProvider
 
-        public abstract SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition);
+        public abstract SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition);
 
-        public virtual SnapResult SnapScreenSpacePositionToValidPosition(Vector2 screenSpacePosition) =>
+        public virtual SnapResult FindSnappedPosition(Vector2 screenSpacePosition) =>
             new SnapResult(screenSpacePosition, null);
 
         #endregion

osu.Game/Rulesets/Edit/IPositionSnapProvider.cs

@@ -5,23 +5,27 @@ using osuTK;
 
 namespace osu.Game.Rulesets.Edit
 {
+    /// <summary>
+    /// A snap provider which given a proposed position for a hit object, potentially offers a more correct position and time value inferred from the context of the beatmap.
+    /// Provided values are inferred in an isolated context, without consideration of other nearby hit objects.
+    /// </summary>
     public interface IPositionSnapProvider
     {
         /// <summary>
         /// Given a position, find a valid time and position snap.
         /// </summary>
         /// <remarks>
-        /// This call should be equivalent to running <see cref="SnapScreenSpacePositionToValidPosition"/> with any additional logic that can be performed without the time immutability restriction.
+        /// This call should be equivalent to running <see cref="FindSnappedPosition"/> with any additional logic that can be performed without the time immutability restriction.
         /// </remarks>
         /// <param name="screenSpacePosition">The screen-space position to be snapped.</param>
         /// <returns>The time and position post-snapping.</returns>
-        SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition);
+        SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition);
 
         /// <summary>
-        /// Given a position, find a value position snap, restricting time to its input value.
+        /// Given a position, find a valid position snap, without changing the time value.
         /// </summary>
         /// <param name="screenSpacePosition">The screen-space position to be snapped.</param>
         /// <returns>The position post-snapping. Time will always be null.</returns>
-        SnapResult SnapScreenSpacePositionToValidPosition(Vector2 screenSpacePosition);
+        SnapResult FindSnappedPosition(Vector2 screenSpacePosition);
     }
 }

osu.Game/Screens/Edit/Compose/Components/BlueprintContainer.cs

@@ -486,7 +486,7 @@ namespace osu.Game.Screens.Edit.Compose.Components
                     Vector2 originalPosition = movementBlueprintOriginalPositions[i];
                     var testPosition = originalPosition + distanceTravelled;
 
-                    var positionalResult = snapProvider.SnapScreenSpacePositionToValidPosition(testPosition);
+                    var positionalResult = snapProvider.FindSnappedPosition(testPosition);
 
                     if (positionalResult.ScreenSpacePosition == testPosition) continue;
 
@@ -505,7 +505,7 @@ namespace osu.Game.Screens.Edit.Compose.Components
             Vector2 movePosition = movementBlueprintOriginalPositions.First() + distanceTravelled;
 
             // Retrieve a snapped position.
-            var result = snapProvider?.SnapScreenSpacePositionToValidTime(movePosition);
+            var result = snapProvider?.FindSnappedPositionAndTime(movePosition);
 
             if (result == null)
             {

osu.Game/Screens/Edit/Compose/Components/ComposeBlueprintContainer.cs

@@ -214,7 +214,7 @@ namespace osu.Game.Screens.Edit.Compose.Components
 
         private void updatePlacementPosition()
         {
-            var snapResult = Composer.SnapScreenSpacePositionToValidTime(inputManager.CurrentState.Mouse.Position);
+            var snapResult = Composer.FindSnappedPositionAndTime(inputManager.CurrentState.Mouse.Position);
 
             // if no time was found from positional snapping, we should still quantize to the beat.
             snapResult.Time ??= Beatmap.SnapTime(EditorClock.CurrentTime, null);

osu.Game/Screens/Edit/Compose/Components/Timeline/Timeline.cs

@@ -307,10 +307,10 @@ namespace osu.Game.Screens.Edit.Compose.Components.Timeline
         /// </summary>
         public double VisibleRange => track.Length / Zoom;
 
-        public SnapResult SnapScreenSpacePositionToValidPosition(Vector2 screenSpacePosition) =>
+        public SnapResult FindSnappedPosition(Vector2 screenSpacePosition) =>
             new SnapResult(screenSpacePosition, null);
 
-        public SnapResult SnapScreenSpacePositionToValidTime(Vector2 screenSpacePosition) =>
+        public SnapResult FindSnappedPositionAndTime(Vector2 screenSpacePosition) =>
             new SnapResult(screenSpacePosition, beatSnapProvider.SnapTime(getTimeFromPosition(Content.ToLocalSpace(screenSpacePosition))));
 
         private double getTimeFromPosition(Vector2 localPosition) =>

osu.Game/Screens/Edit/Compose/Components/Timeline/TimelineHitObjectBlueprint.cs

@@ -382,7 +382,7 @@ namespace osu.Game.Screens.Edit.Compose.Components.Timeline
                 {
                     OnDragHandled?.Invoke(e);
 
-                    if (timeline.SnapScreenSpacePositionToValidTime(e.ScreenSpaceMousePosition).Time is double time)
+                    if (timeline.FindSnappedPositionAndTime(e.ScreenSpaceMousePosition).Time is double time)
                     {
                         switch (hitObject)
                         {