Type Definition libnotcurses_sys::NcCell [−][src]
pub type NcCell = nccell;
Expand description
A coordinate on an NcPlane
storing 128 bits of data.
Methods & Associated Functions
Description
An NcCell
corresponds to a single character cell on some NcPlane
,
which can be occupied by a single EGC
grapheme cluster (some root
spacing glyph, along with possible combining characters, which might span
multiple columns).
An NcCell
is bounded to an NcPlane
, but the cell doesn’t store anything
about the plane.
At any NcCell
, we can have a theoretically arbitrarily long UTF-8 string,
a foreground color, a background color, and an NcStyle
attribute set.
Valid grapheme cluster contents include:
- A NUL terminator,
- A single control character, followed by a NUL terminator,
- At most one spacing character, followed by zero or more nonspacing characters, followed by a NUL terminator.
Diagram
`NcCell`: 128 bits structure comprised of the following 5 elements:
GCLUSTER|GCLUSTER|GCLUSTER|GCLUSTER 1. `EGC`
00000000║WWWWWWWW║11111111|11111111 2. backstop + 3. width + 4. `NcStyle`
~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB 5. `NcChannels`
~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB "
1. (32b) Extended Grapheme Cluster, presented either as:
1.1. An EGC of up to 4 bytes:
UUUUUUUU|UUUUUUUU|UUUUUUUU|UUUUUUUU
1.2. A `0x01` in the first byte, plus 3 bytes with a 24b address to an egcpool:
00000001|IIIIIIII|IIIIIIII|IIIIIIII
2. (8b) backstop (zero)
00000000
3. (8b) column width
WWWWWWWW
4. (16b) `NcStyle`
11111111 11111111
5. (64b) `NcChannels`
~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB║~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
type in C: cell (struct)
More NcCell
Information
Size
Multi-column characters can only have a single style/color throughout.
wcwidth()
is not reliable. It’s just quoting whether or not the EGC
contains a “Wide Asian” double-width character.
This is set for some things, like most emoji, and not set for
other things, like cuneiform.
Each cell occupies 16 static bytes (128 bits). The surface is thus ~1.6MB for a (pretty large) 500x200 terminal. At 80x43, it’s less than 64KB. Dynamic requirements (the egcpool) can add up to 16MB to an ncplane, but such large pools are unlikely in common use.
Alpha Compositing
We implement some small alpha compositing. Foreground and background both have two bits of inverted alpha. The actual grapheme written to a cell is the topmost non-zero grapheme.
-
If its alpha is 00 (
NcAlpha::OPAQUE
) its foreground color is used unchanged. -
If its alpha is 10 (
NcAlpha::TRANSPARENT
) its foreground color is derived entirely from cells underneath it. -
If its alpha is 01 (
NcAlpha::BLEND
) the result will be a composite.
Likewise for the background. If the bottom of a coordinate’s zbuffer is reached with a cumulative alpha of zero, the default is used. In this way, a terminal configured with transparent background can be supported through multiple occluding ncplanes.
A foreground alpha of 11
(NcAlpha::HIGHCONTRAST
)
requests high-contrast text (relative to the computed background).
A background alpha of 11 is currently forbidden.
Precedence
- Default color takes precedence over palette or RGB, and cannot be used with transparency.
- Indexed palette takes precedence over RGB. It cannot meaningfully set transparency, but it can be mixed into a cascading color.
- RGB is used if neither default terminal colors nor palette indexing are in play, and fully supports all transparency options.
Column width (WIP)
See USAGE.md
We store the column width in this field. for a multicolumn EGC of N columns, there will be N nccells, and each has a width of N…for now. eventually, such an EGC will set more than one subsequent cell to WIDE_RIGHT, and this won’t be necessary. it can then be used as a bytecount. see #1203. FIXME iff width >= 2, the cell is part of a multicolumn glyph. whether a cell is the left or right side of the glyph can be determined by checking whether ->gcluster is zero.
Implementations
New NcCell
, expects a 7-bit char
.
New NcCell
, from a char
.
Expects a plane where to save the extra data if it’s greater than 4 bytes.
New NcCell
, from a &str
.
Expects a plane where to save the extra data if it’s greater than 4 bytes.
Breaks the UTF-8 string in egc
down, setting up this NcCell
,
and returns the number of bytes copied out of egc
.
The styling of the cell is left untouched, but any resources are released. C style function: nccell_load().
Same as load, plus blasts the styling with
style
and channels
.
- Breaks the UTF-8 string in
gcluster
down, setting up this NcCell. - Returns the number of bytes copied out of
gcluster
. - Any resources are released.
- Blasts the styling with
style
andchannels
.
C style function: nccell_prime().
Duplicate this NcCell
into another one.
Both must be or will be bound to common_plane
.
C style function: nccell_duplicate().
Initializes (zeroes out) this NcCell
.
C style function: nccell_init().
Releases resources held by the current cell in the NcPlane plane
.
C style function: nccell_release().
Returns the NcChannels
of this NcCell
.
(No equivalent C style function)
Extracts the background NcAlpha
(shifted to LSBs).
C style function: nccell_bg_alpha().
Is the background NcChannel
using the “default background color”?
C style function: nccell_bg_default_p().
Gets the NcPaletteIndex
of the background NcChannel
.
C style function: nccell_bg_palindex().
Is the background NcChannel
using an NcPaletteIndex
indexed
NcPalette
color?
C style function: nccell_bg_palindex_p().
Gets the background NcRgb
(shifted to LSBs).
C style function: nccell_bg_rgb().
Gets the background RGB NcComponent
s.
C style function: nccell_bg_rgb8().
Extracts the foreground NcAlpha
(shifted to LSBs).
C style function: nccell_fg_alpha().
Is the foreground NcChannel
using the “default foreground color”?
C style function: nccell_fg_default_p().
Gets the NcPaletteIndex
of the foreground NcChannel
.
C style function: nccell_fg_palindex().
Is the foreground NcChannel
using an NcPaletteIndex
indexed
NcPalette
color?
C style function: nccell_fg_palindex_p().
Gets the foreground NcRgb
(shifted to LSBs).
C style function: nccell_fg_rgb().
Gets the foreground RGB NcComponent
s.
C style function: nccell_fg_rgb8().
Sets the background NcAlpha
.
C style function: nccell_set_bg_alpha().
Indicates to use the “default color” for the background NcChannel
.
C style function: nccell_set_bg_default().
Sets the background NcPaletteIndex
.
Also sets
NcChannels::BG_PALETTE_MASK
and
NcAlpha::OPAQUE
, and clears out
NcChannels::BG_DEFAULT_MASK
.
C style function: nccell_set_bg_palindex().
Sets the background NcRgb
and marks it as not using the default color.
C style function: nccell_set_bg_rgb().
Sets the background RGB NcComponent
s, and marks it as not using
the “default color”.
C style function: nccell_set_bg_rgb8().
Sets the foreground NcAlpha
.
C style function: nccell_set_fg_alpha().
Indicates to use the “default color” for the foreground NcChannel
.
C style function: nccell_set_fg_default().
Sets the foreground NcPaletteIndex
.
Also sets
NcChannels::FG_PALETTE_MASK
and
NcAlpha::OPAQUE
, and clears out
NcChannels::FG_DEFAULT_MASK
.
C style function: nccell_set_fg_palindex().
Sets the foreground NcRgb
and marks it as not using the default color.
C style function: nccell_set_fg_rgb().
Sets the foreground RGB NcComponent
s, and marks it as not using
the “default color”.
C style function: nccell_set_fg_rgb8().
Returns true if the two cells have distinct EGC
s, attributes,
or NcChannel
s.
The actual egcpool index needn’t be the same–indeed, the planes
needn’t even be the same. Only the expanded EGC
must be bit-equal.
C style function: nccellcmp().
Saves the NcStyle
and the NcChannels
, and returns the EGC
.
(These are the three elements of an NcCell
).
C style function: nccell_fg_alpha().
Returns the NcStyle
bits.
C style function: nccell_styles().
Removes the specified NcStyle
bits.
C style function: nccell_off_styles().
Adds the specified NcStyle
bits.
C style function: nccell_on_styles().
Sets just the specified NcStyle
bits.
C style function: nccell_set_styles().
Returns the number of columns occupied by the cell.
See ncstrwidth
for an equivalent for multiple EGCs.
C style function: nccell_cols().
Returns a pointer to the EGC
of this NcCell in the plane
.
This pointer can be invalidated by any further operation on the referred plane, so… watch out!
C style function: nccell_extended_gcluster().
Copies the UTF8-encoded EGC
out of this NcCell,
whether simple or complex.
The result is not tied to the NcPlane, and persists across erases and destruction.
C style function: nccell_strdup().
Does this NcCell contain a wide codepoint?
C style function: nccell_double_wide_p().
Is this the left half of a wide character?
C style function: nccell_wide_left_p().
Is this the right side of a wide character?
C style function: nccell_wide_right_p().
Loads up six cells with the EGC
s necessary to draw a box.
On error, any NcCell
s this function might have loaded before the error
are released.
There must be at least six EGC
s in gcluster
.
C style function: nccells_load_box().
NcCell.load_box() with the double box-drawing characters.
C style function: nccells_double_box().
NcCell.load_box() with the rounded box-drawing characters.
C style function: nccells_rounded_box().
NcCell.load_box() with ASCII characters.
C style function: nccells_ascii_box().
NcCell.load_box() with the heavy line box-drawing characters.
C style function: nccells_heavy_box().
NcCell.load_box() with the light line box-drawing characters.
C style function: nccells_light_box().