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/Vectors.html | 261 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 252 insertions(+), 9 deletions(-)

(limited to 'manuals/chickadee/Vectors.html')
diff --git a/manuals/chickadee/Vectors.html b/manuals/chickadee/Vectors.html
index eb79149..4857f0a 100644
--- a/manuals/chickadee/Vectors.html
+++ b/manuals/chickadee/Vectors.html
@@ -16,22 +16,22 @@ 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: Vectors</title>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Vectors (The Chickadee Game Toolkit)</title>
 
-<meta name="description" content="The Chickadee Game Toolkit: Vectors">
-<meta name="keywords" content="The Chickadee Game Toolkit: Vectors">
+<meta name="description" content="Vectors (The Chickadee Game Toolkit)">
+<meta name="keywords" content="Vectors (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="Math.html#Math" rel="up" title="Math">
-<link href="Matrices.html#Matrices" rel="next" title="Matrices">
-<link href="Math.html#Math" rel="prev" title="Math">
+<link href="Rectangles.html#Rectangles" rel="next" title="Rectangles">
+<link href="Basics.html#Basics" rel="prev" title="Basics">
 <style type="text/css">
 <!--
 a.summary-letter {text-decoration: none}
@@ -90,12 +90,255 @@ ul.no-bullet {list-style: none}
 <a name="Vectors"></a>
 <div class="header">
 <p>
-Next: <a href="Matrices.html#Matrices" accesskey="n" rel="next">Matrices</a>, Up: <a href="Math.html#Math" accesskey="u" rel="up">Math</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="Rectangles.html#Rectangles" accesskey="n" rel="next">Rectangles</a>, Previous: <a href="Basics.html#Basics" accesskey="p" rel="prev">Basics</a>, Up: <a href="Math.html#Math" accesskey="u" rel="up">Math</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="Vectors-1"></a>
-<h4 class="subsection">2.3.1 Vectors</h4>
+<h4 class="subsection">2.2.2 Vectors</h4>
+
+<p>Unlike Scheme&rsquo;s vector data type, which is a sequence of arbitrary
+Scheme objects, Chickadee&rsquo;s <code>(chickadee math vector)</code> module
+provides vectors in the linear algebra sense: Sequences of numbers
+specialized for particular coordinate spaces.  As of now, Chickadee
+provides 2D and 3D vectors, with 4D vector support coming in a future
+release.
+</p>
+<p>Here&rsquo;s a quick example of adding two vectors:
+</p>
+<div class="example">
+<pre class="example">(define v (vec2+ (vec2 1 2) (vec2 3 4)))
+</pre></div>
+
+<p>Since vectors are used so frequently, the reader macro <code>#v</code> is
+used to cut down on typing:
+</p>
+<div class="example">
+<pre class="example">(define v (vec2+ #v(1 2) #v(3 4)))
+</pre></div>
+
+<a name="A-Note-About-Performance"></a>
+<h4 class="subsubsection">2.2.2.1 A Note About Performance</h4>
+
+<p>A lot of time has been spent making Chickadee&rsquo;s vector operations
+perform relatively efficiently in critical code paths where excessive
+garbage generation will cause major performance issues.  The general
+rule is that procedures ending with <code>!</code> perform an in-place
+modification of one of the arguments in order to avoid allocating a
+new vector.  These procedures are also inlined by Guile&rsquo;s compiler in
+order to take advantage of optimizations relating to floating point
+math operations.  The downside is that since these are not pure
+functions, they do not compose well and create more verbose code.
+</p>
+<a name="g_t2D-Vectors"></a>
+<h4 class="subsubsection">2.2.2.2 2D Vectors</h4>
+
+<dl>
+<dt><a name="index-vec2"></a>Procedure: <strong>vec2</strong> <em><var>x</var> <var>y</var></em></dt>
+<dd><p>Return a new 2D vector with coordinates (<var>x</var>, <var>y</var>).
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002fpolar"></a>Procedure: <strong>vec2/polar</strong> <em><var>r</var> <var>theta</var></em></dt>
+<dd><p>Return a new 2D vector containing the Cartesian representation of the
+polar coordinate (<var>r</var>, <var>theta</var>).  The angle <var>theta</var> is
+measured in radians.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_003f"></a>Procedure: <strong>vec2?</strong> <em><var>obj</var></em></dt>
+<dd><p>Return <code>#t</code> if <var>obj</var> is a 2D vector.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dx"></a>Procedure: <strong>vec2-x</strong> <em><var>v</var></em></dt>
+<dd><p>Return the X coordinate of the 2D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dy"></a>Procedure: <strong>vec2-y</strong> <em><var>v</var></em></dt>
+<dd><p>Return the Y coordinate of the 2D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dcopy"></a>Procedure: <strong>vec2-copy</strong> <em><var>v</var></em></dt>
+<dd><p>Return a fresh copy of the 2D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dmagnitude"></a>Procedure: <strong>vec2-magnitude</strong> <em><var>v</var></em></dt>
+<dd><p>Return the magnitude of the 2D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002ddot_002dproduct"></a>Procedure: <strong>vec2-dot-product</strong> <em><var>v1</var> <var>v2</var></em></dt>
+<dd><p>Return the dot product of the 2D vectors <var>v1</var> and <var>v2</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dnormalize"></a>Procedure: <strong>vec2-normalize</strong> <em><var>v</var></em></dt>
+<dd><p>Return the normalized form of the 2D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002b"></a>Procedure: <strong>vec2+</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Add <var>x</var>, either a 2D vector or a scalar (i.e. a real number), to
+the 2D vector <var>v</var> and return a new vector containing the sum.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002d"></a>Procedure: <strong>vec2-</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Subtract <var>x</var>, either a 2D vector or a scalar, from the 2D vector
+<var>v</var> and return a new vector containing the difference.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002a"></a>Procedure: <strong>vec2*</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Multiply the 2D vector <var>v</var> by <var>x</var>, a 2D vector or a scalar,
+and return a new vector containing the product.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-set_002dvec2_002dx_0021"></a>Procedure: <strong>set-vec2-x!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Set the X coordinate of the 2D vector <var>v</var> to <var>x</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-set_002dvec2_002dy_0021"></a>Procedure: <strong>set-vec2-y!</strong> <em><var>v</var> <var>y</var></em></dt>
+<dd><p>Set the Y coordinate of the 2D vector <var>v</var> to <var>y</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dcopy_0021"></a>Procedure: <strong>vec2-copy!</strong> <em><var>source</var> <var>target</var></em></dt>
+<dd><p>Copy the 2D vector <var>source</var> into the 2D vector <var>target</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dadd_0021"></a>Procedure: <strong>vec2-add!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Perform an in-place modification of the 2D vector <var>v</var> by adding
+<var>x</var>, a 2D vector or a scalar.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dsub_0021"></a>Procedure: <strong>vec2-sub!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Perform an in-place modification of the 2D vector <var>v</var> by
+subtracting <var>x</var>, a 2D vector or a scalar.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec2_002dmult_0021"></a>Procedure: <strong>vec2-mult!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Perform an in-place modification of the 2D vector <var>v</var> by
+multiplying it by <var>x</var>, a 2D vector or a scalar.
+</p></dd></dl>
 
+<a name="g_t3D-Vectors"></a>
+<h4 class="subsubsection">2.2.2.3 3D Vectors</h4>
+
+<dl>
+<dt><a name="index-vec3"></a>Procedure: <strong>vec3</strong> <em><var>x</var> <var>y</var></em></dt>
+<dd><p>Return a new 2D vector with coordinates (<var>x</var>, <var>y</var>).
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_003f"></a>Procedure: <strong>vec3?</strong> <em><var>obj</var></em></dt>
+<dd><p>Return <code>#t</code> if <var>obj</var> is a 3D vector.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dx"></a>Procedure: <strong>vec3-x</strong> <em><var>v</var></em></dt>
+<dd><p>Return the X coordinate of the 3D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dy"></a>Procedure: <strong>vec3-y</strong> <em><var>v</var></em></dt>
+<dd><p>Return the Y coordinate of the 3D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dz"></a>Procedure: <strong>vec3-z</strong> <em><var>v</var></em></dt>
+<dd><p>Return the Z coordinate of the 3D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dcopy"></a>Procedure: <strong>vec3-copy</strong> <em><var>v</var></em></dt>
+<dd><p>Return a fresh copy of the 3D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dmagnitude"></a>Procedure: <strong>vec3-magnitude</strong> <em><var>v</var></em></dt>
+<dd><p>Return the magnitude of the 3D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002ddot_002dproduct"></a>Procedure: <strong>vec3-dot-product</strong> <em><var>v1</var> <var>v2</var></em></dt>
+<dd><p>Return the dot product of the 3D vectors <var>v1</var> and <var>v2</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dnormalize"></a>Procedure: <strong>vec3-normalize</strong> <em><var>v</var></em></dt>
+<dd><p>Return the normalized form of the 3D vector <var>v</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002b"></a>Procedure: <strong>vec3+</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Add <var>x</var>, either a 3D vector or a scalar (i.e. a real number), to
+the 3D vector <var>v</var> and return a new vector containing the sum.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002d"></a>Procedure: <strong>vec3-</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Subtract <var>x</var>, either a 3D vector or a scalar, from the 3D vector
+<var>v</var> and return a new vector containing the difference.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002a"></a>Procedure: <strong>vec3*</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Multiply the 3D vector <var>v</var> by <var>x</var>, a 3D vector or a scalar,
+and return a new vector containing the product.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-set_002dvec3_002dx_0021"></a>Procedure: <strong>set-vec3-x!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Set the X coordinate of the 3D vector <var>v</var> to <var>x</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-set_002dvec3_002dy_0021"></a>Procedure: <strong>set-vec3-y!</strong> <em><var>v</var> <var>y</var></em></dt>
+<dd><p>Set the Y coordinate of the 3D vector <var>v</var> to <var>y</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-set_002dvec3_002dz_0021"></a>Procedure: <strong>set-vec3-z!</strong> <em><var>v</var> <var>z</var></em></dt>
+<dd><p>Set the Z coordinate of the 3D vector <var>v</var> to <var>z</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dcopy_0021"></a>Procedure: <strong>vec3-copy!</strong> <em><var>source</var> <var>target</var></em></dt>
+<dd><p>Copy the 3D vector <var>source</var> into the 3D vector <var>target</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dadd_0021"></a>Procedure: <strong>vec3-add!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Perform an in-place modification of the 3D vector <var>v</var> by adding
+<var>x</var>, a 3D vector or a scalar.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dsub_0021"></a>Procedure: <strong>vec3-sub!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Perform an in-place modification of the 3D vector <var>v</var> by
+subtracting <var>x</var>, a 3D vector or a scalar.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-vec3_002dmult_0021"></a>Procedure: <strong>vec3-mult!</strong> <em><var>v</var> <var>x</var></em></dt>
+<dd><p>Perform an in-place modification of the 3D vector <var>v</var> by
+multiplying it by <var>x</var>, a 3D vector or a scalar.
+</p></dd></dl>
+
+<hr>
+<div class="header">
+<p>
+Next: <a href="Rectangles.html#Rectangles" accesskey="n" rel="next">Rectangles</a>, Previous: <a href="Basics.html#Basics" accesskey="p" rel="prev">Basics</a>, Up: <a href="Math.html#Math" accesskey="u" rel="up">Math</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

