Rework "EGA mode with VGA palette" CRT shader auto-switching

[johnnovak]

Description

The auto-switching to VGA shaders for EGA modes with custom VGA palettes on emulated VGA adapters worked when launching games, but kinda by fluke. It was only reliable on text mode to EGA graphics mode transitions, but only by sheer luck... Things then started falling apart when using an image viewer such as QPV.

Definitely review commit by commit; the first commit is just about removing warnings and is very noisy.

It's a bit hard to explain succinctly why the implementation needs to be done in this particular way. I've spent about 5-6 hours just tracing through the code to figure out how the Rube Goldberg mode-switching machinery works... I understand it now, but I don't want to write 10 pages to explain which no one would bother to read anyway... 😝 Please read the comments and the commit messages if you want to understand it deeper what's really going on.

The high-level overview is that I tried to be a bit too clever previously when detecting non-EGA colours; now it just checks the new colour against all possible EGA colours whenever the program changes a VGA DAC palette entry.

I don't really expect anybody to go through my manual testing steps in detail, but it forces me to do a thorough job, and it will be useful for regression testing later if needed.

Could this all be done in a simpler and more straightforward way? Sure. After spending 5k+ hours refactoring the whole VGA code, everything VGA-related should be simpler. See you in 2050 😎 🤘🏻

Related issues

Original PR:

crt-auto should auto-switch to VGA shaders in EGA modes with 18-bit VGA palettes
#2819

Manual testing

General testing

Used the following specially prepared test pics in QPV: test-pics.zip

Grafx2 is great for such manipulations of paletted/bitplane-based graphics.

MONKEY1.IFF

320x200, 16-colour, EGA palette in canonical EGA colour order.

MONKEY2.IFF

320x200, 16-colour, EGA palette, but with bright cyan missing.

SQ3.IFF

320x200, 16-colour, EGA palette, but with brown missing and a completely different colour ordering.

MAGICWLD.IFF

320x200, 16-colour, non-EGA palette.

SCOOPEX.IFF

320x200, 16-colour, non-EGA palette.

---

Make sure QPV is configured for EGA modes. You should have something like this in QPV.CFG:

# 16-colour EGA/VGA modes
 320  200   16     40 $0d 0
 640  200   16     80 $0e 0
 640  350   16     80 $10 0
 640  480   16     80 $12 0

Turn off auto resolution (# key) and select the 320x200 16-colour mode (with the + and - keys).

Test 1

With the default config:

• Press enter on MONKEY1.IFF — EGA shader gets picked.
• Press Esc to return to the 640x480 interface screen.
• Press enter on MONKEY2.IFF — EGA shader gets picked.
• Press Esc.
• Press enter on SQ3.IFF — EGA shader gets picked.
• Press Esc.
• Press enter on MAGICWLD.IFF — VGA shader gets picked.
• Press Esc.
• Press enter on SCOOPEX.IFF — VGA shader gets picked.

Test 2

With the default config:

• Press enter on MONKEY1.IFF — EGA shader gets picked
• Press enter to advance to MONKEY2.IFF — This involves no scree mode change, but as the image still contains EGA colours only, the EGA shader remains active.
• Press enter to advance to SCOOPEX.IFF — This contains VGA colours, so the VGA shader gets selected.
• Press enter to advance to SQ3.IFF — This has EGA colours, but no screen mode change is involved, so we're stuck with the VGA shader.
• Press Esc and then Enter to display SQ3.IFF but trigger a screen mode change — EGA shader gets picked.

Test 3

Repeated the above tests with different glshader and machine settings:

• glshader = none & sharp — Works as expected.
• glshader = crt-auto-arcade & crt-auto-arcade-sharp — The single-scanned arcade shaders get always picked.
• glshader = crt-auto-machine & machine = vga — Always the VGA shader gets picked.

Test 4

• Use the default config, then start Deluxe Paint in EGA 640x350 16 colors mode (option "e").
• EGA shader gets picked.
• Open the palette editor with the P key, then start dragging the RGB sliders around.
• DPaint snaps the colours to the 64-colour EGA palette, so no shader switching will take place.
• Repeat the test in the VGA 640x350 16 colour mode (option "j"). This mode allows setting VGA colours for this EGA screen mode.
• The EGA shader gets picked initially, but once you start dragging the RGB sliders, the shader auto-switches to VGA.
• Repeat the steps in the 320x200 16 colour mode on EGA vs VGA.

Test 4

Tried a few games with the default config plus cga_color = colodore:

• Dark Seed — VGA shader gets picked
• Gods — VGA shader gets picked
• Space Quest 3 — EGA shader gets picked & the custom colours are displayed correctly.
• Spellcasting 201 — EGA shader gets picked & the custom colours are displayed correctly.

Test 5

Regression tested Total Eclipse in Hercules, CGA, CGA Mono, and Tandy modes with the appropriate machine settings.

"True EGA"

Confirmed that the below "true EGA" games pick the EGA shader with crt-auto on a VGA adapter:

• Command Keen: Keen Dreams
• Drakkhen
• Space Quest II
• Wasteland
• Spellcasting 201 — Picks an EGA shader as the game uses the 640x350 16-colour EGA mode (out of a total palette of 64 possible colours).
• Plus a good selection of the test cases from here

EGA modes with VGA palette

Confirmed that the below games that use EGA modes with custom VGA palettes pick the VGA shader with crt-auto:

• Gods — 320x200 16-colour EGA mode but with a VGA palette. The game switches to an EGA mode at startup, then loads the VGA palette only a few seconds later (the shader switching happens then).
• Dark Seed – The game uses 640x350 but with a custom 16-colour VGA palette. Before this PR, an EGA shader was picked incorrectly for this game (the difference is very subtle, but still not quite correct).
• Plus a good selection of the test cases from here

Checklist

Please tick the items as you have addressed them. Don't remove items; leave the ones that are not applicable unchecked.

I have:

• followed the project's contributing guidelines and code of conduct.
• performed a self-review of my code.
• commented on the particularly hard-to-understand areas of my code.
• split my work into well-defined, bisectable commits, and I named my commits well.
• applied the appropriate labels (bug, enhancement, refactoring, documentation, etc.)
• checked that all my commits can be built.
• confirmed that my code does not cause performance regressions (e.g., by running the Quake benchmark).
• added unit tests where applicable to prove the correctness of my code and to avoid future regressions.
• made corresponding changes to the documentation or the website according to the documentation guidelines.
• locally verified my website or documentation changes.

[johnnovak]

Ping @FeralChild64 @weirddan455 @kklobe, can any of you review this over the next week or so? I only need one person at least 😄 Don't be afraid of it, it's short and only reviewing it at the surface-level is better than nothing. I don't expect anyone to become DOSBox VGA code experts overnight (I'm not one either 😏)

The reasons I'm pinging you is because this needs to go into the final.

[japsmits]

Two code modernisation hints. Approved anyhow, should you decide to ignore them.

[kklobe]

OK, I ran through the manual testing steps to compare against main, nice work!

[kklobe]

approved even sans-const 😁

[johnnovak]

approved even sans-const 😁

Thanks @kklobe . Just force-pushed that minor change into the last commit.