Fixed some little errors with the drawing functions.
[luagame.git] / doc / fun_ref.html
blob4d9e625b071e8e9c1963074714644b26f7859340
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <meta name="generator" content="AsciiDoc 8.2.1" />
7 <style type="text/css">
8 /* Debug borders */
9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11 border: 1px solid red;
15 body {
16 margin: 1em 5% 1em 5%;
19 a {
20 color: blue;
21 text-decoration: underline;
23 a:visited {
24 color: fuchsia;
27 em {
28 font-style: italic;
31 strong {
32 font-weight: bold;
35 tt {
36 color: navy;
39 h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
47 h1 {
48 border-bottom: 2px solid silver;
50 h2 {
51 border-bottom: 2px solid silver;
52 padding-top: 0.5em;
55 div.sectionbody {
56 font-family: serif;
57 margin-left: 0;
60 hr {
61 border: 1px solid silver;
64 p {
65 margin-top: 0.5em;
66 margin-bottom: 0.5em;
69 pre {
70 padding: 0;
71 margin: 0;
74 span#author {
75 color: #527bbd;
76 font-family: sans-serif;
77 font-weight: bold;
78 font-size: 1.1em;
80 span#email {
82 span#revision {
83 font-family: sans-serif;
86 div#footer {
87 font-family: sans-serif;
88 font-size: small;
89 border-top: 2px solid silver;
90 padding-top: 0.5em;
91 margin-top: 4.0em;
93 div#footer-text {
94 float: left;
95 padding-bottom: 0.5em;
97 div#footer-badges {
98 float: right;
99 padding-bottom: 0.5em;
102 div#preamble,
103 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
104 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
105 div.admonitionblock {
106 margin-right: 10%;
107 margin-top: 1.5em;
108 margin-bottom: 1.5em;
110 div.admonitionblock {
111 margin-top: 2.5em;
112 margin-bottom: 2.5em;
115 div.content { /* Block element content. */
116 padding: 0;
119 /* Block element titles. */
120 div.title, caption.title {
121 font-family: sans-serif;
122 font-weight: bold;
123 text-align: left;
124 margin-top: 1.0em;
125 margin-bottom: 0.5em;
127 div.title + * {
128 margin-top: 0;
131 td div.title:first-child {
132 margin-top: 0.0em;
134 div.content div.title:first-child {
135 margin-top: 0.0em;
137 div.content + div.title {
138 margin-top: 0.0em;
141 div.sidebarblock > div.content {
142 background: #ffffee;
143 border: 1px solid silver;
144 padding: 0.5em;
147 div.listingblock {
148 margin-right: 0%;
150 div.listingblock > div.content {
151 border: 1px solid silver;
152 background: #f4f4f4;
153 padding: 0.5em;
156 div.quoteblock > div.content {
157 padding-left: 2.0em;
160 div.attribution {
161 text-align: right;
163 div.verseblock + div.attribution {
164 text-align: left;
167 div.admonitionblock .icon {
168 vertical-align: top;
169 font-size: 1.1em;
170 font-weight: bold;
171 text-decoration: underline;
172 color: #527bbd;
173 padding-right: 0.5em;
175 div.admonitionblock td.content {
176 padding-left: 0.5em;
177 border-left: 2px solid silver;
180 div.exampleblock > div.content {
181 border-left: 2px solid silver;
182 padding: 0.5em;
185 div.verseblock div.content {
186 white-space: pre;
189 div.imageblock div.content { padding-left: 0; }
190 div.imageblock img { border: 1px solid silver; }
191 span.image img { border-style: none; }
193 dl {
194 margin-top: 0.8em;
195 margin-bottom: 0.8em;
197 dt {
198 margin-top: 0.5em;
199 margin-bottom: 0;
200 font-style: italic;
202 dd > *:first-child {
203 margin-top: 0;
206 ul, ol {
207 list-style-position: outside;
209 ol.olist2 {
210 list-style-type: lower-alpha;
213 div.tableblock > table {
214 border: 3px solid #527bbd;
216 thead {
217 font-family: sans-serif;
218 font-weight: bold;
220 tfoot {
221 font-weight: bold;
224 div.hlist {
225 margin-top: 0.8em;
226 margin-bottom: 0.8em;
228 div.hlist td {
229 padding-bottom: 5px;
231 td.hlist1 {
232 vertical-align: top;
233 font-style: italic;
234 padding-right: 0.8em;
236 td.hlist2 {
237 vertical-align: top;
240 @media print {
241 div#footer-badges { display: none; }
244 div#toctitle {
245 color: #527bbd;
246 font-family: sans-serif;
247 font-size: 1.1em;
248 font-weight: bold;
249 margin-top: 1.0em;
250 margin-bottom: 0.1em;
253 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
254 margin-top: 0;
255 margin-bottom: 0;
257 div.toclevel2 {
258 margin-left: 2em;
259 font-size: 0.9em;
261 div.toclevel3 {
262 margin-left: 4em;
263 font-size: 0.9em;
265 div.toclevel4 {
266 margin-left: 6em;
267 font-size: 0.9em;
269 /* Workarounds for IE6's broken and incomplete CSS2. */
271 div.sidebar-content {
272 background: #ffffee;
273 border: 1px solid silver;
274 padding: 0.5em;
276 div.sidebar-title, div.image-title {
277 font-family: sans-serif;
278 font-weight: bold;
279 margin-top: 0.0em;
280 margin-bottom: 0.5em;
283 div.listingblock div.content {
284 border: 1px solid silver;
285 background: #f4f4f4;
286 padding: 0.5em;
289 div.quoteblock-content {
290 padding-left: 2.0em;
293 div.exampleblock-content {
294 border-left: 2px solid silver;
295 padding-left: 0.5em;
298 /* IE6 sets dynamically generated links as visited. */
299 div#toc a:visited { color: blue; }
300 </style>
301 <script type="text/javascript">
302 /*<![CDATA[*/
303 window.onload = function(){generateToc(2)}
304 /* Author: Mihai Bazon, September 2002
305 * http://students.infoiasi.ro/~mishoo
307 * Table Of Content generator
308 * Version: 0.4
310 * Feel free to use this script under the terms of the GNU General Public
311 * License, as long as you do not remove or alter this notice.
314 /* modified by Troy D. Hanson, September 2006. License: GPL */
315 /* modified by Stuart Rackham, October 2006. License: GPL */
317 function getText(el) {
318 var text = "";
319 for (var i = el.firstChild; i != null; i = i.nextSibling) {
320 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
321 text += i.data;
322 else if (i.firstChild != null)
323 text += getText(i);
325 return text;
328 function TocEntry(el, text, toclevel) {
329 this.element = el;
330 this.text = text;
331 this.toclevel = toclevel;
334 function tocEntries(el, toclevels) {
335 var result = new Array;
336 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
337 // Function that scans the DOM tree for header elements (the DOM2
338 // nodeIterator API would be a better technique but not supported by all
339 // browsers).
340 var iterate = function (el) {
341 for (var i = el.firstChild; i != null; i = i.nextSibling) {
342 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
343 var mo = re.exec(i.tagName)
344 if (mo)
345 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
346 iterate(i);
350 iterate(el);
351 return result;
354 // This function does the work. toclevels = 1..4.
355 function generateToc(toclevels) {
356 var toc = document.getElementById("toc");
357 var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
358 for (var i = 0; i < entries.length; ++i) {
359 var entry = entries[i];
360 if (entry.element.id == "")
361 entry.element.id = "toc" + i;
362 var a = document.createElement("a");
363 a.href = "#" + entry.element.id;
364 a.appendChild(document.createTextNode(entry.text));
365 var div = document.createElement("div");
366 div.appendChild(a);
367 div.className = "toclevel" + entry.toclevel;
368 toc.appendChild(div);
371 /*]]>*/
372 </script>
373 <title>LuaGame Function Reference</title>
374 </head>
375 <body>
376 <div id="header">
377 <h1>LuaGame Function Reference</h1>
378 <div id="toc">
379 <div id="toctitle">Table of Contents</div>
380 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
381 </div>
382 </div>
383 <h2>1. Conventions</h2>
384 <div class="sectionbody">
385 <p>Arguments and return values are formatted: <strong>name&lt;type&gt;</strong>.</p>
386 <p>A return value of <strong>&lt;varying&gt;</strong> means that the function can
387 return a variable number of arguments. This will usually
388 be explained in the description of the function.</p>
389 </div>
390 <h2>2. Video</h2>
391 <div class="sectionbody">
392 <h3>2.1. image&lt;SDL_Surface*&gt; get_image(path&lt;string&gt;)</h3>
393 <p>Returns an SDL_Surface* to the image referenced by <strong>path</strong>.
394 If image has not been loaded before, it is loaded. If it has,
395 the pointer is returned.</p>
396 <h3>2.2. release_image(path&lt;string&gt;)</h3>
397 <p>Causes a loaded image to be freed from memory.
398 This is especially useful if one loads an image that is
399 only used for a small portion of the game because normally, an image
400 will stay loaded in memory forever.</p>
401 <h3>2.3. update_screen()</h3>
402 <p>Causes the screen surface in video memory to be updated from
403 the backbuffer or surface in main memory. This is basically
404 a call to <em>SDL_Flip()</em>.</p>
405 <h3>2.4. blit(image&lt;SDL_Surface*&gt;, x&lt;int&gt;, y&lt;int&gt;, rotation&lt;double&gt;, reposition&lt;bool&gt;, smoothing&lt;bool&gt;)</h3>
406 <p>Blits <strong>image</strong> to the screen at position <strong>(x, y)</strong>. If <strong>rotation</strong> is non-zero, the image will be rotated on the fly.
407 If <strong>reposition</strong> is true, the rotated image will be re-centered (you probably want this). <strong>Smoothing</strong> is whether or
408 not linear interpolation should be used (looks pretty but eats CPU).</p>
409 <h3>2.5. blit_frame(image&lt;SDL_Surface*&gt;, x&lt;int&gt;, y&lt;int&gt;, frames&lt;int&gt;, frame_num&lt;int&gt;)</h3>
410 <p>Blits frame <strong>frame_num</strong> to the screen at position <strong>(x, y)</strong> from <strong>image</strong> with <strong>frames</strong> number of frames.</p>
411 <h3>2.6. show_cursor(show&lt;bool&gt;)</h3>
412 <p>Turns on/off the display of the cursor.</p>
413 <h3>2.7. fill_screen(R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;)</h3>
414 <p>Fills the screen with the color specified by the rgb triplet <strong>(R,G,B)</strong>.</p>
415 <h3>2.8. delete_image(image&lt;SDL_Surface*&gt;)</h3>
416 <p>This effectively calls SDL_FreeSurface() on <strong>image</strong>. This function
417 should <em>never</em> be used on an image loaded using <em>get_image()</em>.</p>
418 <h3>2.9. rz_image&lt;SDL_Surface*&gt;, w&lt;int&gt;, h&lt;int&gt; rotzoom(image&lt;SDL_Surface*&gt;, angle&lt;double&gt;, zoom&lt;double&gt;, smooth&lt;bool&gt;)</h3>
419 <p>Returns a rotated and/or zoomed version of <strong>image</strong> and also the width <strong>w</strong> and height <strong>h</strong> of the rotated/zoomed image.
420 <strong>Angle</strong> is specified in degrees. <strong>Zoom</strong> is the scaling factor. <strong>Smooth</strong> specifies whether linear interpolation
421 should be used when rotating/zooming the surface. Smoothing is expensive and should be used with care.
422 Surfaces returned by this function should be freed after use using <em>delete_image()</em>.</p>
423 </div>
424 <h2>3. Misc</h2>
425 <div class="sectionbody">
426 <h3>3.1. ticks&lt;int&gt; get_ticks()</h3>
427 <p>Returns the number of milliseconds since program intialization. This value overflows after 49 days (32-bit integer).</p>
428 <h3>3.2. delay(time&lt;int&gt;)</h3>
429 <p>Waits for <strong>time</strong> milliseconds and then returns.</p>
430 </div>
431 <h2>4. Input</h2>
432 <div class="sectionbody">
433 <h3>4.1. x&lt;int&gt;, y&lt;int&gt;, left&lt;bool&gt;, right&lt;bool&gt; mouse_state()</h3>
434 <p>Returns the absolute position (within the window) of the cursor.
435 It also returns the state of the left and right mouse buttons.
436 This function can be used to get the state of the mouse even when
437 and event manager is in use.</p>
438 <h3>4.2. num&lt;int&gt; num_joysticks()</h3>
439 <p>Returns the number of joysticks currently attached to the system.</p>
440 <h3>4.3. &lt;varying&gt; get_event()</h3>
441 <p>This function is used by the event manager to pass events
442 from SDL to Lua. It should never need to be explicitly
443 called by the programmer. It returns a varying number of
444 results.</p>
445 </div>
446 <h2>5. Sound</h2>
447 <div class="sectionbody">
448 <h3>5.1. sample&lt;Mix_Chunk*&gt; load_sample(path&lt;string&gt;)</h3>
449 <p>Loads a sample, specified by <strong>path</strong>, and returns a pointer to it.</p>
450 <h3>5.2. unload_sample(path&lt;string&gt;)</h3>
451 <p>Unloads a previously loaded sample specified by <strong>path</strong>.</p>
452 <h3>5.3. play_sample(sample&lt;Mix_Chunk*&gt;)</h3>
453 <p>Plays the sample specified by <strong>sample</strong>. The sample will play until completion.
454 Sample needs to have been previously loaded using load_sample().</p>
455 <h3>5.4. clear_samples()</h3>
456 <p>Unloads all loaded samples from memory.</p>
457 <h3>5.5. stop_samples()</h3>
458 <p>Stops the playback of all currently playing samples.</p>
459 <h3>5.6. play_music(path&lt;string&gt;, loops&lt;int&gt;)</h3>
460 <p>Plays music specified by <strong>path</strong>. Music will play <strong>loops</strong> times. If <strong>loops</strong> is -1 then it will loop continuously until stopped.</p>
461 <h3>5.7. stop_music()</h3>
462 <p>Stops the currently playing music.</p>
463 </div>
464 <h2>6. Drawing</h2>
465 <div class="sectionbody">
466 <h3>6.1. draw_pixel(x&lt;int&gt;, y&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
467 <p>Draws a pixel of color <strong>rgb(R,G,B)</strong> at position <strong>(x,y)</strong>.</p>
468 <h3>6.2. draw_line(x1&lt;int&gt;, y1&lt;int&gt;, x2&lt;int&gt;, y2&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
469 <p>Draws a line of color <strong>rgb(R,G,B)</strong> from <strong>(x1,y1)</strong> to <strong>(x2,y2)</strong>.</p>
470 <h3>6.3. draw_rect(x1&lt;int&gt;, y1&lt;int&gt;, x2&lt;int&gt;, y2&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
471 <p>Draws a rectangle of color <strong>rgb(R,G,B)</strong> with top left corner <strong>(x1,y1)</strong> and bottom right corner <strong>(x2,y2)</strong>.</p>
472 <h3>6.4. draw_filled_rect(x1&lt;int&gt;, y1&lt;int&gt;, x2&lt;int&gt;, y2&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
473 <p>Draws a filled rectangle of color <strong>rgb(R,G,B)</strong> with top left corner <strong>(x1,y1)</strong> and bottom right corner <strong>(x2,y2)</strong>.</p>
474 <h3>6.5. draw_circle(x&lt;int&gt;, y&lt;int&gt;, rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
475 <p>Draws a circle of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong> and radius of <strong>rad</strong>.</p>
476 <h3>6.6. draw_filled_circle(x&lt;int&gt;, y&lt;int&gt;, rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
477 <p>Draws a filled circle of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong> and radius of <strong>rad</strong>.</p>
478 <h3>6.7. draw_ellipse(x&lt;int&gt;, y&lt;int&gt;, x_rad&lt;int&gt;, y_rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
479 <p>Draws an ellipse of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong>, x radius of <strong>x_rad</strong> and y radius of <strong>y_rad</strong>.</p>
480 <h3>6.8. draw_filled_ellipse(x&lt;int&gt;, y&lt;int&gt;, x_rad&lt;int&gt;, y_rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
481 <p>Draws a filled ellipse of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong>, x radius of <strong>x_rad</strong> and y radius of <strong>y_rad</strong>.</p>
482 </div>
483 <h2>7. Font</h2>
484 <div class="sectionbody">
485 <h3>7.1. font&lt;TTF_Font*&gt; load_font(path&lt;string&gt;, size&lt;int&gt;)</h3>
486 <p>Loads a font specified by <strong>path</strong> at size <strong>size</strong>.</p>
487 <h3>7.2. unload_font(font&lt;TTF_Font*&gt;)</h3>
488 <p>Unloads a font specified by <strong>font</strong>.</p>
489 <h3>7.3. w&lt;int&gt;, h&lt;int&gt; rendered_string_size(font&lt;TTF_Font*&gt;, text&lt;string&gt;)</h3>
490 <p>Returns the width <strong>w</strong> and height <strong>h</strong> of the string <strong>text</strong> as rendered in <strong>font</strong>.</p>
491 <h3>7.4. txt_image&lt;SDL_Surface*&gt; render_string(font&lt;TTF_Font*&gt;, text&lt;string&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;)</h3>
492 <p>Renders string <strong>text</strong> in the specified <strong>font</strong> and color <strong>rgb(R,G,B)</strong> and returns it as an SDL_Surface.</p>
493 </div>
494 <h2>8. Instrumentation</h2>
495 <div class="sectionbody">
496 <p>These functions are written in Lua, but they belong here more than anywhere else.</p>
497 <h3>8.1. instr_begin(id&lt;string&gt;)</h3>
498 <p>Begins tracking the time between this call and the end tracking call for <strong>id</strong>.
499 Also keeps track of how many times it has been called (good for profiling).</p>
500 <div class="admonitionblock">
501 <table><tr>
502 <td class="icon">
503 <img src="./images/icons/note.png" alt="Note" />
504 </td>
505 <td class="content">Calls for the same id cannot be nested. This would result in the timer being
506 reset for the id, which means that the statistics will be wrong. An error will be
507 thrown if this is attempted.</td>
508 </tr></table>
509 </div>
510 <h3>8.2. instr_end(id&lt;string&gt;)</h3>
511 <p>Ends tracking for <strong>id</strong> and adds the time between the begin call and this one to
512 the total execution time for <strong>id</strong>.</p>
513 <h3>8.3. instr_track(id&lt;string&gt;, val&lt;number&gt;)</h3>
514 <p>Adds an entry to the value tracking table for <strong>id</strong> of value <strong>val</strong>.</p>
515 <h3>8.4. instr_stats()</h3>
516 <p>Prints out in a nice formatted way (with colors) the statistics for the time
517 tracking and the value tracking.</p>
518 <h3>8.5. instr_log(msg&lt;string&gt;, &#8230;&lt;strings&gt;)</h3>
519 <p>Adds an entry, <strong>msg</strong>, to the log, recording the time since start of execution.
520 The varying argument at the end is a number of strings that specify message
521 classes. Message classes are optional.</p>
522 <h3>8.6. instr_print_log(&#8230;&lt;strings&gt;)</h3>
523 <p>Prints out the log entries that match all specified classes. If no classes are
524 specified then it prints out all messages. Prints in ascending order of time recorded.</p>
525 </div>
526 <div id="footer">
527 <div id="footer-text">
528 Last updated 09-Jan-2008 19:32:58 EDT
529 </div>
530 </div>
531 </body>
532 </html>