Bug 1351426 - Part 5: Cleanup style and comments r=kip
☠☠ backed out by 99cab65c998b ☠ ☠
authorMiko Mynttinen <mikokm@gmail.com>
Tue, 04 Apr 2017 03:59:31 +0200
changeset 560194 efdb4e01ad4e4ee99f5b8c3718873530b63e2c17
parent 560193 aeca2ef150b857167731ced9b3a8da68227b88a0
child 560195 dd7433e1cae3ac88b2f92f9e374847c2b44ee6e3
push id53365
push userjichen@mozilla.com
push dateTue, 11 Apr 2017 08:35:12 +0000
reviewerskip
bugs1351426
milestone55.0a1
Bug 1351426 - Part 5: Cleanup style and comments r=kip MozReview-Commit-ID: HOPY8v4UWKo
gfx/2d/Polygon.h
gfx/layers/BSPTree.h
--- a/gfx/2d/Polygon.h
+++ b/gfx/2d/Polygon.h
@@ -12,16 +12,20 @@
 #include "Point.h"
 #include "Triangle.h"
 
 #include <initializer_list>
 
 namespace mozilla {
 namespace gfx {
 
+/**
+ * Calculates the w = 0 intersection point for the edge defined by
+ * |aFirst| and |aSecond|.
+ */
 template<class Units>
 Point4DTyped<Units>
 CalculateEdgeIntersect(const Point4DTyped<Units>& aFirst,
                        const Point4DTyped<Units>& aSecond)
 {
   static const float w = 0.00001f;
   const float t = (w - aFirst.w) / (aSecond.w - aFirst.w);
   return aFirst + (aSecond - aFirst) * t;
@@ -54,16 +58,20 @@ ClipPointsAtInfinity(const nsTArray<Poin
     if ((first.w <= 0.0f) ^ (second.w <= 0.0f)) {
       outPoints.AppendElement(CalculateEdgeIntersect(first, second));
     }
   }
 
   return outPoints;
 }
 
+/**
+ * Calculates the distances between the points in |aPoints| and the plane
+ * defined by |aPlaneNormal| and |aPlanePoint|.
+ */
 template<class Units>
 nsTArray<float>
 CalculatePointPlaneDistances(const nsTArray<Point4DTyped<Units>>& aPoints,
                              const Point4DTyped<Units>& aPlaneNormal,
                              const Point4DTyped<Units>& aPlanePoint,
                              size_t& aPos, size_t& aNeg)
 {
   // Point classification might produce incorrect results due to numerical
@@ -141,17 +149,19 @@ ClipPointsWithPlane(const nsTArray<Point
 
       // Add the intersection point to both polygons.
       aBackPoints.AppendElement(p);
       aFrontPoints.AppendElement(p);
     }
   }
 }
 
-// PolygonTyped stores the points of a convex planar polygon.
+/**
+ * PolygonTyped stores the points of a convex planar polygon.
+ */
 template<class Units>
 class PolygonTyped {
   typedef Point3DTyped<Units> Point3DType;
   typedef Point4DTyped<Units> Point4DType;
 
 public:
   PolygonTyped() {}
 
@@ -167,16 +177,19 @@ public:
                         const Point4DType& aNormal = DefaultNormal())
     : mNormal(aNormal), mPoints(aPoints)
   {
 #ifdef DEBUG
     EnsurePlanarPolygon();
 #endif
   }
 
+  /**
+   * Returns the smallest 2D rectangle that can fully cover the polygon.
+   */
   RectTyped<Units> BoundingBox() const
   {
     if (mPoints.IsEmpty()) {
       return RectTyped<Units>();
     }
 
     float minX, maxX, minY, maxY;
     minX = maxX = mPoints[0].x;
@@ -188,27 +201,31 @@ public:
 
       minY = std::min(point.y, minY);
       maxY = std::max(point.y, maxY);
     }
 
     return RectTyped<Units>(minX, minY, maxX - minX, maxY - minY);
   }
 
-  // Clips the polygon against the given 2D rectangle.
+  /**
+   * Clips the polygon against the given 2D rectangle.
+   */
   PolygonTyped<Units> ClipPolygon(const RectTyped<Units>& aRect) const
   {
     if (aRect.IsEmpty()) {
       return PolygonTyped<Units>();
     }
 
     return ClipPolygon(FromRect(aRect));
   }
 
-  // Clips this polygon against the given polygon in 2D.
+  /**
+   * Clips this polygon against |aPolygon| in 2D and returns a new polygon.
+   */
   PolygonTyped<Units> ClipPolygon(const PolygonTyped<Units>& aPolygon) const
   {
     const nsTArray<Point4DType>& points = aPolygon.GetPoints();
 
     if (mPoints.IsEmpty() || points.IsEmpty()) {
       return PolygonTyped<Units>();
     }
 
@@ -246,16 +263,19 @@ public:
         // The clipping created a polygon with no area.
         return PolygonTyped<Units>();
       }
     }
 
     return PolygonTyped<Units>(Move(clippedPoints), mNormal);
   }
 
+  /**
+   * Returns a new polygon containing the bounds of the given 2D rectangle.
+   */
   static PolygonTyped<Units> FromRect(const RectTyped<Units>& aRect)
   {
     nsTArray<Point4DType> points {
       Point4DType(aRect.x, aRect.y, 0.0f, 1.0f),
       Point4DType(aRect.x, aRect.YMost(), 0.0f, 1.0f),
       Point4DType(aRect.XMost(), aRect.YMost(), 0.0f, 1.0f),
       Point4DType(aRect.XMost(), aRect.y, 0.0f, 1.0f)
     };
@@ -274,28 +294,32 @@ public:
   }
 
   bool IsEmpty() const
   {
     // If the polygon has less than three points, it has no visible area.
     return mPoints.Length() < 3;
   }
 
+  /**
+   * Returns a list of triangles covering the polygon.
+   */
   nsTArray<TriangleTyped<Units>> ToTriangles() const
   {
     nsTArray<TriangleTyped<Units>> triangles;
 
     if (IsEmpty()) {
       return triangles;
     }
 
+    // This fan triangulation method only works for convex polygons.
     for (size_t i = 1; i < mPoints.Length() - 1; ++i) {
       TriangleTyped<Units> triangle(Point(mPoints[0].x, mPoints[0].y),
                                     Point(mPoints[i].x, mPoints[i].y),
-                                    Point(mPoints[i+1].x, mPoints[i+1].y));
+                                    Point(mPoints[i + 1].x, mPoints[i + 1].y));
       triangles.AppendElement(Move(triangle));
     }
 
     return triangles;
   }
 
   void TransformToLayerSpace(const Matrix4x4Typed<Units, Units>& aTransform)
   {
--- a/gfx/layers/BSPTree.h
+++ b/gfx/layers/BSPTree.h
@@ -14,48 +14,52 @@
 
 #include <list>
 
 namespace mozilla {
 namespace layers {
 
 class Layer;
 
-// Represents a layer that might have a non-rectangular geometry.
+/**
+ * Represents a layer that might have a non-rectangular geometry.
+ */
 struct LayerPolygon {
-  explicit LayerPolygon(Layer *aLayer)
+  explicit LayerPolygon(Layer* aLayer)
     : layer(aLayer) {}
 
-  LayerPolygon(Layer *aLayer,
+  LayerPolygon(Layer* aLayer,
                gfx::Polygon&& aGeometry)
     : layer(aLayer), geometry(Some(Move(aGeometry))) {}
 
-  LayerPolygon(Layer *aLayer,
+  LayerPolygon(Layer* aLayer,
                nsTArray<gfx::Point4D>&& aPoints,
                const gfx::Point4D& aNormal)
     : layer(aLayer)
   {
     geometry.emplace(Move(aPoints), aNormal);
   }
 
-  Layer *layer;
+  Layer* layer;
   Maybe<gfx::Polygon> geometry;
 };
 
 /**
  * Allocate BSPTreeNodes from a memory arena to improve performance with
  * complex scenes.
  * The arena size of 4096 bytes was selected as an arbitrary power of two.
  * Depending on the platform, this size accommodates roughly 100 BSPTreeNodes.
  */
 typedef mozilla::ArenaAllocator<4096, 8> BSPTreeArena;
 
-// Represents a node in a BSP tree. The node contains at least one layer with
-// associated geometry that is used as a splitting plane, and at most two child
-// nodes that represent the splitting planes that further subdivide the space.
+/**
+* Represents a node in a BSP tree. The node contains at least one layer with
+* associated geometry that is used as a splitting plane, and at most two child
+* nodes that represent the splitting planes that further subdivide the space.
+*/
 struct BSPTreeNode {
   BSPTreeNode()
     : front(nullptr), back(nullptr) {}
 
   const gfx::Polygon& First() const
   {
     MOZ_ASSERT(!layers.empty());
     MOZ_ASSERT(layers.front().geometry);
@@ -67,50 +71,56 @@ struct BSPTreeNode {
     return mPool.Allocate(aSize);
   }
 
   BSPTreeNode* front;
   BSPTreeNode* back;
   std::list<LayerPolygon> layers;
 };
 
-// BSPTree class takes a list of layers as an input and uses binary space
-// partitioning algorithm to create a tree structure that can be used for
-// depth sorting.
-//
-// Sources for more information:
-// https://en.wikipedia.org/wiki/Binary_space_partitioning
-// ftp://ftp.sgi.com/other/bspfaq/faq/bspfaq.html
+/**
+ * BSPTree class takes a list of layers as an input and uses binary space
+ * partitioning algorithm to create a tree structure that can be used for
+ * depth sorting.
+
+ * Sources for more information:
+ * https://en.wikipedia.org/wiki/Binary_space_partitioning
+ * ftp://ftp.sgi.com/other/bspfaq/faq/bspfaq.html
+ */
 class BSPTree {
 public:
   /**
    * The constructor modifies layers in the given list.
    */
   explicit BSPTree(std::list<LayerPolygon>& aLayers)
   {
     MOZ_ASSERT(!aLayers.empty());
 
     mRoot = new (mPool) BSPTreeNode();
     BuildTree(mRoot, aLayers);
   }
 
-  // Builds and returns the back-to-front draw order for the created BSP tree.
+  /**
+   * Builds and returns the back-to-front draw order for the created BSP tree.
+   */
   nsTArray<LayerPolygon> GetDrawOrder() const
   {
     nsTArray<LayerPolygon> layers;
     BuildDrawOrder(mRoot, layers);
     return layers;
   }
 
 private:
   BSPTreeArena mPool;
   BSPTreeNode* mRoot;
 
-  // BuildDrawOrder and BuildTree are called recursively. The depth of the
-  // recursion depends on the amount of polygons and their intersections.
+  /**
+   * BuildDrawOrder and BuildTree are called recursively. The depth of the
+   * recursion depends on the amount of polygons and their intersections.
+   */
   void BuildDrawOrder(BSPTreeNode* aNode,
                       nsTArray<LayerPolygon>& aLayers) const;
 
   void BuildTree(BSPTreeNode* aRoot,
                  std::list<LayerPolygon>& aLayers);
 };
 
 } // namespace layers