1notcurses_cell(3) notcurses_cell(3)
2
6 notcurses_cell - operations on nccell objects
7
9 #include <notcurses/notcurses.h>
10 // See DESCRIPTION below for information on EGC encoding
12 typedef struct nccell {
13 uint32_t gcluster; // 4B → 4B
14 uint8_t gcluster_backstop; // 1B → 5B (8 bits of zero)
15 uint8_t width; // 1B → 6B (8 bits of column width)
16 uint16_t stylemask; // 2B → 8B (16 bits of NCSTYLE_* attributes)
17 uint64_t channels;
18 } nccell;
19 #define CELL_TRIVIAL_INITIALIZER \
21 { .gcluster = '\0', .stylemask = 0, .channels = 0, }
22 #define CELL_SIMPLE_INITIALIZER(c) \
23 { .gcluster = (c), .stylemask = 0, .channels = 0, }
24 #define CELL_INITIALIZER(c, s, chan) \
25 { .gcluster = (c), .stylemask = (s), .channels = (chan), }
26 #define CELL_BGDEFAULT_MASK 0x0000000040000000ull
28 #define CELL_FGDEFAULT_MASK (CELL_BGDEFAULT_MASK << 32u)
29 #define CELL_BG_RGB_MASK 0x0000000000ffffffull
30 #define CELL_FG_RGB_MASK (CELL_BG_MASK << 32u)
31 #define CELL_BG_PALETTE 0x0000000008000000ull
32 #define CELL_FG_PALETTE (CELL_BG_PALETTE << 32u)
33 #define CHANNEL_ALPHA_MASK 0x30000000ull
34 #define CELL_ALPHA_HIGHCONTRAST 0x30000000ull
35 #define CELL_ALPHA_TRANSPARENT 0x20000000ull
36 #define CELL_ALPHA_BLEND 0x10000000ull
37 #define CELL_ALPHA_OPAQUE 0x00000000ull
38 void cell_init(nccell* c);
40 int cell_load(struct ncplane* n, nccell* c, const char* gcluster);
42 int cell_prime(struct ncplane* n, nccell* c, const char* gcluster,
44 uint32_t stylemask, uint64_t channels);
45 int cell_duplicate(struct ncplane* n, nccell* targ, const nccell* c);
47 void cell_release(struct ncplane* n, nccell* c);
49 void cell_styles_set(nccell* c, unsigned stylebits);
51 unsigned cell_styles(const nccell* c);
53 void cell_on_styles(nccell* c, unsigned stylebits);
55 void cell_off_styles(nccell* c, unsigned stylebits);
57 void cell_set_fg_default(nccell* c);
59 void cell_set_bg_default(nccell* c);
61 int cell_set_fg_alpha(nccell* c, unsigned alpha);
63 int cell_set_bg_alpha(nccell* c, unsigned alpha);
65 bool cell_double_wide_p(const nccell* c);
67 const char* cell_extended_gcluster(const struct ncplane* n, const nc‐
69 cell* c);
70 char* cell_strdup(const struct ncplane* n, const nccell* c);
72 int cell_load_char(struct ncplane* n, nccell* c, char ch);
74 int cell_load_egc32(struct ncplane* n, nccell* c, uint32_t egc);
76 char* cell_extract(const struct ncplane* n, const nccell* c, uint16_t*
78 stylemask, uint64_t* channels);
79 uint32_t cell_bchannel(const nccell* c);
81 uint32_t cell_fchannel(const nccell* c);
83 uint64_t cell_set_bchannel(nccell* c, uint32_t channel);
85 uint64_t cell_set_fchannel(nccell* c, uint32_t channel);
87 uint32_t cell_fg_rgb(const nccell* c);
89 uint32_t cell_bg_rgb(const nccell* c);
91 unsigned cell_fg_alpha(const nccell* c);
93 unsigned cell_bg_alpha(const nccell* c);
95 unsigned cell_fg_rgb8(const nccell* c, unsigned* r, unsigned* g, un‐
97 signed* b);
98 unsigned cell_bg_rgb8(const ncell* c, unsigned* r, unsigned* g, un‐
100 signed* b);
101 int cell_set_fg_rgb8(nccell* c, int r, int g, int b);
103 int cell_set_bg_rgb8(nccell* c, int r, int g, int b);
105 void cell_set_fg_rgb8_clipped(nccell* c, int r, int g, int b);
107 void cell_set_bg_rgb8_clipped(nccell* c, int r, int g, int b);
109 int cell_set_fg_rgb(nccell* c, uint32_t channel);
111 int cell_set_bg_rgb(nccell* c, uint32_t channel);
113 bool cell_fg_default_p(const nccell* c);
115 bool cell_bg_default_p(const nccell* c);
117 int ncstrwidth(const char* text);
119
121 Cells make up the framebuffer associated with each plane, with one cell
122 per addressable coordinate. You should not usually need to interact
123 directly with nccells.
124 Each nccell contains exactly one extended grapheme cluster. If the EGC
126 is encoded in UTF-8 with four or fewer bytes (all Unicode codepoints as
127 of Unicode 13 can be encoded in no more than four UTF-8 bytes), it is
128 encoded directly into the nccell's gcluster field, and no additional
129 storage is necessary. Otherwise, the EGC is stored as a nul-terminated
130 UTF-8 string in some backing egcpool. Egcpools are associated with nc‐
131 planes, so nccells must be considered associated with ncplanes. In‐
132 deed, ncplane_erase() destroys the backing storage for all a plane's
133 cells, invalidating them. This association is formed at the time of
134 cell_load(), cell_prime(), or cell_duplicate(). All of these functions
135 first call cell_release(), as does cell_load_simple(). When done using
136 a nccell entirely, call cell_release(). ncplane_destroy() will free up
137 the memory used by the nccell, but the backing egcpool has a maximum
138 size of 16MiB, and failure to release nccells can eventually block new
139 output.
140 cell_extended_gcluster provides a nul-terminated handle to the EGC.
142 This ought be considered invalidated by changes to the nccell or
143 egcpool. The handle is not heap-allocated; do not attempt to free(3)
144 it. A heap-allocated copy can be acquired with cell_strdup.
145
147 cell_load() and similar functions return the number of bytes loaded
148 from the EGC, or -1 on failure. They can fail due to either an invalid
149 UTF-8 input, or the backing egcpool reaching its maximum size.
150 cell_set_fg_rgb8() and similar functions will return -1 if provided in‐
152 valid inputs, and 0 otherwise.
153
155 cell was renamed to nccell in Notcurses 2.2.0, so as not to bleed such
156 a common term into the (single, global) C namespace. cell will be re‐
157 tained as an alias until Notcurses 3.0.
158
160 notcurses(3), notcurses_channels(3), notcurses_plane(3), notcurses_out‐
161 put(3)
162
164 nick black <nickblack@linux.com>.
165 v2.2.3 notcurses_cell(3)