RGB2RTG 0.76-1 - every command, for the Shell
============================================

Everything RGB2RTG does can be done from a Shell with C:rgb2rtg - handy
without CaffeineOS, without Directory Opus or ToolsDaemon, or in scripts.
"C:rgb2rtg ?" shows the template:

  SYNC/S,CHECK/S,FIX/S,RESET/S,TEST/S,REPLAY/S,NOREPLAY/S,ON/S,OFF/S,
  ASK/S,IMAGE/S,ABOUT/S,APPLY/S,MENU/S,UNMENU/S,BEAM/S,CLOCK/S,PV/S,
  HDMISYNC/K,SYNCLOG/S,TRACE/S,INSTALL/K,UNINSTALL/K,HDMI50/S,FILE/K,
  TEXTTEST/S,WATCH/S,NOWATCH/S,XPOS/K/N,YPOS/K/N,SCANLINES/K/N,LACED/K/N,
  WINDOW/S,NOWINDOW/S,WINDOWTASK/S,GRAB/K/N,GRABSAVE/K,SMCREARM/S,VIDEO/K,
  TAKEOVER/K,BORDER/K/N,BORDERX/K/N,BORDERY/K/N,FLICKERFIX/K,BLITHOLD/K,
  COPTIME/K,COPHOLD/K,31KHZ/K,ECO/K,HDMIRATE/K,SYNCSTEADY/K,
  HDMICOLOURS=HDMICOLORS/K,WBMENU/K,BOOT/K,NOKERNEL/S,HDMISOUND/K,
  SHADOWREAD/K,BEAMHOOK/K,DEVOFF/K,CONVDELAY/K/N,FRAMESKIP/K,STORE/K,
  COPLATE/K,STREAM/K,LOWLAG/K,AHI/K,PAULA/K,SOUNDRATE/K,BRIGHTNESS/K/N,
  GAMMA/K,GAMESTART/S,GAMEEND/S,CPULOAD/S,SECONDS/K/N,SLEEP/K,
  LEDFILTER/K,SMCFLUSH/K,SCANSHAPE/K,MASK/K/N

/K words take a value: HDMISYNC=ON or HDMISYNC ON both work. /N values
are numbers: XPOS=-8.

WATCH, NOWATCH, GRAB and GRABSAVE are developers' words: they work with
a diagnostics build of the kernel only (this package's kernel says so
and does nothing). WINDOW, NOWINDOW and WINDOWTASK are an unfinished
experiment. Neither is described here.


1. EVERYDAY
-----------
 C:rgb2rtg ON              The Amiga's picture on HDMI when a native screen
                           is in front. Saved (ENV: and ENVARC:).
 C:rgb2rtg OFF             No Amiga picture: HDMI is black while a native
                           screen is in front (the RTG desktop still shows).
                           Saved.
 C:rgb2rtg VIDEO=NTSC      The standard the Amiga starts in, PAL or NTSC -
                           Settings' Video setting. Saved. config.txt is
                           set for the next power cycle: HDMI at 1080p 60
                           Hz (50 for PAL) when it sets a rate at all, and
                           when this is not the machine's own standard,
                           Emu68's ntsc or pal overlay (its file goes into
                           EMU68:overlays if missing). The picture's
                           framing (NTSC: 200 lines, another pixel shape)
                           follows the standard the Amiga started in.
 C:rgb2rtg HDMIRATE=2X     HDMI at twice the Amiga's rate: 1080p at 100 Hz
                           (120 for NTSC), every frame shown twice - for a
                           display that flickers at 50 Hz. 1X, the default,
                           is the Amiga's own rate, 50 or 60 Hz. Settings'
                           HDMI rate. Saved; config.txt is set for the next
                           power cycle. The display must take 1080p at 100
                           (120) Hz, or it shows nothing (README: IF
                           SOMETHING GOES WRONG). Not on a Pi 3: its HDMI
                           cannot send 1080p that fast.
 C:rgb2rtg HDMICOLOURS=LIMITED  The TV's limited colour range on HDMI (16-235),
                           for a TV that shows full range with crushed
                           blacks. FULL, the default, sends 0-255, as PC
                           monitors and DVI want. Settings' HDMI colours.
                           Saved; config.txt is set for the next power
                           cycle. HDMICOLORS works too.
 C:rgb2rtg HDMISYNC=ON     HDMI frames follow the Amiga's (with HDMI at the
                           Amiga's rate: every frame shown once). Saved.
 C:rgb2rtg HDMISYNC=OFF    HDMI keeps its own rate (a frame is repeated or
                           dropped every few seconds). Saved.
 C:rgb2rtg XPOS=-8 YPOS=2  Moves the picture on HDMI: XPOS right (minus:
                           left) in hires pixels, YPOS down (minus: up) in
                           lines, on top of the crop. How far it can go
                           depends on the crop - the command prints the
                           range. Either word alone changes only its own
                           direction. PAL and NTSC each keep their own
                           position: this sets the one of the standard
                           the Amiga runs in. Saved.
 C:rgb2rtg SCANLINES=2     Scanlines over the picture: 0 off, 1 to 4 = 25%,
                           50%, 75%, 100% dark. LACED=n sets the level for
                           interlaced screens. Either word alone changes
                           only its own. With RGB2RTG's VideoCore.card
                           (on a Pi 3 1.8). Saved.
 C:rgb2rtg SCANSHAPE=EVEN  Settings' Scanline shape: EVEN (the default)
                           gives every Amiga line the same darkness also
                           where it takes up no whole number of HDMI
                           lines (Scale 4:3, Fill screen) - a dark line
                           shared by two HDMI lines where it falls
                           between them; CRISP a whole dark HDMI line at
                           the end of each, some Amiga lines a line
                           taller. The same with the Integer scale.
                           WHOLE gives every Amiga line a whole number of
                           HDMI lines: the picture a little smaller, its
                           shape kept - clean scanlines at low resolutions
                           such as 800x600 (VideoCore.card 1.9).
                           With RGB2RTG's VideoCore.card 1.6 (on a Pi 3
                           1.8). Saved.
 C:rgb2rtg MASK=2          Settings' CRT mask: an aperture grille's fine
                           dark columns over the picture, like a
                           Trinitron or a PVM - 0 off, 1 to 4 = 25%,
                           50%, 75%, 100% dark. With the scanlines too.
                           It only darkens. With RGB2RTG's
                           VideoCore.card 1.7 (on a Pi 3 1.8). Saved.
 C:rgb2rtg BRIGHTNESS=2    Settings' Brightness: 0 normal (the default), 1 to
                           4 = 110%, 120%, 135%, 150% - for scanlines, which
                           darken the picture. Bright parts are eased into
                           white, not cut off. HDMI's picture only. Saved.
 C:rgb2rtg GAMMA=CRT       Settings' Gamma: EXACT (the default) the Amiga's
                           colours as they are; CRT the darker mid-tones
                           of a CRT such as the 1084S; LIGHTER shadows and
                           mid-tones lifted. HDMI's picture only. Saved.
 C:rgb2rtg BORDER=4        The TV border: every picture on HDMI - the RTG
                           desktop, the Amiga picture, the mouse pointer - 4%
                           smaller, centred, with a black frame (0 to 10;
                           0, the default, is off). For a TV that cuts the
                           edges of 1080p off. Settings' TV border. Saved.
 C:rgb2rtg BORDERY=6       The same, down only (BORDERX: across only), for a
                           TV that cuts more off the top and bottom than the
                           sides, or the other way round. Either word alone
                           changes only its own direction. The pictures keep
                           their shape, so they come out smaller the other
                           way too, where the other direction needs it. Saved.
 C:rgb2rtg FLICKERFIX=OFF  Interlaced screens a field at a time, as the
                           Amiga's own output shows them - they flicker, as
                           on a monitor without a flicker fixer. ON, the
                           default, weaves both fields into one steady
                           picture. Settings' Flicker fixer. Saved.
 C:rgb2rtg HDMISOUND=ON    The Amiga's sound on HDMI as well - the screen's
                           speakers, or an HDMI audio extractor - at once.
                           OFF, the default: not. The Amiga's own audio
                           outputs keep working either way. The desktop
                           menu's Sound, a window that also sets HDMI's
                           volume, stereo width and left/right (below:
                           hdmivolume=, hdmiwidth=, hdmiswap=);
                           HDMISOUND=ASK opens the same window.
                           Saved, and config.txt gets hdmi_drive=2 for the
                           next power cycle (HDMI mode, for a display that
                           would get DVI and no sound) - when the SD card's
                           boot partition is mounted; if not, it says so
                           (a warning, rc 5) and the rest is done. Plays
                           with the RGB2RTG kernel, 0.74 on; the status
                           report's "HDMI sound" says how it plays, or why
                           not.
 C:rgb2rtg PAULA=BANDLIMITED  Paula's sound on HDMI made from each step its
                           four channels make, with nothing folding back
                           as a metallic edge on bright sounds. CLASSIC,
                           the default: from the 28 kHz mix, resampled.
                           The Sound window's Paula. Saved; at once.
 C:rgb2rtg LEDFILTER=OFF   The A1200's LED filter never on HDMI. ON, the
                           default: Paula's sound on HDMI goes through it
                           whenever a program switches it on, as the
                           A1200's own outputs do - Kickstart switches it
                           on, many games and players off (the power LED's
                           signal; on some A1200s the LED dims with it).
                           The Sound window's LED filter. Saved; at once.
 C:rgb2rtg SOUNDRATE=SCREEN  HDMI sound's rate. SCREEN, the default: 48 kHz,
                           or an AHI program's own rate when the screen's
                           EDID lists it; ANY: every rate, whatever the
                           screen lists (some take more); 96 or 192: always
                           that, for everything. The Sound window's Rate.
                           Saved; at once.
 C:rgb2rtg AHI=ON          HiFi: programs that play through AHI play
                           straight on HDMI, in up to 24 bits and at their
                           own rate, also with HDMISOUND off - AHI's unit 0
                           and Music unit at "RGB2RTG HDMI:HiFi 24 bit
                           stereo++" (the driver the Installer puts in
                           DEVS:AHI when AHI is there). LOWLATENCY: the
                           same with "...stereo++ low latency", for games
                           - effects heard some 60 ms sooner; after a
                           stall of the Amiga (a window dragged, a disk
                           read) one short gap, then a safe margin for
                           10 s. OFF gives them their earlier modes back.
                           The Sound window's HiFi (AHI). Saved (ENV: and
                           ENVARC:).
 C:rgb2rtg ECO=OFF         The Amiga picture drawn all the time. ON, the
                           default, draws nothing while only the RTG desktop
                           is on HDMI - the Pi stays cooler - and starts again
                           the moment a game, demo or native screen comes to
                           the front. Settings' Eco mode. Saved.
 C:rgb2rtg 31KHZ=ON        31 kHz screen modes - DblPAL, DblNTSC, Multiscan
                           (Productivity), Euro72 and the like - followed and
                           shown on HDMI, sharp, with the mouse pointer. OFF,
                           the default, shows them black, as before. New, a
                           test for now; PAL and NTSC screens are the same
                           either way. Settings' VGA modes (31 kHz). Saved.
                           The kernel starts with them on, and a reboot
                           turns them on again, until APPLY sets what is
                           saved: Early Startup's 31 kHz menu on HDMI.
 C:rgb2rtg APPLY           Put the saved settings in force - what the line
                           in S:User-Startup does at every boot.
 C:rgb2rtg                 The status report (for bug reports).

2. WINDOWS (need Workbench)
---------------------------
 C:rgb2rtg ASK             The on/off requester (menu: RGB2RTG).
 C:rgb2rtg IMAGE           Settings: HDMI's, and the picture's - look,
                           crop, scale, scanlines, brightness, gamma... -
                           for all games or, with Settings for, one game's
                           own; Position... (the picture's position, on a
                           calibration screen). Changes show at once;
                           Save keeps them, Use keeps them until reboot,
                           Cancel puts back what was there.
 C:rgb2rtg ABOUT           Version and licences (menu: About).

3. THE MENU AND THE STARTUP LINE
--------------------------------
 C:rgb2rtg MENU            Adds the RGB2RTG title to the Directory Opus 5
                           user menu (if DOpus5: exists) and to
                           S:ToolsDaemon.menu (if it exists), and adds this
                           to S:User-Startup:
                             ;BEGIN RGB2RTG
                             If EXISTS C:rgb2rtg
                               C:rgb2rtg APPLY >NIL:
                             EndIf
                             ;END RGB2RTG
                           Each file is copied to *.pre-rgb2rtg first.
                           Without Directory Opus and ToolsDaemon only the
                           S:User-Startup block is added - that is all a
                           plain Workbench needs.
                           And at the top of S:WHDLoad-Startup and
                           S:WHDLoad-Cleanup, when they are there, a block
                           with GAMESTART and GAMEEND (below).
 C:rgb2rtg UNMENU          Takes all of it out again.
 C:rgb2rtg GAMESTART       For S:WHDLoad-Startup, which WHDLoad runs in the
                           game's drawer: that game is the one started last
                           (Settings for offers it), and if it has settings
                           of its own, they are put in force. Never fails.
 C:rgb2rtg GAMEEND         For S:WHDLoad-Cleanup: after a game with its own
                           settings, the all-games ones again.

4. INSTALLING BY HAND (what the installer uses)
------------------------------------------------
 C:rgb2rtg INSTALL CHECK   Looks at this Amiga and prints what it found:
                           PiStorm variant, Raspberry Pi, chipset, whether
                           the RGB2RTG kernel runs, the Emu68 boot partition
                           and whether it can be written, config.txt's
                           PiStorm32-lite sections, the video standard and
                           HDMI at its rate, unicam overlay - and a warning
                           for a dtoverlay= line that names Emu68's overlays
                           as another's settings (the Pi loads one overlay
                           a line: dtoverlay=sdhc,unit0=rw,unicam,boot
                           loads no unicam). It also says when
                           DEVS:Monitors has no VideoCore monitor (an icon
                           with BoardType=VideoCore or Emu68-VC4 -
                           Picasso96 starts the driver only through one),
                           or one that says DisplayChain=No; which driver
                           names the monitors use; and whether the monitor
                           needs VC4_LEGACY_ID for the screen modes made
                           with an older VideoCore driver (decided here,
                           before Install replaces the driver).
                           Also sets ENV: variables for scripts:
                             RGB2RTG_BOOT      the boot partition ("EMU68:")
                             RGB2RTG_PI        4, 3, 0 (other) or ?
                             RGB2RTG_PS32      1, 0 or ? (PiStorm32-lite)
                             RGB2RTG_AGA       1 or 0
                             RGB2RTG_WRITABLE  1 or 0
                             RGB2RTG_CONFIG    1 when config.txt has a
                                               PiStorm32-lite section
                             RGB2RTG_HDMI50    1 when HDMI is 1080p at the
                                               Amiga's rate (50 Hz; 60
                                               for NTSC)
                             RGB2RTG_BLK50     1 when RGB2RTG's block sets a rate
                             RGB2RTG_DTBO      1 when overlays/unicam.dtbo
                                               is there
                             RGB2RTG_NTSC      1 for NTSC (the Video
                                               setting, else the Amiga's)
                             RGB2RTG_HZ        50 or 60
                             RGB2RTG_BURIED    such a dtoverlay= line, or
                                               empty
                             RGB2RTG_DCHAIN    the VideoCore monitor icon
                                               when it says DisplayChain=No
                             RGB2RTG_VCMON     1 when DEVS:Monitors has a
                                               VideoCore monitor (an icon
                                               with BoardType=VideoCore
                                               or Emu68-VC4), 0 none,
                                               ? cannot tell
                             RGB2RTG_E68VC4    1 when a monitor's BoardType
                                               is Emu68-VC4 (the driver
                                               goes in as Emu68-VC4.card)
                             RGB2RTG_LEGACY    1 VC4_LEGACY_ID to be added,
                                               2 to be switched on, 0 not
                             RGB2RTG_SLOW      the Pi 4's SD card at 25 MHz:
                                               2 the card's own setting,
                                               1 RGB2RTG's emmc.low_speed,
                                               0 at 50 MHz
 C:rgb2rtg INSTALL MONITOR        The VideoCore monitor icons
                                   (DEVS:Monitors, BoardType VideoCore or
                                   Emu68-VC4): DisplayChain=No becomes Yes -
                                   Picasso96 hands HDMI to native screens
                                   only then - and VC4_LEGACY_ID is added
                                   or switched on as INSTALL CHECK decided
                                   (RGB2RTG_LEGACY; run alone it decides
                                   itself). A changed icon is kept first in
                                   DEVS:Monitors.pre-rgb2rtg; an older copy
                                   (<icon>.info.pre-rgb2rtg) is moved there.
 C:rgb2rtg UNINSTALL MONITOR       Puts those icons back (from both places).
 C:rgb2rtg UNINSTALL AHI           AHI's units off the RGB2RTG HDMI driver
                                   (their earlier modes back), and the
                                   driver and its modes out of DEVS:.
 C:rgb2rtg INSTALL CONFIG          Edits <boot partition>config.txt: the
                                   PiStorm32-lite's kernel= lines ([gpio24=0]
                                   and [gpio4=0]) point at
                                   kernel/Emu68-rgb2rtg.gz (the old lines stay
                                   as #RGB2RTG-WAS: comments), and a
                                   "# RGB2RTG begin/end" block adds
                                   dtoverlay=unicam,boot. Keeps a copy as
                                   config.txt.pre-rgb2rtg. Running it twice
                                   changes nothing the second time. Emu68's
                                   own config.txt (no [gpio24=0]): its
                                   kernel= line for the PiStorm32-lite is
                                   changed where it is, and the block goes
                                   at the end of the file.
 C:rgb2rtg INSTALL CONFIG HDMI50   The same, plus 1080p at the Amiga's rate
                                   in the block (60 Hz for NTSC, and Emu68's
                                   overlay when the Video setting is not the
                                   Amiga's own standard).
 ... LOWSPEED=ON                   And the Pi 4's SD card at 25 MHz instead
                                   of 50: emmc.low_speed at the end of the
                                   Emu68 command line (the cmdline.txt that
                                   config.txt names; the first copy kept as
                                   <file>.pre-rgb2rtg), which the RGB2RTG
                                   kernel reads, and a line in the block
                                   that says it was RGB2RTG. Some cards
                                   lose writes at 50 MHz on a Pi 4. A card
                                   that has low speed of its own is left as
                                   it is.
 ... LOWSPEED=OFF                  Takes RGB2RTG's emmc.low_speed out again.
                                   Without LOWSPEED= it stays as it is.
 C:rgb2rtg UNINSTALL CONFIG        Puts config.txt back, byte for byte, and
                                   takes RGB2RTG's emmc.low_speed out of the
                                   command line.
 ... FILE=<path>                   Works on another file instead, to try it
                                   out safely:
   Copy EMU68:config.txt RAM:
   C:rgb2rtg INSTALL CONFIG HDMI50 FILE=RAM:config.txt
   Type RAM:config.txt
 Return codes: 0 done (or nothing to do), 10 no PiStorm32-lite section,
 20 cannot read or write, or an RGB2RTG block without its end line.

 The whole install by hand, without the installer:
   1. copy Files/Kernel/Emu68-rgb2rtg.gz to <boot partition>kernel/
   2. copy Files/Overlays/unicam.dtbo to <boot partition>overlays/ if it
      is not there
   3. C:rgb2rtg INSTALL CONFIG HDMI50       (or without HDMI50)
   4. copy Files/Libs/Picasso96/VideoCore.card to LIBS:Picasso96/
      (keep your old one first)
   5. copy Files/C/rgb2rtg to C:
   6. C:rgb2rtg MENU                        (or only the S:User-Startup lines)
   7. C:rgb2rtg ON HDMISYNC=ON              (HDMISYNC=OFF without HDMI50)
   8. power cycle
 Without an Emu68 boot partition the Amiga can write to, do steps 1-3 on a
 PC: copy the files, and add to config.txt by hand - in the PiStorm32-lite
 section kernel=kernel/Emu68-rgb2rtg.gz, and in the global part
 dtoverlay=unicam,boot on a line of its own (and for 50 Hz hdmi_group=1,
 hdmi_mode=31, hdmi_force_mode=1; for NTSC's 60 Hz hdmi_group=2,
 hdmi_mode=82). The Pi loads one overlay a dtoverlay= line and takes the
 rest of the line as that overlay's settings, so unicam added to another
 overlay's line is not loaded.

 The whole uninstall by hand - what Uninstall does, for a system without
 the Installer (MultibootOS's AmigaOS 3.2 has none):
   1. C:rgb2rtg UNINSTALL CONFIG         (stop here if it fails)
   2. C:rgb2rtg UNMENU
   3. C:rgb2rtg UNINSTALL MONITOR
   4. C:rgb2rtg UNINSTALL AHI
   5. copy LIBS:Picasso96/VideoCore.card.pre-rgb2rtg over
      LIBS:Picasso96/VideoCore.card, then delete the copy (the same for
      Emu68-VC4.card.pre-rgb2rtg, if there is one)
   6. Delete ENVARC:RGB2RTG.prefs ENV:RGB2RTG.prefs ENVARC:RGB2RTG
      ENV:RGB2RTG ALL QUIET FORCE
   7. Delete C:rgb2rtg
   8. power cycle

5. FOR BUG REPORTS AND TESTING (need the RGB2RTG kernel)
---------------------------------------------------------
 C:rgb2rtg RESET           Clears the counters and the event trace. Do it
                           just before starting the game or demo.
 C:rgb2rtg TRACE           The kernel's event trace, raw (what happened
                           when). Save it to a file right after the game:
                             C:rgb2rtg TRACE >RAM:trace.txt
                           It is decoded on a PC: tools/rgb2rtg/trace.py in
                           the source.
 C:rgb2rtg SYNCLOG         The last 64 HDMI blanks HDMI sync followed.
 C:rgb2rtg CPULOAD         How busy the Amiga's CPU is, over 3 seconds
                           (SECONDS=10 for longer), like a CPU meter: start
                           a music player or a game first, then run it from
                           a Shell. The report's "AHI mixing" line says how
                           much of it my HDMI driver for AHI took.
 C:rgb2rtg SLEEP=OFF       A developer's A/B, until the next boot: the
                           picture's core on the Pi spins whenever it has
                           nothing to do, as before 0.75-dev48. ON, the
                           default, lets it sleep then - on the RTG desktop
                           almost all the time - so the Pi stays cooler. The
                           report's "follower's core asleep" line says for
                           how much of the time.
 C:rgb2rtg BEAM            The real beam, timed by the Amiga's own E-clock
                           (lines per frame, frame rate). Any kernel.
 C:rgb2rtg CLOCK           The Pi's timer against the Amiga's crystal, 5 s.
                           Any kernel; Pi 3 or 4.
 C:rgb2rtg PV              The Pi's HDMI timing registers and the display
                           scaler's line counter. Pi 3 or 4, any kernel.
 C:rgb2rtg SYNC            Copies the real chip RAM into the kernel's copy
                           and clears the counters. A new start.
 C:rgb2rtg CHECK           Compares the kernel's copy of chip RAM with the
                           real one; changes nothing.
 C:rgb2rtg FIX             CHECK, and copies the real value over every
                           difference.
 C:rgb2rtg TEST            Blitter self-test (the copy must follow blits).
 C:rgb2rtg NOREPLAY        Stops repeating blits into the copy (for tests
                           only - the picture goes wrong).
 C:rgb2rtg REPLAY          Turns it back on (the default).
 C:rgb2rtg SMCREARM        Chip-RAM safe mode off again. The kernel turns
                           it on by itself when a program keeps rewriting
                           its own code in chip RAM (some demos do: State
                           of the Art, Arte) - each instruction it keeps
                           rewriting then runs on its own, checked before
                           each run, as a 68000 without a cache would run
                           it, and the rest at full speed - and off 5 s
                           after the rewriting stops. APPLY does this at
                           the end of every boot.
 C:rgb2rtg COPTIME=OFF     A developer's A/B, until the next boot: a program
                           that rewrites its copper list while it runs has
                           its writes reach the HDMI copper at once, not at
                           their moment of the beam (ON, the default).
 C:rgb2rtg COPLATE=ON      Until the next boot (OFF, the default; RGB2RTG
                           menu: Init, Expert..., Smooth game glitches): a
                           word a game writes into the top of its copper
                           list in the vertical blank, after the copper
                           read it there, is put into its register at once
                           - HDMI then lacks a glitch the real Amiga shows,
                           like Jim Power's lower strip jumping while it
                           scrolls. Needs COPTIME on.
 C:rgb2rtg LOWLAG=ON       Settings' Low lag (OFF, the default). Saved, and
                           sent at every boot: HDMI shows each
                           frame while the Amiga is still drawing it, about
                           8 ms behind the Amiga's own output instead of a
                           frame and more (26 ms on a Pi 3 in Jim Power).
                           Needs HDMI sync on; where it cannot stay ahead
                           of HDMI's scan it falls back to whole frames by
                           itself. The status report's "low lag" line says
                           how many frames raced, and how close they came.
 C:rgb2rtg SHADOWREAD=OFF  A developer's A/B, until the next boot: the CPU
                           reads the real chip RAM even inside a blit the
                           kernel has already done in its copy and the
                           real blitter has not finished (ON, the default,
                           answers such reads from the copy).
 C:rgb2rtg BEAMHOOK=OFF    A developer's A/B, until the next boot: the
                           CPU's reads of the beam position are left alone
                           - no sample for the picture's beam lock (ON,
                           the default).
 C:rgb2rtg DEVOFF=<mask>   A developer's bisect, until the next boot: parts
                           of the work done at every CPU access switched
                           off - 1 extra beam samples, 2 the picture's copy
                           of register writes, 4 chip RAM bookkeeping, 8
                           register bookkeeping, 16 chip-RAM safe mode, 32
                           the picture's core paused, 64 every hook, 128
                           the HDMI poll while the picture catches up
                           (every 64 steps, as before). Add them up;
                           DEVOFF=0 puts everything back. The
                           report then shows the lines the CPU's beam reads
                           saw and its time in the hooks.
 C:rgb2rtg SYNCSTEADY=OFF  A developer's A/B, until the next boot: HDMI sync
                           holds the timing as tightly as it can, changing the
                           HDMI frame's length by a line every few frames, as
                           before. ON, the default, changes it only when the
                           timing has drifted 3 ms - about twice in 40
                           seconds - for displays that flicker at every
                           change.
 C:rgb2rtg COPHOLD=ON      An experiment, off by default, until the next
                           boot: the CPU waits before it writes a word of a
                           copper list the copper has still to read this
                           frame - the order a 68000 always gets, where the
                           Pi's CPU runs ahead. For a program that builds its
                           next copper list while the copper runs this one
                           and tears on the RGB port as well as on HDMI. It
                           can hold the CPU up to a frame.
 C:rgb2rtg BLITHOLD=ON     An experiment, off by default, until the next
                           boot: the CPU waits for the blitter before it
                           reads or writes where a running blit is still
                           drawing - the order a 68000 always gets, where
                           the Pi's CPU can get there first. For a program
                           whose picture tears on the RGB port as well as
                           on HDMI. It can cost milliseconds a frame.
 C:rgb2rtg TAKEOVER=OFF    Leaves programs that take the display over alone,
                           until the next boot; TAKEOVER=ON (the default)
                           looks after them again. Such a program - a demo
                           started from the desktop that loads its own
                           copper list without telling the system - gets
                           the standard PAL or NTSC display it was written
                           for when the one behind the RTG desktop is
                           another (CaffeineOS's is a 31 kHz one), and HDMI
                           shows it; when it gives the display back, both
                           go back as they were. The report counts them.
 C:rgb2rtg TEXTTEST        Opens a native screen, draws text on it (also in
                           a console window) and checks that the kernel's
                           copy of chip RAM got every change: PASS or FAIL.

 A bug report, in short:
   C:rgb2rtg RESET
   (run the game or demo, quit it)
   C:rgb2rtg >RAM:report.txt
   C:rgb2rtg TRACE >RAM:trace.txt

6. COMBINING WORDS
------------------
 Words from sections 1-4, and BEAM, CLOCK and PV, work on any kernel. When
 a line has any of them, only those run - in this order: INSTALL,
 UNINSTALL, VIDEO, AHI, PAULA/SOUNDRATE, HDMIRATE, HDMICOLOURS, HDMISYNC, XPOS/YPOS, SCANLINES/LACED, MASK, SCANSHAPE, BORDER/BORDERX/BORDERY, FLICKERFIX, 31KHZ, HDMISOUND, ECO, ON/OFF, BEAM,
 CLOCK, PV,
 ABOUT, ASK, IMAGE, MENU/UNMENU, APPLY - and the command ends there. Words
 from section 5 (other than BEAM, CLOCK, PV) on the same line are
 ignored.
   C:rgb2rtg ON HDMISYNC=ON          picture on and HDMI sync on, saved
   C:rgb2rtg OFF HDMISYNC=OFF        both off
   C:rgb2rtg MENU APPLY              menu in, settings in force
   C:rgb2rtg INSTALL CONFIG HDMI50 FILE=RAM:config.txt
 Words from section 5 need the RGB2RTG kernel; they run in this order:
 REPLAY/NOREPLAY, SMCREARM, BLITHOLD, COPTIME, SHADOWREAD, BEAMHOOK, COPHOLD, TAKEOVER, HDMISOUND=TONE, SYNCLOG, TRACE, SYNC, RESET, TEST,
 TEXTTEST, CHECK/FIX - and the status report comes last, always.
   C:rgb2rtg SYNC CHECK              a new start, then an immediate check
   C:rgb2rtg SYNCLOG TRACE >RAM:all.txt
 Do not combine ON with OFF (ON wins), or CHECK with FIX (FIX wins).

7. THE SETTINGS FILE
--------------------
 ENVARC:RGB2RTG.prefs (copied to ENV: at boot) is one line, for example:
   picture=on look=sharp crop=overscan scale=fit hdmisync=on x=0 y=0 scanlines=0 laced=0 video=pal
 video=    pal | ntsc (not there: the Amiga's own standard)
 picture=  on | off
 look=     sharp | smooth
 crop=     standard (640x256 PAL, 640x200 NTSC) | overscan | full |
           custom (the cut= values below; Settings: Crop...) | auto (the
           kernel narrows the picture to each game's display window as it
           runs; with the scanlines too since 0.76)
 scale=    fit (4:3) | integer | fill | square (5:4, square pixels) |
           16x9 | 16x10 | 21x9 | 32x9 (the picture stretched to that
           shape: 16:9 TVs and 4K, 16:10 monitors, ultrawide, super-ultrawide)
 hdmisync= on | off
 x=        the picture moved right (minus: left), in hires pixels
 y=        the picture moved down (minus: up), in lines
 scanlines= 0 (off) to 4, for normal screens
 laced=    0 (off) to 4, scanlines for interlaced screens
 borderx=  0 (off) to 10, the TV border across, in percent
 bordery=  0 (off) to 10, the TV border down, in percent
 flickerfix= on | off, interlaced screens woven into one picture, or a
           field at a time (not there: on)
 modes31k= on | off, the 31 kHz modes followed (not there: off)
 eco=      on | off, nothing drawn while only the RTG desktop is on HDMI
           (not there: on)
 hdmirate= 1x | 2x, HDMI at the Amiga's rate or twice it (not there: 1x)
 hdmicolours= full | limited, the colour range on HDMI (not there: full)
 hdmisound= on | off, the Amiga's sound on HDMI as well (not there: off)
 hdmivolume= its volume on HDMI in %, 10 to 800; 100 the Amiga's own
           level, louder ones have their loudest peaks rounded off
           gently (not there: 200)
 hdmiwidth= its stereo width on HDMI in %: 100 the Amiga's hard left
           and right, 0 mono (not there: 100)
 hdmiswap= on | off, left and right swapped on HDMI (not there: off)
 cutl= cutt= cutr= cutb=  crop=custom's: what is cut off the whole frame
           (800x286) at the left, top, right and bottom, in hires pixels
           and lines, in PAL; ntsccutl= ntsccutt= ntsccutr= ntsccutb= the
           same in NTSC (frame 800x237). Not there: the Overscan crop's.
 It can be edited by hand; C:rgb2rtg APPLY puts it in force.

8. KERNEL OPTIONS (the Emu68 command line)
------------------------------------------
 On CaffeineOS the command line is Boot/cmdline.txt on the boot partition
 (config.txt's cmdline= line names it). RGB2RTG adds:
   rgb2rtg=off       the kernel runs as plain Emu68, without RGB2RTG
   rgb2rtg=pattern   a test pattern on HDMI instead of the Amiga picture
   rgb2rtg.smc=off   no chip-RAM safe mode (see SMCREARM in section 5):
                     a program that rewrites its own code runs as with
                     plain Emu68
   rgb2rtg.takeover=off  programs that take the display over are left
                     alone (see TAKEOVER in section 5)
   rgb2rtg.hdmisound=off  HDMI's audio left alone for good: HDMISOUND
                     does nothing (=on: the sound on HDMI from the start,
                     before the settings are applied)
   rgb2rtg.audiolead=<ms>  how far ahead of HDMI the sound is kept, 10 to
                     60 ms (the default 21 on a Pi 4, 48 on a Pi 3)
   rgb2rtg.hdmiforce  HDMI sound starts without its clock check - for
                     finding out why it does not start, nothing else
 and honours sd.unit0=rw and emmc.unit0=rw (the Amiga may write to the
 boot partition), as CaffeineOS's own Emu68 does.

9. ON THE PC
------------
 SD-Setup.cmd (with the SD card in a reader) asks what to do. Or directly:
   SD-Setup.cmd -Action Status            what the card boots, and what of
                                          RGB2RTG is on it
   SD-Setup.cmd -Action Prepare -Yes      the Amiga may write to the card,
                                          unicam.dtbo, the RGB2RTG drawer
                                          on the card (EMU68:RGB2RTG)
   SD-Setup.cmd -Action Remove -Yes       RGB2RTG out of config.txt (when
                                          the Amiga no longer starts)
   -Drive G                               use drive G: without asking
