1notcurses_plane(3) notcurses_plane(3)
2
6 notcurses_plane - operations on ncplanes
7
9 #include <notcurses/notcurses.h>
10 #define NCPLANE_OPTION_HORALIGNED 0x0001ull
12 typedef struct ncplane_options {
14 int y; // vertical placement relative to parent plane
15 int x; // horizontal placement relative to parent plane
16 int rows; // number of rows, must be positive
17 int cols; // number of columns, must be positive
18 void* userptr; // user curry, may be NULL
19 const char* name; // name (used only for debugging), may be NULL
20 int (*resizecb)(struct ncplane*); // called on parent resize
21 uint64_t flags; // closure over NCPLANE_OPTION_*
22 } ncplane_options;
23 struct ncplane* ncplane_create(struct ncplane* n, const ncplane_op‐
25 tions* nopts);
26 struct ncplane* ncpile_create(struct notcurses* n, const ncplane_op‐
28 tions* nopts);
29 struct ncplane* notcurses_top(struct notcurses* n);
31 struct ncplane* notcurses_bottom(struct notcurses* n);
33 struct ncplane* ncpile_top(struct ncplane* n);
35 struct ncplane* ncpile_bottom(struct ncplane* n);
37 struct ncplane* ncplane_reparent(struct ncplane* n, struct ncplane*
39 newparent);
40 struct ncplane* ncplane_reparent_family(struct ncplane* n, struct nc‐
42 plane* newparent);
43 int ncplane_descendant_p(const struct ncplane* n, const struct ncplane*
45 ancestor);
46 int ncplane_resize_realign(struct ncplane* n);
48 void ncplane_set_resizecb(struct ncplane* n, int(resizecb)(struct nc‐
50 plane));
51 int (ncplane_resizecb(const struct ncplane n**))(struct ncplane*);**
53 struct ncplane* ncplane_dup(struct ncplane* n, void* opaque);
55 int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keeple‐
57 ny, int keeplenx, int yoff, int xoff, int ylen, int xlen);
58 int ncplane_move_yx(struct ncplane* n, int y, int x);
60 void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict
62 x);
63 int ncplane_y(const struct ncplane* n);
65 int ncplane_x(const struct ncplane* n);
67 void ncplane_abs_yx(const struct ncplane* n, int* y, int* x);
69 int ncplane_abs_y(const struct ncplane* n);
71 int ncplane_abs_x(const struct ncplane* n);
73 struct ncplane* ncplane_parent(struct ncplane* n);
75 const struct ncplane* ncplane_parent_const(const struct ncplane* n);
77 int ncplane_set_base_cell(struct ncplane* ncp, const nccell* c);
79 int ncplane_set_base(struct ncplane* ncp, const char* egc, uint32_t
81 stylemask, uint64_t channels);
82 int ncplane_base(struct ncplane* ncp, nccell* c);
84 int ncplane_move_top(struct ncplane* n);
86 int ncplane_move_bottom(struct ncplane* n);
88 int ncplane_move_above(struct ncplane* restrict n, struct ncplane* re‐
90 strict above);
91 int ncplane_move_below(struct ncplane* restrict n, struct ncplane* re‐
93 strict below);
94 struct ncplane* ncplane_below(struct ncplane* n);
96 struct ncplane* ncplane_above(struct ncplane* n);
98 char* ncplane_at_cursor(struct ncplane* n, uint16_t* stylemask,
100 uint64_t* channels);
101 int ncplane_at_cursor_cell(struct ncplane* n, nccell* c);
103 char* ncplane_at_yx(const struct ncplane* n, int y, int x, uint16_t*
105 stylemask, uint64_t* channels);
106 int ncplane_at_yx_cell(struct ncplane* n, int y, int x, nccell* c);
108 uint32_t* ncplane_rgba(const struct ncplane* nc, int begy, int begx,
110 int leny, int lenx);
111 char* ncplane_contents(const struct ncplane* nc, int begy, int begx,
113 int leny, int lenx);
114 void* ncplane_set_userptr(struct ncplane* n, void* opaque);
116 void* ncplane_userptr(struct ncplane* n);
118 void ncplane_dim_yx(const struct ncplane* n, int* restrict rows, int*
120 restrict cols);
121 static inline int ncplane_dim_y(const struct ncplane* n);
123 static inline int ncplane_dim_x(const struct ncplane* n);
125 void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int*
127 restrict x);
128 void ncplane_translate(const struct ncplane* src, const struct ncplane*
130 dst, int* restrict y, int* restrict x);
131 bool ncplane_translate_abs(const struct ncplane* n, int* restrict y,
133 int* restrict x);
134 uint64_t ncplane_channels(const struct ncplane* n);
136 void ncplane_set_channels(struct ncplane* nc, uint64_t channels);
138 static inline unsigned ncplane_bchannel(struct ncplane* nc);
140 static inline unsigned ncplane_fchannel(struct ncplane* nc);
142 static inline unsigned ncplane_fg_rgb8(struct ncplane* nc);
144 static inline unsigned ncplane_bg_rgb8(struct ncplane* nc);
146 static inline unsigned ncplane_fg_alpha(struct ncplane* nc);
148 static inline unsigned ncplane_bg_alpha(struct ncplane* nc);
150 static inline unsigned ncplane_fg_rgb8(struct ncplane* n, unsigned* r,
152 unsigned* g, unsigned* b);
153 static inline unsigned ncplane_bg_rgb8(struct ncplane* n, unsigned* r,
155 unsigned* g, unsigned* b);
156 int ncplane_set_fg_rgb8(struct ncplane* n, int r, int g, int b);
158 int ncplane_set_bg_rgb8(struct ncplane* n, int r, int g, int b);
160 void ncplane_set_fg_rgb8_clipped(struct ncplane* n, int r, int g, int
162 b);
163 void ncplane_set_bg_rgb8_clipped(struct ncplane* n, int r, int g, int
165 b);
166 int ncplane_set_fg_rgb8(struct ncplane* n, uint32_t channel);
168 int ncplane_set_bg_rgb8(struct ncplane* n, uint32_t channel);
170 void ncplane_set_fg_default(struct ncplane* n);
172 void ncplane_set_bg_default(struct ncplane* n);
174 int ncplane_set_fg_alpha(struct ncplane* n, unsigned alpha);
176 int ncplane_set_bg_alpha(struct ncplane* n, unsigned alpha);
178 int ncplane_set_fg_palindex(struct ncplane* n, int idx);
180 int ncplane_set_bg_palindex(struct ncplane* n, int idx);
182 uint16_t ncplane_styles(const struct ncplane* n);
184 void ncplane_set_styles(struct ncplane* n, unsigned stylebits);
186 void ncplane_on_styles(struct ncplane* n, unsigned stylebits);
188 void ncplane_off_styles(struct ncplane* n, unsigned stylebits);
190 void ncplane_greyscale(struct ncplane* n);
192 int ncplane_blit_bgrx(struct ncplane* nc, int placey, int placex, int
194 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
195 begx, int leny, int lenx);
196 int ncplane_blit_rgba(struct ncplane* nc, int placey, int placex, int
198 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
199 begx, int leny, int lenx);
200 int ncplane_destroy(struct ncplane* ncp);
202 void notcurses_drop_planes(struct notcurses* nc);
204 int ncplane_mergedown(const struct ncplane* src, struct ncplane* dst,
206 int begsrcy, int begsrcx, int leny, int lenx, int dsty, int dstx);
207 int ncplane_mergedown_simple(const struct ncplane* restrict src, struct
209 ncplane* restrict dst);
210 void ncplane_erase(struct ncplane* n);
212 bool ncplane_set_scrolling(struct ncplane* n, bool scrollp);
214 int ncplane_rotate_cw(struct ncplane* n);
216 int ncplane_rotate_ccw(struct ncplane* n);
218 DESCRIPTION
220 Ncplanes are the fundamental drawing object of notcurses. All output
221 functions take a struct ncplane as an argument. They can be any size,
222 and placed anywhere. In addition to its framebuffer--a rectilinear ma‐
223 trix of nccells (see notcurses_cell(3))--an ncplane is defined by:
224 · a base nccell, used for any cell on the plane without a glyph,
226 · the egcpool backing its nccells,
228 · a current cursor location,
230 · a current style, foreground channel, and background channel,
232 · its geometry,
234 · a configured user pointer,
236 · position relative to the standard plane,
238 · the plane, if any, to which it is bound,
240 · the next plane bound by the plane to which it is bound,
242 · the head of the list of its bound planes,
244 · its z-index, and
246 · a name (used only for debugging).
248 New planes can be created with ncplane_create. If a plane is bound to
250 another, x and y coordinates are relative to the plane to which it is
251 bound, and if this latter plane moves, all its bound planes move along
252 with it. When a plane is destroyed, all planes bound to it (directly
253 or transitively) are destroyed.
254 ncplane_reparent detaches the plane n from any plane to which it is
256 bound, and binds it to newparent. Its children are reparented to its
257 previous parent. The standard plane cannot be reparented. If newpar‐
258 ent is NULL, the plane becomes the root plane of a new, unrendered
259 stack. When ncplane_reparent_family is used, all planes bound to n
260 move along with it during a reparenting operation. See Piles below.
261 ncplane_destroy destroys a particular ncplane, after which it must not
263 be used again. notcurses_drop_planes destroys all ncplanes other than
264 the stdplane. Any references to such planes are, of course, invalidat‐
265 ed. It is undefined to destroy a plane concurrently with any other op‐
266 eration involving that plane, or any operation involving the z-axis.
267 It is an error for two threads to concurrently mutate a single ncplane.
269 So long as rendering is not taking place, however, multiple threads may
270 safely output to multiple ncplanes. So long as all threads are read‐
271 ers, multiple threads may work with a single ncplane. A reading func‐
272 tion is any which accepts a const struct ncplane.
273 ncplane_yx returns the coordinates of the specified plane's origin,
275 relative to the plane to which it is bound. Either or both of y and x
276 may be NULL. ncplane_y and ncplane_x allow a single component of this
277 location to be retrieved. ncplane_abs_yx returns the coordinates of
278 the specified plane's origin relative to its pile.
279 ncplane_translate translates coordinates expressed relative to the
281 plane src, and writes the coordinates of that cell relative to dst.
282 The cell need not intersect with dst, though this will yield coordi‐
283 nates which are invalid for writing or reading on dst. If dst is NULL,
284 it is taken to refer to the standard plane. ncplane_translate_abs
285 takes coordinates expressed relative to the standard plane, and returns
286 coordinates relative to dst, returning false if the coordinates are in‐
287 valid for dst.
288 ncplane_mergedown writes to dst the frame that would be rendered if on‐
290 ly src and dst existed on the z-axis, ad dst represented the entirety
291 of the rendering region. Only those cells where src intersects with
292 dst might see changes. It is an error to merge a plane onto itself.
293 ncplane_erase zeroes out every cell of the plane, dumps the egcpool,
295 and homes the cursor. The base cell is preserved, as are the active
296 attributes.
297 When a plane is resized (whether by ncplane_resize, SIGWINCH, or any
299 other mechanism), a depth-first recursion is performed on its children.
300 Each child plane having a non-NULL resizecb will see that callback in‐
301 voked following resizing of its parent's plane. If it returns non-ze‐
302 ro, the resizing cascade terminates, returning non-zero. Otherwise,
303 resizing proceeds recursively.
304 Base cells
306 Each plane has a base cell, initialized to all zeroes. When rendering,
307 the cells of the plane are examined in turn. Each cell has three inde‐
308 pendent rendering elements--its EGC, its foreground channel, and its
309 background channel. Any default channel is replaced with the corre‐
310 sponding channel from that plane's base cell. ncplane_erase has no ef‐
311 fect on the base cell. Calling ncplane_erase on a plane whose base
312 cell is a purple 'A' results (for rendering purposes) in a plane made
313 up entirely of purple 'A's.
314 ncplane_set_base_cell uses the nccell c (which must be bound to the nc‐
316 plane ncp, and must be the first nccell of a multicolumn sequence) to
317 set the base cell. ncplane_set_base does the same with egc, stylemask,
318 and channels.
319 Piles
321 A single notcurses context is made up of one or more piles. A pile is
322 a set of one or more ncplanes, including the partial orderings made up
323 of their binding and z-axis pointers. A pile has a top and bottom nc‐
324 plane (this might be a single plane), and one or more root planes
325 (planes which are bound to themselves). Multiple threads can concur‐
326 rently operate on distinct piles, even changing one while rendering an‐
327 other.
328 Each plane is part of one and only one pile. By default, a plane is
330 part of the same pile containing that plane to which it is bound. If
331 ncpile_create is used in the place of ncplane_create, the returned
332 plane becomes the root plane, top, and bottom of a new pile. As a root
333 plane, it is bound to itself. A new pile can also be created by repar‐
334 enting a plane to itself, though if the plane is already a root plane,
335 this is a no-op.
336 When a plane is moved to a different pile (whether new or preexisting),
338 any planes which were bound to it are rebound to its previous parent.
339 If the plane was a root plane of some pile, any bound planes become
340 root planes. The new plane is placed immediately atop its new parent
341 on its new pile's z-axis. When ncplane_reparent_family() is used, all
342 planes bound to the reparented plane are moved along with it. Their
343 relative z-order is maintained.
344 Scrolling
346 All planes, including the standard plane, are created with scrolling
347 disabled. Control scrolling on a per-plane basis with nc‐
348 plane_set_scrolling. Attempting to print past the end of a line will
349 stop at the plane boundary, and indicate an error. On a plane 10 col‐
350 umns wide and two rows high, printing "0123456789" at the origin should
351 succeed, but printing "01234567890" will by default fail at the
352 eleventh character. In either case, the cursor will be left at loca‐
353 tion 0x10; it must be moved before further printing can take place. If
354 scrolling is enabled, the first row will be filled with 01234546789,
355 the second row will have 0 written to its first column, and the cursor
356 will end up at 1x1. Note that it is still an error to manually attempt
357 to move the cursor off-plane, or to specify off-plane output. Boxes do
358 not scroll; attempting to draw a 2x11 box on our 2x10 plane will result
359 in an error and no output. When scrolling is enabled, and output takes
360 place while the cursor is past the end of the last row, the first row
361 is discarded, all other rows are moved up, the last row is cleared, and
362 output begins at the beginning of the last row. This does not take
363 place until output is generated (i.e. it is possible to fill a plane
364 when scrolling is enabled).
365
367 ncplane_create and ncplane_dup return a new struct ncplane on success,
368 or NULL on failure.
369 ncplane_userptr returns the configured user pointer for the ncplane,
371 and cannot fail.
372 ncplane_below returns the plane below the specified ncplane. If the
374 provided plane is the bottommost plane, NULL is returned. It cannot
375 fail.
376 ncplane_set_scrolling returns true if scrolling was previously enabled,
378 and false otherwise.
379 ncpile_top and ncpile_bottom return the topmost and bottommost planes,
381 respectively, of the pile containing their argument. notcurses_top and
382 notcurses_bottom do the same for the standard pile.
383 ncplane_at_yx and ncplane_at_cursor return a heap-allocated copy of the
385 EGC at the relevant cell, or NULL if the cell is invalid. The caller
386 should free this result. ncplane_at_yx_cell and ncplane_at_cursor_cell
387 instead load these values into an nccell, which is invalidated if the
388 associated plane is destroyed. The caller should release this nccell
389 with cell_release.
390 Functions returning int return 0 on success, and non-zero on error.
392 All other functions cannot fail (and return void).
394
396 ncplane_new is defined as a deprecated wrapper around ncplane_create.
397 It should not be used in new code.
398
400 notcurses(3), notcurses_cell(3), notcurses_output(3), notcurses_std‐
401 plane(3)
402
404 nick black <nickblack@linux.com>.
405 v2.2.3 notcurses_plane(3)