Introduction

If it wasn't absolutely clear to everyone here that I'm a man who does not believe in half-measures, this PR should really drive that home! 😎 🚬

This started as something quite innocent: I only wanted to expand upon kcgen's excellent vgaonly work to add proper double-scanning to all VESA modes (see this ticket #2604) because it was annoying me that late DOS era demos that use high-colour modes appeared single-scanned... like an EGA monitor 😬 Plus I wanted to fix the logging on video mode changes so it logs the dimensions of the actual video mode, not the render buffer.

Sounds easy right? It turns out it was a case of having to take 10 steps back and take a quite different route just to be able to take one step forward. I discussed this with kcgen, his work was mostly based on heuristics and patching things up here and there, but that approach wasn't really maintainable and scalable; continuing down that track would've resulted in a huge unmaintainable mess. Still, without him bravely forging the path ahead, I would never have dared to touch the scary beast that is vga_draw.cpp!

So one thing lead to another, and suddenly I've sunk easily 150+ hours into this over the last month or so... Running literally thousands of test cases (see test cases below), fun stuff like that 😎 I'm still in recovery mode, refactoring this was exhausting...

To make sense half of all this, you need to be quite familiar with CGA/EGA/VGA... especially with VGA, the custom "Mode X" tweak mode stuff, and how double-scanning of VGA adapters affect image quality on real CRT monitors. Otherwise, you'll just need to trust me 😎 🤘🏻

I've tested things quite extensively over and over again, so I'm quite confident in these changes, but of course it's not impossible that some edge cases are broken. However, with the new, better structure in place, it will be much easier to fix problems with one specific video mode on one adapter without breaking random stuff on other adapters. That's not the case in current main...

Overview

Ok, so main changes in a nutshell (well, it's a rather large nut... 😅 🥜 )

REVIEW BY COMMIT IF YOU VALUE YOUR SANITY!!! I've put considerable effort in coming up with a relatively logical and clean history (I must have spent several full days just reorganising stuff with rebase...)

Double-scanning

• The force_vga_single_scan setting has been moved to the [render] `section.

• force_vga_single_scan can now be toggled at runtime and it gets activated on the next video mode change (which I find pretty cool).

• All VESA modes supported by DOSBox are now double-scanned according to the mode table in int10_modes.cpp (tested with vesa_modes = all and vmemsize = 8). Naturally, the same goes for all non-VESA SVGA modes too on all supported SVGA adapters.

• CGA, PCjr & Tandy text modes are now properly single-scanned.

• The determination of whether a given VGA mode should be double-scanned or not should be almost perfectly correct now (I just don't dare tempt the devil by saying it's 100% 😈 🔥 ). This is because double-scanning is now controlled by the state of VGA registers for the most part instead of various image dimension and BIOS mode based heuristics. This has been tested with demos and various emulators (RealSpec, CCS64) that set up wacky custom modes to for example achieve a single-scanned look with around 300-lines of resolution at 85Hz+ refresh rates... Yep, all that works, in addition to all the games and demoscene productions that use strange custom modes on VGA!

Pixel-doubling

• Sub-640 pixel wide video modes are always pixel-doubled now by default. This is needed to achieve more accurate CRT emulation with virtually all current CRT shaders in existence. For example, on a real monitor there should be zero difference between a 320x200 image displayed in a 320x200 video mode, or the same image width-doubled and displayed in a 640x200 mode. Without pixel-doubling, we would have a very noticeable difference with current CRT shaders that don't take such differences into account, resulting in horizontally blurrier image for the 320x200 video mode case (there are some image comparisons on this below).

• A new force_no_pixel_doubling render setting is also available to disable this behaviour. This might be useful for optimising performance on low-powered devices, or to emulate a really blurry consumer CRT monitor or TV set.

• See these threads for my discussions with prominent shader authors / people
  with an intense interest in accurate CRT emulation on the matter:

  • Discussion on Vogons with lots of interesting technical detail about analog monitors:
    https://www.vogons.org/viewtopic.php?f=63&t=94909
  • My question to Guest (author of the "CRT Advaned Guest" shader, one of the best CRT shaders around):
    https://forums.libretro.com/t/new-crt-shader-from-guest-crt-guest-advanced-updates/25444/3591?u=rincewind
  • Guest's very informative reply:
    https://forums.libretro.com/t/new-crt-shader-from-guest-crt-guest-advanced-updates/25444/3592?u=rincewind

• VileR was kind enough to confirm the above by taking some actual photos of his CGA monitor in 320x200 and 640x200 modes: https://www.vogons.org/viewtopic.php?p=1174367#p1174367

• The TL;DR is that pixel-doubling of roughly sub-640 pixel wide content is necessary to achieve an authentic CRT look with currently available CRT shader technology, without having to maintain a set of different shaders and switch between them manually depending on whether you're playing a game that uses ~320 or ~640 pixel wide modes. Plus I find the multi-shader approach a non-solution when using DOSBox as a computer emulator because a shader optimised for ~320-pixel-wide content would look off in ~640-pixel-wide modes, and vice versa.

Shaders

• Introduced two new shader pragmas, force_single_scan and force_no_pixel_doubling, so shaders can explicitly request single-scanning and no pixel-doubling if this would make no visual difference (we cannot determine this upstream, only the shader author can make this decision). The default "sharp" shader is such an example; this allows for finer scaling granularity with integer scaling enabled, and there are 4x less pixels to process by the shader which can make a big difference on low-powered devices.

• The default interpolation/sharp shader has been updated to force single-scanning and no pixel-doubling. This ensures there's zero negative performance impact on people who are content with just using the defaults.

• These pragmas also for cool possibilities, e.g. to make a "Commodore monitor" shader that forces single-scanning and no pixel-doubling.

Logging of current video mode

• The removal of vgaonly broke the logging of the video mode dimensions because only the rendered image dimensions were available downstream, so we got things like MCGA 640x400 (mode 13h) in the logs which is super-confusing and incorrect. That is now fixed; e.g., for mode 13h we get VGA 320x200 (mode 13h) as we should.

• The logging of video modes is now a lot more accurate in general; now we're consistently logging the video standard the mode first appeared in (e.g., CGA modes should be always CGA, regardless of the emulated display adapter in use).

• If there's ambiguity regarding the video mode (e.g., the actual source image dimensions don't match the nominal dimensions of the BIOS video mode), we omit the (mode XYh) part from the logs to avoid confusing the user. The most noticeable side effect of this is that we no longer log weird stuff like MCGA 360x240 (mode 13h) which is clearly not mode 13h but a tweaked VGA mode---it's just mode 13h was used as a starting point to tweak the mode further. Stuff like that gets simply logged as VGA 360x240 now.

• Another subtle but important detail: now the pixel aspect ratio of the video mode gets logged, not whatever pixel aspect ratio we derive from the rendered image's dimensions for rendering purposes.

• Composite CGA/Tandy/PCjr modes in particular are being logged more accurately, and we get video mode change log message when toggling composite modes.

Image capture

If the below points don't make much sense, it's time to refresh your memory about the new enhanced & revamped image capture feature: #2503

• Because now the dimensions and PAR of the video mode get propagated downstream, the image capturer can write the correct metadata tags into the images (this was just as incorrect as the logging of the current video mode's dimensions).

• The raw image capture mode now really means raw; e.g., a 640x200 image isn't height-doubled like before but simply written as a 640x200 pixel-raster, end of story. This is the logical conclusion of the new revamped image capture functionality; the upscaled aspect-ratio preserving, "sharp" upscaled output is the default, this is what most people should use. The raw mode that corresponded to the "legacy" DOSBox screenshot capture functionality break compatibility with it on purse; this mode is really just there for special needs when you must capture the original, unaltered pixel-raster data.

• The image capturer now always uses the dimensions of the video mode as the basis of performing the upscaling (as opposed to the dimensions of the rendered image, as done previously). In some cases (when dealing with "baked in" double-scanning) this can result in hitting the target ~1200px of upscaled vertical resolution better (because we can effectively use 2x finer vertical integer scaling steps for "baked-in" double-scanning).

• Naturally, and following from the previous point, all combinations of pixel-doubling, "fake" double-scanning, real "baked-in" double-scanning are handled 100% correctly as you would expect during image capturing. Basically, the results for the same video mode should always be completely identical, regardless of these rendering side variations.