Add bunch more comments

1 files changed, 15 insertions, 5 deletions

diff --git a/src/cairo-spline-offset.c b/src/cairo-spline-offset.c
index 5969873a..4fe0a3af 100644
--- a/src/cairo-spline-offset.c
+++ b/src/cairo-spline-offset.c
@@ -684,10 +684,14 @@ approximate_offset_curve_with_shin (knots_t self, double dist, void (*curve_fn)(
     curve_fn(closure, convolve_with_circle(remaining, dist));
 }
 
-/* this code is inspired by the libart mitreing code */
+/* Computes the offset polygon for the control polygon of spline. We can
+ * use this is an approximation of the offset spline. This approximation is
+ * give by Tiller W, Hanson E G. in "Offsets of two-dimensional profile" */
 static knots_t
-knot_offset(knots_t self, double width, cairo_bool_t *is_parallel)
+knot_offset (knots_t self, double width, cairo_bool_t *is_parallel)
 {
+    /* this code is inspired by the libart mitreing code */
+
     /* difference vectors between each point in the knot */
     double dx0, dy0, dx1, dy1, dx2, dy2;
     /* difference vector lengths */
@@ -724,6 +728,7 @@ knot_offset(knots_t self, double width, cairo_bool_t *is_parallel)
     dy2 = self.d.y - self.c.y;
     ld2 = sqrt(dx2*dx2 + dy2*dy2);
 
+    /* compute normalized normals */
     scale = 1. / ld0;
     dlx0 = -dy0 * scale;
     dly0 = dx0 * scale;
@@ -736,8 +741,10 @@ knot_offset(knots_t self, double width, cairo_bool_t *is_parallel)
     dlx2 = -dy2 * scale;
     dly2 = dx2 * scale;
 
-
-    /* deal with any degeneracies in the spline */
+    /* deal with any degeneracies in the spline by treating
+     * degenerate segments as having the same normal
+     * as their neighbour. If all of the segments are degenerate
+     * than we will fail the is_parallel test below */
     last_x = 0;
     last_y = 0;
 
@@ -789,7 +796,9 @@ knot_offset(knots_t self, double width, cairo_bool_t *is_parallel)
     dmr2_1 = (dm1x * dm1x + dm1y * dm1y);
     dmr2_2 = (dm2x * dm2x + dm2y * dm2y);
 
-    if (!dmr2_1 || !dmr2_2)
+    /* the choice of this EPSILON is arbitrary and could use further study */
+#define PARALLEL_EPSILON 1e-6
+    if (fabs(dmr2_1) < PARALLEL_EPSILON || fabs(dmr2_2) < PARALLEL_EPSILON)
 	*is_parallel = TRUE;
     else
 	*is_parallel = FALSE;
@@ -802,6 +811,7 @@ knot_offset(knots_t self, double width, cairo_bool_t *is_parallel)
     dm2x *= scale;
     dm2y *= scale;
 
+    /* write out the result */
     result.a.x = self.a.x + dlx0 * width;
     result.a.y = self.a.y + dly0 * width;