summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2019-05-13 17:59:41 -0400
committerDavid Thompson <dthompson2@worcester.edu>2019-05-13 17:59:41 -0400
commit6a236d690b0cad9272ea89fc0c8d4fa283e75d11 (patch)
tree59ebc26c7016d316c1fb9254287c69f5d9fade06 /doc/api.texi
parent698ee19c1b8c6a6f0483ea5915170cb785e64d46 (diff)
doc: Improve texture documentation.
* chickadee/render/texture.scm (list->texture-atlas): Tweak docstring. * doc/api.texi (Textures): Document more procedures.
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi85
1 files changed, 83 insertions, 2 deletions
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}.