From 5e1769752380fab3a8b2655ac0642b31c281ac08 Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Thu, 23 Sep 2021 09:00:38 -0400
Subject: doc: Document cube maps and skyboxes.

---
 doc/api.texi | 51 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/doc/api.texi b/doc/api.texi
index ca44492..14b1ea9 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1614,7 +1614,8 @@ blocks to implement additional rendering techniques.
 * Particles::                   Pretty little flying pieces!
 * Tile Maps::                   Draw 2D tile maps.
 * Models::                      Load 3D models from disk.
-* Lights::                      Dynamic lighting.
+* Lights::                      Dynamic 3D lighting.
+* Skyboxes::                    Backgrounds for 3D environments.
 * Meshes::                      3D meshes and materials.
 * Blending::                    Control how pixels are combined.
 * Framebuffers::                Render to texture.
@@ -1859,7 +1860,9 @@ Tango color palette}.
 @node Textures
 @subsection Textures
 
-Textures are essentially images: a 2D grid of color values.  The
+Textures are essentially images: a 2D grid of color values.  However,
+this is a great simplification.  Textures can be used to store any
+kind of data that can be encoded into color channels.  The
 @code{(chickadee graphics texture)} module provides an interface for
 working with texture objects.
 
@@ -1933,6 +1936,8 @@ Return the width of @var{texture} in pixels.
 Return the height of @var{texture} in pixels.
 @end deffn
 
+@subsubection Tile Atlases
+
 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
@@ -1976,6 +1981,24 @@ Return the texture that all texture regions in @var{atlas} have been created fro
 Return the texture region in @var{atlas} at @var{index}.
 @end deffn
 
+@subsubsection Cube Maps
+
+A cube map is a special type of texture composed of 6 images that can
+be thought of as forming the 6 faces of a cube.  @xref(Skyboxes) for a
+practical use of cube maps.
+
+@deffn {Procedure} load-cube-map #:right #:left #:top #:bottom #:front #:back @
+       [#:min-filter linear-mipmap-linear] [#:mag-filter linear]
+
+Return a new cube map that uses the image data in the files
+@var{right}, @var{left}, @var{top}, @var{bottom}, @var{front}, and
+@var{back} for the 6 faces of the cube.
+@end deffn
+
+@deffn {Procedure} cube-map? obj
+Return @code{#t} if @var{obj} is a cube map.
+@end deffn
+
 @node Sprites
 @subsection Sprites
 
@@ -3043,6 +3066,30 @@ Set the direction of @var{light} to @var{direction}.
 Set the cut off angle of @var{light} to @var{cut-off}.
 @end deffn
 
+@node Skyboxes
+@subsection Skyboxes
+
+Skyboxes are used as backgrounds in 3D environments, as well as a
+source of ambient lighting data when rendering 3D objects.  The
+@code{(chickadee graphics skybox)} module provides an API for making
+skyboxes.
+
+@deffn {Procedure} make-skybox cube-map
+Return a new skybox that uses @var{cube-map} for a texture.
+@end deffn
+
+@deffn {Procedure} skybox? obj
+Return @code{#t} if @var{obj} is a skybox.
+@end deffn
+
+@deffn {Procedure} skybox-cube-map sky-box
+Return the cube map of @var{skybox}.
+@end deffn
+
+@deffn {Procedure} draw-skybox skybox view
+Render @var{skybox} to the screen using the view matrix @var{view}.
+@end deffn
+
 @node Meshes
 @subsection Meshes
 
-- 
cgit v1.2.3