doc/fun_ref.txt

   1 LuaGame Function Reference
   2 ==========================
   3
   4 == Conventions ==
   5 Arguments and return values are formatted: **name<type>**.
   6
   7 A return value of *<varying>* means that the function can
   8 return a variable number of arguments. This will usually
   9 be explained in the description of the function.
  10
  11
  12 == Video ==
  13 === image<GLSurface*> get_image(path<string>) ===
  14 Returns a GLSurface* to the image referenced by *path*.
  15 If image has not been loaded before, it is loaded. If it has,
  16 the pointer is returned.
  17
  18 === release_image(path<string>) ===
  19 Causes a loaded image to be freed from memory.
  20 This is especially useful if one loads an image that is
  21 only used for a small portion of the game because normally, an image
  22 will stay loaded in memory forever.
  23
  24 === update_screen() ===
  25 Causes the screen surface in video memory to be updated from
  26 the backbuffer or surface in main memory.
  27
  28 === display(image<GLSurface*>, x<int>, y<int>, rotation<double>, scale_x<double>, scale_y<double>, alpha<int>) ===
  29 Displays *image* on the screen at position *(x, y)*. If *rotation* is non-zero, the image will be rotated on the fly.
  30
  31 === display_frame(image<GLSurface*>, x<int>, y<int>, frames<int>, frame_num<int>, rotation<double>, scale_x<double>, scale_y<double>, alpha<int>) ===
  32 Displays frame *frame_num* on the screen at position *(x, y)* from *image* with *frames* number of frames.
  33
  34 === show_cursor(show<bool>) ===
  35 Turns on/off the display of the cursor.
  36
  37 === fill_screen(R<int>, G<int>, B<int>) ===
  38 Fills the screen with the color specified by the rgb triplet *(R,G,B)*.
  39
  40 === delete_image(image<GLSurface*>) ===
  41 This basically calls glDeleteTextures() on *image*. This function
  42 should _never_ be used on an image loaded using _get_image()_.
  43
  44
  45 == Misc ==
  46 === ticks<int> get_ticks() ===
  47 Returns the number of milliseconds since program intialization. This value overflows after 49 days (32-bit integer).
  48
  49 === delay(time<int>) ===
  50 Waits for *time* milliseconds and then returns.
  51
  52
  53 == Input ==
  54 === x<int>, y<int>, left<bool>, right<bool> mouse_state() ===
  55 Returns the absolute position (within the window) of the cursor.
  56 It also returns the state of the left and right mouse buttons.
  57 This function can be used to get the state of the mouse even when
  58 an event manager is in use.
  59
  60 === num<int> num_joysticks() ===
  61 Returns the number of joysticks currently attached to the system.
  62
  63 === <varying> get_event() ===
  64 This function is used by the event manager to pass events
  65 from SDL to Lua. It should never need to be explicitly
  66 called by the programmer. It returns a varying number of
  67 results.
  68
  69
  70 == Sound ==
  71 === sample<Mix_Chunk*> load_sample(path<string>) ===
  72 Loads a sample, specified by *path*, and returns a pointer to it.
  73
  74 === unload_sample(path<string>) ===
  75 Unloads a previously loaded sample specified by *path*.
  76
  77 === play_sample(sample<Mix_Chunk*>) ===
  78 Plays the sample specified by *sample*. The sample will play until completion.
  79 Sample needs to have been previously loaded using load_sample().
  80
  81 === clear_samples() ===
  82 Unloads all loaded samples from memory.
  83
  84 === stop_samples() ===
  85 Stops the playback of all currently playing samples.
  86
  87 === play_music(path<string>, loops<int>) ===
  88 Plays music specified by *path*. Music will play *loops* times. If *loops* is -1 then it will loop continuously until stopped.
  89
  90 === stop_music() ===
  91 Stops the currently playing music.
  92
  93
  94 == Drawing ==
  95 === draw_pixel(x<int>, y<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
  96 Draws a pixel of color *rgb(R,G,B)* at position *(x,y)*.
  97
  98 === draw_line(x1<int>, y1<int>, x2<int>, y2<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
  99 Draws a line of color *rgb(R,G,B)* from *(x1,y1)* to *(x2,y2)*.
 100
 101 === draw_rect(x1<int>, y1<int>, x2<int>, y2<int>, R<int>, G<int>, B<int>, Alpha<int>, rot<float>, scale_x<float>, scale_y<float>) ===
 102 Draws a rectangle of color *rgb(R,G,B)* with top left corner *(x1,y1)* and bottom right corner *(x2,y2)*.
 103
 104 === draw_filled_rect(x1<int>, y1<int>, x2<int>, y2<int>, R<int>, G<int>, B<int>, Alpha<int>, rot<float>, scale_x<float>, scale_y<float>) ===
 105 Draws a filled rectangle of color *rgb(R,G,B)* with top left corner *(x1,y1)* and bottom right corner *(x2,y2)*.
 106
 107 === draw_circle(x<int>, y<int>, rad<int>, R<int>, G<int>, B<int>, Alpha<int>, rot<float>, scale_x<float>, scale_y<float>) ===
 108 Draws a circle of color *rgb(R,G,B)* with center at position *(x,y)* and radius of *rad*.
 109
 110 === draw_filled_circle(x<int>, y<int>, rad<int>, R<int>, G<int>, B<int>, Alpha<int>, rot<float>, scale_x<float>, scale_y<float>) ===
 111 Draws a filled circle of color *rgb(R,G,B)* with center at position *(x,y)* and radius of *rad*.
 112
 113 === draw_ellipse(x<int>, y<int>, x_rad<int>, y_rad<int>, R<int>, G<int>, B<int>, Alpha<int>, rot<float>, scale_x<float>, scale_y<float>) ===
 114 Draws an ellipse of color *rgb(R,G,B)* with center at position *(x,y)*, x radius of *x_rad* and y radius of *y_rad*.
 115
 116 === draw_filled_ellipse(x<int>, y<int>, x_rad<int>, y_rad<int>, R<int>, G<int>, B<int>, Alpha<int>, rot<float>, scale_x<float>, scale_y<float>) ===
 117 Draws a filled ellipse of color *rgb(R,G,B)* with center at position *(x,y)*, x radius of *x_rad* and y radius of *y_rad*.
 118
 119
 120 == Font ==
 121 === font<TTF_Font*> load_font(path<string>, size<int>) ===
 122 Loads a font specified by *path* at size *size*.
 123
 124 === unload_font(font<TTF_Font*>) ===
 125 Unloads a font specified by *font*.
 126
 127 === w<int>, h<int> rendered_string_size(font<TTF_Font*>, text<string>) ===
 128 Returns the width *w* and height *h* of the string *text* as rendered in *font*.
 129
 130 === txt_image<GLSurface*> render_string(font<TTF_Font*>, text<string>, R<int>, G<int>, B<int>) ===
 131 Renders string *text* in the specified *font* and color *rgb(R,G,B)* and returns it as a GLSurface.
 132
 133
 134 == Instrumentation ==
 135 These functions are written in Lua, but they belong here more than anywhere else.
 136
 137 === instr_begin(id<string>) ===
 138 Begins tracking the time between this call and the end tracking call for *id*.
 139 Also keeps track of how many times it has been called (good for profiling).
 140
 141 NOTE: Calls for the same id cannot be nested. This would result in the timer being
 142 reset for the id, which means that the statistics will be wrong. An error will be
 143 thrown if this is attempted.
 144
 145 === instr_end(id<string>) ===
 146 Ends tracking for *id* and adds the time between the begin call and this one to
 147 the total execution time for *id*.
 148
 149 === instr_track(id<string>, val<number>) ===
 150 Adds an entry to the value tracking table for *id* of value *val*.
 151
 152 === instr_stats() ===
 153 Prints out in a nice formatted way (with colors) the statistics for the time
 154 tracking and the value tracking.
 155
 156 === instr_log(msg<string>, ...<strings>) ===
 157 Adds an entry, *msg*, to the log, recording the time since start of execution.
 158 The varying argument at the end is a number of strings that specify message
 159 classes. Message classes are optional.
 160
 161 === instr_print_log(...<strings>) ===
 162 Prints out the log entries that match all specified classes. If no classes are
 163 specified then it prints out all messages. Prints in ascending order of time recorded.