Implement polygon clipping

osu.Framework.Tests/Polygons/ConvexPolygonClipping.cs

···
+// Copyright (c) ppy Pty Ltd <[e-mail]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using NUnit.Framework;
+using osu.Framework.Extensions.PolygonExtensions;
+using osu.Framework.Graphics.Primitives;
+using osuTK;
+
+namespace osu.Framework.Tests.Polygons
+{
+    [TestFixture]
+    public class ConvexPolygonClipping
+    {
+        private static readonly Vector2 origin = Vector2.Zero;
+        private static readonly Vector2 up_1 = new Vector2(0, 1);
+        private static readonly Vector2 up_2 = new Vector2(0, 2);
+        private static readonly Vector2 up_3 = new Vector2(0, 3);
+        private static readonly Vector2 down_1 = new Vector2(0, -1);
+        private static readonly Vector2 down_2 = new Vector2(0, -2);
+        private static readonly Vector2 down_3 = new Vector2(0, -3);
+        private static readonly Vector2 left_1 = new Vector2(-1, 0);
+        private static readonly Vector2 left_2 = new Vector2(-2, 0);
+        private static readonly Vector2 left_3 = new Vector2(-3, 0);
+        private static readonly Vector2 right_1 = new Vector2(1, 0);
+        private static readonly Vector2 right_2 = new Vector2(2, 0);
+        private static readonly Vector2 right_3 = new Vector2(3, 0);
+
+        private static object[] externalTestCases => new object[]
+        {
+            // Non-rotated
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { up_2, up_3, up_3 + right_1, up_2 } },
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { right_2, right_2 + up_1, right_3 + up_1, right_3 } },
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { down_1, down_1 + right_1, down_2 + right_1, down_2 } },
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { left_2, left_2 + up_1, left_1 + up_1, left_1 } },
+            // Rotated
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { up_1 + right_2, up_2 + right_1, up_3 + right_2, up_2 + right_3 } },
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { up_1 + right_2, down_1 + right_3, down_2 + right_2, down_1 + right_1 } },
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { down_1 + right_1, down_2 + right_2, down_3 + right_1, down_2 } },
+            new object[] { new[] { origin, up_1, up_1 + right_1, right_1 }, new[] { left_1 + up_1, down_2, down_3 + left_2, left_2 } },
+        };
+
+        [TestCaseSource(nameof(externalTestCases))]
+        public void TestExternalPolygon(Vector2[] polygonVertices1, Vector2[] polygonVertices2)
+        {
+            var poly1 = new SimpleConvexPolygon(polygonVertices1);
+            var poly2 = new SimpleConvexPolygon(polygonVertices2);
+
+            Assert.That(poly1.Clip(poly2).Length, Is.Zero);
+            Assert.That(poly2.Clip(poly1).Length, Is.Zero);
+
+            Array.Reverse(polygonVertices1);
+            Array.Reverse(polygonVertices2);
+
+            Assert.That(poly1.Clip(poly2).Length, Is.Zero);
+            Assert.That(poly2.Clip(poly1).Length, Is.Zero);
+        }
+
+        private static object[] subjectFullyContainedTestCases => new object[]
+        {
+            // Same polygon
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { origin, up_2, up_2 + right_2, right_2 } },
+            new object[] { new[] { down_2, left_2, up_2, right_2 }, new[] { down_2, left_2, up_2, right_2 } },
+            // Corners
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { origin, up_1, up_1 + right_1, right_1 } },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { up_1, up_2, up_2 + right_1, up_1 + right_1 } },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { up_1 + right_1, up_2 + right_1, up_2 + right_2, up_1 + right_2 } },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { right_1, up_1 + right_1, up_1 + right_2, right_2 } },
+            new object[] { new[] { down_2, left_2, up_2, right_2 }, new[] { down_2, down_1, right_1, right_2 } },
+            new object[] { new[] { down_2, left_2, up_2, right_2 }, new[] { left_2, left_1, down_1, down_2 } },
+            new object[] { new[] { down_2, left_2, up_2, right_2 }, new[] { left_2, up_2, up_1, left_1 } },
+            new object[] { new[] { down_2, left_2, up_2, right_2 }, new[] { up_2, right_2, right_1, up_1 } },
+            // Padded
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { right_1 * 0.5f + up_1 * 0.5f, up_2 * 0.75f, up_2 * 0.75f + right_2 * 0.75f, right_2 * 0.75f } },
+            new object[] { new[] { down_2, left_2, up_2, right_2 }, new[] { down_1, left_1, up_1, right_1 } },
+            // Rotated
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { up_1 + right_1 * 0.5f, up_2 * 0.75f + right_1, up_1 + right_2 * 0.5f, up_1 * 0.5f + right_1 } },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { up_1, up_2 * 0.75f, up_2 + right_1 * 0.5f, up_2 + right_1 } },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { right_1, up_1 + right_2, up_1 * 0.5f + right_2, right_2 * 0.75f } },
+            new object[] { new[] { down_2, left_2, up_2, right_2 }, new[] { left_1 + up_1, up_1 + right_1, down_1 + right_1, left_1 + down_1 } },
+        };
+
+        [TestCaseSource(nameof(subjectFullyContainedTestCases))]
+        public void TestSubjectFullyContained(Vector2[] clipVertices, Vector2[] subjectVertices)
+        {
+            var clipPolygon = new SimpleConvexPolygon(clipVertices);
+            var subjectPolygon = new SimpleConvexPolygon(subjectVertices);
+
+            assertPolygonEquals(subjectPolygon, new SimpleConvexPolygon(clipPolygon.Clip(subjectPolygon).ToArray()), false);
+
+            Array.Reverse(clipVertices);
+            Array.Reverse(subjectVertices);
+
+            assertPolygonEquals(subjectPolygon, new SimpleConvexPolygon(clipPolygon.Clip(subjectPolygon).ToArray()), true);
+        }
+
+        [TestCaseSource(nameof(subjectFullyContainedTestCases))]
+        public void TestClipFullyContained(Vector2[] subjectVertices, Vector2[] clipVertices)
+        {
+            var clipPolygon = new SimpleConvexPolygon(clipVertices);
+            var subjectPolygon = new SimpleConvexPolygon(subjectVertices);
+
+            assertPolygonEquals(clipPolygon, new SimpleConvexPolygon(clipPolygon.Clip(subjectPolygon).ToArray()), false);
+
+            Array.Reverse(clipVertices);
+            Array.Reverse(subjectVertices);
+
+            assertPolygonEquals(clipPolygon, new SimpleConvexPolygon(clipPolygon.Clip(subjectPolygon).ToArray()), true);
+        }
+
+        private static object[] generalClippingTestCases => new object[]
+        {
+            new object[]
+            {
+                new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { left_1 + up_1, up_1 + right_1, down_1 + right_1, left_1 + down_1 }, new[] { origin, up_1, up_1 + right_1, right_1 }
+            },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { left_1, up_1, right_1, down_1 }, new[] { origin, up_1, right_1 } },
+            new object[]
+            {
+                new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { up_1 + right_1, up_3 + right_1, up_3 + right_3, up_1 + right_3 },
+                new[] { up_1 + right_1, up_2 + right_1, up_2 + right_2, up_1 + right_2 }
+            },
+            new object[]
+            {
+                new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { up_2 + right_1, up_3 + right_2, up_2 + right_3, up_1 + right_2 }, new[] { up_2 + right_1, up_2 + right_2, up_1 + right_2 }
+            },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { left_1 + up_1, up_3 + right_1, up_1 + right_1, origin }, new[] { up_2, up_2 + right_1, up_1 + right_1, origin } },
+            new object[]
+            {
+                new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { left_1 + up_1, up_1 + right_3, down_1 + right_3, left_1 + down_1 }, new[] { up_1, up_1 + right_2, right_2, origin }
+            },
+            new object[]
+            {
+                new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { down_1 + left_1, up_3 + left_1, up_3 + right_1, down_1 + right_1 }, new[] { origin, up_2, up_2 + right_1, right_1 }
+            },
+            new object[]
+            {
+                new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { down_1, up_1 + right_1, down_1 + right_2, down_2 + right_1 }, new[] { right_1 * 0.5f, up_1 + right_1, right_2 * 0.75f }
+            },
+            new object[] { new[] { origin, up_2, up_2 + right_2, right_2 }, new[] { origin, up_3 + right_3, right_2 }, new[] { origin, up_2 + right_2, right_2 } },
+            new object[] { new[] { up_2, right_2, down_2, left_2 }, new[] { left_1 + down_2, left_2 + down_2, up_2 + left_2, up_2 + left_1 }, new[] { up_1 + left_1, down_1 + left_1, left_2 } },
+            new object[] { new[] { up_2, right_2, down_2, left_2 }, new[] { origin, down_2 + left_2, up_2 + left_2 }, new[] { origin, down_1 + left_1, left_2, up_1 + left_1 } },
+            new object[] { new[] { up_2, right_2, down_2, left_2 }, new[] { origin, left_3, up_3 }, new[] { origin, left_2, up_2 } },
+            new object[] { new[] { up_2, right_2, down_2, left_2 }, new[] { origin, left_3, up_3, right_3 }, new[] { origin, left_2, up_2, right_2 } },
+            new object[]
+            {
+                new[] { left_1 + up_1, right_1 + up_1, down_1 + right_1, down_1 + left_1 }, new[] { up_2 * 0.75f, right_2 * 0.75f, down_2 * 0.75f, left_2 * 0.75f },
+                new[]
+                {
+                    down_1 + left_1 * 0.5f,
+                    down_1 * 0.5f + left_1,
+                    up_1 * 0.5f + left_1,
+                    up_1 + left_1 * 0.5f,
+                    up_1 + right_1 * 0.5f,
+                    up_1 * 0.5f + right_1,
+                    down_1 * 0.5f + right_1,
+                    down_1 + right_1 * 0.5f
+                }
+            },
+            new object[]
+            {
+                new[] { up_1, right_1, left_1 }, new[] { up_1 + right_1 * 0.5f, down_1 + right_1 * 0.5f, down_1 + left_1 * 0.5f, up_1 + left_1 * 0.5f },
+                new[] { up_1 * 0.5f + left_1 * 0.5f, up_1, up_1 * 0.5f + right_1 * 0.5f, right_1 * 0.5f, left_1 * 0.5f, }
+            },
+            new object[]
+            {
+                // Inverse of the above
+                new[] { up_1 + right_1 * 0.5f, down_1 + right_1 * 0.5f, down_1 + left_1 * 0.5f, up_1 + left_1 * 0.5f }, new[] { up_1, right_1, left_1 },
+                new[] { up_1 * 0.5f + left_1 * 0.5f, up_1, up_1 * 0.5f + right_1 * 0.5f, right_1 * 0.5f, left_1 * 0.5f, }
+            },
+            new object[]
+            {
+                new[] { up_1, right_1, down_1 + right_1, down_1 + left_1, left_1 }, new[] { left_1, up_1, up_1 + right_1, down_1 + right_1, down_1 },
+                new[] { up_1, right_1, right_1 + down_1, down_1, left_1 }
+            }
+        };
+
+        [TestCaseSource(nameof(generalClippingTestCases))]
+        public void TestGeneralClipping(Vector2[] clipVertices, Vector2[] subjectVertices, Vector2[] resultingVertices)
+        {
+            var clipPolygon = new SimpleConvexPolygon(clipVertices);
+            var subjectPolygon = new SimpleConvexPolygon(subjectVertices);
+
+            assertPolygonEquals(new SimpleConvexPolygon(resultingVertices), new SimpleConvexPolygon(clipPolygon.Clip(subjectPolygon).ToArray()), false);
+
+            Array.Reverse(clipVertices);
+            Array.Reverse(subjectVertices);
+
+            // The expected polygon is never reversed
+            assertPolygonEquals(new SimpleConvexPolygon(resultingVertices), new SimpleConvexPolygon(clipPolygon.Clip(subjectPolygon).ToArray()), false);
+        }
+
+        private void assertPolygonEquals(IPolygon expected, IPolygon actual, bool reverse)
+            => Assert.That(PolygonExtensions.GetRotation(actual.GetVertices()),
+                reverse
+                    ? Is.EqualTo(-PolygonExtensions.GetRotation(expected.GetVertices()))
+                    : Is.EqualTo(PolygonExtensions.GetRotation(expected.GetVertices())));
+    }
+}

osu.Framework/Extensions/PolygonExtensions/PolygonExtensions.cs

···
 
             return buffer.Slice(0, vertices.Length);
         }
+
+        public static int GetClipBufferSize<TPolygon1, TPolygon2>(this TPolygon1 clipPolygon, TPolygon2 subjectPolygon)
+            where TPolygon1 : IPolygon
+            where TPolygon2 : IPolygon
+        {
+            if (clipPolygon is IConvexPolygon && subjectPolygon is IConvexPolygon)
+            {
+                // If both polygons are convex, there can only be at most 2 intersections for each edge of the subject
+                return subjectPolygon.GetVertices().Length * 2;
+            }
+
+            // If both polygons are non-convex, each edge of one may intersect with each edge of the other, leading to at most n^2 vertices
+            // For simplicity, the case where only one of the two is non-convex is also covered under this case
+            return clipPolygon.GetVertices().Length * subjectPolygon.GetVertices().Length;
+        }
+
+        public static Span<Vector2> Clip<TPolygon1, TPolygon2>(this TPolygon1 clipPolygon, TPolygon2 subjectPolygon)
+            where TPolygon1 : IPolygon
+            where TPolygon2 : IPolygon
+            => clipPolygon.Clip(subjectPolygon, new Vector2[clipPolygon.GetClipBufferSize(subjectPolygon)]);
+
+        public static Span<Vector2> Clip<TPolygon1, TPolygon2>(this TPolygon1 clipPolygon, TPolygon2 subjectPolygon, Span<Vector2> buffer)
+            where TPolygon1 : IPolygon
+            where TPolygon2 : IPolygon
+        {
+            if (buffer.Length < GetClipBufferSize(clipPolygon, subjectPolygon))
+            {
+                throw new ArgumentException($"Clip buffer must have a length of {GetClipBufferSize(clipPolygon, subjectPolygon)}, but was {buffer.Length}."
+                                            + $"Use {nameof(GetClipBufferSize)} to calculate the size of the buffer.", nameof(buffer));
+            }
+
+            ReadOnlySpan<Vector2> subjectVertices = subjectPolygon.GetVertices();
+            ReadOnlySpan<Vector2> clipVertices = clipPolygon.GetVertices();
+
+            // Buffer is initially filled with the all of the subject's vertices
+            subjectVertices.CopyTo(buffer);
+
+            // Make sure that the subject vertices are clockwise-sorted
+            ClockwiseSort(buffer.Slice(0, subjectVertices.Length));
+
+            // The edges of clip that the subject will be clipped against
+            Span<Line> clipEdges = stackalloc Line[clipVertices.Length];
+
+            // Joins consecutive vertices to form the clip edges
+            // This is done via GetRotation() to avoid a secondary temporary storage
+            if (GetRotation(clipVertices) < 0)
+            {
+                for (int i = clipVertices.Length - 1, c = 0; i > 0; i--, c++)
+                    clipEdges[c] = new Line(clipVertices[i], clipVertices[i - 1]);
+                clipEdges[clipEdges.Length - 1] = new Line(clipVertices[0], clipVertices[clipVertices.Length - 1]);
+            }
+            else
+            {
+                for (int i = 0; i < clipVertices.Length - 1; i++)
+                    clipEdges[i] = new Line(clipVertices[i], clipVertices[i + 1]);
+                clipEdges[clipEdges.Length - 1] = new Line(clipVertices[clipVertices.Length - 1], clipVertices[0]);
+            }
+
+            // Number of vertices in the buffer that need to be tested against
+            // This becomes the number of vertices in the resulting polygon after each clipping iteration
+            int inputCount = subjectVertices.Length;
+
+            // Temporary storage for the vertices from the buffer as the buffer gets altered
+            Span<Vector2> inputVertices = stackalloc Vector2[buffer.Length];
+
+            foreach (var ce in clipEdges)
+            {
+                if (inputCount == 0)
+                    break;
+
+                // Store the original vertices (buffer will get altered)
+                buffer.CopyTo(inputVertices);
+
+                int outputCount = 0;
+                var startPoint = inputVertices[inputCount - 1];
+
+                for (int i = 0; i < inputCount; i++)
+                {
+                    var endPoint = inputVertices[i];
+
+                    if (isInsideRightHalfPlane(ce, endPoint))
+                    {
+                        if (!isInsideRightHalfPlane(ce, startPoint))
+                            buffer[outputCount++] = ce.At(ce.IntersectWith(new Line(startPoint, endPoint)).distance);
+
+                        buffer[outputCount++] = endPoint;
+                    }
+                    else if (isInsideRightHalfPlane(ce, startPoint))
+                        buffer[outputCount++] = ce.At(ce.IntersectWith(new Line(startPoint, endPoint)).distance);
+
+                    startPoint = endPoint;
+                }
+
+                inputCount = outputCount;
+            }
+
+            return buffer.Slice(0, inputCount);
+        }
+
+        /// <summary>
+        /// Determines whether a point is within the right half-plane of a line.
+        /// </summary>
+        /// <param name="line">The line.</param>
+        /// <param name="point">The point.</param>
+        /// <returns>Whether <paramref name="point"/> is in the right half-plane of <paramref name="line"/>.</returns>
+        private static bool isInsideRightHalfPlane(Line line, Vector2 point)
+        {
+            var diff1 = line.Direction;
+            var diff2 = point - line.StartPoint;
+
+            return diff1.X * diff2.Y - diff1.Y * diff2.X <= 0;
+        }
+
+        /// <summary>
+        /// Retrieves the rotation of a set of vertices.
+        /// </summary>
+        /// <param name="vertices">The vertices.</param>
+        /// <returns>Twice the area enclosed by the vertices. The vertices are in clockwise order if the value is positive.</returns>
+        public static float GetRotation(ReadOnlySpan<Vector2> vertices)
+        {
+            float rotation = 0;
+            for (int i = 0; i < vertices.Length - 1; ++i)
+            {
+                var vi = vertices[i];
+                var vj = vertices[i + 1];
+
+                rotation += (vj.X - vi.X) * (vj.Y + vi.Y);
+            }
+
+            rotation += (vertices[0].X - vertices[vertices.Length - 1].X) * (vertices[0].Y + vertices[vertices.Length - 1].Y);
+
+            return rotation;
+        }
+
+        /// <summary>
+        /// Sorts a set of vertices in clockwise order.
+        /// </summary>
+        /// <param name="vertices">The vertices to sort.</param>
+        public static void ClockwiseSort(Span<Vector2> vertices)
+        {
+            if (GetRotation(vertices) < 0)
+                vertices.Reverse();
+        }
     }
 }

osu.Framework/Graphics/Primitives/SimpleConvexPolygon.cs

···
+// Copyright (c) ppy Pty Ltd <[e-mail]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using osuTK;
+
+namespace osu.Framework.Graphics.Primitives
+{
+    public class SimpleConvexPolygon : IConvexPolygon
+    {
+        private readonly Vector2[] vertices;
+
+        public SimpleConvexPolygon(Vector2[] vertices)
+        {
+            this.vertices = vertices;
+        }
+
+        public ReadOnlySpan<Vector2> GetAxisVertices() => vertices;
+
+        public ReadOnlySpan<Vector2> GetVertices() => vertices;
+
+        public int MaxClipVertices => vertices.Length * 2;
+    }
+}