Description

A bunch of mostly non-functional changes separated out of my upcoming viewport resolution/ aspect ratio enhancement PR.

Definitely review by commit.

Main changes:

• SDL_Rect is not leaking into the core emulation layers anymore; I've introduced a custom Rectangle type for this purpose.
• In 99% of cases there was no differentation between logical coordinates (device independent coordinates) and physical coordinates (device coordinates, physical pixels) in SDL main. This is very bad because you can never be sure what you're dealing with just by looking at the variable/function names, and it was making me quite upset after hacking sdlmain for a while... I've clarified the namings in the areas of sdlmain that I'm touching in my other PR directly or indirectly. About 80% of the code is still a mess, but it's a start...

For people who are not experienced with logical/physical coordinates, here's a quick rundown:

Using logical coordinates is the way forward for most use cases now that high DPI displays are increasingly the norm, especially for general GUI development and scalable vector graphics. You just use logical coordinates and things work fine on high DPI displays (if your framework is good), no need to think about it (that's what I'm doing in my other GLFW + OpenGL based programs that feature scalable vector graphics, and I can confirm, ThingsJustWork(tm)).

But when you're dealing with bitmap graphics and OpenGL, you need to deal with physical pixels as well. Also, understanding how things to map to physical pixels is important because of the OpenGL shaders, for instance. So the code will be naturally a mixture of logical and physical units, therefore we must encode the units in the variable and function names, otherwise you can only guess things when reading the code.

Should I multiply this quantity by the DPI scale factor?
Should I not? 😕
Should I divide it by the DPI factor? 🤔

It's anyone's guess if the var is just called something like sdl.clip.w! 🥶

That is bad, very bad, and it results in copious amounts of trace logging and intense hair loss during a compressed duration of time. Now, you don't wish that on your fellow devs, do you? 😎

So the system I started adopting is as follows:

• In sdlmain we're dealing with a mixture of logical and physical coords. That's normal and it's never gonna change. As using logical coords is the preferred and recommended default these days (for the best possible reasons), names like width and get_width mean logical coordinates, while width_px, and get_width_in_pixels means—I'm sure you can figure that out 😎 SDL has also started adding the *InPixels postfix to function names in its API (although I'm not sure how consistent they are with that).
• In all other parts of the emulation code, we should not deal with logical units at all, this being a computer emulator that deals with emulated framebuffers, raw pixel arrays, and so on. So in other parts, there is no need for the _px and _in_pixels postfixes; it's implicit that width, height, etc. are always in pixels in the core layers. I stress it again: only sdlmain should deal with logical pixels! (Well, and the upcoming OSD layer as well, because it will draw the UI as scaleable vector graphics, but that's for later and it's another special case 😎)
• Another special case is passing windowing system related parameters, so for example canvas and viewport dimensions and similar quantities into the core emulation layer (e.g., the shader manager needs to know of the canvas dimensions in physical pixels to select the appropriate shader). So in order to avoid ambiguity, we still use the _px postfix for function arguments that have anything to do with window sizes, canvas sizes, viewport dimensions, etc. Can be a little bit redundant in some cases, but I'd rather be a little redundant than a little confusing 😄

I'm hoping this is all not much controversial 😄 I don't think this is wasted effort because we don't know when we'll migrate to SDL3, plus clarifying the current sdlmain mess would help the transition effort too (I'm sure some of the current code could be (will be?) even lifted into the SDL3 branch).

Manual testing

Tried the shaders and the various integer scaling and viewport resolution modes, fullscreen / windowed, etc., and there are no regressions.

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.