notcurses_cell(3)

1notcurses_cell(3)                                            notcurses_cell(3)
2
3
4

NAME

6       notcurses_cell - operations on nccell objects
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              // 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
20              #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
27              #define NCALPHA_HIGHCONTRAST  0x30000000ull
28              #define NCALPHA_TRANSPARENT   0x20000000ull
29              #define NCALPHA_BLEND         0x10000000ull
30              #define NCALPHA_OPAQUE        0x00000000ull
31
32       void nccell_init(nccell* c);
33
34       int nccell_load(struct ncplane* n, nccell* c, const char* gcluster);
35
36       int  nccell_prime(struct  ncplane*  n, nccell* c, const char* gcluster,
37       uint32_t stylemask, uint64_t channels);
38
39       int nccell_duplicate(struct ncplane* n, nccell* targ, const nccell* c);
40
41       void nccell_release(struct ncplane* n, nccell* c);
42
43       int nccell_cols(const nccell* c);
44
45       void nccell_styles_set(nccell* c, unsigned stylebits);
46
47       unsigned nccell_styles(const nccell* c);
48
49       bool nccellcmp(const struct ncplane* n1, const nccell* c1, const struct
50       ncplane* n2, const nccell* c2);
51
52       void nccell_on_styles(nccell* c, unsigned stylebits);
53
54       void nccell_off_styles(nccell* c, unsigned stylebits);
55
56       void nccell_set_fg_default(nccell* c);
57
58       void nccell_set_bg_default(nccell* c);
59
60       int nccell_set_fg_alpha(nccell* c, unsigned alpha);
61
62       int nccell_set_bg_alpha(nccell* c, unsigned alpha);
63
64       bool nccell_double_wide_p(const nccell* c);
65
66       const char* nccell_extended_gcluster(const struct ncplane* n, const nc‐
67       cell* c);
68
69       char* nccell_strdup(const struct ncplane* n, const nccell* c);
70
71       int nccell_load_char(struct ncplane* n, nccell* c, char ch);
72
73       int nccell_load_egc32(struct ncplane* n, nccell* c, uint32_t egc);
74
75       char*  nccell_extract(const  struct  ncplane*  n,  const   nccell*   c,
76       uint16_t* stylemask, uint64_t* channels);
77
78       uint32_t nccell_bchannel(const nccell* c);
79
80       uint32_t nccell_fchannel(const nccell* c);
81
82       uint64_t nccell_set_bchannel(nccell* c, uint32_t channel);
83
84       uint64_t nccell_set_fchannel(nccell* c, uint32_t channel);
85
86       uint32_t nccell_fg_rgb(const nccell* c);
87
88       uint32_t nccell_bg_rgb(const nccell* c);
89
90       unsigned nccell_fg_alpha(const nccell* c);
91
92       unsigned nccell_bg_alpha(const nccell* c);
93
94       unsigned  nccell_fg_rgb8(const nccell* c, unsigned* r, unsigned* g, un‐
95       signed* b);
96
97       unsigned nccell_bg_rgb8(const ncell* c, unsigned* r, unsigned*  g,  un‐
98       signed* b);
99
100       int nccell_set_fg_rgb8(nccell* c, unsigned r, unsigned g, unsigned b);
101
102       int nccell_set_bg_rgb8(nccell* c, unsigned r, unsigned g, unsigned b);
103
104       void nccell_set_fg_rgb8_clipped(nccell* c, int r, int g, int b);
105
106       void nccell_set_bg_rgb8_clipped(nccell* c, int r, int g, int b);
107
108       int nccell_set_fg_rgb(nccell* c, uint32_t channel);
109
110       int nccell_set_bg_rgb(nccell* c, uint32_t channel);
111
112       bool nccell_fg_default_p(const nccell* c);
113
114       bool nccell_bg_default_p(const nccell* c);
115
116       int ncstrwidth(const char* text);
117
118       int  ncstrwidth_valid(const  char*  text,  int* validbytes, int* valid‐
119       width);
120

DESCRIPTION

122       Cells make up the framebuffer associated with each plane, with one cell
123       per  addressable  coordinate.   You should not usually need to interact
124       directly with nccells.
125
126       Each nccell contains exactly one extended grapheme cluster.  If the EGC
127       is encoded in UTF-8 with four or fewer bytes (all Unicode codepoints as
128       of Unicode 13 can be encoded in no more than four UTF-8 bytes),  it  is
129       encoded  directly  into  the nccell's gcluster field, and no additional
130       storage is necessary.  Otherwise, the EGC is stored as a nul-terminated
131       UTF-8 string in some backing egcpool.  Egcpools are associated with nc‐
132       planes, so nccells must be considered associated  with  ncplanes.   In‐
133       deed,  ncplane_erase  destroys  the  backing  storage for all a plane's
134       cells, invalidating them.  This association is formed at  the  time  of
135       nccell_load, nccell_prime, or nccell_duplicate.  All of these functions
136       first  call   nccell_release,   as   do   nccell_load_egc32   and   nc‐
137       cell_load_char.   When  done  using  a nccell entirely, call nccell_re‐
138       lease.  ncplane_destroy will free up the memory used by the nccell, but
139       the backing egcpool has a maximum size of 16MiB, and failure to release
140       nccells can eventually block new output.
141
142       nccell_extended_gcluster provides a nul-terminated handle to  the  EGC.
143       This  ought  be  considered  invalidated  by  changes  to the nccell or
144       egcpool.  The handle is not heap-allocated; do not attempt  to  free(3)
145       it.  A heap-allocated copy can be acquired with nccell_strdup.
146
147       ncstrwidth_valid  returns  the  number  of  columns occupied by a valid
148       UTF-8 string, or -1 if an error is encountered.  In  either  case,  the
149       number  of valid bytes and columns, respectively, consumed before error
150       into validbytes and validwidth (assuming them to not be NULL).
151

RETURN VALUES

153       nccell_load and similar functions return the  number  of  bytes  loaded
154       from the EGC, or -1 on failure.  They can fail due to either an invalid
155       UTF-8 input, or the backing egcpool reaching its maximum size.
156
157       nccell_set_fg_rgb8 and similar functions will return -1 if provided in‐
158       valid inputs, and 0 otherwise.
159
160       nccellcmp returns a negative integer, 0, or a positive integer if c1 is
161       less than, equal to, or more than c2, respectively.
162
163       nccell_extended_gcluster returns NULL  if  called  on  a  sprixel  (see
164       notcurses_visual(3).
165
166       nccell_cols  returns  the number of columns occupied by c, according to
167       wcwidth(3)*.   ncstrwidth  is  an  equivalent  for   strings.    ncstr‐
168       width_valid returns the same value as ncstrwidth.
169

NOTES

171       cell  was renamed to nccell in Notcurses 2.2.0, so as not to bleed such
172       a common term into the (single, global) C namespace.  cell will be  re‐
173       tained  as an alias until Notcurses 3.0.  Likewise, many functions pre‐
174       fixed with cell have been renamed to start with nccell.
175

AUTHORS

181       nick black <nickblack@linux.com>.
182
183
184
185                                    v2.4.9                   notcurses_cell(3)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

NOTES

SEE ALSO

AUTHORS