RGB2RTG v0.76-1 - an UNOFFICIAL Emu68 fork
      - Redirect your RGB image to RTG display
================================================================
by Astair86

Your A1200's own picture - games, demos, native screens - on the same
HDMI screen as your RTG desktop. No RGB monitor, no scandoubler, no
extra cable or board. Install it, power cycle, start a game.

WHAT'S NEW IN 0.76-1
--------------------
Fixes only - everything else is as in 0.76:
 * The Black Lotus' demos (Starstruck, Rift, Little Nell, Magia,
   Perfect Circle): music played, but HDMI stayed black apart from a
   white flash now and then, while the RGB port was fine. Started from
   CaffeineOS, they switch the screen from its hidden 31 kHz mode to
   PAL, and the real chipset then makes one very long frame (about 1/8
   of a second) in which the system puts its own display away. RGB2RTG
   ended that frame at once and ran the system's old copper list one
   more time - and that list switches the picture off. It now counts
   the lines as the real chipset does. 0.75 did it too.
 * Super Stardust AGA: the menu pointer came out as stripes on HDMI.
   The game draws it with super-hires sprites in a fine checkerboard,
   and RGB2RTG kept only every second pixel; it now mixes both, as a
   CRT blends them. The asteroids no longer vanish for a moment
   either.
 * Lupus Reditus (Tristar & RSI & Mystic): no more row of coloured
   specks under the picture, nor red beams around the wolf in the
   cathedral. A real Amiga shows no sprites on a line without bitplane
   data, and RGB2RTG drew them there. Found and fixed together with
   AGA-PISTORM, whose chipset core RGB2RTG shares.
 * Settings' and Sound's Help fit the screen: on a small screen the
   text comes a page at a time, More... for the next.

WHAT'S NEW IN 0.76
------------------
 * HiFi sound (Sound - HiFi (AHI)): music players, trackers and other
   programs that play through AHI play straight on HDMI, in up to 24
   bits and at their own rate - 44.1 to 192 kHz, what the screen
   takes - with my HDMI driver for AHI, which the installer puts into
   DEVS:AHI when AHI is there (CaffeineOS has it).
 * HiFi (AHI): On, low latency - for games: their sound effects are
   heard some 60 ms sooner (about 40 ms from the mix to HDMI instead
   of about 100). When the Amiga stalls - a window dragged, a disk
   read as a program starts - there is one short gap, then it keeps
   the safe margin for 10 seconds and comes back down. And my driver
   now has AHI's own overload protection (Prefs/AHI's Max CPU).
 * Paula on HDMI, in the Sound window: Band-limited (bright sounds
   without the metallic edge), the Rate, and the A1200's LED filter -
   the A1200 filters its own audio outputs whenever a program switches
   that filter on (Kickstart does, many games and players switch it
   off), and the sound on HDMI now does the same. LED filter: As the
   A1200 (the default) or Off.
 * The Pi stays cooler: the core on the Pi that draws the Amiga picture
   now sleeps whenever it has nothing to do - on the RTG desktop most of
   the time; it used to run flat out. My Pi 4 on the desktop: 52-53 C
   instead of 60-61 C. So that the Pi's firmware does not take the
   sleeping cores for an idle Pi and slow the ARM down, Install puts
   force_turbo=1 into config.txt (unless the card sets force_turbo or
   an over_voltage of its own - see INSTALLING).
 * Brightness (110 to 150 %, to make up for the scanlines' dark lines)
   and Gamma (Exact, CRT - a 1084S's darker mid-tones - or Lighter).
 * Scanlines come out even with Scale 4:3 and Fill screen too, where
   an Amiga line takes up no whole number of HDMI lines: every Amiga
   line gets the same darkness, a dark line shared by two HDMI lines
   where it falls between them. Settings - Scanline shape: Even (the
   default) or Crisp (a whole dark HDMI line, as before). With the
   package's VideoCore.card (1.9), which the installer puts in.
 * CRT mask (Settings - CRT mask): an aperture grille's fine dark
   columns over the picture, like a Trinitron or a PVM up close - 25%
   to 100% dark, and with the scanlines too, as on a PVM. It darkens
   only: the Pi's display hardware lays it over the picture, it cannot
   filter the colours apart as a CRT's phosphors do. With the
   package's VideoCore.card (1.9); like the scanlines, it costs nothing.
 * Crop: Auto with the scanlines too: they follow each game's picture
   as Auto fits it to the screen (in 0.75 Auto was off while they were
   on, and the whole frame showed).
 * Scale 5:4 (square) in Settings: square pixels, as emulators offer
   them - a PAL screen 5:4, an NTSC one 16:10. On a 1280x1024 monitor
   a PAL screen fills it at exactly 4x.
 * The Settings window tidied: its rows in three groups - THIS AMIGA
   (the machine's; * marks the three that take effect at the next
   power cycle), then Settings for with PICTURE and CRT LOOK, the
   settings a game can have of its own. Rows that don't apply are
   greyed out: Scanline shape while both scanline settings are Off,
   Low lag while HDMI sync is on Fixed rate. Two clearer names:
   Scanlines (interlace), was Interlaced; VGA modes (31 kHz), was 31
   kHz modes. The settings themselves are the same.
 * Scale's list: Integer and Fill screen, then the shapes by number.
 * Scale 16:9, 16:10, 21:9 and 32:9 in Settings: the picture
   stretched to that shape, whatever the display - 16:9 fills a TV
   (4K ones too), 16:10 a 16:10 monitor, 21:9 an ultrawide
   (2560x1080), 32:9 a super-ultrawide (3840x1080, 5120x1440).
 * Scanline shape Whole lines (Settings): every Amiga line gets a whole
   number of HDMI lines, the picture a little smaller and its shape
   kept - clean scanlines at low resolutions such as 800x600, where an
   Amiga line took 2.3 HDMI lines. With the package's VideoCore.card
   (1.9).
 * On a Pi 3 (and a Pi Zero 2 W) too: the scanlines, Scanline shape,
   the CRT mask and the flicker fixer - in 0.75 they were there on a
   Pi 4 only - and the 31 kHz modes at their full height, where a Pi 3
   showed every other line. HDMI rate 2x stays Pi 4 only: a Pi 3's
   HDMI cannot send 1080p at 100 Hz, so Settings no longer offers it.
 * On a Pi 3 the kernel pulls up the two pins that tell the PiStorm
   models apart itself, as Emu68 did on a Pi 4 only - not left to
   config.txt's gpio= lines.
 * A game's own settings: Settings for (see A GAME'S OWN SETTINGS).
 * Low lag is a setting now (Settings - Low lag), kept after a power
   cycle; still off by default. The Settings window has HDMI's settings
   on top, and a Help button, as the Sound window has.
 * C:rgb2rtg CPULOAD: how busy the Amiga's CPU is, like a CPU meter.
   The status report also says how much of it my HDMI driver for AHI
   takes, and how much of the time the picture's core sleeps.
 * The kernels are built with a newer compiler: the old one got parts
   of the Pi 3 kernel wrong (the Sharp look's scaling, a sound loop).
 * Your screen modes stay when you come from Emu68 1.0's VideoCore
   driver. VideoCore 1.5 and later - mine too - name the board to
   Picasso96 in a new way, and the modes made with an older driver no
   longer belong to it: the Workbench came up on the Amiga's own
   screen, without RTG. Install now gives the VideoCore monitor icon
   VC4_LEGACY_ID where your modes were made with an older driver, or
   where Picasso96 is older than 3.x (it does not know the new way at
   all) - and leaves it alone where your system switched it off on
   purpose (CaffeineOS 9317 with a newer Picasso96 does).
 * AGS and AmiKit: their VideoCore monitor's BOARDTYPE is Emu68-VC4.
   Install now knows that name too, and puts my VideoCore driver in as
   Emu68-VC4.card as well (the old one kept, as for VideoCore.card).
 * The VideoCore monitor icon, when Install changes it, is kept in
   DEVS:Monitors.pre-rgb2rtg - no longer as <icon>.info.pre-rgb2rtg
   in DEVS:Monitors itself, where the Amiga tries to start every file
   at boot. Install moves an old copy there; Uninstall finds both.
 * My kernel takes emmc.low_speed and sd.low_speed from cmdline.txt
   too, as Emu68 1.0 did: the SD card at 25 MHz instead of 50. On a
   Pi 4 some cards - cheap ones - lost a write now and then at 50 MHz
   (a disk's bookkeeping went wrong); at 25 MHz they did not, and a
   SanDisk Ultra was fine at both. Emu68 1.1 itself takes it only from
   config.txt (dtoverlay=emmc,low_speed).
 * On a Pi 4 Install asks whether to run the SD card at 25 MHz
   (recommended), and then adds emmc.low_speed to cmdline.txt; on a
   card with low speed of its own it does not ask. Uninstall takes it
   out again. In a Shell: C:rgb2rtg INSTALL CONFIG LOWSPEED=ON.
 * Fixed: a demo that changes its display window in the middle of a
   line no longer gets a stray colour there. Crop: Auto with the
   flicker fixer (Pi 4) showed an interlaced screen's top part
   stretched, and switched back and forth (Roadkill's vehicle select);
   it also waits longer before it narrows the picture, and stops
   narrowing it in a game that keeps widening it again.
 * Fixed: Shadow of the Beast's sky under the top clouds sat a few
   pixels left of the rest on HDMI, black at its right end. My copper
   went on after a wait sooner than the Amiga's does, and my picture
   showed a colour change a pixel late; any game or demo that changes
   colours in the middle of a line is drawn more exactly now.
 * Fixed: with HDMI sync on, a game whose frames come a little faster
   than HDMI's (Shadow of the Beast) no longer makes the screen go
   black every few seconds.
 * Fixed: HiFi (AHI) crackled as a song began from the SD card, and
   while windows were dragged - my HDMI driver for AHI (6.3) now mixes
   ahead of the card's driver and of window moves, and HDMI starts a
   song once 40 ms of it are there. C:rgb2rtg CPULOAD no longer makes
   the sound crackle itself.
 * Fixed: a game that rewrites its own code while it plays (Jim
   Power) stuttered - on the Amiga's own output as well: four times a
   second my safe mode for such code held the 68k for up to 2 ms. It
   now does that bookkeeping in a fraction of the time, and keeps
   code a game rewrites over and over instead of dropping it again.
 * Fixed: Jim Power's picture now and then jumped on HDMI only. For a
   while the game neither reads the Amiga's beam position nor writes a
   chipset register - only chip RAM - and my picture went on without
   word of where the beam was, for up to a sixth of a second; it
   drifted a few lines and caught up in one jump. It now asks for the
   beam position itself when it has had no word for 40 ms.
 * Fixed: games stuttered - on the Amiga's own output too - when their
   WHDLoad install flushes the CPU's caches often (Jim Power's: 100
   times a second). After each flush Emu68 checked all the game's
   translated code against chip RAM again, and every one of those
   reads waited for the Amiga's bus behind the blitter: a fifth of the
   68k's time. My kernel sees every write into code, so the check now
   skips what nothing wrote into since. Jim Power's flicker at the
   bottom of the screen is gone with it, on both outputs - the game
   updated its screen too late.
 * Fixed: Brian the Lion's clouds (OCS/ECS) came out streaky on HDMI.
   The game draws them with one sprite that its copper moves along each
   line, writing it just as the beam reaches it, and my picture took
   those writes as a pixel late; and with the game's wide screen the
   sprite's own fetches belong to the screen, but my picture still made
   them, from a stale address. Both now as on the Amiga's own output.
 * Fixed: now and then the Amiga stopped at Emu68 1.0.4's logo instead
   of starting (CaffeineOS). config.txt picks the kernel by what some
   of the Pi's pins read at power-on, and the last match wins: when
   the PiStorm32-lite's GPIO17 read low, the classic PiStorm's kernel
   came last and won. Install now ends config.txt with a short block
   that gives the PiStorm32-lite RGB2RTG's kernel, whatever GPIO17
   says.
 * Fixed: ReshootR's rock layer was flat bands of colour on HDMI. The
   game moves one sprite along each line with its copper, each time
   exactly where the Amiga can still catch it, and my picture took the
   moves a little late and lost them. Brian the Lion's last streaks
   went with it.
 * Fixed: right after a game switches bitplanes off in the middle of a
   line (Zool's status bar), my copper could run two colour clocks
   early: the Amiga's bitplane DMA still takes its slots for a moment
   after the switch.
 * MultibootOS: its boot menu copies each system's own config_<os>.txt
   over config.txt at every start, and undid the install. Install and
   Uninstall now edit that system's file too.
 * AmiKit: Install knows AmiKit's config.txt, and the picture fills
   the screen - AmiKit's config.txt has no disable_overscan, and the
   Pi framed the picture with a black border. Install adds it with
   1080p at 50, 100 or 120 Hz, unless config.txt says otherwise.
 * A PiStorm32-lite in stealth mode: Install has config.txt load the
   FPGA firmware for that mode where the card has it (CaffeineOS and
   MultibootOS do). Without it my kernel hung right after the Emu68
   logo on my A1200, on AmiKit.
 * Fixed: the boot could hang when the RTG driver did not answer my
   settings at once (AmiKit) - now it waits two seconds at most.
 * Fixed: the About window and the Expert window's explanations were
   blank on AmiKit (its look patches paint over text in windows), and
   About closed when you moved it.
 * Fixed: Kickstart 3.2's Early Startup menu (both mouse buttons at
   power-on) in 31 kHz showed nothing on HDMI. VGA modes (31 kHz) are
   now always on until the Workbench starts, whatever is saved.
 * Install and Uninstall find the Installer wherever the system keeps
   it, not only in C:. A system without one (MultibootOS's AmigaOS
   3.2) cannot run them by double-click: Commands.txt lists their
   steps for a Shell (section 4, the whole install and uninstall by
   hand).

WHAT'S NEW IN 0.75
------------------
 * The Raspberry Pi 3 (and the Pi Zero 2 W, which has its chip) gets
   its own kernel, built for its processor - the installer puts in the
   one for your Pi. On a Pi 3, HDMI sync works now and the installer
   switches it on; Top Gear 2 and Jim Power play; config.txt gets
   temp_soft_limit=70, so a Pi 3 B+ or 3 A+ keeps its 1.4 GHz in the
   warmth of an A1200. The status report shows the Pi's clock, its
   temperature and whether it was slowed down.
 * Low lag (Init - Expert..., off by default for now): HDMI shows each
   frame while the Amiga is still drawing it - about 8 ms behind the
   Amiga's own output instead of 26, on a Pi 3 and a Pi 4 (see USING
   IT).
 * The Sound window (RGB2RTG menu - Sound): besides on and off, the
   volume on HDMI - 200 % to begin with, as the Amiga plays quieter
   than other HDMI sources, the loudest peaks rounded off gently - the
   stereo width (the Amiga's hard left and right is tiring on
   headphones: 75, 50, 25 % or mono) and left and right swapped. Each
   change is heard at once; the Amiga's own outputs stay as they are.
 * Settings - Crop: Custom (the Crop... button: how much is cut off at
   each edge, for a display that hides the picture's edges or a game's
   empty border) and Auto (the picture follows each game's own display
   area while it runs and fills the screen with it).
 * Look: Sharp gives every Amiga pixel the same width and every line
   the same height on HDMI, also where the scale is no whole number (a
   report on itch.io) - with the RTG driver in the package, which the
   installer puts in.
 * Init - Expert...: switches that are not settings, each explained in
   the window - Low lag; Smooth game glitches (HDMI without a glitch the
   real Amiga shows when a game updates its copper list a little late,
   like Jim Power's jumping lower strip); Copper timing, Copper hold,
   Frame skip, Blitter wait - and Reset counters and Save report, for
   testing a game without a Shell.
 * Smoother on HDMI: each frame is prepared for HDMI while the Amiga
   draws it, not all at its end; after a hiccup HDMI no longer stays a
   frame behind until the next power cycle; a rare misread of the HDMI
   display list (a dark picture, or a frame shown twice) is gone.
 * Fixed: Jim Power's lives and smart bombs (sprites the copper moves
   just as the beam reaches them); Disposable Hero's menu credits (a
   line that switches between lores and hires part way).
 * The desktop menu's entries are now called Init and Settings (they
   were RGB2RTG and RTG Image).

WHAT'S NEW IN 0.74
------------------
 * Sound on HDMI, as an option (RGB2RTG menu - Sound): the Amiga's
   sound plays on HDMI as well - the screen's speakers, or an HDMI
   audio extractor - in step with the picture, and the Amiga's own
   audio outputs keep working. Off until you switch it on; it goes on
   and off at once and stays as you left it (see USING IT).
 * Fixed from your reports: Indiana Jones and the Last Crusade (the
   action game) came out garbled; Ikari Warriors had a band at the
   bottom while the screen scrolled; Aladdin's Magic Lamp; Aladdin
   AGA's logos; Zool AGA's playfield; the backgrounds of Sonic 060 and
   Castlevania AGA, cut off on the right; Super Stardust's level-end
   screen; Wit Premium's picture, shifted right; Disposable Hero's
   start screen, its scroller corrupted and the 3D ship's background
   shifted; FullMoon's slowdown; Prey AGA's crash.
 * Interlaced screens no longer flicker with HDMI sync on some LCDs
   (Disposable Hero's Euphoria screen flickered at the edges).
 * A plain AmigaOS 3.x, such as 3.2, as well as CaffeineOS: Install
   takes a card set up from Emu68's own config.txt whatever its
   kernel= line names, puts the RGB2RTG title in Workbench's own menu
   bar, and says when Picasso96 has no VideoCore monitor yet; SD-Setup
   can take RGB2RTG off such a card again. WHAT YOU NEED has how to
   set up 3.2, from Michael Gruber's guide.

WHAT'S NEW IN 0.73
------------------
 * Truer colours on HDMI. In its 50 Hz mode the Pi sent the TV's
   limited colour range, and most PC monitors showed it grey and pale
   next to the Amiga's own output - testers saw the difference on the
   two inputs of one monitor. RGB2RTG now sets full-range colour
   (0-255). A TV that shows crushed blacks or clipped whites with it
   wants the new HDMI colours in Settings: Limited (TV).
 * Steadier HDMI sync. To keep HDMI in step with the Amiga, Follow
   Amiga made a frame one line longer or shorter several times a
   second, and some LCDs showed that as flicker on dark pictures (the
   Pang intro). Now it does so about twice in 40 seconds; every Amiga
   frame is still shown exactly once.
 * HDMI at twice the rate, as an option: Settings' HDMI rate 2x
   runs HDMI at 100 Hz (120 for NTSC) and shows each Amiga frame
   twice, with HDMI sync too. Only for a display that takes 1080p at
   100 Hz - any other shows nothing at all with it (see IF SOMETHING
   GOES WRONG).

WHAT'S NEW IN 0.72
------------------
 * Eco mode (on by default): while only the RTG desktop is on HDMI,
   the Pi no longer draws the Amiga picture nobody can see, so it
   stays cooler. The moment a game, demo or native screen comes to the
   front, the picture is there as before.
 * 31 kHz screen modes, as a test: DblPAL, DblNTSC, Multiscan
   (Productivity), Euro72 and friends can now be shown on HDMI, sharp
   and with the mouse pointer. They stay off until you switch them on
   in Settings (31 kHz modes: On). PAL and NTSC screens are the same
   either way.
 * OutRun AGA, and programs that point the copper at a new list the
   same way, no longer show only the copper's colours.
 * Interlaced screens keep their two fields in the right order: the
   Batman demos' intro text no longer jumps a line.
 * A Flicker fixer switch in Settings, for those who like interlaced
   screens a field at a time, the way the Amiga's own output shows
   them.
 * Programs that change their copper list while it is on screen are
   followed more closely (the end of Batman Rises' city scene).
 * When a program writes into memory the blitter is still drawing
   into, HDMI now ends up with what the real machine has.
 * The copper waits for the blits it starts as long as the real
   blitter would - for demos that draw with the copper, like Desert
   Dream.

WHAT'S NEW IN 0.71
------------------
 * Demos that take over the display from the RTG desktop without
   telling the system - they load their own copper list - work now.
   HDMI switches to them, and they get the standard PAL (or NTSC)
   display they were written for instead of the 31 kHz one CaffeineOS
   leaves behind the RTG desktop. There, Lamers' Shiva showed only
   static, on the Amiga's own RGB port too, with garbled sound. When
   the demo hands the display back, everything goes back as it was
   (see GOOD TO KNOW).
 * TV border (Settings): for a TV that cuts the edges of 1080p off.
   Every picture on HDMI - the desktop, the Amiga picture, the mouse
   pointer - gets a few percent smaller, with a black frame, still at
   50 Hz. It is off unless you set it.

WHAT'S NEW IN 0.7
-----------------
 * Interlaced screens (Pi 4): both fields are woven into one picture,
   the way a flicker fixer does it, so interlaced titles and pictures
   stand still on HDMI instead of flickering.
 * Super-hires HAM8 screens look right on HDMI.
 * Demos that rewrite their own code: only the instructions that are
   actually rewritten run the careful way now, and everything around
   them runs at full speed. (0.6 slowed all code in chip RAM down -
   you could see it in Arte's 3D dots.)
 * Blits started by the copper use the blitter registers the 68k set
   (Desert Dream's rays).
 * The installer understands Emu68's own config.txt, not only
   CaffeineOS's.
 * A dtoverlay= line that named unicam as another overlay's setting
   (dtoverlay=sdhc,unit0=rw,unicam,boot) gave no picture, because the
   Pi loads only one overlay per line. The installer and C:rgb2rtg now
   point it out, and C:rgb2rtg tells you when the kernel is waiting
   for a unicam overlay that isn't there.
 * The VideoCore monitor icon: DisplayChain=No kept games and native
   screens off HDMI. The installer now sets it to Yes, and Uninstall
   puts it back. VC4_SWITCH_METHOD and VC4_SWITCH_INVERT could keep
   HDMI stuck on one picture - with the RGB2RTG kernel, VideoCore.card
   now ignores them.
 * VideoCore.card with another kernel (stock Emu68) works like the
   stock driver, instead of showing black with coloured dots.

WHAT'S NEW IN 0.6
-----------------
 * NTSC. NTSC screens, games and demos are followed, on an NTSC A1200
   and on a PAL one started in NTSC. Settings has a Video setting,
   PAL or NTSC: the standard the Amiga starts in, HDMI at 1080p 50 or
   60 Hz to match (with HDMI sync every frame is shown once), and the
   picture framed for that standard. Power cycle after changing it.
 * Trackloaded ECS demos - 9 Fingers, State of the Art, Desert Dream,
   Arte - load from disk and draw with the blitter. That picture is now
   right on HDMI too (the blitter is repeated the way WinUAE does it).
 * Demos that rewrite their own code as they run: the kernel notices
   and runs that code the careful way (see GOOD TO KNOW).
 * Scanlines (Settings): 25% to 100% dark, with a level of their own
   for interlaced screens. Pi 4.
 * Position... (Settings): move the picture on HDMI with the mouse or
   the keys, on a calibration screen. PAL and NTSC each keep their own
   position.
 * The picture is drawn on a Pi core of its own.
 * A program that restarts the copper by reading its strobe register
   gets the right copper list on HDMI.
 * No more "insert volume DOpus5:" requester in the installer on a
   system without Directory Opus.
 * The licences in full in the package, and the Emu68 source archive
   published again (the 0.5 one had Windows line endings, and the
   patch did not apply to it).

WHAT'S NEW IN 0.5.1
-------------------
 * Text on native screens now shows on HDMI. It was missing everywhere:
   the Early Startup Control, requesters and windows on native
   screens, the loading text some demos show.
 * A config.txt edited by hand works with a plain dtoverlay=unicam
   line: the kernel switches the ",boot" part on by itself.
 * The report (C:rgb2rtg) names the RTG driver, and tells you what to
   check when the Amiga picture hasn't reached HDMI yet.

WHAT'S NEW IN 0.5
-----------------
 * First public prototype.
 * The A1200's own picture - games, demos, native screens - on the
   Raspberry Pi's HDMI output, in 24-bit colour, switching with the
   RTG desktop just like any native screen does.
 * HDMI sync: the HDMI frame follows the Amiga's (PAL, 49.92 Hz), so
   in PAL games every frame is shown once. Some demos still hitch now
   and then (see GOOD TO KNOW).
 * The Amiga's sound on HDMI as well, if you want it (RGB2RTG menu -
   Sound): the screen's speakers, or an HDMI audio extractor.
 * The RGB2RTG menu on the desktop: Init (picture on/off), Settings
   (sharp/smooth, crop, scaling, HDMI sync), Sound and About.
 * Its own RTG driver: VideoCore 1.9 with my changes.
 * Install and Uninstall.

WHAT IT IS (PLEASE MAKE A BACKUP OF YOUR EMU68 SDCARD)
------------------------------------------------------
In short: the picture of your A1200's own chipset, on the same HDMI
screen as your RTG desktop.

How it works: your real AGA chipset keeps running exactly as before -
nothing is emulated in its place. The RGB2RTG kernel (Emu68 with
RGB2RTG added) sees everything the 68k writes to chip RAM and to the
custom registers, and keeps its own copy of chip RAM on the Pi up to
date - every write, every blit repeated into it, every disk load. One
of the Pi's cores then redraws the very same picture, line by line, in
step with the real beam, from that copy and from the same register
writes the chipset gets from the 68k and the copper. The redrawing
works as an AGA chipset's would - copper, bitplanes, sprites, colours,
taken from WinUAE - and Paula's sound is redrawn for HDMI the same
way. It only watches: the Amiga never reads anything from it, and the
real chipset still runs the machine. Whenever a native screen is in
front - a game, a demo, a non-RTG screen - you see that picture on
HDMI; when the RTG desktop is in front, you see the desktop.

WHAT YOU NEED
-------------
 * An Amiga 1200 with a PiStorm32-lite and a Raspberry Pi 4 or 3 (or
   a Pi Zero 2 W, which has the Pi 3's chip) - each Pi gets its own
   kernel. HDMI rate 2x (100 Hz) is Pi 4 only.
 * CaffeineOS with its WHDLoad setup and its RTG (Picasso96) desktop.
   Tested with CaffeineOS 9317. Or a plain AmigaOS 3.x, such as 3.2,
   with Picasso96 (see below).
 * A TV or monitor that takes 1080p at 50 Hz (60 Hz for NTSC). Nearly
   all of them do. The installer offers to set it up, and it's what
   makes games run smoothly.
 * Not a must: a Windows PC with a card reader. SD-Setup.cmd is the
   easy way to get the RGB2RTG drawer onto the card, and the PC is the
   way back if the Amiga doesn't start after installing (see IF
   SOMETHING GOES WRONG).

You don't have to install Emu68 first: the package brings its own
kernel (Emu68 1.1.0-beta.1 with RGB2RTG added). CaffeineOS 9317 as it
comes, with its own Emu68 1.0.7, is all the installer needs.
RGB2RTG also brings its own RTG driver, VideoCore 1.9 with my
changes. The driver you have now is kept, and Uninstall puts it back.

Without CaffeineOS - a plain AmigaOS 3.x, such as 3.2, on a card set
up from Emu68's own config.txt - the card's own Emu68 is all the
installer needs too, but the RTG desktop is up to you:
 * Picasso96 itself, before you run Install: the installer stops if
   there is no SYS:Libs/Picasso96. RGB2RTG brings only the VideoCore
   driver.
 * A VideoCore monitor in DEVS:Monitors (CaffeineOS has one).
   Picasso96 starts VideoCore.card only through a monitor whose
   BOARDTYPE tooltype says VideoCore (or Emu68-VC4, as on AGS and
   AmiKit): without one there is no RTG
   desktop, and the Amiga's picture never reaches HDMI. If Picasso96's
   installer offers no VideoCore board, let it install another one.
   Then, in DEVS:Monitors, select that board's monitor and choose Copy
   in Workbench's Icons menu (it copies the file and its icon), name
   the copy VideoCore and change its BOARDTYPE tooltype to VideoCore;
   leave its other tooltypes as they are. Made before you run Install,
   it is looked after there too: Install makes sure its DISPLAYCHAIN
   tooltype doesn't say No. If there is no VideoCore monitor, Install
   tells you so at the end (it installs all the same): make it then,
   run C:rgb2rtg INSTALL MONITOR in a Shell, which sees to its
   DISPLAYCHAIN, and power cycle.
 * VideoCore screen modes, after Install and the power cycle. If
   Prefs/ScreenMode lists none, make them in Prefs/Picasso96Mode: a
   setting for the VideoCore board, with a resolution and its colour
   depths. A mode's timings and rate don't change HDMI: VideoCore.card
   scales the RTG desktop to fit the HDMI mode the Pi starts in
   (1080p at 50 Hz, 60 for NTSC, after the installer's Yes). Pick one
   in ScreenMode, Test it, then Save.
Michael Gruber set up AmigaOS 3.2 on a Raspberry Pi 3A+ this way,
with Picasso96 from Aminet, and wrote it all down in an installation
guide of his own - this part is drawn from it. Thank you, Michael.

WHAT IS IN THE PACKAGE
----------------------
 README.txt                 this file
 Commands.txt               every rgb2rtg command, for the Shell (also
                            in the Amiga drawer)
 SD-Setup.cmd               on the PC, with the SD card in a reader:
                            prepares the card, or takes RGB2RTG out of
                            config.txt again (PC/ holds its script)
 Amiga/RGB2RTG/             the drawer that goes to the Amiga:
   Install                    the installer
   Uninstall                  puts everything back
   ReadMe.txt                 this file, for the Amiga
   Files/C/rgb2rtg            the rgb2rtg command (menu, settings,
                              status); it carries Emu68's ntsc, pal,
                              emmc and sdhc overlays (MPL-2.0,
                              src/overlays/ in the Emu68 source)
   Files/Kernel/Pi4/Emu68-rgb2rtg.gz
   Files/Kernel/Pi3/Emu68-rgb2rtg.gz
                              the RGB2RTG kernel: Emu68 1.1.0-beta.1
                              with RGB2RTG added, for the PiStorm32-lite -
                              one built for each Pi's processor; the
                              installer copies the one for your Pi
   Files/Overlays/unicam.dtbo Emu68's unicam overlay (MPL-2.0, from
                              src/overlays/unicam.dts in the Emu68
                              source; copied only if the card doesn't
                              have it)
   Files/Overlays/emmc.dtbo, sdhc.dtbo
                              Emu68's SD card overlays (MPL-2.0, the
                              same source), for a card the Amiga may
                              not write to - see "If something goes
                              wrong"
   Files/Libs/Picasso96/VideoCore.card
                              the VideoCore 1.9 RTG driver, my build
 Licenses/                  GPL-2.0 (RGB2RTG), MPL-2.0 (Emu68 and
                            VideoCore.card), the UAE/WinUAE notices, and
                            the libraries Emu68 is built with
 Source/                    the source code, the RTG driver's too
 CHECKSUMS.txt              MD5 of every file, to check a copy
A separate download: RGB2RTG-0.5-emu68-src.tar.gz, the complete source
of the Emu68 the kernel is built from (unchanged since 0.5; published
again with 0.6 - the first one had Windows line endings, and the patch
did not apply). Both - the package and this archive - are on RGB2RTG's
page: https://astair86.itch.io/rgb2rtg-amiga1200

INSTALLING
----------
 1. Make a backup of your SD card - an image of the whole card is
    best. At the very least, copy everything on the EMU68 partition
    (the one with config.txt) to a PC, drawers and all.
 2. Get the Amiga/RGB2RTG drawer onto the Amiga, anywhere you like
    (RAM: is fine): over the network or on a CF card. Or use a PC:
    unpack the archive there with its folders as they are, switch the
    Amiga off, put its SD card in the PC, double-click SD-Setup.cmd
    where you unpacked it and choose Prepare. It finds the card by
    itself, puts the drawer on it - on the Amiga, that's the RGB2RTG
    drawer on the EMU68 disk - and makes sure the Amiga may write to
    that partition: in Boot/cmdline.txt for CaffeineOS's kernels, and
    in config.txt for a stock Emu68 1.1 kernel (see READ-ONLY under IF
    SOMETHING GOES WRONG).
    The rest of the package doesn't need to go on the card.
    (SD-Setup.cmd runs the script in the PC folder beside it,
    and that script takes the drawer from the Amiga folder beside
    that: started from inside the archive window, or copied out on its
    own, it finds neither.) If Windows offers to format a drive when
    the card goes in, click Cancel: that is the Amiga's own partition,
    which Windows can't read, and formatting it erases everything the
    Amiga keeps there.
    EMU68 is that disk's name on CaffeineOS. On a plain AmigaOS 3.2
    card it may have another name - the installer finds it by what's
    on it - or not be mounted until you open the icon that mounts it:
    MOUNTFAT on some cards, or one in Storage/DOSDrivers.
 3. Double-click Install. It checks that this is an A1200 with a
    PiStorm32-lite and a Pi 4 (or 3), that Picasso96 is installed, and
    that the boot partition can be written to. It finds that partition
    itself whenever it's mounted - it is, if Install runs from the
    RGB2RTG drawer on the card. If it isn't (on a plain AmigaOS 3.2 it
    may be mounted only from an icon), Install asks which disk it is:
    mount it - the requester's Help says how - click Volumes and pick
    it. Then it asks one question: HDMI at 1080p 50 Hz (60 Hz on an
    NTSC Amiga). Yes is recommended. It isn't asked when your own
    lines in config.txt already set that rate.
 4. POWER CYCLE the Amiga: switch it off, wait a few seconds, switch
    it on. A reset (Ctrl-Amiga-Amiga) does not load a new kernel.

What the installer changes - Uninstall undoes each of these, except
the new files on the boot partition, which simply stay there unused:
 * C:rgb2rtg
 * EMU68:kernel/Emu68-rgb2rtg.gz (a new file; your kernels stay)
 * EMU68:overlays/unicam.dtbo, only if the card had none
 * SYS:Libs/Picasso96/VideoCore.card - the one you had is kept first,
   as VideoCore.card.pre-rgb2rtg
 * EMU68:config.txt - a copy of it as it was is kept first, as
   config.txt.pre-rgb2rtg. In the PiStorm32-lite's two sections,
   [gpio24=0] and [gpio4=0], kernel= points at the RGB2RTG kernel; the
   old line stays, as a comment starting with #RGB2RTG-WAS:. (AmiKit's
   section is [gpio24=0] with [gpio4=1] right under it: the kernel=
   line under the two is the one changed.) After the
   cmdline= line comes a block from "# RGB2RTG begin" to "# RGB2RTG
   end" with dtoverlay=unicam,boot (the display path the picture is
   shown through); if you said yes, the three 1080p 50 Hz lines (60 Hz
   for NTSC); and, with HDMI colours on Full (PC) - the default -
   hdmi_pixel_encoding=2, the full-range colours; with Sound on,
   hdmi_drive=2 (HDMI mode, so that a display that says it is DVI gets
   the sound as well). With 1080p at 50 Hz (or 100/120 Hz, which are TV
   modes too), disable_overscan=1, unless config.txt says something
   about overscan itself: the Pi's firmware puts a black border around
   a TV mode otherwise (AmiKit's config.txt has no such line).
   A line config.txt already has is not added
   again. A Video setting that isn't your
   Amiga's own standard adds dtoverlay=ntsc or dtoverlay=pal there,
   and puts that file in EMU68:overlays if the card has none.
   The block also lets the Amiga write to the boot partition whatever
   Emu68 1.1 kernel starts on a Pi 3: [pi3] dtoverlay=sdhc,unit0=rw (a
   stock 1.1 kernel ignores cmdline.txt's sd.unit0=rw), only if the
   card hasn't got it, and sdhc.dtbo in EMU68:overlays if the card has
   none. Nothing for a Pi 4: the RGB2RTG kernel writes there as
   cmdline.txt's emmc.unit0=rw allows. (The 0.75 test builds added the
   Pi 4's overlay, dtoverlay=emmc,unit0=rw, and installing takes that
   line out again. 0.75's README said that overlay made a Pi 4 damage
   what it wrote to the card: that was wrong - the overlay changes
   nothing there. The damage came from the card's speed: some cards
   lose a write now and then at 50 MHz on a Pi 4 - see 25 MHz below.)
   Unless the card sets force_turbo or an over_voltage of its own,
   force_turbo=1: the Pi's firmware would otherwise slow the ARM down
   whenever RGB2RTG's cores sleep (an over_voltage is left alone - with
   force_turbo=1 it would set the Pi's warranty bit for good).
   And unless the card sets one, [pi3] temp_soft_limit=70: a Pi 3 B+
   or 3 A+ slows from 1.4 to 1.2 GHz once it is 60 C warm, and with
   Emu68 working the Pi hard in an A1200 it gets there within minutes -
   then HDMI drops frames. 70 is the most the Pi's firmware allows;
   its overheat limit (85 C) is unchanged. A heatsink still helps.
   At the very end of a CaffeineOS config.txt, a block from "# RGB2RTG
   last begin" to "# RGB2RTG last end": [all], [gpio4=0], our kernel=
   line, the stealth-mode firmware's initramfs line, [all]. The last
   kernel= line that matches is the one the Pi boots, and CaffeineOS's
   [gpio17=0] (the classic PiStorm's) comes after the PiStorm32-lite's
   sections - with GPIO17 reading low at power-on, the A1200 got Emu68
   1.0.4 and stopped at its logo. A classic PiStorm reads GPIO4 high
   and keeps its own kernel. The initramfs line is the card's own
   [gpio4=0] one when that loads the FPGA firmware for stealth mode;
   else, when the card has that firmware (Boot/ps32lite-stealth-
   firmware.gz, as CaffeineOS and MultibootOS do), it and the ROM the
   card starts the PiStorm32-lite with. A PiStorm32-lite in stealth
   mode (GPIO4 low) hung on the RGB2RTG kernel with Emu68's built-in
   firmware, right after mounting the boot partition (my A1200 on
   AmiKit, whose config.txt loads none); a stock Emu68 1.1 doesn't
   mind. The same block goes on a card with no [gpio4=0] section at
   all (AmiKit's), and INSTALL CHECK says which firmware stealth mode
   gets.
   A card set up from Emu68's own config.txt, as a plain AmigaOS 3.x
   card usually is, has neither section; its kernel= line at the top
   names Emu68 itself (kernel=Emu68-pistorm32lite.gz, or
   kernel=Emu68-pistorm.gz on some 3.2 cards). It is changed the same
   way, whatever file that line names: it points at the RGB2RTG
   kernel, the old one is kept under it, and the block goes at the
   end of the file. The kernel goes into a KERNEL drawer, made if the
   card has none.
 * EMU68:cmdline.txt (the one config.txt names: EMU68:Boot/cmdline.txt
   on CaffeineOS), on a Pi 4 when you said yes to 25 MHz - a copy of
   it as it was is kept first, as cmdline.txt.pre-rgb2rtg. Its
   command line gets emmc.low_speed at the end, and the RGB2RTG block
   in config.txt a line saying so. Uninstall takes the word out
   again; a card that ran at 25 MHz before keeps it.
 * the RGB2RTG title in the desktop menu: in Directory Opus's user
   menu and S:ToolsDaemon.menu when you have them (CaffeineOS does),
   otherwise in Workbench's own menu bar (before 3.1.4, in its Tools
   menu) - Install's last window says where. And a short block in
   S:User-Startup that puts your settings in force at every boot (on
   a plain AmigaOS it also puts the title back in Workbench's menu
   bar), and when WHDLoad's S:WHDLoad-Startup and S:WHDLoad-Cleanup
   are there, a short block at the top of each for a game's own
   settings (A GAME'S OWN SETTINGS). Each of these files is copied to
   *.pre-rgb2rtg first.
 * ENVARC:RGB2RTG.prefs, your settings (running Install again keeps
   them)
 * the VideoCore monitor icon in DEVS:Monitors, only if it says
   DisplayChain=No (afterwards it says Yes), or if it needs
   VC4_LEGACY_ID for your screen modes (WHAT'S NEW IN 0.76): the icon
   as it was is kept first in DEVS:Monitors.pre-rgb2rtg
 * Emu68-VC4.card, only where a monitor's BOARDTYPE is Emu68-VC4 (AGS,
   AmiKit): my VideoCore driver under that name, the one it replaces
   kept as Emu68-VC4.card.pre-rgb2rtg

Installing by hand: the installer knows CaffeineOS's config.txt and
Emu68's own. Got a different one? Then do the same by hand. Copy
Emu68-rgb2rtg.gz from Files/Kernel/Pi4 (or Pi3, for a Raspberry Pi 3)
to the KERNEL drawer of the boot partition and point
your PiStorm32-lite's kernel= line at it. Add dtoverlay=unicam,boot to
config.txt on a line of its own - the Pi loads one overlay per line,
so inside another overlay's line (dtoverlay=sdhc,unit0=rw,unicam,boot)
unicam is not loaded. For 50 Hz add hdmi_group=1, hdmi_mode=31 and
hdmi_force_mode=1. Copy VideoCore.card to LIBS:Picasso96 and rgb2rtg
to C:, and put "C:rgb2rtg APPLY >NIL:" in S:User-Startup.
After that, C:rgb2rtg ON or OFF switches the picture from a Shell.

USING IT
--------
Start a game or a demo: when its screen is in front, its picture is
on HDMI. Back on the desktop, HDMI shows the RTG desktop again. That's
all there is to it.

The RGB2RTG menu on the desktop:
 * Init       - the Amiga picture on HDMI, on or off. Off: HDMI is
                black while a native screen is in front (the RTG
                desktop is shown as always). Its Expert... button
                has switches that last until the next power cycle,
                each explained in the window.
 * Settings   - how the picture looks (see below).
 * Sound      - the Amiga's sound on HDMI as well, on or off, and
                its volume, stereo width and left/right; how Paula
                is made for HDMI, the sound's rate, and HiFi sound
                for AHI programs (see below).
 * About      - version and licences.

The same from a Shell:
 C:rgb2rtg ON | OFF          the picture on HDMI on or off
 C:rgb2rtg VIDEO=PAL | NTSC  the Video setting (see below)
 C:rgb2rtg HDMIRATE=1X | 2X  HDMI at the Amiga's rate, or twice it (below)
 C:rgb2rtg HDMICOLOURS=FULL | LIMITED  full-range colours, or a TV's (below)
 C:rgb2rtg HDMISYNC=ON | OFF HDMI frames follow the Amiga's, or not
 C:rgb2rtg HDMISOUND=ON | OFF  the Amiga's sound on HDMI as well, or not
 C:rgb2rtg PAULA=CLASSIC | BANDLIMITED  how Paula is made for HDMI (below)
 C:rgb2rtg SOUNDRATE=SCREEN | ANY | 96 | 192  HDMI sound's rate (below)
 C:rgb2rtg LEDFILTER=ON | OFF  the A1200's LED filter on HDMI (below)
 C:rgb2rtg AHI=ON | LOWLATENCY | OFF  HiFi sound for AHI programs (below)
 C:rgb2rtg XPOS=n YPOS=n     moves the picture (see Commands.txt)
 C:rgb2rtg SCANLINES=n       scanlines, 0 (off) to 4 (see Commands.txt)
 C:rgb2rtg SCANSHAPE=EVEN | CRISP  the scanlines' shape (below)
 C:rgb2rtg MASK=n            the CRT mask, 0 (off) to 4 (below)
 C:rgb2rtg BRIGHTNESS=n      brightness, 0 (normal) to 4 (150%) (below)
 C:rgb2rtg GAMMA=EXACT | CRT | LIGHTER  the colours' gamma (below)
 C:rgb2rtg                   a status report (for bug reports)

The sound on HDMI (RGB2RTG menu - Sound, or C:rgb2rtg HDMISOUND=ON):
the Amiga's sound plays on HDMI as well - on the screen's speakers, or
through an HDMI audio extractor - in step with the picture, and the
Amiga's own audio outputs keep working. It goes on and off at once,
and stays as you left it after a power cycle. It is Paula's sound as
the Pi makes it again, not a recording of the Amiga's output, so it
can differ a little; the Amiga's own output stays the reference. Only
the Pi's first HDMI port (HDMI0, next to the power socket on a Pi 4)
carries it.

The Sound window also sets how it sounds on HDMI - each change is
heard at once, Save keeps it:
 * Volume - the Amiga plays quieter than other HDMI sources; 200 %,
   the default, evens that out. Above 100 % the loudest peaks are
   rounded off gently instead of crackling. 100 % is the Amiga's own
   level.
 * Stereo - the Amiga puts each of its four channels hard left or
   right. On headphones 50 or 75 % is easier on the ears; Mono gives
   both sides the same. Amiga (full) is as the Amiga plays it.
 * Left and right - Swapped, for speakers or an extractor wired the
   other way round.
These are HDMI's alone: the Amiga's own audio outputs are untouched.
And four more, heard at once as well:
 * Paula - Band-limited builds the Amiga's sound for HDMI from each
   step its four channels make, the way the real Paula's output steps:
   bright sounds lose the metallic edge the Classic way leaves on them.
   Classic, the default, makes it from a 28 kHz mix, as before.
 * LED filter - the A1200 puts its own audio outputs through a filter
   that programs switch on and off: Kickstart switches it on, many
   games and players off (it is the power LED's signal; on some A1200s
   the LED dims with it). As the A1200, the default, does the same on
   HDMI; Off never filters, as before 0.76. The status report says
   whether it is on, and how often programs switched it.
 * Rate - the rate HDMI's sound runs at. Follow the screen, the
   default: 48 kHz, or the rate an AHI program plays at, when the
   screen says it takes it. Follow - any: every rate, whatever the
   screen says - some receivers and monitors take more than they list.
   96 kHz or 192 kHz: always that, for everything. A new rate is a
   short gap while the screen catches up.
 * HiFi (AHI) - programs that play through AHI (music players,
   trackers, the desktop's sounds) play straight on HDMI, in up to 24
   bits and at their own rate - music made at 44.1 kHz as it was made -
   instead of through Paula's four 8-bit channels. On points AHI's unit
   0 and its Music unit at "RGB2RTG HDMI:HiFi 24 bit stereo++"; Off gives
   them their earlier modes back. On, low latency is for games: the
   same with "...stereo++ low latency", sound effects heard some 60 ms
   sooner; when the Amiga stalls (a window dragged, a disk read) there
   is one short gap, then it keeps a safe margin for 10 seconds and
   comes back down - for music, On is the steadier choice. It plays
   with Sound on HDMI off too
   (then without Paula). It needs AHI on the Amiga - CaffeineOS has it
   - and the installer puts my HDMI driver for it into DEVS:AHI when
   AHI is there. In Prefs/AHI you can pick "RGB2RTG HDMI:16 bit
   stereo++" or another frequency for a unit as well. Volume, Stereo
   and Left and right are for Paula's four channels only.
   A player that still drops out while you drag windows is starved by
   them itself: give it a priority above 20, where the system moves
   windows - in AmigaAMP's settings (System), Main and Playback 21 and
   a playback buffer of 1 s.

Low lag (Settings, or C:rgb2rtg LOWLAG=ON): 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). It needs HDMI
sync, and wherever it could not stay ahead of HDMI it falls back to
whole frames by itself. Off by default for now; once on, it stays on
(it was an Expert switch until the next power cycle in 0.75). A game it
does not suit can have it off on its own (A GAME'S OWN SETTINGS,
below).

PICTURE SIZE AND SHARPNESS
--------------------------
RGB2RTG menu - Settings. Its rows come in three groups. THIS AMIGA, the
first six, are for everything (the three marked * from the next power
cycle):
 * Video: PAL or NTSC (default: whatever your Amiga is) - the standard
          the Amiga starts in. Save sets config.txt for the next power
          cycle: HDMI at that standard's rate (1080p 50 or 60 Hz, when
          config.txt sets a rate at all), and, if it isn't your
          Amiga's own standard, Emu68's ntsc or pal overlay - so a PAL
          Amiga plays NTSC games at full speed, and the other way
          round. The picture's framing (NTSC has 200 lines where PAL
          has 256, and a different pixel shape) follows the standard
          the Amiga actually started in. Emu68's overlay also tells
          AmigaOS about the other crystal, so its clock runs 0.9% off
          in the other standard (NTP puts it right).
 * HDMI rate: 1x (default) - HDMI at the Amiga's rate, 1080p at 50 Hz
          (60 for NTSC), every frame shown once; 2x - twice that, 100
          Hz (120 for NTSC), every frame shown twice. 2x is for a
          display that flickers at 50 Hz. HDMI sync works with both:
          Fixed rate gives exactly 100 Hz, Follow Amiga keeps every
          other HDMI frame in step with the Amiga's (99.84 Hz for PAL).
          Like Video it's config.txt's: Save sets it for the next
          power cycle. Check first that your display takes 1080p
          at 100 Hz (120): one that doesn't shows nothing at all -
          see IF SOMETHING GOES WRONG. The status report's HDMI frame
          says 10000 us at 100 Hz. Pi 4 only: a Pi 3's HDMI cannot
          send 1080p that fast.
 * HDMI colours: Full (PC) (default) - colours 0-255, as PC monitors
          and anything on DVI want; Limited (TV) - the TV range, 16-235,
          for a TV that shows Full with crushed blacks or clipped
          whites. Like Video, Save sets it in config.txt for the next
          power cycle; it is the RTG desktop's too.
 * HDMI sync: Follow Amiga (set by the installer with HDMI at the
          Amiga's rate, on a Pi 4 and, since 0.75, on a Pi 3) - the
          HDMI frame moves in
          step with the Amiga's; Fixed rate - HDMI keeps its own
          rate, and every few seconds a frame is repeated or dropped.
 * VGA modes (31 kHz): Off (default) or On - the productivity screen modes
          (DblPAL, DblNTSC, Multiscan/Productivity, Euro72...) shown on
          HDMI, sharp and with the mouse pointer; Off shows them black,
          as before. New, and still a test. PAL and NTSC screens are
          not touched either way. Until the Workbench starts they are
          always on, whatever is saved: Kickstart 3.2's Early Startup
          menu in 31 kHz shows on HDMI after a power-on or a reset.
 * Eco mode: On (default) - nothing is drawn while only the RTG
          desktop is on HDMI, so the Pi stays cooler; the picture comes
          back the moment a native screen is in front. Off draws it all
          the time, as before.
Then Settings for, and under it the settings a game can have of its own -
first PICTURE:
 * Settings for: All games and demos (default) - the settings under it
          are for everything, the Workbench too; or one game or demo,
          which has them of its own (A GAME'S OWN SETTINGS, below).
 * Look:  Sharp (default) shows every Amiga pixel as a crisp block;
          Smooth filters the scaling.
 * Crop:  Standard - the normal screen, no border (640x256 in PAL,
          640x200 in NTSC); Overscan (default) - a little border, for
          games and demos that draw into it; Full frame - everything
          the chipset sends; Custom - what Crop... leaves: on the same
          screen as Position, cut each edge yourself (Tab picks the
          edge, the cursor keys or a drag move it), so that with Fill
          screen it is you, not the display, who decides what of the
          picture's edges is lost; Auto - the picture follows each game's
          own display window while it runs: no empty border, and with
          Fill screen the game's picture fills the display. It grows at
          once and shrinks after five seconds, so menus and fades don't
          make it jump; a game that keeps changing it back and forth
          keeps its biggest picture until you quit it. Not with
          scanlines.
 * Scale: 4:3 (default) - the shape a real monitor gives; Integer -
          whole-number scaling only, the sharpest; Fill screen -
          stretched to fill the whole display; 5:4 (square) - square
          pixels, as emulators offer them: a PAL screen (320x256) is
          5:4, an NTSC one (320x200) 16:10. On a 1280x1024 monitor a
          PAL screen fills it at exactly 4x - with the scanlines 4 HDMI
          lines to each Amiga line; 16:9, 16:10, 21:9 and 32:9 - the
          picture stretched to that shape, the same on every display:
          16:9 fills a TV (4K ones too), 16:10 a 16:10 monitor, 21:9 an
          ultrawide (2560x1080 exactly; a 3440x1440 one leaves hair-thin
          bars at the sides), 32:9 a super-ultrawide (3840x1080,
          5120x1440). On a display of another shape, bars stay at the
          top and bottom or at the sides.
 * TV border: Off (default), 2% to 10% - every picture on HDMI gets
          that much smaller, the desktop too, with a black frame
          around it: for a TV that cuts the edges off (see IF
          SOMETHING GOES WRONG). The pictures are scaled for it, so
          they're a little softer - leave it Off if your display shows
          everything. It sets both directions; for a TV that cuts more
          off one way, C:rgb2rtg BORDERX= and BORDERY= set each
          (Commands.txt).
 * Flicker fixer: On (default) - both fields of an interlaced screen
          woven into one steady picture; Off - a field at a time, the
          way the Amiga's own output shows them, flicker and all.
 * Low lag: Off (default) or On - HDMI shows each frame while the
          Amiga is still drawing it (see USING IT). Needs HDMI sync on
          Follow Amiga: on Fixed rate it is greyed out.
 * Position...: opens a calibration screen on HDMI - a grid, with a
          frame around the standard area (640x256 in PAL, 640x200 in
          NTSC). Drag the picture with the mouse, or move it with the
          cursor keys, W A S D or keypad 8 4 6 2 (hold Shift for
          bigger steps). The right mouse button or Return keeps the
          position, Esc puts it back. How far it can move depends on
          the crop; Full frame already shows everything, so there it
          can't move. PAL and NTSC each keep their own position: after
          changing the Video setting, set it once for the other
          standard too.
Then CRT LOOK:
 * Scanlines: dark lines between the Amiga's lines, like on a CRT -
          Off, 25%, 50%, 75% or 100%. Scanlines (interlace) sets them,
          with a strength of their own, for interlaced screens,
          which already have lines in between (Off suits most). The
          Pi's display hardware lays them over the picture, so they
          cost no speed.
 * Scanline shape (greyed out while both scanline settings are Off):
          Even (default), Crisp or Whole lines - where an
          Amiga line takes up no whole number of HDMI lines (Scale 4:3
          or Fill screen): Even gives every Amiga line the same
          darkness, a dark line shared by two HDMI lines where it falls
          between them; Crisp a whole dark HDMI line at the end of
          each, so some Amiga lines come out a line taller than others,
          and in a game that scrolls up and down the pattern seems to
          move; Whole lines makes the picture a little smaller, its
          shape kept, so that every Amiga line gets a whole number of
          HDMI lines - clean scanlines at low resolutions such as
          800x600 (there: 2 lines each, the picture 512 lines tall).
          With Integer all three are the same.
 * CRT mask: Off (default), Grille 25%, 50%, 75% or 100% - an aperture
          grille's fine dark columns over the whole picture, one every
          three HDMI columns (six at 4K), like a Trinitron or a PVM up
          close; together with the scanlines it gives a PVM's fine
          grid. It only darkens - it cannot filter the colours apart as
          a CRT's phosphors do. Brightness makes up for it.
 * Brightness: Normal (default), 110%, 120%, 135% or 150% - makes up
          for the scanlines' dark lines. The bright parts are eased
          into white instead of cut off, so near-whites stay apart.
 * Gamma: Exact (default) - the Amiga's colours as they are; CRT - the
          darker mid-tones and deeper shadows a CRT such as the 1084S
          gives the same colours (a CRT's gamma is about 2.5, a PC
          monitor's 2.2); Lighter - shadows and mid-tones lifted, white
          stays white: for a dark game or a dim screen. Brightness and
          Gamma change what HDMI shows - HAM, EHB, sprites, all of it -
          and not the Amiga's own RGB output.
Changes show at once. Save keeps them, Use keeps them until the next
reboot, and Cancel (or the close gadget) puts back what was there.
Help says in short what each one does.

A GAME'S OWN SETTINGS
A game or demo can have the picture's settings of its own - Look, Crop,
Scale, TV border, Flicker fixer, Low lag, the position, Scanlines,
Scanlines (interlace), Scanline shape, CRT mask, Brightness and Gamma. Start the
game once and quit it: Settings for then offers it next to All games and
demos - or Add... picks any game's or demo's drawer. Pick it, set its
picture and Save: from then on it gets its own whenever it starts, and
every other game the all-games ones. Remove gives it the all-games ones
again. Video, HDMI rate, colours and sync, VGA modes (31 kHz) and Eco
mode - THIS AMIGA's - stay the same for all. It works for what WHDLoad starts: the installer
puts a line in S:WHDLoad-Startup that gives the game its own settings,
and one in S:WHDLoad-Cleanup that puts the all-games ones back when you
quit - WHDLoad runs them when S:WHDLoad.prefs says so, as CaffeineOS's
does. A game is known by the name of its drawer; the settings of each
live in ENVARC:RGB2RTG/Games/. (The idea, and the window's way of doing
it, are AGA-PISTORM's.)

GOOD TO KNOW
------------
 * The sound on HDMI was tried on a Pi 4 and a Pi 3 with HDMI at
   1080p 50 Hz, through an HDMI audio extractor, in games and demos;
   with HDMI at twice the rate (100/120 Hz), in the 31 kHz modes and on
   AmigaOS 3.2 it is not tried yet - tell me how it goes. It is Paula
   as the Pi makes it again, so a program that plays its samples in an
   unusual way can sound a little different from the Amiga's own
   output, and the A1200's sound filters are not there yet.
 * Low lag is new in 0.75 and off by default. On a Pi 3 and a Pi 4 it
   raced 92 to 99 % of Jim Power's frames, about 8 ms behind the
   Amiga's own output; a frame it cannot race is shown whole, as
   without it, and an interlaced screen with the flicker fixer is
   always shown in whole frames. Should HDMI show a
   tear line - a few lines of the frame before - that the RGB output
   does not, switch it off and tell me the game.
 * PAL and NTSC screens are followed, whichever your Amiga is and
   whatever a program switches to. With HDMI at the other rate - an
   NTSC game on 50 Hz HDMI, or a PAL one on 60 Hz - frames get dropped
   or shown twice, so it judders a little: set Video (Settings) to
   what you play most.
 * The productivity screen modes - DblPAL, DblNTSC, Multiscan, Euro72
   and the like, 31 kHz and more - are followed when Settings'
   VGA modes (31 kHz) is On (still a test); when it's Off, such a screen is
   shown black. They run at their own rates (DblPAL 47 Hz, Productivity
   57 Hz, Euro72 68 Hz), so on 50 Hz HDMI a frame is now and then
   shown twice or left out. An interlaced one (DblPAL High Res Laced)
   is shown a field at a time. (The 31 kHz screen behind the
   CaffeineOS desktop doesn't matter - the desktop is in front of it.)
 * The HDMI picture is about one frame behind the real one.
 * Interlaced screens are woven: each picture is the newest
   field together with the one before it, as on a flicker fixer.
   Things that move fast in an interlaced screen show fine combs at
   their edges. Settings' Flicker fixer (C:rgb2rtg FLICKERFIX=OFF)
   shows them a field at a time instead.
 * With HDMI sync on, the display's frame rate moves by a fraction of
   a Hz to follow the Amiga (PAL 49.92 Hz; NTSC 59.28 Hz on a PAL
   A1200, 59.83 on an NTSC one). It does that by making a frame one
   line longer or shorter, about twice in 40 seconds (it used to be
   several times a second, which some LCDs showed as flicker on dark
   pictures). Nearly every display takes that without noticing. If
   yours blanks now and then, switch HDMI sync off in Settings.
 * Demo parts that run at exactly 50 Hz can drop one frame every few
   seconds: HDMI can follow the Amiga down, but not yet up.
 * Some demos rewrite their own code as they run (State of the Art
   does). Emu68 on its own would keep running the old code, and the
   picture would go wrong. The RGB2RTG kernel notices this and runs
   each instruction the demo keeps rewriting the careful way - on its
   own, checked before each run, as a 68000 would - until 5 seconds
   after the rewriting stops. Everything else runs at full speed.
   rgb2rtg.smc=off on the kernel's command line switches this off
   (Commands.txt, section 8).
 * Keep the Pi cool (a working fan) and at its standard clock. A Pi
   that overheats (around 80 C) or is overclocked throttles, and each
   time its clock stops for a moment - on the first test machine that
   was a hitch every second or two. RGB2RTG now makes up for the lost
   time, but a hot Pi is slower at everything.
 * The Amiga's own audio outputs keep working as always; the sound on
   HDMI is an option on top of them (RGB2RTG menu - Sound).
 * RGB2RTG needs no RGB cable, and the Amiga's own video output keeps
   working as always.
 * A demo started from the RTG desktop that takes over the display
   without telling the system - it loads its own copper list - is
   looked after by the kernel: HDMI switches to it, and it gets the
   standard PAL (or NTSC) display it was written for. CaffeineOS
   leaves a 31 kHz display behind the RTG desktop, and there such a
   demo showed only static, on the Amiga's own RGB port too, with
   garbled sound (Lamers' Shiva did). When the demo hands the display
   back, everything goes back as it was. C:rgb2rtg TAKEOVER=OFF leaves
   such programs alone (Commands.txt).
 * Bubble Bobble (WHDLoad) shows streaks and striped platforms: the
   game never sets one of its two bitplane modulos, and the screen
   WHDLoad shows at start leaves it at -2. The Amiga's own RGB output
   shows exactly the same - it's the game, not RGB2RTG.
 * PiStorm3D (MiniGL on the Pi 4's 3D GPU) works with RGB2RTG on a
   Pi 4 - its demos ran on my A1200 next to the RGB2RTG picture. If
   its programs start and end without showing anything, Picasso96's
   libraries are mixed: CaffeineOS has Picasso96API.library from
   Picasso96 3.x but rtg.library and emulation.library from 2.x
   (Version LIBS:Picasso96/rtg.library shows 40.x). Install all three
   from one Picasso96 - 3.6.3 worked here, with only "Libraries" and
   "Picasso96Mode" ticked in its installer; the screen modes needed
   no change. Keep a copy of LIBS:Picasso96 and
   LIBS:Picasso96API.library first.

UNINSTALLING
------------
Double-click Uninstall in the RGB2RTG drawer, then power cycle. It
puts back the previous kernel line in config.txt and your previous
VideoCore.card, takes the RGB2RTG block out of config.txt, puts back
the VideoCore monitor icon if Install changed it, and removes the
RGB2RTG menu, its lines in S:User-Startup and in WHDLoad's scripts,
the settings (games' own too) and C:rgb2rtg. The kernel file stays on the boot partition, where nothing
uses it any more.

IF SOMETHING GOES WRONG
-----------------------
 * The Amiga doesn't start, or the screen stays black: switch it off,
   put the SD card in a PC (if Windows offers to format a drive, click
   Cancel - see INSTALLING, step 2), double-click SD-Setup.cmd and
   choose Remove. It takes RGB2RTG out of config.txt exactly as
   Uninstall would. (By hand: copy config.txt.pre-rgb2rtg over
   config.txt, or delete the RGB2RTG lines and block and remove
   "#RGB2RTG-WAS: " from the old kernel= lines.) Your previous kernel
   then starts. If its RTG desktop doesn't come up (an older Emu68
   with my VideoCore 1.9), hold both mouse buttons at power-on, boot
   with no startup-sequence, and in the Shell: copy
   SYS:Libs/Picasso96/VideoCore.card.pre-rgb2rtg
   SYS:Libs/Picasso96/VideoCore.card
   Then double-click Uninstall in the RGB2RTG drawer for the rest -
   the RTG driver (yours back, if you had one), the menu, the
   S:User-Startup lines and C:rgb2rtg (see UNINSTALLING). Until then
   a requester at every boot says the kernel that started is not
   RGB2RTG's.
 * On a Pi 3 the A1200 starts on its own instead: the Kickstart
   screen (insert a disk) on its RGB output, HDMI black or the Pi's
   rainbow, and no hard disk in the boot menu (both mouse buttons at
   power-on). The Pi never started Emu68, and a PiStorm32-lite then
   leaves the A1200 to its own CPU. I met it with an AmigaOS 3.2 card
   that had been set up on a Pi 4. On a PC, in config.txt:
   - the SD card has a different overlay on each Pi: on a Pi 4
     dtoverlay=emmc,unit0=rw, on a Pi 3 dtoverlay=sdhc,unit0=rw - put
     each in its own section, [pi4] and [pi3], ending with [all];
   - a Pi 4's overclock (arm_freq=1800, over_voltage) goes into a
     [pi4] section too;
   - my Pi 3 A+ only started Emu68 with CaffeineOS's config.txt as it
     is, its own ROM line aside (I haven't found yet which of its lines
     it needs): boot_delay=1, bootcode_delay=1, gpio=0-27=ip and
     gpio=0-27=pu (the PiStorm's pins pulled up before Emu68 starts),
     and its PiStorm sections,
     [gpio4=0] and the rest, each with its own kernel= and initramfs
     lines. CaffeineOS's stealth firmware loaded for every PiStorm32-
     lite, outside its [gpio4=0] section, never started Emu68 here.
 * The RTG desktop doesn't come back after installing: in a Shell,
   copy SYS:Libs/Picasso96/VideoCore.card.pre-rgb2rtg over
   SYS:Libs/Picasso96/VideoCore.card and power cycle - and please tell
   me which driver you had.
 * Games and native screens never show on HDMI - it stays black, or
   on the RTG desktop: first, in a Shell, run C:rgb2rtg. Its first
   line names the kernel that is running (RGB2RTG and its version).
   If it says instead that this machine is not running the RGB2RTG
   kernel, the Amiga was reset rather than switched off and on after
   installing, config.txt starts another kernel, or the kernel was
   started with rgb2rtg=off. Further down, "picture on HDMI" must say
   ON (C:rgb2rtg ON switches it on). The line under it, "follower on
   core", must not say NOT running; if it says "no unicam overlay",
   config.txt needs dtoverlay=unicam,boot on a line of its own (see
   INSTALLING, "Installing by hand"). The VideoCore.card line must
   name the driver: "not loaded" there means Picasso96 did not load
   it - on a plain AmigaOS 3.x, see the VideoCore monitor under WHAT
   YOU NEED.
 * No sound on HDMI: in a Shell, run C:rgb2rtg - its "HDMI sound" line
   says how the sound plays, or why it doesn't. "the display gets DVI,
   not HDMI": switching Sound on puts hdmi_drive=2 into config.txt
   when the SD card's boot partition is mounted (C:rgb2rtg INSTALL
   CHECK shows it - if it isn't there, mount the partition the way
   your system does and switch Sound on again); then switch the Amiga
   off and on once.
   "no HDMI clock": power-cycle with the display on. A display's or an
   extractor's own volume and mute are not RGB2RTG's - nor is a TV
   input that is set to another sound source.
 * After Install the Workbench comes up on the Amiga's own screen and
   Prefs/ScreenMode lists no VideoCore modes: your modes were made with
   an older VideoCore driver. The VideoCore monitor icon needs the
   tooltype VC4_LEGACY_ID - Install adds it when it can tell; add it
   yourself (Icons menu - Information) if it could not. If the system
   puts screenmode.prefs back from a screenmode.prefs.PI file at every
   boot (CaffeineOS, AGS, MultibootOS's AmigaOS 3.2), a mode you save
   in ScreenMode is lost at the next boot: after saving, in a Shell,
     Copy ENVARC:Sys/screenmode.prefs RAM:sm
     Copy RAM:sm ENVARC:Sys/screenmode.prefs.PI
   (through RAM: - on these systems screenmode.prefs can be a link to
   the .PI file, and a Copy straight from one onto the other empties
   it).
 * HDMI stays on the RTG desktop when a game or a native screen should
   be on it: look at the tooltypes of the VideoCore monitor icon
   (DEVS:Monitors). DISPLAYCHAIN must not be NO - Picasso96 only hands
   HDMI over to native screens when the card is in the display chain
   (CaffeineOS has DisplayChain=Yes). The installer sets it to Yes
   (C:rgb2rtg INSTALL MONITOR; Uninstall puts the icon back). With the
   RGB2RTG kernel, VideoCore.card ignores VC4_SWITCH_METHOD and
   VC4_SWITCH_INVERT: the picture only reaches HDMI through its own
   switch (CSI). Before 0.7 either one could keep HDMI stuck on one
   picture - the RTG desktop never showing, or native screens never.
 * The display says "no signal" or "out of range" after installing, or
   after changing Video or HDMI rate: it doesn't take 1080p at that
   rate. On a PC, delete the three 1080p lines inside the RGB2RTG
   block of config.txt (hdmi_group, hdmi_mode, hdmi_force_mode). After
   HDMI rate 2x, then also set it back to 1x (Settings, or C:rgb2rtg
   HDMIRATE=1X), or the next Save writes the lines again.
 * On a TV, blacks look crushed or whites clipped since 0.73: the TV
   ignores the full-range colour RGB2RTG now sends. In Settings, set
   HDMI colours to Limited (TV), Save, and power cycle.
 * On a TV the desktop's edges are cut off, whatever its resolution:
   the TV enlarges 1080p 50 Hz, a TV mode, the way it does broadcast
   pictures (overscan). The sharpest fix is the TV's picture size
   setting: "Full Pixel", "Just Scan", "Screen Fit" or "Dot by Dot" -
   the name depends on the make (older Sony Bravias: Settings, Screen,
   Display Area). If there's no such setting, set a TV border in RTG
   Image (or C:rgb2rtg BORDER=4, Commands.txt) until nothing is cut
   off: every picture gets a little smaller, and 50 Hz is kept. Or
   delete the three 1080p lines inside the RGB2RTG block of config.txt
   (hdmi_group, hdmi_mode, hdmi_force_mode): HDMI then runs in
   CaffeineOS's own mode again, which the TV shows whole - but not at
   50 Hz, so PAL games judder a little.
 * The installer says the EMU68 partition is READ-ONLY: the kernel
   that runs doesn't let the Amiga write there. Emu68 1.0.x,
   CaffeineOS's own kernels and the RGB2RTG kernel take that from
   cmdline.txt on that partition (sd.unit0=rw and emmc.unit0=rw;
   CaffeineOS 9317 has both, in Boot/cmdline.txt). A stock Emu68 1.1
   kernel takes it from config.txt alone. From the Amiga nothing can be
   written there, so it takes a PC, once:
   - on a Pi 3: add dtoverlay=sdhc,unit0=rw to config.txt, on a line
     of its own, and copy Files/Overlays/sdhc.dtbo into the overlays
     folder (SD-Setup.cmd's Prepare does both), then run the installer
     again - it keeps the line, so the card stays writable;
   - on a Pi 4: copy Files/Kernel/Pi4/Emu68-rgb2rtg.gz
     into the card's kernel folder, point the PiStorm32-lite's kernel=
     line at it, make sure cmdline.txt has emmc.unit0=rw, then start
     the Amiga and run the installer again.
 * A game or demo stutters or looks wrong: in a Shell, run
   C:rgb2rtg >RAM:report.txt and C:rgb2rtg TRACE >RAM:trace.txt right
   after it, and send me both along with the name of the game or demo.

CREDITS AND LICENCES
--------------------
RGB2RTG by Astair86, made for the Amiga community. It builds on
AGA-PISTORM (also mine): its AGA chipset core draws the picture.

 * Emu68 by Michal Schulz (MPL-2.0) - https://github.com/michalsc/Emu68
   - with CrypticalCode0, Marcel Verdaasdonk, Marlon Beijer, Michael
   Rasmussen, Lukasz Winczura (Rondoval), captain-amygdala, Christophe
   Thibault, Adam Polkosnik, Michael Pye and Tom-Cat.
   RGB2RTG is not part of Emu68, and not made, endorsed or supported by
   Michal Schulz or the Emu68 project: please send anything about the
   RGB2RTG kernel to me, not to them.
   The RGB2RTG kernel is Emu68 1.1.0-beta.1 (git 0ba3a89) with RGB2RTG
   added. RGB2RTG's source and its patch are in Source/; the complete
   Emu68 source it is built from is RGB2RTG-0.5-emu68-src.tar.gz
   (the Emu68 part has not changed since 0.5; published again with
   0.6).
   Emu68's own files keep their MPL-2.0 notices; the kernel as a whole
   - Emu68 with RGB2RTG's GPL-2.0 code - is distributed under the
   GPL-2.0, which the MPL-2.0 allows (its section 3.3).
 * Capstone (its M68K part is Musashi), libdeflate, and code from
   the PiStorm project, BSD, AROS and the PowerPC ROM, built into
   Emu68 - their licences and notices are in Licenses/.
 * VideoCore.card, the RTG driver, by Michal Schulz (Emu68-tools,
   MPL-2.0), with changes by Astair86 - the source of this build is
   in Source/.
 * The chipset core contains code from UAE and WinUAE - by Bernd
   Schmidt, Alessandro Bissacco, Toni Wilen and the UAE contributors
   (GPL) - https://www.winuae.net: its blitter and copper are UAE's,
   and so are parts of its bitplane, sprite and collision code, copied
   or translated into C; much of it is the older UAE code kept in
   E-UAE. What comes from where, and their notices, are in
   Licenses/UAE-WinUAE-notice.txt.
 * Sound on HDMI (kernel/rgb_hdmi.c, taken over from AGA-PISTORM's
   arm/aga_hdmi.c) follows the Linux kernel's VC4 HDMI audio driver,
   drivers/gpu/drm/vc4/vc4_hdmi.c from the Raspberry Pi kernel
   (GPL-2.0-only; Copyright (C) 2015 Broadcom, (c) 2014 The Linux
   Foundation, (C) 2013 Red Hat): its start, stop and register
   values, rewritten for Emu68 with a DMA ring of its own. arczi84's
   emu68-hdmi-audio showed first that HDMI sound can work under
   Emu68 - thank you! Its HiFi sound - 24 bits, the rates and the
   screen's EDID, the AHI driver (tools/ahi) and band-limited Paula
   (kernel/rgb_blep.h, the same idea as WinUAE's "sinc" sound
   interpolation) - is taken over from AGA-PISTORM 1.114 as well. The
   LED filter on HDMI (kernel/rgb_ledfilter.h) is WinUAE's filter model
   (audio.cpp; its filter algorithm by Antti S. Lankila), by way of
   AGA-PISTORM 1.114 - see Licenses/UAE-WinUAE-notice.txt.
 * The PiStorm by Claude Schwarz, and the PiStorm community; the
   PiStorm600 by Lemaru - https://github.com/LemaruX/PiStorm600
 * CaffeineOS by Capt. LeChuck.
RGB2RTG itself is GPL-2.0 (Licenses/GPL-2.0.txt).


NOTICE! USE IT AT YOUR OWN RISK
---------------------------------
This is still a young project. It changes how your Amiga boots
(config.txt on the SD card), so please make a backup first. It comes
with no warranty of any kind (GPL-2.0, sections 11 and 12).


AI
--

AI was moderately used for debugging this since i have previously made the tools anyway. It is what it is, if you dont like it dont use it!


PRE-ROADMAP
-----------
Next, before the roadmap below:
 * Low lag on by default, once it has been tried widely (it is a
   saved setting now, in Settings).
 * Hotkeys in games: scanlines, the sound on HDMI, Low lag or HDMI
   sync on and off while a game runs, with a short message on HDMI.


ROADMAP
-------
 * Roadkill's vehicle select shimmers a little with the flicker fixer
   (an interlaced screen; without the flicker fixer it is steady).
 * Super Stardust: patches on HDMI during explosions.
 * A colour depth setting in VideoCore.card.
 * HDMI timing with room above 50 Hz, for demo parts at 50.08 Hz.
 * The 31 kHz modes: from a test to on by default, and their
   interlaced ones woven.
 * 9 Fingers and Pang (WHDLoad) without setting the JIT by hand (the
   careful mode doesn't notice their code rewriting yet).
 * The remaining microstutters in some demos (Starstruck).
 * An option in the CaffeineOS toolbar.
 * Low lag for interlaced screens with the flicker fixer (they are
   shown in whole frames for now).
 * AmigaOS 3.2 on a Pi 3 without CaffeineOS's config.txt lines (see
   IF SOMETHING GOES WRONG): which of them a Pi 3 still needs, now
   that the kernel pulls the PiStorm's pins up itself.
 * A slot mask next to the CRT mask's aperture grille: its pattern
   changes from row to row, so it needs a whole picture of memory
   instead of the grille's one row.
 * Later, a bigger one: CRT shaders through the Pi 4's 3D GPU (V3D) -
   phosphor colours, glow, curvature - between the Amiga's picture and
   HDMI. PiStorm3D shows that the GPU can be driven without Linux;
   mine would be my own code, in the kernel.


Discord server with awesome ppl can be found here: https://discord.gg/b5kuSrDZgs
                                     Pistorm here: https://discord.gg/HCDyDJ897

Very special thanks to Angelclaww (The Diplomat), katzazakis, Shaytan,
Michael Gruber (his install guide for AmigaOS 3.2), BomberMan1989pl and
many others for testing stuff out! 
