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 #define NCPLANE_OPTION_VERALIGNED 0x0002ull
13 #define NCPLANE_OPTION_MARGINALIZED 0x0004ull
14 #define NCPLANE_OPTION_FIXED 0x0008ull
15 typedef struct ncplane_options {
17 int y; // vertical placement relative to parent plane
18 int x; // horizontal placement relative to parent plane
19 int rows; // number of rows, must be positive
20 int cols; // number of columns, must be positive
21 void* userptr; // user curry, may be NULL
22 const char* name; // name (used only for debugging), may be NULL
23 int (*resizecb)(struct ncplane*); // called on parent resize
24 uint64_t flags; // closure over NCPLANE_OPTION_*
25 int margin_b, margin_r; // bottom and right margins
26 } ncplane_options;
27 #define NCSTYLE_ITALIC 0x0020u
29 #define NCSTYLE_UNDERLINE 0x0010u
30 #define NCSTYLE_UNDERCURL 0x0008u
31 #define NCSTYLE_BOLD 0x0004u
32 #define NCSTYLE_STRUCK 0x0002u
33 #define NCSTYLE_BLINK 0x0001u
34 #define NCSTYLE_NONE 0
35 struct ncplane* ncplane_create(struct ncplane* n, const ncplane_op‐
37 tions* nopts);
38 struct ncplane* ncpile_create(struct notcurses* n, const ncplane_op‐
40 tions* nopts);
41 struct ncplane* notcurses_top(struct notcurses* n);
43 struct ncplane* notcurses_bottom(struct notcurses* n);
45 struct ncplane* ncpile_top(struct ncplane* n);
47 struct ncplane* ncpile_bottom(struct ncplane* n);
49 struct ncplane* ncplane_reparent(struct ncplane* n, struct ncplane*
51 newparent);
52 struct ncplane* ncplane_reparent_family(struct ncplane* n, struct nc‐
54 plane* newparent);
55 int ncplane_descendant_p(const struct ncplane* n, const struct ncplane*
57 ancestor);
58 int ncplane_resize_realign(struct ncplane* n);
60 int ncplane_resize_maximize(struct ncplane* n);
62 int ncplane_resize_marginalized(struct ncplane* n);
64 void ncplane_set_resizecb(struct ncplane* n, int(resizecb)(struct nc‐
66 plane));
67 int (ncplane_resizecb(const struct ncplane n**))(struct ncplane*);**
69 struct ncplane* ncplane_dup(struct ncplane* n, void* opaque);
71 int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keeple‐
73 ny, int keeplenx, int yoff, int xoff, int ylen, int xlen);
74 int ncplane_move_yx(struct ncplane* n, int y, int x);
76 int ncplane_moverel(struct ncplane* n, int y, int x);
78 void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict
80 x);
81 int ncplane_y(const struct ncplane* n);
83 int ncplane_x(const struct ncplane* n);
85 void ncplane_abs_yx(const struct ncplane* n, int* y, int* x);
87 int ncplane_abs_y(const struct ncplane* n);
89 int ncplane_abs_x(const struct ncplane* n);
91 struct ncplane* ncplane_parent(struct ncplane* n);
93 const struct ncplane* ncplane_parent_const(const struct ncplane* n);
95 int ncplane_set_base_cell(struct ncplane* ncp, const nccell* c);
97 int ncplane_set_base(struct ncplane* ncp, const char* egc, uint32_t
99 stylemask, uint64_t channels);
100 int ncplane_base(struct ncplane* ncp, nccell* c);
102 void ncplane_move_top(struct ncplane* n);
104 void ncplane_move_bottom(struct ncplane* n);
106 void ncplane_move_family_top(struct ncplane* n);
108 void ncplane_move_family_bottom(struct ncplane* n);
110 int ncplane_move_above(struct ncplane* restrict n, struct ncplane* re‐
112 strict targ);
113 int ncplane_move_below(struct ncplane* restrict n, struct ncplane* re‐
115 strict targ);
116 int ncplane_move_family_above(struct ncplane* restrict n, struct nc‐
118 plane* restrict targ);
119 int ncplane_move_family_below(struct ncplane* restrict n, struct nc‐
121 plane* restrict targ);
122 struct ncplane* ncplane_below(struct ncplane* n);
124 struct ncplane* ncplane_above(struct ncplane* n);
126 char* ncplane_at_cursor(struct ncplane* n, uint16_t* stylemask,
128 uint64_t* channels);
129 int ncplane_at_cursor_cell(struct ncplane* n, nccell* c);
131 char* ncplane_at_yx(const struct ncplane* n, int y, int x, uint16_t*
133 stylemask, uint64_t* channels);
134 int ncplane_at_yx_cell(struct ncplane* n, int y, int x, nccell* c);
136 uint32_t* ncplane_as_rgba(const struct ncplane* nc, ncblitter_e blit,
138 int begy, int begx, int leny, int lenx, int* pxdimy, int* pxdimx);
139 char* ncplane_contents(const struct ncplane* nc, int begy, int begx,
141 int leny, int lenx);
142 void* ncplane_set_userptr(struct ncplane* n, void* opaque);
144 void* ncplane_userptr(struct ncplane* n);
146 void ncplane_dim_yx(const struct ncplane* n, int* restrict rows, int*
148 restrict cols);
149 static inline int ncplane_dim_y(const struct ncplane* n);
151 static inline int ncplane_dim_x(const struct ncplane* n);
153 void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int*
155 restrict x);
156 void ncplane_translate(const struct ncplane* src, const struct ncplane*
158 dst, int* restrict y, int* restrict x);
159 bool ncplane_translate_abs(const struct ncplane* n, int* restrict y,
161 int* restrict x);
162 uint64_t ncplane_channels(const struct ncplane* n);
164 void ncplane_set_channels(struct ncplane* nc, uint64_t channels);
166 static inline unsigned ncplane_bchannel(struct ncplane* nc);
168 static inline unsigned ncplane_fchannel(struct ncplane* nc);
170 static inline unsigned ncplane_fg_rgb8(struct ncplane* nc);
172 static inline unsigned ncplane_bg_rgb8(struct ncplane* nc);
174 static inline unsigned ncplane_fg_alpha(struct ncplane* nc);
176 static inline unsigned ncplane_bg_alpha(struct ncplane* nc);
178 static inline unsigned ncplane_fg_rgb8(struct ncplane* n, unsigned* r,
180 unsigned* g, unsigned* b);
181 static inline unsigned ncplane_bg_rgb8(struct ncplane* n, unsigned* r,
183 unsigned* g, unsigned* b);
184 int ncplane_set_fg_rgb8(struct ncplane* n, unsigned r, unsigned g, un‐
186 signed b);
187 int ncplane_set_bg_rgb8(struct ncplane* n, unsigned r, unsigned g, un‐
189 signed b);
190 void ncplane_set_fg_rgb8_clipped(struct ncplane* n, int r, int g, int
192 b);
193 void ncplane_set_bg_rgb8_clipped(struct ncplane* n, int r, int g, int
195 b);
196 int ncplane_set_fg_rgb8(struct ncplane* n, uint32_t channel);
198 int ncplane_set_bg_rgb8(struct ncplane* n, uint32_t channel);
200 void ncplane_set_fg_default(struct ncplane* n);
202 void ncplane_set_bg_default(struct ncplane* n);
204 int ncplane_set_fg_alpha(struct ncplane* n, unsigned alpha);
206 int ncplane_set_bg_alpha(struct ncplane* n, unsigned alpha);
208 int ncplane_set_fg_palindex(struct ncplane* n, int idx);
210 int ncplane_set_bg_palindex(struct ncplane* n, int idx);
212 uint16_t ncplane_styles(const struct ncplane* n);
214 void ncplane_set_styles(struct ncplane* n, unsigned stylebits);
216 void ncplane_on_styles(struct ncplane* n, unsigned stylebits);
218 void ncplane_off_styles(struct ncplane* n, unsigned stylebits);
220 void ncplane_greyscale(struct ncplane* n);
222 int ncplane_blit_bgrx(struct ncplane* nc, int placey, int placex, int
224 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
225 begx, int leny, int lenx);
226 int ncplane_blit_rgba(struct ncplane* nc, int placey, int placex, int
228 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
229 begx, int leny, int lenx);
230 int ncplane_destroy(struct ncplane* ncp);
232 void notcurses_drop_planes(struct notcurses* nc);
234 int ncplane_mergedown(struct ncplane* src, struct ncplane* dst, int
236 begsrcy, int begsrcx, int leny, int lenx, int dsty, int dstx);
237 int ncplane_mergedown_simple(struct ncplane* restrict src, struct nc‐
239 plane* restrict dst);
240 void ncplane_erase(struct ncplane* n);
242 int ncplane_erase_region(struct ncplane* n, int ystart, int xstart, int
244 ylen, int xlen);
245 bool ncplane_set_scrolling(struct ncplane* n, bool scrollp);
247 bool ncplane_scrolling_p(const struct ncplane* n);
249 int ncplane_scrollup(struct ncplane* n, int r);
251 int ncplane_scrollup_child(struct ncplane* n, const struct ncplane*
253 child);
254 int ncplane_rotate_cw(struct ncplane* n);
256 int ncplane_rotate_ccw(struct ncplane* n);
258 void ncplane_pixelgeom(struct notcurses* n, int* restrict pxy, int* re‐
260 strict pxx, int* restrict celldimy, int* restrict celldimx, int* re‐
261 strict maxbmapy, int* restrict maxbmapx);
262 int ncplane_set_name(struct ncplane* n, const char* name);
264 char* ncplane_name(const struct ncplane* n);
266 DESCRIPTION
268 Ncplanes are the fundamental drawing object of notcurses. All output
269 functions take a struct ncplane as an argument. They can be any size,
270 and placed anywhere. In addition to its framebuffer--a rectilinear ma‐
271 trix of nccells (see notcurses_cell(3))--an ncplane is defined by:
272 • a base nccell, used for any cell on the plane without a glyph,
274 • the egcpool backing its nccells,
276 • a current cursor location,
278 • a current style, foreground channel, and background channel,
280 • its geometry,
282 • a configured user pointer,
284 • position relative to the standard plane,
286 • the plane, if any, to which it is bound,
288 • the next plane bound by the plane to which it is bound,
290 • the head of the list of its bound planes,
292 • its resize methodology,
294 • whether a sprixel (see notcurses_visual(3)) is associated,
296 • its z-index, and
298 • a name (used only for debugging).
300 New planes can be created with ncplane_create. If a plane is bound to
302 another, x and y coordinates are relative to the plane to which it is
303 bound, and if this latter plane moves, all its bound planes move along
304 with it. When a plane is destroyed, all planes bound to it (directly
305 or transitively) are destroyed.
306 If the NCPLANE_OPTION_HORALIGNED flag is provided, x is interpreted as
308 an ncalign_e rather than an absolute position. If the NCPLANE_OP‐
309 TION_VERALIGNED flag is provided, y is interpreted as an ncalign_e
310 rather than an absolute postiion. Either way, all positions are rela‐
311 tive to the parent plane. ncplane_resize_realign should usually be
312 used together with these flags, so that the plane is automatically re‐
313 aligned upon a resize of its parent.
314 If the NCPLANE_OPTION_MARGINALIZED flag is provided, neither NC‐
316 PLANE_OPTION_HORALIGNED nor NCPLANE_OPTION_VERALIGNED may be provided,
317 and rows and cols must both be 0. y and x will be interpreted as top
318 and left margins. margin_b and margin_r will be interpreted as bottom
319 and right margins. The plane will take the maximum space possible sub‐
320 ject to its parent planes and these margins. The plane cannot become
321 smaller than 1x1 (the margins are best-effort). ncplane_re‐
322 size_marginalized should usually be used together with this flag, so
323 that the plane is automatically resized.
324 ncplane_reparent detaches the plane n from any plane to which it is
326 bound, and binds it to newparent. Its children are reparented to its
327 previous parent. The standard plane cannot be reparented. If newpar‐
328 ent is NULL, the plane becomes the root plane of a new, unrendered
329 stack. When ncplane_reparent_family is used, all planes bound to n
330 move along with it during a reparenting operation. See Piles below.
331 ncplane_destroy destroys a particular ncplane, after which it must not
333 be used again. notcurses_drop_planes destroys all ncplanes other than
334 the stdplane. Any references to such planes are, of course, invalidat‐
335 ed. It is undefined to destroy a plane concurrently with any other op‐
336 eration involving that plane, or any operation involving the z-axis.
337 It is an error for two threads to concurrently mutate a single ncplane.
339 So long as rendering is not taking place, however, multiple threads may
340 safely output to multiple ncplanes. So long as all threads are read‐
341 ers, multiple threads may work with a single ncplane. A reading func‐
342 tion is any which accepts a const struct ncplane.
343 A plane can be moved relative to its parent plane's origin with nc‐
345 plane_move_yx. If the plane has no parent, the move is relative to the
346 rendering area. A plane can be moved off-screen entirely, in which
347 case it will not be visible following rasterization; it can also be
348 partially off-screen.
349 A plane has a virtual cursor; Set its new position with ncplane_cur‐
351 sor_move_yx. Specifying -1 as one or both coordinates will hold that
352 axis constant. You may move a cursor relatively to its current posi‐
353 tion with ncplane_cursor_move_rel. Unless coordinates are specified
354 for a call, action takes place at the plane's virtual cursor, which au‐
355 tomatically moves along with output. The current virtual cursor loca‐
356 tion can be acquired with ncplane_cursor_yx.
357 ncplane_yx returns the coordinates of the specified plane's origin,
359 relative to the plane to which it is bound. Either or both of y and x
360 may be NULL. ncplane_y and ncplane_x allow a single component of this
361 location to be retrieved. ncplane_abs_yx returns the coordinates of
362 the specified plane's origin relative to its pile.
363 ncplane_translate translates coordinates expressed relative to the
365 plane src, and writes the coordinates of that cell relative to dst.
366 The cell need not intersect with dst, though this will yield coordi‐
367 nates which are invalid for writing or reading on dst. If dst is NULL,
368 it is taken to refer to the standard plane. ncplane_translate_abs
369 takes coordinates expressed relative to the standard plane, and returns
370 coordinates relative to dst, returning false if the coordinates are in‐
371 valid for dst.
372 ncplane_mergedown writes to dst the frame that would be rendered if on‐
374 ly src and dst existed on the z-axis, ad dst represented the entirety
375 of the rendering region. Only those cells where src intersects with
376 dst might see changes. It is an error to merge a plane onto itself.
377 ncplane_erase zeroes out every cell of the plane, dumps the egcpool,
379 and homes the cursor. The base cell is preserved, as are the active
380 attributes. ncplane_erase_region does the same for a subregion of the
381 plane. For the latter, supply 0 for ylen and/or xlen to erase through
382 that dimension, starting at the specified point. Supply -1 for ystart
383 and/or xstart to use the cursor's current position along that axis for
384 a starting point. Negative ylen and xlen move up and to the left from
385 the starting coordinate; positive ylen and xlen move down and to the
386 right from same. See BUGS below.
387 When a plane is resized (whether by ncplane_resize, SIGWINCH, or any
389 other mechanism), a depth-first recursion is performed on its children.
390 Each child plane having a non-NULL resizecb will see that callback in‐
391 voked following resizing of its parent's plane. If it returns non-ze‐
392 ro, the resizing cascade terminates, returning non-zero. Otherwise,
393 resizing proceeds recursively.
394 ncplane_move_top and ncplane_move_bottom extract their argument n from
396 the z-axis, and reinsert it at the top or bottom, respectively, of its
397 pile. These functions are both O(1). ncplane_move_family_top and nc‐
398 plane_move_family_bottom do the same, and move any bound descendants
399 along with the plane. Ordering among the plane and its descendants
400 will be maintained. For example, assume a pile with A at the top of
401 its z-axis, followed by B, C, D, and E, where E is bound to C. Calling
402 ncplane_move_family_top on C will result in the order CEABD. Calling
403 ncplane_move_family_bottom on C will result in the order ABDCE. Call‐
404 ing ncplane_move_family_top or ncplane_move_top on E will result in
405 EABCD. Calling ncplane_move_family_bottom on E is a no-op. These two
406 functions are O(N) on the number of planes in the pile.
407 ncplane_move_above and ncplane_move_below move the argument n above or
409 below, respectively, the argument targ. Both operate in O(1).
410 Base cells
412 Each plane has a base cell, initialized to all zeroes. When rendering,
413 the cells of the plane are examined in turn. Each cell has three inde‐
414 pendent rendering elements--its EGC, its foreground channel, and its
415 background channel. Any default channel is replaced with the corre‐
416 sponding channel from that plane's base cell. ncplane_erase has no ef‐
417 fect on the base cell. Calling ncplane_erase on a plane whose base
418 cell is a purple 'A' results (for rendering purposes) in a plane made
419 up entirely of purple 'A's.
420 ncplane_set_base_cell uses the nccell c (which must be bound to the nc‐
422 plane ncp, and must be the first nccell of a multicolumn sequence) to
423 set the base cell. ncplane_set_base does the same with egc, stylemask,
424 and channels.
425 Piles
427 A single notcurses context is made up of one or more piles. A pile is
428 a set of one or more ncplanes, including the partial orderings made up
429 of their binding and z-axis pointers. A pile has a top and bottom nc‐
430 plane (this might be a single plane), and one or more root planes
431 (planes which are bound to themselves). Multiple threads can concur‐
432 rently operate on distinct piles, even changing one while rendering an‐
433 other.
434 Each plane is part of one and only one pile. By default, a plane is
436 part of the same pile containing that plane to which it is bound. If
437 ncpile_create is used in the place of ncplane_create, the returned
438 plane becomes the root plane, top, and bottom of a new pile. As a root
439 plane, it is bound to itself. A new pile can also be created by repar‐
440 enting a plane to itself, though if the plane is already a root plane,
441 this is a no-op.
442 When a plane is moved to a different pile (whether new or preexisting),
444 any planes which were bound to it are rebound to its previous parent.
445 If the plane was a root plane of some pile, any bound planes become
446 root planes. The new plane is placed immediately atop its new parent
447 on its new pile's z-axis. When ncplane_reparent_family is used, all
448 planes bound to the reparented plane are moved along with it. Their
449 relative z-order is maintained.
450 Binding
452 The planes of a pile make up a directed acyclic forest. Planes bound
453 to themselves make up the root planes of the pile. Every plane is ei‐
454 ther a root plane, or bound to some other plane in its pile. A plane
455 and its descendants make up a family. When a plane is moved using nc‐
456 plane_move_yx, its family is moved along with it.
457 Scrolling
459 All planes, including the standard plane, are created with scrolling
460 disabled. Control scrolling on a per-plane basis with nc‐
461 plane_set_scrolling. Attempting to print past the end of a line will
462 stop at the plane boundary, and indicate an error. On a plane 10 col‐
463 umns wide and two rows high, printing "0123456789" at the origin should
464 succeed, but printing "01234567890" will by default fail at the
465 eleventh character. In either case, the cursor will be left at loca‐
466 tion 0x10; it must be moved before further printing can take place. If
467 scrolling is enabled, the first row will be filled with 01234546789,
468 the second row will have 0 written to its first column, and the cursor
469 will end up at 1x1. Note that it is still an error to manually attempt
470 to move the cursor off-plane, or to specify off-plane output. Box-
471 drawing does not result in scrolling; attempting to draw a 2x11 box on
472 our 2x10 plane will result in an error and no output. When scrolling
473 is enabled, and output takes place while the cursor is past the end of
474 the last row, the first row is discarded, all other rows are moved up,
475 the last row is cleared, and output begins at the beginning of the last
476 row. This does not take place until output is generated (i.e. it is
477 possible to fill a plane when scrolling is enabled).
478 By default, planes bound to a scrolling plane will scroll along with
480 it, if they intersect the plane. This can be disabled with the NC‐
481 PLANE_OPTION_FIXED flag.
482 Bitmaps
484 ncplane_pixelgeom retrieves pixel geometry details. pxy and pxx return
485 the size of the plane in pixels. celldimy and celldimx return the size
486 of a cell in pixels (these ought be the same across planes). maxbmapy
487 and maxbmapx describe the largest bitmap which can be displayed in the
488 plane. Any parameter (save n) may be NULL.
489 When a plane is blitted to using ncvisual_blit and NCBLIT_PIXEL (see
491 notcurses_visual(3)), it ceases to accept cell-based output. The
492 sprixel will remain associated until a new sprixel is blitted to the
493 plane, the plane is resized, the plane is erased, or the plane is de‐
494 stroyed. The base cell of a sprixelated plane has no effect; if the
495 sprixel is not even multiples of the cell geometry, the "excess plane"
496 is ignored during rendering.
497 ncplane_at_yx and ncplane_at_yx_cell retrieve the contents of the plane
499 at the specified coordinate. The content is returned as it will be
500 used during rendering, and thus integrates any base cell as appropri‐
501 ate. If called on the secondary columns of a wide glyph, ncplane_at_yx
502 returns the EGC, and thus cannot be used to distinguish between primary
503 and secondary columns. ncplane_at_yx_cell, however, preserves this in‐
504 formation: retrieving a secondary column of a wide glyph with nc‐
505 plane_at_yx_cell will fill in the nccell argument such that nccell_ex‐
506 tended_gcluster(3) returns an empty string, and nccell_wide_right_p(3)
507 returns true.
508 ncplane_set_name sets the plane's name, freeing any old name. name may
510 be NULL.
511
513 ncplane_create and ncplane_dup return a new struct ncplane on success,
514 or NULL on failure.
515 ncplane_userptr returns the configured user pointer for the ncplane,
517 and cannot fail.
518 ncplane_below returns the plane below the specified ncplane. If the
520 provided plane is the bottommost plane, NULL is returned. It cannot
521 fail.
522 ncplane_set_scrolling returns true if scrolling was previously enabled,
524 and false otherwise.
525 ncpile_top and ncpile_bottom return the topmost and bottommost planes,
527 respectively, of the pile containing their argument. notcurses_top and
528 notcurses_bottom do the same for the standard pile.
529 ncplane_at_yx and ncplane_at_cursor return a heap-allocated copy of the
531 EGC at the relevant cell, or NULL if the cell is invalid. The caller
532 should free this result. ncplane_at_yx_cell and ncplane_at_cursor_cell
533 instead load these values into an nccell, which is invalidated if the
534 associated plane is destroyed. The caller should release this nccell
535 with nccell_release.
536 ncplane_as_rgba returns a heap-allocated array of uint32_t values, each
538 representing a single RGBA pixel, or NULL on failure.
539 ncplane_erase_region returns -1 if ystart or xstart are less than -1,
541 or outside the plane.
542 ncplane_cursor_move_yx returns -1 if the coordinates are beyond the di‐
544 mensions of the specified plane (except for the special value -1).
545 ncplane_cursor_move_rel returns -1 if the coordinates are beyond the
547 dimensions of the specified plane.
548 ncplane_name returns a heap-allocated copy of the plane's name, or NULL
550 if it has no name (or on error).
551 Functions returning int return 0 on success, and non-zero on error.
553 All other functions cannot fail (and return void).
555
557 ncplane_new is defined as a deprecated wrapper around ncplane_create.
558 It should not be used in new code.
559
561 ncplane_at_yx doesn't yet account for bitmap-based graphics (see
562 notcurses_visual(3)). Whatever glyph-based contents existed on the
563 plane when the bitmap was blitted will continue to be returned.
564 When the alternate screen is not used (see notcurses_init(3)), the con‐
566 tents of the terminal at startup remain present until obliterated on a
567 cell-by-cell basis. ncplane_erase and ncplane_erase_region cannot be
568 used to clear the terminal of startup content. If you want the screen
569 cleared on startup, but do not want to use (or rely on) the alternate
570 screen, use something like:
571 ncplane_set_base(notcurses_stdplane(nc), " ", 0, 0);
573 notcurses_render(nc);
574 or simply:
576 notcurses_refresh(nc);
578
580 notcurses(3), notcurses_capabilities(3), notcurses_cell(3), notcurs‐
581 es_output(3), notcurses_stdplane(3), notcurses_visual(3)
582
584 nick black <nickblack@linux.com>.
585 v2.4.9 notcurses_plane(3)