Type Definition libnotcurses_sys::NcCell

source ·

pub type NcCell = nccell;

Expand description

A coordinate on an NcPlane storing 128 bits of data.

Methods & Associated Functions

Constructors & Destructors
bg|fg NcChannels manipulation
Other components
Text

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.

Type Definition libnotcurses_sys::NcCell

Implementations§

impl NcCell

pub fn from_char7b(ch: char) -> NcResult<Self>

pub fn from_char(plane: &mut NcPlane, ch: char) -> NcResult<Self>

pub fn from_str(plane: &mut NcPlane, string: &str) -> NcResult<Self>

pub fn new() -> Self

pub fn load(plane: &mut NcPlane, cell: &mut NcCell, egc: &str) -> NcResult<u32>

pub fn prime( plane: &mut NcPlane, cell: &mut NcCell, gcluster: &str, style: impl Into<NcStyle>, channels: impl Into<NcChannels> ) -> NcResult<u32>

pub fn duplicate(&self, common_plane: &mut NcPlane) -> NcResult<NcCell>

pub fn init(&mut self)

pub fn release(&mut self, plane: &mut NcPlane)

impl NcCell

pub fn bchannel(&self) -> NcChannel

pub fn fchannel(&self) -> NcChannel

pub fn channels(&self) -> NcChannels

pub fn set_bchannel(&mut self, from: impl Into<NcChannel>) -> NcChannels

pub fn set_fchannel(&mut self, from: impl Into<NcChannel>) -> NcChannels

pub fn set_channels(&mut self, from: impl Into<NcChannels>) -> NcChannels

pub fn bg_alpha(&self) -> NcAlpha

pub fn bg_default_p(&self) -> bool

pub fn bg_palindex(&self) -> NcPaletteIndex

pub fn bg_palindex_p(&self) -> bool

pub fn bg_rgb(&self) -> NcRgb

pub fn fg_alpha(&self) -> NcAlpha

pub fn fg_default_p(&self) -> bool

pub fn fg_palindex(&self) -> NcPaletteIndex

pub fn fg_palindex_p(&self) -> bool

pub fn fg_rgb(&self) -> NcRgb

pub fn set_bg_alpha(&mut self, alpha: impl Into<NcAlpha>)

pub fn set_bg_default(&mut self)

pub fn set_bg_palindex(&mut self, index: impl Into<NcPaletteIndex>)

pub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>)

pub fn set_fg_alpha(&mut self, alpha: impl Into<NcAlpha>)

pub fn set_fg_default(&mut self)

pub fn set_fg_palindex(&mut self, index: impl Into<NcPaletteIndex>)

pub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>)

impl NcCell

pub fn compare( plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCell ) -> bool

pub fn extract( &self, plane: &mut NcPlane, styles: &mut NcStyle, channels: &mut NcChannels ) -> String

pub fn styles(&self) -> NcStyle

pub fn styles_off(&mut self, stylebits: impl Into<NcStyle>)

pub fn styles_on(&mut self, stylebits: impl Into<NcStyle>)

pub fn styles_set(&mut self, stylebits: impl Into<NcStyle>)

impl NcCell

pub const fn cols(&self) -> u8

pub fn egc(&self, plane: &NcPlane) -> &str

pub fn strdup(&self, plane: &NcPlane) -> String

pub fn double_wide_p(&self) -> bool

pub fn wide_left_p(&self) -> bool

pub fn wide_right_p(&self) -> bool

impl NcCell

pub fn load_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell, gcluster: &str ) -> NcResult<()>

pub fn double_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>

pub fn rounded_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>

pub fn ascii_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>

pub fn heavy_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>

pub fn light_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>