From 0ecfb6926894c99ae99b1fbd2e90aee685fc3d0a Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Wed, 8 Apr 2020 17:05:32 -0400
Subject: doc: Add "3D Models" section.

---
 doc/api.texi | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

(limited to 'doc')

diff --git a/doc/api.texi b/doc/api.texi
index dd22341..99e225d 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1511,6 +1511,7 @@ blocks to implement additional rendering techniques.
 * Lines and Shapes::            Draw line segments and polygons.
 * Fonts::                       Drawing text.
 * Particles::                   Pretty little flying pieces!
+* 3D Models::                   Spinning teapots everywhere.
 * Blending::                    Control how pixels are combined.
 * Framebuffers::                Render to texture.
 * Viewports::                   Restrict rendering to a particular area.
@@ -2477,6 +2478,68 @@ Add @var{emitter} to @var{particles}.
 Remove @var{emitter} to @var{particles}
 @end deffn
 
+@node 3D Models
+@subsection 3D Models
+
+@emph{Disclaimer: Chickadee is alpha software, but 3D model support is
+even more alpha than that.  There are many missing features in both
+the model loading and rendering components, so set your expectations
+accordingly!}
+
+Chickadee can load and render 3D models in the classic OBJ and more
+modern glTF 2.0 formats.
+
+Here's some basic boilerplate to render a 3D model:
+
+@example
+(use-modules (chickadee)
+             (chickadee math)
+             (chickadee math matrix)
+             (chickadee render model))
+
+(define model #f)
+(define projection-matrix
+  (perspective-projection (/ pi 3.0) (/ 4.0 3.0) 0.1 500.0))
+;; Adjust these 2 matrices so that you can actually see the model.
+(define view-matrix (make-identity-matrix4))
+(define model-matrix (make-identity-matrix4))
+
+(define (load)
+  (set! model (load-obj "model.obj"))
+
+(define (draw alpha)
+  (with-projection projection-matrix
+    (with-depth-test #t
+      (draw-model model model-matrix view-matrix))))
+
+(run-game #:load load #:draw draw)
+@end example
+
+@deffn {Procedure} load-obj file-name
+Load the OBJ formatted model in @var{file-name} and return a 3D model
+object.
+
+OBJ models are rendered using a Phong lighting model, which is a
+work-in-progress.
+@end deffn
+
+@deffn {Procedure} load-gltf file-name
+Load the glTF 2.0 formatted model in @var{file-name} and return a 3D
+model object.
+
+glTF models are rendered using a physically based lighting model,
+which is currently a stub to be implemented later.
+@end deffn
+
+@deffn {Procedure} model? obj
+Return @code{#t} if @var{obj} is a 3D model.
+@end deffn
+
+@deffn {Procedure} draw-model model model-matrix view-matrix
+Render @var{model} with the transformation matrices @var{model-matrix}
+and @var{view-matrix} applied.
+@end deffn
+
 @node Blending
 @subsection Blending
 
-- 
cgit v1.2.3