1 #LyX 2.1 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
16 \font_default_family default
17 \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
41 \use_package amsmath 1
42 \use_package amssymb 1
45 \use_package mathdots 1
46 \use_package mathtools 1
48 \use_package stackrel 1
49 \use_package stmaryrd 1
50 \use_package undertilde 1
52 \cite_engine_type default
56 \paperorientation portrait
73 \paragraph_separation indent
74 \paragraph_indentation default
75 \quotes_language english
78 \paperpagestyle default
79 \tracking_changes false
89 lsnes Lua functions reference
96 \begin_layout Standard
97 \begin_inset CommandInset toc
98 LatexCommand tableofcontents
105 \begin_layout Standard
106 \begin_inset Newpage pagebreak
112 \begin_layout Section
116 \begin_layout Subsection
120 \begin_layout Itemize
121 Coordinates increase to right and down.
124 \begin_layout Itemize
125 The origin is at top left of game area or buffer.
128 \begin_layout Subsection
132 \begin_layout Itemize
133 Methods that draw something (unless stated otherwise) require a valid rendering
135 This context can come in three ways:
139 \begin_layout Enumerate
140 The default rendering context of paint callback (the screen).
143 \begin_layout Enumerate
144 The default rendering context of video callback (the video).
147 \begin_layout Enumerate
148 Explicitly set rendering context (RENDERCTX:set).
152 \begin_layout Itemize
153 The rendering context is always reset when callback ends.
156 \begin_layout Subsection
160 \begin_layout Standard
161 (Direct) colors can be specified either as numbers or strings.
164 \begin_layout Itemize
165 -1 is fully transparent.
168 \begin_layout Itemize
169 Non-negative numbers less than
170 \begin_inset Formula $2^{32}$
173 are partially opaque colors (
174 \begin_inset Formula $a*2^{24}+r*2^{16}+g*2^{8}+b$
181 \begin_layout Itemize
182 \begin_inset Formula $a$
186 \begin_inset Formula $0-255$
190 \begin_inset Formula $0$
194 \begin_inset Formula $256$
197 would be fully transparent.
201 \begin_layout Itemize
202 Thus, numbers in range
203 \begin_inset Formula $0-16777215$
206 stand for fully opaque colors.
210 \begin_layout Itemize
211 \begin_inset Formula $r$
215 \begin_inset Formula $g$
219 \begin_inset Formula $b$
222 are intensities of base colors on scale
223 \begin_inset Formula $0-255$
230 \begin_layout Itemize
231 Color can also be specified by name as string: The following color names
232 are known: aliceblue antiquewhite antiquewhite1 antiquewhite2 antiquewhite3
233 antiquewhite4 aqua aquamarine aquamarine1 aquamarine2 aquamarine3 aquamarine4
234 azure azure1 azure2 azure3 azure4 beige bisque bisque1 bisque2 bisque3
235 bisque4 black blanchedalmond blue blue1 blue2 blue3 blue4 blueviolet brown
236 brown1 brown2 brown3 brown4 burlywood burlywood1 burlywood2 burlywood3
237 burlywood4 cadet cadetblue cadetblue1 cadetblue2 cadetblue3 cadetblue4
238 chartreuse chartreuse1 chartreuse2 chartreuse3 chartreuse4 chocolate chocolate1
239 chocolate2 chocolate3 chocolate4 coral coral1 coral2 coral3 coral4 cornflowerbl
240 ue cornsilk cornsilk1 cornsilk2 cornsilk3 cornsilk4 crimson cyan cyan1 cyan2
241 cyan3 cyan4 darkblue darkcyan darkgoldenrod darkgoldenrod1 darkgoldenrod2
242 darkgoldenrod3 darkgoldenrod4 darkgray darkgreen darkgrey darkkhaki darkmagenta
243 darkolivegreen darkolivegreen1 darkolivegreen2 darkolivegreen3 darkolivegreen4
244 darkorange darkorange1 darkorange2 darkorange3 darkorange4 darkorchid darkorchi
245 d1 darkorchid2 darkorchid3 darkorchid4 darkred darksalmon darkseagreen darkseagr
246 een1 darkseagreen2 darkseagreen3 darkseagreen4 darkslateblue darkslategray
247 darkslategray1 darkslategray2 darkslategray3 darkslategray4 darkslategrey
248 darkturquoise darkviolet deeppink deeppink1 deeppink2 deeppink3 deeppink4
249 deepskyblue deepskyblue1 deepskyblue2 deepskyblue3 deepskyblue4 dimgray
250 dimgrey dodgerblue dodgerblue1 dodgerblue2 dodgerblue3 dodgerblue4 firebrick
251 firebrick1 firebrick2 firebrick3 firebrick4 floralwhite forestgreen fractal
252 fuchsia gainsboro ghostwhite gold gold1 gold2 gold3 gold4 goldenrod goldenrod1
253 goldenrod2 goldenrod3 goldenrod4 gray gray0 gray1 gray10 gray100 gray11
254 gray12 gray13 gray14 gray15 gray16 gray17 gray18 gray19 gray2 gray20 gray21
255 gray22 gray23 gray24 gray25 gray26 gray27 gray28 gray29 gray3 gray30 gray31
256 gray32 gray33 gray34 gray35 gray36 gray37 gray38 gray39 gray4 gray40 gray41
257 gray42 gray43 gray44 gray45 gray46 gray47 gray48 gray49 gray5 gray50 gray51
258 gray52 gray53 gray54 gray55 gray56 gray57 gray58 gray59 gray6 gray60 gray61
259 gray62 gray63 gray64 gray65 gray66 gray67 gray68 gray69 gray7 gray70 gray71
260 gray72 gray73 gray74 gray75 gray76 gray77 gray78 gray79 gray8 gray80 gray81
261 gray82 gray83 gray84 gray85 gray86 gray87 gray88 gray89 gray9 gray90 gray91
262 gray92 gray93 gray94 gray95 gray96 gray97 gray98 gray99 green green1 green2
263 green3 green4 greenyellow grey grey0 grey1 grey10 grey100 grey11 grey12
264 grey13 grey14 grey15 grey16 grey17 grey18 grey19 grey2 grey20 grey21 grey22
265 grey23 grey24 grey25 grey26 grey27 grey28 grey29 grey3 grey30 grey31 grey32
266 grey33 grey34 grey35 grey36 grey37 grey38 grey39 grey4 grey40 grey41 grey42
267 grey43 grey44 grey45 grey46 grey47 grey48 grey49 grey5 grey50 grey51 grey52
268 grey53 grey54 grey55 grey56 grey57 grey58 grey59 grey6 grey60 grey61 grey62
269 grey63 grey64 grey65 grey66 grey67 grey68 grey69 grey7 grey70 grey71 grey72
270 grey73 grey74 grey75 grey76 grey77 grey78 grey79 grey8 grey80 grey81 grey82
271 grey83 grey84 grey85 grey86 grey87 grey88 grey89 grey9 grey90 grey91 grey92
272 grey93 grey94 grey95 grey96 grey97 grey98 grey99 honeydew honeydew1 honeydew2
273 honeydew3 honeydew4 hotpink hotpink1 hotpink2 hotpink3 hotpink4 indianred
274 indianred1 indianred2 indianred3 indianred4 indigo ivory ivory1 ivory2
275 ivory3 ivory4 khaki khaki1 khaki2 khaki3 khaki4 lavender lavenderblush
276 lavenderblush1 lavenderblush2 lavenderblush3 lavenderblush4 lawngreen lemonchif
277 fon lemonchiffon1 lemonchiffon2 lemonchiffon3 lemonchiffon4 lightblue lightblue1
278 lightblue2 lightblue3 lightblue4 lightcoral lightcyan lightcyan1 lightcyan2
279 lightcyan3 lightcyan4 lightgoldenrod lightgoldenrod1 lightgoldenrod2 lightgolde
280 nrod3 lightgoldenrod4 lightgoldenrodyellow lightgray lightgreen lightgrey
281 lightpink lightpink1 lightpink2 lightpink3 lightpink4 lightsalmon lightsalmon1
282 lightsalmon2 lightsalmon3 lightsalmon4 lightseagreen lightskyblue lightskyblue1
283 lightskyblue2 lightskyblue3 lightskyblue4 lightslateblue lightslategray
284 lightslategrey lightsteelblue lightsteelblue1 lightsteelblue2 lightsteelblue3
285 lightsteelblue4 lightyellow lightyellow1 lightyellow2 lightyellow3 lightyellow4
286 lime limegreen linen magenta magenta1 magenta2 magenta3 magenta4 maroon
287 maroon1 maroon2 maroon3 maroon4 mediumaquamarine mediumblue mediumforestgreen
288 mediumgoldenrod mediumorchid mediumorchid1 mediumorchid2 mediumorchid3
289 mediumorchid4 mediumpurple mediumpurple1 mediumpurple2 mediumpurple3 mediumpurp
290 le4 mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumviole
291 tred midnightblue mintcream mistyrose mistyrose1 mistyrose2 mistyrose3 mistyrose
292 4 moccasin navajowhite navajowhite1 navajowhite2 navajowhite3 navajowhite4
293 navy navyblue oldlace olive olivedrab olivedrab1 olivedrab2 olivedrab3
294 olivedrab4 orange orange1 orange2 orange3 orange4 orangered orangered1
295 orangered2 orangered3 orangered4 orchid orchid1 orchid2 orchid3 orchid4
296 palegoldenrod palegreen palegreen1 palegreen2 palegreen3 palegreen4 paleturquoi
297 se paleturquoise1 paleturquoise2 paleturquoise3 paleturquoise4 palevioletred
298 palevioletred1 palevioletred2 palevioletred3 palevioletred4 papayawhip
299 peachpuff peachpuff1 peachpuff2 peachpuff3 peachpuff4 peru pink pink1 pink2
300 pink3 pink4 plum plum1 plum2 plum3 plum4 powderblue purple purple1 purple2
301 purple3 purple4 red red1 red2 red3 red4 rosybrown rosybrown1 rosybrown2
302 rosybrown3 rosybrown4 royalblue royalblue1 royalblue2 royalblue3 royalblue4
303 saddlebrown salmon salmon1 salmon2 salmon3 salmon4 sandybrown seagreen
304 seagreen1 seagreen2 seagreen3 seagreen4 seashell seashell1 seashell2 seashell3
305 seashell4 sienna sienna1 sienna2 sienna3 sienna4 silver skyblue skyblue1
306 skyblue2 skyblue3 skyblue4 slateblue slateblue1 slateblue2 slateblue3 slateblue
307 4 slategray slategray1 slategray2 slategray3 slategray4 slategrey snow snow1
308 snow2 snow3 snow4 springgreen springgreen1 springgreen2 springgreen3 springgree
309 n4 steelblue steelblue1 steelblue2 steelblue3 steelblue4 tan tan1 tan2 tan3
310 tan4 teal thistle thistle1 thistle2 thistle3 thistle4 tomato tomato1 tomato2
311 tomato3 tomato4 transparent turquoise turquoise1 turquoise2 turquoise3
312 turquoise4 violet violetred violetred1 violetred2 violetred3 violetred4
313 wheat wheat1 wheat2 wheat3 wheat4 white whitesmoke yellow yellow1 yellow2
314 yellow3 yellow4 yellowgreen
317 \begin_layout Itemize
318 The HSL base color names: hsl-<hue><saturation><lightness>.
322 \begin_layout Itemize
323 Hue can be one of: r (red), ry (red-yellow), o (orange, same as red-yellow),
324 y (yellow), yg (yellow-green), g (green), gc (green-cyan), c (cyan), cb
325 (cyan-blue), b (blue), bm (blue-magenta), m (magenta), mr (magenta-red).
328 \begin_layout Itemize
329 Saturation is 0-8, where 0 is greyscale and 8 is fully saturated.
332 \begin_layout Itemize
333 Lightness is 0-8, where 0 is black and 8 is white.
337 \begin_layout Itemize
338 The color names can have a modifier after space (multiple modifiers are
339 allowed, separated by spaces): opaque10, opaque20, opaque25, opaque30,
340 opaque40, opaque50, opaque60, opaque70, opaque75, opaque80, opaque90, opaque,
341 hue{+,-}{1-23}, {saturation,lightness}{+,-}{1-16}.
345 \begin_layout Itemize
346 opaqueness is measured as percentage.
349 \begin_layout Itemize
350 Hue adjustments are on 24-step scale.
353 \begin_layout Itemize
354 Saturation and lightness adjustments are on 16-step scale.
358 \begin_layout Section
362 \begin_layout Standard
363 These tokens are special, and are expanded while the script is being loaded
366 \begin_layout Subsection
367 @@LUA_SCRIPT_FILENAME@@
370 \begin_layout Standard
371 Expanded to string token containing path and filename of this Lua script.
372 Handy for referencing other lua scripts or resources that are relative
376 \begin_layout Standard
377 In practicular, this is suitable to be passed as base argument of various
378 functions like loadfile, dofile, resolve_filename, gui.bitmap_load, gui.bitmap_lo
379 ad_png and gui.bitmap_load_pal.
382 \begin_layout Section
386 \begin_layout Subsection
387 MMAP_STRUCT: Quasi-table mapping emulated memory
390 \begin_layout Standard
391 Objects act like tables, but the values reflect emulated memory.
394 \begin_layout Subsubsection
395 static function new: Create a new instance
398 \begin_layout Itemize
399 Syntax: mmap memory.mmap.new()
402 \begin_layout Itemize
403 Syntax: mmap classes.MMAP_STRUCT.new()
406 \begin_layout Standard
410 \begin_layout Itemize
411 mmap: MMAP_STRUCT: The created mmap structure.
414 \begin_layout Standard
415 Create a new object (with no mappings) and return it.
418 \begin_layout Subsubsection
419 operator(): Bind key in mmap structure
422 \begin_layout Itemize
423 Syntax: obj(key, {marea, address|addrobj}, type)
426 \begin_layout Standard
430 \begin_layout Itemize
431 obj: MMAP_STRUCT: The structure to manipulate.
434 \begin_layout Itemize
435 key: String: The name of the key in array to map.
438 \begin_layout Itemize
439 marea: String: The memory area the mapped address is in (default: global
443 \begin_layout Itemize
444 address: Number: The offset of memory addreess, relative to specified memory
445 area or global memory space.
448 \begin_layout Itemize
449 addrobj: ADDRESS: The memory address.
452 \begin_layout Itemize
453 type: String: The type of data to map.
457 \begin_layout Itemize
458 One of: byte, sbyte, word, sword, hword, shword, dword, sdword, qword, sqword,
463 \begin_layout Standard
464 Bind key <key> in mmap structure <obj> to address <address> (relative to
466 The memory address is treated as type <type>.
469 \begin_layout Itemize
471 \begin_inset Quotes eld
475 \begin_inset Quotes erd
479 \begin_inset Quotes eld
483 \begin_inset Quotes erd
487 \begin_inset Quotes eld
491 \begin_inset Quotes erd
497 \begin_layout Standard
498 This binds signed word at address WRAM+0x2A into key
499 \begin_inset Quotes eld
503 \begin_inset Quotes erd
509 \begin_layout Standard
510 \begin_inset Newpage pagebreak
516 \begin_layout Subsection
517 ZIPWRITER: Write .zip files
520 \begin_layout Standard
521 This class does writing of .zip files.
524 \begin_layout Subsubsection
525 Static function new: Create a new zipfile
528 \begin_layout Itemize
529 Syntax: zip zip.writer.new(filename, [compression])
532 \begin_layout Itemize
533 Deprecated: zip zip.create(filename, [compression])
536 \begin_layout Standard
540 \begin_layout Itemize
541 filename: string: The name of the file to write.
544 \begin_layout Itemize
545 compression: number: Compression level (0-9).
549 \begin_layout Standard
553 \begin_layout Itemize
554 zip: ZIPWRITER: The newly created ZIP writer.
557 \begin_layout Standard
558 Create a new ZIPWRITER object and return it.
561 \begin_layout Subsubsection
562 Method commit: Finish creating ZIP file.
565 \begin_layout Itemize
566 Syntax: zipfile:commit()
569 \begin_layout Standard
573 \begin_layout Itemize
574 zipfile: ZIPFILE: The ZIP file object.
577 \begin_layout Standard
578 Finish writing the ZIP file and actually create it on disk.
581 \begin_layout Itemize
582 If a member is currently open, it is implicitly closed.
585 \begin_layout Itemize
586 Invoking this on already committed or rolled back zipfile causes an error.
589 \begin_layout Subsubsection
590 Method rollback: Cancel writing the ZIP file.
593 \begin_layout Itemize
594 Syntax: zipfile:rollback()
597 \begin_layout Standard
601 \begin_layout Itemize
602 zipfile: ZIPFILE: The ZIP file object.
605 \begin_layout Standard
606 Cancel writing the whole ZIP file.
607 The file on disk will not be modified.
610 \begin_layout Itemize
611 If a member is currently open, it is implicitly closed.
614 \begin_layout Itemize
615 Invoking this on already committed or rolled back zipfile causes an error.
618 \begin_layout Subsubsection
619 Method create_file: Start writing a new member
622 \begin_layout Itemize
623 Syntax: zipfile:create_file(filename)
626 \begin_layout Standard
630 \begin_layout Itemize
631 zipfile: ZIPFILE: The ZIP file object.
634 \begin_layout Itemize
635 string filename: Name of the new member to create
638 \begin_layout Standard
639 Start writing a new member <filename> in ZIP file.
642 \begin_layout Itemize
643 If a member is currently open, it is implicitly closed.
646 \begin_layout Itemize
647 Invoking this on already committed or rolled back zipfile causes an error.
650 \begin_layout Subsubsection
651 Method close_file: Close member
654 \begin_layout Itemize
655 Syntax: zipfile:close_file()
658 \begin_layout Standard
662 \begin_layout Itemize
663 zipfile: ZIPFILE: The ZIP file object.
666 \begin_layout Standard
667 Close the currently open member in zipfile.
670 \begin_layout Itemize
671 Invoking this on already committed or rolled back zipfile causes an error.
674 \begin_layout Itemize
675 Invoking this without an open member causes an error.
678 \begin_layout Subsubsection
679 Method write: Write data
682 \begin_layout Itemize
683 Syntax: zipfile:write(data)
686 \begin_layout Standard
690 \begin_layout Itemize
691 zipfile: ZIPFILE: The ZIP file object.
694 \begin_layout Itemize
695 data: string: The data to write.
698 \begin_layout Standard
699 Write <data> in binary mode (as-is) to currently open member.
702 \begin_layout Itemize
703 Invoking this without a member being open causes an error.
706 \begin_layout Standard
707 \begin_inset Newpage pagebreak
713 \begin_layout Subsection
714 TILEMAP: Tiled collection of bitmaps.
717 \begin_layout Standard
718 A tilemap is tiled table, each cell holding a bitmap (indexed or direct).
721 \begin_layout Subsubsection
722 Static function new: Create a tilemap
725 \begin_layout Itemize
726 Syntax: tilemap gui.tiled_bitmap.new(w, h, bw, bh);
729 \begin_layout Itemize
730 Syntax: tilemap classes.TILEMAP.new(w, h, bw, bh);
733 \begin_layout Itemize
734 Deprecated: tilemap gui.tilemap(w, h, bw, bh);
737 \begin_layout Standard
741 \begin_layout Itemize
742 w: number: Width of the tilemap in tiles
745 \begin_layout Itemize
746 h: number: Height of the tilemap in tiles
749 \begin_layout Itemize
750 bw: number: Width of each tile in pixels.
753 \begin_layout Itemize
754 bh: number: Height of each tile in pixels.
757 \begin_layout Standard
761 \begin_layout Itemize
762 tilemap: TILEMAP: the newly created tilemap
765 \begin_layout Standard
766 Create a new tilemap of <w>*<h> tiles, each of <bw>*<bh> pixels and return
770 \begin_layout Subsubsection
771 TILEMAP:getsize: Query tilemap size
774 \begin_layout Itemize
775 Syntax: width, height tmap:getsize()
778 \begin_layout Standard
782 \begin_layout Itemize
783 tmap: TILEMAP: The tilemap to query.
786 \begin_layout Standard
790 \begin_layout Itemize
791 width: number : The width of the tilemap in tiles.
794 \begin_layout Itemize
795 height: number: The height of the tilemap in tiles.
798 \begin_layout Standard
799 Get size of tilemap in tiles.
802 \begin_layout Subsubsection
803 TILEMAP:getcsize: Query tilemap cell size
806 \begin_layout Itemize
807 Syntax: width, height tmap:getcsize()
810 \begin_layout Standard
814 \begin_layout Itemize
815 tmap: TILEMAP: The tilemap to query.
818 \begin_layout Standard
822 \begin_layout Itemize
823 width: number: The width of tilemap tile in pixels.
826 \begin_layout Itemize
827 height: number: The height of tilemap tile in pixels.
830 \begin_layout Standard
831 Get size of each tilemap tile in pixels.
834 \begin_layout Subsubsection
835 TILEMAP:get: Query tilemap tile
838 \begin_layout Itemize
839 Syntax: bitmap, palette tmap:get(x, y)
842 \begin_layout Standard
846 \begin_layout Itemize
847 tmap: TILEMAP: The tilemap to query.
850 \begin_layout Itemize
851 x: number: The x-coordinate of tile to query.
854 \begin_layout Itemize
855 y: number: The y-coordinate of tile to query.
858 \begin_layout Standard
862 \begin_layout Itemize
863 bitmap: The associated bitmap (BITMAP or DBITMAP), or nil if none.
866 \begin_layout Itemize
867 palette: The palette (PALETTE) associated with indexed-color bitmap, if
872 \begin_layout Standard
873 Return the contents of tile at <x>,<y>.
876 \begin_layout Subsubsection
877 TILEMAP:set: Set tilemap cell
880 \begin_layout Itemize
881 Syntax: tmap:set(x, y)
884 \begin_layout Itemize
885 Syntax: tmap:set(x, y, bitmap)
888 \begin_layout Itemize
889 Syntax: tmap:set(x, y, bitmap, palette)
892 \begin_layout Standard
896 \begin_layout Itemize
897 tmap: TILEMAP: The tilemap to manipulate.
900 \begin_layout Itemize
901 number x: The x-coordinate of tile to set.
904 \begin_layout Itemize
905 number y: The y-coordinate of tile to set.
908 \begin_layout Itemize
909 bitmap: BITMAP/DBITMAP: The bitmap to set to tile.
912 \begin_layout Itemize
913 palette: PALETTE: The associated palette for bitmap.
916 \begin_layout Standard
917 Set the contents of tile <x>,<y>.
918 If no <bitmap> is given, clears the tile.
919 Otherwise sets the tile to contain bitmap <bitmap> with associated palette
923 \begin_layout Itemize
924 Specifying index bitmap <bitmap> without palette <palette> causes an error.
927 \begin_layout Subsubsection
928 TILEMAP:scroll: Scroll tilemap
931 \begin_layout Itemize
932 Syntax: tmap:scroll(ox, oy);
935 \begin_layout Itemize
936 Syntax: tmap:scroll(ox, oy, x, y, w, h);
939 \begin_layout Itemize
940 Syntax: tmap:scroll(ox, oy, x, y, w, h, circ_x, circ_y);
943 \begin_layout Standard
947 \begin_layout Itemize
948 tmap: TILEMAP: The tilemap to manipulate.
951 \begin_layout Itemize
952 ox: number: The number of tiles to scroll horizontally (positive is to right).
955 \begin_layout Itemize
956 oy: number: The number of tiles to scroll vertically (positive is to down).
959 \begin_layout Itemize
960 x: number: The left edge of scroll window.
963 \begin_layout Itemize
964 y: number: The top edge of scroll window.
967 \begin_layout Itemize
968 w: number: The width of scroll window.
971 \begin_layout Itemize
972 h: number: The height of scroll window.
975 \begin_layout Itemize
976 circ_x: boolean: If true, treat the window as circular in horizontal direction.
979 \begin_layout Itemize
980 circ_y: boolean: If true, treat the window as circular in vertical direction.
983 \begin_layout Standard
984 Scroll the specified tilemap <tmap> by <ox>,<oy>.
985 If a window <x>,<y>,<w>,<h> is specified, only that part is scrolled.
986 <circ_x> and <circ_y> control if scroll is circular or not.
989 \begin_layout Itemize
990 Specifying out-of-range window causes an error.
993 \begin_layout Subsubsection
994 TILEMAP:draw: Draw tilemap
997 \begin_layout Itemize
998 Name: tmap:draw(x, y)
1001 \begin_layout Itemize
1002 Name: tmap:draw(x, y, x0, y0, w, h)
1005 \begin_layout Standard
1009 \begin_layout Itemize
1010 tmap: TILEMAP: The tilemap to draw.
1013 \begin_layout Itemize
1014 x: The x coordinate on screen to draw to.
1017 \begin_layout Itemize
1018 y: The y coordinate on screen to draw to.
1021 \begin_layout Itemize
1022 x0: number: The x coordinate on tilemap (in pixels) to start drawing from.
1025 \begin_layout Itemize
1026 y0: number: The y coordinate on tilemap (in pixels) to start drawing from.
1029 \begin_layout Itemize
1030 w: number: The width to draw (in pixels).
1033 \begin_layout Itemize
1034 h: number: The height to draw (in pixels).
1037 \begin_layout Standard
1038 Draw tilemap <tmap> to screen at <x>,<y>.
1039 If a window <x0>,<y0>,<w>,<h> is specified, only that part is drawn.
1042 \begin_layout Itemize
1043 This method requires a rendering context to work.
1046 \begin_layout Subsubsection
1047 TILEMAP:draw_outside: Draw tilemap outside game area
1050 \begin_layout Itemize
1051 Name: tmap:draw_outside(x, y)
1054 \begin_layout Itemize
1055 Name: tmap:draw_outside(x, y, x0, y0, w, h)
1058 \begin_layout Standard
1059 Like TILEMAP:draw, but draws only outside game area.
1062 \begin_layout Standard
1063 \begin_inset Newpage pagebreak
1069 \begin_layout Subsection
1070 RENDERCTX: Off-screen rendering context
1073 \begin_layout Standard
1074 Object acting as off-screen rendering context.
1077 \begin_layout Subsubsection
1078 Static function new: Create a render queue
1081 \begin_layout Itemize
1082 Syntax: renderctx gui.renderctx.new(width, height);
1085 \begin_layout Itemize
1086 Syntax: renderctx classes.RENDERCTX.new(width, height);
1089 \begin_layout Itemize
1090 Deprecated: renderctx gui.renderq_new(width, height);
1093 \begin_layout Standard
1097 \begin_layout Itemize
1098 width: number: The notional width of the game area.
1101 \begin_layout Itemize
1102 height: number: The notional height of the game area.
1105 \begin_layout Standard
1109 \begin_layout Itemize
1110 rendectx: RENDERCTX: The newly created render context.
1113 \begin_layout Standard
1114 Create a render context with reported size <width>*<height> and return it.
1117 \begin_layout Subsubsection
1118 Static function setnull: Reset to default queue
1121 \begin_layout Itemize
1122 Syntax: gui.renderctx.setnull()
1125 \begin_layout Itemize
1126 Syntax: classes.RENDERCTX:setnull()
1129 \begin_layout Itemize
1130 Deprecated: gui.renderq_set()
1133 \begin_layout Standard
1134 Reset the used render context back to default for the executing callback:
1137 \begin_layout Itemize
1138 The default for paint callback is the screen
1141 \begin_layout Itemize
1142 The default for video callback is the video frame
1145 \begin_layout Itemize
1146 The default otherwise is nothing.
1149 \begin_layout Subsubsection
1150 Method clear: Clear a render queue
1153 \begin_layout Itemize
1154 Syntax: renderctx:clear()
1157 \begin_layout Itemize
1158 Deprecated: gui.renderq_clear(renderctx)
1161 \begin_layout Standard
1165 \begin_layout Itemize
1166 renderctx: RENDERCTX: The render queue to clear.
1169 \begin_layout Standard
1170 Clear all drawing from the context.
1173 \begin_layout Subsubsection
1174 Method set: Change active render context
1177 \begin_layout Itemize
1178 Syntax: renderctx:set()
1181 \begin_layout Itemize
1182 Deprecated: gui.renderq_set(renderctx)
1185 \begin_layout Standard
1189 \begin_layout Itemize
1190 renderctx: RENDERCTX: The render queue to use.
1193 \begin_layout Standard
1194 Switch the current rendering context <renderctx>.
1197 \begin_layout Subsubsection
1198 Method run: Draw all objects in context to another
1201 \begin_layout Itemize
1202 Syntax: renderctx:run()
1205 \begin_layout Itemize
1206 Deprecated: gui.renderq_run(renderctx)
1209 \begin_layout Standard
1213 \begin_layout Itemize
1214 renderctx: RENDERCTX: The render context to overlay.
1217 \begin_layout Standard
1218 Overlay the specified render context <context> upon the active rendering
1222 \begin_layout Itemize
1223 Trying to overlay rendering context upon itself is a bad idea.
1226 \begin_layout Subsubsection
1227 Method render: Render a contex to bitmap
1230 \begin_layout Itemize
1231 Syntax: bitmap renderctx:render()
1234 \begin_layout Standard
1238 \begin_layout Itemize
1239 renderctx: RENDERCTX: The context to render.
1242 \begin_layout Standard
1246 \begin_layout Itemize
1247 bitmap: DBITMAP: The rendered bitmap.
1250 \begin_layout Standard
1251 Render the specified context <renderctx> to a new bitmap.
1254 \begin_layout Itemize
1255 The size of bitmap will be nominal game area size, plus any set gaps.
1258 \begin_layout Itemize
1259 This method does not require active rendering context.
1262 \begin_layout Subsubsection
1263 Method synchronous_repaint: Paint screen now
1266 \begin_layout Itemize
1267 Syntax: renderctx:synchronous_repaint()
1270 \begin_layout Itemize
1271 Deprecated: gui.synchronous_repaint(renderctx)
1274 \begin_layout Standard
1278 \begin_layout Itemize
1279 renderctx: RENDERCTX: The context to paint.
1282 \begin_layout Standard
1283 Immediately redraw the screen with game overlayed by drawings from context
1287 \begin_layout Itemize
1288 This does not require active rendering context.
1291 \begin_layout Itemize
1292 Will not cause paint callback to be invoked.
1295 \begin_layout Standard
1296 \begin_inset Newpage pagebreak
1302 \begin_layout Subsection
1303 PALETTE: Color palette for indexed image
1306 \begin_layout Subsubsection
1307 Static function new: Create a new palette
1310 \begin_layout Itemize
1311 Syntax: palette gui.palette.new()
1314 \begin_layout Itemize
1315 Syntax: palette classes.PALETTE.new()
1318 \begin_layout Itemize
1319 Deprecated: palette gui.palette_new()
1322 \begin_layout Standard
1326 \begin_layout Itemize
1327 palette: PALETTE: The created palette.
1330 \begin_layout Standard
1331 Create a new palette (with all colors transparent) and return it.
1334 \begin_layout Subsubsection
1335 Static function load: Load a palette
1338 \begin_layout Itemize
1339 Syntax: palette gui.palette.load(file, [base])
1342 \begin_layout Itemize
1343 Syntax: palette classes.PALETTE.load(file, [base])
1346 \begin_layout Itemize
1347 Deprecated: palette gui.palette_load(file, [base])
1350 \begin_layout Standard
1354 \begin_layout Itemize
1355 string file: The file to load.
1358 \begin_layout Itemize
1359 string base (optional): The base file to resolve file relative to.
1362 \begin_layout Standard
1366 \begin_layout Itemize
1367 palette: PALETTE: The loaded palette.
1370 \begin_layout Standard
1371 Load a palette from file <file> (resolved relative to <base>).
1374 \begin_layout Itemize
1375 The file format is a series of lines, each with following format:
1379 \begin_layout Itemize
1380 Blank or just whitespace: Ignored
1383 \begin_layout Itemize
1384 First non-whitespace is '#': Ignored
1387 \begin_layout Itemize
1388 <r> <g> <b>: Fully opaque color with specified RGB values (0-255)
1391 \begin_layout Itemize
1392 <r> <g> <b> <a>: Color with specified RGB values (0-255) and specified alpha
1393 (0-256, 0 being fully transparent and 256 fully opaque).
1396 \begin_layout Itemize
1397 transparent: Fully transparent color
1401 \begin_layout Subsubsection
1402 Static function load_str: Load a palette from string
1405 \begin_layout Itemize
1406 Syntax: palette gui.palette.load(data)
1409 \begin_layout Itemize
1410 Syntax: palette classes.PALETTE.load(data)
1413 \begin_layout Itemize
1414 Deprecated: palette gui.palette_load(data)
1417 \begin_layout Standard
1421 \begin_layout Itemize
1422 string data: The palette data.
1425 \begin_layout Standard
1429 \begin_layout Itemize
1430 palette: PALETTE: The loaded palette.
1433 \begin_layout Standard
1434 Like PALETTE:load, but instead of reading palette from file, reads it from
1438 \begin_layout Subsubsection
1439 Method set: Set palette entry
1442 \begin_layout Itemize
1443 Syntax: palette:set(index, color)
1446 \begin_layout Itemize
1447 Deprecated: gui.palette_set(palette, ...)
1450 \begin_layout Standard
1454 \begin_layout Itemize
1455 palette: PALETTE: The palette to manipulate
1458 \begin_layout Itemize
1459 index: number: The index of color to set (0-65535).
1462 \begin_layout Itemize
1463 color: number/string: The color value to set.
1466 \begin_layout Standard
1467 Set palette <palette> index <index> to color <color>.
1470 \begin_layout Subsubsection
1471 Method hash: Hash a palette
1474 \begin_layout Itemize
1475 Syntax: hash palette:hash()
1478 \begin_layout Itemize
1479 Deprecated: hash gui.palette_hash(palette)
1482 \begin_layout Standard
1486 \begin_layout Itemize
1487 palette: The palette to hash.
1490 \begin_layout Standard
1494 \begin_layout Itemize
1495 hash: string: 64-hex digit hash.
1498 \begin_layout Standard
1499 Obtain crypto-grade hash of palette data of <palette>.
1502 \begin_layout Itemize
1503 All colors after the last non-transparent one are ignored.
1506 \begin_layout Subsubsection
1507 Method adjust_transparency: Adjust transparency
1510 \begin_layout Itemize
1511 Syntax: palette:adjust_transparency(newvalue)
1514 \begin_layout Itemize
1515 Deprecated: gui.adjust_transparency(palette, ...)
1518 \begin_layout Standard
1522 \begin_layout Itemize
1523 palette: PALETTE: The palette to adjust.
1526 \begin_layout Itemize
1527 Number adj: The factor to multiply opaqueness with times 256.
1530 \begin_layout Standard
1531 Multiply opaqueness of all colors in palette <palette> by factor of <adj>/256.
1534 \begin_layout Standard
1535 \begin_inset Newpage pagebreak
1541 \begin_layout Subsection
1542 BITMAP: Indexed-color bitmap
1545 \begin_layout Subsubsection
1546 Static function new: Create a new bitmap
1549 \begin_layout Itemize
1550 Syntax: bitmap gui.bitmap.new(w, h, [fillcolor])
1553 \begin_layout Itemize
1554 Syntax: bitmap classes.BITMAP.new(w, h, [fillcolor])
1557 \begin_layout Itemize
1558 Deprecated: bitmap gui.bitmap_new(w, h, false, [fillcolor])
1561 \begin_layout Standard
1565 \begin_layout Itemize
1566 w: number: The width of bitmap to create in pixels.
1569 \begin_layout Itemize
1570 h: number: The height of bitmap to create in pixels.
1573 \begin_layout Itemize
1574 false: boolean: Constant boolean false.
1577 \begin_layout Itemize
1578 fillcolor: number: The initial fill index.
1579 Default 0 if not specified.
1582 \begin_layout Standard
1583 Create a new bitmap of size <w>*<h>.
1584 Fill the bitmap with color index <fillcolor>.
1587 \begin_layout Subsubsection
1588 Method draw: Draw a bitmap
1591 \begin_layout Itemize
1592 Syntax: bitmap:draw(x, y, palette)
1595 \begin_layout Itemize
1596 Deprecated: gui.bitmap_draw(x, y, bitmap, palette)
1599 \begin_layout Standard
1603 \begin_layout Itemize
1604 bitmap: BITMAP: The bitmap to draw
1607 \begin_layout Itemize
1608 x: number: The x-coordinate on screen.
1611 \begin_layout Itemize
1612 y: number: The y-coordinate on screen.
1615 \begin_layout Itemize
1616 palette: The palette to use for drawing.
1619 \begin_layout Standard
1620 Draw bitmap <bitmap> on screen at <x>,<y> with palette <palette>.
1623 \begin_layout Subsubsection
1624 Method draw_outside: Draw a bitmap outside game area
1627 \begin_layout Itemize
1628 Syntax: bitmap:draw_outside(x, y, palette)
1631 \begin_layout Standard
1632 Like bitmap:draw, but does not draw on game area.
1635 \begin_layout Subsubsection
1636 Method draw_clip: Draw a bitmap, with clipping
1639 \begin_layout Itemize
1640 Syntax: bitmap:draw_clip(x, y, palette, x0, y0, width, height)
1643 \begin_layout Standard
1647 \begin_layout Itemize
1648 bitmap: BITMAP: The bitmap to draw
1651 \begin_layout Itemize
1652 x: number: The x-coordinate on screen.
1655 \begin_layout Itemize
1656 y: number: The y-coordinate on screen.
1659 \begin_layout Itemize
1660 palette: The palette to use for drawing.
1663 \begin_layout Itemize
1664 x0: The smallest bitmap x coordinate to draw.
1667 \begin_layout Itemize
1668 y0: The smallest bitmap y coordinate to draw.
1671 \begin_layout Itemize
1672 width: Width of region to draw
1675 \begin_layout Itemize
1676 height: Height of region to draw.
1679 \begin_layout Standard
1680 Like bitmap:draw, but clip the bitmap area drawn.
1683 \begin_layout Subsubsection
1684 Method draw_clip_outside: Draw a bitmap outside game are, with clipping
1687 \begin_layout Itemize
1688 Syntax: bitmap:draw_clip_outside(x, y, palette, x0, y0, width, height)
1691 \begin_layout Standard
1692 Like bitmap:draw_clip, but only draw outside game area.
1695 \begin_layout Subsubsection
1696 Method pset: Set pixel in bitmap
1699 \begin_layout Itemize
1700 Syntax: bitmap:pset(x, y, color)
1703 \begin_layout Itemize
1704 Deprecaed: gui.bitmap_pset(bitmap, ...)
1707 \begin_layout Standard
1711 \begin_layout Itemize
1712 bitmap: BITMAP: The bitmap to manipulate.
1715 \begin_layout Itemize
1716 x: number: x-coordinate of pixel to set.
1719 \begin_layout Itemize
1720 y: number: y-coordinate of pixel to set.
1723 \begin_layout Itemize
1724 color: number: The color index to set.
1727 \begin_layout Standard
1728 Sets specified pixel <x>,<y> in bitmap <bitmap> to color index <color>.
1731 \begin_layout Subsubsection
1732 Method pget: Get pixel in bitmap
1735 \begin_layout Itemize
1736 Syntax: color bitmap:pget(x,y)
1739 \begin_layout Itemize
1740 Deprecated: color gui.bitmap_pget(bitmap, ...)
1743 \begin_layout Standard
1747 \begin_layout Itemize
1748 bitmap: BITMAP: The bitmap to query.
1751 \begin_layout Itemize
1752 x: number: x-coordinate of pixel to get.
1755 \begin_layout Itemize
1756 y: number: y-coordinate of pixel to get.
1759 \begin_layout Standard
1763 \begin_layout Itemize
1764 color: number: The color index in specified pixel.
1767 \begin_layout Standard
1768 Gets color index of specified pixel <x>,<y> in bitmap <bitmap>.
1771 \begin_layout Subsubsection
1772 Method size: Get size of bitmap
1775 \begin_layout Itemize
1776 Syntax: width, height bitmap:size()
1779 \begin_layout Itemize
1780 Syntax: width, height gui.bitmap_size(bitmap)
1783 \begin_layout Standard
1787 \begin_layout Itemize
1788 bitmap: BITMAP: The bitmap to query.
1791 \begin_layout Standard
1795 \begin_layout Itemize
1796 width: number: The width of the bitmap.
1799 \begin_layout Itemize
1800 height: number: The height of the bitmap.
1803 \begin_layout Standard
1804 Get size of bitmap <bitmap>.
1807 \begin_layout Subsubsection
1808 Method blit: Blit a bitmap into another
1811 \begin_layout Itemize
1812 Syntax: dest:blit(dx, dy, src, sx, sy, w, h, [ck])
1815 \begin_layout Itemize
1816 Deprecated: gui.bitmap_blit(dest, ...)
1819 \begin_layout Standard
1823 \begin_layout Itemize
1824 dest: BITMAP: The target bitmap to blit to.
1827 \begin_layout Itemize
1828 dx: number: The x-coordinate in target.
1831 \begin_layout Itemize
1832 dy: number: The y-coordinate in target.
1835 \begin_layout Itemize
1836 src: BITMAP: The source bitmap.
1839 \begin_layout Itemize
1840 sx: number: The x-coordinate in source.
1843 \begin_layout Itemize
1844 sy: number: The y-coordinate in source.
1847 \begin_layout Itemize
1848 w: number: The width of area to blit.
1851 \begin_layout Itemize
1852 h: number: The height of area to blit.
1855 \begin_layout Itemize
1856 ck: number: The color key.
1857 Pixels with this index are not copied.
1861 \begin_layout Itemize
1862 If none is specified, all pixels are copied.
1866 \begin_layout Standard
1867 Copy region of size <w>*<h> at <sx>,<sy> in bitmap <src> into <dest> at
1869 If a color key <ck> is specified, pixels of that color are not copied.
1872 \begin_layout Subsubsection
1873 Method blit_scaled: Blit a bitmap into another with scaling
1876 \begin_layout Itemize
1877 Syntax: dest:blit_scaled(dx, dy, src, sx, sy, w, h, hscl, [vscl], [ck])
1880 \begin_layout Itemize
1881 Deprecated: gui.bitmap_blit_scaled(dest, ...)
1884 \begin_layout Standard
1888 \begin_layout Itemize
1889 dest: BITMAP: The target bitmap to blit to.
1892 \begin_layout Itemize
1893 dx: number: The x-coordinate in target.
1896 \begin_layout Itemize
1897 dy: number: The y-coordinate in target.
1900 \begin_layout Itemize
1901 src: BITMAP: The source bitmap.
1904 \begin_layout Itemize
1905 sx: number: The x-coordinate in source.
1908 \begin_layout Itemize
1909 sy: number: The y-coordinate in source.
1912 \begin_layout Itemize
1913 w: number: The width of area to blit.
1916 \begin_layout Itemize
1917 h: number: The height of area to blit.
1920 \begin_layout Itemize
1921 hscl: number: Horizontal scale factor (integer).
1924 \begin_layout Itemize
1925 vscl: number: Vertical scale factor (integer).
1926 Defaults to the same as <hscl>.
1929 \begin_layout Itemize
1930 ck: number: The color key.
1931 Pixels with this index are not copied.
1935 \begin_layout Itemize
1936 If none is specified, all pixels are copied.
1940 \begin_layout Standard
1941 Like BITMAP:blit, but also scales the copied part of bitmap (using nearest
1942 neighbor) by factor of <hscl>*<vscl>.
1945 \begin_layout Subsubsection
1946 Method blit_porterduff: Blit a bitmap into another with Porter-Duff composition
1949 \begin_layout Itemize
1950 Syntax: dest:blit_porterduff(dx, dy, src, sx, sy, w, h, operator)
1953 \begin_layout Itemize
1954 Deprecated: gui.bitmap_blit_porterduff(dest, ...)
1957 \begin_layout Standard
1961 \begin_layout Itemize
1962 dest: BITMAP: The target bitmap to blit to.
1965 \begin_layout Itemize
1966 dx: number: The x-coordinate in target.
1969 \begin_layout Itemize
1970 dy: number: The y-coordinate in target.
1973 \begin_layout Itemize
1974 src: BITMAP: The source bitmap.
1977 \begin_layout Itemize
1978 sx: number: The x-coordinate in source.
1981 \begin_layout Itemize
1982 sy: number: The y-coordinate in source.
1985 \begin_layout Itemize
1986 w: number: The width of area to blit.
1989 \begin_layout Itemize
1990 h: number: The height of area to blit.
1993 \begin_layout Itemize
1994 operator: string: The operator to use.
1998 \begin_layout Itemize
1999 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2000 DestOut, Clear or Xor.
2004 \begin_layout Standard
2005 Like BITMAP:blit, but instead of just overwriting, applies specified Porter-Duff
2010 \begin_layout Itemize
2011 Color index 0 in source and target is treated as background.
2014 \begin_layout Subsubsection
2015 Method blit_scaled_porterduff: Blit a bitmap into another with scaling and
2016 Porter-Duff composition
2019 \begin_layout Itemize
2020 Syntax: dest:blit_scaled_porterduff(dx, dy, src, sx, sy, w, h, hscl, [vscl],
2024 \begin_layout Itemize
2025 Deprecated: gui.bitmap_blit_scaled_porterduff(dest, ...)
2028 \begin_layout Standard
2032 \begin_layout Itemize
2033 dest: BITMAP: The target bitmap to blit to.
2036 \begin_layout Itemize
2037 dx: number: The x-coordinate in target.
2040 \begin_layout Itemize
2041 dy: number: The y-coordinate in target.
2044 \begin_layout Itemize
2045 src: BITMAP: The source bitmap.
2048 \begin_layout Itemize
2049 sx: number: The x-coordinate in source.
2052 \begin_layout Itemize
2053 sy: number: The y-coordinate in source.
2056 \begin_layout Itemize
2057 w: number: The width of area to blit.
2060 \begin_layout Itemize
2061 h: number: The height of area to blit.
2064 \begin_layout Itemize
2065 hscl: number: Horizontal scale factor (integer).
2068 \begin_layout Itemize
2069 vscl: number: Vertical scale factor (integer).
2070 Defaults to the same as <hscl>.
2073 \begin_layout Itemize
2074 operator: string: The operator to use.
2078 \begin_layout Itemize
2079 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2080 DestOut, Clear or Xor.
2084 \begin_layout Standard
2085 Like BITMAP:blit_porterduff, but also scales the source by <hscl>*<vscl>
2086 like BITMAP:blit_scaled.
2089 \begin_layout Subsubsection
2090 Method blit_priority: Blit a bitmap into another with color priority
2093 \begin_layout Itemize
2094 Syntax: dest:blit_priority(dx, dy, src, sx, sy, w, h)
2097 \begin_layout Itemize
2098 Deprecated: gui.bitmap_blit_priority(dest, ...)
2101 \begin_layout Standard
2105 \begin_layout Itemize
2106 dest: BITMAP: The target bitmap to blit to.
2109 \begin_layout Itemize
2110 dx: number: The x-coordinate in target.
2113 \begin_layout Itemize
2114 dy: number: The y-coordinate in target.
2117 \begin_layout Itemize
2118 src: BITMAP: The source bitmap.
2121 \begin_layout Itemize
2122 sx: number: The x-coordinate in source.
2125 \begin_layout Itemize
2126 sy: number: The y-coordinate in source.
2129 \begin_layout Itemize
2130 w: number: The width of area to blit.
2133 \begin_layout Itemize
2134 h: number: The height of area to blit.
2137 \begin_layout Standard
2138 Like BITMAP:blit, but only copy pixels where source color index is greater
2139 than destination color index.
2142 \begin_layout Subsubsection
2143 Method blit_scaled_priority: Blit a bitmap into another with color priority
2147 \begin_layout Itemize
2148 Syntax: dest:blit_scaled_priority(dx, dy, src, sx, sy, w, h, hscl, [vscl])
2151 \begin_layout Itemize
2152 Deprecated: gui.bitmap_blit_scaled_priority(dest, ...)
2155 \begin_layout Standard
2159 \begin_layout Itemize
2160 dest: BITMAP: The target bitmap to blit to.
2163 \begin_layout Itemize
2164 dx: number: The x-coordinate in target.
2167 \begin_layout Itemize
2168 dy: number: The y-coordinate in target.
2171 \begin_layout Itemize
2172 src: BITMAP: The source bitmap.
2175 \begin_layout Itemize
2176 sx: number: The x-coordinate in source.
2179 \begin_layout Itemize
2180 sy: number: The y-coordinate in source.
2183 \begin_layout Itemize
2184 w: number: The width of area to blit.
2187 \begin_layout Itemize
2188 h: number: The height of area to blit.
2191 \begin_layout Itemize
2192 hscl: number: Horizontal scale factor (integer).
2195 \begin_layout Itemize
2196 vscl: number: Vertical scale factor (integer).
2197 Defaults to the same as <hscl>.
2200 \begin_layout Standard
2201 Like BITMAP:blit_priority, but apply scaling by <hscl>*<vscl> like BITMAP:blit_s
2205 \begin_layout Subsubsection
2206 Method save_png: Save a bitmap to PNG
2209 \begin_layout Itemize
2210 Syntax: bitmap:save_png(filename, [base], palette)
2213 \begin_layout Itemize
2214 Syntax: data bitmap:save_png(palette)
2217 \begin_layout Itemize
2219 gui.bitmap_save_png(bitmap, ...)
2222 \begin_layout Standard
2226 \begin_layout Itemize
2227 bitmap: BITMAP: The bitmap to save.
2230 \begin_layout Itemize
2231 filename: string: The filename to save to.
2234 \begin_layout Itemize
2235 base: string: The base filename is resolved relative to.
2238 \begin_layout Itemize
2239 palette: PALETTE: The palette to use.
2242 \begin_layout Standard
2246 \begin_layout Itemize
2247 data: string: BASE64 encoded PNG data.
2250 \begin_layout Standard
2251 Save bitmap <bitmap>, with palette <pal> into PNG file <filename> (relative
2252 to <base>) or return BASE64 encoding of it.
2255 \begin_layout Subsubsection
2256 Method hash: Hash a bitmap
2259 \begin_layout Itemize
2260 Syntax: hash bitmap:hash()
2263 \begin_layout Itemize
2264 Deprecated: hash bitmap:hash(bitmap)
2267 \begin_layout Standard
2271 \begin_layout Itemize
2272 bitmap: BITMAP: The bitmap to hash.
2275 \begin_layout Standard
2279 \begin_layout Itemize
2280 hash: string: 64-hex digit hash
2283 \begin_layout Standard
2284 Hashes bitmap <bitmap> and returns crypto-strong hash.
2288 \begin_layout Itemize
2289 Color order in bitmap is significant.
2292 \begin_layout Standard
2293 \begin_inset Newpage pagebreak
2299 \begin_layout Subsection
2300 DBITMAP: Direct-color bitmap
2303 \begin_layout Subsubsection
2304 Static function: new: Create a new bitmap
2307 \begin_layout Itemize
2308 Syntax: bitmap gui.dbitmap.new(w, h, [fillcolor])
2311 \begin_layout Itemize
2312 Syntax: bitmap classes.DBITMAP.new(w, h, [fillcolor])
2315 \begin_layout Itemize
2316 Deprecated: bitmap gui.bitmap_new (w, h, true, [fillcolor]).
2319 \begin_layout Standard
2323 \begin_layout Itemize
2324 w: number: The width of new bitmap.
2327 \begin_layout Itemize
2328 h: number: The height of new bitmap.
2331 \begin_layout Itemize
2332 true: boolean: Fixed boolean true
2335 \begin_layout Itemize
2336 fillcolor: The color to fill the bitmap with (default transparent).
2339 \begin_layout Standard
2343 \begin_layout Itemize
2344 bitmap: DBITMAP: The new bitmap.
2347 \begin_layout Standard
2348 Create a new direct-color bitmap of size <w>*<h>, initially filled with
2352 \begin_layout Subsubsection
2353 Method draw: Draw a bitmap
2356 \begin_layout Itemize
2357 Syntax: bitmap.draw(x, y)
2360 \begin_layout Itemize
2361 Deprecated: gui.bitmap_draw(x, y, bitmap)
2364 \begin_layout Standard
2368 \begin_layout Itemize
2369 bitmap: DBITMAP: The bitmap to draw.
2372 \begin_layout Itemize
2373 x: number: X-coordinate on screen.
2376 \begin_layout Itemize
2377 y: number: Y-coordinate on screen.
2380 \begin_layout Standard
2381 Draw bitmap <bitmap> on screen at <x>,<y>.
2384 \begin_layout Subsubsection
2385 Method draw_outside: Draw a bitmap outside game area
2388 \begin_layout Itemize
2389 Syntax: dbitmap:draw_outside(x, y, palette)
2392 \begin_layout Standard
2393 Like dbitmap:draw, but does not draw on game area.
2396 \begin_layout Subsubsection
2397 Method draw_clip: Draw a bitmap, with clipping
2400 \begin_layout Itemize
2401 Syntax: dbitmap:draw(x, y, palette, x0, y0, width, height)
2404 \begin_layout Standard
2408 \begin_layout Itemize
2409 bitmap: DBITMAP: The bitmap to draw
2412 \begin_layout Itemize
2413 x: number: The x-coordinate on screen.
2416 \begin_layout Itemize
2417 y: number: The y-coordinate on screen.
2420 \begin_layout Itemize
2421 x0: The smallest bitmap x coordinate to draw.
2424 \begin_layout Itemize
2425 y0: The smallest bitmap y coordinate to draw.
2428 \begin_layout Itemize
2429 width: Width of region to draw
2432 \begin_layout Itemize
2433 height: Height of region to draw.
2436 \begin_layout Standard
2437 Like dbitmap:draw, but clip the bitmap area drawn.
2440 \begin_layout Subsubsection
2441 Method draw_clip_outside: Draw a bitmap outside game are, with clipping
2444 \begin_layout Itemize
2445 Syntax: dbitmap:draw_clip_outside(x, y, palette, x0, y0, width, height)
2448 \begin_layout Standard
2449 Like dbitmap:draw_clip, but only draw outside game area.
2452 \begin_layout Subsubsection
2453 Method pset: Set pixel in bitmap
2456 \begin_layout Itemize
2457 Syntax: bitmap:pset(x, y, color)
2460 \begin_layout Itemize
2461 Deprecaed: gui.bitmap_pset(bitmap, ...)
2464 \begin_layout Standard
2468 \begin_layout Itemize
2469 bitmap: DBITMAP: The bitmap to manipulate.
2472 \begin_layout Itemize
2473 x: number: x-coordinate of pixel to set.
2476 \begin_layout Itemize
2477 y: number: y-coordinate of pixel to set.
2480 \begin_layout Itemize
2481 color: number/string: The color to set.
2484 \begin_layout Standard
2485 Sets specified pixel <x>,<y> in bitmap <bitmap> to color <color>.
2488 \begin_layout Subsubsection
2489 Method pget: Get pixel in bitmap
2492 \begin_layout Itemize
2493 Syntax: color bitmap:pget(x,y)
2496 \begin_layout Itemize
2497 Deprecated: color gui.bitmap_pget(bitmap, ...)
2500 \begin_layout Standard
2504 \begin_layout Itemize
2505 bitmap: DBITMAP: The bitmap to query.
2508 \begin_layout Itemize
2509 x: number: x-coordinate of pixel to get.
2512 \begin_layout Itemize
2513 y: number: y-coordinate of pixel to get.
2516 \begin_layout Standard
2520 \begin_layout Itemize
2521 color: number: The color of specified pixel.
2524 \begin_layout Standard
2525 Gets color index of specified pixel <x>,<y> in bitmap <bitmap>.
2528 \begin_layout Subsubsection
2529 Method size: Get size of bitmap
2532 \begin_layout Itemize
2533 Syntax: width, height bitmap:size()
2536 \begin_layout Itemize
2537 Syntax: width, height gui.bitmap_size(bitmap)
2540 \begin_layout Standard
2544 \begin_layout Itemize
2545 bitmap: DBITMAP: The bitmap to query.
2548 \begin_layout Standard
2552 \begin_layout Itemize
2553 width: number: The width of the bitmap.
2556 \begin_layout Itemize
2557 height: number: The height of the bitmap.
2560 \begin_layout Standard
2561 Get size of bitmap <bitmap>.
2564 \begin_layout Subsubsection
2565 Method blit: Blit a bitmap into another
2568 \begin_layout Itemize
2569 Syntax: dest:blit(dx, dy, src, sx, sy, w, h, [ck])
2572 \begin_layout Itemize
2573 Syntax: dest:blit(dx, dy, src, srcpal, sx, sy, w, h, [ck])
2576 \begin_layout Itemize
2577 Deprecated: gui.bitmap_blit(dest, ...)
2580 \begin_layout Standard
2584 \begin_layout Itemize
2585 dest: DBITMAP: The target bitmap to blit to.
2588 \begin_layout Itemize
2589 dx: number: The x-coordinate in target.
2592 \begin_layout Itemize
2593 dy: number: The y-coordinate in target.
2596 \begin_layout Itemize
2597 src: BITMAP/DBITMAP: The source bitmap.
2600 \begin_layout Itemize
2601 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2604 \begin_layout Itemize
2605 sx: number: The x-coordinate in source.
2608 \begin_layout Itemize
2609 sy: number: The y-coordinate in source.
2612 \begin_layout Itemize
2613 w: number: The width of area to blit.
2616 \begin_layout Itemize
2617 h: number: The height of area to blit.
2620 \begin_layout Itemize
2621 ck: number: The color key.
2622 Pixels with this index are not copied.
2626 \begin_layout Itemize
2627 If none is specified, all pixels are copied.
2630 \begin_layout Itemize
2631 If <src> is paletted, this is color index, otherwise it is a color.
2635 \begin_layout Standard
2636 Copy region of size <w>*<h> at <sx>,<sy> in bitmap <src> (with palette <pal>
2637 if indexed) into <dest> at <dx>,<dy>.
2638 If a color key <ck> is specified, pixels of that color are not copied.
2641 \begin_layout Subsubsection
2642 Method blit_scaled: Blit a bitmap into another with scaling
2645 \begin_layout Itemize
2646 Syntax: dest:blit_scaled(dx, dy, src, sx, sy, w, h, hscl, [vscl], [ck])
2649 \begin_layout Itemize
2650 Syntax: dest:blit_scaled(dx, dy, src, srcpal, sx, sy, w, h, hscl, [vscl],
2654 \begin_layout Itemize
2655 Deprecated: gui.bitmap_blit_scaled(dest, ...)
2658 \begin_layout Standard
2662 \begin_layout Itemize
2663 dest: DBITMAP: The target bitmap to blit to.
2666 \begin_layout Itemize
2667 dx: number: The x-coordinate in target.
2670 \begin_layout Itemize
2671 dy: number: The y-coordinate in target.
2674 \begin_layout Itemize
2675 src: BITMAP/DBITMAP: The source bitmap.
2678 \begin_layout Itemize
2679 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2682 \begin_layout Itemize
2683 sx: number: The x-coordinate in source.
2686 \begin_layout Itemize
2687 sy: number: The y-coordinate in source.
2690 \begin_layout Itemize
2691 w: number: The width of area to blit.
2694 \begin_layout Itemize
2695 h: number: The height of area to blit.
2698 \begin_layout Itemize
2699 hscl: number: Horizontal scale factor (integer).
2702 \begin_layout Itemize
2703 vscl: number: Vertical scale factor (integer).
2704 Defaults to the same as <hscl>.
2707 \begin_layout Itemize
2708 ck: number: The color key.
2709 Pixels with this index are not copied.
2713 \begin_layout Itemize
2714 If none is specified, all pixels are copied.
2717 \begin_layout Itemize
2718 If <src> is paletted, this is color index, otherwise it is a color.
2722 \begin_layout Standard
2723 Like DBITMAP:blit, but also scales the copied part of bitmap (using nearest
2724 neighbor) by factor of <hscl>*<vscl>.
2727 \begin_layout Subsubsection
2728 Method blit_porterduff: Blit a bitmap into another with Porter-Duff composition
2731 \begin_layout Itemize
2732 Syntax: dest:blit_porterduff(dx, dy, src, sx, sy, w, h, operator)
2735 \begin_layout Itemize
2736 Syntax: dest:blit_porterduff(dx, dy, src, srcpal, sx, sy, w, h, operator)
2739 \begin_layout Itemize
2740 Deprecated: gui.bitmap_blit_porterduff(dest, ...)
2743 \begin_layout Standard
2747 \begin_layout Itemize
2748 dest: DBITMAP: The target bitmap to blit to.
2751 \begin_layout Itemize
2752 dx: number: The x-coordinate in target.
2755 \begin_layout Itemize
2756 dy: number: The y-coordinate in target.
2759 \begin_layout Itemize
2760 src: BITMAP/DBITMAP: The source bitmap.
2763 \begin_layout Itemize
2764 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2767 \begin_layout Itemize
2768 sx: number: The x-coordinate in source.
2771 \begin_layout Itemize
2772 sy: number: The y-coordinate in source.
2775 \begin_layout Itemize
2776 w: number: The width of area to blit.
2779 \begin_layout Itemize
2780 h: number: The height of area to blit.
2783 \begin_layout Itemize
2784 operator: string: The operator to use.
2788 \begin_layout Itemize
2789 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2790 DestOut, Clear or Xor.
2794 \begin_layout Standard
2795 Like DBITMAP:blit, but instead of just overwriting, applies specified Porter-Duf
2800 \begin_layout Itemize
2801 In target, fully transparent is background.
2802 In source, either fully transparent (if direct) or index 0 (if paletted)
2803 is treated as background.
2806 \begin_layout Subsubsection
2807 Method blit_scaled_porterduff: Blit a bitmap into another with scaling and
2808 Porter-Duff composition
2811 \begin_layout Itemize
2812 Syntax: dest:blit_scaled_porterduff(dx, dy, src, sx, sy, w, h, hscl, [vscl],
2816 \begin_layout Itemize
2817 Syntax: dest:blit_scaled_porterduff(dx, dy, src, srcpal, sx, sy, w, h, hscl,
2821 \begin_layout Itemize
2822 Deprecated: gui.bitmap_blit_scaled_porterduff(dest, ...)
2825 \begin_layout Standard
2829 \begin_layout Itemize
2830 dest: DBITMAP: The target bitmap to blit to.
2833 \begin_layout Itemize
2834 dx: number: The x-coordinate in target.
2837 \begin_layout Itemize
2838 dy: number: The y-coordinate in target.
2841 \begin_layout Itemize
2842 src: BITMAP/DBITMAP: The source bitmap.
2845 \begin_layout Itemize
2846 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2849 \begin_layout Itemize
2850 sx: number: The x-coordinate in source.
2853 \begin_layout Itemize
2854 sy: number: The y-coordinate in source.
2857 \begin_layout Itemize
2858 w: number: The width of area to blit.
2861 \begin_layout Itemize
2862 h: number: The height of area to blit.
2865 \begin_layout Itemize
2866 hscl: number: Horizontal scale factor (integer).
2869 \begin_layout Itemize
2870 vscl: number: Vertical scale factor (integer).
2871 Defaults to the same as <hscl>.
2874 \begin_layout Itemize
2875 operator: string: The operator to use.
2879 \begin_layout Itemize
2880 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2881 DestOut, Clear or Xor.
2885 \begin_layout Standard
2886 Like DBITMAP:blit_porterduff, but also scales the source by <hscl>*<vscl>
2887 like DBITMAP:blit_scaled.
2890 \begin_layout Subsubsection
2891 Method adjust_transparency: Adjust transparency of bitmap
2894 \begin_layout Itemize
2895 Syntax: bitmap:adjust_transparency(newvalue)
2898 \begin_layout Itemize
2899 Deprecated: gui.adjust_transparency(bitmap, ...)
2902 \begin_layout Standard
2906 \begin_layout Itemize
2907 bitmap: DBITMAP: The bitmap to adjust.
2910 \begin_layout Itemize
2911 Number adj: The factor to multiply opaqueness with times 256.
2914 \begin_layout Standard
2915 Multiply opaqueness of all colors in bitmap <bitmap> by factor of <adj>/256.
2918 \begin_layout Subsubsection
2919 Method save_png: Save a bitmap to PNG
2922 \begin_layout Itemize
2923 Syntax: bitmap:save_png(filename, [base])
2926 \begin_layout Itemize
2927 Syntax: data bitmap:save_png()
2930 \begin_layout Itemize
2932 gui.bitmap_save_png(bitmap, ...)
2935 \begin_layout Standard
2939 \begin_layout Itemize
2940 bitmap: DBITMAP: The bitmap to save.
2943 \begin_layout Itemize
2944 filename: string: The filename to save to.
2947 \begin_layout Itemize
2948 base: string: The base filename is resolved relative to.
2951 \begin_layout Standard
2955 \begin_layout Itemize
2956 data: string: BASE64 encoded PNG data.
2959 \begin_layout Standard
2960 Save bitmap <bitmap> into PNG file <filename> (relative to <base>) or return
2961 BASE64 encoding of it.
2964 \begin_layout Subsubsection
2965 Method hash: Hash a bitmap
2968 \begin_layout Itemize
2969 Syntax: hash bitmap:hash()
2972 \begin_layout Itemize
2973 Deprecated: hash bitmap:hash(bitmap)
2976 \begin_layout Standard
2980 \begin_layout Itemize
2981 bitmap: DBITMAP: The bitmap to hash.
2984 \begin_layout Standard
2988 \begin_layout Itemize
2989 hash: string: 64-hex digit hash
2992 \begin_layout Standard
2993 Hashes bitmap <bitmap> and returns crypto-strong hash.
2997 \begin_layout Subsection
2998 IMAGELOADER: Load an image
3001 \begin_layout Subsubsection
3002 Static function load: Load a bitmap from file
3005 \begin_layout Itemize
3006 Syntax: bitmap, palette gui.image.load(file, [base])
3009 \begin_layout Itemize
3010 Syntax: bitmap, palette classes.IMAGELOADER.load(file, [base])
3013 \begin_layout Itemize
3015 gui.bitmap_load(...)
3018 \begin_layout Standard
3022 \begin_layout Itemize
3023 file: string: The file to read.
3026 \begin_layout Itemize
3027 base: string: The base to resolve <file> relative to.
3030 \begin_layout Standard
3034 \begin_layout Itemize
3035 bitmap: BITMAP/DBITMAP: The new bitmap
3038 \begin_layout Itemize
3039 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3043 \begin_layout Standard
3044 Load a new bitmap and return it (plus associated palette if any).
3047 \begin_layout Subsubsection
3048 Static function load_str: Load a bitmap from string
3051 \begin_layout Itemize
3052 Syntax: bitmap, palette gui.image.load_str(data)
3055 \begin_layout Itemize
3056 Syntax: bitmap, palette classes.IMAGELOADER.load_str(data)
3059 \begin_layout Itemize
3061 gui.bitmap_load_str(...)
3064 \begin_layout Standard
3068 \begin_layout Itemize
3069 data: string: The image data
3072 \begin_layout Standard
3076 \begin_layout Itemize
3077 bitmap: BITMAP/DBITMAP: The new bitmap
3080 \begin_layout Itemize
3081 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3085 \begin_layout Standard
3086 Like IMAGELOADER:load, but read the bitmap from string <data> instead of
3090 \begin_layout Subsubsection
3091 Static function load_png: Load a bitmap from PNG file
3094 \begin_layout Itemize
3095 Syntax: bitmap, palette gui.image.load_png(file, [base])
3098 \begin_layout Itemize
3099 Syntax: bitmap, palette classes.IMAGELOADER.load_png(file, [base])
3102 \begin_layout Itemize
3104 gui.bitmap_load_png(...)
3107 \begin_layout Standard
3111 \begin_layout Itemize
3112 file: string: The file to read.
3115 \begin_layout Itemize
3116 base: string: The base to resolve <file> relative to.
3119 \begin_layout Standard
3123 \begin_layout Itemize
3124 bitmap: BITMAP/DBITMAP: The new bitmap
3127 \begin_layout Itemize
3128 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3132 \begin_layout Standard
3133 Like IMAGELOADER:load, but load a PNG file instead.
3136 \begin_layout Subsubsection
3137 Static function load_png_str: Load a PNG bitmap from string
3140 \begin_layout Itemize
3141 Syntax: bitmap, palette gui.image.load_png_str(data)
3144 \begin_layout Itemize
3145 Syntax: bitmap, palette classes.IMAGELOADER.load_png_str(data)
3148 \begin_layout Itemize
3150 gui.bitmap_load_png_str(...)
3153 \begin_layout Standard
3157 \begin_layout Itemize
3158 data: string: The image data, base64 encoded.
3161 \begin_layout Standard
3165 \begin_layout Itemize
3166 bitmap: BITMAP/DBITMAP: The new bitmap
3169 \begin_layout Itemize
3170 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3174 \begin_layout Standard
3175 Like IMAGELOADER:load_png, but read the bitmap from BASE64 encoded string
3176 <data> instead of file.
3179 \begin_layout Standard
3180 \begin_inset Newpage pagebreak
3186 \begin_layout Subsection
3187 CUSTOMFONT: Arbitrary-sized bitmap font
3190 \begin_layout Subsubsection
3191 Static function new: Return a new empty font
3194 \begin_layout Itemize
3195 Syntax: font gui.font.new()
3198 \begin_layout Itemize
3199 Syntax: font classes.CUSTOMFONT.new()
3202 \begin_layout Itemize
3203 Deprecated: font gui.font_new()
3206 \begin_layout Standard
3210 \begin_layout Itemize
3211 font: CUSTOMFONT: New font.
3214 \begin_layout Standard
3215 Create a new font with no characters and return it.
3218 \begin_layout Subsubsection
3219 Static function: load: Load a font file
3222 \begin_layout Itemize
3223 Syntax: font gui.font.load(file, [base])
3226 \begin_layout Itemize
3227 Syntax: font gui.font.load()
3230 \begin_layout Itemize
3231 Syntax: font classes.CUSTOMFONT.load(file, [base])
3234 \begin_layout Itemize
3235 Syntax: font classes.CUSTOMFONT.load()
3238 \begin_layout Itemize
3239 Deprecated: font gui.loadfont(...)
3242 \begin_layout Standard
3246 \begin_layout Itemize
3247 file: string: The file to read the font from
3250 \begin_layout Itemize
3251 base: string: The file to resolve <file> relative to.
3254 \begin_layout Standard
3258 \begin_layout Itemize
3259 font: CUSTOMFONT: New font.
3262 \begin_layout Standard
3263 Load font from file <file> (relative to <base>).
3264 If no filename is given, system default font is loaded.
3267 \begin_layout Subsubsection
3268 operator(): Render text to screen
3271 \begin_layout Itemize
3272 Syntax: font(x, y, text, [fgc], [bgc], [hlc])
3275 \begin_layout Standard
3279 \begin_layout Itemize
3280 font: CUSTOMFONT: The font to use.
3283 \begin_layout Itemize
3284 x: number: The x-position on screen to draw to.
3287 \begin_layout Itemize
3288 y: number: The y-position on screen to draw to.
3291 \begin_layout Itemize
3292 text: string: The text to draw.
3295 \begin_layout Itemize
3296 fgc: number/string: Foreground color (default white).
3299 \begin_layout Itemize
3300 bgc: number/string: Background color (default transparent).
3303 \begin_layout Itemize
3304 hlc: number/string: Outline color (default transparent).
3307 \begin_layout Standard
3308 Draws a string <text> with specified font <font> and colors <fgc>,<bgc>,<hlc>
3312 \begin_layout Itemize
3313 If <hlc> is transparent, no outline is drawn.
3316 \begin_layout Subsubsection
3317 Method edit: Alter glyph in font
3320 \begin_layout Itemize
3321 Syntax: font:edit(character, glyph)
3324 \begin_layout Standard
3328 \begin_layout Itemize
3329 font: CUSTOMFONT: The font to edit.
3332 \begin_layout Itemize
3333 character: string: The character to edit (UTF-8 encoded).
3336 \begin_layout Itemize
3337 glyph: BITMAP: The bitmap to use.
3340 \begin_layout Standard
3341 Replace character <character> in font <font> by <glyph>.
3344 \begin_layout Itemize
3345 Color index 0 is background, everything else is foreground.
3348 \begin_layout Itemize
3349 <character> may be empty string, meaning the replacement character used
3353 \begin_layout Itemize
3354 <character> may be multi-codepoint string, meaning character used for that
3358 \begin_layout Standard
3359 \begin_inset Newpage pagebreak
3365 \begin_layout Subsection
3366 ICONV: Character set conversions
3369 \begin_layout Subsubsection
3370 Static function new: Create new character set converter
3373 \begin_layout Itemize
3374 Syntax: iconv iconv.new(from, to);
3377 \begin_layout Itemize
3378 Syntax: iconv classes.ICONV.new(from, to);
3381 \begin_layout Itemize
3382 Deprecated: iconv iconv_new(...);
3385 \begin_layout Standard
3389 \begin_layout Itemize
3390 from: string: The source character set.
3393 \begin_layout Itemize
3394 to: string: The target character set.
3397 \begin_layout Standard
3401 \begin_layout Itemize
3402 iconv: ICONV: The converter.
3405 \begin_layout Standard
3406 Create a character set converter, converting from <from> to <to> and return
3410 \begin_layout Subsubsection
3411 Operator(): Convert string fragment from character set to another
3414 \begin_layout Itemize
3415 Syntax: success, result, unconverted, error iconv(input)
3418 \begin_layout Standard
3422 \begin_layout Itemize
3423 iconv: ICONV: The context to use.
3426 \begin_layout Itemize
3427 input: string: The input to convert.
3430 \begin_layout Standard
3434 \begin_layout Itemize
3435 success: boolean: True if conversion was successful, false if not.
3438 \begin_layout Itemize
3439 result: string: The string (partially) converted.
3442 \begin_layout Itemize
3443 unconvered: number: Number of bytes that were not converted (only if <success>
3447 \begin_layout Itemize
3448 error: string: Error that caused conversion to stop (only if <success> is
3453 \begin_layout Itemize
3454 INVALID: The input string is invalid.
3457 \begin_layout Itemize
3458 INCOMPLETE: The input string cuts off in middle of character.
3461 \begin_layout Itemize
3462 INTERNALERR: Internal error.
3466 \begin_layout Standard
3467 Convert a string <input> using character set converter <iconv> and return
3471 \begin_layout Standard
3472 \begin_inset Newpage pagebreak
3478 \begin_layout Subsection
3479 FILEREADER: Read a file as a stream
3482 \begin_layout Subsubsection
3483 Static function open: Open a stream
3486 \begin_layout Itemize
3487 Syntax: handle filereader.open(file, [base])
3490 \begin_layout Itemize
3491 Syntax: handle classes.FILEREADER.open(file, [base])
3494 \begin_layout Itemize
3495 Deprecated: handle open_file(file, [base])
3498 \begin_layout Standard
3502 \begin_layout Itemize
3503 file: string: The filename to read.
3506 \begin_layout Itemize
3507 base: string: The base <file> is resolved against.
3510 \begin_layout Standard
3514 \begin_layout Itemize
3515 handle: FILEREADER: The new file reader.
3518 \begin_layout Standard
3519 Open file <file> (relative to <base>) and return a handle to it.
3522 \begin_layout Subsubsection
3523 operator(): Read line/bytes from stream
3526 \begin_layout Itemize
3527 Syntax: result handle()
3530 \begin_layout Itemize
3531 Syntax: result handle(bytes)
3534 \begin_layout Standard
3538 \begin_layout Itemize
3539 handle: FILEREADER: The handle to read from.
3542 \begin_layout Itemize
3543 bytes: Number of bytes to read (default is next line).
3546 \begin_layout Standard
3550 \begin_layout Itemize
3551 result: string: The read data, or nil on end-of-file.
3554 \begin_layout Standard
3555 Reads next line or <bytes> bytes from specified file handle <handle>.
3558 \begin_layout Itemize
3559 If reading specified number of bytes, the bytes are read in binary mode
3563 \begin_layout Itemize
3564 If reading next line, the line is read in text mode (any line ending is
3568 \begin_layout Subsubsection
3569 Method lines: Iterator to read all lines
3572 \begin_layout Itemize
3573 Syntax: for line in handle:lines() do ...
3577 \begin_layout Standard
3581 \begin_layout Itemize
3582 handle: FILEREADER: The handle to read.
3585 \begin_layout Standard
3589 \begin_layout Itemize
3590 A lua iterator with one variable.
3593 \begin_layout Standard
3594 Return a Lua iterator that iterates all the lines in <handle>.
3597 \begin_layout Standard
3598 \begin_inset Newpage pagebreak
3604 \begin_layout Subsection
3605 COMPARE_OBJ: Watch memory area for changes
3608 \begin_layout Standard
3609 Objects of this class allow fast checking for modifications to given memory
3613 \begin_layout Subsubsection
3614 Static function new: Create a checker
3617 \begin_layout Itemize
3618 Syntax: handle classes.COMPARE_OBJ.new({marea, offset|addrobj}, size, [rows,
3622 \begin_layout Itemize
3623 Syntax: handle memory.compare_new({marea, offset|addrobj}, size, rows, stride)
3626 \begin_layout Standard
3630 \begin_layout Itemize
3631 marea: string: The memory area to interpret <offset> against.
3634 \begin_layout Itemize
3635 offset: number: The initial offset in memory area.
3638 \begin_layout Itemize
3639 addrobj: ADDRESS: The memory address.
3642 \begin_layout Itemize
3643 size: number: The number of bytes in each row.
3646 \begin_layout Itemize
3647 rows: number: The number of rows.
3651 \begin_layout Itemize
3652 stride: number: The number of bytes offset increments from one row to next.
3655 \begin_layout Standard
3659 \begin_layout Itemize
3663 \begin_layout Standard
3664 Return an object watching specified memory area.
3667 \begin_layout Itemize
3668 Note: For fastest operation, limit checks to inside one memory area (that
3669 has to be mappable, individual RAM areas often are).
3672 \begin_layout Subsubsection
3673 operator(): Check area for modifications
3676 \begin_layout Itemize
3677 Syntax: boolean handle()
3680 \begin_layout Standard
3684 \begin_layout Itemize
3685 True if memory block has been modified since last call (or object creation
3686 if first call), false if not.
3689 \begin_layout Standard
3690 Check if the block has been modified.
3693 \begin_layout Subsection
3694 ADDRESS: Memory address
3697 \begin_layout Standard
3698 Objects of this class contain a memory address.
3701 \begin_layout Subsubsection
3702 Static function new: Create new memory address
3705 \begin_layout Itemize
3706 Syntax: ADDRESS classes.ADDRESS.new(string marea, number offset)
3709 \begin_layout Itemize
3710 Syntax: ADDRESS memory.address.new(string marea, number offset)
3713 \begin_layout Itemize
3714 Syntax: ADDRESS memory.mkaddr(string marea, number offset)
3717 \begin_layout Standard
3721 \begin_layout Itemize
3722 marea: The memory area
3725 \begin_layout Itemize
3726 offset: The offset in memory area.
3729 \begin_layout Standard
3733 \begin_layout Itemize
3737 \begin_layout Standard
3738 Construct a new memory address object.
3741 \begin_layout Subsubsection
3742 Method: addr: Get global address
3745 \begin_layout Itemize
3746 Syntax: number addr:addr()
3749 \begin_layout Standard
3753 \begin_layout Itemize
3754 addr: ADRESS: The original address.
3757 \begin_layout Standard
3761 \begin_layout Itemize
3762 The global address corresponding to this address.
3765 \begin_layout Subsubsection
3766 Method: vma: Get memory area
3769 \begin_layout Itemize
3770 Syntax: string addr:vma()
3773 \begin_layout Standard
3777 \begin_layout Itemize
3778 addr: ADRESS: The original address.
3781 \begin_layout Standard
3785 \begin_layout Itemize
3786 The memory area corresponding to this address.
3789 \begin_layout Subsubsection
3790 Method: offset: Get memory area offset
3793 \begin_layout Itemize
3794 Syntax: string addr:offset()
3797 \begin_layout Standard
3801 \begin_layout Itemize
3802 addr: ADRESS: The original address.
3805 \begin_layout Standard
3809 \begin_layout Itemize
3810 The offset in memory area corresponding to this address.
3813 \begin_layout Subsubsection
3814 Method: replace: Replace address part
3817 \begin_layout Itemize
3818 Syntax: ADDRESS addr:replace(offset[, bits])
3821 \begin_layout Standard
3825 \begin_layout Itemize
3826 addr: ADRESS: The original address.
3829 \begin_layout Itemize
3830 offset: number: The new offset
3833 \begin_layout Itemize
3834 bits: number: The number of LSB to replace.
3837 \begin_layout Standard
3841 \begin_layout Itemize
3842 The modified address
3845 \begin_layout Standard
3846 Returns a new address, with <bits> (all if missing) least significant bits
3847 of <addr> replaced by LSB of <offset>.
3850 \begin_layout Subsubsection
3851 Method: add: Add to address
3854 \begin_layout Itemize
3855 Syntax: ADDRESS addr:add(offset)
3858 \begin_layout Itemize
3859 Syntax: ADDRESS addr:add(number, stride)
3862 \begin_layout Itemize
3863 Syntax: ADDRESS addr:add(number, stride, offset)
3866 \begin_layout Standard
3870 \begin_layout Itemize
3871 addr: ADRESS: The original address.
3874 \begin_layout Itemize
3875 offset: number: Offset to add.
3878 \begin_layout Itemize
3879 number: number: Number of table strides to add.
3882 \begin_layout Itemize
3883 stride: number: The table stride.
3886 \begin_layout Standard
3890 \begin_layout Itemize
3891 The modified address
3894 \begin_layout Standard
3895 Adds <offset>, <number>*<stride> or <number>*<stride>+<offset> into specified
3899 \begin_layout Subsection
3900 ADDRESS:<op>: Read/Write memory
3903 \begin_layout Itemize
3904 Syntax: none addr:<op>(value)
3907 \begin_layout Itemize
3908 Syntax: number addr:<op>()
3911 \begin_layout Standard
3915 \begin_layout Itemize
3916 addr: ADDRESS: The address to read/write.
3919 \begin_layout Itemize
3920 value: number: The number to write.
3923 \begin_layout Standard
3927 \begin_layout Itemize
3931 \begin_layout Standard
3932 Read/Write value from/to given address <addr>.
3933 The value written is <value>.
3934 <Op> is of form: [i][s]<type>, where:
3937 \begin_layout Itemize
3938 <type> is one of 'byte', 'word', 'hword', 'dword', 'qword', 'float', 'double'.
3941 \begin_layout Itemize
3942 'i' signifies that the value is treated as opposite-to-normal endianess,
3945 \begin_layout Itemize
3946 's' signifies that value is treated as signed (not available for floating-point).
3949 \begin_layout Standard
3950 \begin_inset Newpage pagebreak
3956 \begin_layout Section
3960 \begin_layout Subsection
3961 print: Print values to console
3964 \begin_layout Itemize
3965 Syntax: none print(value...
3969 \begin_layout Standard
3970 Prints specified values to console.
3971 Can print any Lua type at least enough to identify the type and instance.
3974 \begin_layout Subsection
3975 tostringx: Format a value to string
3978 \begin_layout Itemize
3979 Syntax: string tostringx(value val)
3982 \begin_layout Standard
3983 Formats value <val> like print would, and returns the result as a string.
3986 \begin_layout Subsection
3987 exec: Execute lsnes commands
3990 \begin_layout Itemize
3991 Syntax: none exec(string cmd)
3994 \begin_layout Standard
3995 Execute lsnes command <cmd>.
3998 \begin_layout Subsection
3999 utime: Get current time
4002 \begin_layout Itemize
4003 Syntax: (number,number) utime()
4006 \begin_layout Standard
4007 Returns two numbers.
4008 First is time since some epoch in seconds, the second is microseconds mod
4009 10^6 since that epoch.
4012 \begin_layout Subsection
4013 set_idle_timeout: Run function after timeout when emulator is idle
4016 \begin_layout Itemize
4017 Syntax: none set_idle_timeout(number timeout)
4020 \begin_layout Standard
4021 Set number of microseconds to block idle for.
4022 After this timeout has expired, on_idle() will be called once.
4025 \begin_layout Subsection
4026 set_timer_timeout: Run function after timeout.
4029 \begin_layout Itemize
4030 Syntax: none set_timer_timeout(number timeout)
4033 \begin_layout Standard
4034 Set number of microseconds to block timer for.
4035 After this timeout has expired, on_timer() will be called once.
4038 \begin_layout Subsection
4039 bus_address: Look up address in system bus.
4042 \begin_layout Itemize
4043 Syntax: none bus_address(number bus_addr)
4046 \begin_layout Standard
4047 Returns virtual address corresponding to specified address on system bus.
4050 \begin_layout Subsection
4051 loopwrapper: Convert loop into callable function
4054 \begin_layout Itemize
4055 Syntax: function loopwrapper(function fun, ...)
4058 \begin_layout Standard
4059 Calls function <fun> with function and specified arguments.
4060 The function passed suspends execution until the function returned is called.
4061 Handy for linear flow control among multiple invocations of a hook.
4065 \begin_layout LyX-Code
4066 on_paint = loopwrapper(function(wait)
4070 \begin_layout LyX-Code
4075 \begin_layout LyX-Code
4077 \begin_inset Quotes eld
4081 \begin_inset Quotes erd
4087 \begin_layout LyX-Code
4092 \begin_layout LyX-Code
4097 \begin_layout LyX-Code
4101 \begin_layout Subsection
4102 list_bindings: List keybindings
4105 \begin_layout Itemize
4106 Syntax: table list_bindings([string cmd])
4109 \begin_layout Standard
4110 Get table of all keybindings, indexed by keyspec (modifiers|mask/key).
4111 If <cmd> is specified, the table is limited to that command.
4112 Also searches for controller keys.
4115 \begin_layout Subsection
4116 get_alias: Get expansion of alias
4119 \begin_layout Itemize
4120 Syntax: string get_alias(string aname)
4123 \begin_layout Standard
4124 Get expansion of given alias <aname>.
4127 \begin_layout Subsection
4128 set_alias: Set expansion of alias
4131 \begin_layout Itemize
4132 Syntax: none set_alias(string aname, string value)
4135 \begin_layout Standard
4136 Set expansion of given alias.
4139 \begin_layout Subsection
4140 create_ibind: Create invese binding
4143 \begin_layout Itemize
4144 Syntax: INVERSEBIND create_ibind(string name, string cmd)
4147 \begin_layout Standard
4148 Return object representing inverse binding with specified name <name> and
4149 specified command <cmd>.
4152 \begin_layout Itemize
4153 Note: To create press/release commands, use aliases +foo and -foo .
4156 \begin_layout Itemize
4157 Note: Keep the returned object around.
4160 \begin_layout Subsection
4161 create_command: Create a command
4164 \begin_layout Itemize
4165 Syntax: COMMANDBIND create_commmand(string name, function a)
4168 \begin_layout Itemize
4169 Syntax: COMMANDBIND create_commmand(string name, function a, function b)
4172 \begin_layout Standard
4173 Return object representing a command (pair).
4176 \begin_layout Itemize
4177 If only one function is specied, the command is level-sensitive, <a> is
4181 \begin_layout Itemize
4182 If <b> is function, the function is edge-sensitive, <a> is positive edge
4183 callback and <b> is negative edge callback.
4186 \begin_layout Itemize
4187 All callbacks get single argument: The parameters passed.
4190 \begin_layout Itemize
4191 Keep the returned object around.
4194 \begin_layout Subsection
4195 loadfile: Load Lua script
4198 \begin_layout Itemize
4199 Syntax: function loadfile(string filename[, string base])
4202 \begin_layout Standard
4203 Load lua script from <filename>, resolved relative to <base> (if empty,
4207 \begin_layout Subsection
4208 dofile: Execute Lua script
4211 \begin_layout Itemize
4212 Syntax: function dofile(string filename[, string base])
4215 \begin_layout Standard
4216 Execute lua script from <filename>, resolved relative to <base> (if empty,
4217 current directory) and return all return values.
4220 \begin_layout Subsection
4221 resolve_filename: Resolve name of file relative to another
4224 \begin_layout Itemize
4225 Syntax: string resolve_filename(string filename[, string base])
4228 \begin_layout Standard
4229 Resolve name of file <filename> relative to <base> and return the result.
4232 \begin_layout Subsection
4233 render_queue_function: Return paint function for render queue
4236 \begin_layout Itemize
4237 Syntax: function render_queue_function(RENDERQUEUE rq)
4240 \begin_layout Standard
4241 Return function that renders render queue <rq>.
4244 \begin_layout Itemize
4245 Handy for paint callback if one is using render queues updated in other
4250 \begin_layout LyX-Code
4251 handle = callback.paint:register(render_queue_function(my_rq));
4254 \begin_layout Subsection
4255 identify_class: Identify class of object
4258 \begin_layout Itemize
4259 Syntax: string identify_class(userdata object)
4262 \begin_layout Standard
4263 Identifies the class of userdata <object>, if possible.
4264 If no identification is possible, returns
4265 \begin_inset Quotes eld
4269 \begin_inset Quotes erd
4275 \begin_layout Subsection
4276 lookup_class: Lookup class by name
4279 \begin_layout Itemize
4280 Syntax: classobj lookup_class(string name)
4283 \begin_layout Standard
4284 Looks up class corresponding to <name>, if possible.
4285 If not found, returns nil.
4286 The classobj has following fields:
4289 \begin_layout Itemize
4290 _static_methods: Return static method names
4293 \begin_layout Itemize
4294 _class_methods: Return class method names
4297 \begin_layout Itemize
4298 <static-function-name>: The specified static function.
4301 \begin_layout Subsection
4302 all_classes: Get list of all classes
4305 \begin_layout Itemize
4310 \begin_layout Standard
4311 Get names of all classes available.
4314 \begin_layout Subsection
4318 \begin_layout Subsection
4322 \begin_layout Standard
4326 \begin_layout Subsection
4327 filereader: Class FILEREADER
4330 \begin_layout Standard
4331 See class FILEREADER.
4334 \begin_layout Standard
4335 \begin_inset Newpage pagebreak
4341 \begin_layout Section
4345 \begin_layout Standard
4346 Bitwise logical functions and related.
4349 \begin_layout Subsection
4350 bit.none/bit.bnot: Bitwise none or NOT function
4353 \begin_layout Itemize
4354 Syntax: number bit.none(number...)
4357 \begin_layout Itemize
4358 Syntax: number bit.bnot(number...)
4361 \begin_layout Standard
4362 48-bit bitwise NOT / NONE function (set bits that are set in none of the
4366 \begin_layout Subsection
4367 bit.any/bit.bor: Bitwise any or OR function
4370 \begin_layout Itemize
4371 Syntax: number bit.any(number...)
4374 \begin_layout Itemize
4375 Syntax: number bit.bor(number...)
4378 \begin_layout Standard
4379 48-bit bitwise OR / ANY function (set bits that are set in any of the arguments).
4382 \begin_layout Subsection
4383 bit.all/bit.band: Bitwise all or AND function
4386 \begin_layout Itemize
4387 Syntax: number bit.all(number...)
4390 \begin_layout Itemize
4391 Syntax: number bit.band(number...)
4394 \begin_layout Standard
4395 48-bit bitwise AND / ALL function (set bits that are set in all of the arguments
4399 \begin_layout Subsection
4400 bit.parity/bit.bxor: Bitwise parity or XOR function
4403 \begin_layout Itemize
4404 Syntax: number bit.parity(number...)
4407 \begin_layout Itemize
4408 Syntax: number bit.bxor(number...)
4411 \begin_layout Standard
4412 48-bit bitwise XOR / PARITY function (set bits that are set in odd number
4416 \begin_layout Subsection
4417 bit.lrotate: Rotate a number left
4420 \begin_layout Itemize
4421 Syntax: number bit.lrotate(number base[, number amount[, number bits]])
4424 \begin_layout Standard
4425 Rotate <bits>-bit (max 48, default 48) number <base> left by <amount> (default
4429 \begin_layout Subsection
4430 bit.rrotate: Rotate a number right
4433 \begin_layout Itemize
4434 Syntax: number bit.rrotate(number base[, number amount[, number bits]])
4437 \begin_layout Standard
4438 Rotate <bits>-bit (max 48, default 48) number <base> right by <amount> (default
4442 \begin_layout Subsection
4443 bit.lshift: Shift a number left
4446 \begin_layout Itemize
4447 Syntax: number bit.lshift(number base[, number amount[, number bits]])
4450 \begin_layout Standard
4451 Shift <bits>-bit (max 48, default 48) number <base> left by <amount> (default
4453 The new bits are filled with zeroes.
4456 \begin_layout Subsection
4457 bit.lrshift: Shift a number right (logical)
4460 \begin_layout Itemize
4461 Syntax: number bit.lrshift(number base[, number amount[, number bits]])
4464 \begin_layout Standard
4465 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
4467 The new bits are filled with zeroes.
4470 \begin_layout Subsection
4471 bit.arshift: Shift a number right (arithmetic)
4474 \begin_layout Itemize
4475 Syntax: number bit.arshift(number base[, number amount[, number bits]])
4478 \begin_layout Standard
4479 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
4481 The new bits are shifted in with copy of the high bit.
4484 \begin_layout Subsection
4485 bit.extract: Extract/shuffle bits from number
4488 \begin_layout Itemize
4489 Syntax: number bit.extract(number base[, number bit0[, number bit1,...]])
4492 \begin_layout Standard
4493 Returns number that has bit0-th bit as bit 0, bit1-th bit as 1 and so on.
4496 \begin_layout Itemize
4497 Note: Bit numbers up to 51 should work reliably (then things start falling
4498 apart due to double precision issues).
4501 \begin_layout Itemize
4502 Note: There are two special bit positions, true and false, standing for
4503 always set bit and always clear bit.
4506 \begin_layout Subsection
4507 bit.value: Construct number with specified bits set
4510 \begin_layout Itemize
4511 Syntax: number bit.value([number bit1[, number bit2,...]])
4514 \begin_layout Standard
4515 Returns bitwise OR of 1 left shifted by <bit1> places, 1 left shifted by
4516 <bit2> places and so on.
4517 As special value, nil argument is no-op.
4520 \begin_layout Subsection
4521 bit.test: Test if bit is set
4524 \begin_layout Itemize
4525 Syntax: boolean bit.test(number a, number bit)
4528 \begin_layout Standard
4529 Tests if bit <bit> is set in <a>.
4530 If it is set, returns true, otherwise false.
4533 \begin_layout Subsection
4534 bit.testn: Test if bit is clear
4537 \begin_layout Itemize
4538 Syntax: boolean bit.testn(number a, number bit)
4541 \begin_layout Standard
4542 Tests if bit <bit> is set in <a>.
4543 If it is clear, returns true, otherwise false.
4546 \begin_layout Subsection
4547 bit.test_any: Test if any bit is set
4550 \begin_layout Itemize
4551 Syntax: boolean bit.test_any(number a, number b)
4554 \begin_layout Standard
4555 Returns true if bitwise and of <a> and <b> is nonzero, otherwise false.
4558 \begin_layout Subsection
4559 bit.test_all: Test if all bits are set
4562 \begin_layout Itemize
4563 Syntax: boolean bit.test_all(number a, number b)
4566 \begin_layout Standard
4567 Returns true if bitwise and of <a> and <b> equals <b>, otherwise false.
4570 \begin_layout Subsection
4571 bit.popcount: Population count
4574 \begin_layout Itemize
4575 Syntax: number bit.popcount(number a)
4578 \begin_layout Standard
4579 Returns number of set bits in <a>.
4582 \begin_layout Subsection
4583 bit.clshift: Chained left shift
4586 \begin_layout Itemize
4587 Syntax: (number, number) bit.clshift(number a, number b, [number amount,[number
4591 \begin_layout Standard
4592 Does chained left shift on <a>, <b> by <amount> positions (default 1), assuming
4593 numbers to be of specified number of bits <bits> (default 48).
4596 \begin_layout Subsection
4597 bit.crshift: Chained right shift
4600 \begin_layout Itemize
4601 Syntax: (number, number) bit.crshift(number a, number b, [number amount,[number
4605 \begin_layout Standard
4606 Does chained right shift on <a>, <b> by <amount> positions (default 1),
4607 assuming numbers to be of specified number of bits <bits> (default 48).
4610 \begin_layout Subsection
4611 bit.flagdecode: Decode bitfield into flags
4614 \begin_layout Itemize
4615 Syntax: string bit.flagdecode(number a, number bits, [string on, [string
4619 \begin_layout Standard
4620 Return string of length bits where ith character is ith character of on
4621 if bit i is on, otherwise ith character of off.
4622 Out of range reads give last character.
4625 \begin_layout Itemize
4626 Note: <on> defaults to '*' if empty.
4629 \begin_layout Itemize
4630 Note: <off> defaults to '-' if empty.
4633 \begin_layout Subsection
4634 bit.rflagdecode: Decode bitfield into flags
4637 \begin_layout Itemize
4638 Syntax: string bit.rflagdecode(number a, number bits, [string on, [string
4642 \begin_layout Standard
4643 Like bit.flagdecode, but outputs the string in the opposite order (most significa
4647 \begin_layout Subsection
4648 bit.swap{,s}{,h,d,q}word: Swap word endian
4651 \begin_layout Itemize
4652 Syntax: number bit.swapword(number n)
4655 \begin_layout Itemize
4656 Syntax: number bit.swaphword(number n)
4659 \begin_layout Itemize
4660 Syntax: number bit.swapdword(number n)
4663 \begin_layout Itemize
4664 Syntax: number bit.swapqword(number n)
4667 \begin_layout Itemize
4668 Syntax: number bit.swapsword(number n)
4671 \begin_layout Itemize
4672 Syntax: number bit.swapshword(number n)
4675 \begin_layout Itemize
4676 Syntax: number bit.swapsdword(number n)
4679 \begin_layout Itemize
4680 Syntax: number bit.swapsqword(number n)
4683 \begin_layout Standard
4684 Swap endianess of (un)signed integer <n>.
4687 \begin_layout Subsection
4688 bit.compose: Compose multi-byte number
4691 \begin_layout Itemize
4692 Syntax: number bit.compose(number n...)
4695 \begin_layout Standard
4697 \begin_inset Formula $n_{1}+256n_{2}+256^{2}n_{3}+\ldots$
4703 \begin_layout Subsection
4704 bit.binary_ld_{{u,s}{8,16,24,32,64},float,double}{l,b}e: Load binary integer
4707 \begin_layout Itemize
4708 Syntax: number bit.binary_ld_<type>le(string str, number pos);
4711 \begin_layout Itemize
4712 Syntax: number bit.binary_ld_<type>be(string str, number pos);
4715 \begin_layout Standard
4716 Load little (*le) or big (*be) endian binary number from position <pos>
4718 Type may be one of: u8, u16, u24, u32, u64, s8, s16, s24, s32, s64, float,
4722 \begin_layout Subsection
4723 bit.binary_st_{{u,s}{8,16,24,32,64},float,double}{l,b}e: Store binary integer
4726 \begin_layout Itemize
4727 Syntax: string bit.binary_st_<type>le(number x);
4730 \begin_layout Itemize
4731 Syntax: string bit.binary_st_<type>be(number x);
4734 \begin_layout Standard
4735 Store specified number <x> as binary in string and return the result.
4736 Type may be one of: u8, u16, u24, u32, u64, s8, s16, s24, s32, s64, float,
4740 \begin_layout Subsection
4741 bit.quotent: Integer quotent
4744 \begin_layout Itemize
4745 Syntax: number bit.quotent(number a, number b)
4748 \begin_layout Standard
4749 Calculate quotent a/b.
4752 \begin_layout Subsection
4753 bit.multidiv: Divide and split among multiple divisiors
4756 \begin_layout Itemize
4758 bit.multidiv(number v, number q...)
4761 \begin_layout Standard
4762 Does the following steps:
4765 \begin_layout Enumerate
4769 \begin_layout Enumerate
4774 \begin_layout Enumerate
4775 Calculate quotent(v'/q) and add that to numbers returned.
4778 \begin_layout Enumerate
4779 v' <- remainder(v'/q)
4783 \begin_layout Enumerate
4784 Add v' to numbers returned.
4787 \begin_layout Standard
4788 That is, it successively divides <v> by <q>s, and reduces <v> modulo <q>
4790 <v> may be floating point, <q>s are integers.
4793 \begin_layout Itemize
4795 bit.multidiv(time, 3600, 60) splits time into hours, minutes and seconds.
4798 \begin_layout Itemize
4800 bit.multidiv(a, b) calculates quotent and remainder of a/b.
4803 \begin_layout Subsection
4804 bit.mul32: 32-bit multiply
4807 \begin_layout Itemize
4808 Syntax: number, number bit.mul32(number a, number b)
4811 \begin_layout Standard
4812 Multiply 32-bit numbers <a> and <b>.
4813 The first return value is low 32 bits of result, the second is high 32
4817 \begin_layout Standard
4818 \begin_inset Newpage pagebreak
4824 \begin_layout Section
4828 \begin_layout Subsection
4829 classes.<foo>: The classobj for class <foo>
4832 \begin_layout Itemize
4833 Syntax: classes.<foo>
4836 \begin_layout Standard
4837 The classobj for class <foo>.
4840 \begin_layout Subsection
4841 classes.<foo>._static_methods: Enumerate static methods
4844 \begin_layout Itemize
4846 classes.<foo>._static_methods()
4849 \begin_layout Standard
4850 Returns all static methods of <foo> as strings.
4853 \begin_layout Subsection
4854 classes.<foo>._class_methods: Enumerate static methods
4857 \begin_layout Itemize
4859 classes.<foo>._class_methods()
4862 \begin_layout Standard
4863 Returns all class methods of <foo> as strings.
4866 \begin_layout Subsection
4867 classes.<foo>.<bar>: Static method
4870 \begin_layout Itemize
4871 Syntax: variable classes.<foo>.<bar>(variable...)
4874 \begin_layout Standard
4875 Invokes static method <bar> of class <foo>.
4878 \begin_layout Section
4882 \begin_layout Subsection
4883 gui.resolution: Get current resolution
4886 \begin_layout Itemize
4887 Syntax: (number, number) gui.resolution()
4890 \begin_layout Standard
4891 Returns 2-tuple (hresolution, vresolution).
4894 \begin_layout Subsection
4895 gui.left_gap/gui.right_gap/gui.top_gap/gui.bottom_gap: Set edge gaps
4898 \begin_layout Itemize
4899 Syntax: number gui.left_gap(number gap)
4902 \begin_layout Itemize
4903 Syntax: number gui.right_gap(number gap)
4906 \begin_layout Itemize
4907 Syntax: number gui.top_gap(number gap)
4910 \begin_layout Itemize
4911 Syntax: number gui.bottom_gap(number gap)
4914 \begin_layout Standard
4915 Set the specified edge gap to specified value <gap> (max gap is 8191).
4916 If successful, old gap is returned.
4919 \begin_layout Subsection
4920 gui.delta_left_gap/gui.delta_right_gap/gui.delta_top_gap/gui.delta_bottom_gap:
4924 \begin_layout Itemize
4925 Syntax: number gui.delta_left_gap(number dgap)
4928 \begin_layout Itemize
4929 Syntax: number gui.delta_right_gap(number dgap)
4932 \begin_layout Itemize
4933 Syntax: number gui.delta_top_gap(number dgap)
4936 \begin_layout Itemize
4937 Syntax: number gui.delta_bottom_gap(number dgap)
4940 \begin_layout Standard
4941 Increase the specified edge gap by specified value <dgap> (max gap is 8191)
4942 and return the old gap (returns nothing on error).
4945 \begin_layout Subsection
4946 gui.text/gui.textH/gui.textV,gui.textHV: Draw text
4949 \begin_layout Itemize
4950 Syntax: none gui.text(number x, number y, string text[, number fgc[, number
4954 \begin_layout Itemize
4955 Syntax: none gui.textH(number x, number y, string text[, number fgc[, number
4959 \begin_layout Itemize
4960 Syntax: none gui.textV(number x, number y, string text[, number fgc[, number
4964 \begin_layout Itemize
4965 Syntax: none gui.textHV(number x, number y, string text[, number fgc[, number
4969 \begin_layout Standard
4970 Draw specified text on the GUI (each character cell is 8 or 16 wide and
4975 \begin_layout Itemize
4976 x: X-coordinate to start the drawing from (and x-coordinate at begining
4980 \begin_layout Itemize
4981 y: Y-coordinate to start the drawing from.
4984 \begin_layout Itemize
4985 text: The text to draw.
4988 \begin_layout Itemize
4989 fgc: Text color (default is 0xFFFFFF (white))
4992 \begin_layout Itemize
4993 bgc: Background color (default is -1 (transparent))
4996 \begin_layout Standard
4997 Note: The H variants draw at double width and V variants draw at double
5001 \begin_layout Subsection
5002 gui.rectangle: Draw a rectangle
5005 \begin_layout Itemize
5006 Syntax: none gui.rectangle(number x, number y, number width, number height[,
5007 number thickness[, number outline[, number fill]]])
5010 \begin_layout Standard
5011 Draw rectangle on the GUI.
5015 \begin_layout Itemize
5016 x: X-coordinate of left edge.
5019 \begin_layout Itemize
5020 y: Y-coordinate of upper edge.
5023 \begin_layout Itemize
5024 width: Width of rectangle.
5027 \begin_layout Itemize
5028 height: Height of rectangle.
5031 \begin_layout Itemize
5032 thickness: Thickness of outline (default is 1).
5035 \begin_layout Itemize
5036 outline: Color of outline (default is 0xFFFFFF (white))
5039 \begin_layout Itemize
5040 fill: Color of fill (default is -1 (transparent))
5043 \begin_layout Subsection
5044 gui.solidrectangle: Draw a solid rectangle
5047 \begin_layout Itemize
5048 Syntax: none gui.rectangle(number x, number y, number width, number height[,
5052 \begin_layout Standard
5053 Draw solid rectangle on the GUI.
5057 \begin_layout Itemize
5058 x: X-coordinate of left edge.
5061 \begin_layout Itemize
5062 y: Y-coordinate of upper edge.
5065 \begin_layout Itemize
5066 width: Width of rectangle.
5069 \begin_layout Itemize
5070 height: Height of rectangle.
5073 \begin_layout Itemize
5074 color: Color of rectangle (default is 0xFFFFFF (white))
5077 \begin_layout Subsection
5078 gui.box: Draw a 3D-effect box
5081 \begin_layout Itemize
5082 Syntax: none gui.box(number x, number y, number width, number height[, number
5083 thickness[, number outline1[,number outline2[, number fill]]]])
5086 \begin_layout Standard
5087 Draw rectangle with 3D effect on the GUI.
5091 \begin_layout Itemize
5092 x: X-coordinate of left edge.
5095 \begin_layout Itemize
5096 y: Y-coordinate of upper edge.
5099 \begin_layout Itemize
5100 width: Width of rectangle.
5103 \begin_layout Itemize
5104 height: Height of rectangle.
5107 \begin_layout Itemize
5108 thickness: Thickness of outline (default is 1).
5111 \begin_layout Itemize
5112 outline1: First color of outline (default is 0xFFFFFF (white))
5115 \begin_layout Itemize
5116 outline2: First color of outline (default is 0x808080 (dark gray))
5119 \begin_layout Itemize
5120 fill: Color of fill (default is 0xC0C0C0 (light grayy))
5123 \begin_layout Subsection
5124 gui.pixel: Draw a single pixel
5127 \begin_layout Itemize
5128 Syntax: none gui.pixel(number x, number y[, number color])
5131 \begin_layout Standard
5132 Draw one pixel on the GUI.
5136 \begin_layout Itemize
5137 x: X-coordinate of the pixel
5140 \begin_layout Itemize
5141 y: Y-coordinate of the pixel
5144 \begin_layout Itemize
5145 color: Color of the pixel (default is 0xFFFFFF (white))
5148 \begin_layout Subsection
5149 gui.crosshair: Draw a crosshair
5152 \begin_layout Itemize
5153 Syntax: none gui.crosshair(number x, number y[, number length[, number color]])
5156 \begin_layout Standard
5161 \begin_layout Itemize
5162 x: X-coordinate of the crosshair
5165 \begin_layout Itemize
5166 y: Y-coordinate of the crosshair
5169 \begin_layout Itemize
5170 length: Length of the crosshair lines (default 10).
5173 \begin_layout Itemize
5174 color: Color of the crosshair (default is 0xFFFFFF (white))
5177 \begin_layout Subsection
5178 gui.line: Draw a line
5181 \begin_layout Itemize
5182 Syntax: none gui.line(number x1, number y1, number x2, number y2[, number
5186 \begin_layout Standard
5191 \begin_layout Itemize
5192 x1: X-coordinate of one end.
5195 \begin_layout Itemize
5196 y1: Y-coordinate of one end.
5199 \begin_layout Itemize
5200 x2: X-coordinate of the other end.
5203 \begin_layout Itemize
5204 y2: Y-coordinate of the other end.
5207 \begin_layout Itemize
5208 color: Color of the line (default is 0xFFFFFF (white)).
5211 \begin_layout Subsection
5212 gui.circle: Draw a (filled) circle
5215 \begin_layout Itemize
5216 Syntax: none gui.circle(number x, number y, number r[, number thick[, number
5217 border[, number fil]]])
5220 \begin_layout Standard
5225 \begin_layout Itemize
5226 x: X-coordinate of the center
5229 \begin_layout Itemize
5230 y: Y-coordinate of the center
5233 \begin_layout Itemize
5234 r: The radius of the circle
5237 \begin_layout Itemize
5238 thick: Border thickness
5241 \begin_layout Itemize
5242 border: Border color (default is 0xFFFFFF (white))
5245 \begin_layout Itemize
5246 fill: Fill color (default is -1 (transparent)).
5249 \begin_layout Subsection
5250 gui.repaint: Arrange a repaint
5253 \begin_layout Itemize
5254 Syntax: none gui.repaint()
5257 \begin_layout Standard
5258 Request on_repaint() to happen as soon as possible.
5261 \begin_layout Subsection
5262 gui.subframe_update: Enable/Disable subframe updates
5265 \begin_layout Itemize
5266 Syntax: none gui.subframe_update(boolean on)
5269 \begin_layout Standard
5270 Request subframe updates (calling on_paint() on subframes) to happen (<on>=true)
5271 or not happen (<on>=false).
5274 \begin_layout Subsection
5275 gui.screenshot: Write a screenshot
5278 \begin_layout Itemize
5279 Syntax: none gui.screenshot(string filename)
5282 \begin_layout Standard
5283 Write PNG screenshot of the current frame (no drawings) to specified file
5287 \begin_layout Subsection
5288 gui.screenshot_bitmap: Write a screenshot to bitmap
5291 \begin_layout Itemize
5292 Syntax: DBITMAP gui.screenshot_bitmap()
5295 \begin_layout Standard
5296 Write PNG screenshot of the current frame (no drawings) to dbitmap and return
5300 \begin_layout Subsection
5301 gui.color: Compose a color.
5304 \begin_layout Itemize
5305 Syntax: number gui.color(number r, number g, number b[, number a])
5308 \begin_layout Itemize
5309 Syntax: number gui.color(string c)
5312 \begin_layout Standard
5313 Returns color (in notation Lua scripts use) corresponding to color (<r>,<g>,<b>)
5314 , each component in scale 0-255.
5315 If <a> is specified, that is alpha (0 is fully transparent, 256(sic) is
5317 The default alpha is 256.
5320 \begin_layout Standard
5321 The form taking a string returns color corresponding color name.
5324 \begin_layout Subsection
5325 gui.status: Set status variable
5328 \begin_layout Itemize
5329 Syntax: none gui.status(string name, string value)
5332 \begin_layout Standard
5334 \begin_inset Quotes eld
5338 \begin_inset Quotes erd
5341 to <value> in status area.
5344 \begin_layout Subsection
5345 gui.rainbow: Rainbow color calculation
5348 \begin_layout Itemize
5349 Syntax: number gui.rainbow(number step, number steps[, number color])
5352 \begin_layout Standard
5353 Perform hue rotation of color <color> (default bright red), by <step> steps.
5354 The number of steps per full rotation is given by absolute value of <steps>.
5357 \begin_layout Standard
5358 If <step> is negative, the rotation will be counterclockwise.
5361 \begin_layout Subsection
5362 gui.kill_frame: Kill video frame and associated sound
5365 \begin_layout Itemize
5366 Syntax: none gui.kill_frame()
5369 \begin_layout Standard
5370 Kills the currently dumped video frame + the associated sound.
5371 Only valid in on_video callback.
5374 \begin_layout Subsection
5375 gui.set_video_scale: Set video frame scale
5378 \begin_layout Itemize
5379 Syntax: none gui.set_video_scale(number h, number v)
5382 \begin_layout Standard
5383 Sets the scale factors of current frame to <h>x<v>.
5384 Only valid in on_video callback.
5387 \begin_layout Subsection
5388 gui.arrow: Draw an arrow
5391 \begin_layout Itemize
5392 Syntax: none gui.arrow(number x, number y, number length, number hwidth,
5393 number direction[, bool fill[, number color[, number twidth[, number hthick]]]]
5397 \begin_layout Standard
5398 Draws an arrow using color <color>.
5399 The tip of arrow is at (<x>, <y>).
5403 \begin_layout Enumerate
5404 <length>: The length of arrow tail.
5407 \begin_layout Enumerate
5408 <hwidth>: The width of arrow head.
5412 \begin_layout Enumerate
5413 <direction>: Direction of arrow.
5414 0 is to right, +1 rotates 45 degrees counterclockwise.
5417 \begin_layout Enumerate
5418 <fill>: If true, fill the arrow head.
5422 \begin_layout Enumerate
5423 <twidth>: Tail width.
5428 \begin_layout Enumerate
5429 <hthick>: Head thickness (only used if <fill> is false).
5430 Default is <twidth>.
5433 \begin_layout Subsection
5434 gui.tiled_bitmap: Class TILEMAP
5437 \begin_layout Standard
5441 \begin_layout Subsection
5442 gui.palette: Class PALETTE
5445 \begin_layout Standard
5449 \begin_layout Subsection
5450 gui.bitmap: Class BITMAP
5453 \begin_layout Standard
5457 \begin_layout Subsection
5458 gui.dbitmap: Class DBITMAP
5461 \begin_layout Standard
5465 \begin_layout Subsection
5466 gui.font: Class CUSTOMFONT
5469 \begin_layout Standard
5470 See class CUSTOMFONT.
5473 \begin_layout Subsection
5474 gui.renderctx: Class RENDERCTX
5477 \begin_layout Standard
5478 See class RENDERCTX.
5481 \begin_layout Subsection
5482 gui.image: Class IMAGELOADER
5485 \begin_layout Standard
5486 See class IMAGELOADER.
5489 \begin_layout Subsection
5490 gui.get_runmode: Get current emulator mode
5493 \begin_layout Itemize
5494 Syntax: string gui.get_runmode()
5497 \begin_layout Standard
5498 Gets the current emulator runmode.
5499 The possible ones are:
5502 \begin_layout Itemize
5503 quit: Emulator is quitting.
5506 \begin_layout Itemize
5507 normal: Emulator is running emulation
5510 \begin_layout Itemize
5511 load: Emulator is loading a movie/savestate
5514 \begin_layout Itemize
5515 advance_frame: Emulator is doing frame advance
5518 \begin_layout Itemize
5519 advance_subframe: Emulator is doing subframe advance
5522 \begin_layout Itemize
5523 skiplag: Emulator is skipping lag frames
5526 \begin_layout Itemize
5527 skiplag_pending: Emulator will start skipping lag frames next frame
5530 \begin_layout Itemize
5531 pause: Emulator is paused
5534 \begin_layout Itemize
5535 pause_break: Emulator is paused at breakpoint
5538 \begin_layout Itemize
5539 corrupt: Emulator can't run because corrupt emulation state
5542 \begin_layout Itemize
5543 unknown: Unknown state (should not happen).
5546 \begin_layout Standard
5547 \begin_inset Newpage pagebreak
5553 \begin_layout Section
5557 \begin_layout Standard
5559 Functions manipulating input are only available in on_input callback.
5562 \begin_layout Subsection
5563 input.get: Read controller button/axis (deprecated)
5566 \begin_layout Itemize
5567 Syntax: number input.get(number controller, number index)
5570 \begin_layout Standard
5571 Read the specified index <index> (zero-based) from specified controller
5572 <controller> (zero-based).
5576 \begin_layout Subsection
5577 input.set: Write controller button/axis (deprecated)
5580 \begin_layout Itemize
5581 Syntax: none input.set(number controller, number index, number value)
5584 \begin_layout Standard
5585 Write the specified index <index> (zero-based) from specified controller
5586 <controller> (zero-based), storing value <value>.
5589 \begin_layout Subsection
5590 input.get2: Read controller button/axis
5593 \begin_layout Itemize
5594 Syntax: number input.get2(number port, number controller, number index)
5597 \begin_layout Standard
5598 Read the specified input tuple.
5599 Port 0 is system port.
5602 \begin_layout Subsection
5603 input.set2: Write controller button/axis
5606 \begin_layout Itemize
5607 Syntax: input.set2(number port, number controller, number index, number value)
5610 \begin_layout Standard
5611 Write the specified input tuple.
5612 Port 0 is system port.
5615 \begin_layout Subsection
5616 input.lcid_to_pcid2: Look up logical controller
5619 \begin_layout Itemize
5620 Syntax: (number, number) input.lcid_to_pcid2(number lcid)
5623 \begin_layout Standard
5624 Look up physical pcid pair (port, controller) corresponding to specified
5625 logical controller (1-based).
5626 Returns nothing if controller does not exist.
5629 \begin_layout Subsection
5630 input.port_type: Look up port type
5633 \begin_layout Itemize
5634 Syntax: string input.port_type(number port)
5637 \begin_layout Standard
5638 Return type of specified port.
5641 \begin_layout Subsection
5642 input.controller_info: Get information about controller
5645 \begin_layout Itemize
5646 Syntax: table input.controller_info(number port, number controller)
5649 \begin_layout Standard
5650 Get controller info for specified controller.
5651 If controller does not exist, returns nil.
5652 Otherwise returns a table with following fields:
5655 \begin_layout Itemize
5656 type (string): Type of the controller.
5659 \begin_layout Itemize
5660 class (string): Class of the controller.
5663 \begin_layout Itemize
5664 classnum (number): Number of the controller within its class (1-based)
5667 \begin_layout Itemize
5668 lcid (number): Logical controller number of the controller.
5671 \begin_layout Itemize
5672 button_count (number): Number of buttons on controller
5675 \begin_layout Itemize
5676 buttons (array): Array of following info about each button:
5680 \begin_layout Itemize
5681 type (string): Type of button.
5683 \begin_inset Quotes eld
5687 \begin_inset Quotes erd
5691 \begin_inset Quotes eld
5695 \begin_inset Quotes erd
5699 \begin_inset Quotes eld
5703 \begin_inset Quotes erd
5707 \begin_inset Quotes eld
5711 \begin_inset Quotes erd
5717 \begin_layout Itemize
5718 name (string): Name of button.
5721 \begin_layout Itemize
5722 symbol (string): Symbol of button.
5723 Only present for type
5724 \begin_inset Quotes eld
5728 \begin_inset Quotes erd
5734 \begin_layout Itemize
5735 hidden (boolean): True if hidden button.
5740 \begin_layout Subsection
5741 input.veto_button: Veto a button press
5744 \begin_layout Itemize
5745 Syntax: none input.veto_button()
5748 \begin_layout Standard
5749 Signals that the button event should be vetoed.
5750 Only valid in on_button callback.
5753 \begin_layout Subsection
5754 input.geta: Get all buttons for controller (deprecated)
5757 \begin_layout Itemize
5758 Syntax: (number, number...) input.geta(number controller)
5761 \begin_layout Standard
5762 Get input state for entiere controller.
5763 Returns n return values.
5766 \begin_layout Itemize
5767 1st return value: Bitmask: bit i is set if i:th index is nonzero
5770 \begin_layout Itemize
5771 2nd- return value: value of i:th index.
5774 \begin_layout Subsection
5775 input.seta: Set all buttons for controller (deprecated)
5778 \begin_layout Itemize
5779 Syntax: none input.seta(number controller, number bitmask, number args...)
5782 \begin_layout Standard
5783 Set state for entiere controller.
5784 args is up to N values for indices (overriding values in bitmask if specified).
5787 \begin_layout Subsection
5788 input.controllertype: Get controller type (deprecated)
5791 \begin_layout Itemize
5792 syntax: string input.controllertype(number controller)
5795 \begin_layout Standard
5796 Get the type of controller as string.
5799 \begin_layout Subsection
5800 input.reset: Execute (delayed) reset
5803 \begin_layout Itemize
5804 Syntax: none input.reset([number cycles])
5807 \begin_layout Standard
5809 If <cycles> is greater than zero, do delayed reset.
5810 0 (or no value) causes immediate reset.
5813 \begin_layout Itemize
5814 Note: Only available with subframe flag false.
5817 \begin_layout Subsection
5818 input.raw: Return raw input data
5821 \begin_layout Itemize
5822 Syntax: table input.raw()
5825 \begin_layout Standard
5826 Returns table of tables of all available keys and axes.
5827 The first table is indexed by key name (platform-dependent!), and the inner
5828 table has the following fields:
5831 \begin_layout Itemize
5832 value: Last reported value for control
5836 \begin_layout Itemize
5837 For keys: 1 for pressed, 0 for released.
5840 \begin_layout Itemize
5841 For axes: -32767...32767.
5844 \begin_layout Itemize
5845 For presure-sensitive buttons: 0...32767.
5848 \begin_layout Itemize
5849 For hats: Bitmask: 1=>Up, 2=>Right, 4=>Down, 8=>Left.
5852 \begin_layout Itemize
5853 For mouse: Coordinates relative to game area.
5857 \begin_layout Itemize
5858 ktype: Type of key (disabled, key, mouse, axis, hat, pressure).
5861 \begin_layout Subsection
5862 input.keyhook: Hook a key
5865 \begin_layout Itemize
5866 Syntax: none input.keyhook(string key, boolean state)
5869 \begin_layout Standard
5870 Requests that keyhook events to be sent for key <key> (<state>=true) or
5871 not sent (<state>=false).
5874 \begin_layout Subsection
5875 input.joyget: Get controls for controller
5878 \begin_layout Itemize
5879 Syntax: table input.joyget(number logical)
5882 \begin_layout Standard
5883 Returns table for current controls for specified logical controller <logical>.
5884 The names of fields vary by controller type.
5887 \begin_layout Itemize
5888 The buttons have the same name as those are referred to in other contexts
5892 \begin_layout Itemize
5893 The analog axes are usually
5894 \begin_inset Quotes eld
5898 \begin_inset Quotes erd
5902 \begin_inset Quotes eld
5906 \begin_inset Quotes erd
5912 \begin_layout Itemize
5913 Each field is numeric or boolean depending on axis/button.
5916 \begin_layout Subsection
5917 input.joyset: Set controls for controller
5920 \begin_layout Itemize
5921 Syntax: none input.joyset(number controller, table controls)
5924 \begin_layout Standard
5925 Set the the state of specified controller to values specified in specified
5929 \begin_layout Itemize
5930 Each field can be boolean or number.
5933 \begin_layout Itemize
5934 Also, buttons allow strings, which cause value to be inverted.
5937 \begin_layout Subsection
5938 input.lcid_to_pcid: Look up logical controller (deprecated)
5941 \begin_layout Itemize
5942 Syntax: (number, number, number) input.lcid_to_pcid(number lcid)
5945 \begin_layout Standard
5946 Returns the legacy pcid for controller (or false if there isn't one), followed
5948 Returns nothing if controller does not exist.
5951 \begin_layout Standard
5952 \begin_inset Newpage pagebreak
5958 \begin_layout Section
5962 \begin_layout Standard
5963 Various keybinding-related functions
5966 \begin_layout Subsection
5967 keyboard.bind: Bind a key
5970 \begin_layout Itemize
5971 Syntax: none keyboard.bind(string mod, string mask, string key, string cmd)
5974 \begin_layout Standard
5975 Bind specified key with specified modifers to specified command.
5978 \begin_layout Subsection
5979 keyboard.unbind: Unbind a key
5982 \begin_layout Itemize
5983 Syntax: none keyboard.unbind(string mod, string mask, string key)
5986 \begin_layout Standard
5987 Unbind specified key with specified modifers.
5990 \begin_layout Subsection
5991 keyboard.alias: Set alias expansion
5994 \begin_layout Itemize
5995 Syntax: none keyboard.alias(string alias, string expansion)
5998 \begin_layout Standard
5999 Set expansion of given command.
6002 \begin_layout Standard
6003 \begin_inset Newpage pagebreak
6009 \begin_layout Section
6013 \begin_layout Standard
6017 \begin_layout Subsection
6018 subtitle.byindex: Look up start and length of subtitle by index
6021 \begin_layout Itemize
6022 Syntax: (number, number) subtitle.byindex(number i)
6025 \begin_layout Standard
6026 Read the frame and length of ith subtitle.
6027 Returns nothing if not present.
6030 \begin_layout Subsection
6031 subtitle.set: Write a subtitle
6034 \begin_layout Itemize
6035 Syntax: none subtitle.set(number f, number l, string txt)
6038 \begin_layout Standard
6039 Set the text of subtitle.
6042 \begin_layout Subsection
6043 subtitle.get: Read a subtitle
6046 \begin_layout Itemize
6047 Syntax: string subtitle.get(number f, number l)
6050 \begin_layout Standard
6051 Get the text of subtitle.
6054 \begin_layout Subsection
6055 subtitle.delete: Delete a subtitle
6058 \begin_layout Itemize
6059 Syntax: none subtitle.delete(number f, number l)
6062 \begin_layout Standard
6063 Delete specified subtitle.
6066 \begin_layout Standard
6067 \begin_inset Newpage pagebreak
6073 \begin_layout Section
6077 \begin_layout Standard
6078 Host memory handling (extra memory saved to savestates).
6079 Host memory starts empty.
6082 \begin_layout Itemize
6083 Reads out of range return false.
6086 \begin_layout Itemize
6087 Writes out of range extend the memory.
6090 \begin_layout Subsection
6091 hostmemory.read: Read byte from host memory
6094 \begin_layout Itemize
6095 Syntax: number hostmemory.read(number address)
6098 \begin_layout Standard
6099 Reads byte from hostmemory slot address <address>.
6102 \begin_layout Subsection
6103 hostmemory.write: Write byte to host memory
6106 \begin_layout Itemize
6107 Syntax: none hostmemory.write(number address, number value)
6110 \begin_layout Standard
6111 Writes hostmemory slot with value <value> 0-255.
6114 \begin_layout Subsection
6115 hostmemory.read{,s}{byte,{,h,d,q}word}: Read from host memory
6118 \begin_layout Itemize
6119 Syntax: number hostmemory.readbyte(number address)
6122 \begin_layout Itemize
6123 Syntax: number hostmemory.readsbyte(number address)
6126 \begin_layout Itemize
6127 Syntax: number hostmemory.readword(number address)
6130 \begin_layout Itemize
6131 Syntax: number hostmemory.readsword(number address)
6134 \begin_layout Itemize
6135 Syntax: number hostmemory.readhword(number address)
6138 \begin_layout Itemize
6139 Syntax: number hostmemory.readshword(number address)
6142 \begin_layout Itemize
6143 Syntax: number hostmemory.readdword(number address)
6146 \begin_layout Itemize
6147 Syntax: number hostmemory.readsdword(number address)
6150 \begin_layout Itemize
6151 Syntax: number hostmemory.readqword(number address)
6154 \begin_layout Itemize
6155 Syntax: number hostmemory.readsqword(number address)
6158 \begin_layout Standard
6159 Read elements (big-endian) from given address <address>.
6162 \begin_layout Itemize
6166 \begin_layout Itemize
6170 \begin_layout Itemize
6174 \begin_layout Itemize
6178 \begin_layout Itemize
6179 qword is 8 elements.
6182 \begin_layout Itemize
6183 The 's' variants do signed read.
6186 \begin_layout Subsection
6187 hostmemory.read{float,double}: Read from host memory
6190 \begin_layout Itemize
6191 syntax: number hostmemory.readfloat(number address)
6194 \begin_layout Itemize
6195 Syntax: number hostmemory.readdouble(number address)
6198 \begin_layout Standard
6199 Read elements (big-endian) floating-pont from given address <address>.
6202 \begin_layout Subsection
6203 hostmemory.write{,s}{byte,{,h,d,q}word}: Write to host memory
6206 \begin_layout Itemize
6207 Syntax: number hostmemory.writebyte(number address, number value)
6210 \begin_layout Itemize
6211 Syntax: number hostmemory.writesbyte(number address, number value)
6214 \begin_layout Itemize
6215 Syntax: number hostmemory.writeword(number address, number value)
6218 \begin_layout Itemize
6219 Syntax: number hostmemory.writesword(number address, number value)
6222 \begin_layout Itemize
6223 Syntax: number hostmemory.writehword(number address, number value)
6226 \begin_layout Itemize
6227 Syntax: number hostmemory.writeshword(number address, number value)
6230 \begin_layout Itemize
6231 Syntax: number hostmemory.writedword(number address, number value)
6234 \begin_layout Itemize
6235 Syntax: number hostmemory.writesdword(number address, number value)
6238 \begin_layout Itemize
6239 Syntax: number hostmemory.writeqword(number address, number value)
6242 \begin_layout Itemize
6243 Syntax: number hostmemory.writesqword(number address, number value)
6246 \begin_layout Standard
6247 Write value <value> to elements (little-endian) starting from given address
6251 \begin_layout Itemize
6255 \begin_layout Itemize
6259 \begin_layout Itemize
6263 \begin_layout Itemize
6267 \begin_layout Itemize
6268 qword is 8 elements.
6271 \begin_layout Itemize
6272 The 's' variants do signed write.
6275 \begin_layout Subsection
6276 hostmemory.write{float,double}: Write to host memory
6279 \begin_layout Itemize
6280 syntax: none hostmemory.readfloat(number address, number value)
6283 \begin_layout Itemize
6284 Syntax: none hostmemory.readdouble(number address, number value)
6287 \begin_layout Standard
6288 Write elements (big-endian) floating-pont to given address <address>, storing
6292 \begin_layout Standard
6293 \begin_inset Newpage pagebreak
6299 \begin_layout Section
6303 \begin_layout Standard
6307 \begin_layout Subsection
6308 movie.currentframe: Get current frame number
6311 \begin_layout Itemize
6312 Syntax: number movie.currentframe()
6315 \begin_layout Standard
6316 Return number of current frame.
6319 \begin_layout Subsection
6320 movie.framecount: Get move frame count
6323 \begin_layout Itemize
6324 Syntax: number movie.framecount()
6327 \begin_layout Standard
6328 Return number of frames in movie.
6331 \begin_layout Subsection
6332 movie.lagcount: Get current lag count
6335 \begin_layout Itemize
6336 Syntax: number movie.lagcount()
6339 \begin_layout Standard
6340 Return number of lag frames recorded so far.
6343 \begin_layout Subsection
6344 movie.readonly: Is in playback mode?
6347 \begin_layout Itemize
6348 Syntax: boolean movie.readonly()
6351 \begin_layout Standard
6352 Return true if in playback mode, false if in recording.
6355 \begin_layout Subsection
6356 movie.rerecords: Movie rerecord count
6359 \begin_layout Itemize
6360 Syntax: number movie.rerecords()
6363 \begin_layout Standard
6364 Returns the current value of rerecord count.
6367 \begin_layout Subsection
6368 movie.set_readwrite: Set recording mode.
6371 \begin_layout Itemize
6372 Syntax: none movie.set_readwrite()
6375 \begin_layout Standard
6376 Set recording mode (does not cause on_readwrite callback).
6379 \begin_layout Subsection
6380 movie.frame_subframes: Count subframes in frame
6383 \begin_layout Itemize
6384 Syntax: number movie.frame_subframes(number frame)
6387 \begin_layout Standard
6388 Count number of subframes in specified frame <frame> (frame numbers are
6389 1-based) and return that.
6392 \begin_layout Subsection
6393 movie.read_subframes: Read subframe data (deprecated)
6396 \begin_layout Itemize
6397 Syntax: table movie.read_subframes(number frame, number subframe)
6400 \begin_layout Standard
6401 Read specifed subframe in specified frame and return data as array.
6404 \begin_layout Subsection
6405 movie.read_rtc: Read current RTC time
6408 \begin_layout Itemize
6409 Syntax: (number, number) movie.read_rtc()
6412 \begin_layout Standard
6413 Returns the current value of the RTC as a pair (second, subsecond).
6416 \begin_layout Subsection
6417 movie.unsafe_rewind: Fast movie rewind to saved state
6420 \begin_layout Itemize
6421 Syntax: none movie.unsafe_rewind([UNSAFEREWIND state])
6424 \begin_layout Standard
6425 Start setting point for unsafe rewind or jump to point of unsafe rewind.
6428 \begin_layout Itemize
6429 If called without argument, causes emulator to start process of setting
6430 unsafe rewind point.
6431 When this has finished, callback on_set_rewind occurs, passing the rewind
6432 state to lua script.
6435 \begin_layout Itemize
6436 If called with argument, causes emulator rewind to passed rewind point as
6438 recording mode is implicitly activated.
6441 \begin_layout Standard
6442 The following warnings apply to unsafe rewinding:
6445 \begin_layout Itemize
6446 There are no safety checks against misuse (that's what
6447 \begin_inset Quotes eld
6451 \begin_inset Quotes erd
6457 \begin_layout Itemize
6458 Only call rewind from timeline rewind point was set from.
6461 \begin_layout Itemize
6462 Only call rewind from after the rewind point was set.
6465 \begin_layout Subsection
6466 movie.to_rewind: Load savestate as rewind point
6469 \begin_layout Itemize
6470 Syntax: UNSAFEREWIND movie.to_rewind(string filename)
6473 \begin_layout Standard
6474 Load specified savestate file <filename> as rewind point and return UNSAFEREWIND
6475 corresponding to it.
6478 \begin_layout Itemize
6479 Note: This operation does not take emulated time.
6482 \begin_layout Subsection
6483 movie.copy_movie/INPUTMOVIE::copy_movie: Copy movie to movie object
6486 \begin_layout Itemize
6487 Syntax: INPUTMOVIE movie.copy_movie([INPUTMOVIE/string movie])
6490 \begin_layout Itemize
6491 Syntax: INPUTMOVIE INPUTMOVIE::copy_movie()
6494 \begin_layout Standard
6495 Copies specified movie or branch <movie>/current object (if none or nil,
6496 the active movie) as new movie object.
6499 \begin_layout Subsection
6500 movie.get_frame/INPUTMOVIE::get_frame: Read specified frame in movie.
6503 \begin_layout Itemize
6504 Syntax: INPUTFRAME movie.get_frame([INPUTMOVIE/string movie,] number frame)
6507 \begin_layout Itemize
6508 Syntax: INPUTFRAME INPUTMOVIE::get_frame(number frame);
6511 \begin_layout Standard
6512 Get INPUTFRAME object corresponding to specified frame in specified movie
6516 \begin_layout Subsection
6517 movie.set_frame/INPUTMOVIE::set_frame: Write speicifed frame in movie.
6520 \begin_layout Itemize
6521 Syntax: none movie.set_frame([INPUTMOVIE/string movie,] number frame, INPUTFRAME
6525 \begin_layout Itemize
6526 Syntax: none INPUTMOVIE::set_frame(number frame, INPUTFRAME data)
6529 \begin_layout Standard
6530 Set data in specified frame.
6533 \begin_layout Itemize
6534 Note: Past can't be edited in active movie.
6537 \begin_layout Subsection
6538 movie.get_size/INPUTMOVIE::get_size: Get size of movie
6541 \begin_layout Itemize
6542 Syntax: integer movie.get_size([INPUTMOVIE/string movie])
6545 \begin_layout Itemize
6546 Syntax: integer INPUTMOVIE::get_size()
6549 \begin_layout Standard
6550 Return number of subframes in specified movie or branch.
6553 \begin_layout Subsection
6554 movie.count_frames/INPUTMOVIE::count_frames: Count frames in movie
6557 \begin_layout Itemize
6558 Syntax: number movie.count_frames([INPUTMOVIE/string movie])
6561 \begin_layout Itemize
6562 Syntax: number INPUTMOVIE::count_frames()
6565 \begin_layout Standard
6566 Return number of frames in movie.
6569 \begin_layout Subsection
6570 movie.find_frame/INPUTMOVIE::find_frame: Find subframe corresponding to frame
6573 \begin_layout Itemize
6574 Syntax: number movie.find_frame([INPUTMOVIE/string movie], number frame)
6577 \begin_layout Itemize
6578 Syntax: number INPUTMOVIE::find_frame(number frame)
6581 \begin_layout Standard
6582 Returns starting subframe of given frame (frame numbers are 1-based).
6583 Returns -1 if frame number is bad.
6586 \begin_layout Subsection
6587 movie.blank_frame/INPUTMOVIE::blank_frame: Return a blank frame
6590 \begin_layout Itemize
6591 Syntax: INPUTFRAME movie.blank_frame([INPUTMOVIE/string movie])
6594 \begin_layout Itemize
6595 Syntax: INPUTFRAME INPUTMOVIE::blank_frame()
6598 \begin_layout Standard
6599 Return blank INPUTFRAME with frame type from specified movie.
6602 \begin_layout Subsection
6603 movie.append_frames/INPUTMOVIE::append_frames: Append blank frames
6606 \begin_layout Itemize
6607 Syntax: none movie.append_frames([INPUTMOVIE/string movie,] number frames)
6610 \begin_layout Itemize
6611 Syntax: none INPUTMOVIE::append_frames(number frames)
6614 \begin_layout Standard
6615 Append specified number <frames> of frames.
6618 \begin_layout Subsection
6619 movie.append_frame/INPUTMOVIE::append_frame: Append a frame
6622 \begin_layout Itemize
6623 Syntax: none movie.append_frame([INPUTMOVIE/string movie,] INPUTFRAME frame)
6626 \begin_layout Itemize
6627 Syntax: none INPUTMOVIE::append_frame(INPUTFRAME frame)
6630 \begin_layout Standard
6631 Append specified frame <frame>.
6632 Past of current movie can't be edited.
6635 \begin_layout Subsection
6636 movie.truncate/INPUTMOVIE::truncate: Truncate a movie.
6639 \begin_layout Itemize
6640 Syntax: none movie.truncate([INPUTMOVIE/string movie,] number frames)
6643 \begin_layout Itemize
6644 Syntax: none INPUTMOVIE::truncate(number frames)
6647 \begin_layout Standard
6648 Truncate the specified movie to specified number of frames.
6651 \begin_layout Subsection
6652 movie.edit/INPUTMOVIE::edit: Edit a movie
6655 \begin_layout Itemize
6656 Syntax: none movie.edit([INPUTMOVIE movie,] number frame, number port, number
6657 controller, number control, number/bool value)
6660 \begin_layout Itemize
6661 Syntax: none movie.edit(string branch, number frame, number port, number
6662 controller, number control, number/bool value)
6665 \begin_layout Itemize
6666 Syntax: none INPUTMOVIE::edit(number frame, number port, number controller,
6667 number control, number/bool value)
6670 \begin_layout Standard
6671 Change specified control in specified frame in specified movie.
6672 Past can't be edited in active movie.
6675 \begin_layout Subsection
6676 movie.copy_frames2: Copy frames between movies
6679 \begin_layout Itemize
6680 Syntax: none movie.copy_frames2([INPUTMOVIE/string dstmov,] number dst, [INPUTMOV
6681 IE/string srcmov,] number src, number count)
6684 \begin_layout Standard
6685 Copy specified number of frames between two movies.
6686 The copy proceeeds in forward direction.
6689 \begin_layout Subsection
6690 movie.copy_frames/INPUTMOVIE::copy_frames: Copy frames in movie
6693 \begin_layout Itemize
6694 Syntax: none movie.copy_frames([INPUTMOVIE/string mov,] number dst, number
6695 src, number count, bool backwards)
6698 \begin_layout Itemize
6699 Syntax: none INPUTMOVIE::copy_frames(number dst, number src, number count,
6703 \begin_layout Standard
6704 Copy specified number of frames from one point in movie to another.
6705 If backwards is true, the copy will be done backwards.
6708 \begin_layout Subsection
6709 movie.serialize/INPUTMOVIE::serialize: Serialize movie
6712 \begin_layout Itemize
6713 Syntax: none movie.serialize([INPUTMOVIE movie/string,] string filename,
6717 \begin_layout Itemize
6718 Syntax: none INPUTMOIVE::serialize(string filename, bool binary)
6721 \begin_layout Standard
6722 Serialize given movie into file.
6723 If binary is true, binary format (more compact and much faster) is used.
6726 \begin_layout Subsection
6727 movie.unserialize: Unserialize movie
6730 \begin_layout Itemize
6731 Syntax: INPUTMOVIE movie.unserialize(INPUTFRAME template, string filename,
6735 \begin_layout Standard
6736 Unserialize movie from file.
6737 The given frame is used as template to decide the frame type.
6738 If binary is true, binary format is decoded (much faster).
6741 \begin_layout Subsection
6742 movie.current_first_subframe: Return first subframe in current frame
6745 \begin_layout Itemize
6746 Syntax: number movie.current_first_subframe()
6749 \begin_layout Standard
6750 Returns first subframe in current frame.
6753 \begin_layout Subsection
6754 movie.pollcounter: Return poll counter for speified control
6757 \begin_layout Itemize
6758 Syntax: number movie.pollcounter(number port, number controller, number control)
6761 \begin_layout Standard
6762 Returns number of times the specified control has been polled this frame.
6765 \begin_layout Subsection
6766 movie.current_branch: Return current branch
6769 \begin_layout Itemize
6770 Syntax: string movie.current_branch()
6773 \begin_layout Standard
6774 Returns the name of the current branch.
6777 \begin_layout Subsection
6778 movie.get_branches: Return names of all branches
6781 \begin_layout Itemize
6783 movie.get_branches()
6786 \begin_layout Standard
6787 Returns the name of all branches.
6790 \begin_layout Subsection
6791 movie.rom_loaded: Is ROM loaded?
6794 \begin_layout Itemize
6795 Syntax: boolean movie.rom_loaded()
6798 \begin_layout Standard
6799 Returns true if ROM is loaded, false otherwise.
6802 \begin_layout Subsection
6803 movie.get_rom_info: Get info about loaded ROM
6806 \begin_layout Itemize
6807 Syntax: Table movie.get_rom_info()
6810 \begin_layout Standard
6811 Returns a table of tables.
6812 The outer table is indexed by ROM slot index.
6813 The inner table has the following fields:
6816 \begin_layout Itemize
6817 filename: The name of file
6820 \begin_layout Itemize
6821 hint: File name hint
6824 \begin_layout Itemize
6825 sha256: SHA-256 hash of ROM.
6828 \begin_layout Itemize
6829 xml_filename: The name of file for markup
6832 \begin_layout Itemize
6833 xml_hint: File name hint for markup
6836 \begin_layout Itemize
6837 xml_sha256: SHA-256 hash of ROM markup.
6840 \begin_layout Standard
6841 If there is no markup, the xml_* fields are absent.
6844 \begin_layout Subsection
6845 movie.get_game_info: Get info about loaded game
6848 \begin_layout Itemize
6849 Syntax: Table movie.get_game_info()
6852 \begin_layout Standard
6853 Returns a table with following fields:
6856 \begin_layout Itemize
6857 core: The name of the core
6860 \begin_layout Itemize
6861 core_short: Short name of the core
6864 \begin_layout Itemize
6865 type: The name of the system type
6868 \begin_layout Itemize
6869 type_long: The long name of the system type
6872 \begin_layout Itemize
6873 region: The name of region
6876 \begin_layout Itemize
6877 region_long: The long name of region
6880 \begin_layout Itemize
6881 gametype: The gametype of movie.
6884 \begin_layout Itemize
6885 fps: Nominal fps as floating-point value
6888 \begin_layout Itemize
6889 fps_n: Exact nominal fps numerator
6892 \begin_layout Itemize
6893 fps_d: Exact nominal fps denominator.
6896 \begin_layout Subsection
6897 INPUTFRAME::get_button: Get button
6900 \begin_layout Itemize
6901 Syntax: boolean INPUTFRAME::get_button(number port, number controller, number
6905 \begin_layout Standard
6906 Returns state of given button as boolean.
6909 \begin_layout Subsection
6910 INPUTFRAME::get_axis: Get axis
6913 \begin_layout Itemize
6914 Syntax: number INPUTFRAME::get_axis(number port, number controller, number
6918 \begin_layout Standard
6919 Returns state of given axis as number.
6922 \begin_layout Subsection
6923 INPUTFRAME::set_button/INPUTFRAME::set_axis: Set button or axis
6926 \begin_layout Itemize
6927 Syntax: none INPUTFRAME::set_button(number port, number controller, number
6928 control, number/bool value)
6931 \begin_layout Itemize
6932 Syntax: none INPUTFRAME::set_axis(number port, number controller, number
6936 \begin_layout Standard
6937 Set the given button/axis to given value.
6940 \begin_layout Subsection
6941 INPUTFRAME::serialize: Serialize a frame
6944 \begin_layout Itemize
6945 Syntax: string INPUTFRAME::serialize()
6948 \begin_layout Standard
6949 Return string representation of frame.
6952 \begin_layout Subsection
6953 INPUTFRAME::unserialize: Unserialize a frame
6956 \begin_layout Itemize
6957 Syntax: none INPUTFRAME::unserialize(string data)
6960 \begin_layout Standard
6961 Set current frame from given data.
6964 \begin_layout Subsection
6965 INPUTFRAME::get_stride: Get movie stride
6968 \begin_layout Itemize
6969 Syntax: number INPUTFRAME::get_stride()
6972 \begin_layout Standard
6973 Return number of bytes needed to store the input frame.
6974 Mainly useful for some debugging.
6977 \begin_layout Standard
6978 \begin_inset Newpage pagebreak
6984 \begin_layout Section
6988 \begin_layout Standard
6989 Routines for settings manipulation
6992 \begin_layout Subsection
6993 settings.get: Get value of setting
6996 \begin_layout Itemize
6997 Syntax: string settings.get(string name)
7000 \begin_layout Standard
7001 Get value of setting <name>.
7002 If setting value can't be obtained, returns (nil, error message).
7005 \begin_layout Subsection
7006 settings.set: Set value of setting
7009 \begin_layout Itemize
7010 Syntax: none settings.set(string name, string value)
7013 \begin_layout Standard
7014 Set value <value> of setting <name>.
7015 If setting can't be set, returns (nil, error message).
7018 \begin_layout Subsection
7019 settings.get_all: Get values of all settings
7022 \begin_layout Itemize
7023 Syntax: table settings.get_all()
7026 \begin_layout Standard
7027 Return a table with all setting names as keys and all current values as
7031 \begin_layout Subsection
7032 settings.get_speed: Get current speed
7035 \begin_layout Itemize
7036 Syntax: number/string settings.get_speed()
7039 \begin_layout Standard
7040 Return the current speed multiplier (1 is normal), or
7041 \begin_inset Quotes eld
7045 \begin_inset Quotes erd
7048 if speed is set to turbo (this does not react to turbo toggle).
7051 \begin_layout Subsection
7052 settings.set_speed: Set current speed
7055 \begin_layout Itemize
7056 Syntax: settings.get_speed(number spd)
7059 \begin_layout Itemize
7060 Syntax: settings.get_speed(string special)
7063 \begin_layout Standard
7064 Set the current speed multiplier (1 is normal).
7065 The speed may be positive multiplier or
7066 \begin_inset Quotes eld
7070 \begin_inset Quotes erd
7076 \begin_layout Standard
7077 \begin_inset Newpage pagebreak
7083 \begin_layout Section
7087 \begin_layout Standard
7088 Contains various functions for managing memory
7091 \begin_layout Subsection
7092 memory.vma_count: Count number of memory areas.
7095 \begin_layout Itemize
7096 Syntax: number memory.vma_count()
7099 \begin_layout Standard
7100 Returns the number of memory areas
7103 \begin_layout Subsection
7104 memory.read_vma: Lookup memory area info by index
7107 \begin_layout Itemize
7108 Syntax: table memory.read_vma(number index)
7111 \begin_layout Standard
7112 Reads the specified memory area (indices start from zero).
7113 Trying to read invalid memory area gives nil.
7114 The return value is table with the following fields:
7117 \begin_layout Itemize
7118 region_name (string): The readable name of the memory area
7121 \begin_layout Itemize
7122 baseaddr (number): Base address of the memory area
7125 \begin_layout Itemize
7126 lastaddr (number): Last address in the memory area.
7129 \begin_layout Itemize
7130 size (number): The size of memory area in bytes.
7133 \begin_layout Itemize
7134 readonly (boolean): True of the memory area corresponds to ROM.
7137 \begin_layout Itemize
7138 iospace (boolean): True if the memory area is I/O space.
7141 \begin_layout Itemize
7142 native_endian (boolean): True if the memory area has native endian as opposed
7146 \begin_layout Subsection
7147 memory.find_vma: Find memory area info by address
7150 \begin_layout Itemize
7151 Syntax: table memory.find_vma(number address)
7154 \begin_layout Standard
7155 Finds the memory area containing specified address.
7156 Returns table in the same format as read_vma or nil if not found.
7159 \begin_layout Subsection
7160 memory.read{,s}{byte,{,h,d,q}word}: Read memory
7163 \begin_layout Itemize
7164 Syntax: none memory.readbyte({string marea, number address|ADDRESS addrobj})
7167 \begin_layout Itemize
7168 Syntax: none memory.readword({string marea, number address|ADDRESS addrobj})
7171 \begin_layout Itemize
7172 Syntax: none memory.readhword({string marea, number address|ADDRESS addrobj})
7175 \begin_layout Itemize
7176 Syntax: none memory.readdword({string marea, number address|ADDRESS addrobj})
7179 \begin_layout Itemize
7180 Syntax: none memory.readqword({string marea, number address|ADDRESS addrobj})
7183 \begin_layout Itemize
7184 Syntax: none memory.readsbyte({string marea, number address|ADDRESS addrobj})
7187 \begin_layout Itemize
7188 Syntax: none memory.readsword({string marea, number address|ADDRESS addrobj})
7191 \begin_layout Itemize
7192 Syntax: none memory.readshword({string marea, number address|ADDRESS addrobj})
7195 \begin_layout Itemize
7196 Syntax: none memory.readsdword({string marea, number address|ADDRESS addrobj})
7199 \begin_layout Itemize
7200 Syntax: none memory.readsqword({string marea, number address|ADDRESS addrobj})
7203 \begin_layout Standard
7204 Reads the specified address <address> (if 's' variant is used, do undergo
7208 \begin_layout Subsection
7209 memory.{,s}read_sg: Scatter/Gather read memory
7212 \begin_layout Itemize
7213 Syntax: none memory.read_sg(string/boolean/number...)
7216 \begin_layout Itemize
7217 Syntax: none memory.sread_sg(string/boolean/number...)
7220 \begin_layout Standard
7221 Perform (2s complement signed if using memory.sread_sg) scatter/gather read
7223 Each argument can be string, boolean or number:
7226 \begin_layout Itemize
7227 String: Set memory area addresses are relative to (e.g.
7231 \begin_layout Itemize
7232 boolean: If true, increment relative address by 1, if false, decrement by
7234 The new address is read as next higher byte.
7237 \begin_layout Itemize
7238 integer: Set the relative address to specified value and read the address
7239 as next higher byte.
7242 \begin_layout Subsection
7243 memory.write_sg: Scatter/Gather write memory
7246 \begin_layout Itemize
7247 Syntax: none memory.write_sg(number value, string/boolean/number...)
7250 \begin_layout Standard
7251 Perform scatter/gather write of value <value> on memory.
7252 Each argument can be string, boolean or number:
7255 \begin_layout Itemize
7256 String: Set memory area addresses are relative to (e.g.
7260 \begin_layout Itemize
7261 boolean: If true, increment relative address by 1, if false, decrement by
7263 The new address is read as next higher byte.
7266 \begin_layout Itemize
7267 integer: Set the relative address to specified value and read the address
7268 as next higher byte.
7271 \begin_layout Subsection
7272 memory.read{float,double}: Read memory
7275 \begin_layout Itemize
7276 Syntax: none memory.readfloat({string marea, number address|ADDRESS addrobj})
7279 \begin_layout Itemize
7280 Syntax: none memory.readdouble({string marea, number address|ADDRESS addrobj})
7283 \begin_layout Standard
7284 Reads the specified address <address>
7287 \begin_layout Subsection
7288 memory.write{byte,{,h,d,q}word,float,double}: Write memory
7291 \begin_layout Itemize
7292 Syntax: none memory.writebyte({string marea, number address|ADDRESS addrobj},
7296 \begin_layout Itemize
7297 Syntax: none memory.writeword({string marea, number address|ADDRESS addrobj},
7301 \begin_layout Itemize
7302 Syntax: none memory.writehword({string marea, number address|ADDRESS addrobj},
7306 \begin_layout Itemize
7307 Syntax: none memory.writedword({string marea, number address|ADDRESS addrobj},
7311 \begin_layout Itemize
7312 Syntax: none memory.writeqword({string marea, number address|ADDRESS addrobj},
7316 \begin_layout Itemize
7317 Syntax: none memory.writefloat({string marea, number address|ADDRESS addrobj},
7321 \begin_layout Itemize
7322 Syntax: none memory.writedouble({string marea, number address|ADDRESS addrobj},
7326 \begin_layout Standard
7327 Writes the specified value <value> (negative integer values undergo 2's
7328 complement) to specified address <address>.
7331 \begin_layout Subsection
7332 memory.map{{,s}{byte,{,h,d,q}word},float,double}: Map an array
7335 \begin_layout Itemize
7336 Syntax: userdata memory.map<type>({string marea, number base|ADDRESS addrobj},
7340 \begin_layout Standard
7341 Returns a table mapping specified memory aperture for read/write.
7344 \begin_layout Itemize
7345 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
7346 qword, sqword, float or double.
7349 \begin_layout Subsection
7350 memory.hash_region: Hash region of memory
7353 \begin_layout Itemize
7354 Syntax: string memory.hash_region({string marea, number base|ADDRESS addrobj},
7358 \begin_layout Standard
7359 Hash <size> bytes starting from address <base> (relative to <marea>) and
7363 \begin_layout Subsection
7364 memory.hash_region2: Hash region of memory
7367 \begin_layout Itemize
7368 Syntax: string memory.hash_region2({string marea, number base|ADDRESS addrobj},
7369 number size[, number rows, number stride])
7372 \begin_layout Standard
7373 Hash <rows> blocks of <size> bytes starting from address <base> (relative
7375 The blocks are offset by <stride> from one another and return the SHA-256.
7378 \begin_layout Subsection
7379 memory.hash_region_skein: Hash region of memory
7382 \begin_layout Itemize
7383 Syntax: string memory.hash_region_skein({string marea, number base|ADDRESS
7384 addrobj}, number size[, number rows, number stride])
7387 \begin_layout Standard
7388 Same as memory.hash_region2, but uses Skein-512-256 (v1.3; one of the SHA-3
7389 finalists) as hash function.
7392 \begin_layout Subsection
7393 memory.store: Store region of memory
7396 \begin_layout Itemize
7397 Syntax: none memory.store({string marea, number addr|ADDRESS addrobj}, number
7398 daddr[, number rows, number stride]
7401 \begin_layout Standard
7402 Copy memory starting from <addr> in memory area <marea> (each row being
7403 of size <size>, there being <rows> rows, and rows being separated by <stride>
7404 in memory) into savestate-saved memory area, starting from <daadr> (all
7405 rows are written back to back).
7408 \begin_layout Subsection
7409 memory.storecmp: Compare and store region of memory
7412 \begin_layout Itemize
7413 Syntax: bool memory.storecmp({string marea, number addr|ADDRESS addrobj},
7414 number daddr[, number rows, number stride]
7417 \begin_layout Standard
7418 Like memory.store, but returns true if target of copy already held the value
7419 that would be copied before the copy happened.
7420 Otherwise returns false (if target and source differ before copy).
7423 \begin_layout Subsection
7424 memory.hash_state: Hash system state
7427 \begin_layout Itemize
7428 Syntax: string memory.hash_state()
7431 \begin_layout Standard
7432 Hash the current system state.
7433 Mainly useful for debugging savestates.
7436 \begin_layout Subsection
7437 memory.readregion: Read region of memory
7440 \begin_layout Itemize
7441 Syntax: table memory.readregion({string marea, number base|ADDRESS addrobj},
7445 \begin_layout Standard
7446 Read a region of memory.
7449 \begin_layout Itemize
7450 Warning: If the region crosses memory area boundary, the results are undefined.
7453 \begin_layout Subsection
7454 memory.writeregion: Write region of memory
7457 \begin_layout Itemize
7458 Syntax: none memory.writeregion({string marea, number base|ADDRESS addrobj},
7459 number size, table data)
7462 \begin_layout Standard
7463 Write a region of memory.
7466 \begin_layout Itemize
7467 Warning: If the region crosses memory area boundary, the results are undefined.
7470 \begin_layout Subsection
7471 memory.action: Run core action
7474 \begin_layout Itemize
7475 memory.action(string action, [<params>])
7478 \begin_layout Standard
7480 The different models expect parameters as:
7483 \begin_layout Itemize
7487 \begin_layout Itemize
7491 \begin_layout Itemize
7495 \begin_layout Itemize
7499 \begin_layout Itemize
7503 \begin_layout Subsection
7504 memory.action_flags: Get core action flags
7507 \begin_layout Itemize
7508 memory.action_flags(string action)
7511 \begin_layout Standard
7512 Get value of action flags for core action <action>.
7515 \begin_layout Itemize
7519 \begin_layout Itemize
7520 Bit 1: Selected (not all actions can be selected)?
7523 \begin_layout Subsection
7524 memory.get_lag_flag: Get lag flag
7527 \begin_layout Itemize
7528 Syntax: boolean memory.get_lag_flag()
7531 \begin_layout Standard
7532 Get the value of core lag flag.
7533 True if this frame has been lag so far, false if poll has been detected.
7536 \begin_layout Subsection
7537 memory.set_lag_flag: Set lag flag
7540 \begin_layout Itemize
7541 Syntax: none memory.set_lag_flag(boolean flag)
7544 \begin_layout Standard
7545 Set the value of core lag flag.
7546 This flag automatically gets cleared if poll is detected, but can be forcibly
7547 set or cleared if game so requires.
7550 \begin_layout Itemize
7551 Should only be used in on_frame_emulated callback.
7554 \begin_layout Itemize
7555 Setting or clearing this affects the emulator lag counter.
7558 \begin_layout Subsection
7559 memory.{,un}register{read,write,exec}: (Un)Register read / write / execute
7563 \begin_layout Itemize
7564 Syntax: function memory.registerread({string marea, number addr|ADDRESS addrobj},
7568 \begin_layout Itemize
7569 Syntax: function memory.registerwrite({string marea, number addr|ADDRESS
7570 addrobj}, function fn);
7573 \begin_layout Itemize
7574 Syntax: function memory.registerexec({string marea, number addr|ADDRESS addrobj},
7578 \begin_layout Itemize
7579 Syntax: none memory.unregisterread({string marea, number addr|ADDRESS addrobj},
7583 \begin_layout Itemize
7584 Syntax: none memory.unregisterwrite({string marea, number addr|ADDRESS addrobj},
7588 \begin_layout Itemize
7589 Syntax: none memory.unregisterexec({string marea, number addr|ADDRESS addrobj},
7593 \begin_layout Standard
7594 Add or remove callback on memory read, write or execute (depending on the
7596 <addr> is relative to <marea>.
7597 <fn> is the callback.
7598 The register* functions return <fn> (which can then be passed to unregister*
7602 \begin_layout Itemize
7603 Not all cores support this, and it may be unsupported for some memory areas.
7606 \begin_layout Itemize
7607 The functions are passed two parameters: Address and value.
7610 \begin_layout Subsection
7611 memory.{,un}registertrace: Set/Clear trace hook
7614 \begin_layout Itemize
7615 Syntax: function memory.registertrace(number processor, function fn);
7618 \begin_layout Itemize
7619 Syntax: none memory.unregistertrace(number processor, function fn);
7622 \begin_layout Standard
7623 Add or remove trace callback.
7624 <processor> is system-dependent processor number (0 is usually main CPU).
7625 The function arguments work like in other (un)register* functions.
7628 \begin_layout Itemize
7629 The functions are passed two parameters: Trace CPU and Trace event string.
7632 \begin_layout Subsection
7633 memory.cheat: Set cheat
7636 \begin_layout Itemize
7637 Syntax: none memory.cheat({string marea, number addr|ADDRESS addrobj}, number
7641 \begin_layout Itemize
7642 Syntax: none memory.cheat({string marea, number addr|ADDRESS addrobj});
7645 \begin_layout Standard
7646 Set or clear cheat (value <value>) on address <addr> (relative to <marea>).
7647 If <value> is not speicified, clear a cheat.
7650 \begin_layout Itemize
7651 Not all cores support this, and it may be unsupported for some memory areas.
7654 \begin_layout Subsection
7655 memory.setxmask: Set global execute hook mask
7658 \begin_layout Itemize
7659 Syntax: none memory.setxmask(number mask)
7662 \begin_layout Standard
7663 Set the global execute hook mask to <mask>.
7664 The meaning of each bit is system-dependent, but bit 0 should be the main
7668 \begin_layout Subsection
7669 memory.getregister: Get register value
7672 \begin_layout Itemize
7673 Syntax: number/boolean memory.getregister(string register)
7676 \begin_layout Standard
7677 Get the value of named register.
7680 \begin_layout Subsection
7681 memory.getregisters: Get register values
7684 \begin_layout Itemize
7685 Syntax: table memory.getregisters()
7688 \begin_layout Standard
7689 Get the value of all known registers as table.
7692 \begin_layout Subsection
7693 memory.setregister: Set register value
7696 \begin_layout Itemize
7697 Syntax: none memory.setregister(string register, number/boolean value)
7700 \begin_layout Standard
7701 Set the value of named register.
7704 \begin_layout Subsection
7705 memory.mmap: Class MMAP_STRUCT
7708 \begin_layout Standard
7709 See class MMAP_STRUCT
7712 \begin_layout Standard
7713 \begin_inset Newpage pagebreak
7719 \begin_layout Section
7723 \begin_layout Standard
7724 Contains newer memory functions.
7727 \begin_layout Subsection
7728 memory2(): Get all memory area names.
7731 \begin_layout Itemize
7732 Syntax: table memory2()
7735 \begin_layout Standard
7736 Returns array of all valid memory area names.
7739 \begin_layout Subsection
7740 memory2.<marea>:info: Get memory area info
7743 \begin_layout Itemize
7744 Syntax: table memory2.<marea>:info()
7747 \begin_layout Standard
7748 Return table describing given memory area.
7749 Includes fields address, size, last, readonly, special and endian.
7752 \begin_layout Subsection
7753 memory2.<marea>:<op>: Read/Write memory
7756 \begin_layout Itemize
7757 Syntax: none memory2.<marea>:<op>(number offset, number value)
7760 \begin_layout Itemize
7761 Syntax: number memory2.<marea>:<op>(number offset)
7764 \begin_layout Standard
7765 Read/Write value from/to given memory area <marea> at given offset <offset>
7767 The value written is <value>.
7768 <Op> is of form: [i][s]<type>, where:
7771 \begin_layout Itemize
7772 <type> is one of 'byte', 'word', 'hword', 'dword', 'qword', 'float', 'double'.
7775 \begin_layout Itemize
7776 'i' signifies that the value is treated as opposite-to-normal endianess,
7779 \begin_layout Itemize
7780 's' signifies that value is treated as signed (not available for floating-point).
7783 \begin_layout Subsection
7784 memory2.<marea>:read: Scatter-gather value read
7787 \begin_layout Itemize
7788 Syntax: number memory2.<marea>:read(number addr...)
7791 \begin_layout Standard
7792 Read value from given memory area <marea> at byte offsets <addr>..., given
7793 in order of increasing significance.
7794 Value of true and false are special.
7795 True increments address by 1, and false decrements address by 1.
7798 \begin_layout Subsection
7799 memory2.<marea>:sread: Signed scatter-gather value read
7802 \begin_layout Itemize
7803 Syntax: number memory2.<marea>:sread(number addr...)
7806 \begin_layout Standard
7807 Like memory2.<marea>:read, but reads signed values.
7810 \begin_layout Subsection
7811 memory2.<marea>:write: Scatter-gather value write
7814 \begin_layout Itemize
7815 Syntax: number memory2.<marea>:write(number val, number addr...)
7818 \begin_layout Standard
7819 Write value <val> to given memory area <marea> at byte offsets <addr>..., given
7820 in order of increasing significance.
7821 Value of true and false are special.
7822 True increments address by 1, and false decrements address by 1.
7825 \begin_layout Subsection
7826 memory2.<marea>:cheat: Set/Clear cheat
7829 \begin_layout Itemize
7830 Syntax: none memory2.<marea>:cheat(number addr, [number value])
7833 \begin_layout Standard
7834 Set/Clear cheat at offset <addr> of memory area <marea>.
7835 If <value> is given, cheat with specified value is set.
7836 Otherwise cheat on address is removed.
7839 \begin_layout Subsection
7840 memory2.<marea>:sha256: SHA-256
7843 \begin_layout Itemize
7844 Syntax: string memory2.<marea>:sha256(number addr, number size[, number rows,
7848 \begin_layout Standard
7849 Compute SHA-256 of <rows> (default 1) chunks of <size> bytes each, starting
7850 from offset <addr> of area <marea>.
7851 The chunks are separated by <stride>.
7854 \begin_layout Subsection
7855 memory2.<marea>:skein: Skein-512-256
7858 \begin_layout Itemize
7859 Syntax: string memory2.<marea>:skein(number addr, number size[, number rows,
7863 \begin_layout Standard
7864 Same as memory2.<marea>:sha256, except with Skein-512-256 as hash function.
7867 \begin_layout Subsection
7868 memory2.<marea>:store{,cmp}: Copy region to Lua memory with compare
7871 \begin_layout Itemize
7872 Syntax: none memory2.<marea>:store(number addr, number daddr, number size[,
7873 number rows, number stride])
7876 \begin_layout Itemize
7877 Syntax: boolean memory2.<marea>:storecmp(number addr, number daddr, number
7878 size[, number rows, number stride])
7881 \begin_layout Standard
7882 Copy <rows> (default 1) chunks of <size> bytes each, starting from offset
7883 <addr> of area <marea>.
7884 The chunks are separated by <stride>.
7885 The target is Lua host memory, starting from offset <daddr>.
7888 \begin_layout Standard
7889 Additionally, the storecmp method returns false if target was modified (otherwis
7893 \begin_layout Subsection
7894 memory2.<marea>:readregion: Read region
7897 \begin_layout Itemize
7898 Syntax table memory2.<marea>:readregion(number addr, number size)
7901 \begin_layout Standard
7902 Read <size> bytes starting from <addr> in <marea> and return as array.
7905 \begin_layout Subsection
7906 memory2.<marea>:writeregion: Write region
7909 \begin_layout Itemize
7910 Syntax none memory2.<marea>:writeregion(number addr, table data)
7913 \begin_layout Standard
7914 Write array <data> to bytes starting from <addr> in <marea>.
7917 \begin_layout Subsection
7918 memory2.<marea>:register{read,write,exec}: Register hook
7921 \begin_layout Itemize
7922 Syntax: function memory2.<marea>:registerread(number addr, function fn);
7925 \begin_layout Itemize
7926 Syntax: function memory2.<marea>:registerwrite(number addr, function fn);
7929 \begin_layout Itemize
7930 Syntax: function memory2.<marea>:registerexec(number addr, function fn);
7933 \begin_layout Standard
7934 Register debug callback <fn> of specified type at offset <addr> of memory
7939 \begin_layout Subsection
7940 memory2.<marea>:unregister{read,write,exec}: Unregister hook
7943 \begin_layout Itemize
7944 Syntax: none memory2.<marea>:unregisterread(number addr, function fn);
7947 \begin_layout Itemize
7948 Syntax: none memory2.<marea>:unregisterwrite(number addr, function fn);
7951 \begin_layout Itemize
7952 Syntax: none memory2.<marea>:unregisterexec(number addr, function fn);
7955 \begin_layout Standard
7956 Unregister debug callback <fn> of specified type at offset <addr> of memory
7960 \begin_layout Standard
7961 \begin_inset Newpage pagebreak
7967 \begin_layout Section
7971 \begin_layout Standard
7972 Contains random number generation methods.
7973 These functions do not return reproducable results.
7976 \begin_layout Subsection
7977 random.boolean: Random boolean
7980 \begin_layout Itemize
7981 Syntax: boolean random.boolean()
7984 \begin_layout Standard
7985 Returns true or false at random (50-50 chance).
7988 \begin_layout Subsection
7989 random.integer: Random integer
7992 \begin_layout Itemize
7993 Syntax: number random.integer(number highplusone)
7996 \begin_layout Itemize
7997 Syntax: number random.integer(number low, number high)
8000 \begin_layout Standard
8001 With one argument, return random integer [0,<highplusone>) (upper end exclusive).
8002 With two arguments, return random integer [<low>,<high>] (both ends inclusive).
8005 \begin_layout Standard
8006 The returned numbers are from uniform distribution.
8009 \begin_layout Subsection
8010 random.float: Random float
8013 \begin_layout Itemize
8014 Syntax: number random.float()
8017 \begin_layout Standard
8018 Returns random decimal number [0,1).
8021 \begin_layout Subsection
8022 random.among: Random parameter
8025 \begin_layout Itemize
8026 Syntax: value random.among(value values...)
8029 \begin_layout Standard
8030 Returns random parameter value, picked at uniform.
8031 Multiple equivalent values are returned with higher chance.
8034 \begin_layout Subsection
8035 random.amongtable: Random from table
8038 \begin_layout Itemize
8039 Syntax: value random.amongtable(table tab)
8042 \begin_layout Standard
8043 Returns random value from table <tab>.
8044 As in random.among, no equality testing is done.
8047 \begin_layout Standard
8048 \begin_inset Newpage pagebreak
8054 \begin_layout Section
8058 \begin_layout Subsection
8059 zip.enumerate: Enumerate members in zipfile
8062 \begin_layout Itemize
8063 Syntax: Table zip.enumerate(string filename[, boolean invert])
8066 \begin_layout Standard
8067 Returns table of files in zip archive <filename>.
8068 If <invert> is true, instead of returning array of names, returns table
8069 with keys being member names and values being true.
8072 \begin_layout Subsection
8073 zip.writer: Class ZIPWRITER
8076 \begin_layout Standard
8077 See class ZIPWRITER.
8080 \begin_layout Standard
8081 \begin_inset Newpage pagebreak
8087 \begin_layout Section
8091 \begin_layout Standard
8092 Various callback-related functions.
8095 \begin_layout Subsection
8096 \begin_inset CommandInset label
8098 name "sub:callback.register:-Register-a"
8102 callback.register: Register a callback
8105 \begin_layout Itemize
8106 Syntax: function callback.register(string cbname, function cbfun);
8109 \begin_layout Standard
8110 Instruct function <cbfun> to be added to list of callbacks to call on event
8111 <cbname> (See section
8112 \begin_inset CommandInset ref
8114 reference "sec:Callbacks"
8119 The callback name does not have the 'on_' prefix (e.g.
8121 \begin_inset Quotes eld
8125 \begin_inset Quotes erd
8132 \begin_layout Subsection
8133 \begin_inset CommandInset label
8135 name "sub:callback.unregister:-Unregister-"
8139 callback.unregister: Unregister a callback
8142 \begin_layout Itemize
8143 Syntax: function callback.unregister(string cbname, function cbfun);
8146 \begin_layout Standard
8147 Instruct function <cbfun> to be removed from list of callbacks to call on
8151 \begin_layout Subsection
8152 callback.<cbname>:register: Register callback
8155 \begin_layout Itemize
8156 Syntax: function callback.<cbname>:register(function cbfun)
8159 \begin_layout Standard
8160 Synonym for callback.register (section
8161 \begin_inset CommandInset ref
8163 reference "sub:callback.register:-Register-a"
8167 ), albeit with callback name specified differently.
8170 \begin_layout Subsection
8171 callback.<cbname>:unregister: Register callback
8174 \begin_layout Itemize
8175 Syntax: function callback.<cbname>:unregister(function cbfun)
8178 \begin_layout Standard
8179 Synonym for callback.unregister (section
8180 \begin_inset CommandInset ref
8182 reference "sub:callback.unregister:-Unregister-"
8186 ), albeit with callback name specified differently.
8189 \begin_layout Section
8193 \begin_layout Standard
8194 Various bsnes-specific functions.
8197 \begin_layout Subsection
8198 bsnes.dump_sprite: Dump a sprite
8201 \begin_layout Itemize
8202 Syntax: BITMAP bsnes.dump_sprite(string marea, number addr, number width,
8203 number height[, number stride])
8206 \begin_layout Standard
8207 Dumps given sprite (in native format) from memory.
8208 memory area is usually
8209 \begin_inset Quotes eld
8213 \begin_inset Quotes erd
8217 <Width> and <height> are given in 8x8 blocks.
8218 <Stride> overrides row stride (default 512).
8221 \begin_layout Subsection
8222 bsnes.dump_palette: Dump a palette
8225 \begin_layout Itemize
8226 Syntax: PALETTE bsnes.dump_palette(string marea, number addr, bool full256,
8230 \begin_layout Standard
8231 Dumps a palette from memory.
8232 memory area is usually
8233 \begin_inset Quotes eld
8237 \begin_inset Quotes erd
8241 If <full256> is true, 256 colors are dumped (otherwise 16).
8242 If <first_trans> is true, first color is forced transparent.
8245 \begin_layout Subsection
8246 bsnes.enablelayer: Set layer visibility
8249 \begin_layout Itemize
8250 Syntax: none bsnes.enablelayer(number layer, number priority, boolean enabled)
8253 \begin_layout Standard
8254 Enable or disable specified layer at specified priority.
8257 \begin_layout Subsection
8258 bsnes.redump_sprite: Redump a sprite
8261 \begin_layout Itemize
8262 Syntax: none bsnes.redump_sprite(BITMAP bitmap, string marea, number addr[,
8266 \begin_layout Standard
8267 Like bsnes.dump_sprite, but instead dumps to specified bitmap <bitmap>.
8268 The specified bitmap must have size multiple of 8x8.
8271 \begin_layout Subsection
8272 bsnes.redump_palette: Redump a palette
8275 \begin_layout Itemize
8276 Syntax: none bsnes.dump_palette(PALETTE pal, string marea, number addr, bool
8280 \begin_layout Standard
8281 Like bsnes.dump_palette, but instead dumps to specified palette <pal>.
8282 The specified palette must have either 16 or 256 colors.
8285 \begin_layout Section
8286 extensions to table string
8289 \begin_layout Subsection
8290 string.charU: string.char, UTF-8 version.
8293 \begin_layout Itemize
8294 Syntax: string string.charU(number n...)
8297 \begin_layout Standard
8298 Like Lua string.char(), but works in terms of Unicode codepoints.
8299 The returned string is UTF-8.
8302 \begin_layout Subsection
8303 string.byteU: string.byte, UTF-8 version.
8306 \begin_layout Itemize
8308 string.byteU(string str[, number i[, number j]])
8311 \begin_layout Standard
8312 Like string.byte(), but works in terms of Unicode codepoints.
8313 The input string <str> is assumed UTF-8.
8316 \begin_layout Subsection
8317 string.regex: Match string against regular expression
8320 \begin_layout Itemize
8321 Syntax: boolean/string...
8322 string.regex(string regexp, string against)
8325 \begin_layout Standard
8326 Match POSIX-extended regular expression <regexp> against string <against>.
8327 If no match, false is returned.
8328 Otherwise if string has no subcaptures, true is returned.
8329 Otherwise each subcapture is returned as a string (in order of starting
8333 \begin_layout Subsection
8334 string.hex: Transform integer into hex string
8337 \begin_layout Itemize
8338 Syntax: string string.hex(number n, [number digits])
8341 \begin_layout Standard
8342 Returns hexadecimal string representation of <n>, optionally padded with
8343 zeroes to <digits> digits (default is not to pad).
8346 \begin_layout Subsection
8347 string.lpad: Pad string with spaces from left
8350 \begin_layout Itemize
8351 Syntax: string string.lpad(string x, number n)
8354 \begin_layout Standard
8355 Pad string <x> to <n> bytes by inserting spaces at start and return the
8359 \begin_layout Subsection
8360 string.rpad: Pad string with spaces from right
8363 \begin_layout Itemize
8364 Syntax: string string.rpad(string x, number n)
8367 \begin_layout Standard
8368 Pad string <x> to <n> bytes by inserting spaces at end and return the result.
8371 \begin_layout Section
8375 \begin_layout Standard
8376 Contains copy of global variables from time of Lua initialization.
8380 \begin_layout Standard
8381 \begin_inset Newpage pagebreak
8387 \begin_layout Section
8388 \begin_inset CommandInset label
8390 name "sec:Callbacks"
8397 \begin_layout Standard
8398 Various callbacks to Lua that can occur.
8401 \begin_layout Subsection
8402 on_paint: Screen is being painted
8405 \begin_layout Itemize
8406 Callback: on_paint(bool not_synth)
8409 \begin_layout Standard
8410 Called when screen is being painted.
8411 Any gui.* calls requiring graphic context draw on the screen.
8414 \begin_layout Itemize
8415 not_synth is true if this hook is being called in response to received frame,
8419 \begin_layout Subsection
8420 on_video: Dumped video frame is being painted
8423 \begin_layout Itemize
8424 Callback: on_video()
8427 \begin_layout Standard
8428 Called when video dump frame is being painted.
8429 Any gui.* calls requiring graphic context draw on the video.
8432 \begin_layout Subsection
8433 on_frame_emulated: Frame emulation complete
8436 \begin_layout Itemize
8437 Callback: on_frame_emulated()
8440 \begin_layout Standard
8441 Called when emulating frame has completed and on_paint()/on_video() calls
8442 are about to be issued.
8445 \begin_layout Subsection
8446 on_frame: Frame emulation starting.
8449 \begin_layout Itemize
8450 Callback: on_frame()
8453 \begin_layout Standard
8454 Called on each starting whole frame.
8457 \begin_layout Subsection
8458 on_rewind: Movie rewound to beginning
8461 \begin_layout Itemize
8462 Callback: on_rewind()
8465 \begin_layout Standard
8466 Called when rewind movie to beginning has completed.
8469 \begin_layout Subsection
8470 on_pre_load: Load operation is about to start
8473 \begin_layout Itemize
8474 Callback: on_pre_load(string name)
8477 \begin_layout Standard
8478 Called just before savestate/movie load occurs (note: loads are always delayed,
8479 so this occurs even when load was initiated by lua).
8482 \begin_layout Subsection
8483 on_err_Load: Load failed
8486 \begin_layout Itemize
8487 Callback: on_err_load(string name)
8490 \begin_layout Standard
8491 Called if loadstate goes wrong.
8494 \begin_layout Subsection
8495 on_post_load: Load completed
8498 \begin_layout Itemize
8499 Callback: on_post_load(string name, boolean was_savestate)
8502 \begin_layout Standard
8503 Called on successful loadstate.
8504 was_savestate gives if this was a savestate or a movie.
8507 \begin_layout Subsection
8508 on_pre_save: Save operation is about to start
8511 \begin_layout Itemize
8512 Callback: on_pre_save(string name, boolean is_savestate)
8515 \begin_layout Standard
8516 Called just before savestate save occurs (note: movie saves are synchronous
8517 and won't trigger these callbacks if called from Lua).
8520 \begin_layout Subsection
8521 on_err_save: Save failed
8524 \begin_layout Itemize
8525 Callback: on_err_save(string name)
8528 \begin_layout Standard
8529 Called if savestate goes wrong.
8532 \begin_layout Subsection
8533 on_post_save: Save completed
8536 \begin_layout Itemize
8537 Callback: on_post_save(string name, boolean is_savestate)
8540 \begin_layout Standard
8541 Called on successful savaestate.
8542 is_savestate gives if this was a savestate or a movie.
8545 \begin_layout Subsection
8546 on_quit: Emulator is shutting down
8549 \begin_layout Itemize
8553 \begin_layout Standard
8554 Called when emulator is shutting down.
8557 \begin_layout Subsection
8558 on_input: Polling for input
8561 \begin_layout Standard
8562 Called when emulator is just sending input to bsnes core.
8563 Warning: This is called even in readonly mode, but the results are ignored.
8566 \begin_layout Subsection
8567 on_reset: System has been reset
8570 \begin_layout Itemize
8571 Callback: on_reset()
8574 \begin_layout Standard
8575 Called when system is reset.
8578 \begin_layout Subsection
8579 on_readwrite: Entered recording mode
8582 \begin_layout Itemize
8583 Callback: on_readwrite()
8586 \begin_layout Standard
8587 Called when moving into recording mode as result of
8588 \begin_inset Quotes eld
8592 \begin_inset Quotes erd
8595 command (note: moving to rwmode by Lua won't trigger this, as per recursive
8599 \begin_layout Subsection
8600 on_snoop/on_snoop2: Snoop core controller reads
8603 \begin_layout Itemize
8604 Callback: on_snoop(number port, number controller, number index, number
8608 \begin_layout Itemize
8609 Callback: on_snoop2(number port, number controller, number index, number
8613 \begin_layout Standard
8614 Called each time bsnes asks for input.
8615 The value is the final value to be sent to bsnes core (readonly mode, autohold
8616 and autofire have been taken into account).
8617 Might be useful when translating movies to format suitable for console
8619 Note: There is no way to modify the value to be sent.
8622 \begin_layout Itemize
8623 On_snoop2 is called instead of on_snoop if defined.
8624 Reserves port 0 for system, having first user port be port 1.
8627 \begin_layout Subsection
8628 on_keyhook: Hooked key/axis has been moved
8631 \begin_layout Itemize
8632 Callback: on_keyhook(string keyname, table state)
8635 \begin_layout Standard
8636 Sent when key that has keyhook events requested changes state.
8637 Keyname is name of the key (group) and state is the state (same kind as
8638 table values in input.raw).
8641 \begin_layout Subsection
8645 \begin_layout Itemize
8649 \begin_layout Standard
8650 Called when requested by set_idle_timeout(), the timeout has expired and
8651 emulator is waiting.
8654 \begin_layout Subsection
8655 on_timer: Timer event
8658 \begin_layout Itemize
8659 Callback: on_timer()
8662 \begin_layout Standard
8663 Called when requested by set_idle_timeout() and the timeout has expired
8664 (regardless if emulator is waiting).
8667 \begin_layout Subsection
8668 on_set_rewind: Rewind point has been set
8671 \begin_layout Itemize
8672 Callback: on_set_rewind(UNSAFEREWIND r)
8675 \begin_layout Standard
8676 Called when unsafe rewind object has been constructed.
8679 \begin_layout Subsection
8680 on_pre_rewind: Rewind is about to occur
8683 \begin_layout Itemize
8684 Callback: on_pre_rewind()
8687 \begin_layout Standard
8688 Called just before unsafe rewind is about to occur.
8691 \begin_layout Subsection
8692 on_post_rewind: Rewind has occured
8695 \begin_layout Itemize
8696 Callback: on_post_rewind()
8699 \begin_layout Standard
8700 Called just after unsafe rewind has occured.
8703 \begin_layout Subsection
8704 on_button: Button has been pressed
8707 \begin_layout Itemize
8708 Callback: on_button(number port, number controller, number index, string
8712 \begin_layout Standard
8713 Called on controller button press, with following parameters:
8716 \begin_layout Itemize
8717 port: Port number (0 is system)
8720 \begin_layout Itemize
8721 controller: Controller within port
8724 \begin_layout Itemize
8725 index: Index of button.
8728 \begin_layout Itemize
8729 type: Type of event, one of:
8733 \begin_layout Itemize
8734 \begin_inset Quotes eld
8738 \begin_inset Quotes erd
8741 : Button was pressed.
8744 \begin_layout Itemize
8745 \begin_inset Quotes eld
8749 \begin_inset Quotes erd
8752 : Button was released.
8755 \begin_layout Itemize
8756 \begin_inset Quotes eld
8760 \begin_inset Quotes erd
8766 \begin_layout Itemize
8767 \begin_inset Quotes eld
8771 \begin_inset Quotes erd
8774 : Released from hold.
8777 \begin_layout Itemize
8778 \begin_inset Quotes eld
8782 \begin_inset Quotes erd
8785 : Typing input on button.
8788 \begin_layout Itemize
8789 \begin_inset Quotes eld
8793 \begin_inset Quotes erd
8796 : Typing input undone.
8799 \begin_layout Itemize
8800 \begin_inset Quotes eld
8803 autofire <duty> <cycle>
8804 \begin_inset Quotes erd
8807 : Autofire with specifie duty and cycle.
8810 \begin_layout Itemize
8811 \begin_inset Quotes eld
8815 \begin_inset Quotes erd
8821 \begin_layout Itemize
8822 \begin_inset Quotes eld
8826 \begin_inset Quotes erd
8829 : Analog action on axis.
8833 \begin_layout Subsection
8834 on_movie_lost: Movie data is about to be lost
8837 \begin_layout Itemize
8838 Callback: on_movie_lost(STRING kind)
8841 \begin_layout Standard
8842 Called just before something would happen that could lose movie data.
8846 \begin_layout Itemize
8847 readwrite: Switching to recording mode.
8850 \begin_layout Itemize
8851 reload: ROM is being reloaded in recording mode.
8854 \begin_layout Itemize
8855 load: New movie is being loaded.
8858 \begin_layout Itemize
8859 unsaferewind: Unsafe rewind is happening.
8862 \begin_layout Subsection
8863 on_latch: Latch line is rising
8866 \begin_layout Itemize
8867 Callback: on_latch(<core-dependent-parameters>)
8870 \begin_layout Standard
8871 Called when latch line for controller is rising.
8872 Some cores may not support this.
8875 \begin_layout Section
8876 System-dependent behaviour
8879 \begin_layout Subsection
8883 \begin_layout Itemize
8884 Registers are: pbpc, pb, pc, r0, r1, r2, r3, r4, r5, a, x, y, z, s, d, db,
8885 p, e, irq, wai, mdr, vector, aa, rd, sp, dp, p_n, p_v, p_m, p_x, p_d, p_i,
8886 p_z, p_c, ppu_display_disabled, ppu_oam_priority, ppu_bg_tilesize[0], ppu_bg_ti
8887 lesize[1], ppu_bg_tilesize[2], ppu_bg_tilesize[3], ppu_bg3_priority, ppu_mosaic_
8888 enabled[0], ppu_mosaic_enabled[1], ppu_mosaic_enabled[2], ppu_mosaic_enabled[3],
8889 ppu_vram_incmode, ppu_mode7_vflip, ppu_mode7_hflip, ppu_window1_enabled[0],
8890 ppu_window1_enabled[1], ppu_window1_enabled[2], ppu_window1_enabled[3],
8891 ppu_window1_enabled[4], ppu_window1_enabled[5], ppu_window1_invert[0],
8892 ppu_window1_invert[1], ppu_window1_invert[2], ppu_window1_invert[3], ppu_window
8893 1_invert[4], ppu_window1_invert[5], ppu_window2_enabled[0], ppu_window2_enabled[
8894 1], ppu_window2_enabled[2], ppu_window2_enabled[3], ppu_window2_enabled[4],
8895 ppu_window2_enabled[5], ppu_window2_invert[0], ppu_window2_invert[1], ppu_windo
8896 w2_invert[2], ppu_window2_invert[3], ppu_window2_invert[4], ppu_window2_invert[5
8897 ], ppu_bg_enabled[0], ppu_bg_enabled[1], ppu_bg_enabled[2], ppu_bg_enabled[3],
8898 ppu_bg_enabled[4], ppu_bgsub_enabled[0], ppu_bgsub_enabled[1], ppu_bgsub_enable
8899 d[2], ppu_bgsub_enabled[3], ppu_bgsub_enabled[4], ppu_window_enabled[0],
8900 ppu_window_enabled[1], ppu_window_enabled[2], ppu_window_enabled[3], ppu_window
8901 _enabled[4], ppu_sub_window_enabled[0], ppu_sub_window_enabled[1], ppu_sub_windo
8902 w_enabled[2], ppu_sub_window_enabled[3], ppu_sub_window_enabled[4], ppu_addsub_m
8903 ode, ppu_direct_color, ppu_color_mode, ppu_color_halve, ppu_color_enabled[0],
8904 ppu_color_enabled[1], ppu_color_enabled[2], ppu_color_enabled[3], ppu_color_ena
8905 bled[4], ppu_color_enabled[5], ppu_mode7_extbg, ppu_pseudo_hires, ppu_overscan,
8906 ppu_oam_interlace, ppu_interlace, ppu_latch_hcounter, ppu_latch_vcounter,
8907 ppu_counters_latched, ppu_time_over, ppu_range_over, ppu_ppu1_mdr, ppu_ppu2_mdr
8908 , ppu_bg_y[0], ppu_bg_y[1], ppu_bg_y[2], ppu_bg_y[3], ppu_ioamaddr, ppu_icgramad
8909 dr, ppu_display_brightness, ppu_oam_basesize, ppu_oam_nameselect, ppu_oam_tdaddr
8910 , ppu_oam_baseaddr, ppu_oam_addr, ppu_oam_firstsprite, ppu_oam_latchdata,
8911 ppu_bg_mode, ppu_mosaic_size, ppu_mosaic_countdown, ppu_bg_scaddr[0], ppu_bg_sc
8912 addr[1], ppu_bg_scaddr[2], ppu_bg_scaddr[3], ppu_bg_scsize[0], ppu_bg_scsize[1],
8913 ppu_bg_scsize[2], ppu_bg_scsize[3], ppu_bg_tdaddr[0], ppu_bg_tdaddr[1],
8914 ppu_bg_tdaddr[2], ppu_bg_tdaddr[3], ppu_bg_ofslatch, ppu_m7_hofs, ppu_m7_vofs,
8915 ppu_bg_hofs[0], ppu_bg_hofs[1], ppu_bg_hofs[2], ppu_bg_hofs[3], ppu_bg_vofs[0],
8916 ppu_bg_vofs[1], ppu_bg_vofs[2], ppu_bg_vofs[3], ppu_vram_mapping, ppu_vram_incs
8917 ize, ppu_vram_addr, ppu_mode7_repeat, ppu_m7_latch, ppu_m7a, ppu_m7b, ppu_m7c,
8918 ppu_m7d, ppu_m7x, ppu_m7y, ppu_cgram_addr, ppu_cgram_latchdata, ppu_window1_lef
8919 t, ppu_window1_right, ppu_window2_left, ppu_window2_right, ppu_window_mask[0],
8920 ppu_window_mask[1], ppu_window_mask[2], ppu_window_mask[3], ppu_window_mask[4],
8921 ppu_window_mask[5], ppu_color_mask, ppu_colorsub_mask, ppu_color_r, ppu_color_g
8922 , ppu_color_b, ppu_color_rgb, ppu_scanlines, ppu_hcounter, ppu_vcounter,
8923 ppu_vram_readbuffer, ppu_oam_itemcount, ppu_oam_tilecount,
8926 \begin_layout Itemize
8927 on_latch has no parameters
8930 \begin_layout Itemize
8931 CPU 0 is S-CPU, 1 is S-SMP.
8934 \begin_layout Itemize
8935 Cheats are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_{RAM,ROM}.
8938 \begin_layout Itemize
8939 Read/Write/Execute hooks are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_
8943 \begin_layout Itemize
8944 Memory areas are: WRAM, APURAM, VRAM, OAM, CGRAM, RTC, DSPRAM, DSPPROM,
8945 DSPDROM, SRAM, ROM, BUS, PTRTABLE, CPU_STATE, PPU_STATE, SMP_STATE, DSP_STATE,
8946 BSXFLASH, BSX_RAM, BSX_PRAM, SLOTA_ROM, SLOTB_ROM, SLOTA_RAM, SLOTB_RAM,
8947 GBCPU_STATE, GBROM, GBRAM, GBWRAM, GBHRAM.
8950 \begin_layout Subsection
8954 \begin_layout Itemize
8955 Registers are: wrambank, cyclecounter, pc, sp, hf1, hf2, zf, cf, a, b, c,
8959 \begin_layout Itemize
8960 on_latch is not supported
8963 \begin_layout Itemize
8967 \begin_layout Itemize
8968 Cheats are supported for ROM, SRAM and WRAM.
8971 \begin_layout Itemize
8972 Read/Write/Execute hooks are supported for ROM (read/execute only), SRAM
8976 \begin_layout Itemize
8977 Memory areas are: SRAM, WRAM, VRAM, IOAMHRAM, ROM, BUS.