Skip to main content

News

Topic: API design: Should the clipping rect be reset on flip? (Read 1364 times) previous topic - next topic

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • miniSphere Developer
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?
miniSphere 5.0b4 (stable: 4.8.8) - Cell compiler - SSj debugger - thread | on GitHub
For the sake of our continued health I very much hope that Fat Cerberus does not become skilled enough at whatever arcane art it would require to cause computers to spawn enourmous man eating pigs ~Rhuan

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 :)

  • Radnen
  • [*][*][*][*][*]
  • Senior Staff
  • Wise Warrior
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

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • miniSphere Developer
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.
miniSphere 5.0b4 (stable: 4.8.8) - Cell compiler - SSj debugger - thread | on GitHub
For the sake of our continued health I very much hope that Fat Cerberus does not become skilled enough at whatever arcane art it would require to cause computers to spawn enourmous man eating pigs ~Rhuan

  • N E O
  • [*][*][*][*][*]
  • Administrator
  • Senior Administrator
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.

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • miniSphere Developer
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.
miniSphere 5.0b4 (stable: 4.8.8) - Cell compiler - SSj debugger - thread | on GitHub
For the sake of our continued health I very much hope that Fat Cerberus does not become skilled enough at whatever arcane art it would require to cause computers to spawn enourmous man eating pigs ~Rhuan