diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.texi | 54 |
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 |