diff options
| -rw-r--r-- | Makefile.am | 1 | ||||
| -rw-r--r-- | doc/api.texi | 129 | ||||
| -rw-r--r-- | doc/chickadee.texi | 12 |
3 files changed, 141 insertions, 1 deletions
diff --git a/Makefile.am b/Makefile.am index 84d882a..b29464b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -62,4 +62,5 @@ info_TEXINFOS = doc/chickadee.texi chickadee_TEXINFOS = \ doc/fdl.texi \ + doc/api.texi \ doc/chickadee.texi 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 |