Complete Camera Overhaul

[DragonMoffon]

The camera provided in Arcade currently has many issues that need to be fixed.
• Only provides a 2D orthographic camera
• Has janky and incorrect zoom functionality
• Has an update/use method that breaks arcade conventions
• Does not provide a way to rotate the camera
• SimpleCamera is not simple as it should be
• Normal camera has features that would be better served as an external class(es).

Okay, point three about the update methods might need explaining. Basically, the camera provides an update method, but it does not respect delta_time and is automatically called in the use method without a way to disable it. This means that camera speeds are variable based on the update rate and how many times a camera is used in a single draw call. On top of this, it also breaks arcade conventions by having non-draw logic within the draw call.

I propose that the cameras in Arcade be totally overhauled.

Proposed Changes:
• Provide simple dataclasses to store information about cameras.
• Provide an interface called Projector for objects, which sets the underlying arcade matrices.
• Create a Default Projector, Orthographic Projector, and Perspective Projector, which satisfy most people's needs.
• Use the Default Projector to allow users to safely use cameras in context managers
• Create a backwards-compatible recreation of SimpleCamera, but dissuade users from using it
• Create a new Camera2D that follows conventions and makes it easy for users to plug and play.
• Provide controller classes that users can use to move their Cameras easily in complex ways.
• An all-new tutorial, which explains how cameras in games actually work and how to use the arcade system best.
• Move all examples over to using Camera2D and the Camera Controllers.

Why do it this way?:
The reason that cameras are just represented by PoDs (Packets of Data) rather than fully fledged classes is to promote composition over inheritance. While Camera2D can be treated as though it stores all the data internally, the user should look to the PoDs for more complex use cases. An example benefit is when a user wants multiple projections to share a single position, you wouldn't have to do any position cloning. Or if you have multiple cameras that all have the same projection but are placed in different locations (like a CCTV system for example) then having them all share one projection PoD would save memory and decrease the chance of mistakes.

It also means that camera controllers don't need to know anything about the camera they are moving, and they can know about the position, direction, etc.

This is a breaking change that should occur in 3.0, with later improvements and tutorials coming in 3.1+.

Other issue(s) that can be solved at the same time:
#1592

NOTE I have already created a PR (#1818) and finished many of the features requested.

TODO LIST:

• Dataclasses for view and projection matrices
  • Camera Data (viewport, view data, zoom)
  • Orthographic Projection
  • Perspective Projection
• Projector and Camera Protocols for typing
• Default Projectors
  • A simple projector that Arcade uses internally
  • An orthographic projector capable of both 2D and 3D
  • A perspective projector capable of both 2D and 3D
• A competent replacement for SimpleCamera
• A re-implementation of SimpleCamera with a depreciation warning
• Provide camera controllers for ease of use
  • A track-to-point method as seen in SimpleCamera
  • A lerp to point method (2D and 3D)
  • An lerp to point which accepts an easing function (2D and 3D)
  • Methods to rotate the camera around the view axis (forward, up, right)
  • An isometric controller
  • "Debug" controllers that allow for arrow key control of the camera (2D and 3D)
  • 2D screen shake
  • ... ?
• An offscreen renderer
• VERY IMPORTANT. Remove internal assumptions about projection being Orthographic
• Make Window and ArcadeContext consistent about name of projection and viewport
• Fix sprite culling (difficult)
• Complete typing and Doc Strings
• Fixing all examples which used the old camera
• Improving examples with the new offscreen renderer
• Adding new examples
  • One that shows off the easing methods
  • A replacement for the SimpleCamera example
  • An isometric example
  • A debug example using the debug cameras
• A detailed tutorial page on how the camera's work
• A camera section for the API quick index
• ... ?

[DragonMoffon]

Cant set myself as assigne, but alg.

[DragonMoffon]

Also I can set the labels when first making the issue, but they don't show up at all.

[DragonMoffon]

Also going to add an easy way to render an fbo to screen. Litterally just because I've written it for myself

[DragonMoffon]

Also, a whole bunch of examples have been updated to use the replacement SimpleCamera, and they should be moved over to Camera2D sooner rather than later. They are also missing screen shake.

[alejcas]

Just to have the reference here: #1965 (Camera overhaul simple) was merged into development

[einarf]

Still some things to go through there, but I think we're at least in a better shape.

[alejcas]

Camera shake is not working now on arcade 3.0 dev 26

using python 3.11 running example camera_platform.py

[einarf]

Camera shake is not working now on arcade 3.0 dev 26

using python 3.11 running example camera_platform.py

Can just make a quick issue. I created one now: #2045

[DragonMoffon]

Yup the screen shake in multiple examples and the platformer tutorial all fell victim to merge conflicts