notcurses_render - sync the physical display to a virtual pile

       nick black <nickblack@linux.com>.

                                                     v3.0.7                                  notcurses_render(3)

       In addition to the RGB colors, it is possible to use the "default foreground color"  and  "default  back‐
       ground  color" inherited from the terminal.  Since notcurses doesn't know what these colors are, they are
       not considered for purposes of color blending.

       Rendering reduces a pile of ncplanes to a single plane, proceeding from the top to  the  bottom  along  a
       pile's  z-axis.   The result is a matrix of nccells (see notcurses_cell).  Rasterizing takes this matrix,
       together with the current state of the visual area, and produces a stream of optimized control  sequences
       and  EGCs  for  the  terminal.  By writing this stream to the terminal, 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  main‐
       tained internally; calling ncpile_render again on the same pile will replace this state with a fresh ren‐
       der.   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.  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 updat‐
       ed 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 mustnotcallanyotherfunctionsmodifyingthesamepile.  Other
       piles may be freely accessed and modified.  The pile being rendered may be accessed, but not modified.

       ncpile_render_to_buffer performs the render and raster processes of ncpile_render  and  ncpile_rasterize,
       but  does not write the resulting buffer to the terminal.  The user is responsible for writing the buffer
       to the terminal in its entirety.  If there is an error, subsequent  frames  will  be  out  of  sync,  and
       notcurses_refresh(3) must be called.

       A  render  operation  consists of two logical phases: generation of the rendered scene, and blitting this
       scene to the terminal (these two phases might actually be interleaved, streaming the output as it is ren‐
       dered).  Frame generation requires determining an extended grapheme cluster, foreground color, background
       color, and style for each cell of the physical terminal.  Writing the scene requires synthesizing  a  set
       of  UTF-8-encoded  characters and escape codes appropriate for the terminal (relying on terminfo(5)), and
       writing this sequence to the output FILE.

       Each cell can be rendered in isolation, though synthesis  of  the  stream  carries  dependencies  between
       cells.

   Cellrenderingalgorithm
       Recall  that there is a total ordering on the N ncplanes, and that the standard plane always exists, with
       geometry equal to the physical screen.  Each cell of the physical screen is thus intersected by some  to‐
       tally  ordered subset of planes P0, P1...Pi, where 0 < i ≤ N.  At each cell, rendering starts at the top‐
       most intersecting plane P0.  The algorithm descends until either:

       • it has locked in an extended grapheme cluster, and fore/background colors, or

       • all i planes have been examined

       At each plane P, we consider a cell C.  This cell is the intersecting cell, unless that cell has no  EGC.
       In that case, C is the plane's default cell.

       • If we have not yet determined an EGC, and C has a non-zero EGC, use the EGC and style of C.

       • If  we  have  not  yet locked in a foreground color, and C is not foreground-transparent, use the fore‐
         ground color of C (see BUGS below).  If C is NCALPHA_OPAQUE, lock the color in.

       • If we have not yet locked in a background color, and C is not  background-transparent,  use  the  back‐
         ground color of C (see BUGS below).  If C is NCALPHA_OPAQUE, lock the color in.

       If  the  algorithm concludes without an EGC, the cell is rendered with no glyph and a default background.
       If the algorithm concludes without a color locked in, the color as computed thus far is used.

       notcurses_at_yx retrieves a cell asrendered.  The EGC in that cell is copied and returned;  it  must  be
       free(3)d by the caller.  If the cell is a secondary column of a wide glyph, the glyph is still returned.

       notcurses_render - sync the physical display to a virtual pile

       On  success, 0 is returned.  On failure, a non-zero value is returned.  A success will result in the ren‐ders stat being increased by 1.  A failure will result in the failed_renders stat being increased by 1.

       notcurses_at_yx returns a heap-allocated copy of the cell's EGC on success, and NULL on failure.

notcurses(3), notcurses_cell(3), notcurses_input(3),  notcurses_output(3),  notcurses_plane(3),  notcurs‐es_refresh(3), notcurses_stats(3), notcurses_visual(3), console_codes(4), utf-8(7)

#include<notcurses/notcurses.h>intncpile_render(structncplane*n);intncpile_rasterize(structncplane*n);intnotcurses_render(structnotcurses*nc);char*notcurses_at_yx(structnotcurses*nc,unsignedyoff,unsignedxoff,uint16_t*styles,uint64_t*channels);intncpile_render_to_file(structncplane*p,FILE*fp);intncpile_render_to_buffer(structncplane*p,char**buf,size_t*buflen);