summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2021-09-23 09:00:38 -0400
committerDavid Thompson <dthompson2@worcester.edu>2021-09-23 09:00:38 -0400
commit5e1769752380fab3a8b2655ac0642b31c281ac08 (patch)
tree8a343395db0d3d6a9991a148c9a38dceeafed728 /doc/api.texi
parent40a2a9e39fc26f851891502bcb6c85abd7627439 (diff)
doc: Document cube maps and skyboxes.
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi51
1 files 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