notcurses_ncplane(3) details

doc/man/man3/notcurses.3.ronn

@@ -39,15 +39,10 @@ for the actual terminal must be available.
 
 ### Output
 
-All output is performed on `struct ncplane*`s (see notcurses_ncplane(3)).
-Following initialization, a single ncplane exists, the "standard plane" (see
-notcurses_stdplane(3)). This plane cannot be destoyed nor manually resized,
-and is always exactly as large as the screen. Further 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. Information
-on drawing to ncplanes is available at notcurses_output(3).
-
-Output is not visible until explicitly rendered via notcurses_render(3).
+All output is performed on `struct ncplane*`s (see [Ncplanes][] below). Output
+is not visible until explicitly rendered via notcurses_render(3). It is safe to
+output from multiple threads. Information on drawing functions is available at
+notcurses_output(3).
 
 ### Input
 
@@ -58,6 +53,22 @@ are mapped into Unicode's
 [Supplementary Private Use Area-B](https://unicode.org/charts/PDF/U100000.pdf).
 Information on input is available at notcurses_input(3).
 
+### Ncplanes
+
+Following initialization, a single ncplane exists, the "standard plane" (see
+notcurses_stdplane(3)). This plane cannot be destoyed nor manually resized,
+and is always exactly as large as the screen. Further 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 cells (see [Cells][] below). Information on ncplanes is available at
+notcurses_ncplane(3).
+
+### Cells
+
+Information on cells is available at notcurses_cell(3).
+
 ### Destruction
 
 Before exiting, notcurses_stop(3) should be called. In addition to freeing up
@@ -73,6 +84,6 @@ Nick Black <nickblack@linux.com>
 
 ## SEE ALSO
 
-notcurses-demo(1), notcurses_init(3), notcurses_input(3),
-ncplane_new(3), notcurses_output(3), notcurses_render(3),
+notcurses-demo(1), notcurses_cell(3), notcurses_init(3), notcurses_input(3),
+notcurses_ncplane(3), ncplane_new(3), notcurses_output(3), notcurses_render(3),
 notcurses_stdplane(3), notcurses_stop(3), ncurses(3NCURSES), terminfo(5)

doc/man/man3/notcurses_ncplane.3.ronn

@@ -49,9 +49,35 @@ notcurses_ncplane(3) -- operations on notcurses planes
 
 ## DESCRIPTION
 
+Ncplanes are the fundamental drawing object of notcurses. All output functions
+take a `struct ncplane*` as an argument. They can be any size, and placed
+anywhere. In addition to its framebuffer--a rectilinear matrix of cells
+(see notcurses_cell(3))--an ncplane is defined by:
+
+* a base cell, used for any cell on the plane without a glyph,
+* the egcpool backing its cells,
+* a current cursor location,
+* a current style, foreground channel, and background channel,
+* its geometry,
+* a configured user pointer,
+* its position relative to the visible plane, and
+* its z-index.
 
 ## RETURN VALUES
 
+ncplane_new(3) and ncplane_aligned(3) both return a new `struct ncplane*`, or
+`NULL` on failure.
+
+ncplane_userptr(3) and ncplane_userptr_const(3) both return the configured user
+pointer for the ncplane. They cannot fail.
+
+ncplane_below(3) returns the plane below the specified ncplane. If the provided
+plane is the bottommost plane, NULL is returned. It cannot fail.
+
+Functions returning `int` return 0 on success, and non-zero on error.
+
+All other functions either cannot fail (and return `void`).
+
 ## AUTHOR
 
 Nick Black <nickblack@linux.com>