.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_cell" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_cell - operations on notcurses cells
.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 cell {
  uint32_t gcluster;          // 4B \[->] 4B
  uint8_t gcluster_backstop;  // 1B \[->] 5B (8 bits of zero)
  uint8_t reserved;           // 1B \[->] 6B (8 reserved bits, ought be zero)
  uint16_t stylemask;         // 2B \[->] 8B (16 bits of NCSTYLE_* attributes)
  uint64_t channels;
} cell;

#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 CELL_WIDEASIAN_MASK     0x8000000080000000ull
#define CELL_BGDEFAULT_MASK     0x0000000040000000ull
#define CELL_FGDEFAULT_MASK     (CELL_BGDEFAULT_MASK << 32u)
#define CELL_BG_RGB_MASK        0x0000000000ffffffull
#define CELL_FG_RGB_MASK        (CELL_BG_MASK << 32u)
#define CELL_BG_PALETTE         0x0000000008000000ull
#define CELL_FG_PALETTE         (CELL_BG_PALETTE << 32u)
#define CHANNEL_ALPHA_MASK      0x30000000ull
#define CELL_ALPHA_HIGHCONTRAST 0x30000000ull
#define CELL_ALPHA_TRANSPARENT  0x2.0.4000ull
#define CELL_ALPHA_BLEND        0x10000000ull
#define CELL_ALPHA_OPAQUE       0x00000000ull
\f[R]
.fi
.PP
\f[B]void cell_init(cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int cell_load(struct ncplane* \f[R]\f[I]n\f[R]\f[B], cell*
\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 cell_prime(struct ncplane* \f[R]\f[I]n\f[R]\f[B], cell*
\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 cell_duplicate(struct ncplane* \f[R]\f[I]n\f[R]\f[B], cell*
\f[R]\f[I]targ\f[R]\f[B], const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]void cell_release(struct ncplane* \f[R]\f[I]n\f[R]\f[B], cell*
\f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]void cell_styles_set(cell* \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 cell_styles(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]void cell_styles_on(cell* \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 cell_styles_off(cell* \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 cell_set_fg_default(cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]void cell_set_bg_default(cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int cell_set_fg_alpha(cell* \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 cell_set_bg_alpha(cell* \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 cell_double_wide_p(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]const char* cell_extended_gcluster(const struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]char* cell_strdup(const struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int cell_load_simple(struct ncplane* \f[R]\f[I]n\f[R]\f[B], cell*
\f[R]\f[I]c\f[R]\f[B], char \f[R]\f[I]ch\f[R]\f[B]);\f[R]
.PP
\f[B]char* cell_extract(const struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const cell* \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 cell_bchannel(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t cell_fchannel(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]uint64_t cell_set_bchannel(cell* \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 cell_set_fchannel(cell* \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 cell_fg_rgb(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t cell_bg_rgb(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned cell_fg_alpha(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned cell_bg_alpha(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned cell_fg_rgb8(const cell* \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 cell_bg_rgb8(const cell* \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 cell_set_fg_rgb8(cell* \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 cell_set_bg_rgb8(cell* \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 cell_set_fg_rgb8_clipped(cell* \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 cell_set_bg_rgb8_clipped(cell* \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 cell_set_fg_rgb(cell* \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 cell_set_bg_rgb(cell* \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 cell_fg_default_p(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]bool cell_bg_default_p(const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int ncstrwidth(const char* \f[R]\f[I]text\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 cells.
.PP
Each \f[B]cell\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]cell\f[R]\[cq]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]cell\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\[cq]s cells, invalidating them.
This association is formed at the time of \f[B]cell_load()\f[R],
\f[B]cell_prime()\f[R], or \f[B]cell_duplicate()\f[R].
All of these functions first call \f[B]cell_release()\f[R], as does
\f[B]cell_load_simple()\f[R].
When done using a \f[B]cell\f[R] entirely, call
\f[B]cell_release()\f[R].
\f[B]ncplane_destroy()\f[R] will free up the memory used by the
\f[B]cell\f[R], but the backing egcpool has a maximum size of 16MiB, and
failure to release \f[B]cell\f[R]s can eventually block new output.
.PP
\f[B]cell_extended_gcluster\f[R] provides a nul-terminated handle to the
EGC.
This ought be considered invalidated by changes to the \f[B]cell\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]cell_strdup\f[R].
.SH RETURN VALUES
.PP
\f[B]cell_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]cell_set_fg_rgb8()\f[R] and similar functions will return -1 if
provided invalid inputs, and 0 otherwise.
.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]
.SH AUTHORS
nick black <nickblack@linux.com>.