From d2b5ffc15a2901817d6360330f8f8aea69b85658 Mon Sep 17 00:00:00 2001 From: nick black Date: Sat, 29 May 2021 17:01:23 -0400 Subject: [PATCH] document changes to ncplane_at_yx() --- NEWS.md | 8 ++++++++ USAGE.md | 15 +++++++++++---- doc/man/man3/notcurses_plane.3.md | 19 +++++++++++++++---- include/notcurses/notcurses.h | 12 +++++++++--- 4 files changed, 43 insertions(+), 11 deletions(-) diff --git a/NEWS.md b/NEWS.md index 1947f48519..55c8cb843f 100644 --- a/NEWS.md +++ b/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 diff --git a/USAGE.md b/USAGE.md index 8f5b1c91c1..dd6d7741a5 100644 --- a/USAGE.md +++ b/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'. diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index f2979a7a92..8b3ac747df 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/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. diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index cc8114360a..1eec969d26 100644 --- a/include/notcurses/notcurses.h +++ b/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