From f2d92b0f050703c06c2b6aef80c15251498f9bf8 Mon Sep 17 00:00:00 2001 From: nick black Date: Mon, 24 Aug 2020 15:15:27 -0400 Subject: [PATCH] bring notcurses_cell.3 up to date #949 --- doc/man/man3/notcurses_cell.3.md | 37 ++++++---- doc/man/man3/notcurses_channels.3.md | 103 +++++++++++---------------- 2 files changed, 63 insertions(+), 77 deletions(-) diff --git a/doc/man/man3/notcurses_cell.3.md b/doc/man/man3/notcurses_cell.3.md index 871d8b0f7..069d47b11 100644 --- a/doc/man/man3/notcurses_cell.3.md +++ b/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 diff --git a/doc/man/man3/notcurses_channels.3.md b/doc/man/man3/notcurses_channels.3.md index 9f1d21de6..1df70a511 100644 --- a/doc/man/man3/notcurses_channels.3.md +++ b/doc/man/man3/notcurses_channels.3.md @@ -10,99 +10,76 @@ notcurses_channels - operations on notcurses channels **#include ** -**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