deprecate ofBackground or refactor to mean ofClear

[kylemcdonald]

this suggestion comes from a discussion with @ofzach last week.

right now we have a few functions for working with the background in OF:

1. ofClear(): clears the background color right away
2. ofBackground(): clears the background color right away, and saves the background color
3. ofSetBackgroundColorAuto(): enables or disables whether the saved background color is used to clear the screen at the beginning of each frame
4. ofSetBackgroundColor(): changes the saved background color without clearing the screen

having so many functions creates confusion. the only reason that anything besides ofClear() exists is because processing sets an example of putting the background() call in setup() as if it is a property of the document rather than an action.

i suggest we only use ofClear(). alternatively, we can change the name of ofClear() to ofBackground() and note in the changelog that it doesn't work in setup() anymore.

[tgfrerer]

+0.75 for keeping ofClear() and getting rid of all ofBackground* related items :

• Getting rid of all the ofBackground logic would make it easier to maintain the renderers in the long run, and less error prone.
• Also, ofClear does what it does, is an action verb and would feels more natural in terms of semantics.
• Having only one point of entry will also make it easier to keep track on the GL / renderers side of things.

If i remember correctly, the screen buffer is cleared automatically to the window default color, and opaque alpha, while a frame buffer (FBO) is accumulating (not cleared) by default.

So, if we had an example that goes like this:

void ofApp::draw(){
    ofColor backgroundColor = ofColor(ofColor::darkgray);
    ofClear(backgroundColor);
    // ... things are drawn
}

The use of ofClear and how to set the background colour would be demonstrated in two lines.

---

-0.25 for getting rid of ofBackgound* :

• If we want to maintain the current auto-clear for the screen buffer, setting a background color for the screen buffer by clearing manually would mean the screen buffer gets cleared twice (once to oF-default, then to user-color) before anything gets drawn. glClear is one of the most expensive OpenGL functions, and using it more than needed feels like a waste.

---

I tend to think that people who mostly use the screen buffer tend to be new / or not too interested in OpenGL and performance and will appreciate anything that makes getting something drawn easy. And that therefore, anything screen buffer related should be written so that beginners feel welcome and can keep focus on their task.

But as soon as someone renders to an FBO, they have graduated to advanced level, and there, I think, from a framework perspective, the closer we stick to OpenGL standards and common graphics programming literature, the more will advanced users feel welcomed =).

[kylemcdonald]

with everything you mentioned in mind, then my recommendation is that we deprecate ofBackground* in favor of ofClear and completely remove ofBackground* with 1.0

[DomAmato]

Doesn't that seem verbose though and I am not sure clear makes sense to beginners who aren't familiar with the GL verbage. I lean more towards making things easier for beginners because advanced users will know workarounds or be more familiar with the codebase anyways.

Adhering to standards makes sense but a lot of standards are also written for people with some background knowledge of that code base. I work with elementary kids and they know what the background is, having to explain it is a non issue because it works within their lexicon. I just think people will pose more questions and that in the long run if people want optimization and are advanced users that they may be more likely to read documentation or know how to do so anyways.

[ofTheo]

I think its rare that you need to use ofClear ( unless your working with FBOs ) and most of the time people use ofBackground its just to set the background color of the window ( not so much to clear the screen ).

So I think switching most ofBackground calls in the examples to ofSetBackgroundColor will make a lot of sense for people learning OF.

I think there is only a few cases in the examples where the ofBackground needs to be switched to ofClear.

+1 for deprecation.