Merge pull request #448 from cortex-command-community/Primitive-Transparency

Primitives Expansion 2

Author: garethyr

.gitignore

@@ -13,6 +13,8 @@ compile_commands.json
 
 /build*
 
+/enc_temp_folder
+
 /_Bin
 /NATPunchServer/Server/NATCompleteServer/Debug
 /NATPunchServer/Server/NATCompleteServer/Release

Activities/GibEditor.cpp

@@ -685,7 +685,7 @@ void GibEditor::DrawGUI(BITMAP *pTargetBitmap, const Vector &targetPos, int whic
         // Draw ghost outline of edited object to place gibs upon
         if (m_pEditedObject)
         {
-            g_FrameMan.SetTransTable(MoreTrans);
+            g_FrameMan.SetTransTableFromPreset(TransparencyPreset::MoreTrans);
             // Draw only the MOSRotating since that's all we are adding gibs for; any attachables have to be edited separately
             m_pEditedObject->MOSRotating::Draw(pTargetBitmap, targetPos, g_DrawTrans, true);
         }

CHANGELOG.md

@@ -208,6 +208,157 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 	`PrimitiveMan:DrawLinePrimitive(player, startPos, endPos, color, thickness)`  
 	Original bindings with no thickness argument are untouched and can be called as they were.
 
+- Added rotation option to Text primitives.  
+	New bindings with argument for rotation are:  
+	`PrimitiveMan:DrawTextPrimitive(pos, text, bool useSmallFont, alignment, rotAngleInRadians)`  
+	`PrimitiveMan:DrawTextPrimitive(player, pos, text, bool useSmallFont, alignment, rotAngleInRadians)`  
+	Original bindings with no rotation argument are untouched and can be called as they were.
+
+- Added option to draw bitmap from file instead of from `MOSPrite` based object to Bitmap primitives.  
+	New bindings with argument for file path are:  
+	`PrimitiveMan:DrawBitmapPrimitive(pos, filePath, rotAngleInRadians)`  
+	`PrimitiveMan:DrawBitmapPrimitive(pos, filePath, rotAngleInRadians, hFlipped, vFlipped)`  
+	`PrimitiveMan:DrawBitmapPrimitive(player, pos, filePath, rotAngleInRadians)`  
+	`PrimitiveMan:DrawBitmapPrimitive(player, pos, filePath, rotAngleInRadians, hFlipped, vFlipped)`  
+	Note that the `frame` argument does not exist in these bindings.  
+	Original bindings with no filepath argument are untouched and can be called as they were.
+
+- Added new primitive drawing functions to `PrimitiveMan`:  
+	```lua
+	-- Polygon
+	PrimitiveMan:DrawPolygonPrimitive(Vector startPos, color, { Vector vertexRelPos, ... })
+	PrimitiveMan:DrawPolygonPrimitive(player, Vector startPos, { Vector vertexRelPos, ... })
+
+	PrimitiveMan:DrawPolygonFillPrimitive(Vector startPos, color, { Vector vertexRelPos, ... })
+	PrimitiveMan:DrawPolygonFillPrimitive(player, Vector startPos, { Vector vertexRelPos, ... })
+	```
+	The vertices table contains `Vector`s with the position of each vertex of the polygon **RELATIVE** to the starting position. The starting position will be automatically added to each vertex position, doing so manually will lead to unexpected results.  
+	A minimum of 2 vertices (which would result in a line) are required to draw a polygon primitive. A console error will be printed and drawing will be skipped if less are provided.  
+	There may be a limit for the number of vertices in `PolygonFillPrimitive` because it has different handling but it was not reached during testing.
+
+	The order of vertices is of high importance. Bad ordering will lead to unexpected results.  
+	For example: `{ Vector(10, 0), Vector(10, 10), Vector(0, 10), Vector(0, 0) }` will result in a square, while `{ Vector(10, 0), Vector(0, 10), Vector(10, 10), Vector(0, 0) }` will result in an hourglass shape.  
+	Note that **all** vertices of the shape must be specified, as the last vertex will be connected to the first vertex and not to the starting position (whether it is used as center or as a corner) to complete the shape.  
+	Omitting the last `Vector(0, 0)` in the above example would result in a right angle triangle.
+
+	**The `Vector`s in the vertices table are single use! They will be deleted after being drawn, so they cannot be re-used!**
+
+	Usage example:
+	```lua
+	local myVertices = {
+		Vector(10, 0),
+		Vector(10, 10),
+		Vector(0, 10),
+		Vector(0, 0)
+	};
+	PrimitiveMan:DrawPolygonPrimitive(self.Pos, 13, myVertices);
+
+	-- myVertices no longer contains valid Vectors for this call, they were deleted after being drawn by the previous call.
+	PrimitiveMan:DrawPolygonFillPrimitive(self.Pos, 13, {
+		Vector(10, 0),
+		Vector(10, 10),
+		Vector(0, 10),
+		Vector(0, 0)
+	});
+	```
+
+- Added blended drawing functions to `PrimitiveMan`:  
+	There are 10 blending modes available to produce different color and transparency effects for both true primitives and bitmap based primitives.  
+	Blended drawing effects are not the same as post-processing (glows), as they are all drawn in indexed color mode and will produce widely different results.
+
+	**Note that blended drawing is very expensive and chugs FPS like no tomorrow. It should not be abused!**
+
+	There are 3 blended drawing function overloads:
+
+	* `PrimitiveMan:DrawPrimitives(blendMode, blendAmountR, blendAmountG, blendAmountB, blendAmountA, { primitiveObj, ... })`  
+	This is the fully fledged blended drawing function which allows individual control over each color channel blend amount.  
+	Blend amounts are in percentages, where 0 means no blending and 100 means full blending (e.g. `blendAmountA = 100` will result in a fully transparent primitive, as if it was not drawn at all).  
+	The blend mode and amounts will be applied to all the primitives in the primitive table.  
+	Note that blend amounts are internally rounded to multiples of 5 (e.g. 32 will round to 30, 33 will round to 35) to reduce memory usage and because smaller steps are hardly noticeable.
+	
+	* `PrimitiveMan:DrawPrimitives(blendMode, blendAmountRGBA, { primitiveObj, ... })`  
+	This overload allows selecting a blend mode and applies the blend amount to all color channels at once.  
+	This overload is for convenience when using certain modes (e.g. `Invert` and `Dissolve`). See blend mode specifics further below.
+	
+	* `PrimitiveMan:DrawPrimitives(transBlendAmount, { primitiveObj, ... })`  
+	This overload uses the transparency blending mode and applies the blend amount to all color channels at once.  
+	Transparency blending is likely to be the most commonly used mode so this exists for convenience.
+
+	The blending modes are defined in the new `DrawBlendMode` enum as follows:
+	```
+	(0)  NoBlend
+	(1)  Burn
+	(2)  Color
+	(3)  Difference
+	(4)  Dissolve
+	(5)  Dodge
+	(6)  Invert
+	(7)  Luminance
+	(8)  Multiply
+	(9)  Saturation
+	(10) Screen
+	(11) Transparency
+	(12) BlendModeCount
+	```
+	The blending modes are common and information on what the result of each is can be found with a quick search.
+
+	Some blend mode specifics:
+	* `Invert` and `Dissolve` modes only use alpha channel blend amount. RGB channels blend amounts are ignored in these modes.  
+	* `Transparency` mode ignores alpha channel blend amount. Only RGB channels blend amounts are used in this mode.  
+	* Some trial and error is expected to produce desired results in other modes.
+
+	The primitives table must be filled with `GraphicalPrimitive` objects. For this the constructors for all the supported primitives have been exposed:
+	```lua
+	LinePrimitive(player, startPos, endPos, color)
+	ArcPrimitive(player, centerPos, startAngle, endAngle, radius, thickness, color)
+	SplinePrimitive(player, startPos, guideA, guideB, endPos, color)
+	BoxPrimitive(player, topLeftPos, bottomRightPos, color)
+	BoxFillPrimitive(player, topLeftPos, bottomRightPos, color)
+	RoundedBoxPrimitive(player, topLeftPos, bottomRightPos, cornerRadius, color)
+	RoundedBoxFillPrimitive(player, topLeftPos, bottomRightPos, cornerRadius, color)
+	CirclePrimitive(player, centerPos, radius, color)
+	CircleFillPrimitive(player, centerPos, radius, color)
+	EllipsePrimitive(player, centerPos, horizRadius, vertRadius, color)
+	EllipseFillPrimitive(player, centerPos, horizRadius, vertRadius, color)
+	TrianglePrimitive(player, pointA, pointB, pointC, color)
+	TriangleFillPrimitive(player, pointA, pointB, pointC, color)
+	TextPrimitive(player, pos, text, useSmallFont, alignment, rotAngle)
+	BitmapPrimitive(player, centerPos, moSprite, rotAngle, frame, hFlipped, vFlipped)
+	BitmapPrimitive(player, centerPos, filePath, rotAngle, hFlipped, vFlipped)
+	```
+	Note that `PolygonPrimitive`, `IconPrimitive` and `LinePrimitive` with thickness do not support blended drawing.
+
+	**The `GraphicalPrimitive`s in the primitives table are single use! They will be deleted after being drawn, so they cannot be re-used!**
+
+	Usage example:
+	```lua
+	local myPrimitives = {
+		CircleFillPrimitive(-1, self.Pos + Vector(-100, 0), 20, 13),
+		BitmapPrimitive(-1, self.Pos + Vector(100, 0), "Base.rte/Craft/Rockets/MK2/RocketMK2000.png", 0, false, false)
+	};
+	PrimitiveMan:DrawPrimitives(DrawBlendMode.Screen, 50, 0, 50, 0, myPrimitives);
+
+	-- myPrimitives no longer contains valid primitives for this call, they were deleted after being drawn by the previous call.
+	PrimitiveMan:DrawPrimitives(DrawBlendMode.Dissolve, 50, {
+		CircleFillPrimitive(-1, self.Pos + Vector(-100, -100), 20, 13),
+		BitmapPrimitive(-1, self.Pos + Vector(100, -100), "Base.rte/Craft/Rockets/MK2/RocketMK2000.png", 0, false, false)
+	});
+
+	PrimitiveMan:DrawPrimitives(50, {
+		CircleFillPrimitive(-1, self.Pos + Vector(-100, -200), 20, 13),
+		BitmapPrimitive(-1, self.Pos + Vector(100, -200), "Base.rte/Craft/Rockets/MK2/RocketMK2000.png", 0, false, false)
+	});
+
+	-- NoBlend will draw the primitives without any blending mode (solid mode). Any color channel blend amounts are ignored.
+	PrimitiveMan:DrawPrimitives(DrawBlendMode.NoBlend, 0, 0, 0, 0, {
+		CircleFillPrimitive(-1, self.Pos + Vector(-100, -300), 20, 13),
+		BitmapPrimitive(-1, self.Pos + Vector(100, -300), "Base.rte/Craft/Rockets/MK2/RocketMK2000.png", 0, false, false)
+	});
+	-- It is equivalent to calling the individual draw functions like so:
+	-- PrimitiveMan:DrawCircleFillPrimitive(-1, self.Pos + Vector(-100, -200), 20, 13);
+	-- PrimitiveMan:DrawBitmapPrimitive(-1, self.Pos + Vector(100, -200), "Base.rte/Craft/Rockets/MK2/RocketMK2000.png", 0, false, false);
+	```
+
 - New `Vector` Lua (R/O) property `SqrMagnitude` which returns the squared magnitude of the `Vector`.  
 	Should be used for more efficient comparison with `vector.SqrMagnitude > (floatValue * floatValue)` over `vector.Magnitude > floatValue`.
 
@@ -321,6 +472,9 @@ This can be accessed via the new Lua (R/W) `SettingsMan` property `AIUpdateInter
 
 - Added Lua access (R/W) to `Attachable` property `DeleteWhenRemovedFromParent`, which determines whether the given `Attachable` should delete itself when it's removed from its current parent.
 
+- Added Lua convenience function `RoundToNearestMultiple(num, multiple)` which returns a number rounded to the nearest specified multiple.  
+	Note that this operates on integers, so fractional parts will be truncated towards zero by type conversion.
+
 </details>
 
 <details><summary><b>Changed</b></summary>
@@ -460,6 +614,9 @@ This can be accessed via the new Lua (R/W) `SettingsMan` property `AIUpdateInter
 
 - The keyboard shortcut for clearing the console is now `F10`, since `F5` is used for quick-saving (`F9` quick-loads).
 
+- `BitmapPrimitive` drawing functions now accept `MOSprite` instead of `Entity` for the object they get the bitmap to draw from.  
+	This changes nothing regarding the bindings, but will now print an error to the console when attempting to draw a non-`MOSprite` based object (e.g. `MOPixel`), instead of silently skipping it.
+
 </details>
 
 <details><summary><b>Fixed</b></summary>

Entities/PieMenu.cpp

@@ -589,7 +589,7 @@ namespace RTE {
 
 		if (m_EnabledState != EnabledState::Disabled) {
 			if (m_DrawBackgroundTransparent && !g_FrameMan.IsInMultiplayerMode()) {
-				g_FrameMan.SetTransTable(MoreTrans);
+				g_FrameMan.SetTransTableFromPreset(TransparencyPreset::MoreTrans);
 				draw_trans_sprite(targetBitmap, m_BGBitmap, drawPos.GetFloorIntX() - m_BGBitmap->w / 2, drawPos.GetFloorIntY() - m_BGBitmap->h / 2);
 			} else {
 				draw_sprite(targetBitmap, m_BGBitmap, drawPos.GetFloorIntX() - m_BGBitmap->w / 2, drawPos.GetFloorIntY() - m_BGBitmap->h / 2);

Lua/LuaAdapterDefinitions.h

@@ -20,6 +20,7 @@
 #include "Box.h"
 #include "Controller.h"
 #include "DataModule.h"
+#include "GraphicalPrimitive.h"
 
 #include "GUIBanner.h"
 #include "BuyMenuGUI.h"
@@ -437,6 +438,77 @@ namespace RTE {
 	};
 #pragma endregion
 
+#pragma region PrimitiveMan Lua Adapters
+	struct LuaAdaptersPrimitiveMan {
+		/// <summary>
+		/// Schedule to draw a polygon primitive.
+		/// </summary>
+		/// <param name="primitiveMan">A reference to PrimitiveMan, provided by Lua.</param>
+		/// <param name="centerPos">Position of primitive's center in Scene coordinates.</param>
+		/// <param name="color">Color to draw primitive with.</param>
+		/// <param name="verticesTable">A Lua table that contains the positions of the primitive's vertices, relative to the center position.</param>
+		static void DrawPolygonPrimitive(PrimitiveMan &primitiveMan, const Vector &centerPos, int color, const luabind::object &verticesTable);
+
+		/// <summary>
+		/// Schedule to draw a polygon primitive visible only to a specified player.
+		/// </summary>
+		/// <param name="primitiveMan">A reference to PrimitiveMan, provided by Lua.</param>
+		/// <param name="player">Player screen to draw primitive on.</param>
+		/// <param name="centerPos">Position of primitive's center in Scene coordinates.</param>
+		/// <param name="color">Color to draw primitive with.</param>
+		/// <param name="verticesTable">A Lua table that contains the positions of the primitive's vertices, relative to the center position.</param>
+		static void DrawPolygonPrimitiveForPlayer(PrimitiveMan &primitiveMan, int player, const Vector &centerPos, int color, const luabind::object &verticesTable);
+
+		/// <summary>
+		/// Schedule to draw a filled polygon primitive.
+		/// </summary>
+		/// <param name="primitiveMan">A reference to PrimitiveMan, provided by Lua.</param>
+		/// <param name="startPos">Start position of the primitive in Scene coordinates.</param>
+		/// <param name="color">Color to draw primitive with.</param>
+		/// <param name="verticesTable">A Lua table that contains the positions of the primitive's vertices, relative to the center position.</param>
+		static void DrawPolygonFillPrimitive(PrimitiveMan &primitiveMan, const Vector &startPos, int color, const luabind::object &verticesTable);
+
+		/// <summary>
+		/// Schedule to draw a filled polygon primitive visible only to a specified player.
+		/// </summary>
+		/// <param name="primitiveMan">A reference to PrimitiveMan, provided by Lua.</param>
+		/// <param name="player">Player screen to draw primitive on.</param>
+		/// <param name="startPos">Start position of the primitive in Scene coordinates.</param>
+		/// <param name="color">Color to draw primitive with.</param>
+		/// <param name="verticesTable">A Lua table that contains the positions of the primitive's vertices, relative to the center position.</param>
+		static void DrawPolygonFillPrimitiveForPlayer(PrimitiveMan &primitiveMan, int player, const Vector &startPos, int color, const luabind::object &verticesTable);
+
+		/// <summary>
+		/// Schedules to draw multiple primitives of varying type with transparency enabled.
+		/// </summary>
+		/// <param name="primitiveMan">A reference to PrimitiveMan, provided by Lua.</param>
+		/// <param name="transValue">The transparency value the primitives should be drawn at. From 0 (opaque) to 100 (transparent).</param>
+		/// <param name="primitivesTable">A Lua table of primitives to schedule drawing for.</param>
+		static void DrawPrimitivesWithTransparency(PrimitiveMan &primitiveMan, int transValue, const luabind::object &primitivesTable);
+
+		/// <summary>
+		/// Schedule to draw multiple primitives of varying type with blending enabled.
+		/// </summary>
+		/// <param name="primitiveMan">A reference to PrimitiveMan, provided by Lua.</param>
+		/// <param name="blendMode">The blending mode the primitives should be drawn with. See DrawBlendMode enumeration.</param>
+		/// <param name="blendAmount">The blending amount for all the channels. 0-100.</param>
+		/// <param name="primitivesTable">A Lua table of primitives to schedule drawing for.</param>
+		static void DrawPrimitivesWithBlending(PrimitiveMan &primitiveMan, int blendMode, int blendAmount, const luabind::object &primitivesTable);
+
+		/// <summary>
+		/// Schedule to draw multiple primitives of varying type with blending enabled.
+		/// </summary>
+		/// <param name="primitiveMan">A reference to PrimitiveMan, provided by Lua.</param>
+		/// <param name="blendMode">The blending mode the primitives should be drawn with. See DrawBlendMode enumeration.</param>
+		/// <param name="blendAmountR">The blending amount for the Red channel. 0-100.</param>
+		/// <param name="blendAmountG">The blending amount for the Green channel. 0-100.</param>
+		/// <param name="blendAmountB">The blending amount for the Blue channel. 0-100.</param>
+		/// <param name="blendAmountA">The blending amount for the Alpha channel. 0-100.</param>
+		/// <param name="primitivesTable">A Lua table of primitives to schedule drawing for.</param>
+		static void DrawPrimitivesWithBlendingPerChannel(PrimitiveMan &primitiveMan, int blendMode, int blendAmountR, int blendAmountG, int blendAmountB, int blendAmountA, const luabind::object &primitivesTable);
+	};
+#pragma endregion
+
 #pragma region Utility Lua Adapters
 	struct LuaAdaptersUtility {
 		/// <summary>