diff options
authorDavid Thompson <>2020-04-08 17:05:32 -0400
committerDavid Thompson <>2020-04-08 17:07:38 -0400
commit0ecfb6926894c99ae99b1fbd2e90aee685fc3d0a (patch)
parent521550dad780b1f5bb32a3739b7f1d92984c9ff6 (diff)
doc: Add "3D Models" section.
1 files changed, 63 insertions, 0 deletions
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
+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:
+(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
+OBJ models are rendered using a Phong lighting model, which is a
+@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