updated documentation - added handler / callback prototype section, added key names section; added ag::drawArc() and ag::drawCircle() w/ documentation; added tests/transparent.png and tests/imagetest.lua; renamed init() event to init_event(); re-added missing drawImage Lua hook; changed images to draw transparent parts correctly through to background
git-svn-id: svn://anubis/anaglym/trunk@197 99a6e188-d820-4881-8870-2d33a10e2619
This commit is contained in:
Josh Holtrop committed
1 parent
8ea89aea33
commit
b546ea74dd
14 files changed
+493
-67
No files matched your search
+337
-28
@@ -29,6 +29,8 @@ The library functions are documented below.
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#std"><tt>std</tt> library</a></li>
|
||||
<li><a href="#handlers">Lua Event Handlers</a></li>
|
||||
<li><a href="#key_names">Key Names</a></li>
|
||||
</ul>
|
||||
|
||||
<hr />
|
||||
@@ -42,16 +44,8 @@ The library functions are documented below.
|
||||
<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>
|
||||
<tt>event_name</tt> should be a string containing an event name.
|
||||
See <a href="#handlers">Lua event handlers</a> for a list of events.
|
||||
</p>
|
||||
|
||||
<a name="ag_doPhysics" />
|
||||
@@ -64,6 +58,48 @@ mode is enabled; this mode is enabled by default.
|
||||
See <a href="#ag_setAutoPhysics">setAutoPhysics</a> for more information.
|
||||
</p>
|
||||
|
||||
<a name="ag_drawArc" />
|
||||
<h3>drawArc</h3>
|
||||
<p><tt>ag.drawArc(r, g, b, x, y, radius, a1, a2)</tt></p>
|
||||
<p>
|
||||
This function tells the engine to draw an arc to the screen.
|
||||
The color of the arc is specified by (r, g, b).
|
||||
<tt>x</tt> and <tt>y</tt> specify the coordinates of the center
|
||||
of the arc.
|
||||
The arc ranges from angle <tt>a1</tt> to <tt>a2</tt>, which are
|
||||
specified in degrees, going counter-clockwise from the East.
|
||||
<tt>drawArc()</tt> should normally be called from the
|
||||
<tt>update_overlay</tt> event handler.
|
||||
</p>
|
||||
|
||||
<a name="ag_drawCircle" />
|
||||
<h3>drawCircle</h3>
|
||||
<p><tt>ag.drawCircle(r, g, b, x, y, radius)</tt></p>
|
||||
<p>
|
||||
This function tells the engine to draw a circle to the screen.
|
||||
The color of the circle is specified by (r, g, b).
|
||||
<tt>x</tt> and <tt>y</tt> specify the coordinates of the center
|
||||
of the circle.
|
||||
<tt>drawCircle()</tt> should normally be called from the
|
||||
<tt>update_overlay</tt> event handler.
|
||||
</p>
|
||||
|
||||
<a name="ag_drawImage" />
|
||||
<h3>drawImage</h3>
|
||||
<p><tt>ag.drawImage(width, height, x, y, texture, [, rot])</tt></p>
|
||||
<p>
|
||||
This function tells the engine to draw an image to the screen.
|
||||
<tt>width</tt> and <tt>height</tt> specify the size of the image,
|
||||
in pixels.
|
||||
<tt>x</tt> and <tt>y</tt> specify the coordinates of the center
|
||||
of the image.
|
||||
The image to be drawn is specified by <tt>texture</tt>, which
|
||||
should be loaded by
|
||||
<a href="#ag_loadTexture"><tt>ag.loadTexture()</tt></a>.
|
||||
<tt>drawImage()</tt> should normally be called from the
|
||||
<tt>update_overlay</tt> event handler.
|
||||
</p>
|
||||
|
||||
<a name="ag_drawLine" />
|
||||
<h3>drawLine</h3>
|
||||
<p><tt>ag.drawLine(r, g, b, x1, y1, x2, y2 [, width])</tt></p>
|
||||
@@ -206,7 +242,7 @@ libraries such as <a href="#std">std</a>.
|
||||
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.
|
||||
See <a href="#key_names">Key Names</a> for key names.
|
||||
</p>
|
||||
|
||||
<a name="ag_loadModel" />
|
||||
@@ -280,16 +316,8 @@ 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>
|
||||
<tt>event_name</tt> should be a string containing the name of the event.
|
||||
See <a href="#handlers">Lua event handlers</a> for a list of event names.
|
||||
</p>
|
||||
<p>
|
||||
When the Lua script is initially loaded, any functions found
|
||||
@@ -624,6 +652,16 @@ ag.import("std")
|
||||
</pre>
|
||||
</p>
|
||||
|
||||
<a name="std_createPlanePointNormal" />
|
||||
<h3>createPlanePointNormal</h3>
|
||||
<p><tt>obj = std.createPlanePointNormal(x, y, z, nx, ny, nz)</tt></p>
|
||||
<p>
|
||||
This function simply wraps
|
||||
<a href="#ag_createPlane"><tt>ag.createPlane()</tt></a>
|
||||
allowing the user to specify a point on the plane with coordinates (x, y, z)
|
||||
and the surface normal of the plane (nx, ny, nz).
|
||||
</p>
|
||||
|
||||
<a name="std_crossProduct" />
|
||||
<h3>crossProduct</h3>
|
||||
<p><tt>cp = std.crossProduct(vec1, vec2)</tt></p>
|
||||
@@ -648,15 +686,286 @@ The indices of <tt>vec1</tt> and <tt>vec2</tt> should be from 1 to 3.
|
||||
This allows specifying a Lua array directly as a parameter to the function.
|
||||
</p>
|
||||
|
||||
<a name="std_createPlanePointNormal" />
|
||||
<h3>createPlanePointNormal</h3>
|
||||
<p><tt>obj = std.createPlanePointNormal(x, y, z, nx, ny, nz)</tt></p>
|
||||
<a name="std_pctx" />
|
||||
<h3>pctx</h3>
|
||||
<p><tt>pixels_x = std.pctx(percent)</tt></p>
|
||||
<p>
|
||||
This function simply wraps
|
||||
<a href="#ag_createPlane"><tt>ag.createPlane()</tt></a>
|
||||
allowing the user to specify a point on the plane with coordinates (x, y, z)
|
||||
and the surface normal of the plane (nx, ny, nz).
|
||||
This function returns the number of pixels corresponding to
|
||||
<tt>percent</tt> percent of the screen's X axis.
|
||||
<tt>percent</tt> should be between 0.0 and 1.0.
|
||||
</p>
|
||||
|
||||
<a name="std_pcty" />
|
||||
<h3>pcty</h3>
|
||||
<p><tt>pixels_y = std.pcty(percent)</tt></p>
|
||||
<p>
|
||||
This function returns the number of pixels corresponding to
|
||||
<tt>percent</tt> percent of the screen's Y axis.
|
||||
<tt>percent</tt> should be between 0.0 and 1.0.
|
||||
</p>
|
||||
|
||||
|
||||
<hr />
|
||||
|
||||
<a name="handlers" />
|
||||
<h2>Lua Event Handlers</h2>
|
||||
|
||||
<p>
|
||||
The following is a list of all events that the Anaglym engine
|
||||
handles:
|
||||
<ul>
|
||||
<li><a href="#handler_update"><tt>update</tt></a></li>
|
||||
<li><a href="#handler_update_overlay"><tt>update_overlay</tt></a></li>
|
||||
<li><a href="#handler_key_down"><tt>key_down</tt></a></li>
|
||||
<li><a href="#handler_key_up"><tt>key_up</tt></a></li>
|
||||
<li><a href="#handler_mousebutton_down"><tt>mousebutton_down</tt></a></li>
|
||||
<li><a href="#handler_mousebutton_up"><tt>mousebutton_up</tt></a></li>
|
||||
<li><a href="#handler_mouse_motion"><tt>mouse_motion</tt></a></li>
|
||||
</ul>
|
||||
Lua callback functions may be registered for each of these events.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
When a Lua script is loaded, any defined function that matches the
|
||||
name of an engine event with "<tt>_event</tt>" appended will
|
||||
automatically be registered as a callback for that engine event.
|
||||
For example, a function named <tt>key_up_event()</tt> in
|
||||
a loaded Lua script will automatically be registered to receive
|
||||
<tt>key_up</tt> event notifications.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The prototypes for the Lua event handler callback functions follow.
|
||||
</p>
|
||||
|
||||
<a name="handler_update" />
|
||||
<h3>update</h3>
|
||||
<p><tt>function update_event()</tt></p>
|
||||
<p>
|
||||
This function is called for every frame that is drawn on the screen.
|
||||
It could be called up to a few dozen times per second.
|
||||
</p>
|
||||
|
||||
<a name="handler_update_overlay" />
|
||||
<h3>update_overlay</h3>
|
||||
<p><tt>function update_overlay_event(width, height)</tt></p>
|
||||
<p>
|
||||
This function is called immediately after the <tt>update</tt>
|
||||
function.
|
||||
During this event, the coordinate system is reset from the normal
|
||||
3D system to a 2D system.
|
||||
The coordinates range from (0, 0) in the lower-left corner of the
|
||||
screen to (width, height) in the upper-right corner of the screen.
|
||||
In this mode, depth testing is disabled, so any graphics drawn will
|
||||
"overlay" whatever is currently on the screen.
|
||||
<tt>width</tt> and <tt>height</tt> contain the size of the
|
||||
Anaglym engine window, in pixels.
|
||||
</p>
|
||||
|
||||
<a name="handler_key_down" />
|
||||
<h3>key_down</h3>
|
||||
<p><tt>function key_down_event(key_name)</tt></p>
|
||||
<p>
|
||||
This function is called when a key is initially pressed.
|
||||
<tt>key_name</tt> is a string containing the name of the
|
||||
key pressed.
|
||||
See <a href="#key_names">Key Names</a> for a list of key names.
|
||||
</p>
|
||||
|
||||
<a name="handler_key_up" />
|
||||
<h3>key_up</h3>
|
||||
<p><tt>function key_up_event(key_name)</tt></p>
|
||||
<p>
|
||||
This function is called when a key is released.
|
||||
<tt>key_name</tt> is a string containing the name of the
|
||||
key released.
|
||||
See <a href="#key_names">Key Names</a> for a list of key names.
|
||||
</p>
|
||||
|
||||
<a name="handler_mousebutton_down" />
|
||||
<h3>mousebutton_down</h3>
|
||||
<p><tt>function mousebutton_down_event(button, x, y)</tt></p>
|
||||
<p>
|
||||
This function is called when a mouse button is pressed.
|
||||
<tt>button</tt> contains the number of the button pressed
|
||||
(1: left, 2: middle, 3: right, 4: scroll wheel up, 5: scroll wheel down).
|
||||
The position of the cursor when the mouse button was pressed is at
|
||||
(x, y).
|
||||
This position is only meaningful when the cursor is shown.
|
||||
By default, it is hidden.
|
||||
Cursor visibility can be toggled with the F2 key.
|
||||
</p>
|
||||
|
||||
<a name="handler_mousebutton_up" />
|
||||
<h3>mousebutton_up</h3>
|
||||
<p><tt>function mousebutton_up_event(button, x, y)</tt></p>
|
||||
<p>
|
||||
This function is called when a mouse button is released.
|
||||
<tt>button</tt> contains the number of the button released
|
||||
(1: left, 2: middle, 3: right, 4: scroll wheel up, 5: scroll wheel down).
|
||||
The position of the cursor when the mouse button was released is at
|
||||
(x, y).
|
||||
This position is only meaningful when the cursor is shown.
|
||||
By default, it is hidden.
|
||||
Cursor visibility can be toggled with the F2 key.
|
||||
</p>
|
||||
|
||||
<a name="handler_mouse_motion" />
|
||||
<h3>mouse_motion</h3>
|
||||
<p><tt>function mouse_motion_event(x, y, xrel, yrel)</tt></p>
|
||||
<p>
|
||||
This function is called when the mouse moves.
|
||||
(x, y) specifies the position that the cursor was moved to.
|
||||
This position is only meaningful when the cursor is shown.
|
||||
<tt>xrel</tt> and <tt>yrel</tt> contain the relative
|
||||
movement distance.
|
||||
These values are meaningful regardless of the cursor visibility state.
|
||||
</p>
|
||||
|
||||
|
||||
<hr />
|
||||
|
||||
<a name="key_names" />
|
||||
<h2>Key Names</h2>
|
||||
|
||||
<ul>
|
||||
<li><tt>backspace</tt></li>
|
||||
<li><tt>tab</tt></li>
|
||||
<li><tt>clear</tt></li>
|
||||
<li><tt>return</tt></li>
|
||||
<li><tt>pause</tt></li>
|
||||
<li><tt>escape</tt></li>
|
||||
<li><tt>space</tt></li>
|
||||
<li><tt>exclaim</tt></li>
|
||||
<li><tt>quotedbl</tt></li>
|
||||
<li><tt>hash</tt></li>
|
||||
<li><tt>dollar</tt></li>
|
||||
<li><tt>ampersand</tt></li>
|
||||
<li><tt>quote</tt></li>
|
||||
<li><tt>leftparen</tt></li>
|
||||
<li><tt>rightparen</tt></li>
|
||||
<li><tt>asterisk</tt></li>
|
||||
<li><tt>plus</tt></li>
|
||||
<li><tt>comma</tt></li>
|
||||
<li><tt>minus</tt></li>
|
||||
<li><tt>period</tt></li>
|
||||
<li><tt>slash</tt></li>
|
||||
<li><tt>0</tt></li>
|
||||
<li><tt>1</tt></li>
|
||||
<li><tt>2</tt></li>
|
||||
<li><tt>3</tt></li>
|
||||
<li><tt>4</tt></li>
|
||||
<li><tt>5</tt></li>
|
||||
<li><tt>6</tt></li>
|
||||
<li><tt>7</tt></li>
|
||||
<li><tt>8</tt></li>
|
||||
<li><tt>9</tt></li>
|
||||
<li><tt>colon</tt></li>
|
||||
<li><tt>semicolon</tt></li>
|
||||
<li><tt>less</tt></li>
|
||||
<li><tt>equals</tt></li>
|
||||
<li><tt>greater</tt></li>
|
||||
<li><tt>question</tt></li>
|
||||
<li><tt>at</tt></li>
|
||||
<li><tt>leftbracket</tt></li>
|
||||
<li><tt>backslash</tt></li>
|
||||
<li><tt>rightbracket</tt></li>
|
||||
<li><tt>caret</tt></li>
|
||||
<li><tt>underscore</tt></li>
|
||||
<li><tt>backquote</tt></li>
|
||||
<li><tt>a</tt></li>
|
||||
<li><tt>b</tt></li>
|
||||
<li><tt>c</tt></li>
|
||||
<li><tt>d</tt></li>
|
||||
<li><tt>e</tt></li>
|
||||
<li><tt>f</tt></li>
|
||||
<li><tt>g</tt></li>
|
||||
<li><tt>h</tt></li>
|
||||
<li><tt>i</tt></li>
|
||||
<li><tt>j</tt></li>
|
||||
<li><tt>k</tt></li>
|
||||
<li><tt>l</tt></li>
|
||||
<li><tt>m</tt></li>
|
||||
<li><tt>n</tt></li>
|
||||
<li><tt>o</tt></li>
|
||||
<li><tt>p</tt></li>
|
||||
<li><tt>q</tt></li>
|
||||
<li><tt>r</tt></li>
|
||||
<li><tt>s</tt></li>
|
||||
<li><tt>t</tt></li>
|
||||
<li><tt>u</tt></li>
|
||||
<li><tt>v</tt></li>
|
||||
<li><tt>w</tt></li>
|
||||
<li><tt>x</tt></li>
|
||||
<li><tt>y</tt></li>
|
||||
<li><tt>z</tt></li>
|
||||
<li><tt>delete</tt></li>
|
||||
<li><tt>kp0</tt></li>
|
||||
<li><tt>kp1</tt></li>
|
||||
<li><tt>kp2</tt></li>
|
||||
<li><tt>kp3</tt></li>
|
||||
<li><tt>kp4</tt></li>
|
||||
<li><tt>kp5</tt></li>
|
||||
<li><tt>kp6</tt></li>
|
||||
<li><tt>kp7</tt></li>
|
||||
<li><tt>kp8</tt></li>
|
||||
<li><tt>kp9</tt></li>
|
||||
<li><tt>kp_period</tt></li>
|
||||
<li><tt>kp_divide</tt></li>
|
||||
<li><tt>kp_multiply</tt></li>
|
||||
<li><tt>kp_minus</tt></li>
|
||||
<li><tt>kp_plus</tt></li>
|
||||
<li><tt>kp_enter</tt></li>
|
||||
<li><tt>kp_equals</tt></li>
|
||||
<li><tt>up</tt></li>
|
||||
<li><tt>down</tt></li>
|
||||
<li><tt>right</tt></li>
|
||||
<li><tt>left</tt></li>
|
||||
<li><tt>insert</tt></li>
|
||||
<li><tt>home</tt></li>
|
||||
<li><tt>end</tt></li>
|
||||
<li><tt>pageup</tt></li>
|
||||
<li><tt>pagedown</tt></li>
|
||||
<li><tt>f1</tt></li>
|
||||
<li><tt>f2</tt></li>
|
||||
<li><tt>f3</tt></li>
|
||||
<li><tt>f4</tt></li>
|
||||
<li><tt>f5</tt></li>
|
||||
<li><tt>f6</tt></li>
|
||||
<li><tt>f7</tt></li>
|
||||
<li><tt>f8</tt></li>
|
||||
<li><tt>f9</tt></li>
|
||||
<li><tt>f10</tt></li>
|
||||
<li><tt>f11</tt></li>
|
||||
<li><tt>f12</tt></li>
|
||||
<li><tt>f13</tt></li>
|
||||
<li><tt>f14</tt></li>
|
||||
<li><tt>f15</tt></li>
|
||||
<li><tt>numlock</tt></li>
|
||||
<li><tt>capslock</tt></li>
|
||||
<li><tt>scrollock</tt></li>
|
||||
<li><tt>rshift</tt></li>
|
||||
<li><tt>lshift</tt></li>
|
||||
<li><tt>rctrl</tt></li>
|
||||
<li><tt>lctrl</tt></li>
|
||||
<li><tt>ralt</tt></li>
|
||||
<li><tt>lalt</tt></li>
|
||||
<li><tt>rmeta</tt></li>
|
||||
<li><tt>lmeta</tt></li>
|
||||
<li><tt>lsuper</tt></li>
|
||||
<li><tt>rsuper</tt></li>
|
||||
<li><tt>mode</tt></li>
|
||||
<li><tt>compose</tt></li>
|
||||
<li><tt>help</tt></li>
|
||||
<li><tt>print</tt></li>
|
||||
<li><tt>sysreq</tt></li>
|
||||
<li><tt>break</tt></li>
|
||||
<li><tt>menu</tt></li>
|
||||
<li><tt>power</tt></li>
|
||||
<li><tt>euro</tt></li>
|
||||
<li><tt>undo</tt></li>
|
||||
<li><tt>last</tt></li>
|
||||
</ul>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in new issue
Block a user