From f16fed3d50fd3d56deb46a3d4641a81460e389de Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Wed, 12 Dec 2018 09:20:10 -0500
Subject: Update Chickadee manual and home page for 0.3.0.

Better late than never!
---
 manuals/chickadee/Kernel.html | 300 ++++++++++++++++--------------------------
 1 file changed, 116 insertions(+), 184 deletions(-)

(limited to 'manuals/chickadee/Kernel.html')
diff --git a/manuals/chickadee/Kernel.html b/manuals/chickadee/Kernel.html
index 589c71e..c298723 100644
--- a/manuals/chickadee/Kernel.html
+++ b/manuals/chickadee/Kernel.html
@@ -16,21 +16,21 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html.
 The document was typeset with
 http://www.texinfo.org/ (GNU Texinfo).
  -->
-<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
+<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
 <head>
-<title>The Chickadee Game Toolkit: Kernel</title>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Kernel (The Chickadee Game Toolkit)</title>
 
-<meta name="description" content="The Chickadee Game Toolkit: Kernel">
-<meta name="keywords" content="The Chickadee Game Toolkit: Kernel">
+<meta name="description" content="Kernel (The Chickadee Game Toolkit)">
+<meta name="keywords" content="Kernel (The Chickadee Game Toolkit)">
 <meta name="resource-type" content="document">
 <meta name="distribution" content="global">
 <meta name="Generator" content="makeinfo">
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link href="index.html#Top" rel="start" title="Top">
 <link href="Index.html#Index" rel="index" title="Index">
 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
 <link href="API-Reference.html#API-Reference" rel="up" title="API Reference">
-<link href="Input.html#Input" rel="next" title="Input">
+<link href="Math.html#Math" rel="next" title="Math">
 <link href="API-Reference.html#API-Reference" rel="prev" title="API Reference">
 <style type="text/css">
 <!--
@@ -90,150 +90,118 @@ ul.no-bullet {list-style: none}
 <a name="Kernel"></a>
 <div class="header">
 <p>
-Next: <a href="Input.html#Input" accesskey="n" rel="next">Input</a>, Up: <a href="API-Reference.html#API-Reference" accesskey="u" rel="up">API Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
+Next: <a href="Math.html#Math" accesskey="n" rel="next">Math</a>, Up: <a href="API-Reference.html#API-Reference" accesskey="u" rel="up">API Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
 </div>
 <hr>
 <a name="Kernel-1"></a>
 <h3 class="section">2.1 Kernel</h3>
 
 <p>At the very core of Chickadee, in the <code>(chickadee)</code> module, lies
-an event loop.  This loop, or &ldquo;kernel&rdquo;, 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 &ldquo;kernel&rdquo;, 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 &ldquo;fixed timestep&rdquo; 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</code> and
 <code>abort-game</code> procedures are the entry and exit points to the
-Chickadee kernel.
+Chickadee game loop kernel.
 </p>
 <p>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 &ldquo;hooks&rdquo;,
-and specify what action ought to be taken for any given event.  For
-example, the <code>key-press-hook</code> can be used to respond to the
-<code>a</code> key being pressed by swinging the player&rsquo;s mighty sword.
-There are many hooks available, so read on to learn about all of them.
-For information about using Guile&rsquo;s hook API, see See <a href="http://www.gnu.org/software/guile/manual/html_node/Hooks.html#Hooks">Hooks</a> in <cite>GNU Guile Reference Manual</cite>.
+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.
 </p>
 <dl>
-<dt><a name="index-run_002dgame"></a>Scheme Procedure: <strong>run-game</strong> <em>[#:window-title &quot;Chickadee!&quot;]        [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f]        [#:update-hz 60]</em></dt>
+<dt><a name="index-run_002dgame"></a>Procedure: <strong>run-game</strong> <em>[#:update] [#:render] [#:time] [#:error]        [#:update-hz 60]</em></dt>
 <dd>
-<p>Start the event loop.  This procedure will not return until
+<p>Start the game loop.  This procedure will not return until
 <code>abort-game</code> is called.
 </p>
-<p>The <code>update-hook</code> will be run <var>update-hz</var> times per second.
+<p>The core game loop is generic and requires four additional procedures
+to operate:
 </p>
-<p>A new graphical window will be opened with <var>window-width</var> x
-<var>window-height</var> as its dimensions, <var>window-title</var> as its
-title, and in fullscreen mode if <var>window-fullscreen?</var> is
-<code>#t</code>.
-</p></dd></dl>
-
-<dl>
-<dt><a name="index-abort_002dgame"></a>Scheme Procedure: <strong>abort-game</strong></dt>
-<dd><p>Stop the currently running Chickadee event loop.
-</p></dd></dl>
-
-<dl>
-<dt><a name="index-time"></a>Scheme Procedure: <strong>time</strong></dt>
-<dd><p>Return the current game time in milliseconds.
-</p></dd></dl>
-
-<dl>
-<dt><a name="index-load_002dhook"></a>Scheme Variable: <strong>load-hook</strong></dt>
-<dd><p>A hook that is run once when the event loop boots, before any other
-hook is run.  This hook is run with zero arguments.
-</p>
-<div class="example">
-<pre class="example">(add-hook! load-hook (lambda () (display &quot;hello!\n&quot;)))
-</pre></div>
+<ul>
+<li> <var>update</var>: Called <var>update-hz</var> 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.
+</li><li> <var>render</var>: 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 &ldquo;choppy&rdquo;.  To counter this, the
+<var>alpha</var> 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.
+</li><li> <var>time</var>: Called to get the current time in milliseconds.  This
+procedure is called with no arguments.
+</li><li> <var>error</var>: Called when an error from the <var>update</var> or
+<var>render</var> 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.
+</li></ul>
 
 </dd></dl>
 
 <dl>
-<dt><a name="index-update_002dhook"></a>Scheme Variable: <strong>update-hook</strong></dt>
-<dd><p>A hook that is run every time the game simulation should be advanced.
-This hook is run with a single argument <var>dt</var>, the fixed timestep
-that was configured when the event loop was started, in milliseconds.
-</p>
-<div class="example">
-<pre class="example">(add-hook! update-hook (lambda (dt) (display &quot;tick!\n&quot;)))
-</pre></div>
-
-</dd></dl>
+<dt><a name="index-abort_002dgame"></a>Procedure: <strong>abort-game</strong></dt>
+<dd><p>Stop the currently running Chickadee game loop.
+</p></dd></dl>
 
-<dl>
-<dt><a name="index-before_002ddraw_002dhook"></a>Scheme Variable: <strong>before-draw-hook</strong></dt>
-<dd><p>A hook that is run before a frame is rendered.  This hook is run with
-zero arguments.
+<p>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)</code> module:
+<code>run-game/sdl</code>.
 </p>
-<div class="example">
-<pre class="example">(add-hook! before-draw-hook (lambda () (display &quot;about to draw!\n&quot;)))
-</pre></div>
-
-</dd></dl>
-
 <dl>
-<dt><a name="index-after_002ddraw_002dhook"></a>Scheme Variable: <strong>after-draw-hook</strong></dt>
-<dd><p>A hook that is run after a frame is rendered.  This hook is run with
-zero arguments.
-</p>
-<div class="example">
-<pre class="example">(add-hook! after-draw-hook (lambda () (display &quot;done drawing!\n&quot;)))
-</pre></div>
-
-<p>Combined with <code>before-draw-hook</code>, one can perform a frames per
-second calculation to monitor game performance and stability.
+<dt><a name="index-run_002dgame_002fsdl"></a>Procedure: <strong>run-game/sdl</strong> <em>[#:window-title &quot;Chickadee!&quot;]        [#:window-width 640] [#:window-height 480]        [#:window-fullscreen? <code>#f</code>] [#: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]</em></dt>
+<dd>
+<p>Run the Chickadee game loop using the SDL engine.
 </p>
-</dd></dl>
-
-<dl>
-<dt><a name="index-draw_002dhook"></a>Scheme Variable: <strong>draw-hook</strong></dt>
-<dd><p>A hook that is run each time a frame should be rendered.  This hook is
-run with a single argument <var>alpha</var>, 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
-&ldquo;choppy&rdquo;.  To counter this, the <var>alpha</var> 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.
+<p>A new graphical window will be opened with <var>window-width</var> x
+<var>window-height</var> as its dimensions, <var>window-title</var> as its
+title, and in fullscreen mode if <var>window-fullscreen?</var> is
+<code>#t</code>.
 </p>
+<ul>
+<li> <var>load</var>: 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.
 
-<div class="example">
-<pre class="example">(add-hook! draw-hook (lambda (alpha) (display &quot;&lt;(._.&lt;) \n&quot;)))
-</pre></div>
+</li><li> <var>update</var>: Called <var>update-hz</var> times per second with one
+argument: The amount of time to advance the game simulation.
 
-</dd></dl>
+</li><li> <var>draw</var>: Called each time a frame should be rendered with a single
+argument known as the <code>alpha</code> value.  See the documentation for
+<code>run-game</code> for an explanation of this value.
 
-<dl>
-<dt><a name="index-quit_002dhook"></a>Scheme Variable: <strong>quit-hook</strong></dt>
-<dd><p>A hook that is run when the user clicks the close button on the game
-window.  This hook is run with zero arguments.
-</p>
-<div class="example">
-<pre class="example">(add-hook! quit-hook (lambda () (display &quot;bye!\n&quot;)))
-</pre></div>
+</li><li> <var>quit</var>: Called with zero arguments when the user tries to close
+the game window.  The default behavior is to exit the game.
 
-</dd></dl>
+</li><li> <var>key-press</var>: Called with four arguments when a key is pressed on
+the keyboard:
 
-<dl>
-<dt><a name="index-key_002dpress_002dhook"></a>Scheme Variable: <strong>key-press-hook</strong></dt>
-<dd><p>A hook that is run when a key is pressed on the keyboard.  This hook
-is run with four arguments:
-</p>
 <ol>
 <li> <var>key</var>: The symbolic name of the &ldquo;virtual&rdquo; key that was pressed.
 For example: <code>backspace</code>.  It&rsquo;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 &ldquo;caps lock&rdquo; key to mean
-&ldquo;control&rdquo;.
+entirely, such as how the author likes to bind the &ldquo;caps lock&rdquo; key
+to mean &ldquo;control&rdquo;.
 
 </li><li> <var>scancode</var>: The symbolic name of the physical key that was
 pressed.
@@ -246,21 +214,9 @@ include <code>ctrl</code>, <code>alt</code>, and <code>shift</code>.
 
 </li></ol>
 
-<div class="example">
-<pre class="example">(add-hook! key-press-hook
-           (lambda (key scancode modifiers repeat?)
-             (display &quot;pressed key: &quot;)
-             (display key)
-             (newline)))
-</pre></div>
-
-</dd></dl>
+</li><li> <var>key-release</var>: Called with three arguments when a key is released
+on the keyboard:
 
-<dl>
-<dt><a name="index-key_002drelease_002dhook"></a>Scheme Variable: <strong>key-release-hook</strong></dt>
-<dd><p>A hook that is run when a key is released on the keyboard.  This hook
-is run with three arguments:
-</p>
 <ol>
 <li> <var>key</var>: The symbolic name of the &ldquo;virtual&rdquo; key that was released.
 
@@ -272,20 +228,11 @@ were being held down when the key was released.
 
 </li></ol>
 
-</dd></dl>
+</li><li> <var>text-input</var>: Called with a single argument, a string of text,
+when printable text is typed on the keyboard.
 
-<dl>
-<dt><a name="index-text_002dinput_002dhook"></a>Scheme Variable: <strong>text-input-hook</strong></dt>
-<dd><p>A hook that is run when printable text is typed on the keyboard.  This
-hook is run with a single argument, <var>text</var>, a string containing
-the text that was entered.
-</p></dd></dl>
-
-<dl>
-<dt><a name="index-mouse_002dpress_002dhook"></a>Scheme Variable: <strong>mouse-press-hook</strong></dt>
-<dd><p>A hook that is run when a mouse button is pressed.  This hook is run
-with four arguments:
-</p>
+</li><li> <var>mouse-press</var>: Called with four arguments when a mouse button is
+pressed:
 <ol>
 <li> <var>button</var>: The symbolic name of the button that was pressed, such
 as <code>left</code>, <code>middle</code>, or <code>right</code>.
@@ -298,13 +245,9 @@ as <code>left</code>, <code>middle</code>, or <code>right</code>.
 
 </li></ol>
 
-</dd></dl>
+</li><li> <var>mouse-release</var>: Called with three arguments when a mouse button
+is released:
 
-<dl>
-<dt><a name="index-mouse_002drelease_002dhook"></a>Scheme Variable: <strong>mouse-release-hook</strong></dt>
-<dd><p>A hook that is run when a mouse button is released.  This hook is run
-with three arguments:
-</p>
 <ol>
 <li> <var>button</var>: The symbolic name of the button that was released.
 
@@ -314,13 +257,8 @@ with three arguments:
 
 </li></ol>
 
-</dd></dl>
+</li><li> <var>mouse-move</var>: Called with five arguments when the mouse is moved:
 
-<dl>
-<dt><a name="index-mouse_002dmove_002dhook"></a>Scheme Variable: <strong>mouse-move-hook</strong></dt>
-<dd><p>A hook that is run when the mouse is moved.  This hook is run with
-five arguments:
-</p>
 <ol>
 <li> <var>x</var>: The x coordinate of the mouse cursor.
 
@@ -337,27 +275,15 @@ mouse was moved.
 
 </li></ol>
 
-</dd></dl>
+</li><li> <var>controller-add</var>: Called with a single argument, an SDL game
+controller object, when a game controller is connected.
 
-<dl>
-<dt><a name="index-controller_002dadd_002dhook"></a>Scheme Variable: <strong>controller-add-hook</strong></dt>
-<dd><p>A hook that is run when a game controller is connected.  This hook is
-run with a single argument, <var>controller</var>, the controller that was
-connected.
-</p></dd></dl>
+</li><li> <var>controller-remove</var>: Called with a single argument, an SDL game
+controller object, when a game controller is disconnected.
 
-<dl>
-<dt><a name="index-controller_002dremove_002dhook"></a>Scheme Variable: <strong>controller-remove-hook</strong></dt>
-<dd><p>A hook that is run when a game controller is disconnected.  This hook
-is run with a single argument, <var>controller</var>, the controller that
-was disconnected.
-</p></dd></dl>
+</li><li> <var>controller-press</var>: Called with two arguments when a button on a
+game controller is pressed:
 
-<dl>
-<dt><a name="index-controller_002dpress_002dhook"></a>Scheme Variable: <strong>controller-press-hook</strong></dt>
-<dd><p>A hook that is run when a button on a game controller is pressed.
-This hook is run with two arguments:
-</p>
 <ol>
 <li> <var>controller</var>: The controller that triggered the event.
 
@@ -385,14 +311,9 @@ Possible buttons are:
 
 </li></ol>
 
-</dd></dl>
+</li><li> <var>controller-release</var>: Called with two arguments when a button on a
+game controller is released:
 
-<dl>
-<dt><a name="index-controller_002drelease_002dhook"></a>Scheme Variable: <strong>controller-release-hook</strong></dt>
-<dd><p>A hook that is run when a button on a game controller is released.
-</p>
-<p>This hook is run with two arguments:
-</p>
 <ol>
 <li> <var>controller</var>: The controller that triggered the event.
 
@@ -400,13 +321,9 @@ Possible buttons are:
 
 </li></ol>
 
-</dd></dl>
+</li><li> <var>controller-move</var>: Called with three arguments when an analog
+stick or trigger on a game controller is moved:
 
-<dl>
-<dt><a name="index-controller_002dmove_002dhook"></a>Scheme Variable: <strong>controller-move-hook</strong></dt>
-<dd><p>A hook that is run when an analog stick or trigger on a game
-controller is moved.  This hook is run with three arguments
-</p>
 <ol>
 <li> <var>controller</var>: The controller that triggered the event.
 
@@ -424,12 +341,27 @@ values are:
 
 </li></ol>
 
+</li><li> <var>error</var>: Called with three arguments when an error occurs:
+
+<ol>
+<li> <var>stack</var>: The call stack at the point of error.
+
+</li><li> <var>key</var>: The exception key.
+
+</li><li> <var>args</var>: The arguments thrown with the exception.
+
+</li></ol>
+
+<p>The default behavior is to re-throw the error.
+</p>
+</li></ul>
+
 </dd></dl>
 
 <hr>
 <div class="header">
 <p>
-Next: <a href="Input.html#Input" accesskey="n" rel="next">Input</a>, Up: <a href="API-Reference.html#API-Reference" accesskey="u" rel="up">API Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
+Next: <a href="Math.html#Math" accesskey="n" rel="next">Math</a>, Up: <a href="API-Reference.html#API-Reference" accesskey="u" rel="up">API Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
 </div>
 
 
-- 
cgit v1.2.3

