347 lines
10 KiB
HTML
347 lines
10 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></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>update</li>
|
|
<li>update_overlay</li>
|
|
<li>key_down</li>
|
|
<li>key_up</li>
|
|
<li>mousebutton_down</li>
|
|
<li>mousebutton_up</li>
|
|
<li>mouse_motion</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.
|
|
</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="#model_setPosition">setPosition()</a> and
|
|
<a href="#model_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.
|
|
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>update</li>
|
|
<li>update_overlay</li>
|
|
<li>key_down</li>
|
|
<li>key_up</li>
|
|
<li>mousebutton_down</li>
|
|
<li>mousebutton_up</li>
|
|
<li>mouse_motion</li>
|
|
</ul>
|
|
</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.
|
|
</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.
|
|
</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 is 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.
|
|
</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.
|
|
</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="std" />
|
|
<h2><tt>std</tt> library</h2>
|
|
|
|
<hr />
|
|
|
|
<a name="object_creation" />
|
|
<h2>Object creation functions</h2>
|
|
|
|
<a name="ag_createBox" />
|
|
<h3><tt>createBox</tt></h3>
|
|
|
|
<a name="ag_createBoxStatic" />
|
|
<h3><tt>createBoxStatic</tt></h3>
|
|
|
|
<a name="ag_createCapsul" />
|
|
<h3><tt>createCapsule</tt></h3>
|
|
|
|
<a name="ag_createCapsuleStatic" />
|
|
<h3><tt>createCapsuleStatic</tt></h3>
|
|
|
|
<a name="ag_createCylinder" />
|
|
<h3><tt>createCylinder</tt></h3>
|
|
|
|
<a name="ag_createCylinderStatic" />
|
|
<h3><tt>createCylinderStatic</tt></h3>
|
|
|
|
<a name="ag_createPlane" />
|
|
<h3><tt>createPlane</tt></h3>
|
|
|
|
<a name="ag_createPlaneStatic" />
|
|
<h3><tt>createPlaneStatic</tt></h3>
|
|
|
|
<a name="ag_createSphere" />
|
|
<h3><tt>createSphere</tt></h3>
|
|
|
|
<a name="ag_createSphereStatic" />
|
|
<h3><tt>createSphereStatic</tt></h3>
|
|
|
|
<hr />
|
|
|
|
<a name="object" />
|
|
<h2>Object member functions</h2>
|
|
|
|
<a name="object_setPosition" />
|
|
<h3><tt>obj:setPosition(x, y, z)</tt></h3>
|
|
|
|
</body>
|
|
</html>
|