updated documentation for ag.loadModel() and ag.create*() for reference objects

git-svn-id: svn://anubis/anaglym/trunk@245 99a6e188-d820-4881-8870-2d33a10e2619

.todo

@@ -1,4 +1,3 @@
-update documentation for loadModel*(), create*()
 add documentation for motors
 add Lua interface for showing/hiding mouse cursor
 add 3d-picking routines using temporary ODE ray geometries

doc/index.html

@@ -286,7 +286,7 @@ See <a href="#key_names">Key Names</a> for key names.
 
 <a name="ag_loadModel" />
 <h3>loadModel</h3>
-<p><tt>object = ag.loadModel(model_name [, scale])</tt></p>
+<p><tt>object = ag.loadModel(model_name [, optargs])</tt></p>
 <p>
 This function loads an object file and returns the object loaded.
 If the returned value is <tt>nil</tt>, loading of the object failed.
@@ -294,21 +294,32 @@ If the returned value is <tt>nil</tt>, loading of the object failed.
 the model file, without the ".obj" extension.
 Models are searched for relative to the folder containing the
 hosted script first, then relative to the engine library folder.
-<tt>scale</tt> is an optional parameter that defaults to 1.0.
 </p>
-
-<a name="ag_loadModelStatic" />
-<h3>loadModelStatic</h3>
-<p><tt>object = ag.loadModelStatic(model_name [, scale])</tt></p>
 <p>
-<tt>loadModelStatic()</tt> is the same as <tt>loadModel()</tt>, with
+If specified, <tt>optargs</tt> should be a table of named parameters.
-the exception that the object loaded is created as a static object.
+Possible parameters are:
+<ul>
+    <li><tt>scale</tt> - specify the scale of the model (default 1.0)</li>
+    <li><tt>static</tt> - boolean to indicate if the object is static</li>
+    <li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
+</ul>
+</p>
+<p>
 A static object can still be placed with
 <a href="#object_setPosition">setPosition()</a> and
 <a href="#object_setRotation">setRotation()</a>.
 A static object will participate in collision detection when
 physics computations are performed, however a static object will not
 be moved by any colliding objects.
+Static objects do not have a mass associated with them; they are considered
+to be a part of the environment.
+</p>
+<p>
+A reference object will not be drawn and cannot participate in physics.
+A reference object is useful when one wishes to load a model some time
+before actually using it.
+You can instantiate a reference object into a normal object by calling
+the <a href="#object_clone">clone()</a> method on the object.
 </p>
 
 <a name="ag_loadTexture" />
@@ -478,24 +489,25 @@ and rotation, can be controlled by using the
 
 <a name="ag_createBox" />
 <h3><tt>createBox</tt></h3>
-<p><tt>obj = ag.createBox(width, depth, height)</tt></p>
+<p><tt>obj = ag.createBox(width, depth, height [, optargs])</tt></p>
 <p>
 This function creates a managed object which is a box with
 dimensions given by (width, depth, height).
 The center of the box is initially located at the origin.
 </p>
-
-<a name="ag_createBoxStatic" />
-<h3><tt>createBoxStatic</tt></h3>
-<p><tt>obj = ag.createBoxStatic(width, depth, height)</tt></p>
 <p>
-Identical to <tt>ag.createBox()</tt> except that the created
+If specified, <tt>optargs</tt> should be a table containing
-object is static.
+named parameters.
+Valid parameters:
+<ul>
+    <li><tt>static</tt> - boolean to indicate if the object is static</li>
+    <li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
+</ul>
 </p>
 
-<a name="ag_createCapsul" />
+<a name="ag_createCapsule" />
 <h3><tt>createCapsule</tt></h3>
-<p><tt>obj = ag.createCapsule(radius, length)</tt></p>
+<p><tt>obj = ag.createCapsule(radius, length [, optargs])</tt></p>
 <p>
 This function creates a capsule managed object.
 A capsule is like a cylinder, but has a half-sphere "capping"
@@ -506,19 +518,20 @@ the capsule (not including the caps).
 The capsule is oriented with its axis along the Z axis and its
 center point at the origin.
 </p>
-
-<a name="ag_createCapsuleStatic" />
-<h3><tt>createCapsuleStatic</tt></h3>
-<p><tt>obj = ag.createCapsuleStatic(radius, length)</tt></p>
 <p>
-Identical to <tt>ag.createCapsule()</tt> except that the created
+If specified, <tt>optargs</tt> should be a table containing
-object is static.
+named parameters.
+Valid parameters:
+<ul>
+    <li><tt>static</tt> - boolean to indicate if the object is static</li>
+    <li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
+</ul>
 </p>
 
 <a name="ag_createPlane" />
 <h3><tt>createPlane</tt></h3>
-<p>1) <tt>obj = ag.createPlane(a, b, c, d)</tt></p>
+<p>1) <tt>obj = ag.createPlane(a, b, c, d [, optargs])</tt></p>
-<p>2) <tt>obj = ag.createPlane(x, y, z, rot_x, rot_y, rot_z)</tt></p>
+<p>2) <tt>obj = ag.createPlane(x, y, z, rot_x, rot_y, rot_z [, optargs])</tt></p>
 <p>
 The <tt>createPlane()</tt> function creates a managed plane object.
 All planes are static and are not moved as a result of physics
@@ -535,21 +548,30 @@ the surface and the surface normal, see the
 <a href="#std_createPlanePointNormal">std.createPlanePointNormal()</a>
 function.
 </p>
+<p>
+If specified, <tt>optargs</tt> should be a table containing
+named parameters.
+Valid parameters:
+<ul>
+    <li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
+</ul>
+</p>
 
 <a name="ag_createSphere" />
 <h3><tt>createSphere</tt></h3>
-<p><tt>obj = ag.createSphere(radius)</tt></p>
+<p><tt>obj = ag.createSphere(radius [, optargs])</tt></p>
 <p>
 This function creates a managed sphere object with the radius given.
 The center of the sphere is initially located at the origin.
 </p>
-
-<a name="ag_createSphereStatic" />
-<h3><tt>createSphereStatic</tt></h3>
-<p><tt>obj = ag.createSphereStatic(radius)</tt></p>
 <p>
-Identical to <tt>ag.createSphere()</tt> except that the created
+If specified, <tt>optargs</tt> should be a table containing
-object is static.
+named parameters.
+Valid parameters:
+<ul>
+    <li><tt>static</tt> - boolean to indicate if the object is static</li>
+    <li><tt>reference</tt> - boolean to indicate if the object is a reference object </li>
+</ul>
 </p>
 
 <hr />
@@ -606,6 +628,8 @@ One should call
 <tt>new_obj:<a href="#object_setPosition">setPosition()</a></tt>
 in order to place <tt>new_obj</tt> somewhere where it is not
 intersecting with other objects in order to pacify the physics engine.
+The new object created will be a regular (non-reference) object, regardless
+of whether <tt>obj</tt> was a regular or reference object.
 </p>
 
 <a name="object_destroy" />