bring notcurses_cell.3 up to date #949

doc/man/man3/notcurses_cell.3.md

@@ -72,8 +72,12 @@ typedef struct cell {
 
 **const char* cell_extended_gcluster(const struct ncplane* n, const cell* c);**
 
+**char* cell_strdup(const struct ncplane* n, const cell* c);**
+
 **int cell_load_simple(struct ncplane* n, cell* c, char ch);**
 
+**char* cell_extract(const struct ncplane* n, const cell* c, uint16_t* stylemask, uint64_t* channels);**
+
 **unsigned cell_bchannel(const cell* cl);**
 
 **unsigned cell_fchannel(const cell* cl);**
@@ -116,20 +120,25 @@ Cells make up the framebuffer associated with each plane, with one cell per
 addressable coordinate. You should not usually need to interact directly
 with cells.
 
-Each **cell** contains exactly one extended grapheme cluster. If the EGC happens
-to be a single ASCII character, i.e. a single character with a value less than
-128, it is encoded directly into the **cell**'s **gcluster** field, and no
-additional storage is necessary. In this case, **cell_simple_p()** is **true**.
-Otherwise, the EGC is stored as a UTF-8 string in some backing egcpool. Egcpools
-are associated with **ncplane**s, so **cell**s must be considered associated
-with **ncplane**s. Indeed, **ncplane_erase()** destroys the backing storage for
-all a plane's cells, invalidating them. This association is formed at the time
-of **cell_load()**, **cell_prime()**, or **cell_duplicate()**. All of these
-functions first call **cell_release()**, as does **cell_load_simple()**. When
-done using a **cell** entirely, call **cell_release()**. **ncplane_destroy()**
-will free up the memory used by the **cell**, but the backing egcpool has a
-maximum size of 32MiB, and failure to release **cell**s can eventually block new
-output.
+Each **cell** contains exactly one extended grapheme cluster. If the EGC
+is encoded in UTF-8 with four or fewer bytes (all Unicode codepoints as of
+Unicode 13 can be encoded in no more than four UTF-8 bytes), it is encoded
+directly into the **cell**'s **gcluster** field, and no additional storage
+is necessary. Otherwise, the EGC is stored as a nul-terminated UTF-8 string in
+some backing egcpool. Egcpools are associated with **ncplane**s, so **cell**s
+must be considered associated with **ncplane**s. Indeed, **ncplane_erase()**
+destroys the backing storage for all a plane's cells, invalidating them. This
+association is formed at the time of **cell_load()**, **cell_prime()**, or
+**cell_duplicate()**. All of these functions first call **cell_release()**, as
+does **cell_load_simple()**. When done using a **cell** entirely, call
+**cell_release()**. **ncplane_destroy()** will free up the memory used by the
+**cell**, but the backing egcpool has a maximum size of 16MiB, and failure to
+release **cell**s can eventually block new output.
+
+**cell_extended_gcluster** provides a nul-terminated handle to the EGC. This
+ought be considered invalidated by changes to the **cell** or **egcpool**.
+The handle is **not** heap-allocated; do **not** attempt to **free(3)** it.
+A heap-allocated copy can be acquired with **cell_strdup**.
 
 # RETURN VALUES
 

doc/man/man3/notcurses_channels.3.md

@@ -10,99 +10,76 @@ notcurses_channels - operations on notcurses channels
 
 **#include <notcurses/notcurses.h>**
 
-**static inline unsigned
-channel_r(unsigned channel);**
+```c
+#define CHANNELS_RGB_INITIALIZER(fr, fg, fb, br, bg, bb) \
+  (((((uint64_t)(fr) << 16u) + ((uint64_t)(fg) << 8u) + (uint64_t)(fb)) << 32ull) + \
+   (((br) << 16u) + ((bg) << 8u) + (bb)) + CELL_BGDEFAULT_MASK + CELL_FGDEFAULT_MASK)
 
-**static inline unsigned
-channel_g(unsigned channel);**
+#define CHANNEL_RGB_INITIALIZER(r, g, b) \
+  (((uint32_t)r << 16u) + ((uint32_t)g << 8u) + (b) + CELL_BGDEFAULT_MASK)
+```
 
-**static inline unsigned
-channel_b(unsigned channel);**
+**unsigned channel_r(unsigned channel);**
 
-**static inline unsigned
-channel_rgb(unsigned channel, unsigned* restrict r, unsigned* restrict g,
-                unsigned* restrict b);**
+**unsigned channel_g(unsigned channel);**
 
-**static inline int
-channel_set_rgb(unsigned* channel, int r, int g, int b);**
+**unsigned channel_b(unsigned channel);**
 
-**static inline int
-channel_set(unsigned* channel, unsigned rgb);**
+**unsigned channel_rgb(unsigned channel, unsigned* restrict r, unsigned* restrict g, unsigned* restrict b);**
 
-**static inline unsigned
-channel_alpha(unsigned channel);**
+**int channel_set_rgb(unsigned* channel, int r, int g, int b);**
 
-**static inline int
-channel_set_alpha(unsigned* channel, int alpha);**
+**int channel_set(unsigned* channel, unsigned rgb);**
 
-**static inline bool
-channel_default_p(unsigned channel);**
+**unsigned channel_alpha(unsigned channel);**
 
-**static inline unsigned
-channel_set_default(unsigned* channel);**
+**int channel_set_alpha(unsigned* channel, int alpha);**
 
-**static inline unsigned
-channels_bchannel(uint64_t channels);**
+**bool channel_default_p(unsigned channel);**
 
-**static inline unsigned
-channels_fchannel(uint64_t channels);**
+**unsigned channel_set_default(unsigned* channel);**
 
-**static inline uint64_t
-channels_set_bchannel(uint64_t* channels, uint32_t channel);**
+**unsigned channels_bchannel(uint64_t channels);**
 
-**static inline uint64_t
-channels_set_fchannel(uint64_t* channels, uint32_t channel);**
+**unsigned channels_fchannel(uint64_t channels);**
 
-**static inline unsigned
-channels_fg(uint64_t channels);**
+**uint64_t channels_set_bchannel(uint64_t* channels, uint32_t channel);**
 
-**static inline unsigned
-channels_bg(uint64_t channels);**
+**uint64_t channels_set_fchannel(uint64_t* channels, uint32_t channel);**
 
-**static inline unsigned
-channels_fg_alpha(uint64_t channels);**
+**unsigned channels_fg(uint64_t channels);**
 
-**static inline unsigned
-channels_bg_alpha(uint64_t channels);**
+**unsigned channels_bg(uint64_t channels);**
 
-**static inline unsigned
-channels_fg_rgb(uint64_t channels, unsigned* r, unsigned* g, unsigned* b);**
+**unsigned channels_fg_alpha(uint64_t channels);**
 
-**static inline unsigned
-channels_bg_rgb(uint64_t channels, unsigned* r, unsigned* g, unsigned* b);**
+**unsigned channels_bg_alpha(uint64_t channels);**
 
-**static inline int
-channels_set_fg_rgb(uint64_t* channels, int r, int g, int b);**
+**unsigned channels_fg_rgb(uint64_t channels, unsigned* r, unsigned* g, unsigned* b);**
 
-**static inline int
-channels_set_bg_rgb(uint64_t* channels, int r, int g, int b);**
+**unsigned channels_bg_rgb(uint64_t channels, unsigned* r, unsigned* g, unsigned* b);**
 
-**static inline int
-channels_set_fg(uint64_t* channels, unsigned rgb);**
+**int channels_set_fg_rgb(uint64_t* channels, int r, int g, int b);**
 
-**static inline int
-channels_set_bg(uint64_t* channels, unsigned rgb);**
+**int channels_set_bg_rgb(uint64_t* channels, int r, int g, int b);**
 
-**static inline int
-channels_set_fg_alpha(uint64_t* channels, int alpha);**
+**int channels_set_fg(uint64_t* channels, unsigned rgb);**
 
-**static inline int
-channels_set_bg_alpha(uint64_t* channels, int alpha);**
+**int channels_set_bg(uint64_t* channels, unsigned rgb);**
 
-**static inline bool
-channels_fg_default_p(uint64_t channels);**
+**int channels_set_fg_alpha(uint64_t* channels, int alpha);**
 
-**static inline bool
-channels_bg_default_p(uint64_t channels);**
+**int channels_set_bg_alpha(uint64_t* channels, int alpha);**
 
-**static inline uint64_t
-channels_set_fg_default(uint64_t* channels);**
+**bool channels_fg_default_p(uint64_t channels);**
 
-**static inline uint64_t
-channels_set_bg_default(uint64_t* channels);**
+**bool channels_bg_default_p(uint64_t channels);**
 
-**static inline unsigned
-channels_blend(unsigned c1, unsigned c2, unsigned blends);**
+**uint64_t channels_set_fg_default(uint64_t* channels);**
+
+**uint64_t channels_set_bg_default(uint64_t* channels);**
+
+**unsigned channels_blend(unsigned c1, unsigned c2, unsigned blends);**
 
 # DESCRIPTION