Update Chickadee manual.

1 files changed, 106 insertions, 3 deletions

diff --git a/manuals/chickadee/Sprites.html b/manuals/chickadee/Sprites.html
index 700941b..0c114bd 100644
--- a/manuals/chickadee/Sprites.html
+++ b/manuals/chickadee/Sprites.html
@@ -31,7 +31,7 @@ http://www.texinfo.org/ (GNU Texinfo).
 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
 <link href="Graphics.html#Graphics" rel="up" title="Graphics">
 <link href="Lines-and-Shapes.html#Lines-and-Shapes" rel="next" title="Lines and Shapes">
-<link href="Rendering-Engine.html#Rendering-Engine" rel="prev" title="Rendering Engine">
+<link href="Textures.html#Textures" rel="prev" title="Textures">
 <style type="text/css">
 <!--
 a.summary-letter {text-decoration: none}
@@ -57,8 +57,31 @@ span.nolinebreak {white-space: nowrap}
 span.roman {font-family: initial; font-weight: normal}
 span.sansserif {font-family: sans-serif; font-weight: normal}
 ul.no-bullet {list-style: none}
+@media (min-width: 1140px) {
+    body {
+        margin-left: 14rem;
+        margin-right: 4rem;
+        max-width: 52rem;
+    }
+}
+
+@media (min-width: 800px) and (max-width: 1140px) {
+    body {
+        margin-left: 6rem;
+        margin-right: 4rem;
+        max-width: 52rem;
+    }
+}
+
+@media (max-width: 800px) {
+    body {
+        margin: 1rem;
+    }
+}
+
 -->
 </style>
+<link rel="stylesheet" type="text/css" href="https://dthompson.us/css/dthompson.css">
 
 
 </head>
@@ -67,12 +90,92 @@ ul.no-bullet {list-style: none}
 <a name="Sprites"></a>
 <div class="header">
 <p>
-Next: <a href="Lines-and-Shapes.html#Lines-and-Shapes" accesskey="n" rel="next">Lines and Shapes</a>, Previous: <a href="Rendering-Engine.html#Rendering-Engine" accesskey="p" rel="prev">Rendering Engine</a>, Up: <a href="Graphics.html#Graphics" accesskey="u" rel="up">Graphics</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="Lines-and-Shapes.html#Lines-and-Shapes" accesskey="n" rel="next">Lines and Shapes</a>, Previous: <a href="Textures.html#Textures" accesskey="p" rel="prev">Textures</a>, Up: <a href="Graphics.html#Graphics" accesskey="u" rel="up">Graphics</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="Sprites-1"></a>
-<h4 class="subsection">2.4.2 Sprites</h4>
+<h4 class="subsection">2.4.3 Sprites</h4>
+
+<p>For those who are new to this game, a sprite is a 2D rectangular
+bitmap that is rendered to the screen.  For 2D games, sprites are the
+most essential graphical abstraction.  They are used for drawing maps,
+players, NPCs, items, particles, text, etc.  In Chickadee, bitmaps are
+stored in textures (see <a href="Textures.html#Textures">Textures</a>) and can be used to draw sprites
+via the <code>draw-sprite</code> procedure.
+</p>
+<dl>
+<dt><a name="index-draw_002dsprite"></a>Scheme Procedure: <strong>draw-sprite</strong> <em><var>texture</var> <var>region</var>        [#:scale] [#:rotation] [#:blend-mode alpha] [#:texture-region]        [#:shader]</em></dt>
+</dl>
+
+<p>It&rsquo;s not uncommon to need to draw hundreds or thousands of sprites
+each frame.  However, GPUs (graphics processing units) are tricky
+beasts that prefer to be sent few, large chunks of data to render
+rather than many, small chunks.  Using <code>draw-sprite</code> on its own
+will involve at least one GPU call <em>per sprite</em>, which will
+quickly lead to poor performance.  To deal with this, a technique
+known as &ldquo;sprite batching&rdquo; can be used.  Instead of drawing each
+sprite immediately, the sprite batch will build up a large of buffer
+of sprites to draw and defer rendering until the last possible moment.
+Batching isn&rsquo;t a panacea, though.  Batching only works if the sprites
+being drawn share as much in common as possible.  Every time you draw
+a sprite with a different texture or blend mode, the batch will be
+sent off to the GPU.  Therefore, batching is most useful if you
+minimize such changes.  A good strategy for reducing texture changes
+is to stuff many bitmaps into a single image file and create a
+&ldquo;texture atlas&rdquo; (see <a href="Textures.html#Textures">Textures</a>) to access the sub-images within.
+</p>
+<p>Taking advantage of sprite batching in Chickadee is easy, just wrap
+the code that is calling <code>draw-sprite</code> a lot in the
+<code>with-batched-sprites</code> form.
+</p>
+<dl>
+<dt><a name="index-with_002dbatched_002dsprites"></a>Scheme Syntax: <strong>with-batched-sprites</strong> <em><var>body</var> &hellip;</em></dt>
+<dd><p>Use batched rendering for all <code>draw-sprite</code> calls within
+<var>body</var>.
+</p></dd></dl>
+
+<p>With a basic sprite abstraction in place, it&rsquo;s possible to build other
+abstractions on top of it.  One such example is the &ldquo;nine patch&rdquo;.  A
+nine patch is a sprite that can be rendered at various sizes without
+becoming distorted.  This is achieved by diving up the sprite into
+nine regions:
+</p>
+<ul>
+<li> the center, which can be scaled horizontally and vertically
+</li><li> the four corners, which can never be scaled
+</li><li> the left and right sides, which can be scaled vertically
+</li><li> the top and bottom sides, which can be scaled horizontally
+</li></ul>
 
+<p>The one caveat is that the bitmap regions must be designed in such a
+way so that they are not distorted when stretched along the affected
+axes.  For example, that means that the top and bottom sides could
+have varying colored pixels vertically, but not horizontally.
+</p>
+<p>The most common application of this technique is for graphical user
+interface widgets like buttons and dialog boxes.  By using a nine
+patch, they can be rendered at any size without unappealing scaling
+artifacts.
+</p>
+<dl>
+<dt><a name="index-draw_002dnine_002dpatch"></a>Scheme Procedure: <strong>draw-nine-patch</strong> <em><var>texture</var> <var>region</var>        [#:margin 0] [#:top-margin margin] [#:bottom-margin margin]        [#:left-margin margin] [#:right-margin margin]        [#:texture-region] [#:scale] [#:rotation] [#:blend-mode alpha]        [#:shader]</em></dt>
+<dd>
+<p>Draw a nine patch sprite.  A nine patch sprite renders <var>texture</var>
+as a <var>width</var> x <var>height</var> rectangle whose stretchable areas are
+defined by the given margin measurements <var>top-margin</var>,
+<var>bottom-margin</var>, <var>left-margin</var>, and <var>right-margin</var>. The
+<var>margin</var> argument may be used to configure all four margins at
+once.
+</p>
+<p>Refer to <code>draw-sprite</code> (see <a href="#Sprites">Sprites</a>) for information about
+the other arguments.
+</p></dd></dl>
+
+<hr>
+<div class="header">
+<p>
+Next: <a href="Lines-and-Shapes.html#Lines-and-Shapes" accesskey="n" rel="next">Lines and Shapes</a>, Previous: <a href="Textures.html#Textures" accesskey="p" rel="prev">Textures</a>, Up: <a href="Graphics.html#Graphics" accesskey="u" rel="up">Graphics</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>