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

DESCRIPTION

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

RETURN VALUES

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

NOTES

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

AUTHORS

179       nick black <nickblack@linux.com>.
180
181
182
183                                    v2.3.1                   notcurses_cell(3)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

NOTES

SEE ALSO

AUTHORS