lua.lyx

   1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 413
   3 \begin_document
   4 \begin_header
   5 \textclass article
   6 \use_default_options true
   7 \maintain_unincluded_children false
   8 \language english
   9 \language_package default
  10 \inputencoding auto
  11 \fontencoding global
  12 \font_roman default
  13 \font_sans default
  14 \font_typewriter default
  15 \font_default_family default
  16 \use_non_tex_fonts false
  17 \font_sc false
  18 \font_osf false
  19 \font_sf_scale 100
  20 \font_tt_scale 100
  21
  22 \graphics default
  23 \default_output_format default
  24 \output_sync 0
  25 \bibtex_command default
  26 \index_command default
  27 \paperfontsize default
  28 \spacing single
  29 \use_hyperref true
  30 \pdf_bookmarks true
  31 \pdf_bookmarksnumbered false
  32 \pdf_bookmarksopen false
  33 \pdf_bookmarksopenlevel 1
  34 \pdf_breaklinks false
  35 \pdf_pdfborder false
  36 \pdf_colorlinks false
  37 \pdf_backref false
  38 \pdf_pdfusetitle true
  39 \papersize a4paper
  40 \use_geometry true
  41 \use_amsmath 1
  42 \use_esint 1
  43 \use_mhchem 1
  44 \use_mathdots 1
  45 \cite_engine basic
  46 \use_bibtopic false
  47 \use_indices false
  48 \paperorientation portrait
  49 \suppress_date false
  50 \use_refstyle 1
  51 \index Hakusana
  52 \shortcut idx
  53 \color #008000
  54 \end_index
  55 \leftmargin 2cm
  56 \topmargin 2cm
  57 \rightmargin 1cm
  58 \bottommargin 2cm
  59 \headheight 1cm
  60 \headsep 1cm
  61 \footskip 1cm
  62 \secnumdepth 3
  63 \tocdepth 3
  64 \paragraph_separation indent
  65 \paragraph_indentation default
  66 \quotes_language english
  67 \papercolumns 1
  68 \papersides 1
  69 \paperpagestyle default
  70 \tracking_changes false
  71 \output_changes false
  72 \html_math_output 0
  73 \html_css_as_file 0
  74 \html_be_strict false
  75 \end_header
  76
  77 \begin_body
  78
  79 \begin_layout Title
  80 lsnes Lua functions reference
  81 \end_layout
  82
  83 \begin_layout Section
  84 Table of contents
  85 \end_layout
  86
  87 \begin_layout Standard
  88 \begin_inset CommandInset toc
  89 LatexCommand tableofcontents
  90
  91 \end_inset
  92
  93
  94 \end_layout
  95
  96 \begin_layout Standard
  97 \begin_inset Newpage pagebreak
  98 \end_inset
  99
 100
 101 \end_layout
 102
 103 \begin_layout Section
 104 Special tokens
 105 \end_layout
 106
 107 \begin_layout Standard
 108 These tokens are special, and are expanded while the script is being loaded
 109 \end_layout
 110
 111 \begin_layout Subsection
 112 @@LUA_SCRIPT_FILENAME@@
 113 \end_layout
 114
 115 \begin_layout Standard
 116 Expanded to string token containing path and filename of this Lua script.
 117  Handy for referencing other lua scripts or resources that are relative
 118  to this Lua script.
 119 \end_layout
 120
 121 \begin_layout Standard
 122 In practicular, this is suitable to be passed as base argument of various
 123  functions like loadfile, dofile, resolve_filename, gui.bitmap_load, gui.bitmap_lo
 124 ad_png and gui.bitmap_load_pal.
 125 \end_layout
 126
 127 \begin_layout Section
 128 Global
 129 \end_layout
 130
 131 \begin_layout Subsection
 132 print: Print values to console
 133 \end_layout
 134
 135 \begin_layout Itemize
 136 Syntax: none print(value...
 137  values)
 138 \end_layout
 139
 140 \begin_layout Standard
 141 Prints specified values to console.
 142  Can print any Lua type at least enough to identify the type and instance.
 143 \end_layout
 144
 145 \begin_layout Subsection
 146 tostringx: Format a value to string
 147 \end_layout
 148
 149 \begin_layout Itemize
 150 Syntax: string tostringx(value val)
 151 \end_layout
 152
 153 \begin_layout Standard
 154 Formats value <val> like print would, and returns the result as a string.
 155 \end_layout
 156
 157 \begin_layout Subsection
 158 exec: Execute lsnes commands
 159 \end_layout
 160
 161 \begin_layout Itemize
 162 Syntax: none exec(string cmd)
 163 \end_layout
 164
 165 \begin_layout Standard
 166 Execute lsnes command <cmd>.
 167 \end_layout
 168
 169 \begin_layout Subsection
 170 utime: Get current time
 171 \end_layout
 172
 173 \begin_layout Itemize
 174 Syntax: (number,number) utime()
 175 \end_layout
 176
 177 \begin_layout Standard
 178 Returns two numbers.
 179  First is time since some epoch in seconds, the second is microseconds mod
 180  10^6 since that epoch.
 181 \end_layout
 182
 183 \begin_layout Subsection
 184 emulator_ready: Check if emulator has been fully initialized
 185 \end_layout
 186
 187 \begin_layout Itemize
 188 Syntax: boolean emulator_ready()
 189 \end_layout
 190
 191 \begin_layout Standard
 192 Returns true if emulator has finished booting, false if not (on_startup()
 193  will be issued later).
 194 \end_layout
 195
 196 \begin_layout Subsection
 197 set_idle_timeout: Run function after timeout when emulator is idle
 198 \end_layout
 199
 200 \begin_layout Itemize
 201 Syntax: none set_idle_timeout(number timeout)
 202 \end_layout
 203
 204 \begin_layout Standard
 205 Set number of microseconds to block idle for.
 206  After this timeout has expired, on_idle() will be called once.
 207 \end_layout
 208
 209 \begin_layout Subsection
 210 set_timer_timeout: Run function after timeout.
 211 \end_layout
 212
 213 \begin_layout Itemize
 214 Syntax: none set_timer_timeout(number timeout)
 215 \end_layout
 216
 217 \begin_layout Standard
 218 Set number of microseconds to block timer for.
 219  After this timeout has expired, on_timer() will be called once.
 220 \end_layout
 221
 222 \begin_layout Subsection
 223 bus_address: Look up address in system bus.
 224 \end_layout
 225
 226 \begin_layout Itemize
 227 Syntax: none bus_address(number bus_addr)
 228 \end_layout
 229
 230 \begin_layout Standard
 231 Returns virtual address corresponding to specified address on system bus.
 232 \end_layout
 233
 234 \begin_layout Subsection
 235 loopwrapper: Convert loop into callable function
 236 \end_layout
 237
 238 \begin_layout Itemize
 239 Syntax: function loopwrapper(function fun, ...)
 240 \end_layout
 241
 242 \begin_layout Standard
 243 Calls function <fun> with function and specified arguments.
 244  The function passed suspends execution until the function returned is called.
 245  Handy for linear flow control among multiple invocations of a hook.
 246  Example code:
 247 \end_layout
 248
 249 \begin_layout LyX-Code
 250 on_paint = loopwrapper(function(wait)
 251 \end_layout
 252
 253 \begin_deeper
 254 \begin_layout LyX-Code
 255 while true do
 256 \end_layout
 257
 258 \begin_deeper
 259 \begin_layout LyX-Code
 260 gui.text(0, 0,
 261 \begin_inset Quotes eld
 262 \end_inset
 263
 264 Test!
 265 \begin_inset Quotes erd
 266 \end_inset
 267
 268 );
 269 \end_layout
 270
 271 \begin_layout LyX-Code
 272 wait();
 273 \end_layout
 274
 275 \end_deeper
 276 \begin_layout LyX-Code
 277 end
 278 \end_layout
 279
 280 \end_deeper
 281 \begin_layout LyX-Code
 282 end);
 283 \end_layout
 284
 285 \begin_layout Subsection
 286 list_bindings: List keybindings
 287 \end_layout
 288
 289 \begin_layout Itemize
 290 Syntax: table list_bindings([string cmd])
 291 \end_layout
 292
 293 \begin_layout Standard
 294 Get table of all keybindings, indexed by keyspec (modifiers|mask/key).
 295  If <cmd> is specified, the table is limited to that command.
 296  Also searches for controller keys.
 297 \end_layout
 298
 299 \begin_layout Subsection
 300 get_alias: Get expansion of alias
 301 \end_layout
 302
 303 \begin_layout Itemize
 304 Syntax: string get_alias(string aname)
 305 \end_layout
 306
 307 \begin_layout Standard
 308 Get expansion of given alias <aname>.
 309 \end_layout
 310
 311 \begin_layout Subsection
 312 set_alias: Set expansion of alias
 313 \end_layout
 314
 315 \begin_layout Itemize
 316 Syntax: none set_alias(string aname, string value)
 317 \end_layout
 318
 319 \begin_layout Standard
 320 Set expansion of given alias.
 321 \end_layout
 322
 323 \begin_layout Subsection
 324 create_ibind: Create invese binding
 325 \end_layout
 326
 327 \begin_layout Itemize
 328 Syntax: INVERSEBIND create_ibind(string name, string cmd)
 329 \end_layout
 330
 331 \begin_layout Standard
 332 Return object representing inverse binding with specified name <name> and
 333  specified command <cmd>.
 334 \end_layout
 335
 336 \begin_layout Itemize
 337 Note: To create press/release commands, use aliases +foo and -foo .
 338 \end_layout
 339
 340 \begin_layout Itemize
 341 Note: Keep the returned object around.
 342 \end_layout
 343
 344 \begin_layout Subsection
 345 create_command: Create a command
 346 \end_layout
 347
 348 \begin_layout Itemize
 349 Syntax: COMMANDBIND create_commmand(string name, function a)
 350 \end_layout
 351
 352 \begin_layout Itemize
 353 Syntax: COMMANDBIND create_commmand(string name, function a, function b)
 354 \end_layout
 355
 356 \begin_layout Standard
 357 Return object representing a command (pair).
 358 \end_layout
 359
 360 \begin_layout Itemize
 361 If only one function is specied, the command is level-sensitive, <a> is
 362  callback.
 363 \end_layout
 364
 365 \begin_layout Itemize
 366 If <b> is function, the function is edge-sensitive, <a> is positive edge
 367  callback and <b> is negative edge callback.
 368 \end_layout
 369
 370 \begin_layout Itemize
 371 All callbacks get single argument: The parameters passed.
 372 \end_layout
 373
 374 \begin_layout Itemize
 375 Keep the returned object around.
 376 \end_layout
 377
 378 \begin_layout Subsection
 379 loadfile: Load Lua script
 380 \end_layout
 381
 382 \begin_layout Itemize
 383 Syntax: function loadfile(string filename[, string base])
 384 \end_layout
 385
 386 \begin_layout Standard
 387 Load lua script from <filename>, resolved relative to <base> (if empty,
 388  current directory).
 389 \end_layout
 390
 391 \begin_layout Subsection
 392 dofile: Execute Lua script
 393 \end_layout
 394
 395 \begin_layout Itemize
 396 Syntax: function dofile(string filename[, string base])
 397 \end_layout
 398
 399 \begin_layout Standard
 400 Execute lua script from <filename>, resolved relative to <base> (if empty,
 401  current directory) and return all return values.
 402 \end_layout
 403
 404 \begin_layout Subsection
 405 open_file: Open a stream
 406 \end_layout
 407
 408 \begin_layout Itemize
 409 Syntax: FILEREADER open_file(string filename[, string base])
 410 \end_layout
 411
 412 \begin_layout Standard
 413 Open file <filename>, resolved relative to <base> (if empty, current directory)
 414  and return a handle.
 415 \end_layout
 416
 417 \begin_layout Subsection
 418 FILEREADER(): Read line/bytes from stream
 419 \end_layout
 420
 421 \begin_layout Itemize
 422 Syntax: string/nil FILEREADER()
 423 \end_layout
 424
 425 \begin_layout Itemize
 426 Syntax: string/nil FILEREADER(number bytes)
 427 \end_layout
 428
 429 \begin_layout Standard
 430 Reads next line or <bytes> bytes from specified file handle.
 431  On EOF, nil is returned.
 432 \end_layout
 433
 434 \begin_layout Itemize
 435 Note: The line-oriented variant reads in text mode, so CR at end of line
 436  is stripped.
 437 \end_layout
 438
 439 \begin_layout Subsection
 440 FILEREADER:lines: Iterator to read all lines
 441 \end_layout
 442
 443 \begin_layout Itemize
 444 Syntax: for line in <foo>:lines() do ...
 445  end
 446 \end_layout
 447
 448 \begin_layout Standard
 449 Iterator for reading all lines of <foo> in a loop.
 450 \end_layout
 451
 452 \begin_layout Subsection
 453 resolve_filename: Resolve name of file relative to another
 454 \end_layout
 455
 456 \begin_layout Itemize
 457 Syntax: string resolve_file(string filename, string base)
 458 \end_layout
 459
 460 \begin_layout Standard
 461 Resolve name of file <filename> relative to <base> and return the result.
 462 \end_layout
 463
 464 \begin_layout Standard
 465 \begin_inset Newpage pagebreak
 466 \end_inset
 467
 468
 469 \end_layout
 470
 471 \begin_layout Section
 472 Table bit:
 473 \end_layout
 474
 475 \begin_layout Standard
 476 Bitwise logical functions and related.
 477 \end_layout
 478
 479 \begin_layout Subsection
 480 bit.none/bit.bnot: Bitwise none or NOT function
 481 \end_layout
 482
 483 \begin_layout Itemize
 484 Syntax: number bit.none(number...)
 485 \end_layout
 486
 487 \begin_layout Itemize
 488 Syntax: number bit.bnot(number...)
 489 \end_layout
 490
 491 \begin_layout Standard
 492 48-bit bitwise NOT / NONE function (set bits that are set in none of the
 493  arguments).
 494 \end_layout
 495
 496 \begin_layout Subsection
 497 bit.any/bit.bor: Bitwise any or OR function
 498 \end_layout
 499
 500 \begin_layout Itemize
 501 Syntax: number bit.any(number...)
 502 \end_layout
 503
 504 \begin_layout Itemize
 505 Syntax: number bit.bor(number...)
 506 \end_layout
 507
 508 \begin_layout Standard
 509 48-bit bitwise OR / ANY function (set bits that are set in any of the arguments).
 510 \end_layout
 511
 512 \begin_layout Subsection
 513 bit.all/bit.band: Bitwise all or AND function
 514 \end_layout
 515
 516 \begin_layout Itemize
 517 Syntax: number bit.all(number...)
 518 \end_layout
 519
 520 \begin_layout Itemize
 521 Syntax: number bit.band(number...)
 522 \end_layout
 523
 524 \begin_layout Standard
 525 48-bit bitwise AND / ALL function (set bits that are set in all of the arguments
 526 ).
 527 \end_layout
 528
 529 \begin_layout Subsection
 530 bit.parity/bit.bxor: Bitwise parity or XOR function
 531 \end_layout
 532
 533 \begin_layout Itemize
 534 Syntax: number bit.parity(number...)
 535 \end_layout
 536
 537 \begin_layout Itemize
 538 Syntax: number bit.bxor(number...)
 539 \end_layout
 540
 541 \begin_layout Standard
 542 48-bit bitwise XOR / PARITY function (set bits that are set in odd number
 543  of the arguments).
 544 \end_layout
 545
 546 \begin_layout Subsection
 547 bit.lrotate: Rotate a number left
 548 \end_layout
 549
 550 \begin_layout Itemize
 551 Syntax: number bit.lrotate(number base[, number amount[, number bits]])
 552 \end_layout
 553
 554 \begin_layout Standard
 555 Rotate <bits>-bit (max 48, default 48) number <base> left by <amount> (default
 556  1) places.
 557 \end_layout
 558
 559 \begin_layout Subsection
 560 bit.rrotate: Rotate a number right
 561 \end_layout
 562
 563 \begin_layout Itemize
 564 Syntax: number bit.rrotate(number base[, number amount[, number bits]])
 565 \end_layout
 566
 567 \begin_layout Standard
 568 Rotate <bits>-bit (max 48, default 48) number <base> right by <amount> (default
 569  1) places.
 570 \end_layout
 571
 572 \begin_layout Subsection
 573 bit.lshift: Shift a number left
 574 \end_layout
 575
 576 \begin_layout Itemize
 577 Syntax: number bit.lshift(number base[, number amount[, number bits]])
 578 \end_layout
 579
 580 \begin_layout Standard
 581 Shift <bits>-bit (max 48, default 48) number <base> left by <amount> (default
 582  1) places.
 583  The new bits are filled with zeroes.
 584 \end_layout
 585
 586 \begin_layout Subsection
 587 bit.lrshift: Shift a number right (logical)
 588 \end_layout
 589
 590 \begin_layout Itemize
 591 Syntax: number bit.lrshift(number base[, number amount[, number bits]])
 592 \end_layout
 593
 594 \begin_layout Standard
 595 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
 596  (default 1) places.
 597  The new bits are filled with zeroes.
 598 \end_layout
 599
 600 \begin_layout Subsection
 601 bit.arshift: Shift a number right (arithmetic)
 602 \end_layout
 603
 604 \begin_layout Itemize
 605 Syntax: number bit.arshift(number base[, number amount[, number bits]])
 606 \end_layout
 607
 608 \begin_layout Standard
 609 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
 610  (default 1) places.
 611  The new bits are shifted in with copy of the high bit.
 612 \end_layout
 613
 614 \begin_layout Subsection
 615 bit.extract: Extract/shuffle bits from number
 616 \end_layout
 617
 618 \begin_layout Itemize
 619 Syntax: number bit.extract(number base[, number bit0[, number bit1,...]])
 620 \end_layout
 621
 622 \begin_layout Standard
 623 Returns number that has bit0-th bit as bit 0, bit1-th bit as 1 and so on.
 624 \end_layout
 625
 626 \begin_layout Itemize
 627 Note: Bit numbers up to 51 should work reliably (then things start falling
 628  apart due to double precision issues).
 629 \end_layout
 630
 631 \begin_layout Itemize
 632 Note: There are two special bit positions, true and false, standing for
 633  always set bit and always clear bit.
 634 \end_layout
 635
 636 \begin_layout Subsection
 637 bit.value: Construct number with specified bits set
 638 \end_layout
 639
 640 \begin_layout Itemize
 641 Syntax: number bit.value([number bit1[, number bit2,...]])
 642 \end_layout
 643
 644 \begin_layout Standard
 645 Returns bitwise OR of 1 left shifted by <bit1> places, 1 left shifted by
 646  <bit2> places and so on.
 647  As special value, nil argument is no-op.
 648 \end_layout
 649
 650 \begin_layout Subsection
 651 bit.test_any: Test if any bit is set
 652 \end_layout
 653
 654 \begin_layout Itemize
 655 Syntax: boolean bit.test_any(number a, number b)
 656 \end_layout
 657
 658 \begin_layout Standard
 659 Returns true if bitwise and of <a> and <b> is nonzero, otherwise false.
 660 \end_layout
 661
 662 \begin_layout Subsection
 663 bit.test_all: Test if all bits are set
 664 \end_layout
 665
 666 \begin_layout Itemize
 667 Syntax: boolean bit.test_all(number a, number b)
 668 \end_layout
 669
 670 \begin_layout Standard
 671 Returns true if bitwise and of <a> and <b> equals <b>, otherwise false.
 672 \end_layout
 673
 674 \begin_layout Subsection
 675 bit.popcount: Population count
 676 \end_layout
 677
 678 \begin_layout Itemize
 679 Syntax: number bit.popcount(number a)
 680 \end_layout
 681
 682 \begin_layout Standard
 683 Returns number of set bits in <a>.
 684 \end_layout
 685
 686 \begin_layout Subsection
 687 bit.clshift: Chained left shift
 688 \end_layout
 689
 690 \begin_layout Itemize
 691 Syntax: (number, number) bit.clshift(number a, number b, [number amount,[number
 692  bits]])
 693 \end_layout
 694
 695 \begin_layout Standard
 696 Does chained left shift on <a>, <b> by <amount> positions (default 1), assuming
 697  numbers to be of specified number of bits <bits> (default 48).
 698 \end_layout
 699
 700 \begin_layout Subsection
 701 bit.crshift: Chained right shift
 702 \end_layout
 703
 704 \begin_layout Itemize
 705 Syntax: (number, number) bit.crshift(number a, number b, [number amount,[number
 706  bits]])
 707 \end_layout
 708
 709 \begin_layout Standard
 710 Does chained right shift on <a>, <b> by <amount> positions (default 1),
 711  assuming numbers to be of specified number of bits <bits> (default 48).
 712 \end_layout
 713
 714 \begin_layout Subsection
 715 bit.flagdecode: Decode bitfield into flags
 716 \end_layout
 717
 718 \begin_layout Itemize
 719 Syntax: string bit.flagdecode(number a, number bits, [string on, [string
 720  off]])
 721 \end_layout
 722
 723 \begin_layout Standard
 724 Return string of length bits where ith character is ith character of on
 725  if bit i is on, otherwise ith character of off.
 726  Out of range reads give last character.
 727 \end_layout
 728
 729 \begin_layout Itemize
 730 Note: <on> defaults to '*' if empty.
 731 \end_layout
 732
 733 \begin_layout Itemize
 734 Note: <off> defaults to '-' if empty.
 735 \end_layout
 736
 737 \begin_layout Subsection
 738 bit.rflagdecode: Decode bitfield into flags
 739 \end_layout
 740
 741 \begin_layout Itemize
 742 Syntax: string bit.rflagdecode(number a, number bits, [string on, [string
 743  off]])
 744 \end_layout
 745
 746 \begin_layout Standard
 747 Like bit.flagdecode, but outputs the string in the opposite order (most significa
 748 nt bit first).
 749 \end_layout
 750
 751 \begin_layout Standard
 752 \begin_inset Newpage pagebreak
 753 \end_inset
 754
 755
 756 \end_layout
 757
 758 \begin_layout Section
 759 Table gui:
 760 \end_layout
 761
 762 \begin_layout Itemize
 763 Functions that draw to screen can only only be called in on_paint and on_video
 764  callbacks or if non-default render queue has been set.
 765 \end_layout
 766
 767 \begin_layout Itemize
 768 Colors are 32-bit.
 769  Bits 0-7 are the blue component, bits 8-15 are the green component, bits
 770  16-23 are the red component, bits 24-31 are alpha component (0 is fully
 771  opaque, 255 is almost transparent).
 772  -1 is the fully transparent color.
 773 \end_layout
 774
 775 \begin_layout Itemize
 776 Alpha values greater than 127 do work properly.
 777 \end_layout
 778
 779 \begin_layout Itemize
 780 Origin of coordinates is at top left corner of game display area.
 781  Left and top gaps correspond to negative coordinates.
 782 \end_layout
 783
 784 \begin_layout Subsection
 785 gui.resolution: Get current resolution
 786 \end_layout
 787
 788 \begin_layout Itemize
 789 Syntax: (number, number) gui.resolution()
 790 \end_layout
 791
 792 \begin_layout Standard
 793 Returns 2-tuple (hresolution, vresolution).
 794 \end_layout
 795
 796 \begin_layout Subsection
 797 gui.left_gap/gui.right_gap/gui.top_gap/gui.bottom_gap: Set edge gaps
 798 \end_layout
 799
 800 \begin_layout Itemize
 801 Syntax: number gui.left_gap(number gap)
 802 \end_layout
 803
 804 \begin_layout Itemize
 805 Syntax: number gui.right_gap(number gap)
 806 \end_layout
 807
 808 \begin_layout Itemize
 809 Syntax: number gui.top_gap(number gap)
 810 \end_layout
 811
 812 \begin_layout Itemize
 813 Syntax: number gui.bottom_gap(number gap)
 814 \end_layout
 815
 816 \begin_layout Standard
 817 Set the specified edge gap to specified value <gap> (max gap is 8191).
 818  If successful, old gap is returned.
 819 \end_layout
 820
 821 \begin_layout Subsection
 822 gui.delta_left_gap/gui.delta_right_gap/gui.delta_top_gap/gui.delta_bottom_gap:
 823  Adjust edge gaps
 824 \end_layout
 825
 826 \begin_layout Itemize
 827 Syntax: number gui.delta_left_gap(number dgap)
 828 \end_layout
 829
 830 \begin_layout Itemize
 831 Syntax: number gui.delta_right_gap(number dgap)
 832 \end_layout
 833
 834 \begin_layout Itemize
 835 Syntax: number gui.delta_top_gap(number dgap)
 836 \end_layout
 837
 838 \begin_layout Itemize
 839 Syntax: number gui.delta_bottom_gap(number dgap)
 840 \end_layout
 841
 842 \begin_layout Standard
 843 Increase the specified edge gap by specified value <dgap> (max gap is 8191)
 844  and return the old gap (returns nothing on error).
 845 \end_layout
 846
 847 \begin_layout Subsection
 848 gui.text/gui.textH/gui.textV,gui.textHV: Draw text
 849 \end_layout
 850
 851 \begin_layout Itemize
 852 Syntax: none gui.text(number x, number y, string text[, number fgc[, number
 853  bgc]])
 854 \end_layout
 855
 856 \begin_layout Itemize
 857 Syntax: none gui.textH(number x, number y, string text[, number fgc[, number
 858  bgc]])
 859 \end_layout
 860
 861 \begin_layout Itemize
 862 Syntax: none gui.textV(number x, number y, string text[, number fgc[, number
 863  bgc]])
 864 \end_layout
 865
 866 \begin_layout Itemize
 867 Syntax: none gui.textHV(number x, number y, string text[, number fgc[, number
 868  bgc]])
 869 \end_layout
 870
 871 \begin_layout Standard
 872 Draw specified text on the GUI (each character cell is 8 or 16 wide and
 873  16 high).
 874  Parameters:
 875 \end_layout
 876
 877 \begin_layout Itemize
 878 x: X-coordinate to start the drawing from (and x-coordinate at begining
 879  of the lines).
 880 \end_layout
 881
 882 \begin_layout Itemize
 883 y: Y-coordinate to start the drawing from.
 884 \end_layout
 885
 886 \begin_layout Itemize
 887 text: The text to draw.
 888 \end_layout
 889
 890 \begin_layout Itemize
 891 fgc: Text color (default is 0xFFFFFF (white))
 892 \end_layout
 893
 894 \begin_layout Itemize
 895 bgc: Background color (default is -1 (transparent))
 896 \end_layout
 897
 898 \begin_layout Standard
 899 Note: The H variants draw at double width and V variants draw at double
 900  height.
 901 \end_layout
 902
 903 \begin_layout Subsection
 904 gui.rectangle: Draw a rectangle
 905 \end_layout
 906
 907 \begin_layout Itemize
 908 Syntax: none gui.rectangle(number x, number y, number width, number height[,
 909  number thickness[, number outline[, number fill]]])
 910 \end_layout
 911
 912 \begin_layout Standard
 913 Draw rectangle on the GUI.
 914  Parameters:
 915 \end_layout
 916
 917 \begin_layout Itemize
 918 x: X-coordinate of left edge.
 919 \end_layout
 920
 921 \begin_layout Itemize
 922 y: Y-coordinate of upper edge.
 923 \end_layout
 924
 925 \begin_layout Itemize
 926 width: Width of rectangle.
 927 \end_layout
 928
 929 \begin_layout Itemize
 930 height: Height of rectangle.
 931 \end_layout
 932
 933 \begin_layout Itemize
 934 thickness: Thickness of outline (default is 1).
 935 \end_layout
 936
 937 \begin_layout Itemize
 938 outline: Color of outline (default is 0xFFFFFF (white))
 939 \end_layout
 940
 941 \begin_layout Itemize
 942 fill: Color of fill (default is -1 (transparent))
 943 \end_layout
 944
 945 \begin_layout Subsection
 946 gui.box: Draw a 3D-effect box
 947 \end_layout
 948
 949 \begin_layout Itemize
 950 Syntax: none gui.box(number x, number y, number width, number height[, number
 951  thickness[, number outline1[,number outline2[, number fill]]]])
 952 \end_layout
 953
 954 \begin_layout Standard
 955 Draw rectangle with 3D effect on the GUI.
 956  Parameters:
 957 \end_layout
 958
 959 \begin_layout Itemize
 960 x: X-coordinate of left edge.
 961 \end_layout
 962
 963 \begin_layout Itemize
 964 y: Y-coordinate of upper edge.
 965 \end_layout
 966
 967 \begin_layout Itemize
 968 width: Width of rectangle.
 969 \end_layout
 970
 971 \begin_layout Itemize
 972 height: Height of rectangle.
 973 \end_layout
 974
 975 \begin_layout Itemize
 976 thickness: Thickness of outline (default is 1).
 977 \end_layout
 978
 979 \begin_layout Itemize
 980 outline1: First color of outline (default is 0xFFFFFF (white))
 981 \end_layout
 982
 983 \begin_layout Itemize
 984 outline2: First color of outline (default is 0x808080 (dark gray))
 985 \end_layout
 986
 987 \begin_layout Itemize
 988 fill: Color of fill (default is 0xC0C0C0 (light grayy))
 989 \end_layout
 990
 991 \begin_layout Subsection
 992 gui.pixel: Draw a single pixel
 993 \end_layout
 994
 995 \begin_layout Itemize
 996 Syntax: none gui.pixel(number x, number y[, number color])
 997 \end_layout
 998
 999 \begin_layout Standard
1000 Draw one pixel on the GUI.
1001  Parameters:
1002 \end_layout
1003
1004 \begin_layout Itemize
1005 x: X-coordinate of the pixel
1006 \end_layout
1007
1008 \begin_layout Itemize
1009 y: Y-coordinate of the pixel
1010 \end_layout
1011
1012 \begin_layout Itemize
1013 color: Color of the pixel (default is 0xFFFFFF (white))
1014 \end_layout
1015
1016 \begin_layout Subsection
1017 gui.crosshair: Draw a crosshair
1018 \end_layout
1019
1020 \begin_layout Itemize
1021 Syntax: none gui.crosshair(number x, number y[, number length[, number color]])
1022 \end_layout
1023
1024 \begin_layout Standard
1025 Draw a crosshair.
1026  Parameters:
1027 \end_layout
1028
1029 \begin_layout Itemize
1030 x: X-coordinate of the crosshair
1031 \end_layout
1032
1033 \begin_layout Itemize
1034 y: Y-coordinate of the crosshair
1035 \end_layout
1036
1037 \begin_layout Itemize
1038 length: Length of the crosshair lines (default 10).
1039 \end_layout
1040
1041 \begin_layout Itemize
1042 color: Color of the crosshair (default is 0xFFFFFF (white))
1043 \end_layout
1044
1045 \begin_layout Subsection
1046 gui.line: Draw a line
1047 \end_layout
1048
1049 \begin_layout Itemize
1050 Syntax: none gui.line(number x1, number y1, number x2, number y2[, number
1051  color])
1052 \end_layout
1053
1054 \begin_layout Standard
1055 Draw a thin line.
1056  Parameters:
1057 \end_layout
1058
1059 \begin_layout Itemize
1060 x1: X-coordinate of one end.
1061 \end_layout
1062
1063 \begin_layout Itemize
1064 y1: Y-coordinate of one end.
1065 \end_layout
1066
1067 \begin_layout Itemize
1068 x2: X-coordinate of the other end.
1069 \end_layout
1070
1071 \begin_layout Itemize
1072 y2: Y-coordinate of the other end.
1073 \end_layout
1074
1075 \begin_layout Itemize
1076 color: Color of the line (default is 0xFFFFFF (white)).
1077 \end_layout
1078
1079 \begin_layout Subsection
1080 gui.circle: Draw a (filled) circle
1081 \end_layout
1082
1083 \begin_layout Itemize
1084 Syntax: none gui.circle(number x, number y, number r[, number thick[, number
1085  border[, number fil]]])
1086 \end_layout
1087
1088 \begin_layout Standard
1089 Draw a circle.
1090  Parameters.
1091 \end_layout
1092
1093 \begin_layout Itemize
1094 x: X-coordinate of the center
1095 \end_layout
1096
1097 \begin_layout Itemize
1098 y: Y-coordinate of the center
1099 \end_layout
1100
1101 \begin_layout Itemize
1102 r: The radius of the circle
1103 \end_layout
1104
1105 \begin_layout Itemize
1106 thick: Border thickness
1107 \end_layout
1108
1109 \begin_layout Itemize
1110 border: Border color (default is 0xFFFFFF (white))
1111 \end_layout
1112
1113 \begin_layout Itemize
1114 fill: Fill color (default is -1 (transparent)).
1115 \end_layout
1116
1117 \begin_layout Subsection
1118 gui.bitmap_draw: Draw a bitmap
1119 \end_layout
1120
1121 \begin_layout Itemize
1122 Syntax: none gui.bitmap_draw(number x, number y, BITMAP bitmap, PALETTE palette)
1123 \end_layout
1124
1125 \begin_layout Itemize
1126 Syntax: none gui.bitmap_draw(number x, number y, DBITMAP bitmap)
1127 \end_layout
1128
1129 \begin_layout Standard
1130 Draw a bitmap <bitmap> on screen with specified palette <palette> (if bitmap
1131  is paletted) .
1132  Parameters:
1133 \end_layout
1134
1135 \begin_layout Itemize
1136 x: X-coordinate of left edge.
1137 \end_layout
1138
1139 \begin_layout Itemize
1140 y: Y-coordinate of top edge.
1141 \end_layout
1142
1143 \begin_layout Itemize
1144 bitmap: The bitmap to draw
1145 \end_layout
1146
1147 \begin_layout Itemize
1148 palette: The palette to draw the bitmap using.
1149 \end_layout
1150
1151 \begin_layout Subsection
1152 gui.palette_new: Create a new palette
1153 \end_layout
1154
1155 \begin_layout Itemize
1156 Syntax: PALETTE gui.palette_new()
1157 \end_layout
1158
1159 \begin_layout Standard
1160 Returns a new palette (initially all transparent).
1161
1162 \end_layout
1163
1164 \begin_layout Subsection
1165 gui.bitmap_new: Create a new bitmap
1166 \end_layout
1167
1168 \begin_layout Itemize
1169 Syntax: BITMAP/DBITMAP gui.bitmap_new(number w, number h, boolean direct[,
1170  bool icolor])
1171 \end_layout
1172
1173 \begin_layout Standard
1174 Returns a new bitmap/dbitmap.
1175 \end_layout
1176
1177 \begin_layout Standard
1178 Parameters:
1179 \end_layout
1180
1181 \begin_layout Itemize
1182 w: The width of new bitmap
1183 \end_layout
1184
1185 \begin_layout Itemize
1186 h: The height of new bitmap
1187 \end_layout
1188
1189 \begin_layout Itemize
1190 direct: If true, the returned bitmap is dbitmap, otherwise bitmap.
1191 \end_layout
1192
1193 \begin_layout Itemize
1194 icolor: Initital fill color (defaults to 0 on BITMAP, -1 on DBITMAP)
1195 \end_layout
1196
1197 \begin_layout Subsection
1198 gui.bitmap_load/gui.bitmap_load_str: Load a bitmap from file or string
1199 \end_layout
1200
1201 \begin_layout Itemize
1202 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load(string file[, string base])
1203 \end_layout
1204
1205 \begin_layout Itemize
1206 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_str(string content)
1207 \end_layout
1208
1209 \begin_layout Standard
1210 Reads file <file> (resolved relative to <base>) or string <content> and
1211  returns loaded bitmap/dbitmap (if bitmap, the second return value is palette
1212  for bitmap).
1213 \end_layout
1214
1215 \begin_layout Subsection
1216 gui.bitmap_load_png/gui.bitmap_load_png_str: Load a bitmap from PNG
1217 \end_layout
1218
1219 \begin_layout Itemize
1220 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_png(string file[, string
1221  base])
1222 \end_layout
1223
1224 \begin_layout Itemize
1225 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_png_str(string content)
1226 \end_layout
1227
1228 \begin_layout Standard
1229 Load a bitmap from PNG file <file> (resolved relative to <base>) or BASE64
1230  encoded content <content>.
1231 \end_layout
1232
1233 \begin_layout Itemize
1234 If the PNG is of color type 3 (PALETTE), returns two value.
1235  First is BITMAP containing the image data from the PNG and second is PALETTE
1236  containg the palette data from the PNG.
1237 \end_layout
1238
1239 \begin_layout Itemize
1240 For color types 0 (GRAY), 2 (RGB), 4 (GRAY_ALPHA) and 6 (RGBA), returns
1241  one DBITMAP containg the image data loaded from the PNG.
1242 \end_layout
1243
1244 \begin_layout Subsection
1245 gui.bitmap_load_pal/gui.bitmap_load_pal_str: Load a palette
1246 \end_layout
1247
1248 \begin_layout Itemize
1249 Syntax: PALETTE gui.bitmap_load_pal(string file[, string base])
1250 \end_layout
1251
1252 \begin_layout Itemize
1253 Syntax: PALETTE gui.bitmap_load_pal_str(string content)
1254 \end_layout
1255
1256 \begin_layout Standard
1257 Load a palette from file <file>(resolved relative to <base>) or string <content>.
1258 \end_layout
1259
1260 \begin_layout Itemize
1261 The kinds of lines supported:
1262 \end_layout
1263
1264 \begin_deeper
1265 \begin_layout Itemize
1266 Blank or just whitespace: Ignored
1267 \end_layout
1268
1269 \begin_layout Itemize
1270 First non-whitespace is '#': Ignored
1271 \end_layout
1272
1273 \begin_layout Itemize
1274 <r> <g> <b>: Fully opaque color with specified RGB values (0-255)
1275 \end_layout
1276
1277 \begin_layout Itemize
1278 <r> <g> <b> <a>: Color with specified RGB values (0-255) and specified alpha
1279  (0-256, 0 being fully transparent and 256 fully opaque).
1280 \end_layout
1281
1282 \begin_layout Itemize
1283 transparent: Fully transparent color
1284 \end_layout
1285
1286 \end_deeper
1287 \begin_layout Subsection
1288 gui.palette_set: Set palette entry
1289 \end_layout
1290
1291 \begin_layout Itemize
1292 Syntax: none gui.palette_set(PALETTE palette, number index, number color)
1293 \end_layout
1294
1295 \begin_layout Standard
1296 Sets color in palette.
1297  Parameters:
1298 \end_layout
1299
1300 \begin_layout Itemize
1301 palette: The palette to manipulate
1302 \end_layout
1303
1304 \begin_layout Itemize
1305 index: Index of color (0-65535).
1306 \end_layout
1307
1308 \begin_layout Itemize
1309 color: The color value.
1310 \end_layout
1311
1312 \begin_layout Subsection
1313 gui.bitmap_pset: Set pixel in bitmap
1314 \end_layout
1315
1316 \begin_layout Itemize
1317 Syntax: none gui.bitmap_pset(BITMAP/DBITMAP bitmap, number x, number y, number
1318  color)
1319 \end_layout
1320
1321 \begin_layout Standard
1322 Sets specified pixel in bitmap.
1323  Parameters:
1324 \end_layout
1325
1326 \begin_layout Itemize
1327 bitmap: The bitmap to manipulate
1328 \end_layout
1329
1330 \begin_layout Itemize
1331 x: The x-coordinate of the pixel.
1332 \end_layout
1333
1334 \begin_layout Itemize
1335 y: The y-coordinate of the pixel.
1336 \end_layout
1337
1338 \begin_layout Itemize
1339 color: If bitmap is a bitmap, color index (0-65535).
1340  Otherwise color value.
1341 \end_layout
1342
1343 \begin_layout Subsection
1344 gui.bitmap_pget: Get pixel in bitmap
1345 \end_layout
1346
1347 \begin_layout Itemize
1348 Syntax: number gui.bitmap_pget(BITMAP/DBITMAP bitmap, number x, number y)
1349 \end_layout
1350
1351 \begin_layout Standard
1352 Gets specified pixel in bitmap.
1353  Parameters:
1354 \end_layout
1355
1356 \begin_layout Itemize
1357 bitmap: The bitmap to query
1358 \end_layout
1359
1360 \begin_layout Itemize
1361 x: The x-coordinate of the pixel.
1362 \end_layout
1363
1364 \begin_layout Itemize
1365 y: The y-coordinate of the pixel.
1366 \end_layout
1367
1368 \begin_layout Standard
1369 The bitmap color (color index if paletted, otherwise color value).
1370 \end_layout
1371
1372 \begin_layout Subsection
1373 gui.bitmap_size: Get size of bitmap
1374 \end_layout
1375
1376 \begin_layout Itemize
1377 Syntax: (number, number) gui.bitmap_size(BITMAP/DBITMAP bitmap)
1378 \end_layout
1379
1380 \begin_layout Standard
1381 Get size of bitmap <bitmap>.
1382  The first return is the width, the second is the height.
1383 \end_layout
1384
1385 \begin_layout Itemize
1386 Note: Can be used anywhere.
1387 \end_layout
1388
1389 \begin_layout Subsection
1390 gui.bitmap_blit: Blit a bitmap into another
1391 \end_layout
1392
1393 \begin_layout Itemize
1394 Syntax: none gui.bitmap_blit(BITMAP dest, number dx, number dy, BITMAP src,
1395  number sx, number sy, number w, number h[, number ck])
1396 \end_layout
1397
1398 \begin_layout Itemize
1399 Syntax: none gui.bitmap_blit(DBITMAP dest, number dx, number dy, DBITMAP
1400  src, number sx, number sy, number w, number h[, number ck])
1401 \end_layout
1402
1403 \begin_layout Itemize
1404 Syntax: none gui.bitmap_blit(DBITMAP dest, number dx, number dy, BITMAP src,
1405  PALETTE pal, number sx, number sy, number w, number h[, number ck])
1406 \end_layout
1407
1408 \begin_layout Standard
1409 Blit a part of bitmap to another.
1410  Parameters:
1411 \end_layout
1412
1413 \begin_layout Itemize
1414 dest: Destination to blit to.
1415 \end_layout
1416
1417 \begin_layout Itemize
1418 dx: left edge of target
1419 \end_layout
1420
1421 \begin_layout Itemize
1422 dy: Top edge of target
1423 \end_layout
1424
1425 \begin_layout Itemize
1426 src: The source to blit from.
1427 \end_layout
1428
1429 \begin_layout Itemize
1430 pal: The palette to use in blit.
1431 \end_layout
1432
1433 \begin_layout Itemize
1434 sx: left edge of source
1435 \end_layout
1436
1437 \begin_layout Itemize
1438 sy: Top edge of source
1439 \end_layout
1440
1441 \begin_layout Itemize
1442 w: Width of region
1443 \end_layout
1444
1445 \begin_layout Itemize
1446 h: Height of region.
1447 \end_layout
1448
1449 \begin_layout Itemize
1450 ck: Color key.
1451  Pixels of this color are not blitted.
1452 \end_layout
1453
1454 \begin_deeper
1455 \begin_layout Itemize
1456 If soruce bitmap is bitmap, this is color index of colorkey.
1457  Values outside range 0-65535 cause no key to be used as colorkey.
1458 \end_layout
1459
1460 \begin_layout Itemize
1461 If source bitmap is dbitmap, this is the color value of colorkey.
1462 \end_layout
1463
1464 \begin_layout Itemize
1465 May be absent or nil for no colorkey blit.
1466 \end_layout
1467
1468 \end_deeper
1469 \begin_layout Subsection
1470 gui.repaint: Arrange a repaint
1471 \end_layout
1472
1473 \begin_layout Itemize
1474 Syntax: none gui.repaint()
1475 \end_layout
1476
1477 \begin_layout Standard
1478 Request on_repaint() to happen as soon as possible.
1479 \end_layout
1480
1481 \begin_layout Subsection
1482 gui.synchronous_repaint: Paint screen now
1483 \end_layout
1484
1485 \begin_layout Itemize
1486 Syntax: none gui.synchronous_repaint(RENDERQUEUE queue)
1487 \end_layout
1488
1489 \begin_layout Standard
1490 Paints specified render queue on screen right there and then.
1491 \end_layout
1492
1493 \begin_layout Subsection
1494 gui.subframe_update: Enable/Disable subframe updates
1495 \end_layout
1496
1497 \begin_layout Itemize
1498 Syntax: none gui.subframe_update(boolean on)
1499 \end_layout
1500
1501 \begin_layout Standard
1502 Request subframe updates (calling on_paint() on subframes) to happen (<on>=true)
1503  or not happen (<on>=false).
1504 \end_layout
1505
1506 \begin_layout Subsection
1507 gui.screenshot: Write a screenshot
1508 \end_layout
1509
1510 \begin_layout Itemize
1511 Syntax: none gui.screenshot(string filename)
1512 \end_layout
1513
1514 \begin_layout Standard
1515 Write PNG screenshot of the current frame (no drawings) to specified file
1516  <filename>.
1517 \end_layout
1518
1519 \begin_layout Subsection
1520 gui.screenshot_bitmap: Write a screenshot to bitmap
1521 \end_layout
1522
1523 \begin_layout Itemize
1524 Syntax: DBITMAP gui.screenshot_bitmap()
1525 \end_layout
1526
1527 \begin_layout Standard
1528 Write PNG screenshot of the current frame (no drawings) to dbitmap and return
1529  the result.
1530 \end_layout
1531
1532 \begin_layout Subsection
1533 gui.color: Compose a color.
1534 \end_layout
1535
1536 \begin_layout Itemize
1537 Syntax: number gui.color(number r, number g, number b[, number a])
1538 \end_layout
1539
1540 \begin_layout Standard
1541 Returns color (in notation Lua scripts use) corresponding to color (<r>,<g>,<b>)
1542 , each component in scale 0-255.
1543  If <a> is specified, that is alpha (0 is fully transparent, 256(sic) is
1544  fully opaque).
1545  The default alpha is 256.
1546 \end_layout
1547
1548 \begin_layout Subsection
1549 gui.status: Set status variable
1550 \end_layout
1551
1552 \begin_layout Itemize
1553 Syntax: none gui.status(string name, string value)
1554 \end_layout
1555
1556 \begin_layout Standard
1557 Set status field
1558 \begin_inset Quotes eld
1559 \end_inset
1560
1561 L[<name>]
1562 \begin_inset Quotes erd
1563 \end_inset
1564
1565  to <value> in status area.
1566 \end_layout
1567
1568 \begin_layout Subsection
1569 gui.rainbow: Rainbow color calculation
1570 \end_layout
1571
1572 \begin_layout Itemize
1573 Syntax: number gui.rainbow(number step, number steps[, number color])
1574 \end_layout
1575
1576 \begin_layout Standard
1577 Perform hue rotation of color <color> (default bright red), by <step> steps.
1578  The number of steps per full rotation is given by absolute value of <steps>.
1579 \end_layout
1580
1581 \begin_layout Standard
1582 If <steps> is negative, the rotation will be counterclockwise.
1583 \end_layout
1584
1585 \begin_layout Subsection
1586 gui.renderq_new: Create a render queue
1587 \end_layout
1588
1589 \begin_layout Itemize
1590 Syntax: RENDERQUEUE gui.renderq_new(number width, number height)
1591 \end_layout
1592
1593 \begin_layout Standard
1594 Create render queue with specified reported size and return it.
1595 \end_layout
1596
1597 \begin_layout Subsection
1598 gui.renderq_clear: Clear a render queue
1599 \end_layout
1600
1601 \begin_layout Itemize
1602 Syntax: none gui.renderq_clear(RENDERQUEUE queue)
1603 \end_layout
1604
1605 \begin_layout Standard
1606 Clear specified render queue.
1607 \end_layout
1608
1609 \begin_layout Subsection
1610 gui.renderq_set: Change active render queue
1611 \end_layout
1612
1613 \begin_layout Itemize
1614 Syntax: none gui.renderq_set(RENDERQUEUE queue)
1615 \end_layout
1616
1617 \begin_layout Standard
1618 Switch to specified render queue.
1619  Use nil as queue to switch to default queue.
1620 \end_layout
1621
1622 \begin_layout Itemize
1623 Note: When switched to another queue, all drawing functions work and draw
1624  there, even outside on_video/on_paint.
1625 \end_layout
1626
1627 \begin_layout Subsection
1628 gui.renderq_run: Run render queue
1629 \end_layout
1630
1631 \begin_layout Itemize
1632 Syntax: none gui.renderq_run(RENDERQUEUE queue)
1633 \end_layout
1634
1635 \begin_layout Standard
1636 Run specified render queue, copying the objects to current render queue.
1637
1638 \end_layout
1639
1640 \begin_layout Itemize
1641 Warning: Don't try to run the current render queue.
1642 \end_layout
1643
1644 \begin_layout Subsection
1645 gui.loadfont: Load a font file
1646 \end_layout
1647
1648 \begin_layout Itemize
1649 Syntax: CUSTOMFONT gui.loadfont([string filename])
1650 \end_layout
1651
1652 \begin_layout Standard
1653 Loads font from specified file (CUSTOMFONT object).
1654  If filename is not given, loads the system default font.
1655 \end_layout
1656
1657 \begin_layout Subsection
1658 CUSTOMFONT(): Render text to screen
1659 \end_layout
1660
1661 \begin_layout Itemize
1662 Syntax: none CUSTOMFONT(number x, number y, string text[, number fgc[, number
1663  bgc[, number hlc]]])
1664 \end_layout
1665
1666 \begin_layout Standard
1667 Draw string with custom font to screen.
1668  The parameters are the same as in gui.text, except <hlc> is the halo color
1669  (default is no halo).
1670
1671 \end_layout
1672
1673 \begin_layout Subsection
1674 gui.adjust_transparency: Adjust transparency of DBITMAP or PALETTE
1675 \end_layout
1676
1677 \begin_layout Itemize
1678 Syntax: none gui.adjust_transparency(DBITMAP obj, number adj)
1679 \end_layout
1680
1681 \begin_layout Itemize
1682 Syntax: none gui.adjust_transparency(PALETTE obj, number adj)
1683 \end_layout
1684
1685 \begin_layout Standard
1686 Multiply alpha channel of <obj> by <adj>/256.
1687  Useful for making
1688 \begin_inset Quotes eld
1689 \end_inset
1690
1691 ghosts
1692 \begin_inset Quotes erd
1693 \end_inset
1694
1695  out of solid bitmaps.
1696 \end_layout
1697
1698 \begin_layout Subsection
1699 gui.kill_frame: Kill video frame and associated sound
1700 \end_layout
1701
1702 \begin_layout Itemize
1703 Syntax: none gui.kill_frame()
1704 \end_layout
1705
1706 \begin_layout Standard
1707 Kills the currently dumped video frame + the associated sound.
1708  Only valid in on_video callback.
1709 \end_layout
1710
1711 \begin_layout Subsection
1712 gui.arrow: Draw an arrow
1713 \end_layout
1714
1715 \begin_layout Itemize
1716 Syntax: none gui.arrow(number x, number y, number length, number hwidth,
1717  number direction[, bool fill[, number color[, number twidth[, number hthick]]]]
1718 )
1719 \end_layout
1720
1721 \begin_layout Standard
1722 Draws an arrow using color <color>.
1723  The tip of arrow is at (<x>, <y>).
1724  Other parameters:
1725 \end_layout
1726
1727 \begin_layout Enumerate
1728 <length>: The length of arrow tail.
1729 \end_layout
1730
1731 \begin_layout Enumerate
1732 <hwidth>: The width of arrow head.
1733  Should be odd.
1734 \end_layout
1735
1736 \begin_layout Enumerate
1737 <direction>: Direction of arrow.
1738  0 is to right, +1 rotates 45 degrees counterclockwise.
1739 \end_layout
1740
1741 \begin_layout Enumerate
1742 <fill>: If true, fill the arrow head.
1743  Default false.
1744 \end_layout
1745
1746 \begin_layout Enumerate
1747 <twidth>: Tail width.
1748  Should be odd.
1749  Default 1.
1750 \end_layout
1751
1752 \begin_layout Enumerate
1753 <hthick>: Head thickness (only used if <fill> is false).
1754  Default is <twidth>.
1755 \end_layout
1756
1757 \begin_layout Subsection
1758 gui.tilemap: Create a tilemap
1759 \end_layout
1760
1761 \begin_layout Itemize
1762 Syntax: TILEMAP gui.tilemap(number w, number h, number bw, number bh)
1763 \end_layout
1764
1765 \begin_layout Standard
1766 Create a new tilemap of size <w>*<h>, with each cell being <bw>*<bh>.
1767 \end_layout
1768
1769 \begin_layout Subsection
1770 TILEMAP:getsize: Query tilemap size
1771 \end_layout
1772
1773 \begin_layout Itemize
1774 Syntax: number, number TILEMAP:getsize()
1775 \end_layout
1776
1777 \begin_layout Standard
1778 Return size of tilemap (width first).
1779 \end_layout
1780
1781 \begin_layout Subsection
1782 TILEMAP:getcsize: Query tilemap cell size
1783 \end_layout
1784
1785 \begin_layout Itemize
1786 Syntax: number, number TILEMAP:getcsize()
1787 \end_layout
1788
1789 \begin_layout Standard
1790 Return size of tilemap cell (width first).
1791 \end_layout
1792
1793 \begin_layout Subsection
1794 TILEMAP:get: Query tilemap cell
1795 \end_layout
1796
1797 \begin_layout Itemize
1798 Syntax: none TILEMAP:get(number x, number y)
1799 \end_layout
1800
1801 \begin_layout Itemize
1802 Syntax: dbitmap TILEMAP:get(number x, number y)
1803 \end_layout
1804
1805 \begin_layout Itemize
1806 Syntax: bitmap,palette TILEMAP:get(number x, number y)
1807 \end_layout
1808
1809 \begin_layout Standard
1810 Return contents of cell at <x>,<y>.
1811 \end_layout
1812
1813 \begin_layout Subsection
1814 TILEMAP:set: Set tilemap cell
1815 \end_layout
1816
1817 \begin_layout Itemize
1818 Syntax: none TILEMAP:set(number x, number y)
1819 \end_layout
1820
1821 \begin_layout Itemize
1822 Syntax: none TILEMAP:set(number x, number y, dbitmap b)
1823 \end_layout
1824
1825 \begin_layout Itemize
1826 Syntax: none TILEMAP:set(number x, number y, bitmap b, palette p)
1827 \end_layout
1828
1829 \begin_layout Standard
1830 Set contents of cell at <x>,<y>.
1831  If no bitmap/dbitmap is given, cell is cleared.
1832  Otherwise specified (d)bitmap is used (with specified palette if bitmap).
1833 \end_layout
1834
1835 \begin_layout Subsection
1836 TILEMAP:scroll: Scroll tilemap
1837 \end_layout
1838
1839 \begin_layout Itemize
1840 Syntax: none TILEMAP:scroll(number ox, number oy)
1841 \end_layout
1842
1843 \begin_layout Itemize
1844 Syntax: none TILEMAP:scroll(number ox, number oy, number x, number y, number
1845  w, number h)
1846 \end_layout
1847
1848 \begin_layout Itemize
1849 Syntax: none TILEMAP:scroll(number ox, number oy, number x, number y, number
1850  w, number h, boolean circx, boolean circy)
1851 \end_layout
1852
1853 \begin_layout Standard
1854 Scrolls the tilemap tiles by <ox>,<oy>.
1855  If <x>,<y>,<w>,<h> is specified, the scrolling is limited to <w>*<h> window
1856  starting at <x>,<y> (in tiles).
1857 \end_layout
1858
1859 \begin_layout Standard
1860 If <circx> is true, the window is circular in horizontal direction.
1861  Similarly with <circy> and vertical direciton.
1862 \end_layout
1863
1864 \begin_layout Subsection
1865 TILEMAP:draw: Draw tilemap
1866 \end_layout
1867
1868 \begin_layout Itemize
1869 Syntax: none TILEMAP:draw(number x, number y)
1870 \end_layout
1871
1872 \begin_layout Itemize
1873 Syntax: none TILEMAP:draw(number x, number y, number x0, number y0)
1874 \end_layout
1875
1876 \begin_layout Itemize
1877 Syntax: none TILEMAP:draw(number x, number y, number x0, number y0, number
1878  w, number h)
1879 \end_layout
1880
1881 \begin_layout Standard
1882 Draw tilemap at <x>,<y>.
1883  If <x0>,<y0> is given, that is tilemap coordinate (in pixels) of upper
1884  left edge.
1885  If <w>,<h> is given, that is the size of window to draw (in pixels)
1886 \end_layout
1887
1888 \begin_layout Subsection
1889 gui.bitmap_save_png: Save a bitmap to PNG
1890 \end_layout
1891
1892 \begin_layout Itemize
1893 Syntax: none gui.bitmap_save_png(string filename[, string base], BITMAP bmp,
1894  PALETTE pal)
1895 \end_layout
1896
1897 \begin_layout Itemize
1898 Syntax: none gui.bitmap_save_png(string filename[, string base], DBITMAP
1899  bmp)
1900 \end_layout
1901
1902 \begin_layout Itemize
1903 Syntax: string gui.bitmap_save_png(BITMAP bmp, PALETTE pal)
1904 \end_layout
1905
1906 \begin_layout Itemize
1907 Syntax: string gui.bitmap_save_png(DBITMAP bmp)
1908 \end_layout
1909
1910 \begin_layout Standard
1911 Save specified bitmap <bmp>, with palette <pal> (only if paletted) into
1912  PNG file <filename> (relative to <base>) or return BASE64 encoding as return
1913  value.
1914 \end_layout
1915
1916 \begin_layout Subsection
1917 gui.bitmap_hash: Hash a bitmap
1918 \end_layout
1919
1920 \begin_layout Itemize
1921 Syntax: string gui.bitmap_hash(BITMAP bmp)
1922 \end_layout
1923
1924 \begin_layout Itemize
1925 Syntax: string gui.bitmap_hash(DBITMAP bmp)
1926 \end_layout
1927
1928 \begin_layout Standard
1929 Hashes bitmap <bmp> and returns 64-hex digit crypto-strong hash.
1930  Identical bitmaps result in indentical hashes (but color order in indexed
1931  bitmaps is significant).
1932 \end_layout
1933
1934 \begin_layout Subsection
1935 gui.palette_hash: Hash a palette
1936 \end_layout
1937
1938 \begin_layout Itemize
1939 Syntax: string gui.palette_hash(PALETTE pal)
1940 \end_layout
1941
1942 \begin_layout Standard
1943 Hashes palette <pal> and retruns 64-hex digit crypto-strong hash.
1944  Identical palettes result in identical hashes (fully transparent colors
1945  at end of palette don't affect the hash).
1946 \end_layout
1947
1948 \begin_layout Standard
1949 \begin_inset Newpage pagebreak
1950 \end_inset
1951
1952
1953 \end_layout
1954
1955 \begin_layout Section
1956 table input
1957 \end_layout
1958
1959 \begin_layout Standard
1960 Input handling.
1961  Functions manipulating input are only available in on_input callback.
1962 \end_layout
1963
1964 \begin_layout Subsection
1965 input.get: Read controller button/axis (deprecated)
1966 \end_layout
1967
1968 \begin_layout Itemize
1969 Syntax: number input.get(number controller, number index)
1970 \end_layout
1971
1972 \begin_layout Standard
1973 Read the specified index <index> (zero-based) from specified controller
1974  <controller> (zero-based).
1975
1976 \end_layout
1977
1978 \begin_layout Subsection
1979 input.set: Write controller button/axis (deprecated)
1980 \end_layout
1981
1982 \begin_layout Itemize
1983 Syntax: none input.set(number controller, number index, number value)
1984 \end_layout
1985
1986 \begin_layout Standard
1987 Write the specified index <index> (zero-based) from specified controller
1988  <controller> (zero-based), storing value <value>.
1989 \end_layout
1990
1991 \begin_layout Subsection
1992 input.get2: Read controller button/axis
1993 \end_layout
1994
1995 \begin_layout Itemize
1996 Syntax: number input.get2(number port, number controller, number index)
1997 \end_layout
1998
1999 \begin_layout Standard
2000 Read the specified input tuple.
2001  Port 0 is system port.
2002 \end_layout
2003
2004 \begin_layout Subsection
2005 input.set2: Write controller button/axis
2006 \end_layout
2007
2008 \begin_layout Itemize
2009 Syntax: input.set2(number port, number controller, number index, number value)
2010 \end_layout
2011
2012 \begin_layout Standard
2013 Write the specified input tuple.
2014  Port 0 is system port.
2015 \end_layout
2016
2017 \begin_layout Subsection
2018 input.lcid_to_pcid2: Look up logical controller
2019 \end_layout
2020
2021 \begin_layout Itemize
2022 Syntax: (number, number) input.lcid_to_pcid2(number lcid)
2023 \end_layout
2024
2025 \begin_layout Standard
2026 Look up physical pcid pair (port, controller) corresponding to specified
2027  logical controller (1-based).
2028  Returns nothing if controller does not exist.
2029 \end_layout
2030
2031 \begin_layout Subsection
2032 input.port_type: Look up port type
2033 \end_layout
2034
2035 \begin_layout Itemize
2036 Syntax: string input.port_type(number port)
2037 \end_layout
2038
2039 \begin_layout Standard
2040 Return type of specified port.
2041 \end_layout
2042
2043 \begin_layout Subsection
2044 input.controller_info: Get information about controller
2045 \end_layout
2046
2047 \begin_layout Itemize
2048 Syntax: table input.controller_info(number port, number controller)
2049 \end_layout
2050
2051 \begin_layout Standard
2052 Get controller info for specified controller.
2053  If controller does not exist, returns nil.
2054  Otherwise returns a table with following fields:
2055 \end_layout
2056
2057 \begin_layout Itemize
2058 type (string): Type of the controller.
2059 \end_layout
2060
2061 \begin_layout Itemize
2062 class (string): Class of the controller.
2063 \end_layout
2064
2065 \begin_layout Itemize
2066 classnum (number): Number of the controller within its class (1-based)
2067 \end_layout
2068
2069 \begin_layout Itemize
2070 lcid (number): Logical controller number of the controller.
2071 \end_layout
2072
2073 \begin_layout Itemize
2074 button_count (number): Number of buttons on controller
2075 \end_layout
2076
2077 \begin_layout Itemize
2078 buttons (array): Array of following info about each button:
2079 \end_layout
2080
2081 \begin_deeper
2082 \begin_layout Itemize
2083 type (string): Type of button.
2084  Currently one of
2085 \begin_inset Quotes eld
2086 \end_inset
2087
2088 null
2089 \begin_inset Quotes erd
2090 \end_inset
2091
2092 ,
2093 \begin_inset Quotes eld
2094 \end_inset
2095
2096 button
2097 \begin_inset Quotes erd
2098 \end_inset
2099
2100 ,
2101 \begin_inset Quotes eld
2102 \end_inset
2103
2104 axis
2105 \begin_inset Quotes erd
2106 \end_inset
2107
2108 ,
2109 \begin_inset Quotes eld
2110 \end_inset
2111
2112 raxis
2113 \begin_inset Quotes erd
2114 \end_inset
2115
2116 .
2117 \end_layout
2118
2119 \begin_layout Itemize
2120 name (string): Name of button.
2121 \end_layout
2122
2123 \begin_layout Itemize
2124 symbol (string): Symbol of button.
2125  Only present for type
2126 \begin_inset Quotes eld
2127 \end_inset
2128
2129 button
2130 \begin_inset Quotes erd
2131 \end_inset
2132
2133 .
2134 \end_layout
2135
2136 \begin_layout Itemize
2137 hidden (boolean): True if hidden button.
2138
2139 \end_layout
2140
2141 \end_deeper
2142 \begin_layout Subsection
2143 input.veto_button: Veto a button press
2144 \end_layout
2145
2146 \begin_layout Itemize
2147 Syntax: none input.veto_button()
2148 \end_layout
2149
2150 \begin_layout Standard
2151 Signals that the button event should be vetoed.
2152  Only valid in on_button callback.
2153 \end_layout
2154
2155 \begin_layout Subsection
2156 input.geta: Get all buttons for controller (deprecated)
2157 \end_layout
2158
2159 \begin_layout Itemize
2160 Syntax: (number, number...) input.geta(number controller)
2161 \end_layout
2162
2163 \begin_layout Standard
2164 Get input state for entiere controller.
2165  Returns n return values.
2166 \end_layout
2167
2168 \begin_layout Itemize
2169 1st return value: Bitmask: bit i is set if i:th index is nonzero
2170 \end_layout
2171
2172 \begin_layout Itemize
2173 2nd- return value: value of i:th index.
2174 \end_layout
2175
2176 \begin_layout Subsection
2177 input.seta: Set all buttons for controller (deprecated)
2178 \end_layout
2179
2180 \begin_layout Itemize
2181 Syntax: none input.seta(number controller, number bitmask, number args...)
2182 \end_layout
2183
2184 \begin_layout Standard
2185 Set state for entiere controller.
2186  args is up to N values for indices (overriding values in bitmask if specified).
2187 \end_layout
2188
2189 \begin_layout Subsection
2190 input.controllertype: Get controller type (deprecated)
2191 \end_layout
2192
2193 \begin_layout Itemize
2194 syntax: string input.controllertype(number controller)
2195 \end_layout
2196
2197 \begin_layout Standard
2198 Get the type of controller as string.
2199 \end_layout
2200
2201 \begin_layout Subsection
2202 input.reset: Execute (delayed) reset
2203 \end_layout
2204
2205 \begin_layout Itemize
2206 Syntax: none input.reset([number cycles])
2207 \end_layout
2208
2209 \begin_layout Standard
2210 Execute reset.
2211  If <cycles> is greater than zero, do delayed reset.
2212  0 (or no value) causes immediate reset.
2213 \end_layout
2214
2215 \begin_layout Itemize
2216 Note: Only available with subframe flag false.
2217 \end_layout
2218
2219 \begin_layout Subsection
2220 input.raw: Return raw input data
2221 \end_layout
2222
2223 \begin_layout Itemize
2224 Syntax: table input.raw()
2225 \end_layout
2226
2227 \begin_layout Standard
2228 Returns table of tables of all available keys and axes.
2229  The first table is indexed by key name (platform-dependent!), and the inner
2230  table has the following fields:
2231 \end_layout
2232
2233 \begin_layout Itemize
2234 value: Last reported value for control
2235 \end_layout
2236
2237 \begin_deeper
2238 \begin_layout Itemize
2239 For keys: 1 for pressed, 0 for released.
2240 \end_layout
2241
2242 \begin_layout Itemize
2243 For axes: -32767...32767.
2244 \end_layout
2245
2246 \begin_layout Itemize
2247 For presure-sensitive buttons: 0...32767.
2248 \end_layout
2249
2250 \begin_layout Itemize
2251 For hats: Bitmask: 1=>Up, 2=>Right, 4=>Down, 8=>Left.
2252 \end_layout
2253
2254 \begin_layout Itemize
2255 For mouse: Coordinates relative to game area.
2256 \end_layout
2257
2258 \end_deeper
2259 \begin_layout Itemize
2260 ktype: Type of key (disabled, key, mouse, axis, hat, pressure).
2261 \end_layout
2262
2263 \begin_layout Subsection
2264 input.keyhook: Hook a key
2265 \end_layout
2266
2267 \begin_layout Itemize
2268 Syntax: none input.keyhook(string key, boolean state)
2269 \end_layout
2270
2271 \begin_layout Standard
2272 Requests that keyhook events to be sent for key <key> (<state>=true) or
2273  not sent (<state>=false).
2274 \end_layout
2275
2276 \begin_layout Subsection
2277 input.joyget: Get controls for controller
2278 \end_layout
2279
2280 \begin_layout Itemize
2281 Syntax: table input.joyget(number logical)
2282 \end_layout
2283
2284 \begin_layout Standard
2285 Returns table for current controls for specified logical controller <logical>.
2286  The names of fields vary by controller type.
2287 \end_layout
2288
2289 \begin_layout Itemize
2290 The buttons have the same name as those are referred to in other contexts
2291  in the emulator
2292 \end_layout
2293
2294 \begin_layout Itemize
2295 The analog axes are usually
2296 \begin_inset Quotes eld
2297 \end_inset
2298
2299 xaxis
2300 \begin_inset Quotes erd
2301 \end_inset
2302
2303  and
2304 \begin_inset Quotes eld
2305 \end_inset
2306
2307 yaxis
2308 \begin_inset Quotes erd
2309 \end_inset
2310
2311 .
2312 \end_layout
2313
2314 \begin_layout Itemize
2315 Each field is numeric or boolean depending on axis/button.
2316 \end_layout
2317
2318 \begin_layout Subsection
2319 input.joyset: Set controls for controller
2320 \end_layout
2321
2322 \begin_layout Itemize
2323 Syntax: none input.joyset(number controller, table controls)
2324 \end_layout
2325
2326 \begin_layout Standard
2327 Set the the state of specified controller to values specified in specified
2328  table.
2329 \end_layout
2330
2331 \begin_layout Itemize
2332 Each field can be boolean or number.
2333 \end_layout
2334
2335 \begin_layout Itemize
2336 Also, buttons allow strings, which cause value to be inverted.
2337 \end_layout
2338
2339 \begin_layout Subsection
2340 input.lcid_to_pcid: Look up logical controller (deprecated)
2341 \end_layout
2342
2343 \begin_layout Itemize
2344 Syntax: (number, number, number) input.lcid_to_pcid(number lcid)
2345 \end_layout
2346
2347 \begin_layout Standard
2348 Returns the legacy pcid for controller (or false if there isn't one), followed
2349  by pcid pair.
2350  Returns nothing if controller does not exist.
2351 \end_layout
2352
2353 \begin_layout Standard
2354 \begin_inset Newpage pagebreak
2355 \end_inset
2356
2357
2358 \end_layout
2359
2360 \begin_layout Section
2361 Table keyboard
2362 \end_layout
2363
2364 \begin_layout Standard
2365 Various keybinding-related functions
2366 \end_layout
2367
2368 \begin_layout Subsection
2369 keyboard.bind: Bind a key
2370 \end_layout
2371
2372 \begin_layout Itemize
2373 Syntax: none keyboard.bind(string mod, string mask, string key, string cmd)
2374 \end_layout
2375
2376 \begin_layout Standard
2377 Bind specified key with specified modifers to specified command.
2378 \end_layout
2379
2380 \begin_layout Subsection
2381 keyboard.unbind: Unbind a key
2382 \end_layout
2383
2384 \begin_layout Itemize
2385 Syntax: none keyboard.unbind(string mod, string mask, string key)
2386 \end_layout
2387
2388 \begin_layout Standard
2389 Unbind specified key with specified modifers.
2390 \end_layout
2391
2392 \begin_layout Subsection
2393 keyboard.alias: Set alias expansion
2394 \end_layout
2395
2396 \begin_layout Itemize
2397 Syntax: none keyboard.alias(string alias, string expansion)
2398 \end_layout
2399
2400 \begin_layout Standard
2401 Set expansion of given command.
2402 \end_layout
2403
2404 \begin_layout Standard
2405 \begin_inset Newpage pagebreak
2406 \end_inset
2407
2408
2409 \end_layout
2410
2411 \begin_layout Section
2412 Table subtitle
2413 \end_layout
2414
2415 \begin_layout Standard
2416 Subtitle handling
2417 \end_layout
2418
2419 \begin_layout Subsection
2420 subtitle.byindex: Look up start and length of subtitle by index
2421 \end_layout
2422
2423 \begin_layout Itemize
2424 Syntax: (number, number) subtitle.byindex(number i)
2425 \end_layout
2426
2427 \begin_layout Standard
2428 Read the frame and length of ith subtitle.
2429  Returns nothing if not present.
2430 \end_layout
2431
2432 \begin_layout Subsection
2433 subtitle.set: Write a subtitle
2434 \end_layout
2435
2436 \begin_layout Itemize
2437 Syntax: none subtitle.set(number f, number l, string txt)
2438 \end_layout
2439
2440 \begin_layout Standard
2441 Set the text of subtitle.
2442 \end_layout
2443
2444 \begin_layout Subsection
2445 subtitle.get: Read a subtitle
2446 \end_layout
2447
2448 \begin_layout Itemize
2449 Syntax: string subtitle.get(number f, number l)
2450 \end_layout
2451
2452 \begin_layout Standard
2453 Get the text of subtitle.
2454 \end_layout
2455
2456 \begin_layout Subsection
2457 subtitle.delete: Delete a subtitle
2458 \end_layout
2459
2460 \begin_layout Itemize
2461 Syntax: nonesubtitle.delete(number f, number l)
2462 \end_layout
2463
2464 \begin_layout Standard
2465 Delete specified subtitle.
2466 \end_layout
2467
2468 \begin_layout Standard
2469 \begin_inset Newpage pagebreak
2470 \end_inset
2471
2472
2473 \end_layout
2474
2475 \begin_layout Section
2476 Table hostmemory
2477 \end_layout
2478
2479 \begin_layout Standard
2480 Host memory handling (extra memory saved to savestates).
2481  Host memory starts empty.
2482 \end_layout
2483
2484 \begin_layout Itemize
2485 Reads out of range return false.
2486 \end_layout
2487
2488 \begin_layout Itemize
2489 Writes out of range extend the memory.
2490 \end_layout
2491
2492 \begin_layout Subsection
2493 hostmemory.read: Read byte from host memory
2494 \end_layout
2495
2496 \begin_layout Itemize
2497 Syntax: number hostmemory.read(number address)
2498 \end_layout
2499
2500 \begin_layout Standard
2501 Reads byte from hostmemory slot address <address>.
2502 \end_layout
2503
2504 \begin_layout Subsection
2505 hostmemory.write: Write byte to host memory
2506 \end_layout
2507
2508 \begin_layout Itemize
2509 Syntax: none hostmemory.write(number address, number value)
2510 \end_layout
2511
2512 \begin_layout Standard
2513 Writes hostmemory slot with value <value> 0-255.
2514 \end_layout
2515
2516 \begin_layout Subsection
2517 hostmemory.read{,s}{byte,{,h,d,q}word}: Read from host memory
2518 \end_layout
2519
2520 \begin_layout Itemize
2521 Syntax: number hostmemory.readbyte(number address)
2522 \end_layout
2523
2524 \begin_layout Itemize
2525 Syntax: number hostmemory.readsbyte(number address)
2526 \end_layout
2527
2528 \begin_layout Itemize
2529 Syntax: number hostmemory.readword(number address)
2530 \end_layout
2531
2532 \begin_layout Itemize
2533 Syntax: number hostmemory.readsword(number address)
2534 \end_layout
2535
2536 \begin_layout Itemize
2537 Syntax: number hostmemory.readhword(number address)
2538 \end_layout
2539
2540 \begin_layout Itemize
2541 Syntax: number hostmemory.readshword(number address)
2542 \end_layout
2543
2544 \begin_layout Itemize
2545 Syntax: number hostmemory.readdword(number address)
2546 \end_layout
2547
2548 \begin_layout Itemize
2549 Syntax: number hostmemory.readsdword(number address)
2550 \end_layout
2551
2552 \begin_layout Itemize
2553 Syntax: number hostmemory.readqword(number address)
2554 \end_layout
2555
2556 \begin_layout Itemize
2557 Syntax: number hostmemory.readsqword(number address)
2558 \end_layout
2559
2560 \begin_layout Standard
2561 Read elements (big-endian) from given address <address>.
2562 \end_layout
2563
2564 \begin_layout Itemize
2565 byte is 1 element
2566 \end_layout
2567
2568 \begin_layout Itemize
2569 word is 2 elements
2570 \end_layout
2571
2572 \begin_layout Itemize
2573 hword is 3 elements
2574 \end_layout
2575
2576 \begin_layout Itemize
2577 dword is 4 elements
2578 \end_layout
2579
2580 \begin_layout Itemize
2581 qword is 8 elements.
2582 \end_layout
2583
2584 \begin_layout Itemize
2585 The 's' variants do signed read.
2586 \end_layout
2587
2588 \begin_layout Subsection
2589 hostmemory.read{float,double}: Read from host memory
2590 \end_layout
2591
2592 \begin_layout Itemize
2593 syntax: number hostmemory.readfloat(number address)
2594 \end_layout
2595
2596 \begin_layout Itemize
2597 Syntax: number hostmemory.readdouble(number address)
2598 \end_layout
2599
2600 \begin_layout Standard
2601 Read elements (big-endian) floating-pont from given address <address>.
2602 \end_layout
2603
2604 \begin_layout Subsection
2605 hostmemory.write{,s}{byte,{,h,d,q}word}: Write to host memory
2606 \end_layout
2607
2608 \begin_layout Itemize
2609 Syntax: number hostmemory.writebyte(number address, number value)
2610 \end_layout
2611
2612 \begin_layout Itemize
2613 Syntax: number hostmemory.writesbyte(number address, number value)
2614 \end_layout
2615
2616 \begin_layout Itemize
2617 Syntax: number hostmemory.writeword(number address, number value)
2618 \end_layout
2619
2620 \begin_layout Itemize
2621 Syntax: number hostmemory.writesword(number address, number value)
2622 \end_layout
2623
2624 \begin_layout Itemize
2625 Syntax: number hostmemory.writehword(number address, number value)
2626 \end_layout
2627
2628 \begin_layout Itemize
2629 Syntax: number hostmemory.writeshword(number address, number value)
2630 \end_layout
2631
2632 \begin_layout Itemize
2633 Syntax: number hostmemory.writedword(number address, number value)
2634 \end_layout
2635
2636 \begin_layout Itemize
2637 Syntax: number hostmemory.writesdword(number address, number value)
2638 \end_layout
2639
2640 \begin_layout Itemize
2641 Syntax: number hostmemory.writeqword(number address, number value)
2642 \end_layout
2643
2644 \begin_layout Itemize
2645 Syntax: number hostmemory.writesqword(number address, number value)
2646 \end_layout
2647
2648 \begin_layout Standard
2649 Write value <value> to elements (little-endian) starting from given address
2650  <address>.
2651 \end_layout
2652
2653 \begin_layout Itemize
2654 byte is 1 element
2655 \end_layout
2656
2657 \begin_layout Itemize
2658 word is 2 elements
2659 \end_layout
2660
2661 \begin_layout Itemize
2662 hword is 3 elements
2663 \end_layout
2664
2665 \begin_layout Itemize
2666 dword is 4 elements
2667 \end_layout
2668
2669 \begin_layout Itemize
2670 qword is 8 elements.
2671 \end_layout
2672
2673 \begin_layout Itemize
2674 The 's' variants do signed write.
2675 \end_layout
2676
2677 \begin_layout Subsection
2678 hostmemory.write{float,double}: Write to host memory
2679 \end_layout
2680
2681 \begin_layout Itemize
2682 syntax: none hostmemory.readfloat(number address, number value)
2683 \end_layout
2684
2685 \begin_layout Itemize
2686 Syntax: none hostmemory.readdouble(number address, number value)
2687 \end_layout
2688
2689 \begin_layout Standard
2690 Write elements (big-endian) floating-pont to given address <address>, storing
2691  <value>.
2692 \end_layout
2693
2694 \begin_layout Standard
2695 \begin_inset Newpage pagebreak
2696 \end_inset
2697
2698
2699 \end_layout
2700
2701 \begin_layout Section
2702 Table movie
2703 \end_layout
2704
2705 \begin_layout Standard
2706 Movie handling
2707 \end_layout
2708
2709 \begin_layout Subsection
2710 movie.currentframe: Get current frame number
2711 \end_layout
2712
2713 \begin_layout Itemize
2714 Syntax: number movie.currentframe()
2715 \end_layout
2716
2717 \begin_layout Standard
2718 Return number of current frame.
2719 \end_layout
2720
2721 \begin_layout Subsection
2722 movie.framecount: Get move frame count
2723 \end_layout
2724
2725 \begin_layout Itemize
2726 Syntax: number movie.framecount()
2727 \end_layout
2728
2729 \begin_layout Standard
2730 Return number of frames in movie.
2731 \end_layout
2732
2733 \begin_layout Subsection
2734 movie.readonly: Is in readonly mode?
2735 \end_layout
2736
2737 \begin_layout Itemize
2738 Syntax: boolean movie.readonly()
2739 \end_layout
2740
2741 \begin_layout Standard
2742 Return true if in readonly mode, false if in readwrite.
2743 \end_layout
2744
2745 \begin_layout Subsection
2746 movie.rerecords: Movie rerecord count
2747 \end_layout
2748
2749 \begin_layout Itemize
2750 Syntax: number movie.rerecords()
2751 \end_layout
2752
2753 \begin_layout Standard
2754 Returns the current value of rerecord count.
2755 \end_layout
2756
2757 \begin_layout Subsection
2758 movie.set_readwrite: Set read-write mode.
2759 \end_layout
2760
2761 \begin_layout Itemize
2762 Syntax: none movie.set_readwrite()
2763 \end_layout
2764
2765 \begin_layout Standard
2766 Set readwrite mode (does not cause on_readwrite callback).
2767 \end_layout
2768
2769 \begin_layout Subsection
2770 movie.frame_subframes: Count subframes in frame
2771 \end_layout
2772
2773 \begin_layout Itemize
2774 Syntax: number movie.frame_subframes(number frame)
2775 \end_layout
2776
2777 \begin_layout Standard
2778 Count number of subframes in specified frame <frame> (frame numbers are
2779  1-based) and return that.
2780 \end_layout
2781
2782 \begin_layout Subsection
2783 movie.read_subframes: Read subframe data (deprecated)
2784 \end_layout
2785
2786 \begin_layout Itemize
2787 Syntax: table movie.read_subframes(number frame, number subframe)
2788 \end_layout
2789
2790 \begin_layout Standard
2791 Read specifed subframe in specified frame and return data as array.
2792 \end_layout
2793
2794 \begin_layout Subsection
2795 movie.read_rtc: Read current RTC time
2796 \end_layout
2797
2798 \begin_layout Itemize
2799 Syntax: (number, number) movie.read_rtc()
2800 \end_layout
2801
2802 \begin_layout Standard
2803 Returns the current value of the RTC as a pair (second, subsecond).
2804 \end_layout
2805
2806 \begin_layout Subsection
2807 movie.unsafe_rewind: Fast movie rewind to saved state
2808 \end_layout
2809
2810 \begin_layout Itemize
2811 Syntax: none movie.unsafe_rewind([UNSAFEREWIND state])
2812 \end_layout
2813
2814 \begin_layout Standard
2815 Start setting point for unsafe rewind or jump to point of unsafe rewind.
2816 \end_layout
2817
2818 \begin_layout Itemize
2819 If called without argument, causes emulator to start process of setting
2820  unsafe rewind point.
2821  When this has finished, callback on_set_rewind occurs, passing the rewind
2822  state to lua script.
2823 \end_layout
2824
2825 \begin_layout Itemize
2826 If called with argument, causes emulator rewind to passed rewind point as
2827  soon as possible.
2828  Readwrite mode is implicitly activated.
2829 \end_layout
2830
2831 \begin_layout Standard
2832 The following warnings apply to unsafe rewinding:
2833 \end_layout
2834
2835 \begin_layout Itemize
2836 There are no safety checks against misuse (that's what
2837 \begin_inset Quotes eld
2838 \end_inset
2839
2840 unsafe
2841 \begin_inset Quotes erd
2842 \end_inset
2843
2844  comes from)!
2845 \end_layout
2846
2847 \begin_layout Itemize
2848 Only call rewind from timeline rewind point was set from.
2849 \end_layout
2850
2851 \begin_layout Itemize
2852 Only call rewind from after the rewind point was set.
2853 \end_layout
2854
2855 \begin_layout Subsection
2856 movie.to_rewind: Load savestate as rewind point
2857 \end_layout
2858
2859 \begin_layout Itemize
2860 Syntax: UNSAFEREWIND movie.to_rewind(string filename)
2861 \end_layout
2862
2863 \begin_layout Standard
2864 Load specified savestate file <filename> as rewind point and return UNSAFEREWIND
2865  corresponding to it.
2866 \end_layout
2867
2868 \begin_layout Itemize
2869 Note: This operation does not take emulated time.
2870 \end_layout
2871
2872 \begin_layout Subsection
2873 movie.copy_movie/INPUTMOVIE::copy_movie: Copy movie to movie object
2874 \end_layout
2875
2876 \begin_layout Itemize
2877 Syntax: INPUTMOVIE movie.copy_movie([INPUTMOVIE movie])
2878 \end_layout
2879
2880 \begin_layout Itemize
2881 Syntax: INPUTMOVIE INPUTMOVIE::copy_movie()
2882 \end_layout
2883
2884 \begin_layout Standard
2885 Copies specified movie <movie>/current object (if none or nil, the active
2886  movie) as new movie object.
2887 \end_layout
2888
2889 \begin_layout Subsection
2890 movie.get_frame/INPUTMOVIE::get_frame: Read specified frame in movie.
2891 \end_layout
2892
2893 \begin_layout Itemize
2894 Syntax: INPUTFRAME movie.get_frame([INPUTMOVIE movie,] number frame)
2895 \end_layout
2896
2897 \begin_layout Itemize
2898 Syntax: INPUTFRAME INPUTMOVIE::get_frame(number frame);
2899 \end_layout
2900
2901 \begin_layout Standard
2902 Get INPUTFRAME object corresponding to specified frame in specified movie.
2903 \end_layout
2904
2905 \begin_layout Subsection
2906 movie.set_frame/INPUTMOVIE::set_frame: Write speicifed frame in movie.
2907 \end_layout
2908
2909 \begin_layout Itemize
2910 Syntax: none movie.set_frame([INPUTMOVIE movie,] number frame, INPUTFRAME
2911  data)
2912 \end_layout
2913
2914 \begin_layout Itemize
2915 Syntax: none INPUTMOVIE::set_frame(number frame, INPUTFRAME data)
2916 \end_layout
2917
2918 \begin_layout Standard
2919 Set data in specified frame.
2920 \end_layout
2921
2922 \begin_layout Itemize
2923 Note: Past can't be edited in active movie.
2924 \end_layout
2925
2926 \begin_layout Subsection
2927 movie.get_size/INPUTMOVIE::get_size: Get size of movie
2928 \end_layout
2929
2930 \begin_layout Itemize
2931 Syntax: integer movie.get_size([INPUTMOVIE movie])
2932 \end_layout
2933
2934 \begin_layout Itemize
2935 Syntax: integer INPUTMOVIE::get_size()
2936 \end_layout
2937
2938 \begin_layout Standard
2939 Return number of subframes in specified movie.
2940 \end_layout
2941
2942 \begin_layout Subsection
2943 movie.count_frames/INPUTMOVIE::count_frames: Count frames in movie
2944 \end_layout
2945
2946 \begin_layout Itemize
2947 Syntax: number movie.count_frames([INPUTMOVIE movie])
2948 \end_layout
2949
2950 \begin_layout Itemize
2951 Syntax: number INPUTMOVIE::count_frames()
2952 \end_layout
2953
2954 \begin_layout Standard
2955 Return number of frames in movie.
2956 \end_layout
2957
2958 \begin_layout Subsection
2959 movie.find_frame/INPUTMOVIE::find_frame: Find subframe corresponding to frame
2960 \end_layout
2961
2962 \begin_layout Itemize
2963 Syntax: number movie.find_frame([INPUTMOVIE movie], number frame)
2964 \end_layout
2965
2966 \begin_layout Itemize
2967 Syntax: number INPUTMOVIE::find_frame(number frame)
2968 \end_layout
2969
2970 \begin_layout Standard
2971 Returns starting subframe of given frame (frame numbers are 1-based).
2972  Returns -1 if frame number is bad.
2973 \end_layout
2974
2975 \begin_layout Subsection
2976 movie.blank_frame/INPUTMOVIE::blank_frame: Return a blank frame
2977 \end_layout
2978
2979 \begin_layout Itemize
2980 Syntax: INPUTFRAME movie.blank_frame([INPUTMOVIE movie])
2981 \end_layout
2982
2983 \begin_layout Itemize
2984 Syntax: INPUTFRAME INPUTMOVIE::blank_frame()
2985 \end_layout
2986
2987 \begin_layout Standard
2988 Return blank INPUTFRAME with frame type from specified movie.
2989 \end_layout
2990
2991 \begin_layout Subsection
2992 movie.append_frames/INPUTMOVIE::append_frames: Append blank frames
2993 \end_layout
2994
2995 \begin_layout Itemize
2996 Syntax: none movie.append_frames([INPUTMOVIE movie,] number frames)
2997 \end_layout
2998
2999 \begin_layout Itemize
3000 Syntax: none INPUTMOVIE::append_frames(number frames)
3001 \end_layout
3002
3003 \begin_layout Standard
3004 Append specified number <frames> of frames.
3005 \end_layout
3006
3007 \begin_layout Subsection
3008 movie.append_frame/INPUTMOVIE::append_frame: Append a frame
3009 \end_layout
3010
3011 \begin_layout Itemize
3012 Syntax: none movie.append_frame([INPUTMOVIE movie,] INPUTFRAME frame)
3013 \end_layout
3014
3015 \begin_layout Itemize
3016 Syntax: none INPUTMOVIE::append_frame(INPUTFRAME frame)
3017 \end_layout
3018
3019 \begin_layout Standard
3020 Append specified frame <frame>.
3021  Past of current movie can't be edited.
3022 \end_layout
3023
3024 \begin_layout Subsection
3025 movie.truncate/INPUTMOVIE::truncate: Truncate a movie.
3026 \end_layout
3027
3028 \begin_layout Itemize
3029 Syntax: none movie.truncate([INPUTMOVIE movie,] number frames)
3030 \end_layout
3031
3032 \begin_layout Itemize
3033 Syntax: none INPUTMOVIE::truncate(number frames)
3034 \end_layout
3035
3036 \begin_layout Standard
3037 Truncate the specified movie to specified number of frames.
3038 \end_layout
3039
3040 \begin_layout Subsection
3041 movie.edit/INPUTMOVIE::edit: Edit a movie
3042 \end_layout
3043
3044 \begin_layout Itemize
3045 Syntax: none movie.edit([INPUTMOVIE movie,] number frame, number port, number
3046  controller, number control, number/bool value)
3047 \end_layout
3048
3049 \begin_layout Itemize
3050 Syntax: none INPUTMOVIE::edit(number frame, number port, number controller,
3051  number control, number/bool value)
3052 \end_layout
3053
3054 \begin_layout Standard
3055 Change specified control in specified frame in specified movie.
3056  Past can't be edited in active movie.
3057 \end_layout
3058
3059 \begin_layout Subsection
3060 movie.copy_frames2: Copy frames between movies
3061 \end_layout
3062
3063 \begin_layout Itemize
3064 Syntax: none movie.copy_frames2([INPUTMOVIE dstmov,] number dst, [INPUTMOVIE
3065  srcmov,] number src, number count)
3066 \end_layout
3067
3068 \begin_layout Standard
3069 Copy specified number of frames between two movies.
3070  The copy proceeeds in forward direction.
3071 \end_layout
3072
3073 \begin_layout Subsection
3074 movie.copy_frames/INPUTMOVIE::copy_frames: Copy frames in movie
3075 \end_layout
3076
3077 \begin_layout Itemize
3078 Syntax: none movie.copy_frames([INPUTMOVIE mov,] number dst, number src,
3079  number count, bool backwards)
3080 \end_layout
3081
3082 \begin_layout Itemize
3083 Syntax: none INPUTMOVIE::copy_frames(number dst, number src, number count,
3084  bool backwards)
3085 \end_layout
3086
3087 \begin_layout Standard
3088 Copy specified number of frames from one point in movie to another.
3089  If backwards is true, the copy will be done backwards.
3090 \end_layout
3091
3092 \begin_layout Subsection
3093 movie.serialize/INPUTMOVIE::serialize: Serialize movie
3094 \end_layout
3095
3096 \begin_layout Itemize
3097 Syntax: none movie.serialize([INPUTMOVIE movie,] string filename, bool binary)
3098 \end_layout
3099
3100 \begin_layout Itemize
3101 Syntax: none INPUTMOIVE::serialize(string filename, bool binary)
3102 \end_layout
3103
3104 \begin_layout Standard
3105 Serialize given movie into file.
3106  If binary is true, binary format (more compact and much faster) is used.
3107 \end_layout
3108
3109 \begin_layout Subsection
3110 movie.unserialize: Unserialize movie
3111 \end_layout
3112
3113 \begin_layout Itemize
3114 Syntax: INPUTMOVIE movie.unserialize(INPUTFRAME template, string filename,
3115  bool binary)
3116 \end_layout
3117
3118 \begin_layout Standard
3119 Unserialize movie from file.
3120  The given frame is used as template to decide the frame type.
3121  If binary is true, binary format is decoded (much faster).
3122 \end_layout
3123
3124 \begin_layout Subsection
3125 movie.current_first_subframe: Return first subframe in current frame
3126 \end_layout
3127
3128 \begin_layout Itemize
3129 Syntax: number movie.current_first_subframe()
3130 \end_layout
3131
3132 \begin_layout Standard
3133 Returns first subframe in current frame.
3134 \end_layout
3135
3136 \begin_layout Subsection
3137 movie.pollcounter: Return poll counter for speified control
3138 \end_layout
3139
3140 \begin_layout Itemize
3141 Syntax: number movie.pollcounter(number port, number controller, number control)
3142 \end_layout
3143
3144 \begin_layout Standard
3145 Returns number of times the specified control has been polled this frame.
3146 \end_layout
3147
3148 \begin_layout Subsection
3149 INPUTFRAME::get_button: Get button
3150 \end_layout
3151
3152 \begin_layout Itemize
3153 Syntax: boolean INPUTFRAME::get_button(number port, number controller, number
3154  control)
3155 \end_layout
3156
3157 \begin_layout Standard
3158 Returns state of given button as boolean.
3159 \end_layout
3160
3161 \begin_layout Subsection
3162 INPUTFRAME::get_axis: Get axis
3163 \end_layout
3164
3165 \begin_layout Itemize
3166 Syntax: number INPUTFRAME::get_axis(number port, number controller, number
3167  control)
3168 \end_layout
3169
3170 \begin_layout Standard
3171 Returns state of given axis as number.
3172 \end_layout
3173
3174 \begin_layout Subsection
3175 INPUTFRAME::set_button/INPUTFRAME::set_axis: Set button or axis
3176 \end_layout
3177
3178 \begin_layout Itemize
3179 Syntax: none INPUTFRAME::set_button(number port, number controller, number
3180  control, number/bool value)
3181 \end_layout
3182
3183 \begin_layout Itemize
3184 Syntax: none INPUTFRAME::set_axis(number port, number controller, number
3185  control)
3186 \end_layout
3187
3188 \begin_layout Standard
3189 Set the given button/axis to given value.
3190 \end_layout
3191
3192 \begin_layout Subsection
3193 INPUTFRAME::serialize: Serialize a frame
3194 \end_layout
3195
3196 \begin_layout Itemize
3197 Syntax: string INPUTFRAME::serialize()
3198 \end_layout
3199
3200 \begin_layout Standard
3201 Return string representation of frame.
3202 \end_layout
3203
3204 \begin_layout Subsection
3205 INPUTFRAME::unserialize: Unserialize a frame
3206 \end_layout
3207
3208 \begin_layout Itemize
3209 Syntax: none INPUTFRAME::unserialize(string data)
3210 \end_layout
3211
3212 \begin_layout Standard
3213 Set current frame from given data.
3214 \end_layout
3215
3216 \begin_layout Subsection
3217 INPUTFRAME::get_stride: Get movie stride
3218 \end_layout
3219
3220 \begin_layout Itemize
3221 Syntax: number INPUTFRAME::get_stride()
3222 \end_layout
3223
3224 \begin_layout Standard
3225 Return number of bytes needed to store the input frame.
3226  Mainly useful for some debugging.
3227 \end_layout
3228
3229 \begin_layout Standard
3230 \begin_inset Newpage pagebreak
3231 \end_inset
3232
3233
3234 \end_layout
3235
3236 \begin_layout Section
3237 Table settings
3238 \end_layout
3239
3240 \begin_layout Standard
3241 Routines for settings manipulation
3242 \end_layout
3243
3244 \begin_layout Subsection
3245 settings.get: Get value of setting
3246 \end_layout
3247
3248 \begin_layout Itemize
3249 Syntax: string settings.get(string name)
3250 \end_layout
3251
3252 \begin_layout Standard
3253 Get value of setting <name>.
3254  If setting value can't be obtained, returns (nil, error message).
3255 \end_layout
3256
3257 \begin_layout Subsection
3258 settings.set: Set value of setting
3259 \end_layout
3260
3261 \begin_layout Itemize
3262 Syntax: none settings.set(string name, string value)
3263 \end_layout
3264
3265 \begin_layout Standard
3266 Set value <value> of setting <name>.
3267  If setting can't be set, returns (nil, error message).
3268 \end_layout
3269
3270 \begin_layout Standard
3271 \begin_inset Newpage pagebreak
3272 \end_inset
3273
3274
3275 \end_layout
3276
3277 \begin_layout Section
3278 Table memory
3279 \end_layout
3280
3281 \begin_layout Standard
3282 Contains various functions for managing memory
3283 \end_layout
3284
3285 \begin_layout Subsection
3286 memory.vma_count: Count number of VMAs.
3287 \end_layout
3288
3289 \begin_layout Itemize
3290 Syntax: number memory.vma_count()
3291 \end_layout
3292
3293 \begin_layout Standard
3294 Returns the number of VMAs
3295 \end_layout
3296
3297 \begin_layout Subsection
3298 memory.read_vma: Lookup VMA info by index
3299 \end_layout
3300
3301 \begin_layout Itemize
3302 Syntax: string memory.read_vma(number index)
3303 \end_layout
3304
3305 \begin_layout Standard
3306 Reads the specified VMA (indices start from zero).
3307  Trying to read invalid VMA gives nil.
3308  The read VMA is table with the following fields:
3309 \end_layout
3310
3311 \begin_layout Itemize
3312 region_name (string): The readable name of the VMA
3313 \end_layout
3314
3315 \begin_layout Itemize
3316 baseaddr (number): Base address of the VMA
3317 \end_layout
3318
3319 \begin_layout Itemize
3320 lastaddr (number): Last address in the VMA.
3321 \end_layout
3322
3323 \begin_layout Itemize
3324 size (number): The size of VMA in bytes.
3325 \end_layout
3326
3327 \begin_layout Itemize
3328 readonly (boolean): True of the VMA corresponds to ROM.
3329 \end_layout
3330
3331 \begin_layout Itemize
3332 iospace (boolean): True if the VMA is I/O space.
3333 \end_layout
3334
3335 \begin_layout Itemize
3336 native_endian (boolean): True if the VMA has native endian as opposed to
3337  little endian.
3338 \end_layout
3339
3340 \begin_layout Subsection
3341 memory.find_vma: Find VMA info by address
3342 \end_layout
3343
3344 \begin_layout Itemize
3345 Syntax: table memory.find_vma(number address)
3346 \end_layout
3347
3348 \begin_layout Standard
3349 Finds the VMA containing specified address.
3350  Returns table in the same format as read_vma or nil if not found.
3351 \end_layout
3352
3353 \begin_layout Subsection
3354 memory.read{,s}{byte,{,h,d,q}word}: Read memory
3355 \end_layout
3356
3357 \begin_layout Itemize
3358 Syntax: none memory.readbyte([string vma, ]number address)
3359 \end_layout
3360
3361 \begin_layout Itemize
3362 Syntax: none memory.readword([string vma, ]number address)
3363 \end_layout
3364
3365 \begin_layout Itemize
3366 Syntax: none memory.readhword([string vma, ]number address)
3367 \end_layout
3368
3369 \begin_layout Itemize
3370 Syntax: none memory.readdword([string vma, ]number address)
3371 \end_layout
3372
3373 \begin_layout Itemize
3374 Syntax: none memory.readqword([string vma, ]number address)
3375 \end_layout
3376
3377 \begin_layout Itemize
3378 Syntax: none memory.readsbyte([string vma, ]number address)
3379 \end_layout
3380
3381 \begin_layout Itemize
3382 Syntax: none memory.readsword([string vma, ]number address)
3383 \end_layout
3384
3385 \begin_layout Itemize
3386 Syntax: none memory.readshword([string vma, ]number address)
3387 \end_layout
3388
3389 \begin_layout Itemize
3390 Syntax: none memory.readsdword([string vma, ]number address)
3391 \end_layout
3392
3393 \begin_layout Itemize
3394 Syntax: none memory.readsqword([string vma, ]number address)
3395 \end_layout
3396
3397 \begin_layout Standard
3398 Reads the specified address <address> (if 's' variant is used, do undergo
3399  2's complement).
3400 \end_layout
3401
3402 \begin_layout Subsection
3403 memory.{,s}read_sg: Scatter/Gather read memory
3404 \end_layout
3405
3406 \begin_layout Itemize
3407 Syntax: none memory.read_sg(string/boolean/number...)
3408 \end_layout
3409
3410 \begin_layout Itemize
3411 Syntax: none memory.sread_sg(string/boolean/number...)
3412 \end_layout
3413
3414 \begin_layout Standard
3415 Perform (2s complement signed if using memory.sread_sg) scatter/gather read
3416  of memory.
3417  Each argument can be string, boolean or number:
3418 \end_layout
3419
3420 \begin_layout Itemize
3421 String: Set VMA addresses are relative to (e.g.
3422  'WRAM').
3423 \end_layout
3424
3425 \begin_layout Itemize
3426 boolean: If true, increment relative address by 1, if false, decrement by
3427  1.
3428  The new address is read as next higher byte.
3429 \end_layout
3430
3431 \begin_layout Itemize
3432 integer: Set the relative address to specified value and read the address
3433  as next higher byte.
3434 \end_layout
3435
3436 \begin_layout Subsection
3437 memory.write_sg: Scatter/Gather write memory
3438 \end_layout
3439
3440 \begin_layout Itemize
3441 Syntax: none memory.write_sg(number value, string/boolean/number...)
3442 \end_layout
3443
3444 \begin_layout Standard
3445 Perform scatter/gather write of value <value> on memory.
3446  Each argument can be string, boolean or number:
3447 \end_layout
3448
3449 \begin_layout Itemize
3450 String: Set VMA addresses are relative to (e.g.
3451  'WRAM').
3452 \end_layout
3453
3454 \begin_layout Itemize
3455 boolean: If true, increment relative address by 1, if false, decrement by
3456  1.
3457  The new address is read as next higher byte.
3458 \end_layout
3459
3460 \begin_layout Itemize
3461 integer: Set the relative address to specified value and read the address
3462  as next higher byte.
3463 \end_layout
3464
3465 \begin_layout Subsection
3466 memory.read{float,double}: Read memory
3467 \end_layout
3468
3469 \begin_layout Itemize
3470 Syntax: none memory.readfloat([string vma, ]number address)
3471 \end_layout
3472
3473 \begin_layout Itemize
3474 Syntax: none memory.readdouble([string vma, ]number address)
3475 \end_layout
3476
3477 \begin_layout Standard
3478 Reads the specified address <address>
3479 \end_layout
3480
3481 \begin_layout Subsection
3482 memory.write{byte,{,h,d,q}word,float,double}: Write memory
3483 \end_layout
3484
3485 \begin_layout Itemize
3486 Syntax: none memory.writebyte([string vma, ]number address, number value)
3487 \end_layout
3488
3489 \begin_layout Itemize
3490 Syntax: none memory.writeword([string vma, ]number address, number value)
3491 \end_layout
3492
3493 \begin_layout Itemize
3494 Syntax: none memory.writehword([string vma, ]number address, number value)
3495 \end_layout
3496
3497 \begin_layout Itemize
3498 Syntax: none memory.writedword([string vma, ]number address, number value)
3499 \end_layout
3500
3501 \begin_layout Itemize
3502 Syntax: none memory.writeqword([string vma, ]number address, number value)
3503 \end_layout
3504
3505 \begin_layout Itemize
3506 Syntax: none memory.writefloat([string vma, ]number address, number value)
3507 \end_layout
3508
3509 \begin_layout Itemize
3510 Syntax: none memory.writedouble([string vma, ]number address, number value)
3511 \end_layout
3512
3513 \begin_layout Standard
3514 Writes the specified value <value> (negative integer values undergo 2's
3515  complement) to specified address <address>.
3516 \end_layout
3517
3518 \begin_layout Subsection
3519 memory.map{{,s}{byte,{,h,d,q}word},float,double}: Map an array
3520 \end_layout
3521
3522 \begin_layout Itemize
3523 Syntax: userdata memory.map<type>([[string vma, ]number base, number size])
3524 \end_layout
3525
3526 \begin_layout Standard
3527 Returns a table mapping specified memory aperture for read/write.
3528  If parameters are omitted, entiere map space is the aperture.
3529 \end_layout
3530
3531 \begin_layout Itemize
3532 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
3533  qword, sqword, float or double.
3534 \end_layout
3535
3536 \begin_layout Subsection
3537 memory.hash_region: Hash region of memory
3538 \end_layout
3539
3540 \begin_layout Itemize
3541 Syntax: string memory.hash_region([string vma, ]number base, number size)
3542 \end_layout
3543
3544 \begin_layout Standard
3545 Hash specified number of bytes starting from specified address and return
3546  the SHA-256.
3547 \end_layout
3548
3549 \begin_layout Subsection
3550 memory.hash_state: Hash system state
3551 \end_layout
3552
3553 \begin_layout Itemize
3554 Syntax: string memory.hash_state()
3555 \end_layout
3556
3557 \begin_layout Standard
3558 Hash the current system state.
3559  Mainly useful for debugging savestates.
3560 \end_layout
3561
3562 \begin_layout Subsection
3563 memory.readregion: Read region of memory
3564 \end_layout
3565
3566 \begin_layout Itemize
3567 Syntax: table memory.readregion([string vma, ]number base, number size)
3568 \end_layout
3569
3570 \begin_layout Standard
3571 Read a region of memory.
3572 \end_layout
3573
3574 \begin_layout Itemize
3575 Warning: If the region crosses VMA boundary, the results are undefined.
3576 \end_layout
3577
3578 \begin_layout Subsection
3579 memory.writeregion: Write region of memory
3580 \end_layout
3581
3582 \begin_layout Itemize
3583 Syntax: none memory.writeregion([string vma, ]number base, number size, table
3584  data)
3585 \end_layout
3586
3587 \begin_layout Standard
3588 Write a region of memory.
3589 \end_layout
3590
3591 \begin_layout Itemize
3592 Warning: If the region crosses VMA boundary, the results are undefined.
3593 \end_layout
3594
3595 \begin_layout Subsection
3596 memory.map_structure: Create mmap structure
3597 \end_layout
3598
3599 \begin_layout Itemize
3600 syntax: MMAP_STRUCT memory.map_structure()
3601 \end_layout
3602
3603 \begin_layout Standard
3604 Returns a new mapping structure (MMAP_STRUCT)
3605 \end_layout
3606
3607 \begin_layout Subsection
3608 MMAP_STRUCT(): Bind key in mmap structure
3609 \end_layout
3610
3611 \begin_layout Itemize
3612 Syntax: none MMAP_STRUCT(string key, [string vma, ]number address, string
3613  type)
3614 \end_layout
3615
3616 \begin_layout Standard
3617 Bind key <key> in mmap structure to specified address <address> with specified
3618  type <type>.
3619 \end_layout
3620
3621 \begin_layout Itemize
3622 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
3623  qword, sqword, float or double.
3624 \end_layout
3625
3626 \begin_layout Subsection
3627 memory.read_expr: Evaluate memory watch expression
3628 \end_layout
3629
3630 \begin_layout Itemize
3631 Syntax: string memory.read_expr(string expr)
3632 \end_layout
3633
3634 \begin_layout Standard
3635 Evaluate specified watch expression and return result
3636 \end_layout
3637
3638 \begin_layout Subsection
3639 memory.action: Run core action
3640 \end_layout
3641
3642 \begin_layout Itemize
3643 memory.action(string action, [<params>])
3644 \end_layout
3645
3646 \begin_layout Standard
3647 Run core action.
3648  The different models expect parameters as:
3649 \end_layout
3650
3651 \begin_layout Itemize
3652 string: String
3653 \end_layout
3654
3655 \begin_layout Itemize
3656 numeric: numeric
3657 \end_layout
3658
3659 \begin_layout Itemize
3660 enumeration: String
3661 \end_layout
3662
3663 \begin_layout Itemize
3664 boolean: String
3665 \end_layout
3666
3667 \begin_layout Itemize
3668 toggle: None.
3669 \end_layout
3670
3671 \begin_layout Subsection
3672 memory.get_lag_flag: Get lag flag
3673 \end_layout
3674
3675 \begin_layout Itemize
3676 Syntax: boolean memory.get_lag_flag()
3677 \end_layout
3678
3679 \begin_layout Standard
3680 Get the value of core lag flag.
3681  True if this frame has been lag so far, false if poll has been detected.
3682 \end_layout
3683
3684 \begin_layout Subsection
3685 memory.set_lag_flag: Set lag flag
3686 \end_layout
3687
3688 \begin_layout Itemize
3689 Syntax: none memory.set_lag_flag(boolean flag)
3690 \end_layout
3691
3692 \begin_layout Standard
3693 Set the value of core lag flag.
3694  This flag automatically gets cleared if poll is detected, but can be forcibly
3695  set or cleared if game so requires.
3696 \end_layout
3697
3698 \begin_layout Itemize
3699 Should only be used in on_frame_emulated callback.
3700 \end_layout
3701
3702 \begin_layout Itemize
3703 Setting or clearing this affects the emulator lag counter.
3704 \end_layout
3705
3706 \begin_layout Subsection
3707 memory.{,un}register{read,write,exec}: (Un)Register read / write / execute
3708  callback
3709 \end_layout
3710
3711 \begin_layout Itemize
3712 Syntax: function memory.registerread([string vma, ] number addr, function
3713  fn);
3714 \end_layout
3715
3716 \begin_layout Itemize
3717 Syntax: function memory.registerwrite([string vma, ] number addr, function
3718  fn);
3719 \end_layout
3720
3721 \begin_layout Itemize
3722 Syntax: function memory.registerexec([string vma, ] number addr, function
3723  fn);
3724 \end_layout
3725
3726 \begin_layout Itemize
3727 Syntax: none memory.unregisterread([string vma, ] number addr, function fn);
3728 \end_layout
3729
3730 \begin_layout Itemize
3731 Syntax: none memory.unregisterwrite([string vma, ] number addr, function
3732  fn);
3733 \end_layout
3734
3735 \begin_layout Itemize
3736 Syntax: none memory.unregisterexec([string vma, ] number addr, function fn);
3737 \end_layout
3738
3739 \begin_layout Standard
3740 Add or remove callback on memory read, write or execute (depending on the
3741  function).
3742  If <vma> is specified, <addr> is relative to it, otherwise <addr> is global.
3743  <fn> is the callback.
3744  The register* functions return <fn> (which can then be passed to unregister*
3745  functions.
3746 \end_layout
3747
3748 \begin_layout Itemize
3749 Not all cores support this, and it may be unsupported for some VMAs.
3750 \end_layout
3751
3752 \begin_layout Itemize
3753 The functions are passed two parameters: Address and value.
3754 \end_layout
3755
3756 \begin_layout Subsection
3757 memory.{,un}registertrace: Set/Clear trace hook
3758 \end_layout
3759
3760 \begin_layout Itemize
3761 Syntax: function memory.registertrace(number processor, function fn);
3762 \end_layout
3763
3764 \begin_layout Itemize
3765 Syntax: none memory.unregistertrace(number processor, function fn);
3766 \end_layout
3767
3768 \begin_layout Standard
3769 Add or remove trace callback.
3770  <processor> is system-dependent processor number (0 is usually main CPU).
3771  The function arguments work like in other (un)register* functions.
3772 \end_layout
3773
3774 \begin_layout Itemize
3775 The functions are passed two parameters: Trace CPU and Trace event string.
3776 \end_layout
3777
3778 \begin_layout Subsection
3779 memory.cheat: Set cheat
3780 \end_layout
3781
3782 \begin_layout Itemize
3783 Syntax: none memory.cheat([string vma, ] number addr, number value);
3784 \end_layout
3785
3786 \begin_layout Itemize
3787 Syntax: none memory.cheat([string vma, ] number addr);
3788 \end_layout
3789
3790 \begin_layout Standard
3791 Set or clear cheat (value <value>) on address <addr>.
3792  If <vma> is specified, <addr> is relative to that.
3793  If <value> is not speicified, clear a cheat.
3794 \end_layout
3795
3796 \begin_layout Itemize
3797 Not all cores support this, and it may be unsupported for some VMAs.
3798 \end_layout
3799
3800 \begin_layout Subsection
3801 memory.setxmask: Set global execute hook mask
3802 \end_layout
3803
3804 \begin_layout Itemize
3805 Syntax: none memory.setxmask(number mask)
3806 \end_layout
3807
3808 \begin_layout Standard
3809 Set the global execute hook mask to <mask>.
3810  The meaning of each bit is system-dependent, but bit 0 should be the main
3811  CPU.
3812 \end_layout
3813
3814 \begin_layout Standard
3815 \begin_inset Newpage pagebreak
3816 \end_inset
3817
3818
3819 \end_layout
3820
3821 \begin_layout Section
3822 Table memory2
3823 \end_layout
3824
3825 \begin_layout Standard
3826 Contains newer memory functions.
3827 \end_layout
3828
3829 \begin_layout Subsection
3830 memory2(): Get all VMA names.
3831 \end_layout
3832
3833 \begin_layout Itemize
3834 Syntax: table memory2()
3835 \end_layout
3836
3837 \begin_layout Standard
3838 Returns array of all valid VMA names.
3839 \end_layout
3840
3841 \begin_layout Subsection
3842 memory2.<vma>:info: Get VMA info
3843 \end_layout
3844
3845 \begin_layout Itemize
3846 Syntax: table memory2.<vma>:info()
3847 \end_layout
3848
3849 \begin_layout Standard
3850 Return table describing given VMA.
3851  Includes fields address, size, last, readonly, special and endian.
3852 \end_layout
3853
3854 \begin_layout Subsection
3855 memory2.<vma>:<op>: Read/Write memory
3856 \end_layout
3857
3858 \begin_layout Itemize
3859 Syntax: none memory2.<vma>:<op>(number offset, number value)
3860 \end_layout
3861
3862 \begin_layout Itemize
3863 Syntax: number memory2.<vma>:<op>(number offset)
3864 \end_layout
3865
3866 \begin_layout Standard
3867 Read/Write value from/to given VMA <vma> at given offset <offset> (must
3868  be in-range).
3869  The value written is <value>.
3870  <Op> is of form: [i][s]<type>, where:
3871 \end_layout
3872
3873 \begin_layout Itemize
3874 <type> is one of 'byte', 'word', 'hword', 'dword', 'qword', 'float', 'double'.
3875 \end_layout
3876
3877 \begin_layout Itemize
3878 'i' signifies that the value is treated as opposite-to-normal endianess,
3879 \end_layout
3880
3881 \begin_layout Itemize
3882 's' signifies that value is treated as signed (not available for floating-point).
3883 \end_layout
3884
3885 \begin_layout Subsection
3886 memory2.<vma>:read: Scatter-gather value read
3887 \end_layout
3888
3889 \begin_layout Itemize
3890 Syntax: number memory2.<vma>:read(number addr...)
3891 \end_layout
3892
3893 \begin_layout Standard
3894 Read value from given VMA <vma> at byte offsets <addr>..., given in order of
3895  increasing significance.
3896  Value of true and false are special.
3897  True increments address by 1, and false decrements address by 1.
3898 \end_layout
3899
3900 \begin_layout Subsection
3901 memory2.<vma>:sread: Signed scatter-gather value read
3902 \end_layout
3903
3904 \begin_layout Itemize
3905 Syntax: number memory2.<vma>:sread(number addr...)
3906 \end_layout
3907
3908 \begin_layout Standard
3909 Like memory2.<vma>:read, but reads signed values.
3910 \end_layout
3911
3912 \begin_layout Subsection
3913 memory2.<vma>:write: Scatter-gather value write
3914 \end_layout
3915
3916 \begin_layout Itemize
3917 Syntax: number memory2.<vma>:write(number val, number addr...)
3918 \end_layout
3919
3920 \begin_layout Standard
3921 Write value <val> to given VMA <vma> at byte offsets <addr>..., given in order
3922  of increasing significance.
3923  Value of true and false are special.
3924  True increments address by 1, and false decrements address by 1.
3925 \end_layout
3926
3927 \begin_layout Standard
3928 \begin_inset Newpage pagebreak
3929 \end_inset
3930
3931
3932 \end_layout
3933
3934 \begin_layout Section
3935 Table random
3936 \end_layout
3937
3938 \begin_layout Standard
3939 Contains random number generation methods.
3940  These functions do not return reproducable results.
3941 \end_layout
3942
3943 \begin_layout Subsection
3944 random.boolean: Random boolean
3945 \end_layout
3946
3947 \begin_layout Itemize
3948 Syntax: boolean random.boolean()
3949 \end_layout
3950
3951 \begin_layout Standard
3952 Returns true or false at random (50-50 chance).
3953 \end_layout
3954
3955 \begin_layout Subsection
3956 random.integer: Random integer
3957 \end_layout
3958
3959 \begin_layout Itemize
3960 Syntax: number random.integer(number highplusone)
3961 \end_layout
3962
3963 \begin_layout Itemize
3964 Syntax: number random.integer(number low, number high)
3965 \end_layout
3966
3967 \begin_layout Standard
3968 With one argument, return random integer [0,<highplusone>) (upper end exclusive).
3969  With two arguments, return random integer [<low>,<high>] (both ends inclusive).
3970 \end_layout
3971
3972 \begin_layout Standard
3973 The returned numbers are from uniform distribution.
3974 \end_layout
3975
3976 \begin_layout Subsection
3977 random.float: Random float
3978 \end_layout
3979
3980 \begin_layout Itemize
3981 Syntax: number random.float()
3982 \end_layout
3983
3984 \begin_layout Standard
3985 Returns random decimal number [0,1).
3986 \end_layout
3987
3988 \begin_layout Subsection
3989 random.among: Random parameter
3990 \end_layout
3991
3992 \begin_layout Itemize
3993 Syntax: value random.among(value values...)
3994 \end_layout
3995
3996 \begin_layout Standard
3997 Returns random parameter value, picked at uniform.
3998  Multiple equivalent values are returned with higher chance.
3999 \end_layout
4000
4001 \begin_layout Subsection
4002 random.amongtable: Random from table
4003 \end_layout
4004
4005 \begin_layout Itemize
4006 Syntax: value random.amongtable(table tab)
4007 \end_layout
4008
4009 \begin_layout Standard
4010 Returns random value from table <tab>.
4011  As in random.among, no equality testing is done.
4012 \end_layout
4013
4014 \begin_layout Standard
4015 \begin_inset Newpage pagebreak
4016 \end_inset
4017
4018
4019 \end_layout
4020
4021 \begin_layout Section
4022 Table zip
4023 \end_layout
4024
4025 \begin_layout Subsection
4026 zip.create: Create a new zipfile
4027 \end_layout
4028
4029 \begin_layout Itemize
4030 Syntax: ZIPWRITER zip.create(string filename[, number compression])
4031 \end_layout
4032
4033 \begin_layout Standard
4034 Creates a new zipfile <filename>, with specified compression level <compression>
4035  (default 9).
4036 \end_layout
4037
4038 \begin_layout Subsection
4039 zip.enumerate: Enumerate members in zipfile
4040 \end_layout
4041
4042 \begin_layout Itemize
4043 Syntax: Table zip.enumerate(string filename[, boolean invert])
4044 \end_layout
4045
4046 \begin_layout Standard
4047 Returns table of files in zip archive <filename>.
4048  If <invert> is true, instead of returning array of names, returns table
4049  with keys being member names and values being true.
4050 \end_layout
4051
4052 \begin_layout Subsection
4053 ZIPWRITER:commit: Finish creating ZIP file.
4054 \end_layout
4055
4056 \begin_layout Itemize
4057 Syntax: none ZIPWRITER:commit()
4058 \end_layout
4059
4060 \begin_layout Standard
4061 Closes the ZIP archive.
4062  Nothing more can be written.
4063 \end_layout
4064
4065 \begin_layout Subsection
4066 ZIPWRITER:rollback: Delete the ZIP file being creted
4067 \end_layout
4068
4069 \begin_layout Itemize
4070 Syntax: none ZIPWRITER:rollback()
4071 \end_layout
4072
4073 \begin_layout Standard
4074 Deletes the newly written ZIP archive.
4075  Nothing more can be written.
4076 \end_layout
4077
4078 \begin_layout Subsection
4079 ZIPWRITER:create_file: Start writing a new member
4080 \end_layout
4081
4082 \begin_layout Itemize
4083 Syntax: none ZIPWRITER:create_file(string filename)
4084 \end_layout
4085
4086 \begin_layout Standard
4087 Starts writing a new member <filename> in ZIP file.
4088  If member is open, it is closed.
4089 \end_layout
4090
4091 \begin_layout Subsection
4092 ZIPWRITER:close_file: Close member
4093 \end_layout
4094
4095 \begin_layout Itemize
4096 Syntax: none ZIPWRITER:close_file()
4097 \end_layout
4098
4099 \begin_layout Standard
4100 Closes member in ZIP file.
4101 \end_layout
4102
4103 \begin_layout Subsection
4104 ZIPWRITER:write: Write data
4105 \end_layout
4106
4107 \begin_layout Itemize
4108 Syntax none ZIPWRITER:write(string data)
4109 \end_layout
4110
4111 \begin_layout Standard
4112 Writes data <data> into ZIP file (binary mode).
4113 \end_layout
4114
4115 \begin_layout Standard
4116 \begin_inset Newpage pagebreak
4117 \end_inset
4118
4119
4120 \end_layout
4121
4122 \begin_layout Section
4123 Table callback
4124 \end_layout
4125
4126 \begin_layout Standard
4127 Various callback-related functions.
4128 \end_layout
4129
4130 \begin_layout Subsection
4131 \begin_inset CommandInset label
4132 LatexCommand label
4133 name "sub:callback.register:-Register-a"
4134
4135 \end_inset
4136
4137 callback.register: Register a callback
4138 \end_layout
4139
4140 \begin_layout Itemize
4141 Syntax: function callback.register(string cbname, function cbfun);
4142 \end_layout
4143
4144 \begin_layout Standard
4145 Instruct function <cbfun> to be added to list of callbacks to call on event
4146  <cbname> (See section
4147 \begin_inset CommandInset ref
4148 LatexCommand ref
4149 reference "sec:Callbacks"
4150
4151 \end_inset
4152
4153 ).
4154  The callback name does not have the 'on_' prefix (e.g.
4155
4156 \begin_inset Quotes eld
4157 \end_inset
4158
4159 paint
4160 \begin_inset Quotes erd
4161 \end_inset
4162
4163 ).
4164  Returns <cbfun>.
4165 \end_layout
4166
4167 \begin_layout Subsection
4168 \begin_inset CommandInset label
4169 LatexCommand label
4170 name "sub:callback.unregister:-Unregister-"
4171
4172 \end_inset
4173
4174 callback.unregister: Unregister a callback
4175 \end_layout
4176
4177 \begin_layout Itemize
4178 Syntax: function callback.unregister(string cbname, function cbfun);
4179 \end_layout
4180
4181 \begin_layout Standard
4182 Instruct function <cbfun> to be removed from list of callbacks to call on
4183  event <cbname>.
4184 \end_layout
4185
4186 \begin_layout Subsection
4187 callback.<cbname>:register: Register callback
4188 \end_layout
4189
4190 \begin_layout Itemize
4191 Syntax: function callback.<cbname>:register(function cbfun)
4192 \end_layout
4193
4194 \begin_layout Standard
4195 Synonym for callback.register (section
4196 \begin_inset CommandInset ref
4197 LatexCommand ref
4198 reference "sub:callback.register:-Register-a"
4199
4200 \end_inset
4201
4202 ), albeit with callback name specified differently.
4203 \end_layout
4204
4205 \begin_layout Subsection
4206 callback.<cbname>:unregister: Register callback
4207 \end_layout
4208
4209 \begin_layout Itemize
4210 Syntax: function callback.<cbname>:unregister(function cbfun)
4211 \end_layout
4212
4213 \begin_layout Standard
4214 Synonym for callback.unregister (section
4215 \begin_inset CommandInset ref
4216 LatexCommand ref
4217 reference "sub:callback.unregister:-Unregister-"
4218
4219 \end_inset
4220
4221 ), albeit with callback name specified differently.
4222 \end_layout
4223
4224 \begin_layout Section
4225 table bsnes
4226 \end_layout
4227
4228 \begin_layout Standard
4229 Various bsnes-specific functions.
4230 \end_layout
4231
4232 \begin_layout Subsection
4233 bsnes.dump_sprite: Dump a sprite
4234 \end_layout
4235
4236 \begin_layout Itemize
4237 Syntax: BITMAP bsnes.dump_sprite([string vma, ] number addr, number width,
4238  number height[, number stride])
4239 \end_layout
4240
4241 \begin_layout Standard
4242 Dumps given sprite (in native format) from memory.
4243  VMA is usually
4244 \begin_inset Quotes eld
4245 \end_inset
4246
4247 VRAM
4248 \begin_inset Quotes erd
4249 \end_inset
4250
4251 .
4252  <Width> and <height> are given in 8x8 blocks.
4253  <Stride> overrides row stride (default 512).
4254 \end_layout
4255
4256 \begin_layout Subsection
4257 bsnes.dump_palette: Dump a palette
4258 \end_layout
4259
4260 \begin_layout Itemize
4261 Syntax: PALETTE bsnes.dump_palette([string vma, ] number addr, bool full256,
4262  bool first_trans)
4263 \end_layout
4264
4265 \begin_layout Standard
4266 Dumps a palette from memory.
4267  VMA is usually
4268 \begin_inset Quotes eld
4269 \end_inset
4270
4271 CGRAM
4272 \begin_inset Quotes erd
4273 \end_inset
4274
4275 .
4276  If <full256> is true, 256 colors are dumped (otherwise 16).
4277  If <first_trans> is true, first color is forced transparent.
4278 \end_layout
4279
4280 \begin_layout Section
4281 Table _SYSTEM
4282 \end_layout
4283
4284 \begin_layout Standard
4285 Contains copy of global variables from time of Lua initialization.
4286  Non-writeable.
4287 \end_layout
4288
4289 \begin_layout Standard
4290 \begin_inset Newpage pagebreak
4291 \end_inset
4292
4293
4294 \end_layout
4295
4296 \begin_layout Section
4297 \begin_inset CommandInset label
4298 LatexCommand label
4299 name "sec:Callbacks"
4300
4301 \end_inset
4302
4303 Callbacks
4304 \end_layout
4305
4306 \begin_layout Standard
4307 Various callbacks to Lua that can occur.
4308 \end_layout
4309
4310 \begin_layout Subsection
4311 on_paint: Screen is being painted
4312 \end_layout
4313
4314 \begin_layout Itemize
4315 Callback: on_paint(bool not_synth)
4316 \end_layout
4317
4318 \begin_layout Standard
4319 Called when screen is being painted.
4320  Any gui.* calls requiring graphic context draw on the screen.
4321 \end_layout
4322
4323 \begin_layout Itemize
4324 not_synth is true if this hook is being called in response to received frame,
4325  false otherwise.
4326 \end_layout
4327
4328 \begin_layout Subsection
4329 on_video: Dumped video frame is being painted
4330 \end_layout
4331
4332 \begin_layout Itemize
4333 Callback: on_video()
4334 \end_layout
4335
4336 \begin_layout Standard
4337 Called when video dump frame is being painted.
4338  Any gui.* calls requiring graphic context draw on the video.
4339 \end_layout
4340
4341 \begin_layout Subsection
4342 on_frame_emulated: Frame emulation complete
4343 \end_layout
4344
4345 \begin_layout Itemize
4346 Callback: on_frame_emulated()
4347 \end_layout
4348
4349 \begin_layout Standard
4350 Called when emulating frame has completed and on_paint()/on_video() calls
4351  are about to be issued.
4352 \end_layout
4353
4354 \begin_layout Subsection
4355 on_frame: Frame emulation starting.
4356 \end_layout
4357
4358 \begin_layout Itemize
4359 Callback: on_frame()
4360 \end_layout
4361
4362 \begin_layout Standard
4363 Called on each starting whole frame.
4364 \end_layout
4365
4366 \begin_layout Subsection
4367 on_startup: Emulator startup complete
4368 \end_layout
4369
4370 \begin_layout Itemize
4371 Callback: on_startup()
4372 \end_layout
4373
4374 \begin_layout Standard
4375 Called when the emulator is starting (lsnes.rc and --run files has been run).
4376 \end_layout
4377
4378 \begin_layout Subsection
4379 on_rewind: Movie rewound to beginning
4380 \end_layout
4381
4382 \begin_layout Itemize
4383 Callback: on_rewind()
4384 \end_layout
4385
4386 \begin_layout Standard
4387 Called when rewind movie to beginning has completed.
4388 \end_layout
4389
4390 \begin_layout Subsection
4391 on_pre_load: Load operation is about to start
4392 \end_layout
4393
4394 \begin_layout Itemize
4395 Callback: on_pre_load(string name)
4396 \end_layout
4397
4398 \begin_layout Standard
4399 Called just before savestate/movie load occurs (note: loads are always delayed,
4400  so this occurs even when load was initiated by lua).
4401 \end_layout
4402
4403 \begin_layout Subsection
4404 on_err_Load: Load failed
4405 \end_layout
4406
4407 \begin_layout Itemize
4408 Callback: on_err_load(string name)
4409 \end_layout
4410
4411 \begin_layout Standard
4412 Called if loadstate goes wrong.
4413 \end_layout
4414
4415 \begin_layout Subsection
4416 on_post_load: Load completed
4417 \end_layout
4418
4419 \begin_layout Itemize
4420 Callback: on_post_load(string name, boolean was_savestate)
4421 \end_layout
4422
4423 \begin_layout Standard
4424 Called on successful loadstate.
4425  was_savestate gives if this was a savestate or a movie.
4426 \end_layout
4427
4428 \begin_layout Subsection
4429 on_pre_save: Save operation is about to start
4430 \end_layout
4431
4432 \begin_layout Itemize
4433 Callback: on_pre_save(string name, boolean is_savestate)
4434 \end_layout
4435
4436 \begin_layout Standard
4437 Called just before savestate save occurs (note: movie saves are synchronous
4438  and won't trigger these callbacks if called from Lua).
4439 \end_layout
4440
4441 \begin_layout Subsection
4442 on_err_save: Save failed
4443 \end_layout
4444
4445 \begin_layout Itemize
4446 Callback: on_err_save(string name)
4447 \end_layout
4448
4449 \begin_layout Standard
4450 Called if savestate goes wrong.
4451 \end_layout
4452
4453 \begin_layout Subsection
4454 on_post_save: Save completed
4455 \end_layout
4456
4457 \begin_layout Itemize
4458 Callback: on_post_save(string name, boolean is_savestate)
4459 \end_layout
4460
4461 \begin_layout Standard
4462 Called on successful savaestate.
4463  is_savestate gives if this was a savestate or a movie.
4464 \end_layout
4465
4466 \begin_layout Subsection
4467 on_quit: Emulator is shutting down
4468 \end_layout
4469
4470 \begin_layout Itemize
4471 Callback: on_quit()
4472 \end_layout
4473
4474 \begin_layout Standard
4475 Called when emulator is shutting down.
4476 \end_layout
4477
4478 \begin_layout Subsection
4479 on_input: Polling for input
4480 \end_layout
4481
4482 \begin_layout Standard
4483 Called when emulator is just sending input to bsnes core.
4484  Warning: This is called even in readonly mode, but the results are ignored.
4485 \end_layout
4486
4487 \begin_layout Subsection
4488 on_reset: System has been reset
4489 \end_layout
4490
4491 \begin_layout Itemize
4492 Callback: on_reset()
4493 \end_layout
4494
4495 \begin_layout Standard
4496 Called when system is reset.
4497 \end_layout
4498
4499 \begin_layout Subsection
4500 on_readwrite: Entered readwrite mode
4501 \end_layout
4502
4503 \begin_layout Itemize
4504 Callback: on_readwrite()
4505 \end_layout
4506
4507 \begin_layout Standard
4508 Called when moving into readwrite mode as result of
4509 \begin_inset Quotes eld
4510 \end_inset
4511
4512 set-rwmode
4513 \begin_inset Quotes erd
4514 \end_inset
4515
4516  command (note: moving to rwmode by Lua won't trigger this, as per recursive
4517  entry protection).
4518 \end_layout
4519
4520 \begin_layout Subsection
4521 on_snoop/on_snoop2: Snoop core controller reads
4522 \end_layout
4523
4524 \begin_layout Itemize
4525 Callback: on_snoop(number port, number controller, number index, number
4526  value)
4527 \end_layout
4528
4529 \begin_layout Itemize
4530 Callback: on_snoop2(number port, number controller, number index, number
4531  value)
4532 \end_layout
4533
4534 \begin_layout Standard
4535 Called each time bsnes asks for input.
4536  The value is the final value to be sent to bsnes core (readonly mode, autohold
4537  and autofire have been taken into account).
4538  Might be useful when translating movies to format suitable for console
4539  verification.
4540  Note: There is no way to modify the value to be sent.
4541 \end_layout
4542
4543 \begin_layout Itemize
4544 On_snoop2 is called instead of on_snoop if defined.
4545  Reserves port 0 for system, having first user port be port 1.
4546 \end_layout
4547
4548 \begin_layout Subsection
4549 on_keyhook: Hooked key/axis has been moved
4550 \end_layout
4551
4552 \begin_layout Itemize
4553 Callback: on_keyhook(string keyname, table state)
4554 \end_layout
4555
4556 \begin_layout Standard
4557 Sent when key that has keyhook events requested changes state.
4558  Keyname is name of the key (group) and state is the state (same kind as
4559  table values in input.raw).
4560 \end_layout
4561
4562 \begin_layout Subsection
4563 on_idle: Idle event
4564 \end_layout
4565
4566 \begin_layout Itemize
4567 Callback: on_idle()
4568 \end_layout
4569
4570 \begin_layout Standard
4571 Called when requested by set_idle_timeout(), the timeout has expired and
4572  emulator is waiting.
4573 \end_layout
4574
4575 \begin_layout Subsection
4576 on_timer: Timer event
4577 \end_layout
4578
4579 \begin_layout Itemize
4580 Callback: on_timer()
4581 \end_layout
4582
4583 \begin_layout Standard
4584 Called when requested by set_idle_timeout() and the timeout has expired
4585  (regardless if emulator is waiting).
4586 \end_layout
4587
4588 \begin_layout Subsection
4589 on_set_rewind: Rewind point has been set
4590 \end_layout
4591
4592 \begin_layout Itemize
4593 Callback: on_set_rewind(UNSAFEREWIND r)
4594 \end_layout
4595
4596 \begin_layout Standard
4597 Called when unsafe rewind object has been constructed.
4598 \end_layout
4599
4600 \begin_layout Subsection
4601 on_pre_rewind: Rewind is about to occur
4602 \end_layout
4603
4604 \begin_layout Itemize
4605 Callback: on_pre_rewind()
4606 \end_layout
4607
4608 \begin_layout Standard
4609 Called just before unsafe rewind is about to occur.
4610 \end_layout
4611
4612 \begin_layout Subsection
4613 on_post_rewind: Rewind has occured
4614 \end_layout
4615
4616 \begin_layout Itemize
4617 Callback: on_post_rewind()
4618 \end_layout
4619
4620 \begin_layout Standard
4621 Called just after unsafe rewind has occured.
4622 \end_layout
4623
4624 \begin_layout Subsection
4625 on_button: Button has been pressed
4626 \end_layout
4627
4628 \begin_layout Itemize
4629 Callback: on_button(number port, number controller, number index, string
4630  type)
4631 \end_layout
4632
4633 \begin_layout Standard
4634 Called on controller button press, with following parameters:
4635 \end_layout
4636
4637 \begin_layout Itemize
4638 port: Port number (0 is system)
4639 \end_layout
4640
4641 \begin_layout Itemize
4642 controller: Controller within port
4643 \end_layout
4644
4645 \begin_layout Itemize
4646 index: Index of button.
4647 \end_layout
4648
4649 \begin_layout Itemize
4650 type: Type of event, one of:
4651 \end_layout
4652
4653 \begin_deeper
4654 \begin_layout Itemize
4655 \begin_inset Quotes eld
4656 \end_inset
4657
4658 pressed
4659 \begin_inset Quotes erd
4660 \end_inset
4661
4662 : Button was pressed.
4663 \end_layout
4664
4665 \begin_layout Itemize
4666 \begin_inset Quotes eld
4667 \end_inset
4668
4669 released
4670 \begin_inset Quotes erd
4671 \end_inset
4672
4673 : Button was released.
4674 \end_layout
4675
4676 \begin_layout Itemize
4677 \begin_inset Quotes eld
4678 \end_inset
4679
4680 hold
4681 \begin_inset Quotes erd
4682 \end_inset
4683
4684 : Held.
4685 \end_layout
4686
4687 \begin_layout Itemize
4688 \begin_inset Quotes eld
4689 \end_inset
4690
4691 unhold
4692 \begin_inset Quotes erd
4693 \end_inset
4694
4695 : Released from hold.
4696 \end_layout
4697
4698 \begin_layout Itemize
4699 \begin_inset Quotes eld
4700 \end_inset
4701
4702 type
4703 \begin_inset Quotes erd
4704 \end_inset
4705
4706 : Typing input on button.
4707 \end_layout
4708
4709 \begin_layout Itemize
4710 \begin_inset Quotes eld
4711 \end_inset
4712
4713 untype
4714 \begin_inset Quotes erd
4715 \end_inset
4716
4717 : Typing input undone.
4718 \end_layout
4719
4720 \begin_layout Itemize
4721 \begin_inset Quotes eld
4722 \end_inset
4723
4724 autofire <duty> <cycle>
4725 \begin_inset Quotes erd
4726 \end_inset
4727
4728 : Autofire with specifie duty and cycle.
4729 \end_layout
4730
4731 \begin_layout Itemize
4732 \begin_inset Quotes eld
4733 \end_inset
4734
4735 autofire
4736 \begin_inset Quotes erd
4737 \end_inset
4738
4739 : Stop autofire.
4740 \end_layout
4741
4742 \begin_layout Itemize
4743 \begin_inset Quotes eld
4744 \end_inset
4745
4746 analog
4747 \begin_inset Quotes erd
4748 \end_inset
4749
4750 : Analog action on axis.
4751 \end_layout
4752
4753 \end_deeper
4754 \begin_layout Subsection
4755 on_movie_lost: Movie data is about to be lost
4756 \end_layout
4757
4758 \begin_layout Itemize
4759 Callback: on_movie_lost(STRING kind)
4760 \end_layout
4761
4762 \begin_layout Standard
4763 Called just before something would happen that could lose movie data.
4764  Kind can be:
4765 \end_layout
4766
4767 \begin_layout Itemize
4768 readwrite: Switching to readwrite mode.
4769 \end_layout
4770
4771 \begin_layout Itemize
4772 reload: ROM is being reloaded in readwrite mode.
4773 \end_layout
4774
4775 \begin_layout Itemize
4776 load: New movie is being loaded.
4777 \end_layout
4778
4779 \begin_layout Itemize
4780 unsaferewind: Unsafe rewind is happening.
4781 \end_layout
4782
4783 \begin_layout Subsection
4784 on_latch: Latch line is rising
4785 \end_layout
4786
4787 \begin_layout Itemize
4788 Callback: on_latch(<core-dependent-parameters>)
4789 \end_layout
4790
4791 \begin_layout Standard
4792 Called when latch line for controller is rising.
4793  Some cores may not support this.
4794 \end_layout
4795
4796 \begin_layout Section
4797 System-dependent behaviour
4798 \end_layout
4799
4800 \begin_layout Subsection
4801 bsnes core
4802 \end_layout
4803
4804 \begin_layout Itemize
4805 Registers are: pbpc, pb, pc, r0, r1, r2, r3, r4, r5, a, x, y, z, s, d, db,
4806  p, e, irq, wai, mdr, vector, aa, rd, sp, dp, p_n, p_v, p_m, p_x, p_d, p_i,
4807  p_z, p_c
4808 \end_layout
4809
4810 \begin_layout Itemize
4811 on_latch has no parameters
4812 \end_layout
4813
4814 \begin_layout Itemize
4815 CPU 0 is S-CPU, 1 is S-SMP.
4816 \end_layout
4817
4818 \begin_layout Itemize
4819 Cheats are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_{RAM,ROM}.
4820 \end_layout
4821
4822 \begin_layout Itemize
4823 Read/Write/Execute hooks are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_
4824 {RAM,ROM}.
4825 \end_layout
4826
4827 \begin_layout Subsection
4828 gambatte core
4829 \end_layout
4830
4831 \begin_layout Itemize
4832 Registers are: wrambank, cyclecounter, pc, sp, hf1, hf2, zf, cf, a, b, c,
4833  d, e, f, h, l
4834 \end_layout
4835
4836 \begin_layout Itemize
4837 on_latch is not supported
4838 \end_layout
4839
4840 \begin_layout Itemize
4841 CPU 0 is main CPU.
4842 \end_layout
4843
4844 \begin_layout Itemize
4845 Cheats are supported for ROM, SRAM and WRAM.
4846 \end_layout
4847
4848 \begin_layout Itemize
4849 Read/Write/Execute hooks are supported for ROM (read/execute only), SRAM
4850  and WRAM.
4851 \end_layout
4852
4853 \end_body
4854 \end_document