1notcurses_render(3) notcurses_render(3)
2
6 notcurses_render - sync the physical display to a virtual pile
7
9 #include <notcurses/notcurses.h>
10 int ncpile_render(struct ncplane* n);
12 int ncpile_rasterize(struct ncplane* n);
14 int notcurses_render(struct notcurses* nc);
16 char* notcurses_at_yx(struct notcurses* nc, int yoff, int xoff,
18 uint16_t* styles, uint64_t* channels);
19 int ncpile_render_to_file(struct ncplane* p, FILE* fp);
21 int ncpile_render_to_buffer(struct ncplane* p, char** buf, size_t* bu‐
23 flen);
24
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 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.
40 notcurses_render calls ncpile_render and ncpile_rasterize on the stan‐
41 dard plane, for backwards compatibility. It is an exclusive blocking
42 call.
43 It is necessary to call ncpile_rasterize or notcurses_render to gener‐
45 ate any visible output; the various notcurses_output(3) calls only draw
46 to the virtual ncplanes. Most of the notcurses statistics are updated
47 as a result of a render (see notcurses_stats(3)), and screen geometry
48 is refreshed (similarly to notcurses_refresh(3)) following the render.
49 While notcurses_render is called, you must not call any other functions
51 modifying the same pile. Other piles may be freely accessed and modi‐
52 fied. The pile being rendered may be accessed, but not modified.
53 ncpile_render_to_buffer performs the render and raster processes of
55 ncpile_render and ncpile_rasterize, but does not write the resulting
56 buffer to the terminal. The user is responsible for writing the buffer
57 to the terminal in its entirety. If there is an error, subsequent
58 frames will be out of sync, and notcurses_refresh(3) must be called.
59 A render operation consists of two logical phases: generation of the
61 rendered scene, and blitting this scene to the terminal (these two
62 phases might actually be interleaved, streaming the output as it is
63 rendered). Frame generation requires determining an extended grapheme
64 cluster, foreground color, background color, and style for each cell of
65 the physical terminal. Writing the scene requires synthesizing a set
66 of UTF-8-encoded characters and escape codes appropriate for the termi‐
67 nal (relying on terminfo(5)), and writing this sequence to the output
68 FILE. If the renderfp value was not NULL in the original call to
69 notcurses_init, the frame will be written to that FILE as well. This
70 write does not affect statistics.
71 Each cell can be rendered in isolation, though synthesis of the stream
73 carries dependencies between cells.
74 Cell rendering algorithm
76 Recall that there is a total ordering on the N ncplanes, and that the
77 standard plane always exists, with geometry equal to the physical
78 screen. Each cell of the physical screen is thus intersected by some
79 totally ordered subset of planes P0, P1...Pi, where 0 < i ≤ N. At each
80 cell, rendering starts at the topmost intersecting plane P0. The algo‐
81 rithm descends until either:
82 • it has locked in an extended grapheme cluster, and fore/background
84 colors, or
85 • all i planes have been examined
87 At each plane P, we consider a cell C. This cell is the intersecting
89 cell, unless that cell has no EGC. In that case, C is the plane's de‐
90 fault cell.
91 • If we have not yet determined an EGC, and C has a non-zero EGC, use
93 the EGC and style of C.
94 • If we have not yet locked in a foreground color, and C is not fore‐
96 ground-transparent, use the foreground color of C (see BUGS below).
97 If C is NCALPHA_OPAQUE, lock the color in.
98 • If we have not yet locked in a background color, and C is not back‐
100 ground-transparent, use the background color of C (see BUGS below).
101 If C is NCALPHA_OPAQUE, lock the color in.
102 If the algorithm concludes without an EGC, the cell is rendered with no
104 glyph and a default background. If the algorithm concludes without a
105 color locked in, the color as computed thus far is used.
106 notcurses_at_yx retrieves a cell as rendered. The EGC in that cell is
108 copied and returned; it must be free(3)d by the caller. If the cell is
109 a secondary column of a wide glyph, the glyph is still returned.
110
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 notcurses_at_yx returns a heap-allocated copy of the cell's EGC on suc‐
117 cess, and NULL on failure.
118
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
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
131 nick black <nickblack@linux.com>.
132 v2.4.9 notcurses_render(3)