litiengine extra camera dev notes

I have taken up the task of adding support for "more than one camera" in litiengine.

Now, there are few details that come with this feature, so I have to make assumtions.
So, I make two major assumtions of use-cases here.

1: user wants to hot-switch between two diffrent cameras on the fly.
2: The user want to watch two or more different perspectives at the same time on the same screen.
2b: possebly in some complex ui layout.

My goal would be to create a feature that would cover both usecases

Some notes on existing structure regarding the camera:
	1: Camera is data and calculation only, it does not render anything.
	2: The Camera class is not a singleton (it could easely have been one, luckly it is not)
	3: The camera class is only ever created once as a part of the GameWorld class, which is a singleton.
	4: The private value of GameWorld#camera is never used directly outside a standard setter / getter pattern.
	5: The setter is only used indirectly via GameWorld#setCamera
	6: While setCamera is only used once by the engine itself, it is left exposed to use by game projects, presumably as standard API.

So, this creates a starting point.
I need to add support for more cameras to GameWorld.

Current idea on how to do this:
* Add a new integer property GameWorld#currentCamera. This is used when rendering to keep track of the index what camera is in use.
* Change the private variable GameWorld#camera from a single iCamera value to a iCamera array.
	* This invalidates the setter and getter. fix: add new setter and getter with index paramater, have the old setter and getter redirect with index GameWorld#currentCamera
	* Problem: GameWorld#camera still must be initalized, but it is now an array.
	* Possible fixes:
		* Use a dynamic list (may be costly)
		* Use an array utility tool to rebuild a new array everytime a camera is added or removed. (may be a bit of a kludge)
		* Have number of cameras set in game settings, and default to 2.
	* In any case, at least one camera must be created and initiated.
* Problem: The feature issue mention the need to clip the camera render.
	* This is presumably a part of usecase #2.
	* Fix: when starting render of viewport of camera, create a child graphics object with a restricted cliprect. This is a native feature we should be able to trust.


Before I can start doing anything, I need  a plan, and I need to understand the render-flow of the engine

* The GameWindow class is an indirect singleton via the Game class. There is no need to change this (with the possible exception of merging GameWindow into Game)
* GameWindow contains two properties of interest. The renderCanvas (RenderComponent) and hostControl (JFrame). All rendering seems to be done on renderCanvas.
		* note: there is a naming inconsistency here. The getter for GameWindow#renderCanvas is named GameWindow#GetRenderComponent, and is of class RenderComponent.
* The Graphics instance used to render EVERYTHING seems to be created in RenderComponent#Render via the RenderComponent#currentBufferStrategy property.
	* I super-duper do not want to fuck with this.
	* BufferStrategy is part of the AWT package, so I suppose I can confirm I have found the root of the Graphics object for the engine.
	* The RenderComponent#render function does wisely set the cliprect of the master Graphics object.
	* There are never created any child graphics objects of the master Graphics Object.
	* This is a HUGE problem, as any render function could mess up everything called afterwards.
	* The master Graphics Object is cliped in GuiComponent#render, only to be restored shortly afterwards.
* The render flow is as such
	1: GameLoop calls RenderComponent#render
	2: render updates fade values
	3: render gets a new Graphics2D from the buffer system (presumably it is created in that system somewhere somehow, not important)
	4: render fills with background color and sets AA and interpolation settings
	5: render gets the current Screen object from Game.
	6: render calls render on the current screen.
	7: render calls render on the cursor object
	8: ?? render runns accept on a list of renderedComsumer
		I need to figure out what this is used for.
		This looks like an Event pattern.
	9: render applies fade effect if any.
	10:render takes and saves screenshot, if requested.
		NOTE: this is done by rendering current screen all over again !!
		NOTE: fade effet would not be applied on screenshot.

* Based on this, I can form a plan for implementing mulible camera support.
* First of, add the extra camera support as theorized earlier.
* NOTE: first idea for this next part was based on Screen overwriteing render from GuiComponent, but this would be void as GameScreen runs it's render before calling super.
* So a change has to happen in RenderComponent.
	* In RenderComponent#render, add the following after `if (currentScreen != null) {`
		1: create a child instance of argument Graphics2D g, let's call it screenG.
		2: apply any required local translations of the Screen object (x, y, clipRect, rotation, scale, etc.) to screenG.
		3: change `currentScreen.render(g);` to `currentScreen.render(screenG);`
	* Now in Screen class:
		* Remove the setX and setY overrides, as the given statement in those comments are now incorrect.

* What does this give us?
	* A screen may now exist on any arbitrary place within the rendering canvas, and should, if I understand awt correctly, clip accourding to the cliprect.
	* We are limited to just one screen object, and the game only uses one camera.
* To implement a use of extra cameras, we add a feature to GameScreen.
	* Note: we do not need to touch the Screen class for this, as it does not use a camera.

* In the GameScreen class:
	* add this parameter: `int cameraIndex`.
	* add a setter for cameraIndex that checks if the index is legal compared to the GameWorld settings (sets to 0 if it fails)
	* in the existing constructors, initiate cameraIndex with the value 0.
	* Add a new constructor that takes in the parameters `(String name, int cameraIndex)`, have it set cameraIndex using the setter (as in, do not trust the input, aka assume the user (game developer) is an idiot, as we often are)

* With that, we now have cover for usercase #1, and laid the groundwork for usercase #2 and #2b.
* Next fix is: support for multible screens instances!
* Again, this will take some changes, as like the camera, the game assumes there can only be one Screen object active at the time.
	* First, in Screen class:
		* Add a new int property Screen#screenLayer
		* in the existing constructor, initialize screenLayer as 0
		* Create a new constructor with a parameter for screenLayer.
	* In GameScreen:
		* Add a complementary constructor that passes a ScreenLayer to its superclass Screen
	* This one is worse, however, as the ScreenManager includes properties that relies on this assumption. Care must be made to prevent feature-braking.
	* First of, replace ScreenManager#currentScreen property with a new ScreenManager#activeScreens property of type dynamic list of Screen.
	* Add a new getter ScreenManager#ActiveScreens for ScreenManager#activeScreens.
	* Mark the getter ScreenManager#CurrentScreen as obsolete (or depreacted), and have it return the first item in ScreenManager#ActiveScreens as a fallback.

	* Add a new function ScreenManager#RemoveScreen with parameter oldScreen
		* It should do this:
			1: return if oldScreen is null or not found in activeScreens
			2: call suspend on oldScreen
		* To keep with the code pattern, add a string overload oldScreenName
			* Find oldScreen by name from ActiveScreens, remove if found.
	* As replacements ScreenManager#Display, add a new function ScreenManager#ReplaceDisplay that takes two arguments: Screen oldScreen and Screen newScreen.
		* To keep with the existing pattern, add an overload with arguments: String oldScreenName and String newScreenName.
			* Get a ScreenObject from ScreenManager#ActiveScreens by searching for oldScreenName. This will be used as argument Screen oldScreen
			* Reuse code from ScreenManager#Display(String) to get Screen newScreen from newScreenName.
			* Call ScreenManager#ReplaceDisplay(Screen, Screen)
				* Note: null-values should be logged, but will be handled.
		* This new function will have this flow:
			1: Call ScreenManager#RemoveScreen on oldScreen.
				* null value will be handled, and is safe
			2: return if newScreen is null.
			3: return if newScreen already exist in activeScreens
			4: Add newScreen to activeScreens
			5: sort activeScreens by Screen#screenLayer
			6: call prepeare on NewScreen
	* Add a new function ScreenManager#AddDisplay, with a Screen argument and an overload with a string argument. Have them both redirect to their equivalent ScreenManager#ReplaceDisplay with null as argument for oldScreen.
		* Since there are null-handlers in ReplaceDisplay, this is fine, we don't need to duplicate code
	* Mark both overloads of ScreenManager#Display as obsolete/depracted, have them redirect to ScreenManager#ReplaceDisplay with first item of ScreenManager#activeScreens as the argument for oldScreen

* Last thing to do, is to change up RenderComponent#render once again.
	* remove the line ´final Screen currentScreen = Game.screens().current();´
	* Replace ´if (currentScreen != null) {´ with ´for each ( Screen currentScreen : Game.screens().ActiveScreens()´
	* Find the line for rendering screenshots ´currentScreen.render(imgGraphics);´, wrap it with the same for each loop as above.

	* Note: no replacements found so far for the cooldown properties. implementing them in the same way may break intended use. However, since repeated calls for adding the same screen would be stopped before reaching the prepeare call, we should be good.
	* Note: further enhancements could be made by adding functions that sets the translations of all active screens into a desired layout, for example side-by-side for use in co-op.
	* Note: Since RenderEngine#renderEnteties has been marked as a costly function, I suggest an optimization of filtering for all screens and storing the list as a first step in the render flow, that way we can save on some prosessing power when adding more than one GameScreen.


And now, dear reader of my notes, know that at time of writing these 137 lines of notes, not a single line of real code has been written so far.
Implementation begins soon. And I hope it goes according to plan.