doc: Add the beginnings of an API reference.

1 files changed, 129 insertions, 0 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