add stencil-whiteout-outline function (issue 236480043 by address@hidden)

[paulwmorris]

Reviewers: ,

Message:
Please review, thanks.

See discussion here for background and usage demo:
http://lists.gnu.org/archive/html/lilypond-user/2015-05/msg00522.html

I have not yet done a regtest, but will add one if this is reviewed
favorably for inclusion in LilyPond.

Description:
add stencil-whiteout-outline function


clean up code formatting in stencil-whiteout

Please review this at https://codereview.appspot.com/236480043/

Affected files (+55, -5 lines):
  M scm/stencil.scm


Index: scm/stencil.scm
diff --git a/scm/stencil.scm b/scm/stencil.scm
index  
03259cc3f53e90a9e1057a1e84a128964d003730..948ee221bc55b60d14413620a566f6c1dc3c427e  
100644
--- a/scm/stencil.scm
+++ b/scm/stencil.scm
@@ -688,15 +688,65 @@ box, remains the same."
 (define-public (stencil-whiteout stencil)
   (let*
       ((x-ext (ly:stencil-extent stencil X))
-       (y-ext (ly:stencil-extent stencil Y))
-
-       )
+       (y-ext (ly:stencil-extent stencil Y)))

     (ly:stencil-add
      (stencil-with-color (ly:round-filled-box x-ext y-ext 0.0)
                          white)
-     stencil)
-    ))
+     stencil)))
+
+(define*-public (stencil-whiteout-outline
+                 stil #:optional (thickness 0.3) (color white)
+                 (angle-increments 12) (radial-increments 3))
+  "This function works by creating a series of white or @var{color}
+stencils radially thickness from the original stencil with angles from
+0 to 2*pi, at an increment of @code{angle-inc}, and with radii
+from @code{radial-inc} to @var{thickness}.  @var{thickness} is how big
+the white outline is in staff-spaces.  @var{radial-increments} is how
+many copies of the white stencil we make on our way out to thickness.
address@hidden is how many copies of the white stencil
+we make between 0 and 2*pi."
+  (if (or (not (positive? angle-increments))
+          (not (positive? radial-increments)))
+      (begin
+       (ly:warning "Both angle-increments and radial-increments must be  
positive numbers.")
+       stil)
+      (let* ((2pi 6.283185307)
+             (angle-inc (/ 2pi angle-increments))
+             (radial-inc (/ thickness radial-increments)))
+
+        (define (circle-plot ang dec radius original-stil new-stil)
+          ;; ang (angle) and dec (decrement) are in radians, not degrees
+          (if (<= ang 0)
+              new-stil
+              (circle-plot (- ang dec) dec radius original-stil
+                (ly:stencil-add
+                 new-stil
+                 (ly:stencil-translate original-stil
+                   (cons
+                    (* radius (cos ang))
+                    (* radius (sin ang))))))))
+
+        (define (radial-plot radius original-stil new-stil)
+          (if (<= radius 0)
+              new-stil
+              (ly:stencil-add new-stil
+                (radial-plot
+                 (- radius radial-inc)
+                 original-stil
+                 (circle-plot 2pi angle-inc
+                   radius original-stil empty-stencil)))))
+
+        (let ((whiteout-stil
+               (ly:stencil-add
+                (stencil-with-color
+                 (radial-plot thickness stil empty-stencil)
+                 color)
+                stil)))
+          (ly:make-stencil
+           (ly:stencil-expr whiteout-stil)
+           (ly:stencil-extent stil X)
+           (ly:stencil-extent stil Y))))))

 (define-public (arrow-stencil-maker start? end?)
   "Return a function drawing a line from current point to  
@code{destination},