.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_cell" "3" "v3.0.0" "" ""
.hy
.SH NAME
.PP
notcurses_cell - operations on nccell objects
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
// See DESCRIPTION below for information on EGC encoding
typedef struct nccell {
  uint32_t gcluster;          // 4B \[->] 4B
  uint8_t gcluster_backstop;  // 1B \[->] 5B (8 bits of zero)
  uint8_t width;              // 1B \[->] 6B (8 bits of column width)
  uint16_t stylemask;         // 2B \[->] 8B (16 bits of NCSTYLE_* attributes)
  uint64_t channels;
} nccell;

#define CELL_TRIVIAL_INITIALIZER \[rs]
 { .gcluster = \[aq]\[rs]0\[aq], .stylemask = 0, .channels = 0, }
#define CELL_SIMPLE_INITIALIZER(c) \[rs]
 { .gcluster = (c), .stylemask = 0, .channels = 0, }
#define CELL_INITIALIZER(c, s, chan) \[rs]
 { .gcluster = (c), .stylemask = (s), .channels = (chan), }

#define NCALPHA_HIGHCONTRAST  0x30000000ull
#define NCALPHA_TRANSPARENT   0x20000000ull
#define NCALPHA_BLEND         0x10000000ull
#define NCALPHA_OPAQUE        0x00000000ull
\f[R]
.fi
.PP
\f[B]void nccell_init(nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_load(struct ncplane* \f[R]\f[I]n\f[R]\f[B], nccell*
\f[R]\f[I]c\f[R]\f[B], const char* \f[R]\f[I]gcluster\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_prime(struct ncplane* \f[R]\f[I]n\f[R]\f[B], nccell*
\f[R]\f[I]c\f[R]\f[B], const char* \f[R]\f[I]gcluster\f[R]\f[B],
uint32_t \f[R]\f[I]stylemask\f[R]\f[B], uint64_t
\f[R]\f[I]channels\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_duplicate(struct ncplane* \f[R]\f[I]n\f[R]\f[B], nccell*
\f[R]\f[I]targ\f[R]\f[B], const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_release(struct ncplane* \f[R]\f[I]n\f[R]\f[B], nccell*
\f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_cols(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_styles_set(nccell* \f[R]\f[I]c\f[R]\f[B], unsigned
\f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned nccell_styles(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]bool nccellcmp(const struct ncplane* \f[R]\f[I]n1\f[R]\f[B], const
nccell* \f[R]\f[I]c1\f[R]\f[B], const struct ncplane*
\f[R]\f[I]n2\f[R]\f[B], const nccell* \f[R]\f[I]c2\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_on_styles(nccell* \f[R]\f[I]c\f[R]\f[B], unsigned
\f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_off_styles(nccell* \f[R]\f[I]c\f[R]\f[B], unsigned
\f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_set_fg_default(nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_set_bg_default(nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_fg_alpha(nccell* \f[R]\f[I]c\f[R]\f[B], unsigned
\f[R]\f[I]alpha\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_bg_alpha(nccell* \f[R]\f[I]c\f[R]\f[B], unsigned
\f[R]\f[I]alpha\f[R]\f[B]);\f[R]
.PP
\f[B]bool nccell_double_wide_p(const nccell*
\f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]const char* nccell_extended_gcluster(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]char* nccell_strdup(const struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_load_char(struct ncplane* \f[R]\f[I]n\f[R]\f[B], nccell*
\f[R]\f[I]c\f[R]\f[B], char \f[R]\f[I]ch\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_load_egc32(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
nccell* \f[R]\f[I]c\f[R]\f[B], uint32_t \f[R]\f[I]egc\f[R]\f[B]);\f[R]
.PP
\f[B]char* nccell_extract(const struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const nccell* \f[R]\f[I]c\f[R]\f[B], uint16_t*
\f[R]\f[I]stylemask\f[R]\f[B], uint64_t*
\f[R]\f[I]channels\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t nccell_bchannel(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t nccell_fchannel(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]uint64_t nccell_set_bchannel(nccell* \f[R]\f[I]c\f[R]\f[B],
uint32_t \f[R]\f[I]channel\f[R]\f[B]);\f[R]
.PP
\f[B]uint64_t nccell_set_fchannel(nccell* \f[R]\f[I]c\f[R]\f[B],
uint32_t \f[R]\f[I]channel\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t nccell_fg_rgb(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t nccell_bg_rgb(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned nccell_fg_alpha(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned nccell_bg_alpha(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned nccell_fg_rgb8(const nccell* \f[R]\f[I]c\f[R]\f[B],
unsigned* \f[R]\f[I]r\f[R]\f[B], unsigned* \f[R]\f[I]g\f[R]\f[B],
unsigned* \f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned nccell_bg_rgb8(const ncell* \f[R]\f[I]c\f[R]\f[B],
unsigned* \f[R]\f[I]r\f[R]\f[B], unsigned* \f[R]\f[I]g\f[R]\f[B],
unsigned* \f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_fg_rgb8(nccell* \f[R]\f[I]c\f[R]\f[B], unsigned
\f[R]\f[I]r\f[R]\f[B], unsigned \f[R]\f[I]g\f[R]\f[B], unsigned
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_bg_rgb8(nccell* \f[R]\f[I]c\f[R]\f[B], unsigned
\f[R]\f[I]r\f[R]\f[B], unsigned \f[R]\f[I]g\f[R]\f[B], unsigned
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_set_fg_rgb8_clipped(nccell* \f[R]\f[I]c\f[R]\f[B], int
\f[R]\f[I]r\f[R]\f[B], int \f[R]\f[I]g\f[R]\f[B], int
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]void nccell_set_bg_rgb8_clipped(nccell* \f[R]\f[I]c\f[R]\f[B], int
\f[R]\f[I]r\f[R]\f[B], int \f[R]\f[I]g\f[R]\f[B], int
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_fg_rgb(nccell* \f[R]\f[I]c\f[R]\f[B], uint32_t
\f[R]\f[I]channel\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_bg_rgb(nccell* \f[R]\f[I]c\f[R]\f[B], uint32_t
\f[R]\f[I]channel\f[R]\f[B]);\f[R]
.PP
\f[B]bool nccell_fg_default_p(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]bool nccell_bg_default_p(const nccell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_fg_palindex(nccell* \f[R]\f[I]cl\f[R]\f[B], int
\f[R]\f[I]idx\f[R]\f[B]);\f[R]
.PP
\f[B]int nccell_set_bg_palindex(nccell* \f[R]\f[I]cl\f[R]\f[B], int
\f[R]\f[I]idx\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t nccell_fg_palindex(const nccell*
\f[R]\f[I]cl\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t nccell_bg_palindex(const nccell*
\f[R]\f[I]cl\f[R]\f[B]);\f[R]
.PP
\f[B]bool nccell_fg_palindex_p(const nccell*
\f[R]\f[I]cl\f[R]\f[B]);\f[R]
.PP
\f[B]bool nccell_bg_palindex_p(const nccell*
\f[R]\f[I]cl\f[R]\f[B]);\f[R]
.PP
\f[B]int ncstrwidth(const char* \f[R]\f[I]text\f[R]\f[B])\f[R];
.PP
\f[B]int ncstrwidth_valid(const char* \f[R]\f[I]text\f[R]\f[B], int*
\f[R]\f[I]validbytes\f[R]\f[B], int*
\f[R]\f[I]validwidth\f[R]\f[B])\f[R];
.SH DESCRIPTION
.PP
Cells make up the framebuffer associated with each plane, with one cell
per addressable coordinate.
You should not usually need to interact directly with \f[B]nccell\f[R]s.
.PP
Each \f[B]nccell\f[R] 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 \f[B]nccell\f[R]\[aq]s
\f[B]gcluster\f[R] 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 \f[B]ncplane\f[R]s, so \f[B]nccell\f[R]s
must be considered associated with \f[B]ncplane\f[R]s.
Indeed, \f[B]ncplane_erase\f[R] destroys the backing storage for all a
plane\[aq]s cells, invalidating them.
This association is formed at the time of \f[B]nccell_load\f[R],
\f[B]nccell_prime\f[R], or \f[B]nccell_duplicate\f[R].
All of these functions first call \f[B]nccell_release\f[R], as do
\f[B]nccell_load_egc32\f[R] and \f[B]nccell_load_char\f[R].
When done using a \f[B]nccell\f[R] entirely, call
\f[B]nccell_release\f[R].
\f[B]ncplane_destroy\f[R] will free up the memory used by the
\f[B]nccell\f[R], but the backing egcpool has a maximum size of 16MiB,
and failure to release \f[B]nccell\f[R]s can eventually block new
output.
.PP
\f[B]nccell_extended_gcluster\f[R] provides a nul-terminated handle to
the EGC.
This ought be considered invalidated by changes to the \f[B]nccell\f[R]
or \f[B]egcpool\f[R].
The handle is \f[B]not\f[R] heap-allocated; do \f[B]not\f[R] attempt to
\f[B]free(3)\f[R] it.
A heap-allocated copy can be acquired with \f[B]nccell_strdup\f[R].
.PP
\f[B]ncstrwidth_valid\f[R] returns the number of columns occupied by a
valid UTF-8 string, or -1 if an error is encountered.
In either case, the number of valid bytes and columns, respectively,
consumed before error into \f[B]\f[BI]validbytes\f[B]\f[R] and
\f[B]\f[BI]validwidth\f[B]\f[R] (assuming them to not be
\f[B]NULL\f[R]).
.PP
\f[B]nccell_fg_palindex\f[R] extracts the palette index from a
cell\[aq]s foreground channel.
The channel must be palette-indexed, or the return value is meaningless.
Verify palette indexing with \f[B]nccell_fg_palindex_p\f[R].
A cell\[aq]s foreground channel can be set to palette-indexed mode (and
have the index set) with \f[B]nccell_set_fg_palindex\f[R].
The index must be less than \f[B]NCPALETTESIZE\f[R].
Replace \f[B]fg\f[R] with \f[B]bg\f[R] to operate on the background
channel.
.SH RETURN VALUES
.PP
\f[B]nccell_load\f[R] and similar functions return the number of bytes
loaded from the EGC, or -1 on failure.
They can fail due to either an invalid UTF-8 input, or the backing
egcpool reaching its maximum size.
.PP
\f[B]nccell_set_fg_rgb8\f[R] and similar functions will return -1 if
provided invalid inputs, and 0 otherwise.
.PP
\f[B]nccellcmp\f[R] returns a negative integer, 0, or a positive integer
if \f[B]\f[BI]c1\f[B]\f[R] is less than, equal to, or more than
\f[B]\f[BI]c2\f[B]\f[R], respectively.
.PP
\f[B]nccell_extended_gcluster\f[R] returns \f[B]NULL\f[R] if called on a
sprixel (see \f[B]notcurses_visual(3)\f[R].
.PP
\f[B]nccell_cols\f[R] returns the number of columns occupied by
\f[B]\f[BI]c\f[B]\f[R], according to \f[B]wcwidth(3)\f[R]*.
\f[B]ncstrwidth\f[R] is an equivalent for strings.
\f[B]ncstrwidth_valid\f[R] returns the same value as
\f[B]ncstrwidth\f[R].
.SH NOTES
.PP
\f[B]cell\f[R] was renamed to \f[B]nccell\f[R] in Notcurses 2.2.0, so as
not to bleed such a common term into the (single, global) C namespace.
\f[B]cell\f[R] will be retained as an alias until Notcurses 3.0.
Likewise, many functions prefixed with \f[B]cell\f[R] have been renamed
to start with \f[B]nccell\f[R].
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_channels(3)\f[R],
\f[B]notcurses_plane(3)\f[R], \f[B]notcurses_output(3)\f[R],
\f[B]notcurses_visual(3)\f[R], \f[B]wcwidth(3)\f[R], \f[B]utf8(7)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.