Update manual to reflect major API changes.

1 files changed, 132 insertions, 242 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 5b02d60..5bfad7a 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1,9 +1,7 @@
 @menu
 * Kernel::                      The fundamental components.
-* Input::                       Keyboard, mouse, and controller input.
 * Math::                        Linear algebra and more.
 * Graphics::                    Eye candy.
-* Audio::                       Sound effects and music.
 * Scripting::                   Bringing the game world to life.
 @end menu
 
@@ -11,138 +9,126 @@
 @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.
+an event loop.  This loop, or ``kernel'', is responsible for ensuring
+that the game is updated at the desired interval, rendering the
+current state of the game world, and handling errors if they occur.
 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.
+Chickadee game loop 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 {Procedure} run-game [#:window-title "Chickadee!"] @
-       [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] @
+actually respond to input events, update game state, or render output,
+the programmer must provide an engine.  But don’t worry, you don’t
+have to start from scratch!  Chickadee comes with a simple engine that
+uses SDL to create a graphical window and handle input devices, and
+OpenGL to handle rendering.  This default engine is enough for most
+users to get started writing games quickly.  More advanced users may
+want to write a custom engine that uses a different I/O system.
+Perhaps you are writing a text adventure or roguelike that reads from
+and writes to a terminal instead of a graphical window.  The game loop
+kernel makes no assumptions.
+
+@deffn {Procedure} run-game [#:update] [#:render] [#:time] [#:error] @
        [#:update-hz 60]
 
-Start the event loop.  This procedure will not return until
+Start the game 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.
+The core game loop is generic and requires four additional procedures
+to operate:
 
-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
+@itemize
+@item
+@var{update}: Called @var{update-hz} times per second to advance the
+game simulation.  This procedure is called with a single argument: The
+amount of time that has passed since the last update, in milliseconds.
+@item
+@var{render}: Called each iteration of the loop to render the game to
+the desired output device.  This procedure is called with a single
+argument: 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.
+@item
+@var{time}: Called to get the current time in milliseconds.  This
+procedure is called with no arguments.
+@item
+@var{error}: Called when an error from the @var{update} or
+@var{render} procedures reaches the game loop.  This procedure is
+called with three arguments: The call stack, the error key, and the
+error arguments.  If no error handler is provided, the default
+behavior is to simply re-throw the error.
+@end itemize
 
-@deffn {Procedure} abort-game
-Stop the currently running Chickadee event loop.
 @end deffn
 
-@deffn {Procedure} time
-Return the current game time in milliseconds.
+@deffn {Procedure} abort-game
+Stop the currently running Chickadee game loop.
 @end deffn
 
-@defvr {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 {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
+Since most users will want to write 2D/3D games with hardware
+accelerated graphics rendering, controlled via keyboard, mouse, or
+game controller, Chickadee comes with an easy to use engine just for
+this purpose in the @code{(chickadee sdl)} module:
+@code{run-game/sdl}.
 
-@end defvr
+@deffn {Procedure} run-game/sdl [#:window-title "Chickadee!"] @
+       [#:window-width 640] [#:window-height 480] @
+       [#:window-fullscreen? @code{#f}] [#:update-hz 60] @
+       [#:load] [#:update] [#:draw] [#:quit] @
+       [#:key-press] [#:key-release] [#:text-input] @
+       [#:mouse-press] [#:mouse-release] [#:mouse-move] @
+       [#:controller-add] [#:controller-remove] [#:controller-press] @
+       [#:controller-release] [#:controller-move] [#:error]
 
-@defvr {Variable} before-draw-hook
-A hook that is run before a frame is rendered.  This hook is run with
-zero arguments.
+Run the Chickadee game loop using the SDL engine.
 
-@example
-(add-hook! before-draw-hook (lambda () (display "about to draw!\n")))
-@end example
-
-@end defvr
-
-@defvr {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 {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.
-
-@c TODO: Add example of linear interpolation
-
-@example
-(add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n")))
-@end example
+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 defvr
+@itemize
+@item
+@var{load}: Called with zero arguments when the game window has opened
+but before the game loop has started.  Can be used to perform
+initialization that requires an open window and OpenGL context such as
+loading textures.
 
-@defvr {Variable} quit-hook
-A hook that is run when the user clicks the close button on the game
-window.  This hook is run with zero arguments.
+@item
+@var{update}: Called @var{update-hz} times per second with one
+argument: The amount of time to advance the game simulation.
 
-@example
-(add-hook! quit-hook (lambda () (display "bye!\n")))
-@end example
+@item
+@var{draw}: Called each time a frame should be rendered with a single
+argument known as the @code{alpha} value.  See the documentation for
+@code{run-game} for an explanation of this value.
 
-@end defvr
+@item
+@var{quit}: Called with zero arguments when the user tries to close
+the game window.  The default behavior is to exit the game.
 
-@defvr {Variable} key-press-hook
-A hook that is run when a key is pressed on the keyboard.  This hook
-is run with four arguments:
+@item
+@var{key-press}: Called with four arguments when a key is pressed on
+the keyboard:
 
 @enumerate
 @item
 @var{key}: The symbolic name of the ``virtual'' key that was pressed.
 For example: @code{backspace}.  It's called a virtual key because the
 operating system may map a physical keyboard key to another key
-entirely, such as how the author binds the ``caps lock'' key to mean
-``control''.
+entirely, such as how the author likes to bind the ``caps lock'' key
+to mean ``control''.
 
 @item
 @var{scancode}: The symbolic name of the physical key that was
@@ -158,19 +144,9 @@ include @code{ctrl}, @code{alt}, and @code{shift}.
 
 @end enumerate
 
-@example
-(add-hook! key-press-hook
-           (lambda (key scancode modifiers repeat?)
-             (display "pressed key: ")
-             (display key)
-             (newline)))
-@end example
-
-@end defvr
-
-@defvr {Variable} key-release-hook
-A hook that is run when a key is released on the keyboard.  This hook
-is run with three arguments:
+@item
+@var{key-release}: Called with three arguments when a key is released
+on the keyboard:
 
 @enumerate
 @item
@@ -186,18 +162,13 @@ were being held down when the key was released.
 
 @end enumerate
 
-@end defvr
-
-@defvr {Variable} text-input-hook
-A hook that is run when printable text is typed on the keyboard.  This
-hook is run with a single argument, @var{text}, a string containing
-the text that was entered.
-@end defvr
-
-@defvr {Variable} mouse-press-hook
-A hook that is run when a mouse button is pressed.  This hook is run
-with four arguments:
+@item
+@var{text-input}: Called with a single argument, a string of text,
+when printable text is typed on the keyboard.
 
+@item
+@var{mouse-press}: Called with four arguments when a mouse button is
+pressed:
 @enumerate
 
 @item
@@ -215,11 +186,9 @@ as @code{left}, @code{middle}, or @code{right}.
 
 @end enumerate
 
-@end defvr
-
-@defvr {Variable} mouse-release-hook
-A hook that is run when a mouse button is released.  This hook is run
-with three arguments:
+@item
+@var{mouse-release}: Called with three arguments when a mouse button
+is released:
 
 @enumerate
 
@@ -234,11 +203,8 @@ with three arguments:
 
 @end enumerate
 
-@end defvr
-
-@defvr {Variable} mouse-move-hook
-A hook that is run when the mouse is moved.  This hook is run with
-five arguments:
+@item
+@var{mouse-move}: Called with five arguments when the mouse is moved:
 
 @enumerate
 
@@ -262,23 +228,17 @@ mouse was moved.
 
 @end enumerate
 
-@end defvr
-
-@defvr {Variable} controller-add-hook
-A hook that is run when a game controller is connected.  This hook is
-run with a single argument, @var{controller}, the controller that was
-connected.
-@end defvr
+@item
+@var{controller-add}: Called with a single argument, an SDL game
+controller object, when a game controller is connected.
 
-@defvr {Variable} controller-remove-hook
-A hook that is run when a game controller is disconnected.  This hook
-is run with a single argument, @var{controller}, the controller that
-was disconnected.
-@end defvr
+@item
+@var{controller-remove}: Called with a single argument, an SDL game
+controller object, when a game controller is disconnected.
 
-@defvr {Variable} controller-press-hook
-A hook that is run when a button on a game controller is pressed.
-This hook is run with two arguments:
+@item
+@var{controller-press}: Called with two arguments when a button on a
+game controller is pressed:
 
 @enumerate
 
@@ -325,12 +285,9 @@ Possible buttons are:
 
 @end enumerate
 
-@end defvr
-
-@defvr {Variable} controller-release-hook
-A hook that is run when a button on a game controller is released.
-
-This hook is run with two arguments:
+@item
+@var{controller-release}: Called with two arguments when a button on a
+game controller is released:
 
 @enumerate
 
@@ -342,11 +299,9 @@ This hook is run with two arguments:
 
 @end enumerate
 
-@end defvr
-
-@defvr {Variable} controller-move-hook
-A hook that is run when an analog stick or trigger on a game
-controller is moved.  This hook is run with three arguments
+@item
+@var{controller-move}: Called with three arguments when an analog
+stick or trigger on a game controller is moved:
 
 @enumerate
 
@@ -374,27 +329,26 @@ values are:
 
 @end enumerate
 
-@end defvr
+@item
+@var{error}: Called with three arguments when an error occurs:
 
-@node Input
-@section Input
+@enumerate
 
-Chickadee can handle input events from the keyboard, mouse, and game
-controllers.
+@item
+@var{stack}: The call stack at the point of error.
 
-@menu
-* Keyboard::                    Keyboard input.
-@end menu
+@item
+@var{key}: The exception key.
+
+@item
+@var{args}: The arguments thrown with the exception.
 
-@node Keyboard
-@subsection Keyboard
+@end enumerate
 
-@deffn {Procedure} key-pressed? @var{key}
-Return @code{#t} if @var{key} is currently being pressed.
-@end deffn
+The default behavior is to re-throw the error.
+
+@end itemize
 
-@deffn {Procedure} key-released? @var{key}
-Return @code{#t} if @var{key} is not currently being pressed.
 @end deffn
 
 @node Math
@@ -962,70 +916,6 @@ The default framebuffer.
 @node Viewports
 @subsection Viewports
 
-@node Audio
-@section Audio
-
-Chickadee has two data types for audio: samples and music.  Samples
-are for short sound effects like explosions.  Music is for, well,
-uh@dots{}, music.
-
-Supported file formats include WAV and OGG.
-
-@deffn {Procedure} load-sample @var{file}
-Load audio sample from @var{file}.
-@end deffn
-
-@deffn {Procedure} set-sample-volume! @var{volume}
-Set the volume that all samples are played at to @var{volume}, an
-integer value between 0 and 128.
-@end deffn
-
-@deffn {Procedure} play-sample @var{sample}
-Play @var{sample}.  Pretty straightforward!
-@end deffn
-
-@deffn {Procedure} load-music @var{file}
-Load music from @var{file}.
-@end deffn
-
-@deffn {Procedure} music-volume
-Return the volume level for music, an integer value between 0 and 128.
-@end deffn
-
-@deffn {Procedure} set-music-volume! @var{volume}
-Set the volume that music is played at to @var{volume}, an integer
-value between 0 and 128.
-@end deffn
-
-@deffn {Procedure} play-music @var{music} [@var{loop?}]
-Play @var{music}.  If @var{loop?}, play it over and over and over and
-over and@dots{}
-@end deffn
-
-@deffn {Procedure} pause-music
-Pause the current music track.
-@end deffn
-
-@deffn {Procedure} resume-music
-Resume the current music track.
-@end deffn
-
-@deffn {Procedure} rewind-music
-estart the current music track from the beginning.
-@end deffn
-
-@deffn {Procedure} stop-music
-Stop playing the current music track.
-@end deffn
-
-@deffn {Procedure} music-playing?
-Return @code{#t} if music is currently playing.
-@end deffn
-
-@deffn {Procedure} music-paused?
-Return @code{#t} if music is currently paused.
-@end deffn
-
 @node Scripting
 @section Scripting