graphics: Rewrite 9-patch implementation and move it to its own module.

1 files changed, 29 insertions, 25 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 5fa18b3..e99c89c 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1586,6 +1586,7 @@ blocks to implement additional rendering techniques.
 * Colors::                      Such pretty colors...
 * Textures::                    2D images.
 * Sprites::                     Draw 2D images.
+* 9-Patches::                   Scalable bitmap boxes.
 * Fonts::                       Drawing text.
 * Vector Paths::                Draw filled and stroked paths.
 * Particles::                   Pretty little flying pieces!
@@ -2041,48 +2042,51 @@ Render @var{batch} using @var{blend-mode}.  Alpha blending is used by
 default.
 @end deffn
 
-With a basic sprite abstraction in place, it's possible to build other
-abstractions on top of it.  One such example is the ``nine patch''.  A
-nine patch is a sprite that can be rendered at various sizes without
-becoming distorted.  This is achieved by dividing up the sprite into
-nine regions:
+@node 9-Patches
+@subsection 9-Patches
+
+A 9-patch is a method of rendering a texture so that it can be
+stretched to cover an area of any size without becoming distorted.
+This is achieved by dividing up the sprite into nine regions:
 
 @itemize
 @item
-the center, which can be scaled horizontally and vertically
+the center, which can be stretched or tiled horizontally and vertically
 @item
-the four corners, which can never be scaled
+the four corners, which are never stretched or tiled
 @item
-the left and right sides, which can be scaled vertically
+the left and right sides, which can be stretched or tiled vertically
 @item
-the top and bottom sides, which can be scaled horizontally
+the top and bottom sides, which can be stretched or tiled horizontally
 @end itemize
 
-The one caveat is that the bitmap regions must be designed in such a
-way so that they are not distorted when stretched along the affected
-axes.  For example, that means that the top and bottom sides could
-have varying colored pixels vertically, but not horizontally.
-
 The most common application of this technique is for graphical user
-interface widgets like buttons and dialog boxes.  By using a nine
-patch, they can be rendered at any size without unappealing scaling
-artifacts.
+interface widgets like buttons and dialog boxes which are often
+dynamically resizable.  By using a 9-patch, they can be rendered at
+any size without scaling artifacts.
 
 @deffn {Procedure} draw-nine-patch texture rect @
        [#:margin 0] [#:top-margin margin] [#:bottom-margin margin] @
-       [#:left-margin margin] [#:right-margin margin] @
+       [#:left-margin margin] [#:right-margin margin] [#:mode stretch] @
        [#:origin] [#:scale] [#:rotation] [#:blend-mode] @
        [#:tint white]
 
-Draw a nine patch sprite.  A nine patch sprite renders @var{texture}
-as a @var{width} x @var{height} rectangle whose stretchable areas are
-defined by the given margin measurements @var{top-margin},
-@var{bottom-margin}, @var{left-margin}, and @var{right-margin}. The
-@var{margin} argument may be used to configure all four margins at
-once.
+Draw a 9-patch over the area @var{rect} using @var{texture} whose
+stretchable/tileable patches are defined by the given margin
+measurements.  The corners are never stretched/tiled, the left and
+right edges will be stretched/tiled vertically, the top and bottom
+edges may be stretched/tiled horizontally, and the center may be
+stretched/tiled in both directions.
+
+@var{mode} may be either @code{stretch} (the default) or @code{tile}.
+
+@var{margin} specifies the margin size for all sides of the 9-patch.
+To make margins of differing sizes, the @var{top-margin},
+@var{bottom-margin}, @var{left-margin}, and @var{right-margin}
+arguments may be used.
 
 Refer to @code{draw-sprite} (@pxref{Sprites}) for information about
-the other arguments.
+the other arguments as they are the same.
 @end deffn
 
 @node Fonts