What is the equivalent of ncdirect_clear() in rendered mode without alt screen?

[joseluis]

ncplane_erase on the standard plane doesn't seem to do anything to clear the screen.

[dankamongmen]

i assume you mean with respect to preexisting content, right? anything you draw ought be cleared with an ncplane_erase() followed by a render. to clear preexisting content, i think a notcurses_refresh() at startup ought suffice. if it does, please consider adding an entry to the FAQ.

[dankamongmen]

let me explain why this is. as you probably know by now, rendered mode keeps a copy of the current screen contents. this copy starts off as all zeroes (it's not portably possible to acquire the preexisting content), and is built up over the course of rasterizations. rendering "solves" for the new desired screen. rasterization checks each cell, emitting only those cells which are different, and updates the copy.

so if you do an ncplane_erase() on the standard screen, it reduces to a solution of an erased screen. unfortunately, we believe ourselves to have an erased screen already, so this results in no writeout, and thus no update.

we could avoid this by somehow initializing the screen copy to "unknown". the problem with this is that we would always blow away every cell on the screen with the first render, and the whole point of not using the alternate screen (which always clears the screen) is to leave preexisting output unchanged, and leave our own output up when we're done. so doing so eliminates half of the reason why one would not use the alternate screen. think, for instance, of how this would work with CLI mode.

it kinda sucks, but that's the way it is. i spent an hour myself wondering why the hell i couldn't get my screen erased once, many months ago. i think this is a good FAQ entry.

[joseluis]

i assume you mean with respect to preexisting content, right?

yes

to clear preexisting content, i think a notcurses_refresh() at startup ought suffice.

It turns out notcurses_refresh() does not erase the preexisting content in any terminal... even when following it with notcurses render...

if it does, please consider adding an entry to the FAQ.

Ok I'll update the FAQ with the solution when there's one.

[joseluis]

The best solutions I can see that uses the current API are either:

• set the plane to scroll and call plane_putstr with a string made of as many spaces as cells in the plane, and then call ncplane_home.
• set the plane to scroll and call plane_putstr with a string made of as many newlines as the terminal rows * 2. So that it advances the scroll a full window height, not loosing any previous content. Then call ncplane_home.

[dankamongmen]

It turns out notcurses_refresh() does not erase the preexisting content in any terminal... even when following it with notcurses render...

that is very surprising, and a bug if true. let me go verify.

[dankamongmen]

as for why notcurses_refresh() works to solve the problem -- notcurses_refresh() is intended to be run when the screen is disrupted, and our knowledge is no longer accurate. for that reason, it disregards the screen copy (the "damage buffer"), and prints to every cell. though apparently it does not? checking now.