1notcurses_render(3)                                        notcurses_render(3)
2
3
4

NAME

6       notcurses_render - sync the physical display to a virtual pile
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11       int ncpile_render(struct ncplane* n);
12
13       int ncpile_rasterize(struct ncplane* n);
14
15       int notcurses_render(struct notcurses* nc);
16
17       char*   notcurses_at_yx(struct  notcurses*  nc,  int  yoff,  int  xoff,
18       uint16_t* styles, uint64_t* channels);
19
20       int notcurses_render_to_file(struct notcurses* nc, FILE* fp);
21
22       int  notcurses_render_to_buffer(struct  notcurses*  nc,   char**   buf,
23       size_t* buflen);
24

DESCRIPTION

26       Rendering reduces a pile of ncplanes to a single plane, proceeding from
27       the top to the bottom along a pile's z-axis.  The result is a matrix of
28       nccells  (see notcurses_cell).  Rasterizing takes this matrix, together
29       with the current state of the visual area, and produces a stream of op‐
30       timized  control  sequences and EGCs for the terminal.  By writing this
31       stream to the terminal, the physical display is synced to  some  pile's
32       planes.
33
34       ncpile_render performs the first of these tasks for the pile of which n
35       is a part.  The output is maintained internally; calling  ncpile_render
36       again  on  the  same  pile will replace this state with a fresh render.
37       Multiple piles can be concurrently rendered.  ncpile_rasterize performs
38       rasterization, and writes the result to the terminal.  It is a blocking
39       call, and only one rasterization operation may proceed at a  time.   It
40       does not destroy the render output, and can be called multiple times on
41       the same render.  notcurses_render calls ncpile_render and  ncpile_ras‐
42       terize  on  the  standard plane, for backwards compatibility.  It is an
43       exclusive blocking call.
44
45       It is necessary to call ncpile_rasterize or notcurses_render to  gener‐
46       ate any visible output; the various notcurses_output(3) calls only draw
47       to the virtual ncplanes.  Most of the notcurses statistics are  updated
48       as  a  result of a render (see notcurses_stats(3)), and screen geometry
49       is refreshed (similarly to notcurses_refresh(3)) following the render.
50
51       While notcurses_render is called, you must not call any other functions
52       modifying  the same pile.  Other piles may be freely accessed and modi‐
53       fied.  The pile being rendered may be accessed, but not modified.
54
55       notcurses_render_to_buffer performs the render and raster processes  of
56       notcurses_render, but does not write the resulting buffer to the termi‐
57       nal.  The user is responsible for writing the buffer to the terminal in
58       its  entirety.   If there is an error, subsequent frames will be out of
59       sync, and notcurses_refresh(3) must be called.
60
61       A render operation consists of two logical phases:  generation  of  the
62       rendered  scene,  and  blitting  this  scene to the terminal (these two
63       phases might actually be interleaved, streaming the  output  as  it  is
64       rendered).   Frame generation requires determining an extended grapheme
65       cluster, foreground color, background color, and style for each cell of
66       the  physical  terminal.  Writing the scene requires synthesizing a set
67       of UTF-8-encoded characters and escape codes appropriate for the termi‐
68       nal  (relying  on terminfo(5)), and writing this sequence to the output
69       FILE.  If the renderfp value was not  NULL  in  the  original  call  to
70       notcurses_init,  the  frame will be written to that FILE as well.  This
71       write does not affect statistics.
72
73       Each cell can be rendered in isolation, though synthesis of the  stream
74       carries dependencies between cells.
75
76   Cell rendering algorithm
77       Recall  that  there is a total ordering on the N ncplanes, and that the
78       standard plane always exists,  with  geometry  equal  to  the  physical
79       screen.   Each  cell of the physical screen is thus intersected by some
80       totally ordered subset of planes P0, P1...Pi, where 0 < i N.  At each
81       cell, rendering starts at the topmost intersecting plane P0.  The algo‐
82       rithm descends until either:
83
84       • it has locked in an extended grapheme  cluster,  and  fore/background
85         colors, or
86
87       • all i planes have been examined
88
89       At  each  plane P, we consider a cell C.  This cell is the intersecting
90       cell, unless that cell has no EGC.  In that case, C is the plane's  de‐
91       fault cell.
92
93       • If  we  have not yet determined an EGC, and C has a non-zero EGC, use
94         the EGC and style of C.
95
96       • If we have not yet locked in a foreground color, and C is  not  fore‐
97         ground-transparent,  use  the foreground color of C (see BUGS below).
98         If C is CELL_ALPHA_OPAQUE, lock the color in.
99
100       • If we have not yet locked in a background color, and C is  not  back‐
101         ground-transparent,  use  the background color of C (see BUGS below).
102         If C is CELL_ALPHA_OPAQUE, lock the color in.
103
104       If the algorithm concludes without an EGC, the cell is rendered with no
105       glyph  and  a default background.  If the algorithm concludes without a
106       color locked in, the color as computed thus far is used.
107
108       notcurses_at_yx retrieves a call as rendered.  The EGC in that cell  is
109       copied and returned; it must be free(3)d by the caller.
110

RETURN VALUES

112       On  success,  0 is returned.  On failure, a non-zero value is returned.
113       A success will result in the renders stat  being  increased  by  1.   A
114       failure will result in the failed_renders stat being increased by 1.
115
116       notcurses_at_yx returns a heap-allocated copy of the cell's EGC on suc‐
117       cess, and NULL on failure.
118

BUGS

120       In addition to the RGB colors, it is possible to use the "default fore‐
121       ground  color" and "default background color" inherited from the termi‐
122       nal.  Since notcurses doesn't know what these colors are, they are  not
123       considered for purposes of color blending.
124

SEE ALSO

126       notcurses(3),   notcurses_cell(3),  notcurses_input(3),  notcurses_out‐
127       put(3), notcurses_plane(3),  notcurses_refresh(3),  notcurses_stats(3),
128       notcurses_visual(3), console_codes(4), utf-8(7)
129

AUTHORS

131       nick black <nickblack@linux.com>.
132
133
134
135                                    v2.3.1                 notcurses_render(3)
Impressum