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 #define NCPLANE_OPTION_AUTOGROW 0x0010ull
16 #define NCPLANE_OPTION_VSCROLL 0x0020ull
17 typedef struct ncplane_options {
19 int y; // vertical placement relative to parent plane
20 int x; // horizontal placement relative to parent plane
21 int rows; // number of rows, must be positive
22 int cols; // number of columns, must be positive
23 void* userptr; // user curry, may be NULL
24 const char* name; // name (used only for debugging), may be NULL
25 int (*resizecb)(struct ncplane*); // called on parent resize
26 uint64_t flags; // closure over NCPLANE_OPTION_*
27 unsigned margin_b, margin_r; // bottom and right margins
28 } ncplane_options;
29 #define NCSTYLE_MASK 0xffffu
31 #define NCSTYLE_ITALIC 0x0010u
32 #define NCSTYLE_UNDERLINE 0x0008u
33 #define NCSTYLE_UNDERCURL 0x0004u
34 #define NCSTYLE_BOLD 0x0002u
35 #define NCSTYLE_STRUCK 0x0001u
36 #define NCSTYLE_NONE 0
37 struct ncplane* ncplane_create(struct ncplane* n, const ncplane_op‐
39 tions* nopts);
40 struct ncplane* ncpile_create(struct notcurses* n, const ncplane_op‐
42 tions* nopts);
43 struct ncplane* ncplane_reparent(struct ncplane* n, struct ncplane*
45 newparent);
46 struct ncplane* ncplane_reparent_family(struct ncplane* n, struct nc‐
48 plane* newparent);
49 int ncplane_descendant_p(const struct ncplane* n, const struct ncplane*
51 ancestor);
52 int ncplane_resize_realign(struct ncplane* n);
54 int ncplane_resize_maximize(struct ncplane* n);
56 int ncplane_resize_marginalized(struct ncplane* n);
58 int ncplane_resize_placewithin(struct ncplane* n);
60 void ncplane_set_resizecb(struct ncplane* n, int(resizecb)(struct nc‐
62 plane));
63 int (ncplane_resizecb(const struct ncplane n**))(struct ncplane*);**
65 struct ncplane* ncplane_dup(struct ncplane* n, void* opaque);
67 int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keeple‐
69 ny, int keeplenx, int yoff, int xoff, int ylen, int xlen);
70 int ncplane_move_yx(struct ncplane* n, int y, int x);
72 int ncplane_move_rel(struct ncplane* n, int y, int x);
74 void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict
76 x);
77 int ncplane_y(const struct ncplane* n);
79 int ncplane_x(const struct ncplane* n);
81 void ncplane_abs_yx(const struct ncplane* n, int* y, int* x);
83 int ncplane_abs_y(const struct ncplane* n);
85 int ncplane_abs_x(const struct ncplane* n);
87 struct ncplane* ncplane_parent(struct ncplane* n);
89 const struct ncplane* ncplane_parent_const(const struct ncplane* n);
91 int ncplane_set_base_cell(struct ncplane* ncp, const nccell* c);
93 int ncplane_set_base(struct ncplane* ncp, const char* egc, uint16_t
95 stylemask, uint64_t channels);
96 int ncplane_base(struct ncplane* ncp, nccell* c);
98 static inline void ncplane_move_top(struct ncplane* n);
100 static inline void ncplane_move_bottom(struct ncplane* n);
102 void ncplane_move_family_top(struct ncplane* n);
104 void ncplane_move_family_bottom(struct ncplane* n);
106 int ncplane_move_above(struct ncplane* restrict n, struct ncplane* re‐
108 strict targ);
109 int ncplane_move_below(struct ncplane* restrict n, struct ncplane* re‐
111 strict targ);
112 int ncplane_move_family_above(struct ncplane* restrict n, struct nc‐
114 plane* restrict targ);
115 int ncplane_move_family_below(struct ncplane* restrict n, struct nc‐
117 plane* restrict targ);
118 struct ncplane* ncplane_below(struct ncplane* n);
120 struct ncplane* ncplane_above(struct ncplane* n);
122 char* ncplane_at_cursor(struct ncplane* n, uint16_t* stylemask,
124 uint64_t* channels);
125 int ncplane_at_cursor_cell(struct ncplane* n, nccell* c);
127 char* ncplane_at_yx(const struct ncplane* n, int y, int x, uint16_t*
129 stylemask, uint64_t* channels);
130 int ncplane_at_yx_cell(struct ncplane* n, int y, int x, nccell* c);
132 uint32_t* ncplane_as_rgba(const struct ncplane* nc, ncblitter_e blit,
134 unsigned begy, unsigned begx, unsigned leny, unsigned lenx, unsigned*
135 pxdimy, unsigned* pxdimx);
136 char* ncplane_contents(const struct ncplane* nc, int begy, int begx,
138 unsigned leny, unsigned lenx);
139 void* ncplane_set_userptr(struct ncplane* n, void* opaque);
141 void* ncplane_userptr(struct ncplane* n);
143 void ncplane_dim_yx(const struct ncplane* n, unsigned* restrict rows,
145 unsigned* restrict cols);
146 static inline unsigned ncplane_dim_y(const struct ncplane* n);
148 static inline unsigned ncplane_dim_x(const struct ncplane* n);
150 void ncplane_cursor_yx(const struct ncplane* n, unsigned* restrict y,
152 unsigned* restrict x);
153 unsigned ncplane_cursor_y(const struct ncplane* n);
155 unsigned ncplane_cursor_x(const struct ncplane* n);
157 void ncplane_translate(const struct ncplane* src, const struct ncplane*
159 dst, int* restrict y, int* restrict x);
160 bool ncplane_translate_abs(const struct ncplane* n, int* restrict y,
162 int* restrict x);
163 uint64_t ncplane_channels(const struct ncplane* n);
165 void ncplane_set_channels(struct ncplane* nc, uint64_t channels);
167 static inline unsigned ncplane_bchannel(struct ncplane* nc);
169 static inline unsigned ncplane_fchannel(struct ncplane* nc);
171 uint64_t ncplane_set_bchannel(struct ncplane* nc, uint32_t channel);
173 uint64_t ncplane_set_fchannel(struct ncplane* nc, uint32_t channel);
175 static inline unsigned ncplane_fg_rgb(struct ncplane* nc);
177 static inline unsigned ncplane_bg_rgb(struct ncplane* nc);
179 int ncplane_set_fg_rgb(struct ncplane* n, uint32_t channel);
181 int ncplane_set_bg_rgb(struct ncplane* n, uint32_t channel);
183 static inline unsigned ncplane_fg_alpha(struct ncplane* nc);
185 static inline unsigned ncplane_bg_alpha(struct ncplane* nc);
187 int ncplane_set_fg_alpha(struct ncplane* n, unsigned alpha);
189 int ncplane_set_bg_alpha(struct ncplane* n, unsigned alpha);
191 static inline unsigned ncplane_fg_rgb8(struct ncplane* n, unsigned* r,
193 unsigned* g, unsigned* b);
194 static inline unsigned ncplane_bg_rgb8(struct ncplane* n, unsigned* r,
196 unsigned* g, unsigned* b);
197 int ncplane_set_fg_rgb8(struct ncplane* n, unsigned r, unsigned g, un‐
199 signed b);
200 int ncplane_set_bg_rgb8(struct ncplane* n, unsigned r, unsigned g, un‐
202 signed b);
203 void ncplane_set_fg_rgb8_clipped(struct ncplane* n, int r, int g, int
205 b);
206 void ncplane_set_bg_rgb8_clipped(struct ncplane* n, int r, int g, int
208 b);
209 void ncplane_set_fg_default(struct ncplane* n);
211 void ncplane_set_bg_default(struct ncplane* n);
213 int ncplane_set_fg_palindex(struct ncplane* n, unsigned idx);
215 int ncplane_set_bg_palindex(struct ncplane* n, unsigned idx);
217 uint16_t ncplane_styles(const struct ncplane* n);
219 void ncplane_set_styles(struct ncplane* n, unsigned stylebits);
221 void ncplane_on_styles(struct ncplane* n, unsigned stylebits);
223 void ncplane_off_styles(struct ncplane* n, unsigned stylebits);
225 void ncplane_greyscale(struct ncplane* n);
227 int ncplane_blit_bgrx(struct ncplane* nc, int placey, int placex, int
229 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
230 begx, int leny, int lenx);
231 int ncplane_blit_rgba(struct ncplane* nc, int placey, int placex, int
233 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
234 begx, int leny, int lenx);
235 int ncplane_destroy(struct ncplane* ncp);
237 void notcurses_drop_planes(struct notcurses* nc);
239 int ncplane_mergedown(struct ncplane* src, struct ncplane* dst, int
241 begsrcy, int begsrcx, unsigned leny, unsigned lenx, int dsty, int
242 dstx);
243 int ncplane_mergedown_simple(struct ncplane* restrict src, struct nc‐
245 plane* restrict dst);
246 void ncplane_erase(struct ncplane* n);
248 int ncplane_erase_region(struct ncplane* n, int ystart, int xstart, int
250 ylen, int xlen);
251 bool ncplane_set_scrolling(struct ncplane* n, unsigned scrollp);
253 bool ncplane_scrolling_p(const struct ncplane* n);
255 bool ncplane_set_autogrow(struct ncplane* n, unsigned growp);
257 bool ncplane_autogrow_p(const struct ncplane* n);
259 int ncplane_scrollup(struct ncplane* n, int r);
261 int ncplane_scrollup_child(struct ncplane* n, const struct ncplane*
263 child);
264 int ncplane_rotate_cw(struct ncplane* n);
266 int ncplane_rotate_ccw(struct ncplane* n);
268 void ncplane_pixel_geom(const struct notcurses* n, unsigned* restrict
270 pxy, unsigned* restrict pxx, unsigned* restrict celldimy, unsigned* re‐
271 strict celldimx, unsigned* restrict maxbmapy, unsigned* restrict
272 maxbmapx);
273 int ncplane_set_name(struct ncplane* n, const char* name);
275 char* ncplane_name(const struct ncplane* n);
277
279 Ncplanes are the fundamental drawing object of notcurses. All output
280 functions take a struct ncplane as an argument. They can be any size,
281 and placed anywhere. In addition to its framebuffer--a rectilinear ma‐
282 trix of nccells (see notcurses_cell(3))--an ncplane is defined by:
283 • a base nccell, used for any cell on the plane without a glyph,
285 • the egcpool backing its nccells,
287 • a current cursor location,
289 • a current style, foreground channel, and background channel,
291 • its geometry,
293 • a configured user pointer,
295 • position relative to the standard plane,
297 • the plane, if any, to which it is bound,
299 • the next plane bound by the plane to which it is bound,
301 • the head of the list of its bound planes,
303 • its resize methodology,
305 • whether a sprixel (see notcurses_visual(3)) is associated,
307 • its z-index, and
309 • a name (used only for debugging).
311 New planes can be created with ncplane_create. If a plane is bound to
313 another, x and y coordinates are relative to the plane to which it is
314 bound, and if this latter plane moves, all its bound planes move along
315 with it. When a plane is destroyed, all planes bound to it (directly
316 or transitively) are destroyed.
317 If the NCPLANE_OPTION_HORALIGNED flag is provided, x is interpreted as
319 an ncalign_e rather than an absolute position. If the NCPLANE_OP‐
320 TION_VERALIGNED flag is provided, y is interpreted as an ncalign_e
321 rather than an absolute postiion. Either way, all positions are rela‐
322 tive to the parent plane. ncplane_resize_realign should usually be
323 used together with these flags, so that the plane is automatically re‐
324 aligned upon a resize of its parent.
325 If the NCPLANE_OPTION_MARGINALIZED flag is provided, neither NC‐
327 PLANE_OPTION_HORALIGNED nor NCPLANE_OPTION_VERALIGNED may be provided,
328 and rows and cols must both be 0. y and x will be interpreted as top
329 and left margins. margin_b and margin_r will be interpreted as bottom
330 and right margins. The plane will take the maximum space possible sub‐
331 ject to its parent planes and these margins. The plane cannot become
332 smaller than 1x1 (the margins are best-effort). ncplane_re‐
333 size_marginalized should usually be used together with this flag, so
334 that the plane is automatically resized.
335 ncplane_reparent detaches the plane n from any plane to which it is
337 bound, and binds it to newparent. Its children are reparented to its
338 previous parent. The standard plane cannot be reparented. If newpar‐
339 ent is NULL, the plane becomes the root plane of a new, unrendered
340 stack. When ncplane_reparent_family is used, all planes bound to n
341 move along with it during a reparenting operation. See Piles below.
342 ncplane_destroy destroys a particular ncplane, after which it must not
344 be used again. notcurses_drop_planes destroys all ncplanes other than
345 the stdplane. Any references to such planes are, of course, invalidat‐
346 ed. It is undefined to destroy a plane concurrently with any other op‐
347 eration involving that plane, or any operation involving the z-axis.
348 It is an error for two threads to concurrently mutate a single ncplane.
350 So long as rendering is not taking place, however, multiple threads may
351 safely output to multiple ncplanes. So long as all threads are read‐
352 ers, multiple threads may work with a single ncplane. A reading func‐
353 tion is any which accepts a const struct ncplane.
354 A plane can be moved relative to its parent plane's origin with nc‐
356 plane_move_yx. If the plane has no parent, the move is relative to the
357 rendering area. A plane can be moved off-screen entirely, in which
358 case it will not be visible following rasterization; it can also be
359 partially off-screen.
360 A plane has a virtual cursor; Set its new position with ncplane_cur‐
362 sor_move_yx. Specifying -1 as one or both coordinates will hold that
363 axis constant. You may move a cursor relatively to its current posi‐
364 tion with ncplane_cursor_move_rel. Unless coordinates are specified
365 for a call, action takes place at the plane's virtual cursor, which au‐
366 tomatically moves along with output. The current virtual cursor loca‐
367 tion can be acquired with ncplane_cursor_yx.
368 ncplane_yx returns the coordinates of the specified plane's origin,
370 relative to the plane to which it is bound. Either or both of y and x
371 may be NULL. ncplane_y and ncplane_x allow a single component of this
372 location to be retrieved. ncplane_abs_yx returns the coordinates of
373 the specified plane's origin relative to its pile.
374 ncplane_translate translates coordinates expressed relative to the
376 plane src, and writes the coordinates of that cell relative to dst.
377 The cell need not intersect with dst, though this will yield coordi‐
378 nates which are invalid for writing or reading on dst. If dst is NULL,
379 it is taken to refer to the standard plane. ncplane_translate_abs
380 takes coordinates expressed relative to the standard plane, and returns
381 coordinates relative to dst, returning false if the coordinates are in‐
382 valid for dst.
383 ncplane_mergedown writes to dst the frame that would be rendered if on‐
385 ly src and dst existed on the z-axis, ad dst represented the entirety
386 of the rendering region. Only those cells where src intersects with
387 dst might see changes. It is an error to merge a plane onto itself.
388 ncplane_erase zeroes out every cell of the plane, dumps the egcpool,
390 and homes the cursor. The base cell is preserved, as are the active
391 attributes. ncplane_erase_region does the same for a subregion of the
392 plane. For the latter, supply 0 for ylen and/or xlen to erase through
393 that dimension, starting at the specified point. Supply -1 for ystart
394 and/or xstart to use the cursor's current position along that axis for
395 a starting point. Negative ylen and xlen move up and to the left from
396 the starting coordinate; positive ylen and xlen move down and to the
397 right from same. See BUGS below.
398 When a plane is resized (whether by ncplane_resize, SIGWINCH, or any
400 other mechanism), a depth-first recursion is performed on its children.
401 Each child plane having a non-NULL resizecb will see that callback in‐
402 voked following resizing of its parent's plane. If it returns non-ze‐
403 ro, the resizing cascade terminates, returning non-zero. Otherwise,
404 resizing proceeds recursively.
405 ncplane_move_top and ncplane_move_bottom extract their argument n from
407 the z-axis, and reinsert it at the top or bottom, respectively, of its
408 pile. These functions are both O(1). ncplane_move_family_top and nc‐
409 plane_move_family_bottom do the same, and move any bound descendants
410 along with the plane. Ordering among the plane and its descendants
411 will be maintained. For example, assume a pile with A at the top of
412 its z-axis, followed by B, C, D, and E, where E is bound to C. Calling
413 ncplane_move_family_top on C will result in the order CEABD. Calling
414 ncplane_move_family_bottom on C will result in the order ABDCE. Call‐
415 ing ncplane_move_family_top or ncplane_move_top on E will result in
416 EABCD. Calling ncplane_move_family_bottom on E is a no-op. These two
417 functions are O(N) on the number of planes in the pile.
418 ncplane_move_above and ncplane_move_below move the argument n above or
420 below, respectively, the argument targ. Both operate in O(1).
421 ncplane_at_yx and ncplane_at_yx_cell retrieve the contents of the plane
423 at the specified coordinate. The content is returned as it will be
424 used during rendering, and thus integrates any base cell as appropri‐
425 ate. If called on the secondary columns of a wide glyph, ncplane_at_yx
426 returns the EGC, and thus cannot be used to distinguish between primary
427 and secondary columns. ncplane_at_yx_cell, however, preserves this in‐
428 formation: retrieving a secondary column of a wide glyph with nc‐
429 plane_at_yx_cell will fill in the nccell argument such that nccell_ex‐
430 tended_gcluster(3) returns an empty string, and nccell_wide_right_p(3)
431 returns true.
432 If ncplane_at_yx is invoked upon a sprixel plane, the control sequence
434 will be returned for any valid coordinates (note that this may be quite
435 large). This does not apply to ncplane_at_yx_cell, which will return
436 an error.
437 ncplane_set_name sets the plane's name, freeing any old name. name may
439 be NULL. ncplane_set_name duplicates the provided name internally.
440 Base cells
442 Each plane has a base cell, initialized to all zeroes. When rendering,
443 the cells of the plane are examined in turn. Each cell has three inde‐
444 pendent rendering elements--its EGC, its foreground channel, and its
445 background channel. Any default channel is replaced with the corre‐
446 sponding channel from that plane's base cell. ncplane_erase has no ef‐
447 fect on the base cell. Calling ncplane_erase on a plane whose base
448 cell is a purple 'A' results (for rendering purposes) in a plane made
449 up entirely of purple 'A's.
450 ncplane_set_base_cell uses the nccell c (which must be bound to the nc‐
452 plane ncp, and must be the first nccell of a multicolumn sequence) to
453 set the base cell. ncplane_set_base does the same with egc, stylemask,
454 and channels.
455 Piles
457 A single notcurses context is made up of one or more piles. A pile is
458 a set of one or more ncplanes, including the partial orderings made up
459 of their binding and z-axis pointers. A pile has a top and bottom nc‐
460 plane (this might be a single plane), and one or more root planes
461 (planes which are bound to themselves). Multiple threads can concur‐
462 rently operate on distinct piles, even changing one while rendering an‐
463 other.
464 Each plane is part of one and only one pile. By default, a plane is
466 part of the same pile containing that plane to which it is bound. If
467 ncpile_create is used in the place of ncplane_create, the returned
468 plane becomes the root plane, top, and bottom of a new pile. As a root
469 plane, it is bound to itself. A new pile can also be created by repar‐
470 enting a plane to itself, though if the plane is already a root plane,
471 this is a no-op.
472 When a plane is moved to a different pile (whether new or preexisting),
474 any planes which were bound to it are rebound to its previous parent.
475 If the plane was a root plane of some pile, any bound planes become
476 root planes. The new plane is placed immediately atop its new parent
477 on its new pile's z-axis. When ncplane_reparent_family is used, all
478 planes bound to the reparented plane are moved along with it. Their
479 relative z-order is maintained.
480 More information is available from notcurses_pile(3).
482 Binding
484 The planes of a pile make up a directed acyclic forest. Planes bound
485 to themselves make up the root planes of the pile. Every plane is ei‐
486 ther a root plane, or bound to some other plane in its pile. A plane
487 and its descendants make up a family. When a plane is moved using nc‐
488 plane_move_yx, its family is moved along with it.
489 Scrolling
491 All planes, including the standard plane, are created with scrolling
492 disabled. Control scrolling on a per-plane basis with nc‐
493 plane_set_scrolling. Attempting to print past the end of a line will
494 stop at the plane boundary, and indicate an error. On a plane 10 col‐
495 umns wide and two rows high, printing "0123456789" at the origin should
496 succeed, but printing "01234567890" will by default fail at the
497 eleventh character. In either case, the cursor will be left at loca‐
498 tion 0x10; it must be moved before further printing can take place. If
499 scrolling is enabled, the first row will be filled with 01234546789,
500 the second row will have 0 written to its first column, and the cursor
501 will end up at 1x1. Note that it is still an error to manually attempt
502 to move the cursor off-plane, or to specify off-plane output. Box-
503 drawing does not result in scrolling; attempting to draw a 2x11 box on
504 our 2x10 plane will result in an error and no output. When scrolling
505 is enabled, and output takes place while the cursor is past the end of
506 the last row, the first row is discarded, all other rows are moved up,
507 the last row is cleared, and output begins at the beginning of the last
508 row. This does not take place until output is generated (i.e. it is
509 possible to fill a plane when scrolling is enabled).
510 Creating a plane with the NCPLANE_OPTION_VSCROLL flag is equivalent to
512 immediately calling ncplane_set_scrolling on that plane with an argu‐
513 ment of true.
514 By default, planes bound to a scrolling plane will scroll along with
516 it, if they intersect the plane. This can be disabled by creating them
517 with the NCPLANE_OPTION_FIXED flag.
518 Autogrow
520 Normally, once output reaches the right boundary of a plane, it is im‐
521 possible to place more output unless the cursor is first moved. If
522 scrolling is enabled, the cursor will automatically move down and to
523 the left in this case, but upon reaching the bottom right corner of the
524 plane, it is impossible to place more output without a scrolling event.
525 If autogrow is in play, the plane will automatically be enlarged to ac‐
526 commodate output. If scrolling is disabled, growth takes place to the
527 right; it otherwise takes place at the bottom. The plane only grows in
528 one dimension. Autogrow cannot be enabled for the standard plane.
529 Creating a plane with the NCPLANE_OPTION_AUTOGROW flag is equivalent to
531 immediately calling ncplane_set_autogrow on that plane with an argument
532 of true.
533 Bitmaps
535 ncplane_pixel_geom retrieves pixel geometry details. pxy and pxx re‐
536 turn the size of the plane in pixels. celldimy and celldimx return the
537 size of a cell in pixels (these ought be the same across planes).
538 maxbmapy and maxbmapx describe the largest bitmap which can be dis‐
539 played in the plane. Any parameter (save n) may be NULL.
540 When a plane is blitted to using ncvisual_blit and NCBLIT_PIXEL (see
542 notcurses_visual(3)), it ceases to accept cell-based output. The
543 sprixel will remain associated until a new sprixel is blitted to the
544 plane, the plane is resized, the plane is erased, or the plane is de‐
545 stroyed. The base cell of a sprixelated plane has no effect; if the
546 sprixel is not even multiples of the cell geometry, the "excess plane"
547 is ignored during rendering.
548
550 ncplane_create and ncplane_dup return a new struct ncplane on success,
551 or NULL on failure.
552 ncplane_userptr returns the configured user pointer for the ncplane,
554 and cannot fail.
555 ncplane_below returns the plane below the specified ncplane. If the
557 provided plane is the bottommost plane, NULL is returned. It cannot
558 fail.
559 ncplane_set_scrolling returns true if scrolling was previously enabled,
561 and false otherwise.
562 ncplane_at_yx and ncplane_at_cursor return a heap-allocated copy of the
564 EGC at the relevant cell, or NULL if the cell is invalid. The caller
565 should free this result. ncplane_at_yx_cell and ncplane_at_cursor_cell
566 instead load these values into an nccell, which is invalidated if the
567 associated plane is destroyed. The caller should release this nccell
568 with nccell_release.
569 ncplane_as_rgba returns a heap-allocated array of uint32_t values, each
571 representing a single RGBA pixel, or NULL on failure.
572 ncplane_erase_region returns -1 if ystart or xstart are less than -1,
574 or outside the plane.
575 ncplane_cursor_move_yx returns -1 if the coordinates are beyond the di‐
577 mensions of the specified plane (except for the special value -1).
578 ncplane_cursor_move_rel returns -1 if the coordinates are beyond the
580 dimensions of the specified plane.
581 ncplane_name returns a heap-allocated copy of the plane's name, or NULL
583 if it has no name (or on error).
584 Functions returning int return 0 on success, and non-zero on error.
586 All other functions cannot fail (and return void).
588
591 ncplane_at_yx doesn't yet account for bitmap-based graphics (see
592 notcurses_visual(3)). Whatever glyph-based contents existed on the
593 plane when the bitmap was blitted will continue to be returned.
594 When the alternate screen is not used (see notcurses_init(3)), the con‐
596 tents of the terminal at startup remain present until obliterated on a
597 cell-by-cell basis. ncplane_erase and ncplane_erase_region cannot be
598 used to clear the terminal of startup content. If you want the screen
599 cleared on startup, but do not want to use (or rely on) the alternate
600 screen, use something like:
601 ncplane_set_base(notcurses_stdplane(nc), " ", 0, 0);
603 notcurses_render(nc);
604 or simply:
606 notcurses_refresh(nc);
608
610 notcurses(3), notcurses_capabilities(3), notcurses_cell(3), notcurs‐
611 es_output(3), notcurses_pile(3), notcurses_stdplane(3), notcurses_vis‐
612 ual(3)
613
615 nick black <nickblack@linux.com>.
616 v3.0.8 notcurses_plane(3)