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 NCALPHA_HIGHCONTRAST 0x30000000ull
28 #define NCALPHA_TRANSPARENT 0x20000000ull
29 #define NCALPHA_BLEND 0x10000000ull
30 #define NCALPHA_OPAQUE 0x00000000ull
31 void nccell_init(nccell* c);
33 int nccell_load(struct ncplane* n, nccell* c, const char* gcluster);
35 int nccell_prime(struct ncplane* n, nccell* c, const char* gcluster,
37 uint32_t stylemask, uint64_t channels);
38 int nccell_duplicate(struct ncplane* n, nccell* targ, const nccell* c);
40 void nccell_release(struct ncplane* n, nccell* c);
42 int nccell_cols(const nccell* c);
44 void nccell_styles_set(nccell* c, unsigned stylebits);
46 unsigned nccell_styles(const nccell* c);
48 bool nccellcmp(const struct ncplane* n1, const nccell* c1, const struct
50 ncplane* n2, const nccell* c2);
51 void nccell_on_styles(nccell* c, unsigned stylebits);
53 void nccell_off_styles(nccell* c, unsigned stylebits);
55 void nccell_set_fg_default(nccell* c);
57 void nccell_set_bg_default(nccell* c);
59 int nccell_set_fg_alpha(nccell* c, unsigned alpha);
61 int nccell_set_bg_alpha(nccell* c, unsigned alpha);
63 bool nccell_double_wide_p(const nccell* c);
65 const char* nccell_extended_gcluster(const struct ncplane* n, const nc‐
67 cell* c);
68 char* nccell_strdup(const struct ncplane* n, const nccell* c);
70 int nccell_load_char(struct ncplane* n, nccell* c, char ch);
72 int nccell_load_egc32(struct ncplane* n, nccell* c, uint32_t egc);
74 int nccell_load_ucs32(struct ncplane* n, nccell* c, uint32_t u);
76 char* nccell_extract(const struct ncplane* n, const nccell* c,
78 uint16_t* stylemask, uint64_t* channels);
79 uint64_t nccell_channels(const nccell* c);
81 uint32_t nccell_bchannel(const nccell* c);
83 uint32_t nccell_fchannel(const nccell* c);
85 uint64_t nccell_set_channels(nccell* c, uint64_t channels);
87 uint64_t nccell_set_bchannel(nccell* c, uint32_t channel);
89 uint64_t nccell_set_fchannel(nccell* c, uint32_t channel);
91 uint32_t nccell_fg_rgb(const nccell* c);
93 uint32_t nccell_bg_rgb(const nccell* c);
95 unsigned nccell_fg_alpha(const nccell* c);
97 unsigned nccell_bg_alpha(const nccell* c);
99 unsigned nccell_fg_rgb8(const nccell* c, unsigned* r, unsigned* g, un‐
101 signed* b);
102 unsigned nccell_bg_rgb8(const ncell* c, unsigned* r, unsigned* g, un‐
104 signed* b);
105 int nccell_set_fg_rgb8(nccell* c, unsigned r, unsigned g, unsigned b);
107 int nccell_set_bg_rgb8(nccell* c, unsigned r, unsigned g, unsigned b);
109 void nccell_set_fg_rgb8_clipped(nccell* c, int r, int g, int b);
111 void nccell_set_bg_rgb8_clipped(nccell* c, int r, int g, int b);
113 int nccell_set_fg_rgb(nccell* c, uint32_t channel);
115 int nccell_set_bg_rgb(nccell* c, uint32_t channel);
117 bool nccell_fg_default_p(const nccell* c);
119 bool nccell_bg_default_p(const nccell* c);
121 int nccell_set_fg_palindex(nccell* cl, unsigned idx);
123 int nccell_set_bg_palindex(nccell* cl, unsigned idx);
125 uint32_t nccell_fg_palindex(const nccell* cl);
127 uint32_t nccell_bg_palindex(const nccell* cl);
129 bool nccell_fg_palindex_p(const nccell* cl);
131 bool nccell_bg_palindex_p(const nccell* cl);
133 int ncstrwidth(const char* text);
135 int ncstrwidth_valid(const char* text, int* validbytes, int* valid‐
137 width);
138
140 Cells make up the framebuffer associated with each plane, with one cell
141 per addressable coordinate. You should not usually need to interact
142 directly with nccells.
143 Each nccell contains exactly one extended grapheme cluster. If the EGC
145 is encoded in UTF-8 with four or fewer bytes (all Unicode codepoints as
146 of Unicode 13 can be encoded in no more than four UTF-8 bytes), it is
147 encoded directly into the nccell's gcluster field, and no additional
148 storage is necessary. Otherwise, the EGC is stored as a nul-terminated
149 UTF-8 string in some backing egcpool. Egcpools are associated with nc‐
150 planes, so nccells must be considered associated with ncplanes. In‐
151 deed, ncplane_erase destroys the backing storage for all a plane's
152 cells, invalidating them. This association is formed at the time of
153 nccell_load, nccell_prime, or nccell_duplicate. All of these functions
154 first call nccell_release, as do nccell_load_egc32, nccell_load_char,
155 and nccell_load_ucs32. When done using a nccell entirely, call nc‐
156 cell_release. ncplane_destroy will free up the memory used by the nc‐
157 cell, but the backing egcpool has a maximum size of 16MiB, and failure
158 to release nccells can eventually block new output. Writing over an
159 ncplane's cells releases them automatically.
160 nccell_extended_gcluster provides a nul-terminated handle to the EGC.
162 This ought be considered invalidated by changes to the nccell or
163 egcpool. The handle is not heap-allocated; do not attempt to free(3)
164 it. A heap-allocated copy can be acquired with nccell_strdup.
165 ncstrwidth_valid returns the number of columns occupied by a valid
167 UTF-8 string, or -1 if an error is encountered. In either case, the
168 number of valid bytes and columns, respectively, consumed before error
169 into validbytes and validwidth (assuming them to not be NULL).
170 nccell_fg_palindex extracts the palette index from a cell's foreground
172 channel. The channel must be palette-indexed, or the return value is
173 meaningless. Verify palette indexing with nccell_fg_palindex_p. A
174 cell's foreground channel can be set to palette-indexed mode (and have
175 the index set) with nccell_set_fg_palindex. The index must be less
176 than NCPALETTESIZE. Replace fg with bg to operate on the background
177 channel.
178
180 nccell_load and similar functions return the number of bytes loaded
181 from the EGC, or -1 on failure. They can fail due to either an invalid
182 UTF-8 input, or the backing egcpool reaching its maximum size.
183 nccell_set_fg_rgb8 and similar functions will return -1 if provided in‐
185 valid inputs, and 0 otherwise.
186 nccellcmp returns a negative integer, 0, or a positive integer if c1 is
188 less than, equal to, or more than c2, respectively.
189 nccell_extended_gcluster returns NULL if called on a sprixel (see
191 notcurses_visual(3).
192 nccell_cols returns the number of columns occupied by c, according to
194 wcwidth(3)*. ncstrwidth is an equivalent for strings. ncstr‐
195 width_valid returns the same value as ncstrwidth.
196
198 cell was renamed to nccell in Notcurses 2.2.0, so as not to bleed such
199 a common term into the (single, global) C namespace. cell will be re‐
200 tained as an alias until Notcurses 3.0. Likewise, many functions pre‐
201 fixed with cell have been renamed to start with nccell.
202
204 notcurses(3), notcurses_channels(3), notcurses_plane(3), notcurses_out‐
205 put(3), notcurses_visual(3), wcwidth(3), utf8(7)
206
208 nick black <nickblack@linux.com>.
209 v3.0.8 notcurses_cell(3)