Refactoring

Docs/Building.dox

@@ -11,8 +11,8 @@ namespace Death {
 The project requires following tools and libraries to build it successfully:
 
 -   **CMake** 3.15 or newer
--   C++ compiler with C++17 support --- any newer version of **GCC**, **Clang**
-    and **MSVC** should work, **MinGW** and **Clang-CL** should be also supported
+-   C++ compiler with C++17 support --- any newer version of **GCC**, **Clang** and **MSVC**
+    should work, **MinGW** and **clang-cl** toolchains should be also supported
 -   **OpenGL** 3.0, **OpenGL|ES** 3.0 or **WebGL** 2.0 library (alternatively **ANGLE**
     or **Mesa** translation library)
 -   **GLEW** (required only on Windows)
@@ -120,7 +120,7 @@ See @ref building-config-params-windows for more details. To build it for 32-bit
 use `Win32` instead of `x64`. To change version of VS toolset, use `-D CMAKE_GENERATOR_TOOLSET=…` parameter.
 By default CMake creates a new Visual Studio `.sln` solution and project files
 in @cpp "build" @ce directory that can be opened easily afterwards. Building
-with Clang-CL is also possible specifying `-T ClangCL` parameter.
+with **clang-cl** compiler is also possible specifying `-T ClangCL` parameter.
 
 @subsection building-uwp Building for Xbox (Universal Windows Platform)
 
@@ -148,46 +148,49 @@ libraries. **GLFW** is usually preferred over **SDL2**, because it's more lightw
 On the other hand, **SDL2** usually has better gamepad support and better support in general.
 The following parameters can be used to customize the build:
 
--   `CMAKE_BUILD_TYPE` --- Specify build configuration: `Debug`, `Release`
--   `CMAKE_INSTALL_PREFIX` (default @cpp "/usr/local" @ce) --- Install prefix on Unix systems
+-   `CMAKE_BUILD_TYPE` --- Build configuration
+    -   Possible values: `Debug`, `Release`
+-   `CMAKE_INSTALL_PREFIX` (default @cpp "/usr/local" @ce) --- Install prefix on **Unix** systems
 -   `NCINE_DOWNLOAD_DEPENDENCIES` (default @cpp ON @ce) --- Download all missing dependencies automatically
--   `NCINE_PREFERRED_BACKEND` (default @cpp "GLFW" @ce) --- Specify preferred backend on desktop: `GLFW`, `SDL2`
--   `NCINE_VERSION_FROM_GIT` (default @cpp ON @ce) --- Try to set current game version from Git repository
+-   `NCINE_PREFERRED_BACKEND` (default @cpp "GLFW" @ce) --- Preferred backend on desktop
+    -   Possible values: `GLFW`, `SDL2`
+    -   Ignored on **Android** and **UWP** platforms
+-   `NCINE_VERSION_FROM_GIT` (default @cpp ON @ce) --- Set current game version from Git repository automatically
 -   `NCINE_EMBED_SHADERS` (default @cpp ON @ce) --- Embed shader files inside executable
--   `NCINE_PROFILING` (default @cpp OFF @ce) --- Enable profiling
--   `NCINE_WITH_THREADS` (default @cpp ON @ce except on Emscripten) --- Use multiple threads for better performance
--   `NCINE_WITH_OPENGLES` (default @cpp OFF @ce) --- Use **OpenGL|ES** instead of **OpenGL**
--   `NCINE_WITH_ANGLE` (default @cpp OFF @ce except on UWP) --- Enable Google **ANGLE** libraries support
+-   `NCINE_WITH_THREADS` (default @cpp ON @ce except on Emscripten) --- Allow to use multiple threads for better performance
+-   `NCINE_WITH_OPENGLES` (default @cpp OFF @ce) --- Use **OpenGL|ES** library instead of **OpenGL**
+-   `NCINE_WITH_ANGLE` (default @cpp OFF @ce except on UWP) --- Enable Google **ANGLE** library support
 -   `NCINE_WITH_GLEW` (default @cpp ON @ce) --- Use **GLEW** library
--   `NCINE_WITH_BACKWARD` (default @cpp ON @ce) --- Enable integration with Backward for exception handling
--   `NCINE_WITH_WEBP` (default @cpp OFF @ce) --- Enable `.webp` image file support
--   `NCINE_WITH_AUDIO` (default @cpp ON @ce) --- Enable audio support, requires [OpenAL](https://www.openal.org/)
--   `NCINE_WITH_VORBIS` (default @cpp ON @ce) -- Enable `.ogg` audio file support
--   `NCINE_WITH_OPENMPT` (default @cpp ON @ce) -- Enable module music (`libopenmpt`) audio file support
--   `NCINE_COMPILE_OPENMPT` (default @cpp ON @ce) -- Download and compile `libopenmpt` from source automatically
+-   `NCINE_WITH_BACKWARD` (default @cpp ON @ce) --- Enable better exception handling
+-   `NCINE_WITH_WEBP` (default @cpp OFF @ce) --- Enable `.webp` image file support, requires **libwebp** library
+-   `NCINE_WITH_AUDIO` (default @cpp ON @ce) --- Enable audio support, requires **OpenAL** library
+-   `NCINE_WITH_VORBIS` (default @cpp ON @ce) -- Enable `.ogg` audio file support, requires **libvorbis** library
+-   `NCINE_WITH_OPENMPT` (default @cpp ON @ce) -- Enable module music audio file support, requires **libopenmpt** library
+-   `NCINE_COMPILE_OPENMPT` (default @cpp ON @ce) -- Download and compile **libopenmpt** from source automatically
 -   `NCINE_WITH_ANGELSCRIPT` (default @cpp OFF @ce) --- Enable [AngelScript](https://www.angelcode.com/angelscript/) scripting support
--   `NCINE_WITH_IMGUI` (default @cpp OFF @ce) --- Enable integration with [Dear ImGui](https://github.com/ocornut/imgui)
+-   `NCINE_WITH_LUA` @m_class{m-label m-danger m-flat} **deprecated** --- Enable [Lua](https://www.lua.org/) scripting support
+-   `NCINE_WITH_IMGUI` (default @cpp OFF @ce) --- Enable integration with [Dear ImGui](https://github.com/ocornut/imgui) library
     -   `IMGUI_VERSION_TAG` allows to specify version
 -   `NCINE_WITH_TRACY` (default @cpp OFF @ce) --- Enable integration with [Tracy](https://github.com/wolfpld/tracy) frame profiler
     -   `TRACY_VERSION_TAG` allows to specify version
--   `NCINE_WITH_RENDERDOC` (default @cpp OFF @ce) --- Enable integration with [RenderDoc](https://renderdoc.org/)
+-   `NCINE_WITH_RENDERDOC` @m_class{m-label m-danger m-flat} **deprecated** --- Enable integration with [RenderDoc](https://renderdoc.org/)
 -   `NCINE_DATA_DIR` (default @cpp "./Content" @ce) --- Path to @cpp "Content" @ce game data directory
     -   Some build targets include @cpp "Content" @ce directory directly inside the executable package
 
 @subsubsection building-config-params-android Platform-specific parameters for Android
 
--   `NCINE_BUILD_ANDROID` (default @cpp OFF @ce) --- Enable building for Android
+-   `NCINE_BUILD_ANDROID` (default @cpp OFF @ce) --- Enable building for **Android** platform
 -   `NCINE_ASSEMBLE_APK` (default @cpp ON @ce) --- Assemble Android APK file, requires with **Gradle**
--   `NCINE_UNIVERSAL_APK` (default @cpp OFF @ce) --- Create universal APK containing all specified CPU architectures
 -   `NCINE_NDK_ARCHITECTURES` (default @cpp "arm64-v8a" @ce) --- Semicolon-separated list of target CPU architectures
     -   Possible values: `arm64-v8a` (for 64-bit ARM), `armeabi-v7a` (for 32-bit ARM), `x86`, `x86_64`
+-   `NCINE_UNIVERSAL_APK` (default @cpp OFF @ce) --- Create universal APK containing all specified CPU architectures
 -   `NDK_DIR` --- Android NDK directory, usually detected automatically
 
 @subsubsection building-config-params-linux Platform-specific parameters for Linux
 
--   `NCINE_BUILD_FLATPAK` (default @cpp OFF @ce) --- Build Flatpak version of the game
 -   `NCINE_ASSEMBLE_DEB` (default @cpp OFF @ce) --- Assemble DEB package of the game
 -   `NCINE_ASSEMBLE_RPM` (default @cpp OFF @ce) --- Assemble RPM package of the game
+-   `NCINE_BUILD_FLATPAK` (default @cpp OFF @ce) --- Build Flatpak version of the game
 -   `NCINE_LINUX_PACKAGE` --- Override Linux package name, otherwise @cpp "Jazz² Resurrection" @ce will be used
 -   `NCINE_OVERRIDE_CONTENT_PATH` --- Override @cpp "Content" @ce directory path
     -   If not specified, following path will be used: @cpp CMAKE_INSTALL_PREFIX "/share/" NCINE_LINUX_PACKAGE "/Content/" @ce
@@ -199,7 +202,7 @@ The following parameters can be used to customize the build:
 
 -   `DEATH_WITH_VC_LTL` (default @cpp ON @ce) --- Build with **VC-LTL** for lighter
     binaries, requires [VC-LTL](https://github.com/Chuyu-Team/VC-LTL5)
--   `NCINE_COPY_DEPENDENCIES` (default @cpp OFF @ce) --- Copy all required libraries to build target directory
+-   `NCINE_COPY_DEPENDENCIES` (default @cpp OFF @ce) --- Copy all required libraries to build target directory automatically
 
 @subsubsection building-config-params-uwp Platform-specific parameters for Universal Windows Platform
 
@@ -213,24 +216,30 @@ The following parameters can be used to customize the build:
 -   `DEATH_CPU_USE_RUNTIME_DISPATCH` (default @cpp ON @ce if `DEATH_CPU_USE_IFUNC`) --- Build
     with runtime dispatch for CPU-dependent functionality, see @ref Death::Cpu
 -   `DEATH_CPU_USE_IFUNC` (default @cpp ON @ce if supported) --- Allow using **GNU IFUNC** for runtime CPU dispatch
--   `DEATH_RUNTIME_CAST` (default @cpp ON @ce) --- Enable @cpp runtime_cast<T>() @ce optimization
--   `DEATH_TRACE` (default @cpp ON @ce) --- Enable runtime event tracing
+-   `DEATH_RUNTIME_CAST` (default @cpp ON @ce) --- Enable @ref Death::runtime_cast() optimization
+-   `DEATH_TRACE` (default @cpp ON @ce) --- Enable runtime event tracing, see @ref Asserts.h
 -   `DEATH_TRACE_ASYNC` (default @cpp ON @ce if `NCINE_WITH_THREADS`) --- Enable asynchronous processing of event tracing for better performance
+-   `NCINE_ADDRESS_SANITIZER` (default @cpp OFF @ce) --- Enable `AddressSanitizer` memory error detector
 -   `NCINE_ARCH_EXTENSIONS` --- Target CPU architecture extensions (instruction sets)
-    -   See documentation of [`/arch` (MSVC)](https://learn.microsoft.com/en-us/cpp/build/reference/arch-minimum-cpu-architecture?view=msvc-170) and [`-m` (GCC)](https://gcc.gnu.org/onlinedocs/gcc-8.4.0/gcc/Submodel-Options.html) for more details.
--   `NCINE_INPUT_DEBUGGING` (default @cpp OFF @ce) --- Enable (gamepad) input debugging and logging
--   `NCINE_LINKTIME_OPTIMIZATION` (default @cpp ON @ce) --- Compile with link time optimization
--   `NCINE_ADDRESS_SANITIZER` (default @cpp OFF @ce) --- Enable AddressSanitizer memory error detector
--   `NCINE_UNDEFINED_SANITIZER` (default @cpp OFF @ce) --- Enable UndefinedBehaviorSanitizer detector
--   `NCINE_CODE_COVERAGE` (default @cpp OFF @ce) --- Enable gcov instrumentation for testing code coverage
+    -   Depends on target CPU and compiler support
+    -   See documentation of `/arch` ([MSVC](https://learn.microsoft.com/en-us/cpp/build/reference/arch-minimum-cpu-architecture?view=msvc-170)) and `-m` ([GCC](https://gcc.gnu.org/onlinedocs/gcc-8.4.0/gcc/Submodel-Options.html)) for more details.
+-   `NCINE_CODE_COVERAGE` (default @cpp OFF @ce) --- Enable `gcov` instrumentation for testing code coverage
 -   `NCINE_GCC_HARDENING` (default @cpp OFF @ce) --- Enable memory corruption mitigation methods of GCC
+-   `NCINE_LINKTIME_OPTIMIZATION` (default @cpp ON @ce) --- Compile with link-time optimization
+-   `NCINE_UNDEFINED_SANITIZER` (default @cpp OFF @ce) --- Enable `UndefinedBehaviorSanitizer` detector
+
+@subsubsection building-config-params-debug Debugging parameters
+
 -   `NCINE_AUTOVECTORIZATION_REPORT` (default @cpp OFF @ce) --- Enable report generation from compiler auto-vectorization
+-   `NCINE_INPUT_DEBUGGING` (default @cpp OFF @ce) --- Enable extensive (gamepad) input debugging and logging
+-   `NCINE_PROFILING` (default @cpp OFF @ce) --- Enable profiling
 -   `NCINE_STRIP_BINARIES` (default @cpp OFF @ce) --- Strip debug symbols from binaries for smaller size
+-   `NCINE_WITH_FIXED_BATCH_SIZE` (default @cpp OFF @ce) --- Enable fixed batch size for rendering
 
 @subsubsection building-config-params-game Game-specific parameters
 
--   `SHAREWARE_DEMO_ONLY` (default @cpp OFF @ce) --- Shareware Demo only, usually used with **Emscripten**
 -   `DISABLE_RESCALE_SHADERS` (default @cpp OFF @ce) --- Disable rescale shaders and use only nearest neighbor for resizing
+-   `SHAREWARE_DEMO_ONLY` (default @cpp OFF @ce) --- Shareware Demo only, usually used on **Emscripten** platform
 -   `WITH_MULTIPLAYER` (default @cpp OFF @ce) --- Enable experimental multiplayer support
 
 */

Docs/Namespaces.dox

@@ -6,18 +6,20 @@ namespace Death {
 This is an API documentation for Jazz² Resurrection. For user documentation, please visit [project homepage](https://deat.tk/jazz2/).
 Additionaly, the project is hosted on https://github.com/deathkiller/jazz2-native/.
 
-Jazz² Resurrection is reimplementation of the game Jazz Jackrabbit 2 released in 1998. Supports various versions of the game
-(Shareware Demo, Holiday Hare '98, The Secret Files and Christmas Chronicles). Also, it partially supports some features
-of JJ2+ extension and MLLE. **Online multiplayer** and **scripting support** (AngelScript) is currently in development,
-everything else is already fully implemented.
+Jazz² Resurrection is reimplementation of the game Jazz Jackrabbit 2 released in 1998. Supports
+various versions of the game (Shareware Demo, Holiday Hare '98, The Secret Files and Christmas
+Chronicles). Also, it partially supports some features of JJ2+ extension and MLLE. **Online multiplayer**
+and **scripting support** (AngelScript) is currently in development, everything else, including
+story episodes fully playable in cooperation, is already implemented.
 
 To get in touch with the developers and the community, you can use the official [Discord server](https://discord.gg/Y7SBvkD).
 
-For getting started guide, see @ref building. For game-specific API documentation, see @ref Jazz2 namespace.
-For common utility functions and generic containers, see @ref Death "the shared root namespace".
-In addition, @ref CommonBase.h contains common configuration-specific and platform-specific definitions.
-For **nCine** game engine documentation, see @ref nCine namespace. The **nCine** game engine used in this game has
-been extensively modified, so the original documentation no longer matches the current implementation.
+For getting started guide, see @ref building. For game-specific API documentation, see @ref Jazz2
+namespace. For common utility functions and generic containers, see @ref Death "the shared root namespace".
+In addition, @ref CommonBase.h contains common configuration-specific and platform-specific
+definitions. For **nCine** game engine documentation, see @ref nCine namespace. The **nCine** game
+engine used in this game has been extensively modified, so the original documentation no longer
+matches the current implementation.
 
 @section mainpage-platforms Supported platforms
 
@@ -30,10 +32,11 @@ been extensively modified, so the original documentation no longer matches the c
 - **Xbox** (Universal Windows Platform) using ANGLE/Mesa
 - **Web** (WebAssembly) using [Emscripten](https://kripken.github.io/emscripten-site/)
 
-The code is mainly optimized to run on 64-bit **x86** and **ARM** processors including advanced instruction
-sets. Additionally, **OpenGL** 3.0, **OpenGL|ES** 3.0 or **WebGL** 2.0 is required to run the application.
-However, Google ANGLE or Mesa can be used to translate OpenGL calls to the native graphics API. See also
-@ref death-partialsupport "the list of partially supported features" that depend on specific platforms.
+The code is mainly optimized to run on 64-bit **x86** and **ARM** processors including advanced
+instruction sets. Additionally, **OpenGL** 3.0, **OpenGL|ES** 3.0 or **WebGL** 2.0 is required
+to run the application. However, Google ANGLE or Mesa can be used to translate OpenGL calls to
+the native graphics API. See also @ref death-partialsupport "the list of partially supported features"
+that depend on specific platforms.
 
 @section mainpage-license License
 
@@ -56,12 +59,17 @@ See also @ref third-party for the licenses of the libraries used.
 */
 /** @file Shared/Asserts.h
 	@brief Assertions and event tracing
+
+	Most functions and macros for event tracing require `DEATH_TRACE` to be defined. Otherwise, no operation is performed.
+	In addition, assert statements can be suppressed with `DEATH_NO_ASSERT` define. See also @ref Death::ITraceSink
+	companion interface.
 */
 /** @file Shared/CommonBase.h
 	@brief Basic definitions
 
-	Some configuration-specific and platform-specific definitions, including `DEATH_TARGET_*`, are @ref Death.dox "listed separately".
-	Some of them are supplied via a compiler flag by CMake, the rest of them also requires this header file to work properly.
+	Some configuration-specific and platform-specific definitions, including `DEATH_TARGET_*`, are
+	@ref Death.dox "listed separately". Some of them are supplied via a compiler flag by CMake,
+	the rest of them also requires this header file to work properly.
 */
 /** @file Shared/Common.h
 	@brief Common header file, includes also @ref CommonBase.h, `<cstddef>` and `<cstdint>`
@@ -94,6 +102,11 @@ See also @ref third-party for the licenses of the libraries used.
 
 	Literals for easy construction of string views.
 */
+/** @file Shared/Containers/GrowableArray.h
+	@brief Class @ref Death::Containers::ArrayAllocator, @ref Death::Containers::ArrayNewAllocator, @ref Death::Containers::ArrayMallocAllocator, function @ref Death::Containers::arrayAllocatorCast(), @ref Death::Containers::arrayIsGrowable(), @ref Death::Containers::arrayCapacity(), @ref Death::Containers::arrayReserve(), @ref Death::Containers::arrayResize(), @ref Death::Containers::arrayAppend(), @ref Death::Containers::arrayInsert(), @ref Death::Containers::arrayRemove(), @ref Death::Containers::arrayRemoveUnordered(), @ref Death::Containers::arrayRemoveSuffix(), @ref Death::Containers::arrayClear(), @ref Death::Containers::arrayShrink()
+
+	See @ref Containers-Array-growable for more information.
+ */
 /** @file Shared/Containers/StringUtils.h
 	@brief Namespace @ref Death::Containers::StringUtils
 */

Sources/Jazz2/UI/Cinematics.cpp

@@ -331,7 +331,7 @@ namespace Jazz2::UI
 			}
 		}
 
-		_pressedActions |= ControlScheme::FetchNativation(_pressedKeys, ArrayView(joyStates, joyStatesCount));
+		_pressedActions |= ControlScheme::FetchNavigation(_pressedKeys, ArrayView(joyStates, joyStatesCount));
 
 		// Also allow Menu action as skip key
 		if (_pressedActions & (1 << (std::uint32_t)PlayerActions::Menu)) {

Sources/Jazz2/UI/ControlScheme.cpp

@@ -197,7 +197,7 @@ namespace Jazz2::UI
 		return result;
 	}
 
-	std::uint32_t ControlScheme::FetchNativation(const BitArray& pressedKeys, const ArrayView<const JoyMappedState*> joyStates, NavigationFlags flags)
+	std::uint32_t ControlScheme::FetchNavigation(const BitArray& pressedKeys, const ArrayView<const JoyMappedState*> joyStates, NavigationFlags flags)
 	{
 		std::uint32_t pressedActions = 0;
 		std::size_t joyStateCount = joyStates.size();

Sources/Jazz2/UI/ControlScheme.h

@@ -80,7 +80,7 @@ namespace Jazz2::UI
 		/** @brief Fetches processed standard input for specified player according to the current bindings */
 		static ProcessedInput FetchProcessedInput(std::int32_t playerIndex, const BitArray& pressedKeys, const ArrayView<const JoyMappedState*> joyStates, bool analogAsButtons = true);
 		/** @brief Fetches navigation input according to the current bindings */
-		static std::uint32_t FetchNativation(const BitArray& pressedKeys, const ArrayView<const JoyMappedState*> joyStates, NavigationFlags flags = NavigationFlags::AllowAll);
+		static std::uint32_t FetchNavigation(const BitArray& pressedKeys, const ArrayView<const JoyMappedState*> joyStates, NavigationFlags flags = NavigationFlags::AllowAll);
 
 		/** @brief Returns the entire mapping configuration */
 		static ArrayView<ControlSchemeMapping> GetAllMappings();

Sources/Jazz2/UI/Menu/InGameMenu.cpp

@@ -520,7 +520,7 @@ namespace Jazz2::UI::Menu
 			flags = lastSection->GetNavigationFlags();
 		}
 
-		_pressedActions |= ControlScheme::FetchNativation(_root->_pressedKeys, ArrayView(joyStates, joyStatesCount), flags);
+		_pressedActions |= ControlScheme::FetchNavigation(_root->_pressedKeys, ArrayView(joyStates, joyStatesCount), flags);
 		if (_lastNavigationFlags != flags) {
 			_lastNavigationFlags = flags;
 			_pressedActions &= 0xffff;

Sources/Jazz2/UI/Menu/MainMenu.cpp

@@ -624,7 +624,7 @@ namespace Jazz2::UI::Menu
 			flags = lastSection->GetNavigationFlags();
 		}
 
-		_pressedActions |= ControlScheme::FetchNativation(_pressedKeys, ArrayView(joyStates, joyStatesCount), flags);
+		_pressedActions |= ControlScheme::FetchNavigation(_pressedKeys, ArrayView(joyStates, joyStatesCount), flags);
 		if (_lastNavigationFlags != flags) {
 			_lastNavigationFlags = flags;
 			_pressedActions &= 0xffff;