Add flip-stencil function

Issue 4370
Patch 2/2

3 files changed, 53 insertions, 2 deletions

diff --git a/input/regression/flip-stencil.ly b/input/regression/flip-stencil.ly
new file mode 100644
index 0000000000..3c9b4d24aa
--- /dev/null
+++ b/input/regression/flip-stencil.ly
@@ -0,0 +1,32 @@
+\version "2.19.19"
+
+\header {
+  texidoc = "Stencils can be flipped horizontally or vertically within
+their bounding box using @code{flip-stencil}."
+}
+
+square =
+#(make-path-stencil
+  '(moveto 0 0 lineto 0 2 lineto 2 2 lineto 2 0 closepath)
+  0.1 1 1 #f)
+
+triangle =
+#(stencil-with-color
+  (make-path-stencil
+   '(moveto 0 0 lineto 2 2 lineto 2 0 closepath)
+   0.3 1 1 #f)
+  blue)
+
+{
+  g'1^\markup \stencil
+  #(ly:stencil-add square triangle)
+  _\markup \teeny "baseline"
+
+  g'1^\markup \stencil
+  #(ly:stencil-add square (flip-stencil X triangle))
+  _\markup \teeny "flip X"
+
+  g'1^\markup \stencil
+  #(ly:stencil-add square (flip-stencil Y triangle))
+  _\markup \teeny "flip Y"
+}
diff --git a/lily/stencil-scheme.cc b/lily/stencil-scheme.cc
index f337beb3f4..ab4ebd3a7c 100644
--- a/lily/stencil-scheme.cc
+++ b/lily/stencil-scheme.cc
@@ -457,8 +457,10 @@ LY_DEFINE (ly_all_stencil_expressions, "ly:all-stencil-expressions",
 
 LY_DEFINE (ly_stencil_scale, "ly:stencil-scale",
            3, 0, 0, (SCM stil, SCM x, SCM y),
-           "Scale @var{stil} using the horizontal and vertical scaling"
-           " factors @var{x} and @var{y}.")
+           "Scale stencil @var{stil} using the horizontal and vertical"
+           " scaling factors @var{x} and @var{y}.  Negative values will"
+           " flip or mirror @var{stil} without changing its origin;"
+           " this may result in collisions unless it is repositioned.")
 {
   Stencil *s = Stencil::unsmob (stil);
   LY_ASSERT_SMOB (Stencil, stil, 1);
diff --git a/scm/stencil.scm b/scm/stencil.scm
index c4858d39a4..03259cc3f5 100644
--- a/scm/stencil.scm
+++ b/scm/stencil.scm
@@ -662,6 +662,23 @@ producing a new stencil."
     (set! stencil (ly:stencil-add outer inner))
     stencil))
 
+(define-public (flip-stencil axis stil)
+  "Flip stencil @var{stil} in the direction of @var{axis}.
+Value @code{X} (or @code{0}) for @var{axis} flips it horizontally.
+Value @code{Y} (or @code{1}) flips it vertically.  @var{stil} is
+flipped in place; its position, the coordinates of its bounding
+box, remains the same."
+  (let* (
+          ;; scale stencil using -1 to flip it and
+          ;; then restore it to its original position
+          (xy (if (= axis X) '(-1 . 1) '(1 . -1)))
+          (flipped-stil (ly:stencil-scale stil (car xy) (cdr xy)))
+          (flipped-ext (ly:stencil-extent flipped-stil axis))
+          (original-ext (ly:stencil-extent stil axis))
+          (offset (- (car original-ext) (car flipped-ext)))
+          (replaced-stil (ly:stencil-translate-axis flipped-stil offset axis)))
+    replaced-stil))
+
 (define-public (stencil-with-color stencil color)
   (ly:make-stencil
    (list 'color color (ly:stencil-expr stencil))