mirror of
https://github.com/dankamongmen/notcurses.git
synced 2024-11-18 03:25:55 +00:00
bring notcurses_cell.3 up to date #949
This commit is contained in:
nick black
parent
8b75769476
commit
f2d92b0f05
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user