Refactoring

Docs/Death.dox

@@ -363,7 +363,7 @@ namespace Death {
 #undef DEATH_TARGET_MSVC
 
 /**
-	@brief Cygwin compiler
+	@brief Cygwin environment
 
 	Defined if the code is being compiled by Cygwin toolchain. If
 	this variable is defined, @ref DEATH_TARGET_GCC and possibly also

README.md

@@ -39,7 +39,7 @@ Jazz² Resurrection is reimplementation of the game **Jazz Jackrabbit 2** releas
 * Copy contents of original *Jazz Jackrabbit 2* directory to `‹Game›\Source\`
 * Run `‹Game›\Jazz2.exe`, `‹Game›\Jazz2_avx2.exe` or `‹Game›\Jazz2_sdl2.exe` application
 
-`‹Game›` *is path to Jazz² Resurrection. The game requires **Windows 7** (or newer) and GPU with **OpenGL 3.0** support. Game files should **not** be copied to* `Program Files`*. Cache is recreated during intro cinematics on the first startup, so it can't be skipped.*
+`‹Game›` *denotes path to Jazz² Resurrection. The game requires **Windows 7** (or newer) and GPU with **OpenGL 3.0** support. Game files should **not** be copied to* `Program Files`*. Cache is recreated during intro cinematics on the first startup, so it can't be skipped.*
 
 ### Linux
 * Download the game
@@ -50,7 +50,7 @@ Jazz² Resurrection is reimplementation of the game **Jazz Jackrabbit 2** releas
 * Run `‹Game›/jazz2` or `‹Game›/jazz2_sdl2` application
   * If packages are used, the game should be visible in application list
 
-`‹Game›` *is path to Jazz² Resurrection. The game requires GPU with **OpenGL 3.0** or **OpenGL ES 3.0** (ARM) support. Cache is recreated during intro cinematics on the first startup, so it can't be skipped.*
+`‹Game›` *denotes path to Jazz² Resurrection.* `~` *denotes user's home directory. The game requires GPU with **OpenGL 3.0** or **OpenGL ES 3.0** (ARM) support. Cache is recreated during intro cinematics on the first startup, so it can't be skipped.*
 
 <sup>Alternatively, you can use package repository for your Linux distribution:</sup><br>
 [![ArchLinux](https://img.shields.io/badge/Arch%20Linux-grey?logo=archlinux&logoColor=ffffff)](https://aur.archlinux.org/packages/jazz2-bin)
@@ -65,7 +65,7 @@ Jazz² Resurrection is reimplementation of the game **Jazz Jackrabbit 2** releas
 * Copy contents of original *Jazz Jackrabbit 2* directory to `~/Library/Application Support/Jazz² Resurrection/Source/`
 * Run the newly installed application
 
-*Cache is recreated during intro cinematics on the first startup, so it can't be skipped.*
+`~` *denotes user's home directory. Cache is recreated during intro cinematics on the first startup, so it can't be skipped.*
 
 Alternatively, you can install it using <sub><sub>[![Homebrew](https://img.shields.io/homebrew/cask/v/jazz2-resurrection?logo=homebrew&logoColor=ffffff&label=Homebrew&color=b56b2b)](https://formulae.brew.sh/cask/jazz2-resurrection)</sub></sub> `brew install --cask jazz2-resurrection`
 
@@ -78,7 +78,7 @@ Alternatively, you can install it using <sub><sub>[![Homebrew](https://img.shiel
     * `‹Storage›/Download/Jazz² Resurrection/Source/`
 * Run the newly installed application
 
-`‹Storage›` *is usually internal storage on your device.* `Content` *directory is included directly in APK file, no action is needed. The game requires **Android 5.0** (or newer) and GPU with **OpenGL ES 3.0** support. Cache is recreated during intro cinematics on the first startup.*
+`‹Storage›` *usually denotes internal storage on your device.* `Content` *directory is included directly in APK file, no action is needed. The game requires **Android 5.0** (or newer) and GPU with **OpenGL ES 3.0** support. Cache is recreated during intro cinematics on the first startup.*
 
 ### Nintendo Switch
 * Download the game
@@ -105,6 +105,9 @@ Alternatively, you can install it using <sub><sub>[![Homebrew](https://img.shiel
 
 
 ## Building the application
+
+This section contains only a brief explanation of the build process. For a more detailed explanation, including build configuration parameters, please refer to [the developer documentation](https://deat.tk/jazz2/docs/).
+
 ### Windows
 * Build dependencies will be downloaded automatically by *CMake*
   * Can be disabled with `NCINE_DOWNLOAD_DEPENDENCIES` option, then download [build dependencies](https://github.com/deathkiller/jazz2-libraries) manually to `.\Libs\`

Sources/Jazz2/Compatibility/JJ2Level.h

@@ -28,16 +28,23 @@ namespace Jazz2::Compatibility
 	public:
 		/** @brief Episode name and level name */
 		struct LevelToken {
+			/** @brief Episode name */
 			String Episode;
+			/** @brief Level name */
 			String Level;
 		};
 
 		/** @brief Extra tileset used in the level */
 		struct ExtraTilesetEntry {
+			/** @brief Tile set name */
 			String Name;
+			/** @brief Offset tile index */
 			std::uint16_t Offset;
+			/** @brief Number of tiles */
 			std::uint16_t Count;
+			/** @brief Whether palette remapping is used */
 			bool HasPaletteRemapping;
+			/** @brief Palette remapping */
 			std::uint8_t PaletteRemapping[256];
 		};
 
@@ -62,14 +69,17 @@ namespace Jazz2::Compatibility
 		bool Open(StringView path, bool strictParser);
 
 		void Convert(StringView targetPath, EventConverter& eventConverter, Function<LevelToken(StringView)>&& levelTokenConversion = {});
-		void AddLevelTokenTextID(uint8_t textId);
+		void AddLevelTokenTextID(std::uint8_t textId);
 
+		/** @brief Returns target version of the level */
 		JJ2Version GetVersion() const {
 			return _version;
 		}
+		/** @brief Returns maximum number of supported tiles */
 		std::int32_t GetMaxSupportedTiles() const {
 			return (_version == JJ2Version::BaseGame ? 1024 : 4096);
 		}
+		/** @brief Returns maximum number of supported animations */
 		std::int32_t GetMaxSupportedAnims() const {
 			return (_version == JJ2Version::BaseGame ? 128 : 256);
 		}

Sources/Jazz2/Compatibility/JJ2Tileset.h

@@ -26,6 +26,7 @@ namespace Jazz2::Compatibility
 
 		void Convert(StringView targetPath) const;
 
+		/** @brief Returns maximum number of supported tiles */
 		std::int32_t GetMaxSupportedTiles() const {
 			return (_version == JJ2Version::BaseGame ? 1024 : 4096);
 		}

Sources/Jazz2/Events/EventMap.h

@@ -34,6 +34,7 @@ namespace Jazz2::Events
 
 		EventMap(Vector2i layoutSize);
 
+		/** @brief Sets owner of the event map */
 		void SetLevelHandler(ILevelHandler* levelHandler);
 		/** @brief Returns size of event map in tiles */
 		Vector2i GetSize() const;

Sources/Jazz2/PreferencesCache.h

@@ -76,21 +76,31 @@ namespace Jazz2
 	/** @brief Continuation state between two episodes */
 	// These structures are aligned manually, because they are serialized and it should work cross-platform
 	struct EpisodeContinuationState {
+		/** @brief Flags */
 		EpisodeContinuationFlags Flags;
+		/** @brief Difficulty and player type */
 		std::uint8_t DifficultyAndPlayerType;
+		/** @brief Lives */
 		std::uint8_t Lives;
 		std::uint8_t Unused1;
+		/** @brief Score */
 		std::int32_t Score;
 		std::uint16_t Unused2;
+		/** @brief Elapsed game time in milliseconds */
 		std::uint64_t ElapsedMilliseconds;
+		/** @brief Gems collected */
 		std::int32_t Gems[4];
+		/** @brief Weapon ammo */
 		std::uint16_t Ammo[(std::int32_t)WeaponType::Count];
+		/** @brief Weapon upgrades */
 		std::uint8_t WeaponUpgrades[(std::int32_t)WeaponType::Count];
 	};
 
 	/** @brief Continuation state between two levels in episode */
 	struct EpisodeContinuationStateWithLevel {
+		/** @brief Continuation state */
 		EpisodeContinuationState State;
+		/** @brief Last level name */
 		String LevelName;
 	};
 

Sources/Jazz2/RumbleProcessor.h

@@ -18,6 +18,7 @@ namespace Jazz2
 		/** @brief Executes an effect on a given gamepad */
 		void ExecuteEffect(std::int32_t joyId, const std::shared_ptr<RumbleDescription>& desc);
 
+		/** @brief Called at the end of each frame */
 		void OnEndFrame(float timeMult);
 
 	private:

Sources/Jazz2/Scripting/RegisterArray.h

@@ -86,12 +86,14 @@ namespace Jazz2::Scripting
 		void ReleaseAllHandles(asIScriptEngine* engine);
 
 	protected:
+#ifndef DOXYGEN_GENERATING_OUTPUT
 		mutable int refCount;
 		mutable bool gcFlag;
 		asITypeInfo* objType;
 		SArrayBuffer* buffer;
 		int elementSize;
 		int subTypeId;
+#endif
 
 		// Constructors
 		CScriptArray(asITypeInfo* ot, void* initBuf); // Called from script when initialized with list

Sources/Jazz2/Scripting/RegisterDictionary.h

@@ -23,6 +23,8 @@ namespace Jazz2::Scripting
 	/** @brief **AngelScript** dictionary value */
 	class CScriptDictValue
 	{
+		friend class CScriptDictionary;
+
 	public:
 		// This class must not be declared as local variable in C++, because it needs
 		// to receive the script engine pointer in all operations. The engine pointer
@@ -57,15 +59,15 @@ namespace Jazz2::Scripting
 		void EnumReferences(asIScriptEngine* engine);
 
 	protected:
-		friend class CScriptDictionary;
-
+#ifndef DOXYGEN_GENERATING_OUTPUT
 		union
 		{
 			asINT64 m_valueInt;
 			double  m_valueFlt;
 			void* m_valueObj;
 		};
 		int m_typeId;
+#endif
 	};
 
 	/** @brief **AngelScript** dictionary */
@@ -124,6 +126,8 @@ namespace Jazz2::Scripting
 		/** @brief **AngelScript** dictionary iterator */
 		class CIterator
 		{
+			friend class CScriptDictionary;
+
 		public:
 			void operator++();    // Pre-increment
 			void operator++(int); // Post-increment
@@ -143,15 +147,15 @@ namespace Jazz2::Scripting
 			const void* GetAddressOfValue() const;
 
 		protected:
-			friend class CScriptDictionary;
-
 			CIterator();
 			CIterator(const CScriptDictionary& dict, dictMap_t::const_iterator it);
 
 			CIterator& operator=(const CIterator&) { return *this; } // Not used
 
+#ifndef DOXYGEN_GENERATING_OUTPUT
 			dictMap_t::const_iterator m_it;
 			const CScriptDictionary& m_dict;
+#endif
 		};
 
 		CIterator begin() const;
@@ -178,11 +182,13 @@ namespace Jazz2::Scripting
 		// Cache the object types needed
 		void Init(asIScriptEngine* engine);
 
+#ifndef DOXYGEN_GENERATING_OUTPUT
 		// Our properties
 		asIScriptEngine* engine;
 		mutable int refCount;
 		mutable bool gcFlag;
 		dictMap_t dict;
+#endif
 	};
 
 	/** @brief Registers `dictionary` type to **AngelScript** engine */

Sources/Jazz2/Scripting/RegisterRef.h

@@ -53,8 +53,10 @@ namespace Jazz2::Scripting
 		CScriptHandle(void* ref, int typeId);
 		CScriptHandle &Assign(void* ref, int typeId);
 
+#ifndef DOXYGEN_GENERATING_OUTPUT
 		void* m_ref;
 		asITypeInfo* m_type;
+#endif
 	};
 
 	/** @brief Registers `ref` type to **AngelScript** engine */

Sources/Jazz2/Scripting/ScriptActorWrapper.h

@@ -43,11 +43,13 @@ namespace Jazz2::Scripting
 		bool OnHandleCollision(std::shared_ptr<ActorBase> other) override;
 
 	protected:
+#ifndef DOXYGEN_GENERATING_OUTPUT
 		LevelScriptLoader* _levelScripts;
 		asIScriptObject* _obj;
 		asILockableSharedBool* _isDead;
 
-		uint32_t _scoreValue;
+		std::uint32_t _scoreValue;
+#endif
 
 		Task<bool> OnActivatedAsync(const Actors::ActorActivationDetails& details) override;
 		bool OnTileDeactivated() override;

Sources/Jazz2/Scripting/ScriptLoader.h

@@ -57,7 +57,7 @@ namespace Jazz2::Scripting
 	class ScriptLoader
 	{
 	public:
-		/** @brief Returns @ref ScriptLoader instance from active **AngelScript** context */
+		/** @brief Returns @ref ScriptLoader instance from active **AngelScript** context if exists */
 		template<typename T = ScriptLoader, class = typename std::enable_if<std::is_base_of<ScriptLoader, T>::value>::type>
 		static T* FromActiveContext() {
 			auto* ctx = asGetActiveContext();

Sources/Jazz2/Scripting/ScriptPlayerWrapper.h

@@ -41,8 +41,10 @@ namespace Jazz2::Scripting
 		}
 
 	protected:
+#ifndef DOXYGEN_GENERATING_OUTPUT
 		LevelScriptLoader* _levelScripts;
 		Actors::Player* _player;
+#endif
 
 		bool asIsInGame() const;
 		int asGetIndex() const;

Sources/Jazz2/Tiles/TileCollisionParams.h

@@ -9,11 +9,17 @@ namespace Jazz2::Tiles
 	/** @brief Describes how the object interacts and collides with the environment */
 	struct TileCollisionParams
 	{
+		/** @brief Destruction type */
 		TileDestructType DestructType;
+		/** @brief Whether movement direction is downwards */
 		bool Downwards;
+		/** @brief Used weapon type */
 		WeaponType UsedWeaponType;
+		/** @brief Remaining weapon strength */
 		std::int32_t WeaponStrength;
+		/** @brief Movement speed */
 		float Speed;
+		/** @brief Number of destroyed tiles */
 		/*out*/ std::int32_t TilesDestroyed;
 	};
 }

Sources/Jazz2/Tiles/TileMap.h

@@ -242,6 +242,7 @@ namespace Jazz2::Tiles
 		void SetPitType(PitType value);
 
 		void OnUpdate(float timeMult) override;
+		/** @brief Called at the end of each frame */
 		void OnEndFrame();
 		bool OnDraw(RenderQueue& renderQueue) override;
 
@@ -258,8 +259,11 @@ namespace Jazz2::Tiles
 
 		/** @brief Adds an additional tile set as a continuation of the previous one */
 		void AddTileSet(StringView tileSetPath, std::uint16_t offset, std::uint16_t count, const std::uint8_t* paletteRemapping = nullptr);
+		/** @brief Reads layer configuration from a stream */
 		void ReadLayerConfiguration(Stream& s);
+		/** @brief Reads description of animated tiles from a stream */
 		void ReadAnimatedTiles(Stream& s);
+		/** @brief Sets tile event flags */
 		void SetTileEventFlags(std::int32_t x, std::int32_t y, EventType tileEvent, std::uint8_t* tileParams);
 
 		/** @brief Returns a caption tile */
@@ -287,6 +291,7 @@ namespace Jazz2::Tiles
 		/** @brief Serializes tile map state to a stream */
 		void SerializeResumableToStream(Stream& dest);
 
+		/** @brief Called when the viewport needs to be initialized (e.g., when the resolution is changed) */
 		void OnInitializeViewport();
 
 	private:

Sources/Jazz2/UI/Font.h

@@ -25,7 +25,9 @@ namespace Jazz2::UI
 
 		Font(StringView path, const std::uint32_t* palette);
 
+		/** @brief Returns font size in pixels */
 		std::int32_t GetSizeInPixels() const;
+		/** @brief Returns font ascent in pixels */
 		std::int32_t GetAscentInPixels() const;
 		/** @brief Returns size of a single character */
 		Vector2f MeasureChar(char32_t c) const;

Sources/Shared/Common.h

@@ -59,11 +59,22 @@ namespace Death { namespace Implementation {
 #define DEATH_HELPER_ARGS_COUNT(...) DEATH_HELPER_EXPAND(DEATH_HELPER_PICK(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0))
 
 #ifndef DOXYGEN_GENERATING_OUTPUT
+// Internal macro implementation
+#define __DEATH_PASTE(a, b) a ## b
 #define __DEATH_NOOP__DEATH_REMOVE_PARENS_EXTRACT
 #define __DEATH_REMOVE_PARENS_EXTRACT(...) __DEATH_REMOVE_PARENS_EXTRACT __VA_ARGS__
 #define __DEATH_REMOVE_PARENS_PASTE(x, ...) x ## __VA_ARGS__
 #define __DEATH_REMOVE_PARENS_EVALUATE(x, ...) __DEATH_REMOVE_PARENS_PASTE(x, __VA_ARGS__)
 #endif
+
+/**
+	@brief Paste two tokens together
+
+	Concatenates preprocessor tokens to create a new one. However, two tokens
+	that don't together form a valid token cannot be pasted together.
+*/
+#define DEATH_PASTE(a, b) __DEATH_PASTE(a, b)
+
 /** @brief Remove optional parentheses from the specified argument */
 #define DEATH_REMOVE_PARENS(x) __DEATH_REMOVE_PARENS_EVALUATE(__DEATH_NOOP, __DEATH_REMOVE_PARENS_EXTRACT x)
 

Sources/Shared/CommonBase.h

@@ -617,19 +617,10 @@
 
 #ifndef DOXYGEN_GENERATING_OUTPUT
 // Internal macro implementation
-#define __DEATH_PASTE(a, b) a ## b
 #define __DEATH_HELPER_STR(x) #x
 #define __DEATH_LINE_STRING_IMPLEMENTATION(...) __DEATH_HELPER_STR(__VA_ARGS__)
 #endif
 
-/**
-	@brief Paste two tokens together
-	
-	Concatenates preprocessor tokens to create a new one. However, two tokens
-	that don't together form a valid token cannot be pasted together.
-*/
-#define DEATH_PASTE(a, b) __DEATH_PASTE(a, b)
-
 /**
 	@brief Line number as a string