From aaa0cda3a53285c6d1c1d2ffca69c48d171bd0b7 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Wed, 25 Nov 2009 00:19:48 +0000 Subject: [PATCH] finished documentation for ag library git-svn-id: svn://anubis/anaglym/trunk@193 99a6e188-d820-4881-8870-2d33a10e2619 --- doc/index.html | 285 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 255 insertions(+), 30 deletions(-) diff --git a/doc/index.html b/doc/index.html index 8793301..3337963 100644 --- a/doc/index.html +++ b/doc/index.html @@ -21,7 +21,13 @@ The library functions are documented below.

@@ -38,13 +44,13 @@ This function removes a Lua callback function from being associated with the engine event specified. event_name should be one of the following strings:

@@ -127,7 +133,8 @@ name of the Lua library without the ".lua" extension. Source files are searched for relative to the folder containing the hosted script first, then relative to the engine library folder. The import() function can be used to load Lua code that -is broken into separate source files. +is broken into separate source files, and to load +libraries such as std.

@@ -160,8 +167,8 @@ hosted script first, then relative to the engine library folder. loadModelStatic() is the same as loadModel(), with the exception that the object loaded is created as a static object. A static object can still be placed with -setPosition() and -setRotation(). +setPosition() and +setRotation(). 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. @@ -185,6 +192,7 @@ hosted script first, then relative to the engine library folder.

ag.print(args...)

This function prints its arguments to the standard output. +It is mainly used for debugging when developing Lua scripts. On Windows, this output stream may be redirected to a file (stdout.txt). Example usage: 

local x, y, z = my_obj:getPosition()
@@ -212,15 +220,22 @@ Lua function was registered for event_name, it will be
 overwritten to call the new handler.
 event_name should be one of:
 
 

+

+When the Lua script is initially loaded, any functions found
+that have names matching an event name with "_event" appended
+(ex. "mouse_motion_event" for the "mouse_motion" event)
+are registered automatically as handlers for their corresponding
+events.
+

 
 
 
setAutoDrawObjects

@@ -233,6 +248,7 @@ engine will be drawn automatically every update step.
 If it is not enabled, one can call
 ag.drawObjects()
 to draw all visible objects in the scene.
+The AutoDrawObjects mode is initially enabled.
 

 
 
@@ -245,6 +261,7 @@ If AutoEndFrame mode is enabled, then
 ag.endFrame()
 will be invoked automatically after executing the update
 and update_overlay Lua callback functions.
+The AutoEndFrame mode is initially enabled.
 

 
 
@@ -254,10 +271,11 @@ and update_overlay Lua callback functions.
 This function sets the "AutoPhysics" mode.
 enable_flag should be true or false.
 If AutoPhysics mode is enabled, then collision detection and
-physics processing is performed automatically on every update step.
+physics processing are performed automatically on every update step.
 If it is not enabled, one can call
 ag.doPhysics()
 to perform physics updates.
+The AutoPhysics mode is initially enabled.
 

 
 
@@ -267,9 +285,10 @@ to perform physics updates.
 This function sets the "AutoStartFrame" mode.
 enable_flag should be true or false.
 If AutoStartFrame mode is enabled, then
-ag.startFrame()
+ag.startFrame()
 will be invoked automatically prior to executing the update and
 update_overlay Lua callback functions.
+The AutoStartFrame mode is initially enabled.
 

 
 
@@ -296,51 +315,257 @@ See ag.setAutoStartFrame().
 
 

 
-
-
std library

-
-

-
 
 
Object creation functions

 
+

+The following functions can be used to create "managed" objects.
+These objects are "managed" by the Lua script (as opposed to having
+all of their attributes defined in a model file).
+The properties of managed objects, such as the color, texture, position,
+and rotation, can be controlled by using the 
+object member functions.
+

+
 
 
createBox

+
obj = ag.createBox(width, depth, height)

+

+This function creates a managed object which is a box with
+dimensions given by (width, depth, height).
+

 
 
 
createBoxStatic

+
obj = ag.createBoxStatic(width, depth, height)

+

+Identical to ag.createBox() except that the created
+object is static.
+

 
 
 
createCapsule

+
obj = ag.createCapsule(radius, length)

+

+This function creates a capsule managed object.
+A capsule is like a cylinder, but has a half-sphere "capping"
+each end of the cylinder.
+radius specifies the radius of the cylinder (and caps).
+length specifies the length of the straight part of
+the capsule (not including the caps).
+The capsule is oriented with its axis along the Z axis and its
+center point at the origin.
+

 
 
 
createCapsuleStatic

+
obj = ag.createCapsuleStatic(radius, length)

+

+Identical to ag.createCapsule() except that the created
+object is static.
+

 
 
 
createCylinder

+
obj = ag.createCylinder(radius, length)

+

+This function creates a cylinder managed object.
+radius specifies the radius of the cylinder.
+length specifies the length of the cylinder.
+The cylinder is oriented with its axis along the Z axis and its
+center point at the origin.
+

 
 
 
createCylinderStatic

+
obj = ag.createCylinderStatic(radius, length)

+

+Identical to ag.createCylinder() except that the created
+object is static.
+

 
 
 
createPlane

-
-
-
createPlaneStatic

+
1) obj = ag.createPlane(a, b, c, d)

+
2) obj = ag.createPlane(x, y, z, rot_x, rot_y, rot_z)

+

+The createPlane() function creates a managed plane object.
+All planes are static and are not moved as a result of physics
+collisions (other objects can still bounce off them).
+In the four-argument form, the plane is created with equation
+ax + by + cz = d.
+(a, b, c) specifies the normal vector for the plane.
+In the six-argument form, the plane is created by specifying a point
+on the plane, with coordinates (x, y, z), and the Euler rotation
+angles around the x, y, and z axis.
+Specifying no rotation would use the default plane normal of (0, 0, 1).
+If you would like to create a plane by specifying a point on
+the surface and the surface normal, see the
+std.createPlanePtNormal() function.
+

 
 
 
createSphere

+
obj = ag.createSphere(radius)

+

+This function creates a managed sphere object with the radius given.
+

 
 
 
createSphereStatic

+
obj = ag.createSphereStatic(radius)

+

+Identical to ag.createSphere() except that the created
+object is static.
+

 
 

 
 
-
Object member functions

+
Object member methods

+
+
+
addForce

+
obj:addForce(xf, yf, zf)

+

+This function adds a one-time force to obj
+with a force vector (xf, yf, zf).
+

+
+
+
addForceRel

+
obj:addForceRel

+

+This function adds a one-time force to obj
+with a force vector (xf, yf, zf) which is
+relative to the local reference frame of obj.
+

+
+
+
addTorque

+
obj:addTorque(xr, yr, zr)

+

+This function adds torque (a rotational force) to obj.
+The torque vector around global axes x, y, z is given by (xr, yr, zr).
+

+
+
+
addTorqueRel

+
obj:addTorqueRel(xr, yr, zr)

+

+This function adds torque (a rotational force) to obj.
+The torque vector around the local axes x, y, z of obj
+is given by (xr, yr, zr).
+

+
+
+
clone

+
new_obj = obj:clone()

+

+This function makes a copy of the object in the engine.
+This is more efficient then recreating the object in whatever
+manner was used to create obj.
+new_obj will have all of its own parameters - position,
+rotation, color, texture, etc...
+However, these parameters will be instantiated with the corresponding
+values from obj at the time of cloning.
+One should call
+new_obj:setPosition()
+in order to place new_obj somewhere where it is not
+intersecting with other objects in order to pacify the physics engine.
+

+
+
+
destroy

+
obj:destroy()

+

+This function destroys the object in the engine.
+obj should not be used after this method is called.
+

+
+
+
draw

+
obj:draw()

+

+This function will draw obj to the screen.
+It is called automatically by ag.drawObjects(),
+so calling it is only required if the "AutoDrawObjects" mode
+is disabled, and ag.drawObjects() is not called.
+

+
+
+
getMass

+
mass = obj:getMass()

+

+This function returns the mass of obj.
+

+
+
+
getPosition

+
x, y, z = obj:getPosition()

+

+This function returns the coordinates (x, y, z) of the object.
+Normally, the center-of-mass of the object is located at its
+local origin.
+The coordinates of the object's local origin are returned by
+this call, so these coordinates will be the coordinates of the
+object's center-of-mass.
+

+
+
+
setColor

+
obj:setColor(r, g, b)

+

+This function sets the color of the object.
+The parameters correspond to the red, green, and blue components
+of the object color.
+Each component should be between 0.0 and 1.0.
+

+
+
+
setMass

+
obj:setMass(new_mass)

+

+This function sets the mass of obj to new_mass.
+

 
 
-
obj:setPosition(x, y, z)

+
setPosition

+
obj:setPosition(x, y, z)

+

+This function sets the coordinates for the object's
+center-of-mass (local origin) to (x, y, z).
+

+
+
+
setRotation

+
obj:setRotation(xr, yr, zr)

+

+This function sets the object's rotation to that specified
+by Euler angles (xr, yr, zr).
+

+
+
+
setTexture

+
obj:setTexture(tex)

+

+This function sets the texture of obj to tex.
+tex is a Lua reference to a texture loaded with
+ag.loadTexture().
+

+
+
+
setVisible

+
obj:setVisible(visible_flag)

+

+This function sets the visibility of obj to visible_flag.
+If visible_flag is true, then the object will be drawn.
+

+
+

+
+
+
std library