Re: NcPile vs NcPlane

[Nick Black]

igo9...@yandex.ru left as an exercise for the reader:
> I am working on porting NcPlane to Python. I have noticed there is a new
> type called NcPile.
>
> Would it be correct to implement it as a subtype of NcPlane? Is calling
> `ncpile_render` on a regular NcPlane an error?

(sorry for the latent reply. i've cc'd the notcurses list,
because this seems good general information)

That would definitely be an error. Quoting the "notcurses(3)"
man page:

Ncpiles
A given notcurses context is made up of one or more piles. Piles pro‐
vide distinct rendering contexts: a thread can be rendering or mutat‐
ing one pile, while another thread concurrently renders or mutates an‐
other pile. A pile is made up of planes, totally ordered on a z-axis.
In addition to the z-ordering, the planes of a pile are bound in a
forest (a set of directed, acyclic graphs). Those planes which are
not bound to some other plane constitute the root planes of a pile. A
pile is destroyed when all its planes are destroyed, or moved to other
piles. Since the standard plane (see below) always exists, and cannot
be moved to another pile, one pile always exists, known as the stan‐
dard pile.

Ncplanes
Following initialization, a single ncplane exists, the "standard
plane" (see notcurses_stdplane(3)). This plane cannot be destroyed
nor manually resized, and is always exactly as large as the screen (if
run without a TTY, the "screen" is assumed to be 80x24 cells). Fur‐
ther ncplanes can be created with ncplane_new(3). A total z-ordering
always exists on the set of ncplanes, and new ncplanes are placed at
the top of the z-buffer. Ncplanes can be larger, smaller, or the same
size as the physical screen, and can be placed anywhere relative to it
(including entirely off-screen). Ncplanes are made up of nccells (see
NcCells below). Information on ncplanes is available at notcurs‐
es_plane(3).

https://nick-black.com/dankwiki/images/1/15/Notcurses-Model.png
might be helpful. To explain further:

- there is always at least one plane, the standard plane (see
notcurses_stdplane(3))
- each plane is part of a pile
- there is thus always at least one pile (the pile containing
the standard plane)
- piles generally aren't explicitly manipulated by the user;
they come into being implicitly (when a plane is reparented
to NULL), and are destroyed implicitly (when the last plane
of a pile is destroyed, or reparented into another pile). i'm
not even sure that the ncpile type is exposed to the user
(you render a pile by calling ncpile_render() on any of its
planes).
- the entire point of piles is to facilitate multithreaded
work. it is prohibited to modify any plane within a pile
being rendered. when there was only one pile (i.e. before
piles existed), this meant you couldn't modify anything
during a render. with multiple piles, you can work on one,
render it, and while that render is going on, work on another
pile (which can then be rendered).

so no, piles are definitely not subclasses of planes, but rather
collections of planes. with that said, users generally ought not
be manipulating piles explicitly, and i do not believe there is
any public call which takes an ncpile as an argument, so i'd be
inclined to say that your wrappers ought not be exposing the
concept at all (at least not in the API proper).

does that answer your question? don't hesitate to request more
information if not. thanks for your hard work!

--
nick black -=- https://www.nick-black.com
to make an apple pie from scratch,
you need first invent a universe.