summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2021-04-07 17:04:39 -0400
committerDavid Thompson <dthompson2@worcester.edu>2021-04-07 17:07:35 -0400
commit37a466f7089b88f5554eafbe9b4bcee7290868c7 (patch)
tree67bb4450e20a55eff4c9d25ae4d966478c45b24a /doc/api.texi
parent42f3ce0e79f0fe488c6844a8819fab1659177a01 (diff)
graphics: Rewrite 9-patch implementation and move it to its own module.
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi54
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