[planes] add NCPLANE_OPTION_VERALIGNED #1465

NEWS.md

@@ -7,7 +7,9 @@ rearrangements of Notcurses.
   * Added `notcurses_debug_caps()` to dump terminal properties, both those
     reported and those inferred, to a `FILE*`.
   * Added `NCOPTION_NO_CLEAR_BITMAPS` option for `notcurses_init()`.
-  * Added `NCVISUAL_OPTION_HORALIGNED` flag for `ncvisual_render()`.
+  * Added `NCVISUAL_OPTION_HORALIGNED` and `NCVISUAL_OPTION_VERALIGNED` flags
+    for `ncvisual_render()`.
+  * Added `NCPLANE_OPTION_VERALIGNED` flag for `ncplane_create()`.
   * Added the `nctabbed` widget for multiplexing planes data with navigational
     tabs. Courtesy Łukasz Drukała, in his first contribution.
   * Removed **notcurses_canpixel()**, which was obsoleted by

USAGE.md

@@ -716,7 +716,10 @@ When an `ncplane` is no longer needed, free it with
 `ncplane_destroy()`. To quickly reset the `ncplane`, use `ncplane_erase()`.
 
 ```c
+// Horizontal alignment relative to the parent plane. Use ncalign_e for 'x'.
 #define NCPLANE_OPTION_HORALIGNED 0x0001ull
+// Vertical alignment relative to the parent plane. Use ncalign_e for 'y'.
+#define NCPLANE_OPTION_VERALIGNED 0x0002ull
 
 typedef struct ncplane_options {
   int y;            // vertical placement relative to parent plane

doc/man/man3/notcurses_plane.3.md

@@ -12,6 +12,7 @@ notcurses_plane - operations on ncplanes
 
 ```c
 #define NCPLANE_OPTION_HORALIGNED 0x0001ull
+#define NCPLANE_OPTION_VERALIGNED 0x0002ull
 
 typedef struct ncplane_options {
   int y;            // vertical placement relative to parent plane
@@ -217,6 +218,12 @@ and if this latter plane moves, all its bound planes move along with it. When a
 plane is destroyed, all planes bound to it (directly or transitively) are
 destroyed.
 
+If the **NCPLANE_OPTION_HORALIGNED** flag is provided, ***x*** is interpreted
+as an **ncalign_e** rather than an absolute position. If the
+**NCPLANE_OPTION_VERALIGNED** flag is provided, ***y*** is interpreted as an
+**ncalign_e** rather than an absolute postiion. Either way, all positions
+are relative to the parent plane.
+
 **ncplane_reparent** detaches the plane ***n*** from any plane to which it is
 bound, and binds it to ***newparent***. Its children are reparented to its
 previous parent. The standard plane cannot be reparented. If ***newparent*** is

include/notcurses/notcurses.h

@@ -1123,8 +1123,10 @@ notcurses_term_dim_yx(const struct notcurses* n, int* RESTRICT rows, int* RESTRI
 API char* notcurses_at_yx(struct notcurses* nc, int yoff, int xoff,
                           uint16_t* stylemask, uint64_t* channels);
 
-// Horizontal alignment relative to the parent plane. Use 'align' instead of 'x'.
+// Horizontal alignment relative to the parent plane. Use ncalign_e for 'x'.
 #define NCPLANE_OPTION_HORALIGNED 0x0001ull
+// Vertical alignment relative to the parent plane. Use ncalign_e for 'y'.
+#define NCPLANE_OPTION_VERALIGNED 0x0002ull
 
 typedef struct ncplane_options {
   int y;            // vertical placement relative to parent plane

src/demo/xray.c

@@ -104,7 +104,7 @@ int xray_demo(struct notcurses* nc){
   }
   struct ncvisual_options vopts = {
     .n = n,
-    .scaling = NCSCALE_STRETCH,
+    .scaling = NCSCALE_SCALE_HIRES,
     .blitter = NCBLIT_PIXEL,
     .flags = NCVISUAL_OPTION_NODEGRADE, // to test for NCBLIT_PIXEL
   };