From e14c2ef56ce2e9c3b84087fc8ee6480f3ea9a49a Mon Sep 17 00:00:00 2001
From: Josh Holtrop <jholtrop+git@gmail.com>
Date: Tue, 16 Feb 2010 20:45:55 +0000
Subject: [PATCH] added documentation for ag.createAMotor() and
 ag.createHinge()

git-svn-id: svn://anubis/anaglym/trunk@246 99a6e188-d820-4881-8870-2d33a10e2619
---
 .todo          |  1 -
 doc/index.html | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/.todo b/.todo
index fa2b4fc..54ec4be 100644
--- a/.todo
+++ b/.todo
@@ -1,4 +1,3 @@
-add documentation for motors
 add Lua interface for showing/hiding mouse cursor
 add 3d-picking routines using temporary ODE ray geometries
 add audio capabilities
diff --git a/doc/index.html b/doc/index.html
index f553c93..b551ef6 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -63,6 +63,77 @@ See <a href="#handlers">Lua event handlers</a> for a list of events.
 This function removes all objects from the world.
 </p>
 
+<a name="ag_createAMotor" />
+<h3>createAMotor</h3>
+<p><tt>motor = ag.createAMotor(obj1, obj2, axis0 [, axis1 [, axis2 ] ])</tt></p>
+<p>
+This function creates an angular motor in the simulation.
+An angular motor supplies torque to the bodies it is connected to around the
+axes specified in order to control the relative angular velocities of
+the two objects around the axes.
+Up to three axes can be specified, but only one is required.
+<tt>obj1</tt> and <tt>obj2</tt> specify the two objects that are connected
+with the motor.
+One of <tt>obj1</tt> or <tt>obj2</tt> can be the number 0 to signify
+that the other object should be connected to the static environment.
+</p>
+<p>
+Connecting two objects with an angular motor does not restrict their
+positions relative to one another.
+See <a href="#ag_createHinge">createHinge()</a>.
+</p>
+<p>
+Each axis<em>n</em> argument should be a table containing named parameters.
+All parameters are optional.
+Valid parameters:
+<ul>
+    <li><tt>x</tt> - x coordinate of axis vector (default 1)</li>
+    <li><tt>y</tt> - y coordinate of axis vector (default 0)</li>
+    <li><tt>z</tt> - z coordinate of axis vector (default 0)</li>
+    <li><tt>rel</tt> - controls relative orientation of axis. Possible values:
+        <ul>
+            <li>0 - axis is anchored to the static environment (default)</li>
+            <li>1 - axis is anchored to the first body</li>
+            <li>2 - axis is anchored to the second body</li>
+        </ul>
+    </li>
+    <li><tt>angle</tt> - initial angle of the motor on this axis (default 0)</li>
+    <li><tt>lo_stop</tt> - minimum angle of the motor (default disabled)</li>
+    <li><tt>hi_stop</tt> - maximum angle of the motor (default disabled)</li>
+    <li><tt>vel</tt> - target angular velocity of the motor on this axis (default 0)</li>
+    <li><tt>fmax</tt> - maximum amount of force the motor will apply around this axis to try to reach a velocity of <tt>vel</tt> (default 0)</li>
+    <li><tt>bounce</tt> - bounciness of the motor stops (default 0)</li>
+</ul>
+The motor will only allow movement around each axis from the <tt>lo_stop</tt>
+to <tt>hi_stop</tt> angles.
+The motor will attempt to maintain relative angular velocities of <tt>vel</tt>
+around each axis.
+The maximum amount of force that the motor is allowed to apply in order to
+maintain this velocity is specified by the <tt>fmax</tt> axis parameter.
+Specifying a low <tt>fmax</tt> value will cause the motor to take a while
+to reach its target velocity, and will mean that other objects can
+slow down or stop the motor easily.
+In contrast, a very high <tt>fmax</tt> value will allow the motor to reach
+its target velocity more quickly and the motor will be harder to stop by
+collisions with other objects.
+The <tt>bounce</tt> parameter should range from 0 to 1, with 0 meaning a hard stop and 1 meaning full bounciness.
+</p>
+
+<a name="ag_createHinge" />
+<h3>createHinge</h3>
+<p><tt>hinge = ag.createHinge(obj1, obj2, anchor, axis)</tt></p>
+<p>
+This function creates a hinge joint between two objects,
+keeping a single axis from each object aligned.
+The two objects can rotate around this axis independently.
+One of <tt>obj1</tt> or <tt>obj2</tt> can be the number 0 to signify
+that the other object should be connected to the static environment.
+<tt>anchor</tt> and <tt>axis</tt> should be Lua "arrays" (tables with
+integer indices starting at 1), with three elemenets each.
+<tt>anchor</tt> gives the coordinates of a point on the hinge.
+<tt>axis</tt> gives the direction vector of the hinge.
+</p>
+
 <a name="ag_doPhysics" />
 <h3>doPhysics</h3>
 <p><tt>ag.doPhysics()</tt></p>