diff options
Diffstat (limited to 'manuals/chickadee/Kernel.html')
| -rw-r--r-- | manuals/chickadee/Kernel.html | 300 |
1 files changed, 116 insertions, 184 deletions
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> [<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> [<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 “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</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 “hooks”, -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’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 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 "Chickadee!"] [#: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 "hello!\n"))) -</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 “choppy”. 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 "tick!\n"))) -</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 "about to draw!\n"))) -</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 "done drawing!\n"))) -</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 "Chickadee!"] [#: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 -“choppy”. 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 "<(._.<) \n"))) -</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 "bye!\n"))) -</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 “virtual” key that was pressed. For example: <code>backspace</code>. 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”. </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 "pressed key: ") - (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 “virtual” 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> [<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> [<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> |