1 files changed, 15 insertions, 3 deletions
diff --git a/gfx/2d/Matrix.h b/gfx/2d/Matrix.h
index 84c9a5280..d6835c8e6 100644
--- a/gfx/2d/Matrix.h
+++ b/gfx/2d/Matrix.h
@@ -723,7 +723,7 @@ public:
    * The resulting vertices are populated in aVerts.  aVerts must be
    * pre-allocated to hold at least kTransformAndClipRectMaxVerts Points.
    * The vertex count is returned by TransformAndClipRect.  It is possible to
-   * emit fewer that 3 vertices, indicating that aRect will not be visible
+   * emit fewer than 3 vertices, indicating that aRect will not be visible
    * within aClip.
    */
   template<class F>
@@ -751,8 +751,10 @@ public:
     planeNormals[3] = Point4DTyped<UnknownUnits, F>(0.0, -1.0, 0.0, aClip.YMost());
 
     // Iterate through each clipping plane and clip the polygon.
-    // In each pass, we double buffer, alternating between points[0] and
-    // points[1].
+    // For each clipping plane, we intersect the plane with all polygon edges.
+    // Each pass can increase or decrease the number of points that make up the
+    // current clipped polygon. We double buffer that set of points, alternating
+    // between points[0] and points[1].
     for (int plane=0; plane < 4; plane++) {
       planeNormals[plane].Normalize();
       Point4DTyped<UnknownUnits, F>* srcPoint = dstPointStart;
@@ -761,6 +763,14 @@ public:
       dstPointStart = points[~plane & 1];
       dstPoint = dstPointStart;
 
+      // Iterate over the polygon edges. In each iteration the current edge is
+      // the edge from prevPoint to srcPoint. If the two end points lie on
+      // different sides of the plane, we have an intersection. Otherwise, the
+      // edge is either completely "inside" the half-space created by the
+      // clipping plane, and we add srcPoint, or it is completely "outside", and
+      // we discard srcPoint.
+      // We may create duplicated points in the polygon. We keep those around
+      // until all clipping is done and then filter out duplicates at the end.
       Point4DTyped<UnknownUnits, F>* prevPoint = srcPointEnd - 1;
       F prevDot = planeNormals[plane].DotProduct(*prevPoint);
       while (srcPoint < srcPointEnd && ((dstPoint - dstPointStart) < kTransformAndClipRectMaxVerts)) {
@@ -784,6 +794,8 @@ public:
       }
 
       if (dstPoint == dstPointStart) {
+        // No polygon points were produced, so the polygon has been
+        // completely clipped away by the current clipping plane. Exit.
         break;
       }
     }