1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
6 \use_default_options true
7 \maintain_unincluded_children false
9 \language_package default
14 \font_typewriter default
15 \font_default_family default
16 \use_non_tex_fonts false
23 \default_output_format default
25 \bibtex_command default
26 \index_command default
27 \paperfontsize default
31 \pdf_bookmarksnumbered false
32 \pdf_bookmarksopen false
33 \pdf_bookmarksopenlevel 1
48 \paperorientation portrait
64 \paragraph_separation indent
65 \paragraph_indentation default
66 \quotes_language english
69 \paperpagestyle default
70 \tracking_changes false
80 lsnes Lua functions reference
87 \begin_layout Standard
88 \begin_inset CommandInset toc
89 LatexCommand tableofcontents
96 \begin_layout Standard
97 \begin_inset Newpage pagebreak
103 \begin_layout Section
107 \begin_layout Standard
108 These tokens are special, and are expanded while the script is being loaded
111 \begin_layout Subsection
112 @@LUA_SCRIPT_FILENAME@@
115 \begin_layout Standard
116 Expanded to string token containing path and filename of this Lua script.
117 Handy for referencing other lua scripts or resources that are relative
121 \begin_layout Standard
122 In practicular, this is suitable to be passed as base argument of various
123 functions like loadfile, dofile, resolve_filename, gui.bitmap_load, gui.bitmap_lo
124 ad_png and gui.bitmap_load_pal.
127 \begin_layout Section
131 \begin_layout Subsection
132 print: Print values to console
135 \begin_layout Itemize
136 Syntax: none print(value...
140 \begin_layout Standard
141 Prints specified values to console.
142 Can print any Lua type at least enough to identify the type and instance.
145 \begin_layout Subsection
146 tostringx: Format a value to string
149 \begin_layout Itemize
150 Syntax: string tostringx(value val)
153 \begin_layout Standard
154 Formats value <val> like print would, and returns the result as a string.
157 \begin_layout Subsection
158 exec: Execute lsnes commands
161 \begin_layout Itemize
162 Syntax: none exec(string cmd)
165 \begin_layout Standard
166 Execute lsnes command <cmd>.
169 \begin_layout Subsection
170 utime: Get current time
173 \begin_layout Itemize
174 Syntax: (number,number) utime()
177 \begin_layout Standard
179 First is time since some epoch in seconds, the second is microseconds mod
180 10^6 since that epoch.
183 \begin_layout Subsection
184 emulator_ready: Check if emulator has been fully initialized
187 \begin_layout Itemize
188 Syntax: boolean emulator_ready()
191 \begin_layout Standard
192 Returns true if emulator has finished booting, false if not (on_startup()
193 will be issued later).
196 \begin_layout Subsection
197 set_idle_timeout: Run function after timeout when emulator is idle
200 \begin_layout Itemize
201 Syntax: none set_idle_timeout(number timeout)
204 \begin_layout Standard
205 Set number of microseconds to block idle for.
206 After this timeout has expired, on_idle() will be called once.
209 \begin_layout Subsection
210 set_timer_timeout: Run function after timeout.
213 \begin_layout Itemize
214 Syntax: none set_timer_timeout(number timeout)
217 \begin_layout Standard
218 Set number of microseconds to block timer for.
219 After this timeout has expired, on_timer() will be called once.
222 \begin_layout Subsection
223 bus_address: Look up address in system bus.
226 \begin_layout Itemize
227 Syntax: none bus_address(number bus_addr)
230 \begin_layout Standard
231 Returns virtual address corresponding to specified address on system bus.
234 \begin_layout Subsection
235 loopwrapper: Convert loop into callable function
238 \begin_layout Itemize
239 Syntax: function loopwrapper(function fun, ...)
242 \begin_layout Standard
243 Calls function <fun> with function and specified arguments.
244 The function passed suspends execution until the function returned is called.
245 Handy for linear flow control among multiple invocations of a hook.
249 \begin_layout LyX-Code
250 on_paint = loopwrapper(function(wait)
254 \begin_layout LyX-Code
259 \begin_layout LyX-Code
261 \begin_inset Quotes eld
265 \begin_inset Quotes erd
271 \begin_layout LyX-Code
276 \begin_layout LyX-Code
281 \begin_layout LyX-Code
285 \begin_layout Subsection
286 list_bindings: List keybindings
289 \begin_layout Itemize
290 Syntax: table list_bindings([string cmd])
293 \begin_layout Standard
294 Get table of all keybindings, indexed by keyspec (modifiers|mask/key).
295 If <cmd> is specified, the table is limited to that command.
296 Also searches for controller keys.
299 \begin_layout Subsection
300 get_alias: Get expansion of alias
303 \begin_layout Itemize
304 Syntax: string get_alias(string aname)
307 \begin_layout Standard
308 Get expansion of given alias <aname>.
311 \begin_layout Subsection
312 set_alias: Set expansion of alias
315 \begin_layout Itemize
316 Syntax: none set_alias(string aname, string value)
319 \begin_layout Standard
320 Set expansion of given alias.
323 \begin_layout Subsection
324 create_ibind: Create invese binding
327 \begin_layout Itemize
328 Syntax: INVERSEBIND create_ibind(string name, string cmd)
331 \begin_layout Standard
332 Return object representing inverse binding with specified name <name> and
333 specified command <cmd>.
336 \begin_layout Itemize
337 Note: To create press/release commands, use aliases +foo and -foo .
340 \begin_layout Itemize
341 Note: Keep the returned object around.
344 \begin_layout Subsection
345 create_command: Create a command
348 \begin_layout Itemize
349 Syntax: COMMANDBIND create_commmand(string name, function a)
352 \begin_layout Itemize
353 Syntax: COMMANDBIND create_commmand(string name, function a, function b)
356 \begin_layout Standard
357 Return object representing a command (pair).
360 \begin_layout Itemize
361 If only one function is specied, the command is level-sensitive, <a> is
365 \begin_layout Itemize
366 If <b> is function, the function is edge-sensitive, <a> is positive edge
367 callback and <b> is negative edge callback.
370 \begin_layout Itemize
371 All callbacks get single argument: The parameters passed.
374 \begin_layout Itemize
375 Keep the returned object around.
378 \begin_layout Subsection
379 loadfile: Load Lua script
382 \begin_layout Itemize
383 Syntax: function loadfile(string filename[, string base])
386 \begin_layout Standard
387 Load lua script from <filename>, resolved relative to <base> (if empty,
391 \begin_layout Subsection
392 dofile: Execute Lua script
395 \begin_layout Itemize
396 Syntax: function dofile(string filename[, string base])
399 \begin_layout Standard
400 Execute lua script from <filename>, resolved relative to <base> (if empty,
401 current directory) and return all return values.
404 \begin_layout Subsection
405 open_file: Open a stream
408 \begin_layout Itemize
409 Syntax: FILEREADER open_file(string filename[, string base])
412 \begin_layout Standard
413 Open file <filename>, resolved relative to <base> (if empty, current directory)
417 \begin_layout Subsection
418 FILEREADER(): Read line/bytes from stream
421 \begin_layout Itemize
422 Syntax: string/nil FILEREADER()
425 \begin_layout Itemize
426 Syntax: string/nil FILEREADER(number bytes)
429 \begin_layout Standard
430 Reads next line or <bytes> bytes from specified file handle.
431 On EOF, nil is returned.
434 \begin_layout Itemize
435 Note: The line-oriented variant reads in text mode, so CR at end of line
439 \begin_layout Subsection
440 FILEREADER:lines: Iterator to read all lines
443 \begin_layout Itemize
444 Syntax: for line in <foo>:lines() do ...
448 \begin_layout Standard
449 Iterator for reading all lines of <foo> in a loop.
452 \begin_layout Subsection
453 resolve_filename: Resolve name of file relative to another
456 \begin_layout Itemize
457 Syntax: string resolve_file(string filename, string base)
460 \begin_layout Standard
461 Resolve name of file <filename> relative to <base> and return the result.
464 \begin_layout Standard
465 \begin_inset Newpage pagebreak
471 \begin_layout Section
475 \begin_layout Standard
476 Bitwise logical functions and related.
479 \begin_layout Subsection
480 bit.none/bit.bnot: Bitwise none or NOT function
483 \begin_layout Itemize
484 Syntax: number bit.none(number...)
487 \begin_layout Itemize
488 Syntax: number bit.bnot(number...)
491 \begin_layout Standard
492 48-bit bitwise NOT / NONE function (set bits that are set in none of the
496 \begin_layout Subsection
497 bit.any/bit.bor: Bitwise any or OR function
500 \begin_layout Itemize
501 Syntax: number bit.any(number...)
504 \begin_layout Itemize
505 Syntax: number bit.bor(number...)
508 \begin_layout Standard
509 48-bit bitwise OR / ANY function (set bits that are set in any of the arguments).
512 \begin_layout Subsection
513 bit.all/bit.band: Bitwise all or AND function
516 \begin_layout Itemize
517 Syntax: number bit.all(number...)
520 \begin_layout Itemize
521 Syntax: number bit.band(number...)
524 \begin_layout Standard
525 48-bit bitwise AND / ALL function (set bits that are set in all of the arguments
529 \begin_layout Subsection
530 bit.parity/bit.bxor: Bitwise parity or XOR function
533 \begin_layout Itemize
534 Syntax: number bit.parity(number...)
537 \begin_layout Itemize
538 Syntax: number bit.bxor(number...)
541 \begin_layout Standard
542 48-bit bitwise XOR / PARITY function (set bits that are set in odd number
546 \begin_layout Subsection
547 bit.lrotate: Rotate a number left
550 \begin_layout Itemize
551 Syntax: number bit.lrotate(number base[, number amount[, number bits]])
554 \begin_layout Standard
555 Rotate <bits>-bit (max 48, default 48) number <base> left by <amount> (default
559 \begin_layout Subsection
560 bit.rrotate: Rotate a number right
563 \begin_layout Itemize
564 Syntax: number bit.rrotate(number base[, number amount[, number bits]])
567 \begin_layout Standard
568 Rotate <bits>-bit (max 48, default 48) number <base> right by <amount> (default
572 \begin_layout Subsection
573 bit.lshift: Shift a number left
576 \begin_layout Itemize
577 Syntax: number bit.lshift(number base[, number amount[, number bits]])
580 \begin_layout Standard
581 Shift <bits>-bit (max 48, default 48) number <base> left by <amount> (default
583 The new bits are filled with zeroes.
586 \begin_layout Subsection
587 bit.lrshift: Shift a number right (logical)
590 \begin_layout Itemize
591 Syntax: number bit.lrshift(number base[, number amount[, number bits]])
594 \begin_layout Standard
595 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
597 The new bits are filled with zeroes.
600 \begin_layout Subsection
601 bit.arshift: Shift a number right (arithmetic)
604 \begin_layout Itemize
605 Syntax: number bit.arshift(number base[, number amount[, number bits]])
608 \begin_layout Standard
609 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
611 The new bits are shifted in with copy of the high bit.
614 \begin_layout Subsection
615 bit.extract: Extract/shuffle bits from number
618 \begin_layout Itemize
619 Syntax: number bit.extract(number base[, number bit0[, number bit1,...]])
622 \begin_layout Standard
623 Returns number that has bit0-th bit as bit 0, bit1-th bit as 1 and so on.
626 \begin_layout Itemize
627 Note: Bit numbers up to 51 should work reliably (then things start falling
628 apart due to double precision issues).
631 \begin_layout Itemize
632 Note: There are two special bit positions, true and false, standing for
633 always set bit and always clear bit.
636 \begin_layout Subsection
637 bit.value: Construct number with specified bits set
640 \begin_layout Itemize
641 Syntax: number bit.value([number bit1[, number bit2,...]])
644 \begin_layout Standard
645 Returns bitwise OR of 1 left shifted by <bit1> places, 1 left shifted by
646 <bit2> places and so on.
647 As special value, nil argument is no-op.
650 \begin_layout Subsection
651 bit.test_any: Test if any bit is set
654 \begin_layout Itemize
655 Syntax: boolean bit.test_any(number a, number b)
658 \begin_layout Standard
659 Returns true if bitwise and of <a> and <b> is nonzero, otherwise false.
662 \begin_layout Subsection
663 bit.test_all: Test if all bits are set
666 \begin_layout Itemize
667 Syntax: boolean bit.test_all(number a, number b)
670 \begin_layout Standard
671 Returns true if bitwise and of <a> and <b> equals <b>, otherwise false.
674 \begin_layout Subsection
675 bit.popcount: Population count
678 \begin_layout Itemize
679 Syntax: number bit.popcount(number a)
682 \begin_layout Standard
683 Returns number of set bits in <a>.
686 \begin_layout Subsection
687 bit.clshift: Chained left shift
690 \begin_layout Itemize
691 Syntax: (number, number) bit.clshift(number a, number b, [number amount,[number
695 \begin_layout Standard
696 Does chained left shift on <a>, <b> by <amount> positions (default 1), assuming
697 numbers to be of specified number of bits <bits> (default 48).
700 \begin_layout Subsection
701 bit.crshift: Chained right shift
704 \begin_layout Itemize
705 Syntax: (number, number) bit.crshift(number a, number b, [number amount,[number
709 \begin_layout Standard
710 Does chained right shift on <a>, <b> by <amount> positions (default 1),
711 assuming numbers to be of specified number of bits <bits> (default 48).
714 \begin_layout Subsection
715 bit.flagdecode: Decode bitfield into flags
718 \begin_layout Itemize
719 Syntax: string bit.flagdecode(number a, number bits, [string on, [string
723 \begin_layout Standard
724 Return string of length bits where ith character is ith character of on
725 if bit i is on, otherwise ith character of off.
726 Out of range reads give last character.
729 \begin_layout Itemize
730 Note: <on> defaults to '*' if empty.
733 \begin_layout Itemize
734 Note: <off> defaults to '-' if empty.
737 \begin_layout Subsection
738 bit.rflagdecode: Decode bitfield into flags
741 \begin_layout Itemize
742 Syntax: string bit.rflagdecode(number a, number bits, [string on, [string
746 \begin_layout Standard
747 Like bit.flagdecode, but outputs the string in the opposite order (most significa
751 \begin_layout Standard
752 \begin_inset Newpage pagebreak
758 \begin_layout Section
762 \begin_layout Itemize
763 Functions that draw to screen can only only be called in on_paint and on_video
764 callbacks or if non-default render queue has been set.
767 \begin_layout Itemize
769 Bits 0-7 are the blue component, bits 8-15 are the green component, bits
770 16-23 are the red component, bits 24-31 are alpha component (0 is fully
771 opaque, 255 is almost transparent).
772 -1 is the fully transparent color.
775 \begin_layout Itemize
776 Alpha values greater than 127 do work properly.
779 \begin_layout Itemize
780 Origin of coordinates is at top left corner of game display area.
781 Left and top gaps correspond to negative coordinates.
784 \begin_layout Subsection
785 gui.resolution: Get current resolution
788 \begin_layout Itemize
789 Syntax: (number, number) gui.resolution()
792 \begin_layout Standard
793 Returns 2-tuple (hresolution, vresolution).
796 \begin_layout Subsection
797 gui.left_gap/gui.right_gap/gui.top_gap/gui.bottom_gap: Set edge gaps
800 \begin_layout Itemize
801 Syntax: number gui.left_gap(number gap)
804 \begin_layout Itemize
805 Syntax: number gui.right_gap(number gap)
808 \begin_layout Itemize
809 Syntax: number gui.top_gap(number gap)
812 \begin_layout Itemize
813 Syntax: number gui.bottom_gap(number gap)
816 \begin_layout Standard
817 Set the specified edge gap to specified value <gap> (max gap is 8191).
818 If successful, old gap is returned.
821 \begin_layout Subsection
822 gui.delta_left_gap/gui.delta_right_gap/gui.delta_top_gap/gui.delta_bottom_gap:
826 \begin_layout Itemize
827 Syntax: number gui.delta_left_gap(number dgap)
830 \begin_layout Itemize
831 Syntax: number gui.delta_right_gap(number dgap)
834 \begin_layout Itemize
835 Syntax: number gui.delta_top_gap(number dgap)
838 \begin_layout Itemize
839 Syntax: number gui.delta_bottom_gap(number dgap)
842 \begin_layout Standard
843 Increase the specified edge gap by specified value <dgap> (max gap is 8191)
844 and return the old gap (returns nothing on error).
847 \begin_layout Subsection
848 gui.text/gui.textH/gui.textV,gui.textHV: Draw text
851 \begin_layout Itemize
852 Syntax: none gui.text(number x, number y, string text[, number fgc[, number
856 \begin_layout Itemize
857 Syntax: none gui.textH(number x, number y, string text[, number fgc[, number
861 \begin_layout Itemize
862 Syntax: none gui.textV(number x, number y, string text[, number fgc[, number
866 \begin_layout Itemize
867 Syntax: none gui.textHV(number x, number y, string text[, number fgc[, number
871 \begin_layout Standard
872 Draw specified text on the GUI (each character cell is 8 or 16 wide and
877 \begin_layout Itemize
878 x: X-coordinate to start the drawing from (and x-coordinate at begining
882 \begin_layout Itemize
883 y: Y-coordinate to start the drawing from.
886 \begin_layout Itemize
887 text: The text to draw.
890 \begin_layout Itemize
891 fgc: Text color (default is 0xFFFFFF (white))
894 \begin_layout Itemize
895 bgc: Background color (default is -1 (transparent))
898 \begin_layout Standard
899 Note: The H variants draw at double width and V variants draw at double
903 \begin_layout Subsection
904 gui.rectangle: Draw a rectangle
907 \begin_layout Itemize
908 Syntax: none gui.rectangle(number x, number y, number width, number height[,
909 number thickness[, number outline[, number fill]]])
912 \begin_layout Standard
913 Draw rectangle on the GUI.
917 \begin_layout Itemize
918 x: X-coordinate of left edge.
921 \begin_layout Itemize
922 y: Y-coordinate of upper edge.
925 \begin_layout Itemize
926 width: Width of rectangle.
929 \begin_layout Itemize
930 height: Height of rectangle.
933 \begin_layout Itemize
934 thickness: Thickness of outline (default is 1).
937 \begin_layout Itemize
938 outline: Color of outline (default is 0xFFFFFF (white))
941 \begin_layout Itemize
942 fill: Color of fill (default is -1 (transparent))
945 \begin_layout Subsection
946 gui.box: Draw a 3D-effect box
949 \begin_layout Itemize
950 Syntax: none gui.box(number x, number y, number width, number height[, number
951 thickness[, number outline1[,number outline2[, number fill]]]])
954 \begin_layout Standard
955 Draw rectangle with 3D effect on the GUI.
959 \begin_layout Itemize
960 x: X-coordinate of left edge.
963 \begin_layout Itemize
964 y: Y-coordinate of upper edge.
967 \begin_layout Itemize
968 width: Width of rectangle.
971 \begin_layout Itemize
972 height: Height of rectangle.
975 \begin_layout Itemize
976 thickness: Thickness of outline (default is 1).
979 \begin_layout Itemize
980 outline1: First color of outline (default is 0xFFFFFF (white))
983 \begin_layout Itemize
984 outline2: First color of outline (default is 0x808080 (dark gray))
987 \begin_layout Itemize
988 fill: Color of fill (default is 0xC0C0C0 (light grayy))
991 \begin_layout Subsection
992 gui.pixel: Draw a single pixel
995 \begin_layout Itemize
996 Syntax: none gui.pixel(number x, number y[, number color])
999 \begin_layout Standard
1000 Draw one pixel on the GUI.
1004 \begin_layout Itemize
1005 x: X-coordinate of the pixel
1008 \begin_layout Itemize
1009 y: Y-coordinate of the pixel
1012 \begin_layout Itemize
1013 color: Color of the pixel (default is 0xFFFFFF (white))
1016 \begin_layout Subsection
1017 gui.crosshair: Draw a crosshair
1020 \begin_layout Itemize
1021 Syntax: none gui.crosshair(number x, number y[, number length[, number color]])
1024 \begin_layout Standard
1029 \begin_layout Itemize
1030 x: X-coordinate of the crosshair
1033 \begin_layout Itemize
1034 y: Y-coordinate of the crosshair
1037 \begin_layout Itemize
1038 length: Length of the crosshair lines (default 10).
1041 \begin_layout Itemize
1042 color: Color of the crosshair (default is 0xFFFFFF (white))
1045 \begin_layout Subsection
1046 gui.line: Draw a line
1049 \begin_layout Itemize
1050 Syntax: none gui.line(number x1, number y1, number x2, number y2[, number
1054 \begin_layout Standard
1059 \begin_layout Itemize
1060 x1: X-coordinate of one end.
1063 \begin_layout Itemize
1064 y1: Y-coordinate of one end.
1067 \begin_layout Itemize
1068 x2: X-coordinate of the other end.
1071 \begin_layout Itemize
1072 y2: Y-coordinate of the other end.
1075 \begin_layout Itemize
1076 color: Color of the line (default is 0xFFFFFF (white)).
1079 \begin_layout Subsection
1080 gui.circle: Draw a (filled) circle
1083 \begin_layout Itemize
1084 Syntax: none gui.circle(number x, number y, number r[, number thick[, number
1085 border[, number fil]]])
1088 \begin_layout Standard
1093 \begin_layout Itemize
1094 x: X-coordinate of the center
1097 \begin_layout Itemize
1098 y: Y-coordinate of the center
1101 \begin_layout Itemize
1102 r: The radius of the circle
1105 \begin_layout Itemize
1106 thick: Border thickness
1109 \begin_layout Itemize
1110 border: Border color (default is 0xFFFFFF (white))
1113 \begin_layout Itemize
1114 fill: Fill color (default is -1 (transparent)).
1117 \begin_layout Subsection
1118 gui.bitmap_draw: Draw a bitmap
1121 \begin_layout Itemize
1122 Syntax: none gui.bitmap_draw(number x, number y, BITMAP bitmap, PALETTE palette)
1125 \begin_layout Itemize
1126 Syntax: none gui.bitmap_draw(number x, number y, DBITMAP bitmap)
1129 \begin_layout Standard
1130 Draw a bitmap <bitmap> on screen with specified palette <palette> (if bitmap
1135 \begin_layout Itemize
1136 x: X-coordinate of left edge.
1139 \begin_layout Itemize
1140 y: Y-coordinate of top edge.
1143 \begin_layout Itemize
1144 bitmap: The bitmap to draw
1147 \begin_layout Itemize
1148 palette: The palette to draw the bitmap using.
1151 \begin_layout Subsection
1152 gui.palette_new: Create a new palette
1155 \begin_layout Itemize
1156 Syntax: PALETTE gui.palette_new()
1159 \begin_layout Standard
1160 Returns a new palette (initially all transparent).
1164 \begin_layout Subsection
1165 gui.bitmap_new: Create a new bitmap
1168 \begin_layout Itemize
1169 Syntax: BITMAP/DBITMAP gui.bitmap_new(number w, number h, boolean direct[,
1173 \begin_layout Standard
1174 Returns a new bitmap/dbitmap.
1177 \begin_layout Standard
1181 \begin_layout Itemize
1182 w: The width of new bitmap
1185 \begin_layout Itemize
1186 h: The height of new bitmap
1189 \begin_layout Itemize
1190 direct: If true, the returned bitmap is dbitmap, otherwise bitmap.
1193 \begin_layout Itemize
1194 icolor: Initital fill color (defaults to 0 on BITMAP, -1 on DBITMAP)
1197 \begin_layout Subsection
1198 gui.bitmap_load/gui.bitmap_load_str: Load a bitmap from file or string
1201 \begin_layout Itemize
1202 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load(string file[, string base])
1205 \begin_layout Itemize
1206 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_str(string content)
1209 \begin_layout Standard
1210 Reads file <file> (resolved relative to <base>) or string <content> and
1211 returns loaded bitmap/dbitmap (if bitmap, the second return value is palette
1215 \begin_layout Subsection
1216 gui.bitmap_load_png/gui.bitmap_load_png_str: Load a bitmap from PNG
1219 \begin_layout Itemize
1220 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_png(string file[, string
1224 \begin_layout Itemize
1225 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_png_str(string content)
1228 \begin_layout Standard
1229 Load a bitmap from PNG file <file> (resolved relative to <base>) or BASE64
1230 encoded content <content>.
1233 \begin_layout Itemize
1234 If the PNG is of color type 3 (PALETTE), returns two value.
1235 First is BITMAP containing the image data from the PNG and second is PALETTE
1236 containg the palette data from the PNG.
1239 \begin_layout Itemize
1240 For color types 0 (GRAY), 2 (RGB), 4 (GRAY_ALPHA) and 6 (RGBA), returns
1241 one DBITMAP containg the image data loaded from the PNG.
1244 \begin_layout Subsection
1245 gui.bitmap_load_pal/gui.bitmap_load_pal_str: Load a palette
1248 \begin_layout Itemize
1249 Syntax: PALETTE gui.bitmap_load_pal(string file[, string base])
1252 \begin_layout Itemize
1253 Syntax: PALETTE gui.bitmap_load_pal_str(string content)
1256 \begin_layout Standard
1257 Load a palette from file <file>(resolved relative to <base>) or string <content>.
1260 \begin_layout Itemize
1261 The kinds of lines supported:
1265 \begin_layout Itemize
1266 Blank or just whitespace: Ignored
1269 \begin_layout Itemize
1270 First non-whitespace is '#': Ignored
1273 \begin_layout Itemize
1274 <r> <g> <b>: Fully opaque color with specified RGB values (0-255)
1277 \begin_layout Itemize
1278 <r> <g> <b> <a>: Color with specified RGB values (0-255) and specified alpha
1279 (0-256, 0 being fully transparent and 256 fully opaque).
1282 \begin_layout Itemize
1283 transparent: Fully transparent color
1287 \begin_layout Subsection
1288 gui.palette_set: Set palette entry
1291 \begin_layout Itemize
1292 Syntax: none gui.palette_set(PALETTE palette, number index, number color)
1295 \begin_layout Standard
1296 Sets color in palette.
1300 \begin_layout Itemize
1301 palette: The palette to manipulate
1304 \begin_layout Itemize
1305 index: Index of color (0-65535).
1308 \begin_layout Itemize
1309 color: The color value.
1312 \begin_layout Subsection
1313 gui.bitmap_pset: Set pixel in bitmap
1316 \begin_layout Itemize
1317 Syntax: none gui.bitmap_pset(BITMAP/DBITMAP bitmap, number x, number y, number
1321 \begin_layout Standard
1322 Sets specified pixel in bitmap.
1326 \begin_layout Itemize
1327 bitmap: The bitmap to manipulate
1330 \begin_layout Itemize
1331 x: The x-coordinate of the pixel.
1334 \begin_layout Itemize
1335 y: The y-coordinate of the pixel.
1338 \begin_layout Itemize
1339 color: If bitmap is a bitmap, color index (0-65535).
1340 Otherwise color value.
1343 \begin_layout Subsection
1344 gui.bitmap_pget: Get pixel in bitmap
1347 \begin_layout Itemize
1348 Syntax: number gui.bitmap_pget(BITMAP/DBITMAP bitmap, number x, number y)
1351 \begin_layout Standard
1352 Gets specified pixel in bitmap.
1356 \begin_layout Itemize
1357 bitmap: The bitmap to query
1360 \begin_layout Itemize
1361 x: The x-coordinate of the pixel.
1364 \begin_layout Itemize
1365 y: The y-coordinate of the pixel.
1368 \begin_layout Standard
1369 The bitmap color (color index if paletted, otherwise color value).
1372 \begin_layout Subsection
1373 gui.bitmap_size: Get size of bitmap
1376 \begin_layout Itemize
1377 Syntax: (number, number) gui.bitmap_size(BITMAP/DBITMAP bitmap)
1380 \begin_layout Standard
1381 Get size of bitmap <bitmap>.
1382 The first return is the width, the second is the height.
1385 \begin_layout Itemize
1386 Note: Can be used anywhere.
1389 \begin_layout Subsection
1390 gui.bitmap_blit: Blit a bitmap into another
1393 \begin_layout Itemize
1394 Syntax: none gui.bitmap_blit(BITMAP dest, number dx, number dy, BITMAP src,
1395 number sx, number sy, number w, number h[, number ck])
1398 \begin_layout Itemize
1399 Syntax: none gui.bitmap_blit(DBITMAP dest, number dx, number dy, DBITMAP
1400 src, number sx, number sy, number w, number h[, number ck])
1403 \begin_layout Itemize
1404 Syntax: none gui.bitmap_blit(DBITMAP dest, number dx, number dy, BITMAP src,
1405 PALETTE pal, number sx, number sy, number w, number h[, number ck])
1408 \begin_layout Standard
1409 Blit a part of bitmap to another.
1413 \begin_layout Itemize
1414 dest: Destination to blit to.
1417 \begin_layout Itemize
1418 dx: left edge of target
1421 \begin_layout Itemize
1422 dy: Top edge of target
1425 \begin_layout Itemize
1426 src: The source to blit from.
1429 \begin_layout Itemize
1430 pal: The palette to use in blit.
1433 \begin_layout Itemize
1434 sx: left edge of source
1437 \begin_layout Itemize
1438 sy: Top edge of source
1441 \begin_layout Itemize
1445 \begin_layout Itemize
1446 h: Height of region.
1449 \begin_layout Itemize
1451 Pixels of this color are not blitted.
1455 \begin_layout Itemize
1456 If soruce bitmap is bitmap, this is color index of colorkey.
1457 Values outside range 0-65535 cause no key to be used as colorkey.
1460 \begin_layout Itemize
1461 If source bitmap is dbitmap, this is the color value of colorkey.
1464 \begin_layout Itemize
1465 May be absent or nil for no colorkey blit.
1469 \begin_layout Subsection
1470 gui.repaint: Arrange a repaint
1473 \begin_layout Itemize
1474 Syntax: none gui.repaint()
1477 \begin_layout Standard
1478 Request on_repaint() to happen as soon as possible.
1481 \begin_layout Subsection
1482 gui.synchronous_repaint: Paint screen now
1485 \begin_layout Itemize
1486 Syntax: none gui.synchronous_repaint(RENDERQUEUE queue)
1489 \begin_layout Standard
1490 Paints specified render queue on screen right there and then.
1493 \begin_layout Subsection
1494 gui.subframe_update: Enable/Disable subframe updates
1497 \begin_layout Itemize
1498 Syntax: none gui.subframe_update(boolean on)
1501 \begin_layout Standard
1502 Request subframe updates (calling on_paint() on subframes) to happen (<on>=true)
1503 or not happen (<on>=false).
1506 \begin_layout Subsection
1507 gui.screenshot: Write a screenshot
1510 \begin_layout Itemize
1511 Syntax: none gui.screenshot(string filename)
1514 \begin_layout Standard
1515 Write PNG screenshot of the current frame (no drawings) to specified file
1519 \begin_layout Subsection
1520 gui.color: Compose a color.
1523 \begin_layout Itemize
1524 Syntax: number gui.color(number r, number g, number b[, number a])
1527 \begin_layout Standard
1528 Returns color (in notation Lua scripts use) corresponding to color (<r>,<g>,<b>)
1529 , each component in scale 0-255.
1530 If <a> is specified, that is alpha (0 is fully transparent, 256(sic) is
1532 The default alpha is 256.
1535 \begin_layout Subsection
1536 gui.status: Set status variable
1539 \begin_layout Itemize
1540 Syntax: none gui.status(string name, string value)
1543 \begin_layout Standard
1545 \begin_inset Quotes eld
1549 \begin_inset Quotes erd
1552 to <value> in status area.
1555 \begin_layout Subsection
1556 gui.rainbow: Rainbow color calculation
1559 \begin_layout Itemize
1560 Syntax: number gui.rainbow(number step, number steps[, number color])
1563 \begin_layout Standard
1564 Perform hue rotation of color <color> (default bright red), by <step> steps.
1565 The number of steps per full rotation is given by absolute value of <steps>.
1568 \begin_layout Standard
1569 If <steps> is negative, the rotation will be counterclockwise.
1572 \begin_layout Subsection
1573 gui.renderq_new: Create a render queue
1576 \begin_layout Itemize
1577 Syntax: RENDERQUEUE gui.renderq_new(number width, number height)
1580 \begin_layout Standard
1581 Create render queue with specified reported size and return it.
1584 \begin_layout Subsection
1585 gui.renderq_clear: Clear a render queue
1588 \begin_layout Itemize
1589 Syntax: none gui.renderq_clear(RENDERQUEUE queue)
1592 \begin_layout Standard
1593 Clear specified render queue.
1596 \begin_layout Subsection
1597 gui.renderq_set: Change active render queue
1600 \begin_layout Itemize
1601 Syntax: none gui.renderq_set(RENDERQUEUE queue)
1604 \begin_layout Standard
1605 Switch to specified render queue.
1606 Use nil as queue to switch to default queue.
1609 \begin_layout Itemize
1610 Note: When switched to another queue, all drawing functions work and draw
1611 there, even outside on_video/on_paint.
1614 \begin_layout Subsection
1615 gui.renderq_run: Run render queue
1618 \begin_layout Itemize
1619 Syntax: none gui.renderq_run(RENDERQUEUE queue)
1622 \begin_layout Standard
1623 Run specified render queue, copying the objects to current render queue.
1627 \begin_layout Itemize
1628 Warning: Don't try to run the current render queue.
1631 \begin_layout Subsection
1632 gui.loadfont: Load a font file
1635 \begin_layout Itemize
1636 Syntax: CUSTOMFONT gui.loadfont(string filename)
1639 \begin_layout Standard
1640 Loads font from specified file (CUSTOMFONT object).
1643 \begin_layout Subsection
1644 CUSTOMFONT(): Render text to screen
1647 \begin_layout Itemize
1648 Syntax: none CUSTOMFONT(number x, number y, string text[, number fgc[, number
1649 bgc[, number hlc]]])
1652 \begin_layout Standard
1653 Draw string with custom font to screen.
1654 The parameters are the same as in gui.text, except <hlc> is the halo color
1655 (default is no halo).
1659 \begin_layout Subsection
1660 gui.adjust_transparency: Adjust transparency of DBITMAP or PALETTE
1663 \begin_layout Itemize
1664 Syntax: none gui.adjust_transparency(DBITMAP obj, number adj)
1667 \begin_layout Itemize
1668 Syntax: none gui.adjust_transparency(PALETTE obj, number adj)
1671 \begin_layout Standard
1672 Multiply alpha channel of <obj> by <adj>/256.
1674 \begin_inset Quotes eld
1678 \begin_inset Quotes erd
1681 out of solid bitmaps.
1684 \begin_layout Subsection
1685 gui.kill_frame: Kill video frame and associated sound
1688 \begin_layout Itemize
1689 Syntax: none gui.kill_frame()
1692 \begin_layout Standard
1693 Kills the currently dumped video frame + the associated sound.
1694 Only valid in on_video callback.
1697 \begin_layout Subsection
1698 gui.arrow: Draw an arrow
1701 \begin_layout Itemize
1702 Syntax: none gui.arrow(number x, number y, number length, number hwidth,
1703 number direction[, bool fill[, number color[, number twidth[, number hthick]]]]
1707 \begin_layout Standard
1708 Draws an arrow using color <color>.
1709 The tip of arrow is at (<x>, <y>).
1713 \begin_layout Enumerate
1714 <length>: The length of arrow tail.
1717 \begin_layout Enumerate
1718 <hwidth>: The width of arrow head.
1722 \begin_layout Enumerate
1723 <direction>: Direction of arrow.
1724 0 is to right, +1 rotates 45 degrees counterclockwise.
1727 \begin_layout Enumerate
1728 <fill>: If true, fill the arrow head.
1732 \begin_layout Enumerate
1733 <twidth>: Tail width.
1738 \begin_layout Enumerate
1739 <hthick>: Head thickness (only used if <fill> is false).
1740 Default is <twidth>.
1743 \begin_layout Subsection
1744 gui.tilemap: Create a tilemap
1747 \begin_layout Itemize
1748 Syntax: TILEMAP gui.tilemap(number w, number h, number bw, number bh)
1751 \begin_layout Standard
1752 Create a new tilemap of size <w>*<h>, with each cell being <bw>*<bh>.
1755 \begin_layout Subsection
1756 TILEMAP:getsize: Query tilemap size
1759 \begin_layout Itemize
1760 Syntax: number, number TILEMAP:getsize()
1763 \begin_layout Standard
1764 Return size of tilemap (width first).
1767 \begin_layout Subsection
1768 TILEMAP:getcsize: Query tilemap cell size
1771 \begin_layout Itemize
1772 Syntax: number, number TILEMAP:getcsize()
1775 \begin_layout Standard
1776 Return size of tilemap cell (width first).
1779 \begin_layout Subsection
1780 TILEMAP:get: Query tilemap cell
1783 \begin_layout Itemize
1784 Syntax: none TILEMAP:get(number x, number y)
1787 \begin_layout Itemize
1788 Syntax: dbitmap TILEMAP:get(number x, number y)
1791 \begin_layout Itemize
1792 Syntax: bitmap,palette TILEMAP:get(number x, number y)
1795 \begin_layout Standard
1796 Return contents of cell at <x>,<y>.
1799 \begin_layout Subsection
1800 TILEMAP:set: Set tilemap cell
1803 \begin_layout Itemize
1804 Syntax: none TILEMAP:set(number x, number y)
1807 \begin_layout Itemize
1808 Syntax: none TILEMAP:set(number x, number y, dbitmap b)
1811 \begin_layout Itemize
1812 Syntax: none TILEMAP:set(number x, number y, bitmap b, palette p)
1815 \begin_layout Standard
1816 Set contents of cell at <x>,<y>.
1817 If no bitmap/dbitmap is given, cell is cleared.
1818 Otherwise specified (d)bitmap is used (with specified palette if bitmap).
1821 \begin_layout Subsection
1822 TILEMAP:scroll: Scroll tilemap
1825 \begin_layout Itemize
1826 Syntax: none TILEMAP:scroll(number ox, number oy)
1829 \begin_layout Itemize
1830 Syntax: none TILEMAP:scroll(number ox, number oy, number x, number y, number
1834 \begin_layout Itemize
1835 Syntax: none TILEMAP:scroll(number ox, number oy, number x, number y, number
1836 w, number h, boolean circx, boolean circy)
1839 \begin_layout Standard
1840 Scrolls the tilemap tiles by <ox>,<oy>.
1841 If <x>,<y>,<w>,<h> is specified, the scrolling is limited to <w>*<h> window
1842 starting at <x>,<y> (in tiles).
1845 \begin_layout Standard
1846 If <circx> is true, the window is circular in horizontal direction.
1847 Similarly with <circy> and vertical direciton.
1850 \begin_layout Subsection
1851 TILEMAP:draw: Draw tilemap
1854 \begin_layout Itemize
1855 Syntax: none TILEMAP:draw(number x, number y)
1858 \begin_layout Itemize
1859 Syntax: none TILEMAP:draw(number x, number y, number x0, number y0)
1862 \begin_layout Itemize
1863 Syntax: none TILEMAP:draw(number x, number y, number x0, number y0, number
1867 \begin_layout Standard
1868 Draw tilemap at <x>,<y>.
1869 If <x0>,<y0> is given, that is tilemap coordinate (in pixels) of upper
1871 If <w>,<h> is given, that is the size of window to draw (in pixels)
1874 \begin_layout Subsection
1875 gui.bitmap_save_png: Save a bitmap to PNG
1878 \begin_layout Itemize
1879 Syntax: none gui.bitmap_save_png(string filename[, string base], BITMAP bmp,
1883 \begin_layout Itemize
1884 Syntax: none gui.bitmap_save_png(string filename[, string base], DBITMAP
1888 \begin_layout Itemize
1889 Syntax: string gui.bitmap_save_png(BITMAP bmp, PALETTE pal)
1892 \begin_layout Itemize
1893 Syntax: string gui.bitmap_save_png(DBITMAP bmp)
1896 \begin_layout Standard
1897 Save specified bitmap <bmp>, with palette <pal> (only if paletted) into
1898 PNG file <filename> (relative to <base>) or return BASE64 encoding as return
1902 \begin_layout Standard
1903 \begin_inset Newpage pagebreak
1909 \begin_layout Section
1913 \begin_layout Standard
1915 Functions manipulating input are only available in on_input callback.
1918 \begin_layout Subsection
1919 input.get: Read controller button/axis (deprecated)
1922 \begin_layout Itemize
1923 Syntax: number input.get(number controller, number index)
1926 \begin_layout Standard
1927 Read the specified index <index> (zero-based) from specified controller
1928 <controller> (zero-based).
1932 \begin_layout Subsection
1933 input.set: Write controller button/axis (deprecated)
1936 \begin_layout Itemize
1937 Syntax: none input.set(number controller, number index, number value)
1940 \begin_layout Standard
1941 Write the specified index <index> (zero-based) from specified controller
1942 <controller> (zero-based), storing value <value>.
1945 \begin_layout Subsection
1946 input.get2: Read controller button/axis
1949 \begin_layout Itemize
1950 Syntax: number input.get2(number port, number controller, number index)
1953 \begin_layout Standard
1954 Read the specified input tuple.
1955 Port 0 is system port.
1958 \begin_layout Subsection
1959 input.set2: Write controller button/axis
1962 \begin_layout Itemize
1963 Syntax: input.set2(number port, number controller, number index, number value)
1966 \begin_layout Standard
1967 Write the specified input tuple.
1968 Port 0 is system port.
1971 \begin_layout Subsection
1972 input.lcid_to_pcid2: Look up logical controller
1975 \begin_layout Itemize
1976 Syntax: (number, number) input.lcid_to_pcid2(number lcid)
1979 \begin_layout Standard
1980 Look up physical pcid pair (port, controller) corresponding to specified
1981 logical controller (1-based).
1982 Returns nothing if controller does not exist.
1985 \begin_layout Subsection
1986 input.port_type: Look up port type
1989 \begin_layout Itemize
1990 Syntax: string input.port_type(number port)
1993 \begin_layout Standard
1994 Return type of specified port.
1997 \begin_layout Subsection
1998 input.controller_info: Get information about controller
2001 \begin_layout Itemize
2002 Syntax: table input.controller_info(number port, number controller)
2005 \begin_layout Standard
2006 Get controller info for specified controller.
2007 If controller does not exist, returns nil.
2008 Otherwise returns a table with following fields:
2011 \begin_layout Itemize
2012 type (string): Type of the controller.
2015 \begin_layout Itemize
2016 class (string): Class of the controller.
2019 \begin_layout Itemize
2020 classnum (number): Number of the controller within its class (1-based)
2023 \begin_layout Itemize
2024 lcid (number): Logical controller number of the controller.
2027 \begin_layout Itemize
2028 button_count (number): Number of buttons on controller
2031 \begin_layout Itemize
2032 buttons (array): Array of following info about each button:
2036 \begin_layout Itemize
2037 type (string): Type of button.
2039 \begin_inset Quotes eld
2043 \begin_inset Quotes erd
2047 \begin_inset Quotes eld
2051 \begin_inset Quotes erd
2055 \begin_inset Quotes eld
2059 \begin_inset Quotes erd
2063 \begin_inset Quotes eld
2067 \begin_inset Quotes erd
2073 \begin_layout Itemize
2074 name (string): Name of button.
2077 \begin_layout Itemize
2078 symbol (string): Symbol of button.
2079 Only present for type
2080 \begin_inset Quotes eld
2084 \begin_inset Quotes erd
2090 \begin_layout Itemize
2091 hidden (boolean): True if hidden button.
2096 \begin_layout Subsection
2097 input.veto_button: Veto a button press
2100 \begin_layout Itemize
2101 Syntax: none input.veto_button()
2104 \begin_layout Standard
2105 Signals that the button event should be vetoed.
2106 Only valid in on_button callback.
2109 \begin_layout Subsection
2110 input.geta: Get all buttons for controller (deprecated)
2113 \begin_layout Itemize
2114 Syntax: (number, number...) input.geta(number controller)
2117 \begin_layout Standard
2118 Get input state for entiere controller.
2119 Returns n return values.
2122 \begin_layout Itemize
2123 1st return value: Bitmask: bit i is set if i:th index is nonzero
2126 \begin_layout Itemize
2127 2nd- return value: value of i:th index.
2130 \begin_layout Subsection
2131 input.seta: Set all buttons for controller (deprecated)
2134 \begin_layout Itemize
2135 Syntax: none input.seta(number controller, number bitmask, number args...)
2138 \begin_layout Standard
2139 Set state for entiere controller.
2140 args is up to N values for indices (overriding values in bitmask if specified).
2143 \begin_layout Subsection
2144 input.controllertype: Get controller type (deprecated)
2147 \begin_layout Itemize
2148 syntax: string input.controllertype(number controller)
2151 \begin_layout Standard
2152 Get the type of controller as string.
2155 \begin_layout Subsection
2156 input.reset: Execute (delayed) reset
2159 \begin_layout Itemize
2160 Syntax: none input.reset([number cycles])
2163 \begin_layout Standard
2165 If <cycles> is greater than zero, do delayed reset.
2166 0 (or no value) causes immediate reset.
2169 \begin_layout Itemize
2170 Note: Only available with subframe flag false.
2173 \begin_layout Subsection
2174 input.raw: Return raw input data
2177 \begin_layout Itemize
2178 Syntax: table input.raw()
2181 \begin_layout Standard
2182 Returns table of tables of all available keys and axes.
2183 The first table is indexed by key name (platform-dependent!), and the inner
2184 table has the following fields:
2187 \begin_layout Itemize
2188 value: Last reported value for control
2192 \begin_layout Itemize
2193 For keys: 1 for pressed, 0 for released.
2196 \begin_layout Itemize
2197 For axes: -32767...32767.
2200 \begin_layout Itemize
2201 For presure-sensitive buttons: 0...32767.
2204 \begin_layout Itemize
2205 For hats: Bitmask: 1=>Up, 2=>Right, 4=>Down, 8=>Left.
2208 \begin_layout Itemize
2209 For mouse: Coordinates relative to game area.
2213 \begin_layout Itemize
2214 ktype: Type of key (disabled, key, mouse, axis, hat, pressure).
2217 \begin_layout Subsection
2218 input.keyhook: Hook a key
2221 \begin_layout Itemize
2222 Syntax: none input.keyhook(string key, boolean state)
2225 \begin_layout Standard
2226 Requests that keyhook events to be sent for key <key> (<state>=true) or
2227 not sent (<state>=false).
2230 \begin_layout Subsection
2231 input.joyget: Get controls for controller
2234 \begin_layout Itemize
2235 Syntax: table input.joyget(number logical)
2238 \begin_layout Standard
2239 Returns table for current controls for specified logical controller <logical>.
2240 The names of fields vary by controller type.
2243 \begin_layout Itemize
2244 The buttons have the same name as those are referred to in other contexts
2248 \begin_layout Itemize
2249 The analog axes are usually
2250 \begin_inset Quotes eld
2254 \begin_inset Quotes erd
2258 \begin_inset Quotes eld
2262 \begin_inset Quotes erd
2268 \begin_layout Itemize
2269 Each field is numeric or boolean depending on axis/button.
2272 \begin_layout Subsection
2273 input.joyset: Set controls for controller
2276 \begin_layout Itemize
2277 Syntax: none input.joyset(number controller, table controls)
2280 \begin_layout Standard
2281 Set the the state of specified controller to values specified in specified
2285 \begin_layout Itemize
2286 Each field can be boolean or number.
2289 \begin_layout Itemize
2290 Also, buttons allow strings, which cause value to be inverted.
2293 \begin_layout Subsection
2294 input.lcid_to_pcid: Look up logical controller (deprecated)
2297 \begin_layout Itemize
2298 Syntax: (number, number, number) input.lcid_to_pcid(number lcid)
2301 \begin_layout Standard
2302 Returns the legacy pcid for controller (or false if there isn't one), followed
2304 Returns nothing if controller does not exist.
2307 \begin_layout Standard
2308 \begin_inset Newpage pagebreak
2314 \begin_layout Section
2318 \begin_layout Standard
2319 Various keybinding-related functions
2322 \begin_layout Subsection
2323 keyboard.bind: Bind a key
2326 \begin_layout Itemize
2327 Syntax: none keyboard.bind(string mod, string mask, string key, string cmd)
2330 \begin_layout Standard
2331 Bind specified key with specified modifers to specified command.
2334 \begin_layout Subsection
2335 keyboard.unbind: Unbind a key
2338 \begin_layout Itemize
2339 Syntax: none keyboard.unbind(string mod, string mask, string key)
2342 \begin_layout Standard
2343 Unbind specified key with specified modifers.
2346 \begin_layout Subsection
2347 keyboard.alias: Set alias expansion
2350 \begin_layout Itemize
2351 Syntax: none keyboard.alias(string alias, string expansion)
2354 \begin_layout Standard
2355 Set expansion of given command.
2358 \begin_layout Standard
2359 \begin_inset Newpage pagebreak
2365 \begin_layout Section
2369 \begin_layout Standard
2373 \begin_layout Subsection
2374 subtitle.byindex: Look up start and length of subtitle by index
2377 \begin_layout Itemize
2378 Syntax: (number, number) subtitle.byindex(number i)
2381 \begin_layout Standard
2382 Read the frame and length of ith subtitle.
2383 Returns nothing if not present.
2386 \begin_layout Subsection
2387 subtitle.set: Write a subtitle
2390 \begin_layout Itemize
2391 Syntax: none subtitle.set(number f, number l, string txt)
2394 \begin_layout Standard
2395 Set the text of subtitle.
2398 \begin_layout Subsection
2399 subtitle.get: Read a subtitle
2402 \begin_layout Itemize
2403 Syntax: string subtitle.get(number f, number l)
2406 \begin_layout Standard
2407 Get the text of subtitle.
2410 \begin_layout Subsection
2411 subtitle.delete: Delete a subtitle
2414 \begin_layout Itemize
2415 Syntax: nonesubtitle.delete(number f, number l)
2418 \begin_layout Standard
2419 Delete specified subtitle.
2422 \begin_layout Standard
2423 \begin_inset Newpage pagebreak
2429 \begin_layout Section
2433 \begin_layout Standard
2434 Host memory handling (extra memory saved to savestates).
2435 Host memory starts empty.
2438 \begin_layout Itemize
2439 Reads out of range return false.
2442 \begin_layout Itemize
2443 Writes out of range extend the memory.
2446 \begin_layout Subsection
2447 hostmemory.read: Read byte from host memory
2450 \begin_layout Itemize
2451 Syntax: number hostmemory.read(number address)
2454 \begin_layout Standard
2455 Reads byte from hostmemory slot address <address>.
2458 \begin_layout Subsection
2459 hostmemory.write: Write byte to host memory
2462 \begin_layout Itemize
2463 Syntax: none hostmemory.write(number address, number value)
2466 \begin_layout Standard
2467 Writes hostmemory slot with value <value> 0-255.
2470 \begin_layout Subsection
2471 hostmemory.read{,s}{byte,{,h,d,q}word}: Read from host memory
2474 \begin_layout Itemize
2475 Syntax: number hostmemory.readbyte(number address)
2478 \begin_layout Itemize
2479 Syntax: number hostmemory.readsbyte(number address)
2482 \begin_layout Itemize
2483 Syntax: number hostmemory.readword(number address)
2486 \begin_layout Itemize
2487 Syntax: number hostmemory.readsword(number address)
2490 \begin_layout Itemize
2491 Syntax: number hostmemory.readhword(number address)
2494 \begin_layout Itemize
2495 Syntax: number hostmemory.readshword(number address)
2498 \begin_layout Itemize
2499 Syntax: number hostmemory.readdword(number address)
2502 \begin_layout Itemize
2503 Syntax: number hostmemory.readsdword(number address)
2506 \begin_layout Itemize
2507 Syntax: number hostmemory.readqword(number address)
2510 \begin_layout Itemize
2511 Syntax: number hostmemory.readsqword(number address)
2514 \begin_layout Standard
2515 Read elements (big-endian) from given address <address>.
2518 \begin_layout Itemize
2522 \begin_layout Itemize
2526 \begin_layout Itemize
2530 \begin_layout Itemize
2534 \begin_layout Itemize
2535 qword is 8 elements.
2538 \begin_layout Itemize
2539 The 's' variants do signed read.
2542 \begin_layout Subsection
2543 hostmemory.read{float,double}: Read from host memory
2546 \begin_layout Itemize
2547 syntax: number hostmemory.readfloat(number address)
2550 \begin_layout Itemize
2551 Syntax: number hostmemory.readdouble(number address)
2554 \begin_layout Standard
2555 Read elements (big-endian) floating-pont from given address <address>.
2558 \begin_layout Subsection
2559 hostmemory.write{,s}{byte,{,h,d,q}word}: Write to host memory
2562 \begin_layout Itemize
2563 Syntax: number hostmemory.writebyte(number address, number value)
2566 \begin_layout Itemize
2567 Syntax: number hostmemory.writesbyte(number address, number value)
2570 \begin_layout Itemize
2571 Syntax: number hostmemory.writeword(number address, number value)
2574 \begin_layout Itemize
2575 Syntax: number hostmemory.writesword(number address, number value)
2578 \begin_layout Itemize
2579 Syntax: number hostmemory.writehword(number address, number value)
2582 \begin_layout Itemize
2583 Syntax: number hostmemory.writeshword(number address, number value)
2586 \begin_layout Itemize
2587 Syntax: number hostmemory.writedword(number address, number value)
2590 \begin_layout Itemize
2591 Syntax: number hostmemory.writesdword(number address, number value)
2594 \begin_layout Itemize
2595 Syntax: number hostmemory.writeqword(number address, number value)
2598 \begin_layout Itemize
2599 Syntax: number hostmemory.writesqword(number address, number value)
2602 \begin_layout Standard
2603 Write value <value> to elements (little-endian) starting from given address
2607 \begin_layout Itemize
2611 \begin_layout Itemize
2615 \begin_layout Itemize
2619 \begin_layout Itemize
2623 \begin_layout Itemize
2624 qword is 8 elements.
2627 \begin_layout Itemize
2628 The 's' variants do signed write.
2631 \begin_layout Subsection
2632 hostmemory.write{float,double}: Write to host memory
2635 \begin_layout Itemize
2636 syntax: none hostmemory.readfloat(number address, number value)
2639 \begin_layout Itemize
2640 Syntax: none hostmemory.readdouble(number address, number value)
2643 \begin_layout Standard
2644 Write elements (big-endian) floating-pont to given address <address>, storing
2648 \begin_layout Standard
2649 \begin_inset Newpage pagebreak
2655 \begin_layout Section
2659 \begin_layout Standard
2663 \begin_layout Subsection
2664 movie.currentframe: Get current frame number
2667 \begin_layout Itemize
2668 Syntax: number movie.currentframe()
2671 \begin_layout Standard
2672 Return number of current frame.
2675 \begin_layout Subsection
2676 movie.framecount: Get move frame count
2679 \begin_layout Itemize
2680 Syntax: number movie.framecount()
2683 \begin_layout Standard
2684 Return number of frames in movie.
2687 \begin_layout Subsection
2688 movie.readonly: Is in readonly mode?
2691 \begin_layout Itemize
2692 Syntax: boolean movie.readonly()
2695 \begin_layout Standard
2696 Return true if in readonly mode, false if in readwrite.
2699 \begin_layout Subsection
2700 movie.rerecords: Movie rerecord count
2703 \begin_layout Itemize
2704 Syntax: number movie.rerecords()
2707 \begin_layout Standard
2708 Returns the current value of rerecord count.
2711 \begin_layout Subsection
2712 movie.set_readwrite: Set read-write mode.
2715 \begin_layout Itemize
2716 Syntax: none movie.set_readwrite()
2719 \begin_layout Standard
2720 Set readwrite mode (does not cause on_readwrite callback).
2723 \begin_layout Subsection
2724 movie.frame_subframes: Count subframes in frame
2727 \begin_layout Itemize
2728 Syntax: number movie.frame_subframes(number frame)
2731 \begin_layout Standard
2732 Count number of subframes in specified frame <frame> (frame numbers are
2733 1-based) and return that.
2736 \begin_layout Subsection
2737 movie.read_subframes: Read subframe data (deprecated)
2740 \begin_layout Itemize
2741 Syntax: table movie.read_subframes(number frame, number subframe)
2744 \begin_layout Standard
2745 Read specifed subframe in specified frame and return data as array.
2748 \begin_layout Subsection
2749 movie.read_rtc: Read current RTC time
2752 \begin_layout Itemize
2753 Syntax: (number, number) movie.read_rtc()
2756 \begin_layout Standard
2757 Returns the current value of the RTC as a pair (second, subsecond).
2760 \begin_layout Subsection
2761 movie.unsafe_rewind: Fast movie rewind to saved state
2764 \begin_layout Itemize
2765 Syntax: none movie.unsafe_rewind([UNSAFEREWIND state])
2768 \begin_layout Standard
2769 Start setting point for unsafe rewind or jump to point of unsafe rewind.
2772 \begin_layout Itemize
2773 If called without argument, causes emulator to start process of setting
2774 unsafe rewind point.
2775 When this has finished, callback on_set_rewind occurs, passing the rewind
2776 state to lua script.
2779 \begin_layout Itemize
2780 If called with argument, causes emulator rewind to passed rewind point as
2782 Readwrite mode is implicitly activated.
2785 \begin_layout Standard
2786 The following warnings apply to unsafe rewinding:
2789 \begin_layout Itemize
2790 There are no safety checks against misuse (that's what
2791 \begin_inset Quotes eld
2795 \begin_inset Quotes erd
2801 \begin_layout Itemize
2802 Only call rewind from timeline rewind point was set from.
2805 \begin_layout Itemize
2806 Only call rewind from after the rewind point was set.
2809 \begin_layout Subsection
2810 movie.to_rewind: Load savestate as rewind point
2813 \begin_layout Itemize
2814 Syntax: UNSAFEREWIND movie.to_rewind(string filename)
2817 \begin_layout Standard
2818 Load specified savestate file <filename> as rewind point and return UNSAFEREWIND
2819 corresponding to it.
2822 \begin_layout Itemize
2823 Note: This operation does not take emulated time.
2826 \begin_layout Subsection
2827 movie.copy_movie/INPUTMOVIE::copy_movie: Copy movie to movie object
2830 \begin_layout Itemize
2831 Syntax: INPUTMOVIE movie.copy_movie([INPUTMOVIE movie])
2834 \begin_layout Itemize
2835 Syntax: INPUTMOVIE INPUTMOVIE::copy_movie()
2838 \begin_layout Standard
2839 Copies specified movie <movie>/current object (if none or nil, the active
2840 movie) as new movie object.
2843 \begin_layout Subsection
2844 movie.get_frame/INPUTMOVIE::get_frame: Read specified frame in movie.
2847 \begin_layout Itemize
2848 Syntax: INPUTFRAME movie.get_frame([INPUTMOVIE movie,] number frame)
2851 \begin_layout Itemize
2852 Syntax: INPUTFRAME INPUTMOVIE::get_frame(number frame);
2855 \begin_layout Standard
2856 Get INPUTFRAME object corresponding to specified frame in specified movie.
2859 \begin_layout Subsection
2860 movie.set_frame/INPUTMOVIE::set_frame: Write speicifed frame in movie.
2863 \begin_layout Itemize
2864 Syntax: none movie.set_frame([INPUTMOVIE movie,] number frame, INPUTFRAME
2868 \begin_layout Itemize
2869 Syntax: none INPUTMOVIE::set_frame(number frame, INPUTFRAME data)
2872 \begin_layout Standard
2873 Set data in specified frame.
2876 \begin_layout Itemize
2877 Note: Past can't be edited in active movie.
2880 \begin_layout Subsection
2881 movie.get_size/INPUTMOVIE::get_size: Get size of movie
2884 \begin_layout Itemize
2885 Syntax: integer movie.get_size([INPUTMOVIE movie])
2888 \begin_layout Itemize
2889 Syntax: integer INPUTMOVIE::get_size()
2892 \begin_layout Standard
2893 Return number of subframes in specified movie.
2896 \begin_layout Subsection
2897 movie.count_frames/INPUTMOVIE::count_frames: Count frames in movie
2900 \begin_layout Itemize
2901 Syntax: number movie.count_frames([INPUTMOVIE movie])
2904 \begin_layout Itemize
2905 Syntax: number INPUTMOVIE::count_frames()
2908 \begin_layout Standard
2909 Return number of frames in movie.
2912 \begin_layout Subsection
2913 movie.find_frame/INPUTMOVIE::find_frame: Find subframe corresponding to frame
2916 \begin_layout Itemize
2917 Syntax: number movie.find_frame([INPUTMOVIE movie], number frame)
2920 \begin_layout Itemize
2921 Syntax: number INPUTMOVIE::find_frame(number frame)
2924 \begin_layout Standard
2925 Returns starting subframe of given frame (frame numbers are 1-based).
2926 Returns -1 if frame number is bad.
2929 \begin_layout Subsection
2930 movie.blank_frame/INPUTMOVIE::blank_frame: Return a blank frame
2933 \begin_layout Itemize
2934 Syntax: INPUTFRAME movie.blank_frame([INPUTMOVIE movie])
2937 \begin_layout Itemize
2938 Syntax: INPUTFRAME INPUTMOVIE::blank_frame()
2941 \begin_layout Standard
2942 Return blank INPUTFRAME with frame type from specified movie.
2945 \begin_layout Subsection
2946 movie.append_frames/INPUTMOVIE::append_frames: Append blank frames
2949 \begin_layout Itemize
2950 Syntax: none movie.append_frames([INPUTMOVIE movie,] number frames)
2953 \begin_layout Itemize
2954 Syntax: none INPUTMOVIE::append_frames(number frames)
2957 \begin_layout Standard
2958 Append specified number <frames> of frames.
2961 \begin_layout Subsection
2962 movie.append_frame/INPUTMOVIE::append_frame: Append a frame
2965 \begin_layout Itemize
2966 Syntax: none movie.append_frame([INPUTMOVIE movie,] INPUTFRAME frame)
2969 \begin_layout Itemize
2970 Syntax: none INPUTMOVIE::append_frame(INPUTFRAME frame)
2973 \begin_layout Standard
2974 Append specified frame <frame>.
2975 Past of current movie can't be edited.
2978 \begin_layout Subsection
2979 movie.truncate/INPUTMOVIE::truncate: Truncate a movie.
2982 \begin_layout Itemize
2983 Syntax: none movie.truncate([INPUTMOVIE movie,] number frames)
2986 \begin_layout Itemize
2987 Syntax: none INPUTMOVIE::truncate(number frames)
2990 \begin_layout Standard
2991 Truncate the specified movie to specified number of frames.
2994 \begin_layout Subsection
2995 movie.edit/INPUTMOVIE::edit: Edit a movie
2998 \begin_layout Itemize
2999 Syntax: none movie.edit([INPUTMOVIE movie,] number frame, number port, number
3000 controller, number control, number/bool value)
3003 \begin_layout Itemize
3004 Syntax: none INPUTMOVIE::edit(number frame, number port, number controller,
3005 number control, number/bool value)
3008 \begin_layout Standard
3009 Change specified control in specified frame in specified movie.
3010 Past can't be edited in active movie.
3013 \begin_layout Subsection
3014 movie.copy_frames2: Copy frames between movies
3017 \begin_layout Itemize
3018 Syntax: none movie.copy_frames2([INPUTMOVIE dstmov,] number dst, [INPUTMOVIE
3019 srcmov,] number src, number count)
3022 \begin_layout Standard
3023 Copy specified number of frames between two movies.
3024 The copy proceeeds in forward direction.
3027 \begin_layout Subsection
3028 movie.copy_frames/INPUTMOVIE::copy_frames: Copy frames in movie
3031 \begin_layout Itemize
3032 Syntax: none movie.copy_frames([INPUTMOVIE mov,] number dst, number src,
3033 number count, bool backwards)
3036 \begin_layout Itemize
3037 Syntax: none INPUTMOVIE::copy_frames(number dst, number src, number count,
3041 \begin_layout Standard
3042 Copy specified number of frames from one point in movie to another.
3043 If backwards is true, the copy will be done backwards.
3046 \begin_layout Subsection
3047 movie.serialize/INPUTMOVIE::serialize: Serialize movie
3050 \begin_layout Itemize
3051 Syntax: none movie.serialize([INPUTMOVIE movie,] string filename, bool binary)
3054 \begin_layout Itemize
3055 Syntax: none INPUTMOIVE::serialize(string filename, bool binary)
3058 \begin_layout Standard
3059 Serialize given movie into file.
3060 If binary is true, binary format (more compact and much faster) is used.
3063 \begin_layout Subsection
3064 movie.unserialize: Unserialize movie
3067 \begin_layout Itemize
3068 Syntax: INPUTMOVIE movie.unserialize(INPUTFRAME template, string filename,
3072 \begin_layout Standard
3073 Unserialize movie from file.
3074 The given frame is used as template to decide the frame type.
3075 If binary is true, binary format is decoded (much faster).
3078 \begin_layout Subsection
3079 movie.current_first_subframe: Return first subframe in current frame
3082 \begin_layout Itemize
3083 Syntax: number movie.current_first_subframe()
3086 \begin_layout Standard
3087 Returns first subframe in current frame.
3090 \begin_layout Subsection
3091 movie.pollcounter: Return poll counter for speified control
3094 \begin_layout Itemize
3095 Syntax: number movie.pollcounter(number port, number controller, number control)
3098 \begin_layout Standard
3099 Returns number of times the specified control has been polled this frame.
3102 \begin_layout Subsection
3103 INPUTFRAME::get_button: Get button
3106 \begin_layout Itemize
3107 Syntax: boolean INPUTFRAME::get_button(number port, number controller, number
3111 \begin_layout Standard
3112 Returns state of given button as boolean.
3115 \begin_layout Subsection
3116 INPUTFRAME::get_axis: Get axis
3119 \begin_layout Itemize
3120 Syntax: number INPUTFRAME::get_axis(number port, number controller, number
3124 \begin_layout Standard
3125 Returns state of given axis as number.
3128 \begin_layout Subsection
3129 INPUTFRAME::set_button/INPUTFRAME::set_axis: Set button or axis
3132 \begin_layout Itemize
3133 Syntax: none INPUTFRAME::set_button(number port, number controller, number
3134 control, number/bool value)
3137 \begin_layout Itemize
3138 Syntax: none INPUTFRAME::set_axis(number port, number controller, number
3142 \begin_layout Standard
3143 Set the given button/axis to given value.
3146 \begin_layout Subsection
3147 INPUTFRAME::serialize: Serialize a frame
3150 \begin_layout Itemize
3151 Syntax: string INPUTFRAME::serialize()
3154 \begin_layout Standard
3155 Return string representation of frame.
3158 \begin_layout Subsection
3159 INPUTFRAME::unserialize: Unserialize a frame
3162 \begin_layout Itemize
3163 Syntax: none INPUTFRAME::unserialize(string data)
3166 \begin_layout Standard
3167 Set current frame from given data.
3170 \begin_layout Subsection
3171 INPUTFRAME::get_stride: Get movie stride
3174 \begin_layout Itemize
3175 Syntax: number INPUTFRAME::get_stride()
3178 \begin_layout Standard
3179 Return number of bytes needed to store the input frame.
3180 Mainly useful for some debugging.
3183 \begin_layout Standard
3184 \begin_inset Newpage pagebreak
3190 \begin_layout Section
3194 \begin_layout Standard
3195 Routines for settings manipulation
3198 \begin_layout Subsection
3199 settings.get: Get value of setting
3202 \begin_layout Itemize
3203 Syntax: string settings.get(string name)
3206 \begin_layout Standard
3207 Get value of setting <name>.
3208 If setting value can't be obtained, returns (nil, error message).
3211 \begin_layout Subsection
3212 settings.set: Set value of setting
3215 \begin_layout Itemize
3216 Syntax: none settings.set(string name, string value)
3219 \begin_layout Standard
3220 Set value <value> of setting <name>.
3221 If setting can't be set, returns (nil, error message).
3224 \begin_layout Standard
3225 \begin_inset Newpage pagebreak
3231 \begin_layout Section
3235 \begin_layout Standard
3236 Contains various functions for managing memory
3239 \begin_layout Subsection
3240 memory.vma_count: Count number of VMAs.
3243 \begin_layout Itemize
3244 Syntax: number memory.vma_count()
3247 \begin_layout Standard
3248 Returns the number of VMAs
3251 \begin_layout Subsection
3252 memory.read_vma: Lookup VMA info by index
3255 \begin_layout Itemize
3256 Syntax: string memory.read_vma(number index)
3259 \begin_layout Standard
3260 Reads the specified VMA (indices start from zero).
3261 Trying to read invalid VMA gives nil.
3262 The read VMA is table with the following fields:
3265 \begin_layout Itemize
3266 region_name (string): The readable name of the VMA
3269 \begin_layout Itemize
3270 baseaddr (number): Base address of the VMA
3273 \begin_layout Itemize
3274 lastaddr (number): Last address in the VMA.
3277 \begin_layout Itemize
3278 size (number): The size of VMA in bytes.
3281 \begin_layout Itemize
3282 readonly (boolean): True of the VMA corresponds to ROM.
3285 \begin_layout Itemize
3286 iospace (boolean): True if the VMA is I/O space.
3289 \begin_layout Itemize
3290 native_endian (boolean): True if the VMA has native endian as opposed to
3294 \begin_layout Subsection
3295 memory.find_vma: Find VMA info by address
3298 \begin_layout Itemize
3299 Syntax: table memory.find_vma(number address)
3302 \begin_layout Standard
3303 Finds the VMA containing specified address.
3304 Returns table in the same format as read_vma or nil if not found.
3307 \begin_layout Subsection
3308 memory.read{,s}{byte,{,h,d,q}word}: Read memory
3311 \begin_layout Itemize
3312 Syntax: none memory.readbyte([string vma, ]number address)
3315 \begin_layout Itemize
3316 Syntax: none memory.readword([string vma, ]number address)
3319 \begin_layout Itemize
3320 Syntax: none memory.readhword([string vma, ]number address)
3323 \begin_layout Itemize
3324 Syntax: none memory.readdword([string vma, ]number address)
3327 \begin_layout Itemize
3328 Syntax: none memory.readqword([string vma, ]number address)
3331 \begin_layout Itemize
3332 Syntax: none memory.readsbyte([string vma, ]number address)
3335 \begin_layout Itemize
3336 Syntax: none memory.readsword([string vma, ]number address)
3339 \begin_layout Itemize
3340 Syntax: none memory.readshword([string vma, ]number address)
3343 \begin_layout Itemize
3344 Syntax: none memory.readsdword([string vma, ]number address)
3347 \begin_layout Itemize
3348 Syntax: none memory.readsqword([string vma, ]number address)
3351 \begin_layout Standard
3352 Reads the specified address <address> (if 's' variant is used, do undergo
3356 \begin_layout Subsection
3357 memory.{,s}read_sg: Scatter/Gather read memory
3360 \begin_layout Itemize
3361 Syntax: none memory.read_sg(string/boolean/number...)
3364 \begin_layout Itemize
3365 Syntax: none memory.sread_sg(string/boolean/number...)
3368 \begin_layout Standard
3369 Perform (2s complement signed if using memory.sread_sg) scatter/gather read
3371 Each argument can be string, boolean or number:
3374 \begin_layout Itemize
3375 String: Set VMA addresses are relative to (e.g.
3379 \begin_layout Itemize
3380 boolean: If true, increment relative address by 1, if false, decrement by
3382 The new address is read as next higher byte.
3385 \begin_layout Itemize
3386 integer: Set the relative address to specified value and read the address
3387 as next higher byte.
3390 \begin_layout Subsection
3391 memory.write_sg: Scatter/Gather write memory
3394 \begin_layout Itemize
3395 Syntax: none memory.write_sg(number value, string/boolean/number...)
3398 \begin_layout Standard
3399 Perform scatter/gather write of value <value> on memory.
3400 Each argument can be string, boolean or number:
3403 \begin_layout Itemize
3404 String: Set VMA addresses are relative to (e.g.
3408 \begin_layout Itemize
3409 boolean: If true, increment relative address by 1, if false, decrement by
3411 The new address is read as next higher byte.
3414 \begin_layout Itemize
3415 integer: Set the relative address to specified value and read the address
3416 as next higher byte.
3419 \begin_layout Subsection
3420 memory.read{float,double}: Read memory
3423 \begin_layout Itemize
3424 Syntax: none memory.readfloat([string vma, ]number address)
3427 \begin_layout Itemize
3428 Syntax: none memory.readdouble([string vma, ]number address)
3431 \begin_layout Standard
3432 Reads the specified address <address>
3435 \begin_layout Subsection
3436 memory.write{byte,{,h,d,q}word,float,double}: Write memory
3439 \begin_layout Itemize
3440 Syntax: none memory.writebyte([string vma, ]number address, number value)
3443 \begin_layout Itemize
3444 Syntax: none memory.writeword([string vma, ]number address, number value)
3447 \begin_layout Itemize
3448 Syntax: none memory.writehword([string vma, ]number address, number value)
3451 \begin_layout Itemize
3452 Syntax: none memory.writedword([string vma, ]number address, number value)
3455 \begin_layout Itemize
3456 Syntax: none memory.writeqword([string vma, ]number address, number value)
3459 \begin_layout Itemize
3460 Syntax: none memory.writefloat([string vma, ]number address, number value)
3463 \begin_layout Itemize
3464 Syntax: none memory.writedouble([string vma, ]number address, number value)
3467 \begin_layout Standard
3468 Writes the specified value <value> (negative integer values undergo 2's
3469 complement) to specified address <address>.
3472 \begin_layout Subsection
3473 memory.map{{,s}{byte,{,h,d,q}word},float,double}: Map an array
3476 \begin_layout Itemize
3477 Syntax: userdata memory.map<type>([[string vma, ]number base, number size])
3480 \begin_layout Standard
3481 Returns a table mapping specified memory aperture for read/write.
3482 If parameters are omitted, entiere map space is the aperture.
3485 \begin_layout Itemize
3486 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
3487 qword, sqword, float or double.
3490 \begin_layout Subsection
3491 memory.hash_region: Hash region of memory
3494 \begin_layout Itemize
3495 Syntax: string memory.hash_region([string vma, ]number base, number size)
3498 \begin_layout Standard
3499 Hash specified number of bytes starting from specified address and return
3503 \begin_layout Subsection
3504 memory.hash_state: Hash system state
3507 \begin_layout Itemize
3508 Syntax: string memory.hash_state()
3511 \begin_layout Standard
3512 Hash the current system state.
3513 Mainly useful for debugging savestates.
3516 \begin_layout Subsection
3517 memory.readregion: Read region of memory
3520 \begin_layout Itemize
3521 Syntax: table memory.readregion([string vma, ]number base, number size)
3524 \begin_layout Standard
3525 Read a region of memory.
3528 \begin_layout Itemize
3529 Warning: If the region crosses VMA boundary, the results are undefined.
3532 \begin_layout Subsection
3533 memory.writeregion: Write region of memory
3536 \begin_layout Itemize
3537 Syntax: none memory.writeregion([string vma, ]number base, number size, table
3541 \begin_layout Standard
3542 Write a region of memory.
3545 \begin_layout Itemize
3546 Warning: If the region crosses VMA boundary, the results are undefined.
3549 \begin_layout Subsection
3550 memory.map_structure: Create mmap structure
3553 \begin_layout Itemize
3554 syntax: MMAP_STRUCT memory.map_structure()
3557 \begin_layout Standard
3558 Returns a new mapping structure (MMAP_STRUCT)
3561 \begin_layout Subsection
3562 MMAP_STRUCT(): Bind key in mmap structure
3565 \begin_layout Itemize
3566 Syntax: none MMAP_STRUCT(string key, [string vma, ]number address, string
3570 \begin_layout Standard
3571 Bind key <key> in mmap structure to specified address <address> with specified
3575 \begin_layout Itemize
3576 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
3577 qword, sqword, float or double.
3580 \begin_layout Subsection
3581 memory.read_expr: Evaluate memory watch expression
3584 \begin_layout Itemize
3585 Syntax: string memory.read_expr(string expr)
3588 \begin_layout Standard
3589 Evaluate specified watch expression and return result
3592 \begin_layout Subsection
3593 memory.action: Run core action
3596 \begin_layout Itemize
3597 memory.action(string action, [<params>])
3600 \begin_layout Standard
3602 The different models expect parameters as:
3605 \begin_layout Itemize
3609 \begin_layout Itemize
3613 \begin_layout Itemize
3617 \begin_layout Itemize
3621 \begin_layout Itemize
3625 \begin_layout Subsection
3626 memory.get_lag_flag: Get lag flag
3629 \begin_layout Itemize
3630 Syntax: boolean memory.get_lag_flag()
3633 \begin_layout Standard
3634 Get the value of core lag flag.
3635 True if this frame has been lag so far, false if poll has been detected.
3638 \begin_layout Subsection
3639 memory.set_lag_flag: Set lag flag
3642 \begin_layout Itemize
3643 Syntax: none memory.set_lag_flag(boolean flag)
3646 \begin_layout Standard
3647 Set the value of core lag flag.
3648 This flag automatically gets cleared if poll is detected, but can be forcibly
3649 set or cleared if game so requires.
3652 \begin_layout Itemize
3653 Should only be used in on_frame_emulated callback.
3656 \begin_layout Itemize
3657 Setting or clearing this affects the emulator lag counter.
3660 \begin_layout Standard
3661 \begin_inset Newpage pagebreak
3667 \begin_layout Section
3671 \begin_layout Standard
3672 Contains newer memory functions.
3675 \begin_layout Subsection
3676 memory2(): Get all VMA names.
3679 \begin_layout Itemize
3680 Syntax: table memory2()
3683 \begin_layout Standard
3684 Returns array of all valid VMA names.
3687 \begin_layout Subsection
3688 memory2.<vma>:info: Get VMA info
3691 \begin_layout Itemize
3692 Syntax: table memory2.<vma>:info()
3695 \begin_layout Standard
3696 Return table describing given VMA.
3697 Includes fields address, size, last, readonly, special and endian.
3700 \begin_layout Subsection
3701 memory2.<vma>:<op>: Read/Write memory
3704 \begin_layout Itemize
3705 Syntax: none memory2.<vma>:<op>(number offset, number value)
3708 \begin_layout Itemize
3709 Syntax: number memory2.<vma>:<op>(number offset)
3712 \begin_layout Standard
3713 Read/Write value from/to given VMA <vma> at given offset <offset> (must
3715 The value written is <value>.
3716 <Op> is of form: [i][s]<type>, where:
3719 \begin_layout Itemize
3720 <type> is one of 'byte', 'word', 'hword', 'dword', 'qword', 'float', 'double'.
3723 \begin_layout Itemize
3724 'i' signifies that the value is treated as opposite-to-normal endianess,
3727 \begin_layout Itemize
3728 's' signifies that value is treated as signed (not available for floating-point).
3731 \begin_layout Subsection
3732 memory2.<vma>:read: Scatter-gather value read
3735 \begin_layout Itemize
3736 Syntax: number memory2.<vma>:read(number addr...)
3739 \begin_layout Standard
3740 Read value from given VMA <vma> at byte offsets <addr>..., given in order of
3741 increasing significance.
3742 Value of true and false are special.
3743 True increments address by 1, and false decrements address by 1.
3746 \begin_layout Subsection
3747 memory2.<vma>:sread: Signed scatter-gather value read
3750 \begin_layout Itemize
3751 Syntax: number memory2.<vma>:sread(number addr...)
3754 \begin_layout Standard
3755 Like memory2.<vma>:read, but reads signed values.
3758 \begin_layout Subsection
3759 memory2.<vma>:write: Scatter-gather value write
3762 \begin_layout Itemize
3763 Syntax: number memory2.<vma>:write(number val, number addr...)
3766 \begin_layout Standard
3767 Write value <val> to given VMA <vma> at byte offsets <addr>..., given in order
3768 of increasing significance.
3769 Value of true and false are special.
3770 True increments address by 1, and false decrements address by 1.
3773 \begin_layout Standard
3774 \begin_inset Newpage pagebreak
3780 \begin_layout Section
3784 \begin_layout Standard
3785 Various callback-related functions.
3788 \begin_layout Subsection
3789 \begin_inset CommandInset label
3791 name "sub:callback.register:-Register-a"
3795 callback.register: Register a callback
3798 \begin_layout Itemize
3799 Syntax: function callback.register(string cbname, function cbfun);
3802 \begin_layout Standard
3803 Instruct function <cbfun> to be added to list of callbacks to call on event
3804 <cbname> (See section
3805 \begin_inset CommandInset ref
3807 reference "sec:Callbacks"
3812 The callback name does not have the 'on_' prefix (e.g.
3814 \begin_inset Quotes eld
3818 \begin_inset Quotes erd
3825 \begin_layout Subsection
3826 \begin_inset CommandInset label
3828 name "sub:callback.unregister:-Unregister-"
3832 callback.unregister: Unregister a callback
3835 \begin_layout Itemize
3836 Syntax: function callback.unregister(string cbname, function cbfun);
3839 \begin_layout Standard
3840 Instruct function <cbfun> to be removed from list of callbacks to call on
3844 \begin_layout Subsection
3845 callback.<cbname>:register: Register callback
3848 \begin_layout Itemize
3849 Syntax: function callback.<cbname>:register(function cbfun)
3852 \begin_layout Standard
3853 Synonym for callback.register (section
3854 \begin_inset CommandInset ref
3856 reference "sub:callback.register:-Register-a"
3860 ), albeit with callback name specified differently.
3863 \begin_layout Subsection
3864 callback.<cbname>:unregister: Register callback
3867 \begin_layout Itemize
3868 Syntax: function callback.<cbname>:unregister(function cbfun)
3871 \begin_layout Standard
3872 Synonym for callback.unregister (section
3873 \begin_inset CommandInset ref
3875 reference "sub:callback.unregister:-Unregister-"
3879 ), albeit with callback name specified differently.
3882 \begin_layout Section
3886 \begin_layout Standard
3887 Various bsnes-specific functions.
3890 \begin_layout Subsection
3891 bsnes.dump_sprite: Dump a sprite
3894 \begin_layout Itemize
3895 Syntax: BITMAP bsnes.dump_sprite([string vma, ] number addr, number width,
3899 \begin_layout Standard
3900 Dumps given sprite (in native format) from memory.
3902 \begin_inset Quotes eld
3906 \begin_inset Quotes erd
3910 Width and height are given in 8x8 blocks.
3913 \begin_layout Subsection
3914 bsnes.dump_palette: Dump a palette
3917 \begin_layout Itemize
3918 Syntax: PALETTE bsnes.dump_palette([string vma, ] number addr, bool full256,
3922 \begin_layout Standard
3923 Dumps a palette from memory.
3925 \begin_inset Quotes eld
3929 \begin_inset Quotes erd
3933 If <full256> is true, 256 colors are dumped (otherwise 16).
3934 If <first_trans> is true, first color is forced transparent.
3937 \begin_layout Section
3941 \begin_layout Standard
3942 Contains copy of global variables from time of Lua initialization.
3946 \begin_layout Standard
3947 \begin_inset Newpage pagebreak
3953 \begin_layout Section
3954 \begin_inset CommandInset label
3956 name "sec:Callbacks"
3963 \begin_layout Standard
3964 Various callbacks to Lua that can occur.
3967 \begin_layout Subsection
3968 on_paint: Screen is being painted
3971 \begin_layout Itemize
3972 Callback: on_paint(bool not_synth)
3975 \begin_layout Standard
3976 Called when screen is being painted.
3977 Any gui.* calls requiring graphic context draw on the screen.
3980 \begin_layout Itemize
3981 not_synth is true if this hook is being called in response to received frame,
3985 \begin_layout Subsection
3986 on_video: Dumped video frame is being painted
3989 \begin_layout Itemize
3990 Callback: on_video()
3993 \begin_layout Standard
3994 Called when video dump frame is being painted.
3995 Any gui.* calls requiring graphic context draw on the video.
3998 \begin_layout Subsection
3999 on_frame_emulated: Frame emulation complete
4002 \begin_layout Itemize
4003 Callback: on_frame_emulated()
4006 \begin_layout Standard
4007 Called when emulating frame has completed and on_paint()/on_video() calls
4008 are about to be issued.
4011 \begin_layout Subsection
4012 on_frame: Frame emulation starting.
4015 \begin_layout Itemize
4016 Callback: on_frame()
4019 \begin_layout Standard
4020 Called on each starting whole frame.
4023 \begin_layout Subsection
4024 on_startup: Emulator startup complete
4027 \begin_layout Itemize
4028 Callback: on_startup()
4031 \begin_layout Standard
4032 Called when the emulator is starting (lsnes.rc and --run files has been run).
4035 \begin_layout Subsection
4036 on_rewind: Movie rewound to beginning
4039 \begin_layout Itemize
4040 Callback: on_rewind()
4043 \begin_layout Standard
4044 Called when rewind movie to beginning has completed.
4047 \begin_layout Subsection
4048 on_pre_load: Load operation is about to start
4051 \begin_layout Itemize
4052 Callback: on_pre_load(string name)
4055 \begin_layout Standard
4056 Called just before savestate/movie load occurs (note: loads are always delayed,
4057 so this occurs even when load was initiated by lua).
4060 \begin_layout Subsection
4061 on_err_Load: Load failed
4064 \begin_layout Itemize
4065 Callback: on_err_load(string name)
4068 \begin_layout Standard
4069 Called if loadstate goes wrong.
4072 \begin_layout Subsection
4073 on_post_load: Load completed
4076 \begin_layout Itemize
4077 Callback: on_post_load(string name, boolean was_savestate)
4080 \begin_layout Standard
4081 Called on successful loadstate.
4082 was_savestate gives if this was a savestate or a movie.
4085 \begin_layout Subsection
4086 on_pre_save: Save operation is about to start
4089 \begin_layout Itemize
4090 Callback: on_pre_save(string name, boolean is_savestate)
4093 \begin_layout Standard
4094 Called just before savestate save occurs (note: movie saves are synchronous
4095 and won't trigger these callbacks if called from Lua).
4098 \begin_layout Subsection
4099 on_err_save: Save failed
4102 \begin_layout Itemize
4103 Callback: on_err_save(string name)
4106 \begin_layout Standard
4107 Called if savestate goes wrong.
4110 \begin_layout Subsection
4111 on_post_save: Save completed
4114 \begin_layout Itemize
4115 Callback: on_post_save(string name, boolean is_savestate)
4118 \begin_layout Standard
4119 Called on successful savaestate.
4120 is_savestate gives if this was a savestate or a movie.
4123 \begin_layout Subsection
4124 on_quit: Emulator is shutting down
4127 \begin_layout Itemize
4131 \begin_layout Standard
4132 Called when emulator is shutting down.
4135 \begin_layout Subsection
4136 on_input: Polling for input
4139 \begin_layout Standard
4140 Called when emulator is just sending input to bsnes core.
4141 Warning: This is called even in readonly mode, but the results are ignored.
4144 \begin_layout Subsection
4145 on_reset: System has been reset
4148 \begin_layout Itemize
4149 Callback: on_reset()
4152 \begin_layout Standard
4153 Called when system is reset.
4156 \begin_layout Subsection
4157 on_readwrite: Entered readwrite mode
4160 \begin_layout Itemize
4161 Callback: on_readwrite()
4164 \begin_layout Standard
4165 Called when moving into readwrite mode as result of
4166 \begin_inset Quotes eld
4170 \begin_inset Quotes erd
4173 command (note: moving to rwmode by Lua won't trigger this, as per recursive
4177 \begin_layout Subsection
4178 on_snoop/on_snoop2: Snoop core controller reads
4181 \begin_layout Itemize
4182 Callback: on_snoop(number port, number controller, number index, number
4186 \begin_layout Itemize
4187 Callback: on_snoop2(number port, number controller, number index, number
4191 \begin_layout Standard
4192 Called each time bsnes asks for input.
4193 The value is the final value to be sent to bsnes core (readonly mode, autohold
4194 and autofire have been taken into account).
4195 Might be useful when translating movies to format suitable for console
4197 Note: There is no way to modify the value to be sent.
4200 \begin_layout Itemize
4201 On_snoop2 is called instead of on_snoop if defined.
4202 Reserves port 0 for system, having first user port be port 1.
4205 \begin_layout Subsection
4206 on_keyhook: Hooked key/axis has been moved
4209 \begin_layout Itemize
4210 Callback: on_keyhook(string keyname, table state)
4213 \begin_layout Standard
4214 Sent when key that has keyhook events requested changes state.
4215 Keyname is name of the key (group) and state is the state (same kind as
4216 table values in input.raw).
4219 \begin_layout Subsection
4223 \begin_layout Itemize
4227 \begin_layout Standard
4228 Called when requested by set_idle_timeout(), the timeout has expired and
4229 emulator is waiting.
4232 \begin_layout Subsection
4233 on_timer: Timer event
4236 \begin_layout Itemize
4237 Callback: on_timer()
4240 \begin_layout Standard
4241 Called when requested by set_idle_timeout() and the timeout has expired
4242 (regardless if emulator is waiting).
4245 \begin_layout Subsection
4246 on_set_rewind: Rewind point has been set
4249 \begin_layout Itemize
4250 Callback: on_set_rewind(UNSAFEREWIND r)
4253 \begin_layout Standard
4254 Called when unsafe rewind object has been constructed.
4257 \begin_layout Subsection
4258 on_pre_rewind: Rewind is about to occur
4261 \begin_layout Itemize
4262 Callback: on_pre_rewind()
4265 \begin_layout Standard
4266 Called just before unsafe rewind is about to occur.
4269 \begin_layout Subsection
4270 on_post_rewind: Rewind has occured
4273 \begin_layout Itemize
4274 Callback: on_post_rewind()
4277 \begin_layout Standard
4278 Called just after unsafe rewind has occured.
4281 \begin_layout Subsection
4282 on_button: Button has been pressed
4285 \begin_layout Itemize
4286 Callback: on_button(number port, number controller, number index, string
4290 \begin_layout Standard
4291 Called on controller button press, with following parameters:
4294 \begin_layout Itemize
4295 port: Port number (0 is system)
4298 \begin_layout Itemize
4299 controller: Controller within port
4302 \begin_layout Itemize
4303 index: Index of button.
4306 \begin_layout Itemize
4307 type: Type of event, one of:
4311 \begin_layout Itemize
4312 \begin_inset Quotes eld
4316 \begin_inset Quotes erd
4319 : Button was pressed.
4322 \begin_layout Itemize
4323 \begin_inset Quotes eld
4327 \begin_inset Quotes erd
4330 : Button was released.
4333 \begin_layout Itemize
4334 \begin_inset Quotes eld
4338 \begin_inset Quotes erd
4344 \begin_layout Itemize
4345 \begin_inset Quotes eld
4349 \begin_inset Quotes erd
4352 : Released from hold.
4355 \begin_layout Itemize
4356 \begin_inset Quotes eld
4360 \begin_inset Quotes erd
4363 : Typing input on button.
4366 \begin_layout Itemize
4367 \begin_inset Quotes eld
4371 \begin_inset Quotes erd
4374 : Typing input undone.
4377 \begin_layout Itemize
4378 \begin_inset Quotes eld
4381 autofire <duty> <cycle>
4382 \begin_inset Quotes erd
4385 : Autofire with specifie duty and cycle.
4388 \begin_layout Itemize
4389 \begin_inset Quotes eld
4393 \begin_inset Quotes erd
4399 \begin_layout Itemize
4400 \begin_inset Quotes eld
4404 \begin_inset Quotes erd
4407 : Analog action on axis.
4411 \begin_layout Subsection
4412 on_movie_lost: Movie data is about to be lost
4415 \begin_layout Itemize
4416 Callback: on_movie_lost(STRING kind)
4419 \begin_layout Standard
4420 Called just before something would happen that could lose movie data.
4424 \begin_layout Itemize
4425 readwrite: Switching to readwrite mode.
4428 \begin_layout Itemize
4429 reload: ROM is being reloaded in readwrite mode.
4432 \begin_layout Itemize
4433 load: New movie is being loaded.
4436 \begin_layout Itemize
4437 unsaferewind: Unsafe rewind is happening.
4440 \begin_layout Subsection
4441 on_latch: Latch line is rising
4444 \begin_layout Itemize
4445 Callback: on_latch(<core-dependent-parameters>)
4448 \begin_layout Standard
4449 Called when latch line for controller is rising.
4450 Some cores may not support this.
4453 \begin_layout Itemize
4454 bsnes core: Called with no parameters.
4457 \begin_layout Itemize
4458 gambatte core: Not supported.