From e42a76a2d2e5c0c201b0edc6ca3de204713a24b8 Mon Sep 17 00:00:00 2001 From: nick black Date: Mon, 4 Oct 2021 01:01:35 -0400 Subject: [PATCH] Remove and replace ncplane_boundlist() The function ncplane_boundlist() was poorly-considered, and ought never have existed. Remove all traces of it. Add the new functions ncplane_move_family_top() and ncplane_move_family_bottom(). Replace the ncplane_boundlist() code in notcurses-demo with a call to ncplane_move_family_top(). We'll also want ncplane_move_family_above() and ncplane_move_family_below(), but they're not yet here. Document all z-axis movement functions; they were lacking documentation before #2232. --- USAGE.md | 11 ++++++++--- doc/man/man3/notcurses_plane.3.md | 24 ++++++++++++++++++++++-- include/notcurses/notcurses.h | 26 ++++++++++++++++++-------- src/demo/hud.c | 6 +----- src/lib/notcurses.c | 14 ++++++++++---- 5 files changed, 59 insertions(+), 22 deletions(-) diff --git a/USAGE.md b/USAGE.md index 640b41ecb..9a83dbc5e 100644 --- a/USAGE.md +++ b/USAGE.md @@ -871,9 +871,6 @@ int ncplane_resize_realign(struct ncplane* n); struct ncplane* ncplane_parent(struct ncplane* n); const struct ncplane* ncplane_parent_const(const struct ncplane* n); -// Get the head of the list of planes bound to 'n'. -struct ncplane* ncplane_boundlist(struct ncplane* n); - // Duplicate an existing ncplane. The new plane will have the same geometry, // will duplicate all content, and will start with the same rendering state. struct ncplane* ncplane_dup(struct ncplane* n, void* opaque); @@ -1102,6 +1099,14 @@ int ncplane_base(struct ncplane* ncp, nccell* c); void ncplane_move_top(struct ncplane* n); void ncplane_move_bottom(struct ncplane* n); +// Splice ncplane 'n' and its bound planes out of the z-buffer, and reinsert +// them at the top or bottom. Relative order will be maintained between the +// reinserted planes. For a plane E bound to C, with z-ordering A B C D E, +// moving the C family to the top results in C E A B D, while moving it to +// the bottom results in A B D C E. +void ncplane_move_family_top(struct ncplane* n); +void ncplane_move_family_bottom(struct ncplane* n); + // Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'. // Returns non-zero if 'n' is already in the desired location. 'n' and // 'below' must not be the same plane. diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index 5037b00fc..fa8a92be9 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/doc/man/man3/notcurses_plane.3.md @@ -99,9 +99,13 @@ typedef struct ncplane_options { **int ncplane_move_bottom(struct ncplane* ***n***);** -**int ncplane_move_above(struct ncplane* restrict ***n***, struct ncplane* restrict ***above***);** +**void ncplane_move_family_top(struct ncplane* ***n***);** -**int ncplane_move_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***below***);** +**void ncplane_move_family_bottom(struct ncplane* ***n***);** + +**int ncplane_move_above(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);** + +**int ncplane_move_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);** **struct ncplane* ncplane_below(struct ncplane* ***n***);** @@ -333,6 +337,22 @@ invoked following resizing of its parent's plane. If it returns non-zero, the resizing cascade terminates, returning non-zero. Otherwise, resizing proceeds recursively. +**ncplane_move_top** and **ncplane_move_bottom** extract their argument +***n*** from the z-axis, and reinsert it at the top or bottom, respectively, +of its pile. These functions are both O(1). **ncplane_move_family_top** and +**ncplane_move_family_bottom** do the same, and move any bound descendants +along with the plane. Ordering among the plane and its descendants will be +maintained. For example, assume a pile with A at the top of its z-axis, +followed by B, C, D, and E, where E is bound to C. Calling +**ncplane_move_family_top** on C will result in the order CEABD. Calling +**ncplane_move_family_bottom** on C will result in the order ABDCE. Calling +**ncplane_move_family_top** or **ncplane_move_top** on E will result in EABCD. +Calling **ncplane_move_family_bottom** on E is a no-op. These two functions +are O(N) on the number of planes in the pile. + +**ncplane_move_above** and **ncplane_move_below** move the argument ***n*** +above or below, respectively, the argument ***targ***. Both operate in O(1). + ## Base cells Each plane has a base cell, initialized to all zeroes. When rendering, the diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index c7713665e..7ddbab0f5 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -1618,10 +1618,6 @@ API struct ncplane* ncplane_parent(struct ncplane* n) API const struct ncplane* ncplane_parent_const(const struct ncplane* n) __attribute__ ((nonnull (1))); -// Get the head of the list of planes bound to 'n'. -API struct ncplane* ncplane_boundlist(struct ncplane* n) - __attribute__ ((nonnull (1))); - // Return non-zero iff 'n' is a proper descendent of 'ancestor'. static inline int ncplane_descendant_p(const struct ncplane* n, const struct ncplane* ancestor){ @@ -1634,20 +1630,34 @@ ncplane_descendant_p(const struct ncplane* n, const struct ncplane* ancestor){ } // Splice ncplane 'n' out of the z-buffer, and reinsert it at the top or bottom. -API void ncplane_move_top(struct ncplane* n); -API void ncplane_move_bottom(struct ncplane* n); +API void ncplane_move_top(struct ncplane* n) + __attribute__ ((nonnull (1))); +API void ncplane_move_bottom(struct ncplane* n) + __attribute__ ((nonnull (1))); + +// Splice ncplane 'n' and its bound planes out of the z-buffer, and reinsert +// them at the top or bottom. Relative order will be maintained between the +// reinserted planes. For a plane E bound to C, with z-ordering A B C D E, +// moving the C family to the top results in C E A B D, while moving it to +// the bottom results in A B D C E. +API void ncplane_move_family_top(struct ncplane* n) + __attribute__ ((nonnull (1))); +API void ncplane_move_family_bottom(struct ncplane* n) + __attribute__ ((nonnull (1))); // Splice ncplane 'n' out of the z-buffer, and reinsert it above 'above'. // Returns non-zero if 'n' is already in the desired location. 'n' and // 'above' must not be the same plane. API int ncplane_move_above(struct ncplane* RESTRICT n, - struct ncplane* RESTRICT above); + struct ncplane* RESTRICT above) + __attribute__ ((nonnull (1, 2))); // Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'. // Returns non-zero if 'n' is already in the desired location. 'n' and // 'below' must not be the same plane. API int ncplane_move_below(struct ncplane* RESTRICT n, - struct ncplane* RESTRICT below); + struct ncplane* RESTRICT below) + __attribute__ ((nonnull (1, 2))); // Return the plane below this one, or NULL if this is at the bottom. API struct ncplane* ncplane_below(struct ncplane* n) diff --git a/src/demo/hud.c b/src/demo/hud.c index f48e7983d..b7969b1d2 100644 --- a/src/demo/hud.c +++ b/src/demo/hud.c @@ -582,11 +582,7 @@ int demo_render(struct notcurses* nc){ clock_gettime(CLOCK_MONOTONIC, &ts); if(plot){ if(!plot_hidden){ - struct ncplane* pixelp = ncplane_boundlist(ncuplot_plane(plot)); - if(pixelp){ - ncplane_move_top(pixelp); - } - ncplane_move_top(ncuplot_plane(plot)); + ncplane_move_family_top(ncuplot_plane(plot)); } uint64_t ns = (timespec_to_ns(&ts) - plottimestart) / (NANOSECS_IN_SEC / FPSHZ); ncuplot_add_sample(plot, ns, 1); diff --git a/src/lib/notcurses.c b/src/lib/notcurses.c index 98ef20c9c..9fa0cbcc9 100644 --- a/src/lib/notcurses.c +++ b/src/lib/notcurses.c @@ -1444,6 +1444,16 @@ void ncplane_move_bottom(ncplane* n){ } } +void ncplane_move_family_top(ncplane* n){ + ncplane_move_top(n); + // FIXME walk above and below, moving descendants +} + +void ncplane_move_family_bottom(ncplane* n){ + ncplane_move_bottom(n); + // FIXME walk above and below, moving descendants +} + void ncplane_cursor_yx(const ncplane* n, int* y, int* x){ if(y){ *y = n->y; @@ -2356,10 +2366,6 @@ const ncplane* ncplane_parent_const(const ncplane* n){ return n->boundto; } -ncplane* ncplane_boundlist(ncplane* n){ - return n->blist; -} - void ncplane_set_resizecb(ncplane* n, int(*resizecb)(ncplane*)){ n->resizecb = resizecb; }