document changes to ncplane_at_yx()

NEWS.md

@@ -8,6 +8,14 @@ rearrangements of Notcurses.
     only if its `ncinput` argument has no modifiers active.
   * Added `notcurses_cursor_yx()` to get the current location of the cursor.
   * Added `ncdirect_supported_styles()`.
+  * `ncplane_at_yx()` now properly integrates the plane's base cell when
+    appropriate, and thus represents the cell as it will be used during
+    rendering. This change cascades, affecting `ncplane_at_yx_cell()`,
+    `ncplane_contents()`, and `ncplane_as_rgba()`.
+  * `ncplane_at_yx()` now returns the EGC when called on any column of a
+    wide glyph. `ncplane_at_yx_cell()` continues to duplicate the exact
+    `nccell`, and can thus continue to be used to distinguish between primary
+    and secondary columns of a wide glyph.
 
 * 2.3.1 (2021-05-18)
   * Sprixels no longer interact with their associated plane's framebuffer. This

USAGE.md

@@ -1044,13 +1044,20 @@ char* ncplane_at_cursor(struct ncplane* n, uint16_t* styles, uint64_t* channels)
 int ncplane_at_cursor_cell(struct ncplane* n, nccell* c);
 
 // Retrieve the current contents of the specified cell. The EGC is returned, or
-// NULL on error. This EGC must be free()d by the caller. The styles and
-// channels are written to 'styles' and 'channels', respectively.
+// NULL on error. This EGC must be free()d by the caller. The stylemask and
+// channels are written to 'stylemask' and 'channels', respectively. The return
+// represents how the cell will be used during rendering, and thus integrates
+// any base cell where appropriate. If called upon the secondary columns of a
+// wide glyph, the EGC will be returned (i.e. this function does not distinguish
+// between the primary and secondary columns of a wide glyph).
 char* ncplane_at_yx(const struct ncplane* n, int y, int x,
-                    uint16_t* styles, uint64_t* channels);
+                    uint16_t* stylemask, uint64_t* channels);
 
 // Retrieve the current contents of the specified cell into 'c'. This cell is
-// invalidated if the associated plane is destroyed.
+// invalidated if the associated plane is destroyed. Returns the number of
+// bytes in the EGC, or -1 on error. Unlike ncplane_at_yx(), when called upon
+// the secondary columns of a wide glyph, the return can be distinguished from
+// the primary column (nccell_wide_right_p(c) will return true).
 int ncplane_at_yx_cell(struct ncplane* n, int y, int x, nccell* c);
 
 // Create an RGBA flat array from the selected region of the ncplane 'nc'.

doc/man/man3/notcurses_plane.3.md

@@ -375,6 +375,16 @@ is resized, the plane is erased, or the plane is destroyed. The base cell of a
 sprixelated plane has no effect; if the sprixel is not even multiples of the
 cell geometry, the "excess plane" is ignored during rendering.
 
+**ncplane_at_yx** and **ncplane_at_yx_cell** retrieve the contents of the plane
+at the specified coordinate. The content is returned as it will be used during
+rendering, and thus integrates any base cell as appropriate. If called on the
+secondary columns of a wide glyph, **ncplane_at_yx** returns the EGC, and thus
+cannot be used to distinguish between primary and secondary columns.
+**ncplane_at_yx_cell**, however, preserves this information: retrieving a
+secondary column of a wide glyph with **ncplane_at_yx_cell** will fill in
+the **nccell** argument such that **nccell_extended_gcluster(3)** returns an
+empty string, and **nccell_wide_right_p(3)** returns **true**.
+
 # RETURN VALUES
 
 **ncplane_create** and **ncplane_dup** return a new **struct ncplane** on
@@ -394,10 +404,11 @@ respectively, of the pile containing their argument. **notcurses_top** and
 **notcurses_bottom** do the same for the standard pile.
 
 **ncplane_at_yx** and **ncplane_at_cursor** return a heap-allocated copy of the
-EGC at the relevant cell, or **NULL** if the cell is invalid. The caller should free
-this result. **ncplane_at_yx_cell** and **ncplane_at_cursor_cell** instead load
-these values into an **nccell**, which is invalidated if the associated plane is
-destroyed. The caller should release this **nccell** with **nccell_release**.
+EGC at the relevant cell, or **NULL** if the cell is invalid. The caller should
+free this result. **ncplane_at_yx_cell** and **ncplane_at_cursor_cell** instead
+load these values into an **nccell**, which is invalidated if the associated
+plane is destroyed. The caller should release this **nccell** with
+**nccell_release**.
 
 **ncplane_as_rgba** returns a heap-allocated array of **uint32_t** values,
 each representing a single RGBA pixel, or **NULL** on failure.

include/notcurses/notcurses.h

@@ -653,7 +653,7 @@ API int nccell_load(struct ncplane* n, nccell* c, const char* gcluster);
 // nccell_load(), plus blast the styling with 'attr' and 'channels'.
 static inline int
 nccell_prime(struct ncplane* n, nccell* c, const char* gcluster,
-           uint32_t stylemask, uint64_t channels){
+             uint32_t stylemask, uint64_t channels){
   c->stylemask = stylemask;
   c->channels = channels;
   int ret = nccell_load(n, c, gcluster);
@@ -1467,13 +1467,19 @@ API int ncplane_at_cursor_cell(struct ncplane* n, nccell* c);
 
 // Retrieve the current contents of the specified cell. The EGC is returned, or
 // NULL on error. This EGC must be free()d by the caller. The stylemask and
-// channels are written to 'stylemask' and 'channels', respectively.
+// channels are written to 'stylemask' and 'channels', respectively. The return
+// represents how the cell will be used during rendering, and thus integrates
+// any base cell where appropriate. If called upon the secondary columns of a
+// wide glyph, the EGC will be returned (i.e. this function does not distinguish
+// between the primary and secondary columns of a wide glyph).
 API char* ncplane_at_yx(const struct ncplane* n, int y, int x,
                         uint16_t* stylemask, uint64_t* channels);
 
 // Retrieve the current contents of the specified cell into 'c'. This cell is
 // invalidated if the associated plane is destroyed. Returns the number of
-// bytes in the EGC, or -1 on error.
+// bytes in the EGC, or -1 on error. Unlike ncplane_at_yx(), when called upon
+// the secondary columns of a wide glyph, the return can be distinguished from
+// the primary column (nccell_wide_right_p(c) will return true).
 API int ncplane_at_yx_cell(struct ncplane* n, int y, int x, nccell* c);
 
 // Create a flat string from the EGCs of the selected region of the ncplane