Improve FlxBitmapText rendering when using renderTile with clipRect (#3395)

* check cliprect changes earlier

* trigger CI again

* optional alpha arg

* add various colorTransform helpers

* add FlxFrame.overlaps

* make FlxFrame constructor public

* add CharList and cleanup text rendering/iteration

* add forEachBorder helper

* add rect.contains, frame.contains and frame.isContained

* improve draw perf by avoiding unnecessary frame clipping

* doc plus optional alpha

* unit tests

* doc

* use MatrixVector to cache draw matrices

* resuse a frame instance for tile drawing

* test more optional args

* remove rgb optional args

Author: Geokureli

flixel/graphics/frames/FlxFrame.hx

@@ -139,13 +139,13 @@ class FlxFrame implements IFlxDestroyable
 	 */
 	public var type:FlxFrameType;
 
-	var tileMatrix:Vector<Float>;
-
-	var blitMatrix:Vector<Float>;
+	/** Internal cache used to draw this frame **/
+	var tileMatrix:MatrixVector;
+	
+	/** Internal cache used to draw this frame **/
+	var blitMatrix:MatrixVector;
 
-	@:allow(flixel.graphics.FlxGraphic)
-	@:allow(flixel.graphics.frames.FlxFramesCollection)
-	function new(parent:FlxGraphic, angle = FlxFrameAngle.ANGLE_0, flipX = false, flipY = false, duration = 0.0)
+	public function new(parent:FlxGraphic, angle = FlxFrameAngle.ANGLE_0, flipX = false, flipY = false, duration = 0.0)
 	{
 		this.parent = parent;
 		this.angle = angle;
@@ -158,35 +158,21 @@ class FlxFrame implements IFlxDestroyable
 		sourceSize = FlxPoint.get();
 		offset = FlxPoint.get();
 
-		blitMatrix = new Vector<Float>(6);
+		blitMatrix = new MatrixVector();
 		if (FlxG.renderTile)
-			tileMatrix = new Vector<Float>(6);
+			tileMatrix = new MatrixVector();
 	}
 
 	@:allow(flixel.graphics.frames.FlxFramesCollection)
 	@:allow(flixel.graphics.frames.FlxBitmapFont)
 	function cacheFrameMatrix():Void
 	{
-		prepareBlitMatrix(_matrix, true);
-		blitMatrix[0] = _matrix.a;
-		blitMatrix[1] = _matrix.b;
-		blitMatrix[2] = _matrix.c;
-		blitMatrix[3] = _matrix.d;
-		blitMatrix[4] = _matrix.tx;
-		blitMatrix[5] = _matrix.ty;
+		blitMatrix.copyFrom(this, true);
 
 		if (FlxG.renderTile)
-		{
-			prepareBlitMatrix(_matrix, false);
-			tileMatrix[0] = _matrix.a;
-			tileMatrix[1] = _matrix.b;
-			tileMatrix[2] = _matrix.c;
-			tileMatrix[3] = _matrix.d;
-			tileMatrix[4] = _matrix.tx;
-			tileMatrix[5] = _matrix.ty;
-		}
+			tileMatrix.copyFrom(this, false);
 	}
-
+	
 	/**
 	 * Applies frame rotation to the specified matrix, which should be used for tiling or blitting.
 	 * Required for rotated frame support.
@@ -195,7 +181,7 @@ class FlxFrame implements IFlxDestroyable
 	 * @param   blit   Whether specified matrix will be used for blitting or for tile rendering.
 	 * @return  Transformed matrix.
 	 */
-	inline function prepareBlitMatrix(mat:FlxMatrix, blit:Bool = true):FlxMatrix
+	inline function prepareBlitMatrix(mat:FlxMatrix, blit = true):FlxMatrix
 	{
 		mat.identity();
 
@@ -218,7 +204,7 @@ class FlxFrame implements IFlxDestroyable
 	}
 
 	/**
-	 * Rotates and flips matrix. This method expects matrix which was prepared by `prepareBlitMatrix()`.
+	 * Rotates and flips matrix. This method expects matrix which was prepared by `MatrixVector.copyTo()`.
 	 * Internal use only.
 	 *
 	 * @param   mat        Matrix to transform
@@ -278,7 +264,7 @@ class FlxFrame implements IFlxDestroyable
 	 */
 	function prepareTransformedBlitMatrix(mat:FlxMatrix, rotation:FlxFrameAngle = FlxFrameAngle.ANGLE_0, flipX:Bool = false, flipY:Bool = false):FlxMatrix
 	{
-		mat = fillBlitMatrix(mat);
+		blitMatrix.copyTo(mat);
 		return rotateAndFlip(mat, rotation, flipX, flipY);
 	}
 
@@ -299,12 +285,7 @@ class FlxFrame implements IFlxDestroyable
 			return mat;
 		}
 
-		mat.a = tileMatrix[0];
-		mat.b = tileMatrix[1];
-		mat.c = tileMatrix[2];
-		mat.d = tileMatrix[3];
-		mat.tx = tileMatrix[4];
-		mat.ty = tileMatrix[5];
+		tileMatrix.copyTo(mat);
 
 		var doFlipX = flipX != this.flipX;
 		var doFlipY = flipY != this.flipY;
@@ -315,17 +296,6 @@ class FlxFrame implements IFlxDestroyable
 		return rotateAndFlip(mat, rotation, doFlipX, doFlipY);
 	}
 
-	inline function fillBlitMatrix(mat:FlxMatrix):FlxMatrix
-	{
-		mat.a = blitMatrix[0];
-		mat.b = blitMatrix[1];
-		mat.c = blitMatrix[2];
-		mat.d = blitMatrix[3];
-		mat.tx = blitMatrix[4];
-		mat.ty = blitMatrix[5];
-		return mat;
-	}
-
 	/**
 	 * Draws frame on specified `BitmapData` object.
 	 *
@@ -355,7 +325,7 @@ class FlxFrame implements IFlxDestroyable
 		}
 		else
 		{
-			fillBlitMatrix(_matrix);
+			blitMatrix.copyTo(_matrix);
 			if (point != null)
 				_matrix.translate(point.x, point.y);
 
@@ -584,7 +554,53 @@ class FlxFrame implements IFlxDestroyable
 		copyTo(clippedFrame);
 		return clippedFrame.clip(rect);
 	}
-
+	
+	/**
+	 * Whether there is any overlap between this frame and the given rect. If clipping this frame to
+	 * the given rect would result in an empty frame, the result is `false`
+	 * @since 6.1.0
+	 */
+	public function overlaps(rect:FlxRect)
+	{
+		rect.x += frame.x - offset.x;
+		rect.y += frame.y - offset.y;
+		final result = rect.overlaps(frame);
+		rect.x -= frame.x - offset.x;
+		rect.y -= frame.y - offset.y;
+		return result;
+	}
+	
+	
+	/**
+	 * Whether this frame fully contains the given rect. If clipping this frame to
+	 * the given rect would result in a smaller frame, the result is `false`
+	 * @since 6.1.0
+	 */
+	public function contains(rect:FlxRect)
+	{
+		rect.x += frame.x - offset.x;
+		rect.y += frame.y - offset.y;
+		final result = frame.contains(rect);
+		rect.x -= frame.x - offset.x;
+		rect.y -= frame.y - offset.y;
+		return result;
+	}
+	
+	/**
+	 * Whether this frame is fully contained by the given rect. If clipping this frame to
+	 * the given rect would result in a smaller frame, the result is `false`
+	 * @since 6.1.0
+	 */
+	public function isContained(rect:FlxRect)
+	{
+		rect.x += frame.x - offset.x;
+		rect.y += frame.y - offset.y;
+		final result = rect.contains(frame);
+		rect.x -= frame.x - offset.x;
+		rect.y -= frame.y - offset.y;
+		return result;
+	}
+	
 	/**
 	 * Clips this frame to the desired rect
 	 *
@@ -777,4 +793,125 @@ abstract FlxUVRect(FlxRect) from FlxRect to flixel.util.FlxPool.IFlxPooled
 	{
 		return FlxRect.get(l, t, r, b);
 	}
+}
+
+/**
+ * Used internally instead of a FlxMatrix, for some unknown reason.
+ * Perhaps improves performance, tbh, I'm skeptical
+ */
+abstract MatrixVector(Vector<Float>)
+{
+	public var a(get, set):Float;
+	inline function get_a() return this[0];
+	inline function set_a(value:Float) return this[0] = value;
+	
+	public var b(get, set):Float;
+	inline function get_b() return this[1];
+	inline function set_b(value:Float) return this[1] = value;
+	
+	public var c(get, set):Float;
+	inline function get_c() return this[2];
+	inline function set_c(value:Float) return this[2] = value;
+	
+	public var d(get, set):Float;
+	inline function get_d() return this[3];
+	inline function set_d(value:Float) return this[3] = value;
+	
+	public var tx(get, set):Float;
+	inline function get_tx() return this[4];
+	inline function set_tx(value:Float) return this[4] = value;
+	
+	public var ty(get, set):Float;
+	inline function get_ty() return this[5];
+	inline function set_ty(value:Float) return this[5] = value;
+	
+	
+	public inline function new ()
+	{
+		this = new Vector<Float>(6);
+		identity();
+	}
+	
+	public inline function identity()
+	{
+		a = 1;
+		b = 0;
+		c = 0;
+		d = 1;
+		tx = 0;
+		ty = 0;
+	}
+	
+	public inline function set(a = 1.0, b = 0.0, c = 0.0, d = 1.0, tx = 0.0, ty = 0.0)
+	{
+		set_a(a);
+		set_b(b);
+		set_c(c);
+		set_d(d);
+		set_tx(tx);
+		set_ty(ty);
+		return this;
+	}
+	
+	public inline function translate(dx:Float, dy:Float)
+	{
+		tx += dx;
+		ty += dy;
+		return this;
+	}
+	
+	public inline function scale(sx:Float, sy:Float)
+	{
+		a *= sx;
+		b *= sy;
+		c *= sx;
+		d *= sy;
+		tx *= sx;
+		ty *= sy;
+		return this;
+	}
+	
+	overload public inline extern function copyFrom(frame:FlxFrame, forBlit = true):MatrixVector
+	{
+		identity();
+
+		if (forBlit)
+			translate(-frame.frame.x, -frame.frame.y);
+
+		if (frame.angle == FlxFrameAngle.ANGLE_90)
+		{
+			set(-b, a, -d, c, -ty, tx);
+			translate(frame.frame.height, 0);
+		}
+		else if (frame.angle == FlxFrameAngle.ANGLE_NEG_90)
+		{
+			set(b, -a, d, -c, ty, -tx);
+			translate(0, frame.frame.width);
+		}
+
+		translate(frame.offset.x, frame.offset.y);
+		return cast this;
+	}
+	
+	overload public inline extern function copyFrom(mat:FlxMatrix):MatrixVector
+	{
+		a = mat.a;
+		b = mat.b;
+		c = mat.c;
+		d = mat.d;
+		tx = mat.tx;
+		ty = mat.ty;
+		return cast this;
+	}
+	
+	public inline function copyTo(mat:FlxMatrix):FlxMatrix
+	{
+		mat.a = a;
+		mat.b = b;
+		mat.c = c;
+		mat.d = d;
+		mat.tx = tx;
+		mat.ty = ty;
+		return mat;
+	}
 }

flixel/math/FlxRect.hx

@@ -285,6 +285,23 @@ class FlxRect implements IFlxPooled
 		return result;
 	}
 
+	/**
+	 * Checks to see if this rectangle fully contains another
+	 *
+	 * @param   rect  The other rectangle
+	 * @return  Whether this rectangle contains the given rectangle
+	 * @since 6.1.0
+	 */
+	public inline function contains(rect:FlxRect):Bool
+	{
+		final result = rect.left >= left
+			&& rect.right <= right
+			&& rect.top >= top
+			&& rect.bottom <= bottom;
+		rect.putWeak();
+		return result;
+	}
+
 	/**
 	 * Returns true if this FlxRect contains the FlxPoint
 	 *