doc: Add the beginnings of an API reference.

2 files changed, 140 insertions, 1 deletions

diff --git a/doc/api.texi b/doc/api.texi
new file mode 100644
index 0000000..8633883
--- /dev/null
+++ b/doc/api.texi
@@ -0,0 +1,129 @@
+@menu
+* Kernel::                      The fundamental components.
+* Input::                       Keyboard, mouse, and controller input.
+* Math::                        Linear algebra and more.
+* Graphics::                    Eye candy.
+@end menu
+
+@node Kernel
+@section Kernel
+
+At the very core of Chickadee, in the @code{(chickadee)} module, lies
+an event loop.  This loop, or ``kernel'', is responsible for creating
+and managing the game window, dispatching input events, ensuring that
+the game is updated at the desired interval, and rendering graphics.
+The kernel implements what is known as a ``fixed timestep'' game loop,
+meaning that the game simulation will be advanced by a fixed interval
+of time and will never vary from frame to frame, unlike some other
+styles of game loops.  The appropriately named @code{run-game} and
+@code{abort-game} procedures are the entry and exit points to the
+Chickadee kernel.
+
+On its own, the kernel does not do very much at all.  In order to
+actually respond to input events, update game state, or draw something
+to the game window, a hacker with a penchant for game development must
+latch onto extension points built into the kernel, called ``hooks'',
+and specify what action ought to be taken for any given event.  For
+example, the @code{key-press-hook} can be used to respond to the
+@code{a} key being pressed by swinging the player's mighty sword.
+There are many hooks available, so read on to learn about all of them.
+For information about using Guile's hook API, see @xref{Hooks,,,
+guile, GNU Guile Reference Manual}.
+
+@deffn {Scheme Procedure} run-game [#:window-title "Chickadee!"]
+       [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f]
+       [#:update-hz 60]
+Start the event loop.  This procedure will not return until
+@code{abort-game} is called.
+
+The @code{update-hook} will be run @var{update-hz} times per second.
+
+A new graphical window will be opened with @var{window-width} x
+@var{window-height} as its dimensions, @var{window-title} as its
+title, and in fullscreen mode if @var{window-fullscreen?} is
+@code{#t}.
+@end deffn
+
+@deffn {Scheme Procedure} abort-game
+Stop the currently running Chickadee event loop.
+@end deffn
+
+@deffn {Scheme Procedure} time
+Return the current game time in milliseconds.
+@end deffn
+
+@defvr {Scheme Variable} load-hook
+A hook that is run once when the event loop boots, before any other
+hook is run.  This hook is run with zero arguments.
+
+@example
+(add-hook! load-hook (lambda () (display "hello!\n")))
+@end example
+
+@end defvr
+
+@defvr {Scheme Variable} update-hook
+A hook that is run every time the game simulation should be advanced.
+This hook is run with a single argument @var{dt}, the fixed timestep
+that was configured when the event loop was started, in milliseconds.
+
+@example
+(add-hook! update-hook (lambda (dt) (display "tick!\n")))
+@end example
+
+@end defvr
+
+@defvr {Scheme Variable} before-draw-hook
+A hook that is run before a frame is rendered.  This hook is run with
+zero arguments.
+
+@example
+(add-hook! before-draw-hook (lambda () (display "about to draw!\n")))
+@end example
+
+@end defvr
+
+@defvr {Scheme Variable} after-draw-hook
+A hook that is run after a frame is rendered.  This hook is run with
+zero arguments.
+
+@example
+(add-hook! after-draw-hook (lambda () (display "done drawing!\n")))
+@end example
+
+Combined with @code{before-draw-hook}, one can perform a frames per
+second calculation to monitor game performance and stability.
+
+@end defvr
+
+@defvr {Scheme Variable} draw-hook
+A hook that is run each time a frame should be rendered.  This hook is
+run with a single argument @var{alpha}, a value in the range [0, 1]
+which represents how much time has past since the last game state
+update relative to the upcoming game state update, as a percentage.
+Because the game state is updated independent of rendering, it is
+often the case that rendering is occuring between two updates.  If the
+game is rendered as it was during the last update, a strange
+side-effect will occur that makes animation appear rough or
+``choppy''.  To counter this, the @var{alpha} value can be used to
+perfrom a linear interpolation of a moving object between its current
+position and its previous position.  This odd trick has the pleasing
+result of making the animation look smooth again, but requires keeping
+track of previous state.
+
+(TODO: Add example of linear interpolation)
+
+@example
+(add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n")))
+@end example
+
+@end defvr
+
+@node Input
+@section Input
+
+@node Math
+@section Math
+
+@node Graphics
+@section Graphics
diff --git a/doc/chickadee.texi b/doc/chickadee.texi
index 7e9362f..c662506 100644
--- a/doc/chickadee.texi
+++ b/doc/chickadee.texi
@@ -46,6 +46,7 @@ The document was typeset with
 @c Generate the nodes for this menu with `C-c C-u C-m'.
 @menu
 * Installation::                Installing Chickadee.
+* API Reference::               Chickadee API reference.
 
 * Copying This Manual::         The GNU Free Documentation License and you!
 * Index::
@@ -75,11 +76,20 @@ and is not covered here.  Please see the files @file{README.org} and
 Chickadee depends on the following packages:
 
 @itemize
-@item @url{https://gnu.org/software/guile, GNU Guile}, version 2.0.11 or later;
+@item @url{https://gnu.org/software/guile, GNU Guile}, version 2.1.0 or later;
 @item @url{https://gnu.org/software/guile-opengl, GNU guile-opengl}, version 0.1 or later.
 @item @url{https://dthompson.us/pages/software/guile-sdl2.html, guile-sdl2}, version 0.2.0 or later;
 @end itemize
 
+Additionally, Chickadee depends on being able to create an OpenGL 3.3
+context at runtime, which means that some older computers may not be
+able to run games written with Chickadee.
+
+@node API Reference
+@chapter API Reference
+
+@include api.texi
+
 @node Copying This Manual
 @appendix Copying This Manual