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<SDL_Surface*> get_image(path<string>) ===
  14 Returns an SDL_Surface* 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. This is basically
  27 a call to _SDL_Flip()_.
  28
  29 === blit(image<SDL_Surface*>, x<int>, y<int>, rotation<double>, reposition<bool>, smoothing<bool>) ===
  30 Blits *image* to the screen at position *(x, y)*. If *rotation* is non-zero, the image will be rotated on the fly.
  31 If *reposition* is true, the rotated image will be re-centered (you probably want this). *Smoothing* is whether or
  32 not linear interpolation should be used (looks pretty but eats CPU).
  33
  34 === blit_frame(image<SDL_Surface*>, x<int>, y<int>, frames<int>, frame_num<int>) ===
  35 Blits frame *frame_num* to the screen at position *(x, y)* from *image* with *frames* number of frames.
  36
  37 === show_cursor(show<bool>) ===
  38 Turns on/off the display of the cursor.
  39
  40 === fill_screen(R<int>, G<int>, B<int>) ===
  41 Fills the screen with the color specified by the rgb triplet *(R,G,B)*.
  42
  43 === delete_image(image<SDL_Surface*>) ===
  44 This effectively calls SDL_FreeSurface() on *image*. This function
  45 should _never_ be used on an image loaded using _get_image()_.
  46
  47 === rz_image<SDL_Surface*>, w<int>, h<int> rotzoom(image<SDL_Surface*>, angle<double>, zoom<double>) ===
  48 Returns a rotated and/or zoomed version of *image* and also the width *w* and height *h* of the rotated/zoomed image.
  49 *Angle* is specified in degrees. *Zoom* is the scaling factor.
  50 Surfaces returned by this function should be freed after use using _delete_image()_.
  51
  52
  53 == Misc ==
  54 === ticks<int> get_ticks() ===
  55 Returns the number of milliseconds since program intialization. This value overflows after 49 days (32-bit integer).
  56
  57 === delay(time<int>) ===
  58 Waits for *time* milliseconds and then returns.
  59
  60
  61 == Input ==
  62 === x<int>, y<int>, left<bool>, right<bool> mouse_state() ===
  63 Returns the absolute position (within the window) of the cursor.
  64 It also returns the state of the left and right mouse buttons.
  65 This function can be used to get the state of the mouse even when
  66 and event manager is in use.
  67
  68 === num<int> num_joysticks() ===
  69 Returns the number of joysticks currently attached to the system.
  70
  71 === <varying> get_event() ===
  72 This function is used by the event manager to pass events
  73 from SDL to Lua. It should never need to be explicitly
  74 called by the programmer. It returns a varying number of
  75 results.
  76
  77
  78 == Sound ==
  79 === sample<Mix_Chunk*> load_sample(path<string>) ===
  80 Loads a sample, specified by *path*, and returns a pointer to it.
  81
  82 === unload_sample(path<string>) ===
  83 Unloads a previously loaded sample specified by *path*.
  84
  85 === play_sample(sample<Mix_Chunk*>) ===
  86 Plays the sample specified by *sample*. The sample will play until completion.
  87 Sample needs to have been previously loaded using load_sample().
  88
  89 === clear_samples() ===
  90 Unloads all loaded samples from memory.
  91
  92 === stop_samples() ===
  93 Stops the playback of all currently playing samples.
  94
  95 === play_music(path<string>, loops<int>) ===
  96 Plays music specified by *path*. Music will play *loops* times. If *loops* is -1 then it will loop continuously until stopped.
  97
  98 === stop_music() ===
  99 Stops the currently playing music.
 100
 101
 102 == Drawing ==
 103 === draw_pixel(x<int>, y<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 104 Draws a pixel of color *rgb(R,G,B)* at position *(x,y)*.
 105
 106 === draw_line(x1<int>, y1<int>, x2<int>, y2<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 107 Draws a line of color *rgb(R,G,B)* from *(x1,y1)* to *(x2,y2)*.
 108
 109 === draw_rect(x1<int>, y1<int>, x2<int>, y2<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 110 Draws a rectangle of color *rgb(R,G,B)* with top left corner *(x1,y1)* and bottom right corner *(x2,y2)*.
 111
 112 === draw_filled_rect(x1<int>, y1<int>, x2<int>, y2<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 113 Draws a filled rectangle of color *rgb(R,G,B)* with top left corner *(x1,y1)* and bottom right corner *(x2,y2)*.
 114
 115 === draw_circle(x<int>, y<int>, rad<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 116 Draws a circle of color *rgb(R,G,B)* with center at position *(x,y)* and radius of *rad*.
 117
 118 === draw_filled_circle(x<int>, y<int>, rad<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 119 Draws a filled circle of color *rgb(R,G,B)* with center at position *(x,y)* and radius of *rad*.
 120
 121 === draw_ellipse(x<int>, y<int>, x_rad<int>, y_rad<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 122 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*.
 123
 124 === draw_filled_ellipse(x<int>, y<int>, x_rad<int>, y_rad<int>, R<int>, G<int>, B<int>, Alpha<int>) ===
 125 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*.
 126
 127
 128 == Font ==
 129 === font<TTF_Font*> load_font(path<string>, size<int>) ===
 130 Loads a font specified by *path* at size *size*.
 131
 132 === unload_font(font<TTF_Font*>) ===
 133 Unloads a font specified by *font*.
 134
 135 === w<int>, h<int> rendered_string_size(font<TTF_Font*>, text<string>) ===
 136 Returns the width *w* and height *h* of the string *text* as rendered in *font*.
 137
 138 === txt_image<SDL_Surface*> render_string(font<TTF_Font*>, text<string>, R<int>, G<int>, B<int>)===
 139 Renders string *text* in the specified *font* and color *rgb(R,G,B)* and returns it as an SDL_Surface.