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 typedef struct ncplane_options {
16 int y; // vertical placement relative to parent plane
17 int x; // horizontal placement relative to parent plane
18 int rows; // number of rows, must be positive
19 int cols; // number of columns, must be positive
20 void* userptr; // user curry, may be NULL
21 const char* name; // name (used only for debugging), may be NULL
22 int (*resizecb)(struct ncplane*); // called on parent resize
23 uint64_t flags; // closure over NCPLANE_OPTION_*
24 int margin_b, margin_r; // bottom and right margins
25 } ncplane_options;
26 struct ncplane* ncplane_create(struct ncplane* n, const ncplane_op‐
28 tions* nopts);
29 struct ncplane* ncpile_create(struct notcurses* n, const ncplane_op‐
31 tions* nopts);
32 struct ncplane* notcurses_top(struct notcurses* n);
34 struct ncplane* notcurses_bottom(struct notcurses* n);
36 struct ncplane* ncpile_top(struct ncplane* n);
38 struct ncplane* ncpile_bottom(struct ncplane* n);
40 struct ncplane* ncplane_reparent(struct ncplane* n, struct ncplane*
42 newparent);
43 struct ncplane* ncplane_reparent_family(struct ncplane* n, struct nc‐
45 plane* newparent);
46 int ncplane_descendant_p(const struct ncplane* n, const struct ncplane*
48 ancestor);
49 int ncplane_resize_realign(struct ncplane* n);
51 int ncplane_resize_maximize(struct ncplane* n);
53 int ncplane_resize_marginalized(struct ncplane* n);
55 void ncplane_set_resizecb(struct ncplane* n, int(resizecb)(struct nc‐
57 plane));
58 int (ncplane_resizecb(const struct ncplane n**))(struct ncplane*);**
60 struct ncplane* ncplane_dup(struct ncplane* n, void* opaque);
62 int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keeple‐
64 ny, int keeplenx, int yoff, int xoff, int ylen, int xlen);
65 int ncplane_move_yx(struct ncplane* n, int y, int x);
67 void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict
69 x);
70 int ncplane_y(const struct ncplane* n);
72 int ncplane_x(const struct ncplane* n);
74 void ncplane_abs_yx(const struct ncplane* n, int* y, int* x);
76 int ncplane_abs_y(const struct ncplane* n);
78 int ncplane_abs_x(const struct ncplane* n);
80 struct ncplane* ncplane_parent(struct ncplane* n);
82 const struct ncplane* ncplane_parent_const(const struct ncplane* n);
84 int ncplane_set_base_cell(struct ncplane* ncp, const nccell* c);
86 int ncplane_set_base(struct ncplane* ncp, const char* egc, uint32_t
88 stylemask, uint64_t channels);
89 int ncplane_base(struct ncplane* ncp, nccell* c);
91 int ncplane_move_top(struct ncplane* n);
93 int ncplane_move_bottom(struct ncplane* n);
95 int ncplane_move_above(struct ncplane* restrict n, struct ncplane* re‐
97 strict above);
98 int ncplane_move_below(struct ncplane* restrict n, struct ncplane* re‐
100 strict below);
101 struct ncplane* ncplane_below(struct ncplane* n);
103 struct ncplane* ncplane_above(struct ncplane* n);
105 char* ncplane_at_cursor(struct ncplane* n, uint16_t* stylemask,
107 uint64_t* channels);
108 int ncplane_at_cursor_cell(struct ncplane* n, nccell* c);
110 char* ncplane_at_yx(const struct ncplane* n, int y, int x, uint16_t*
112 stylemask, uint64_t* channels);
113 int ncplane_at_yx_cell(struct ncplane* n, int y, int x, nccell* c);
115 uint32_t* ncplane_as_rgba(const struct ncplane* nc, int begy, int begx,
117 int leny, int lenx, int* pxdimy, int* pxdimx);
118 char* ncplane_contents(const struct ncplane* nc, int begy, int begx,
120 int leny, int lenx);
121 void* ncplane_set_userptr(struct ncplane* n, void* opaque);
123 void* ncplane_userptr(struct ncplane* n);
125 void ncplane_dim_yx(const struct ncplane* n, int* restrict rows, int*
127 restrict cols);
128 static inline int ncplane_dim_y(const struct ncplane* n);
130 static inline int ncplane_dim_x(const struct ncplane* n);
132 void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int*
134 restrict x);
135 void ncplane_translate(const struct ncplane* src, const struct ncplane*
137 dst, int* restrict y, int* restrict x);
138 bool ncplane_translate_abs(const struct ncplane* n, int* restrict y,
140 int* restrict x);
141 uint64_t ncplane_channels(const struct ncplane* n);
143 void ncplane_set_channels(struct ncplane* nc, uint64_t channels);
145 static inline unsigned ncplane_bchannel(struct ncplane* nc);
147 static inline unsigned ncplane_fchannel(struct ncplane* nc);
149 static inline unsigned ncplane_fg_rgb8(struct ncplane* nc);
151 static inline unsigned ncplane_bg_rgb8(struct ncplane* nc);
153 static inline unsigned ncplane_fg_alpha(struct ncplane* nc);
155 static inline unsigned ncplane_bg_alpha(struct ncplane* nc);
157 static inline unsigned ncplane_fg_rgb8(struct ncplane* n, unsigned* r,
159 unsigned* g, unsigned* b);
160 static inline unsigned ncplane_bg_rgb8(struct ncplane* n, unsigned* r,
162 unsigned* g, unsigned* b);
163 int ncplane_set_fg_rgb8(struct ncplane* n, int r, int g, int b);
165 int ncplane_set_bg_rgb8(struct ncplane* n, int r, int g, int b);
167 void ncplane_set_fg_rgb8_clipped(struct ncplane* n, int r, int g, int
169 b);
170 void ncplane_set_bg_rgb8_clipped(struct ncplane* n, int r, int g, int
172 b);
173 int ncplane_set_fg_rgb8(struct ncplane* n, uint32_t channel);
175 int ncplane_set_bg_rgb8(struct ncplane* n, uint32_t channel);
177 void ncplane_set_fg_default(struct ncplane* n);
179 void ncplane_set_bg_default(struct ncplane* n);
181 int ncplane_set_fg_alpha(struct ncplane* n, unsigned alpha);
183 int ncplane_set_bg_alpha(struct ncplane* n, unsigned alpha);
185 int ncplane_set_fg_palindex(struct ncplane* n, int idx);
187 int ncplane_set_bg_palindex(struct ncplane* n, int idx);
189 uint16_t ncplane_styles(const struct ncplane* n);
191 void ncplane_set_styles(struct ncplane* n, unsigned stylebits);
193 void ncplane_on_styles(struct ncplane* n, unsigned stylebits);
195 void ncplane_off_styles(struct ncplane* n, unsigned stylebits);
197 void ncplane_greyscale(struct ncplane* n);
199 int ncplane_blit_bgrx(struct ncplane* nc, int placey, int placex, int
201 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
202 begx, int leny, int lenx);
203 int ncplane_blit_rgba(struct ncplane* nc, int placey, int placex, int
205 linesize, ncblitter_e blitter, const unsigned char* data, int begy, int
206 begx, int leny, int lenx);
207 int ncplane_destroy(struct ncplane* ncp);
209 void notcurses_drop_planes(struct notcurses* nc);
211 int ncplane_mergedown(struct ncplane* src, struct ncplane* dst, int
213 begsrcy, int begsrcx, int leny, int lenx, int dsty, int dstx);
214 int ncplane_mergedown_simple(struct ncplane* restrict src, struct nc‐
216 plane* restrict dst);
217 void ncplane_erase(struct ncplane* n);
219 int ncplane_erase_region(struct ncplane* n, int ystart, int xstart, int
221 ylen, int xlen);
222 bool ncplane_set_scrolling(struct ncplane* n, bool scrollp);
224 int ncplane_rotate_cw(struct ncplane* n);
226 int ncplane_rotate_ccw(struct ncplane* n);
228 void ncplane_pixelgeom(struct notcurses* n, int* restrict pxy, int* re‐
230 strict pxx, int* restrict celldimy, int* restrict celldimx, int* re‐
231 strict maxbmapy, int* restrict maxbmapx);
232 DESCRIPTION
234 Ncplanes are the fundamental drawing object of notcurses. All output
235 functions take a struct ncplane as an argument. They can be any size,
236 and placed anywhere. In addition to its framebuffer--a rectilinear ma‐
237 trix of nccells (see notcurses_cell(3))--an ncplane is defined by:
238 • a base nccell, used for any cell on the plane without a glyph,
240 • the egcpool backing its nccells,
242 • a current cursor location,
244 • a current style, foreground channel, and background channel,
246 • its geometry,
248 • a configured user pointer,
250 • position relative to the standard plane,
252 • the plane, if any, to which it is bound,
254 • the next plane bound by the plane to which it is bound,
256 • the head of the list of its bound planes,
258 • its resize methodology,
260 • whether a sprixel (see notcurses_visual(3)) is associated,
262 • its z-index, and
264 • a name (used only for debugging).
266 New planes can be created with ncplane_create. If a plane is bound to
268 another, x and y coordinates are relative to the plane to which it is
269 bound, and if this latter plane moves, all its bound planes move along
270 with it. When a plane is destroyed, all planes bound to it (directly
271 or transitively) are destroyed.
272 If the NCPLANE_OPTION_HORALIGNED flag is provided, x is interpreted as
274 an ncalign_e rather than an absolute position. If the NCPLANE_OP‐
275 TION_VERALIGNED flag is provided, y is interpreted as an ncalign_e
276 rather than an absolute postiion. Either way, all positions are rela‐
277 tive to the parent plane. ncplane_resize_realign should usually be
278 used together with these flags, so that the plane is automatically re‐
279 aligned upon a resize of its parent.
280 If the NCPLANE_OPTION_MARGINALIZED flag is provided, neither NC‐
282 PLANE_OPTION_HORALIGNED nor NCPLANE_OPTION_VERALIGNED may be provided,
283 and rows and cols must both be 0. y and x will be interpreted as top
284 and left margins. margin_b and margin_r will be interpreted as bottom
285 and right margins. The plane will take the maximum space possible sub‐
286 ject to its parent planes and these margins. The plane cannot become
287 smaller than 1x1 (the margins are best-effort). ncplane_re‐
288 size_marginalized should usually be used together with this flag, so
289 that the plane is automatically resized.
290 ncplane_reparent detaches the plane n from any plane to which it is
292 bound, and binds it to newparent. Its children are reparented to its
293 previous parent. The standard plane cannot be reparented. If newpar‐
294 ent is NULL, the plane becomes the root plane of a new, unrendered
295 stack. When ncplane_reparent_family is used, all planes bound to n
296 move along with it during a reparenting operation. See Piles below.
297 ncplane_destroy destroys a particular ncplane, after which it must not
299 be used again. notcurses_drop_planes destroys all ncplanes other than
300 the stdplane. Any references to such planes are, of course, invalidat‐
301 ed. It is undefined to destroy a plane concurrently with any other op‐
302 eration involving that plane, or any operation involving the z-axis.
303 It is an error for two threads to concurrently mutate a single ncplane.
305 So long as rendering is not taking place, however, multiple threads may
306 safely output to multiple ncplanes. So long as all threads are read‐
307 ers, multiple threads may work with a single ncplane. A reading func‐
308 tion is any which accepts a const struct ncplane.
309 ncplane_yx returns the coordinates of the specified plane's origin,
311 relative to the plane to which it is bound. Either or both of y and x
312 may be NULL. ncplane_y and ncplane_x allow a single component of this
313 location to be retrieved. ncplane_abs_yx returns the coordinates of
314 the specified plane's origin relative to its pile.
315 ncplane_translate translates coordinates expressed relative to the
317 plane src, and writes the coordinates of that cell relative to dst.
318 The cell need not intersect with dst, though this will yield coordi‐
319 nates which are invalid for writing or reading on dst. If dst is NULL,
320 it is taken to refer to the standard plane. ncplane_translate_abs
321 takes coordinates expressed relative to the standard plane, and returns
322 coordinates relative to dst, returning false if the coordinates are in‐
323 valid for dst.
324 ncplane_mergedown writes to dst the frame that would be rendered if on‐
326 ly src and dst existed on the z-axis, ad dst represented the entirety
327 of the rendering region. Only those cells where src intersects with
328 dst might see changes. It is an error to merge a plane onto itself.
329 ncplane_erase zeroes out every cell of the plane, dumps the egcpool,
331 and homes the cursor. The base cell is preserved, as are the active
332 attributes. ncplane_erase_region does the same for a subregion of the
333 plane. For the latter, supply 0 for ylen and/or xlen to erase through
334 that dimension, starting at the specified point.
335 When a plane is resized (whether by ncplane_resize, SIGWINCH, or any
337 other mechanism), a depth-first recursion is performed on its children.
338 Each child plane having a non-NULL resizecb will see that callback in‐
339 voked following resizing of its parent's plane. If it returns non-ze‐
340 ro, the resizing cascade terminates, returning non-zero. Otherwise,
341 resizing proceeds recursively.
342 Base cells
344 Each plane has a base cell, initialized to all zeroes. When rendering,
345 the cells of the plane are examined in turn. Each cell has three inde‐
346 pendent rendering elements--its EGC, its foreground channel, and its
347 background channel. Any default channel is replaced with the corre‐
348 sponding channel from that plane's base cell. ncplane_erase has no ef‐
349 fect on the base cell. Calling ncplane_erase on a plane whose base
350 cell is a purple 'A' results (for rendering purposes) in a plane made
351 up entirely of purple 'A's.
352 ncplane_set_base_cell uses the nccell c (which must be bound to the nc‐
354 plane ncp, and must be the first nccell of a multicolumn sequence) to
355 set the base cell. ncplane_set_base does the same with egc, stylemask,
356 and channels.
357 Piles
359 A single notcurses context is made up of one or more piles. A pile is
360 a set of one or more ncplanes, including the partial orderings made up
361 of their binding and z-axis pointers. A pile has a top and bottom nc‐
362 plane (this might be a single plane), and one or more root planes
363 (planes which are bound to themselves). Multiple threads can concur‐
364 rently operate on distinct piles, even changing one while rendering an‐
365 other.
366 Each plane is part of one and only one pile. By default, a plane is
368 part of the same pile containing that plane to which it is bound. If
369 ncpile_create is used in the place of ncplane_create, the returned
370 plane becomes the root plane, top, and bottom of a new pile. As a root
371 plane, it is bound to itself. A new pile can also be created by repar‐
372 enting a plane to itself, though if the plane is already a root plane,
373 this is a no-op.
374 When a plane is moved to a different pile (whether new or preexisting),
376 any planes which were bound to it are rebound to its previous parent.
377 If the plane was a root plane of some pile, any bound planes become
378 root planes. The new plane is placed immediately atop its new parent
379 on its new pile's z-axis. When ncplane_reparent_family() is used, all
380 planes bound to the reparented plane are moved along with it. Their
381 relative z-order is maintained.
382 Scrolling
384 All planes, including the standard plane, are created with scrolling
385 disabled. Control scrolling on a per-plane basis with nc‐
386 plane_set_scrolling. Attempting to print past the end of a line will
387 stop at the plane boundary, and indicate an error. On a plane 10 col‐
388 umns wide and two rows high, printing "0123456789" at the origin should
389 succeed, but printing "01234567890" will by default fail at the
390 eleventh character. In either case, the cursor will be left at loca‐
391 tion 0x10; it must be moved before further printing can take place. If
392 scrolling is enabled, the first row will be filled with 01234546789,
393 the second row will have 0 written to its first column, and the cursor
394 will end up at 1x1. Note that it is still an error to manually attempt
395 to move the cursor off-plane, or to specify off-plane output. Boxes do
396 not scroll; attempting to draw a 2x11 box on our 2x10 plane will result
397 in an error and no output. When scrolling is enabled, and output takes
398 place while the cursor is past the end of the last row, the first row
399 is discarded, all other rows are moved up, the last row is cleared, and
400 output begins at the beginning of the last row. This does not take
401 place until output is generated (i.e. it is possible to fill a plane
402 when scrolling is enabled).
403 Bitmaps
405 ncplane_pixelgeom retrieves pixel geometry details. pxy and pxx return
406 the size of the plane in pixels. celldimy and celldimx return the size
407 of a cell in pixels (these ought be the same across planes). maxbmapy
408 and maxbmapx describe the largest bitmap which can be displayed in the
409 plane. This function transitively calls notcurses_check_pixel_support,
410 possibly leading to terminal interrogation (see notcurses_capabili‐
411 ties(3) for why this may be undesirable). Any parameter (save n) may
412 be NULL.
413 When a plane is blitted to using ncvisual_render and NCBLIT_PIXEL (see
415 notcurses_visual(3)), it ceases to accept cell-based output. The
416 sprixel will remain associated until a new sprixel is blitted to the
417 plane, the plane is resized, the plane is erased, or the plane is de‐
418 stroyed. The base cell of a sprixelated plane has no effect; if the
419 sprixel is not even multiples of the cell geometry, the "excess plane"
420 is ignored during rendering.
421
423 ncplane_create and ncplane_dup return a new struct ncplane on success,
424 or NULL on failure.
425 ncplane_userptr returns the configured user pointer for the ncplane,
427 and cannot fail.
428 ncplane_below returns the plane below the specified ncplane. If the
430 provided plane is the bottommost plane, NULL is returned. It cannot
431 fail.
432 ncplane_set_scrolling returns true if scrolling was previously enabled,
434 and false otherwise.
435 ncpile_top and ncpile_bottom return the topmost and bottommost planes,
437 respectively, of the pile containing their argument. notcurses_top and
438 notcurses_bottom do the same for the standard pile.
439 ncplane_at_yx and ncplane_at_cursor return a heap-allocated copy of the
441 EGC at the relevant cell, or NULL if the cell is invalid. The caller
442 should free this result. ncplane_at_yx_cell and ncplane_at_cursor_cell
443 instead load these values into an nccell, which is invalidated if the
444 associated plane is destroyed. The caller should release this nccell
445 with nccell_release.
446 ncplane_as_rgba returns a heap-allocated array of uint32_t values, each
448 representing a single RGBA pixel, or NULL on failure.
449 ncplane_erase_region returns -1 if any of its parameters are negative,
451 or if they specify any area beyond the plane.
452 Functions returning int return 0 on success, and non-zero on error.
454 All other functions cannot fail (and return void).
456
458 ncplane_new is defined as a deprecated wrapper around ncplane_create.
459 It should not be used in new code.
460
462 ncplane_at_yx doesn't yet account for bitmap-based graphics (see
463 notcurses_visual). Whatever glyph-based contents existed on the plane
464 when the bitmap was blitted will continue to be returned.
465
467 notcurses(3), notcurses_capabilities(3), notcurses_cell(3), notcurs‐
468 es_output(3), notcurses_stdplane(3), notcurses_visual(3)
469
471 nick black <nickblack@linux.com>.
472 v2.3.1 notcurses_plane(3)