anaglym/doc/index.html
Josh Holtrop aaa0cda3a5 finished documentation for ag library
git-svn-id: svn://anubis/anaglym/trunk@193 99a6e188-d820-4881-8870-2d33a10e2619
2009-11-25 00:19:48 +00:00

572 lines
18 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Anaglym Documentation</title>
<style type="text/css">
</style>
</head>
<body>
<h1>Anaglym Documentation</h1>
<p>
Anaglym exposes a Lua library named <tt>ag</tt> which contains functions
for interfacing with the Engine.
In addition to the <tt>ag</tt> library, there is a <tt>std</tt> library
which contains a "standard library" of Lua functions that do not directly
interface with the Anaglym engine.
The library functions are documented below.
</p>
<ul>
<li>
<a href="#ag"><tt>ag</tt> library</a>
<ul>
<li><a href="#object_creation">object creation functions</a></li>
<li><a href="#object">object member methods</a></li>
</ul>
</li>
<li><a href="#std"><tt>std</tt> library</a></li>
</ul>
<hr />
<a name="ag" />
<h2><tt>ag</tt> library</h2>
<a name="ag_clearEventHandler" />
<h3>clearEventHandler</h3>
<p><tt>ag.clearEventHandler(event_name)</tt><p>
<p>
This function removes a Lua callback function from being associated
with the engine event specified.
<tt>event_name</tt> should be one of the following strings:
<ul>
<li><tt>"update"</tt></li>
<li><tt>"update_overlay"</tt></li>
<li><tt>"key_down"</tt></li>
<li><tt>"key_up"</tt></li>
<li><tt>"mousebutton_down"</tt></li>
<li><tt>"mousebutton_up"</tt></li>
<li><tt>"mouse_motion"</tt></li>
</ul>
</p>
<a name="ag_doPhysics" />
<h3>doPhysics</h3>
<p><tt>ag.doPhysics()</tt></p>
<p>
This function invokes the physics processing part of the engine.
It is invoked automatically every update step if the "AutoPhysics"
mode is enabled; this mode is enabled by default.
See <a href="#ag_setAutoPhysics">setAutoPhysics</a> for more information.
</p>
<a name="ag_drawObjects" />
<h3>drawObjects</h3>
<p><tt>ag.drawObjects()</tt></p>
<p>
This function instructs the engine to draw all visible objects.
It is invoked automatically every update step if the "AutoDrawObjects"
mode is enabled; this mode is enabled by default.
See <a href="#ag_setAutoDrawObjects">setAutoDrawObjects</a>
for more information.
</p>
<a name="ag_elapsedTime" />
<h3>elapsedTime</h3>
<p><tt>elapsed_msec = ag.elapsedTime()</tt></p>
<p>
This function returns the number of milliseconds that have elapsed
since the beginning of the program.
</p>
<a name="ag_endFrame" />
<h3>endFrame</h3>
<p><tt>ag.endFrame()</tt></p>
<p>
This function signals the engine that all drawing is complete for the
current update frame.
It is invoked automatically if the "AutoEndFrame" mode is enabled;
this mode is enabled by default.
See <a href="#ag_setAutoEndFrame">setAutoEndFrame</a> for more
information.
</p>
<a name="ag_exit" />
<h3>exit</h3>
<p><tt>ag.exit()</tt></p>
<p>
This function instructs the engine to exit.
Internally, this function enqueues an "exit" event on the event
queue to be processed by the engine.
This means that Lua code following the call to <tt>exit()</tt>
will be executed and callbacks to other events may still be called.
The engine should exit within one update step.
</p>
<a name="ag_getCamera" />
<h3>getCamera</h3>
<p><tt>eye_x, eye_y, eye_z, center_x, center_y, center_z, up_x, up_y, up_z = ag.getCamera()</tt></p>
<p>
This function returns the camera position (eye coordinates),
focus position (center coordinates), and up vector for the current
camera settings.
</p>
<a name="ag_getScreenSize" />
<h3>getScreenSize</h3>
<p><tt>width, height = ag.getScreenSize()</tt></p>
<p>
This function returns the dimensions of the engine window, in pixels.
</p>
<a name="ag_import" />
<h3>import</h3>
<p><tt>ag.import(lua_source_name)</tt></p>
<p>
This function instructs the engine to import a Lua source file named
<tt>lua_source_name</tt>, which should be a string specifying the
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 <tt>import()</tt> function can be used to load Lua code that
is broken into separate source files, and to load
libraries such as <a href="#std">std</a>.
</p>
<a name="ag_isKeyDown" />
<h3>isKeyDown</h3>
<p><tt>result = ag.isKeyDown(key)</tt></p>
<p>
This function returns a boolean value for whether or not the key
given by <tt>key</tt> is currently pressed or not.
<tt>key</tt> should be a string corresponding to a key name.
See <a href="#keys">keys</a> for key names.
</p>
<a name="ag_loadModel" />
<h3>loadModel</h3>
<p><tt>object = ag.loadModel(model_name [, scale])</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.
<tt>model_name</tt> should be a string specifying the base name of
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
the exception that the object loaded is created as a static object.
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.
</p>
<a name="ag_loadTexture" />
<h3>loadTexture</h3>
<p><tt>texture = ag.loadTexture(texture_name)</tt></p>
<p>
This function loads a texture file from the file system and returns
a Lua reference to the loaded texture.
<tt>nil</tt> is returned if loading the texture fails.
The <tt>texture_name</tt> should contain the file extension, since
multiple formats are supported (.jpg, .png, .bmp, etc...).
Textures are searched for relative to the folder containing the
hosted script first, then relative to the engine library folder.
</p>
<a name="ag_print" />
<h3>print</h3>
<p><tt>ag.print(args...)</tt></p>
<p>
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:
<pre>local x, y, z = my_obj:getPosition()
ag.print("my_obj position: (", x, ", ", y, ", ", z, ")")
</pre>
</p>
<a name="ag_println" />
<h3>println</h3>
<p><tt>ag.println(args...)</tt></p>
<p>
Identical to <tt>print()</tt> but automatically prints a newline ("\n")
after printing the arguments.
</p>
<a name="ag_registerEventHandler" />
<h3>registerEventHandler</h3>
<p><tt>ag.registerEventHandler(event_name, handler)</tt></p>
<p>
This function registers a Lua callback function (<tt>handler</tt>)
to be called when the engine event specified by <tt>event_name</tt>
occurs.
There can be only one registered handler per event, so if a previous
Lua function was registered for <tt>event_name</tt>, it will be
overwritten to call the new handler.
<tt>event_name</tt> should be one of:
<ul>
<li><tt>"update"</tt></li>
<li><tt>"update_overlay"</tt></li>
<li><tt>"key_down"</tt></li>
<li><tt>"key_up"</tt></li>
<li><tt>"mousebutton_down"</tt></li>
<li><tt>"mousebutton_up"</tt></li>
<li><tt>"mouse_motion"</tt></li>
</ul>
</p>
<p>
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.
</p>
<a name="ag_setAutoDrawObjects" />
<h3>setAutoDrawObjects</h3>
<p><tt>ag.setAutoDrawObjects(enable_flag)</tt></p>
<p>
This function sets the "AutoDrawObjects" mode.
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
If AutoDrawObjects mode is enabled, then all visible objects in the
engine will be drawn automatically every update step.
If it is not enabled, one can call
<a href="#ag_drawObjects"><tt>ag.drawObjects()</tt></a>
to draw all visible objects in the scene.
The AutoDrawObjects mode is initially enabled.
</p>
<a name="ag_setAutoEndFrame" />
<h3>setAutoEndFrame</h3>
<p><tt>ag.setAutoEndFrame(enable_flag)</tt></p>
<p>
This function sets the "AutoEndFrame" mode.
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
If AutoEndFrame mode is enabled, then
<a href="#ag_endFrame"><tt>ag.endFrame()</tt></a>
will be invoked automatically after executing the update
and update_overlay Lua callback functions.
The AutoEndFrame mode is initially enabled.
</p>
<a name="ag_setAutoPhysics" />
<h3>setAutoPhysics</h3>
<p><tt>ag.setAutoPhysics(enable_flag)</tt></p>
<p>
This function sets the "AutoPhysics" mode.
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
If AutoPhysics mode is enabled, then collision detection and
physics processing are performed automatically on every update step.
If it is not enabled, one can call
<a href="#ag_doPhysics"><tt>ag.doPhysics()</tt></a>
to perform physics updates.
The AutoPhysics mode is initially enabled.
</p>
<a name="ag_setAutoStartFrame" />
<h3>setAutoStartFrame</h3>
<p><tt>ag.setAutoStartFrame(enable_flag)</tt></p>
<p>
This function sets the "AutoStartFrame" mode.
<tt>enable_flag</tt> should be <tt>true</tt> or <tt>false</tt>.
If AutoStartFrame mode is enabled, then
<a href="#ag_startFrame"><tt>ag.startFrame()</tt></a>
will be invoked automatically prior to executing the update and
update_overlay Lua callback functions.
The AutoStartFrame mode is initially enabled.
</p>
<a name="ag_setCamera" />
<h3>setCamera</h3>
<p><tt>ag.setCamera(eye_x, eye_y, eye_z [, center_x, center_y, center_z [, up_x, up_y, up_z] ])</tt></p>
<p>
This function sets the camera position (eye coordinates), focus point
(center coordinates), and up vector.
If the center coordinates or up vector are not specified, their values
are unchanged from the previous invocation of <tt>setCamera()</tt>.
The default center point is (0, 0, 0).
The default up vector is (0, 0, 1).
</p>
<a name="ag_startFrame" />
<h3>startFrame</h3>
<p><tt>ag.startFrame()</tt></p>
<p>
This function instructs the engine to begin drawing a frame.
It is not necessary to call this function if the "AutoStartFrame"
mode is enabled.
See <a href="#ag_setAutoStartFrame">ag.setAutoStartFrame()</a>.
</p>
<hr />
<a name="object_creation" />
<h2>Object creation functions</h2>
<p>
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
<a href="#object">object member functions</a>.
</p>
<a name="ag_createBox" />
<h3><tt>createBox</tt></h3>
<p><tt>obj = ag.createBox(width, depth, height)</tt></p>
<p>
This function creates a managed object which is a box with
dimensions given by (width, depth, height).
</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
object is static.
</p>
<a name="ag_createCapsul" />
<h3><tt>createCapsule</tt></h3>
<p><tt>obj = ag.createCapsule(radius, length)</tt></p>
<p>
This function creates a capsule managed object.
A capsule is like a cylinder, but has a half-sphere "capping"
each end of the cylinder.
<tt>radius</tt> specifies the radius of the cylinder (and caps).
<tt>length</tt> 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.
</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
object is static.
</p>
<a name="ag_createCylinder" />
<h3><tt>createCylinder</tt></h3>
<p><tt>obj = ag.createCylinder(radius, length)</tt></p>
<p>
This function creates a cylinder managed object.
<tt>radius</tt> specifies the radius of the cylinder.
<tt>length</tt> specifies the length of the cylinder.
The cylinder is oriented with its axis along the Z axis and its
center point at the origin.
</p>
<a name="ag_createCylinderStatic" />
<h3><tt>createCylinderStatic</tt></h3>
<p><tt>obj = ag.createCylinderStatic(radius, length)</tt></p>
<p>
Identical to <tt>ag.createCylinder()</tt> except that the created
object is static.
</p>
<a name="ag_createPlane" />
<h3><tt>createPlane</tt></h3>
<p>1) <tt>obj = ag.createPlane(a, b, c, d)</tt></p>
<p>2) <tt>obj = ag.createPlane(x, y, z, rot_x, rot_y, rot_z)</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
collisions (other objects can still bounce off them).
In the four-argument form, the plane is created with equation
<tt>ax + by + cz = d</tt>.
(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
<a href="#std_createPlanePtNormal">std.createPlanePtNormal()</a> function.
</p>
<a name="ag_createSphere" />
<h3><tt>createSphere</tt></h3>
<p><tt>obj = ag.createSphere(radius)</tt></p>
<p>
This function creates a managed sphere object with the radius given.
</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
object is static.
</p>
<hr />
<a name="object" />
<h2>Object member methods</h2>
<a name="object_addForce" />
<h3>addForce</h3>
<p><tt>obj:addForce(xf, yf, zf)</tt></p>
<p>
This function adds a one-time force to <tt>obj</tt>
with a force vector (xf, yf, zf).
</p>
<a name="object_addForceRel" />
<h3>addForceRel</h3>
<p><tt>obj:addForceRel</tt></p>
<p>
This function adds a one-time force to <tt>obj</tt>
with a force vector (xf, yf, zf) which is
relative to the local reference frame of <tt>obj</tt>.
</p>
<a name="object_addTorque" />
<h3>addTorque</h3>
<p><tt>obj:addTorque(xr, yr, zr)</tt></p>
<p>
This function adds torque (a rotational force) to <tt>obj</tt>.
The torque vector around global axes x, y, z is given by (xr, yr, zr).
</p>
<a name="object_addTorqueRel" />
<h3>addTorqueRel</h3>
<p><tt>obj:addTorqueRel(xr, yr, zr)</tt></p>
<p>
This function adds torque (a rotational force) to <tt>obj</tt>.
The torque vector around the local axes x, y, z of <tt>obj</tt>
is given by (xr, yr, zr).
</p>
<a name="object_clone" />
<h3>clone</h3>
<p><tt>new_obj = obj:clone()</tt></p>
<p>
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 <tt>obj</tt>.
<tt>new_obj</tt> will have all of its own parameters - position,
rotation, color, texture, etc...
However, these parameters will be instantiated with the corresponding
values from <tt>obj</tt> at the time of cloning.
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.
</p>
<a name="object_destroy" />
<h3>destroy</h3>
<p><tt>obj:destroy()</tt></p>
<p>
This function destroys the object in the engine.
<tt>obj</tt> should not be used after this method is called.
</p>
<a name="object_draw" />
<h3>draw</h3>
<p><tt>obj:draw()</tt></p>
<p>
This function will draw <tt>obj</tt> to the screen.
It is called automatically by <tt>ag.drawObjects()</tt>,
so calling it is only required if the "AutoDrawObjects" mode
is disabled, and <tt>ag.drawObjects()</tt> is not called.
</p>
<a name="object_getMass" />
<h3>getMass</h3>
<p><tt>mass = obj:getMass()</tt></p>
<p>
This function returns the mass of <tt>obj</tt>.
</p>
<a name="object_getPosition" />
<h3>getPosition</h3>
<p><tt>x, y, z = obj:getPosition()</tt></p>
<p>
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.
</p>
<a name="object_setColor" />
<h3>setColor</h3>
<p><tt>obj:setColor(r, g, b)</tt></p>
<p>
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.
</p>
<a name="object_setMass" />
<h3>setMass</h3>
<p><tt>obj:setMass(new_mass)</tt></p>
<p>
This function sets the mass of <tt>obj</tt> to <tt>new_mass</tt>.
</p>
<a name="object_setPosition" />
<h3>setPosition</h3>
<p><tt>obj:setPosition(x, y, z)</tt></p>
<p>
This function sets the coordinates for the object's
center-of-mass (local origin) to (x, y, z).
</p>
<a name="object_setRotation" />
<h3>setRotation</h3>
<p><tt>obj:setRotation(xr, yr, zr)</tt></p>
<p>
This function sets the object's rotation to that specified
by Euler angles (xr, yr, zr).
</p>
<a name="object_setTexture" />
<h3>setTexture</h3>
<p><tt>obj:setTexture(tex)</tt></p>
<p>
This function sets the texture of <tt>obj</tt> to <tt>tex</tt>.
<tt>tex</tt> is a Lua reference to a texture loaded with
<a href="#ag_loadTexture">ag.loadTexture()</a>.
</p>
<a name="object_setVisible" />
<h3>setVisible</h3>
<p><tt>obj:setVisible(visible_flag)</tt></p>
<p>
This function sets the visibility of <tt>obj</tt> to <tt>visible_flag</tt>.
If <tt>visible_flag</tt> is <tt>true</tt>, then the object will be drawn.
</p>
<hr />
<a name="std" />
<h2><tt>std</tt> library</h2>
</body>
</html>