document ncpile_render(), ncpile_rasterize()

USAGE.md

@@ -166,6 +166,15 @@ Only upon a call to `notcurses_render` will the visible terminal display be
 updated to reflect the changes:
 
 ```c
+// Renders the pile of which 'n' is a part. Rendering this pile again will blow
+// away the render. To actually write out the render, call ncpile_rasterize().
+int ncpile_render(struct ncplane* n);
+
+// Make the physical screen match the last rendered frame from the pile of
+// which 'n' is a part. This is a blocking call. Don't call this before the
+// pile has been rendered (doing so will likely result in a blank screen).
+int ncpile_rasterize(struct ncplane* n);
+
 // Make the physical screen match the virtual screen. Changes made to the
 // virtual screen (i.e. most other calls) will not be visible until after a
 // successful call to notcurses_render().

cffi/src/notcurses/build_notcurses.py

@@ -53,6 +53,8 @@ void notcurses_version_components(int* major, int* minor, int* patch, int* tweak
 int notcurses_lex_margins(const char* op, notcurses_options* opts);
 int notcurses_stop(struct notcurses*);
 int notcurses_render(struct notcurses* nc);
+int ncpile_render(struct ncplane* n);
+int ncpile_rasterize(struct ncplane* n);
 int notcurses_render_to_buffer(struct notcurses* nc, char** buf, size_t* buflen);
 int notcurses_render_to_file(struct notcurses* nc, FILE* fp);
 struct ncplane* notcurses_stdplane(struct notcurses*);

doc/man/man3/notcurses_render.3.md

@@ -10,6 +10,10 @@ notcurses_render - sync the physical display to the virtual ncplanes
 
 **#include <notcurses/notcurses.h>**
 
+**int ncpile_render(struct ncplane* n);**
+
+**int ncpile_rasterize(struct ncplane* n);**
+
 **int notcurses_render(struct notcurses* ***nc***);**
 
 **char* notcurses_at_yx(struct notcurses* ***nc***, int ***yoff***, int ***xoff***, uint16_t* ***styles***, uint64_t* ***channels***);**
@@ -20,12 +24,28 @@ notcurses_render - sync the physical display to the virtual ncplanes
 
 # DESCRIPTION
 
-**notcurses_render** syncs the physical display to the context's prepared
+Rendering reduces a pile of **ncplane**s to a single plane, proceeding from the
-ncplanes. It is necessary to call **notcurses_render** to generate any visible
+top to the bottom along a pile's z-axis. The result is a matrix of **cell**s
-output; the various notcurses_output(3) calls only draw to the virtual
+(see **notcurses_cell**). Rasterizing takes this matrix, together with the
-ncplanes. Most of the notcurses statistics are updated as a result of a
+current state of the visual area, and produces a stream of optimized control
-render (see notcurses_stats(3)), and screen geometry is refreshed (similarly to
+sequences and EGCs for the terminal. By writing this stream to the terminal,
-**notcurses_refresh**) *following* the render.
+the physical display is synced to some pile's planes.
+
+**ncpile_render** performs the first of these tasks for the pile of which **n**
+is a part. The output is maintained internally; calling **ncpile_render** again
+on the same pile will replace this state with a fresh render. Multiple piles
+can be concurrently rendered. **ncpile_rasterize** performs rasterization, and
+writes the result to the terminal. It is a blocking call, and only one
+rasterization operation may proceed at a time. It does not destroy the
+render output, and can be called multiple times on the same render.
+**notcurses_render** calls **ncpile_render** and **ncpile_rasterize** on the
+standard plane, for backwards compatibility. It is an exclusive blocking call.
+
+It is necessary to call **ncpile_rasterize** or **notcurses_render** to
+generate any visible output; the various notcurses_output(3) calls only draw to
+the virtual ncplanes. Most of the notcurses statistics are updated as a result
+of a render (see **notcurses_stats(3)**), and screen geometry is refreshed
+(similarly to **notcurses_refresh(3)**) *following* the render.
 
 While **notcurses_render** is called, you **must not call any other functions
 modifying the same pile**. Other piles may be freely accessed and modified.