New surface methods request: Surface#pushClip and Surface#popClip

[postcasio]

I propose the addition of two new Surface methods to handle clipping rectangles.

Typically when I'm writing a rendering function that requires clipping, what I want to do is clip at the start of the function and then restore whatever the clip was previously before, so that the calling code doesn't need to be aware that clipping is even happening and the clip state is always the same coming out of a function as it is going in. So I always write these two functions to make it a lot easier.

Each Surface will maintain a stack of clipping rectangles. The top of the stack is the current clipping rectangle.

Surface#pushClip(x, y, w, h) Push a clipping rectangle onto the top of the clipping rectangle stack.

Surface#popClip() Pop the last clipping rectangle off the clipping rectangle stack, restoring the previous clipping rectangle. If there are no remaining clipping rectangles, disable clipping.

It would also be nice if these methods could handle intersections when there are multiple rectangles on the stack. For example, if you clip to 0,0,20,20, then clip to 10,10,40,40, the intersection and thus actual clipped area would be 10,10,10,10

[fatcerberus]

I think I had this idea, but decided the go with the current design to keep the base API more low-level. It might be worth giving this another look though, as it might align better with how clipping is typically managed.

[fatcerberus]

I’m going to implement this for API level 4. I’ll see if I can come up with a backward-compatible API design for it.

[fatcerberus]

Initial implementation is now in main, at https://github.com/spheredev/neosphere/commit/fa5a00496faa96f91d27af4cb75f529235e5ebe9. First real feature work in quite a while!