Merge pull request #576 from DanielGibson/imgui-rebased

Integrate Dear ImGui and implement a new settings menu with it and much more

also replaced zlib with miniz, HiDPI support, lots of new configuration options

Changelog.md

@@ -4,6 +4,32 @@ dhewm3 Changelog
 Note: Numbers starting with a "#" like #330 refer to the bugreport with that number
       at https://github.com/dhewm/dhewm3/issues/
 
+1.5.4 (WIP)
+------------------------------------------------------------------------
+
+* A brand new settings menu that uses [Dear ImGui](https://github.com/ocornut/imgui).  
+  Can be opened with `F10` (unless that key is bound already) or by entering `dhewm3Settings`
+  in the console. It has lots of settings that the original options menu doesn't have and
+  can be easily navigated with gamepad or keyboard (or the mouse, of course).
+  It can also be opened while in the game, which then is paused (if Single Player) but still visible,
+  so the effect of most graphics settings can be seen immediately.
+  Needs SDL2 and C++11.
+* Replaced dependency on (external) zlib with integrated [miniz](https://github.com/richgel999/miniz)
+* HighDPI/Retina support
+* Allow inverted mouse look (horizontally, vertically or both) with `m_invertLook`
+* CVar to allow always run in single player (still drains stamina though!): `in_allowAlwaysRunInSP`
+* VSync can be enabled/disabled on the fly, without restarting the renderer (still with `r_swapInterval`
+  or in the menu, of course; needs SDL2)
+* Allow enabling/disabling [HRTF](https://en.wikipedia.org/wiki/Head-related_transfer_function)
+  with `s_alHRTF`
+* `s_alOutputLimiter`: Configure OpenAL's output-limiter which temporarily reduces the overall
+  volume when too many too loud sounds play at once, to avoid issues like clipping
+* `s_scaleDownAndClamp`: Clamp and reduce volume of all sounds to prevent clipping or temporary
+  downscaling by OpenAL's output limiter
+* If `r_windowResizable` is set, the dhewm3 window (when in windowed mode..) can be freely resized.
+  Needs SDL2; with 2.0.5 and newer it's applied immediately, otherwise when creating the window.
+
+
 1.5.3 (2024-03-29)
 ------------------------------------------------------------------------
 

Configuration.md

@@ -14,6 +14,33 @@ and a short description of what it does.
 Starting dhewm3 with the commandline argument `-h` (for example `dhewm3.exe -h`) will show some
 useful commandline arguments, for example how to tell dhewm3 where the game data can be found on your system.
 
+## dhewm3 Settings Menu
+
+When built with [Dear ImGui](https://github.com/ocornut/imgui) integration (which is the default
+when using SDL2), dhewm3 has an advanced settings menu with many settings that the main menu doesn't
+offer, including a *Control BIndings* menu that supports as many keys per command as you want and is
+fully navigable with keyboard or gamepad (or mouse, of course).
+
+Unless you have already bound your `F10` key to something else, it will open this menu.  
+If you `F10` key is already in use, you can either unbind it (in the old Options -> Controls menu),
+or open the dhewm3 settings menu by entering `dhewm3Settings` in the console - within that menu,
+you can also bind opening it to any other key.
+
+*By the way:* An especially nice feature of the dhewm3 Settings Menu is that you can **open it while
+your're in the game**. The game is be paused (if you're playing Single Player) but is still on the
+screen, so you **when you modify *Video Options* like *brightness* you can see the effect in realtime**!
+Is this cool or what? B-)
+
+Even though *using ImGui menus with a **gamepad*** is quite intuitive (basically use the DPad to navigate
+and `A` to select and `B` to cancel; in the *Control Bindings* menu read the *Usage Help* section
+for for things specific to that menu), the sheets on https://www.dearimgui.com/controls_sheets/
+might be useful for advanced tricks (note however that not all features are available on PC, it seems like
+there's no on-screen keyboard and I'm not sure whether controlling the mouse cursor with the PS4/5
+touchpad works).
+
+More information for *using ImGui menus with **keyboard and/or mouse*** can be found
+[here](https://github.com/ocornut/imgui/blob/v1.90.7/imgui.cpp#L126)
+
 ## The Console
 
 Like most id Software games from Quake 1 on, Doom3 has a console that allows entering commands 
@@ -145,14 +172,22 @@ This can be configured with the following CVars:
 
 - `r_screenshotFormat` What format screenshots should be in:
   `0` = TGA (default), `1` = BMP, `2` = PNG, `3` = JPG
-- `r_screenshotJpgQuality` Quality when using JPG screenshots (`0` - `100`)
-- `r_screenshotPngCompression` Compression level when using PNG screenshots (`0` - `9`)
+- `r_screenshotJpgQuality` Quality when using JPG screenshots (`1` - `100`). Lower value means smaller
+   image file but worse quality (default is `75`)
+- `r_screenshotPngCompression` Compression level when using PNG screenshots (`0` - `9`). Higher levels
+  generate smaller files, but take noticeably longer; `3` (the default) seems to be a good compromise.
 
 ## Other CVars added in dhewm3
 
 - `g_hitEffect` if set to `1` (the default), mess up player camera when taking damage.
    Set to `0` if you don't like that effect.
 
+- `m_invertLook` allows inverting mouse look: `0`: don't invert (this is the default),
+  `1`: invert up/down (flight controls), `2`: invert left/right, `3`: invert both directions
+
+- `in_allowAlwaysRunInSP` Allow always run (`in_alwaysRun`) and toggle run (`in_toggleRun`) in
+  Single Player as well - keep in mind you may run out of stamina!
+
 - `in_nograb` if set to `1`, the mouse isn't grabbed when ingame. Not overly useful for normal playing
   (unless maybe you play with a gamepad), but very useful for debugging. Default is `0`.
 - `in_grabKeyboard` if enabled (`1`), grabs all keyboard input if mouse is grabbed, so keyboard shortcuts
@@ -165,13 +200,32 @@ This can be configured with the following CVars:
 - `in_kbd` allows you to set your keyboard layout so the console key works better. Mostly useful with SDL1.2
 - `in_tty` tab completion and history for input from the **terminal** (on Unix-likes, like Linux, macOS, BSD, ...)
 
-- `r_fullscreenDesktop` `0`: "real"/"exclusive" fullscreen mode, might switch screen resolution  
+- `r_fullscreenDesktop` configures fullscreen windows (when `r_fullscreen` is `1`).  
+  `0`: "real"/"exclusive" fullscreen mode, might switch screen resolution  
   `1`: "desktop" fullscreen mode, which keeps desktop resolution and is more like a borderless fullscreen window
+- `r_windowResizable` if set to `1` (the default), the dhewm3 window (when in windowed mode..)
+   can be freely resized. Needs SDL2; with 2.0.5 and newer it's applied immediately, otherwise when
+   creating the window (startup or `vid_restart`).
 - `r_fillWindowAlphaChan` Make sure alpha channel of windows default framebuffer is completely opaque
   at the end of each frame. Needed at least when using Wayland.  
   `1`: do this, `0`: don't do it, `-1`: let dhewm3 decide (default)
 
 - `r_useCarmacksReverse` Use Z-Fail ("Carmack's Reverse") when rendering shadows (default `1`)
 - `r_useStencilOpSeparate` Use glStencilOpSeparate() (if available) when rendering shadow (default `1`)
+- `r_scaleMenusTo43` Render full-screen menus in 4:3 by adding black bars on the left/right if necessary (default `1`)
 
 - `s_alReverbGain` reduce strength of OpenAL (EAX-like) EFX reverb effects, `0.0` - `1.0` (default `0.5`)
+- `s_alHRTF` Enable [HRTF](https://en.wikipedia.org/w/index.php?title=Head-related_transfer_function)
+   for better surround sound with stereo **headphones**. `0`: Disable, `1`: Enable, `-1`: Let OpenAL decide (default).  
+   *Note* that OpenAL may automatically enable HRTF when it detects headphones, and it can happen that
+   it detects regular stereo speakers as headphones (when they're plugged into a jack that's somehow
+   labeled as headphone jack) - in that case you'll want to explicitly disable it.
+   The *Audio Options* tab of the [dhewm3 Settings Menu](#dhewm3-settings-menu) shows OpenAL Info,
+   including the current HRTF state (if supported by your OpenAL version).
+- `s_alOutputLimiter` Configure OpenAL's output-limiter which temporarily reduces the overall volume
+  when too many too loud sounds play at once, to avoid issues like clipping. `0`: Disable, `1`: Enable, `-1`: Let OpenAL decide (default)
+- `s_scaleDownAndClamp` Clamp and reduce volume of all sounds to prevent clipping or temporary downscaling by OpenAL's output limiter (default `1`)
+
+- `imgui_scale` Factor to scale ImGui menus by (especially relevant for HighDPI displays).
+  Should be a positive factor like `1.5` or `2`; or `-1` (the default) to let dhewm3 automatically
+  detect an appropriate factor.

README.md

@@ -35,6 +35,7 @@ Compared to the original _DOOM 3_, the changes of _dhewm 3_ worth mentioning are
 - Better support for widescreen (and arbitrary display resolutions)
 - A portable build system based on CMake
 - (Cross-)compilation with MinGW-w64
+- An advanced, mod-independent settings menu (opened with `F10` by default)
 
 See [Changelog.md](./Changelog.md) for a more complete changelog.
 
@@ -59,15 +60,14 @@ See https://dhewm3.org/#how-to-install for game data installation instructions.
 ## Configuration
 
 See [Configuration.md](./Configuration.md) for dhewm3-specific configuration, especially for 
-using gamepads.
+using gamepads or the new settings menu.
 
 ## Compiling
 
 The build system is based on CMake: http://cmake.org/
 
 Required libraries are not part of the tree. These are:
 
-- zlib
 - OpenAL (OpenAL Soft required, Creative's and Apple's versions are made of fail)
 - SDL v1.2 or 2.0 (2.0 recommended)
 - libcurl (optional, required for server downloads)
@@ -108,7 +108,7 @@ build dependecies) it should be the same on other Linux distros and even other U
 Open a terminal and follow these steps:
 
 * Install build dependencies:  
-  `sudo apt install git cmake build-essential libsdl2-dev libopenal-dev zlib1g-dev libcurl4-openssl-dev`  
+  `sudo apt install git cmake build-essential libsdl2-dev libopenal-dev libcurl4-openssl-dev`  
     - The build-essential package on Debian/Ubuntu/... installs some basics for compiling code
       like GCC (incl. g++), GNU Make and the glibc development package
     - Instead of libcurl4-openssl-dev, other libcurl*-dev packages should also work - or none at all, curl is optional.
@@ -207,6 +207,32 @@ ADDITIONAL TERMS:  The Doom 3 GPL Source Code is also subject to certain additio
 
 EXCLUDED CODE:  The code described below and contained in the Doom 3 GPL Source Code release is not part of the Program covered by the GPL and is expressly excluded from its terms.  You are solely responsible for obtaining from the copyright holder a license for such code and complying with the applicable license terms.
 
+## Dear ImGui
+
+neo/libs/imgui/*
+
+The MIT License (MIT)
+
+Copyright (c) 2014-2024 Omar Cornut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 ## PropTree
 
 neo/tools/common/PropTree/*
@@ -264,6 +290,34 @@ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
 
+## miniz
+
+src/framework/miniz/*
+
+The MIT License (MIT)
+
+Copyright 2013-2014 RAD Game Tools and Valve Software
+Copyright 2010-2014 Rich Geldreich and Tenacious Software LLC
+
+All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
 
 ## IO on .zip files using minizip