Documentation for `SubCameraView` is confusing and bad

[BigWingBeat]

For context, I was trying to create a magnifier that zooms in on part of the screen. The example for SubCameraView explicitly lists this as one of its intended use cases, however after ~1 hour of reading the example code, the associated documentation, and trying to implement it myself, I couldn't figure it out.

I then looked at the render-to-texture example and successfully used that feature instead to implement the magnifier as I wanted in just a few minutes.

Some of the issues I had with the SubCameraView docs include:

• The example is cluttered and overcomplicated, with 8 different cameras crammed into a single screen. This makes it very difficult to understand just what exactly any single camera is actually doing with the feature in question.
• The units used by SubCameraView are undocumented. Through experimentation I'm pretty sure it's physical pixels, but that isn't mentioned anywhere that I could find.
• The fields on the type are described using terms like "size" and "offset", which makes you think their effect is "linear", but they actually describe a ratio, which has a "proportional" effect instead.
• The fact that it's actually a ratio, despite being critical information, is only mentioned once at the bottom of the type's documentation, and isn't even phrased as an explanation. Instead, it presumes that you are already aware of that being the case, and is just explaining some part of the unhelpful example instead.

[alice-i-cecile]

Very constructive; these are exactly the sorts of complaints that I like to hear!

[BigWingBeat]

Additionally, I think part of the problem is that SubCameraView is just a poorly designed API to begin with. The goal is, ultimately, to define a rectangular area somewhere in the camera's viewport, but it's done in a very unusual and somewhat implicit way.

The size of the rect is (I think?) a percentage of the size of the whole viewport, expressed as a ratio between the values of the size and full_size fields. The position of the rect is defined by the offset field, but is also relative to the value of full_size in some way.

Ideally, these fields should directly describe the area of the sub view, in a way that doesn't require you to do maths in your head, like it does currently.

[alice-i-cecile]

If you'd like to take a crack at either the docs or refactoring I'd be happy to review it!