From 6a236d690b0cad9272ea89fc0c8d4fa283e75d11 Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Mon, 13 May 2019 17:59:41 -0400
Subject: doc: Improve texture documentation.

* chickadee/render/texture.scm (list->texture-atlas): Tweak docstring.
* doc/api.texi (Textures): Document more procedures.
---
 chickadee/render/texture.scm |  2 +-
 doc/api.texi                 | 85 ++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 84 insertions(+), 3 deletions(-)

diff --git a/chickadee/render/texture.scm b/chickadee/render/texture.scm
index f4d84d1..11785f0 100644
--- a/chickadee/render/texture.scm
+++ b/chickadee/render/texture.scm
@@ -279,7 +279,7 @@ magnification.  Valid values are 'nearest and 'linear.  By default,
 
 (define (list->texture-atlas texture rects)
   "Return a new atlas for TEXTURE containing RECTS, a list of texture
-coordinate rects denoting the various tiles within."
+coordinate rects denoting the various regions within."
   (let ((v (make-vector (length rects))))
     (let loop ((i 0)
                (rects rects))
diff --git a/doc/api.texi b/doc/api.texi
index 473e3b9..26525f6 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1323,6 +1323,87 @@ coordinates that are greater than @code{1.0}.  Possible values are
 
 @end deffn
 
+@deffn {Procedure} texture? @var{obj}
+Return @code{#t} if @var{obj} is a texture.
+@end deffn
+
+@deffn {Procedure} texture-region? @var{obj}
+Return @code{#t} if @var{obj} is a texture region.
+@end deffn
+
+@deffn {Procedure} texture-parent @var{texture}
+If @var{texture} is a texture region, return the full texture that it
+is based upon.  Otherwise, return @code{#f}.
+@end deffn
+
+@deffn {Procedure} texture-min-filter @var{texture}
+Return the minification filter for @var{texture}, either
+@code{nearest} or @code{linear}.
+@end deffn
+
+@deffn {Procedure} texture-mag-filter @var{texture}
+Return the magnification filter for @var{texture}, either
+@code{nearest} or @code{linear}.
+@end deffn
+
+@deffn {Procedure} texture-wrap-s @var{texture}
+Return the method used for wrapping texture coordinates along the X
+axis for @var{texture}.
+
+Possible wrapping methods:
+@itemize
+@item @code{repeat}
+@item @code{clamp}
+@item @code{clamp-to-border}
+@item @code{clamp-to-edge}
+@end itemize
+
+@end deffn
+
+@deffn {Procedure} texture-wrap-t @var{texture}
+Return the method used for wrapping texture coordinates along the Y
+axis for @var{texture}.
+@end deffn
+
+@deffn {Procedure} texture-width @var{texture}
+Return the width of @var{texture} in pixels.
+@end deffn
+
+@deffn {Procedure} texture-height @var{texture}
+Return the height of @var{texture} in pixels.
+@end deffn
+
+It is common practice to combine multiple bitmap images into a single
+texture, known as a ``tile atlas'' or ``tile set'', because it is more
+efficient to render many regions of a large texture than it is to
+render a bunch of small textures.  Chickadee provides a tile atlas
+data type for collecting texture regions into a single vector.
+
+@deffn {Procedure} split-texture @var{texture} @var{tile-width} @var{tile-height} @
+                                 [#:margin 0] [#:spacing 0]
+
+Return a new texture atlas that splits @var{texture} into a grid of
+@var{tile-width} by @var{tile-height} rectangles.  Optionally, each
+tile may have @var{spacing} pixels of horizontal and vertical space
+between surrounding tiles and the entire image may have @var{margin}
+pixels of empty space around its border.
+
+This type of texture atlas layout is very common for 2D tile maps.
+@xref{Tile Maps} for more information.
+@end deffn
+
+@deffn {Procedure} texture-atlas? @var{obj}
+Return @code{#t} if @var{obj} is a texture atlas.
+@end deffn
+
+@deffn {Procedure} texture-atlas-texture @var{atlas}
+Return the texture that all texture regions in @var{atlas} have been created from.
+@end deffn
+
+@deffn {Procedure} texture-atlas-ref @var{atlas} @var{index}
+Return the texture region in @var{atlas} at @var{index}.
+@end deffn
+
 @node Sprites
 @subsection Sprites
 
@@ -1389,8 +1470,8 @@ Return the texture for @var{batch}.
 Set texture for @var{batch} to @var{texture}.
 @end deffn
 
-@deffn {Procedure} sprite-batch-add! @var{batch} @var{position} @@
-                   [#:origin] [#:scale] [:rotation] @@
+@deffn {Procedure} sprite-batch-add! @var{batch} @var{position} @
+                   [#:origin] [#:scale] [:rotation] @
                    [#:tint @code{white}] [#:texture-region]
 
 Add sprite located at @var{position} to @var{batch}.
-- 
cgit v1.2.3