Skip to main content ↑ ↓
Topic: API design: Should the clipping rect be reset on flip? (Read 85803 times) previous topic - next topic
0 Members and 2 Guests are viewing this topic.

API design: Should the clipping rect be reset on flip?

In Sphere 1.x, the effect of SetClippingRectangle() persists across FlipScreen calls.  In practice this usually forces me to save and restore the clipping rectangle in order to maintain modularity.  For Sphere 2.0, I was debating making it so that screen.clip() lasts only until the next flip.  How does everyone feel about that?

Re: API design: Should the clipping rect be reset on flip?

Reply #1 –
I think it's better to not change the clipping rect on flip. That causes more implicit rules. Without it, you know there is only one function that changes the clipping rect: SetClippingRect. With the change, you need to remember there are two, SetClippingRect and FlipScreen.

And I can also imagine getting a few support topics, "Why is the clipping rect wrong?" with that kind of change :)

Re: API design: Should the clipping rect be reset on flip?

Reply #2 –
I'm on the fence with this.

It depends how low level of an API you want. A lower level API can do more, but takes more maintenance and diligence to use. Then again, you can make methods that make it easier to use.

@FJ: I agree with you too, but remember, someone can recreate that ability in a common JS script for newer coders. Like a set of methods that are easier to use.

Code: (javascript) [Select]

// hypothetically, rough code:
var fs = FlipScreen;
FlipScreen = function() {
    if (g_has_clip) {
        screen.clip();
    }
    fs();
};
If you use code to help you code you can use less code to code. Also, I have approximate knowledge of many things.

Sphere-sfml here
Sphere Studio editor here

Re: API design: Should the clipping rect be reset on flip?

Reply #3 –
The main reason I was thinking of doing this is that, in general, the entire screen needs to be re-rendered every frame anyway.  minisphere actually explicitly clears the backbuffer after a flip (since the contents are undefined after a flip, this is the most sane thing to do).  So unless you're doing letterboxing or something, there's very little reason for clipping parameters to persist between flips.  It feels like it would be more friendly to users to simply reset it on flip, rather than forcing users to save/restore it themselves.

I do see where FJ is coming from though, so it's a tough call.

Re: API design: Should the clipping rect be reset on flip?

Reply #4 –
I've always found it interesting how SetClippingRect was persistent but FlipScreen wasn't, even after I learned about the paradigm of screen buffering and flipping. I'm also on the fence about changing the expected persistence behavior.
 

Re: API design: Should the clipping rect be reset on flip?

Reply #5 –
There's really no way to make FlipScreen persistent in a portable way.  In a lot of cases a flip is just that: The front and backbuffers are swapped.  So there's no guarantee the contents of the backbuffer are even preserved.  minisphere solves this nicely by providing a DoEvents() function.  If you want to go into a loop that doesn't render anything without disturbing the contents of the screen, you can call DoEvents in lieu of FlipScreen to keep the engine from locking up.

As for changing expected behavior: To be clear, we're not talking about a "change" per se.  I've decided that the old 1.x functions will continue to be provided in minisphere 4.0 with their existing behaviors intact.  The Sphere 2.0 stuff is completely orthogonal to that.  Essentially, we get to design the API from the ground up without worrying about "expected" behavior, because the compatibility angle is already covered by leaving the old functions in.