Type Definition libnotcurses_sys::NcCell

type NcCell = cell;

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. NcEgcBackstop + 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

impl NcCell

NcCell constructors

pub const fn from_char7b(ch: char) -> Self

New NcCell, expects a 7-bit char.

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

New NcCell, expects an NcPlane and a char.

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

New NcCell, expects an NcPlane and a &str.

pub const fn new() -> Self

New empty NcCell.

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

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().

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

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 and channels.

C style function: nccell_prime().

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

Duplicate this NcCell into another one.

Both must be or will be bound to common_plane.

C style function: nccell_duplicate().

pub fn init(&mut self)

Initializes (zeroes out) this NcCell.

C style function: nccell_init().

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

Releases resources held by the current cell in the NcPlane plane.

C style function: nccell_release().

impl NcCell

NcCell methods: bg|fg NcChannels manipulation.

pub fn channels(&mut self, plane: &mut NcPlane) -> NcChannels

Returns the NcChannels of this NcCell.

(No equivalent C style function)

pub fn bg_alpha(&self) -> NcAlphaBits

Extracts the background NcAlphaBits (shifted to LSBs).

C style function: nccell_bg_alpha().

pub fn bg_default_p(&self) -> bool

Is the background NcChannel using the “default background color”?

C style function: nccell_bg_default_p().

pub fn bg_palindex(&self) -> NcPaletteIndex

Gets the NcPaletteIndex of the background NcChannel.

C style function: nccell_bg_palindex().

pub fn bg_palindex_p(&self) -> bool

Is the background NcChannel using an NcPaletteIndex indexed NcPalette color?

C style function: nccell_bg_palindex_p().

pub fn bg_rgb(&self) -> NcRgb

Gets the background NcRgb (shifted to LSBs).

C style function: nccell_bg_rgb().

pub fn bg_rgb8(&self) -> (NcComponent, NcComponent, NcComponent)

Gets the background RGB NcComponents.

C style function: nccell_bg_rgb8().

pub fn fg_alpha(&self) -> NcAlphaBits

Extracts the foreground NcAlphaBits (shifted to LSBs).

C style function: nccell_fg_alpha().

pub fn fg_default_p(&self) -> bool

Is the foreground NcChannel using the “default foreground color”?

C style function: nccell_fg_default_p().

pub fn fg_palindex(&self) -> NcPaletteIndex

Gets the NcPaletteIndex of the foreground NcChannel.

C style function: nccell_fg_palindex().

pub fn fg_palindex_p(&self) -> bool

Is the foreground NcChannel using an NcPaletteIndex indexed NcPalette color?

C style function: nccell_fg_palindex_p().

pub fn fg_rgb(&self) -> NcRgb

Gets the foreground NcRgb (shifted to LSBs).

C style function: nccell_fg_rgb().

pub fn fg_rgb8(&self) -> (NcComponent, NcComponent, NcComponent)

Gets the foreground RGB NcComponents.

C style function: nccell_fg_rgb8().

pub fn set_bg_alpha(&mut self, alpha: NcAlphaBits)

Sets the background NcAlphaBits.

C style function: nccell_set_bg_alpha().

pub fn set_bg_default(&mut self)

Indicates to use the “default color” for the background NcChannel.

C style function: nccell_set_bg_default().

pub fn set_bg_palindex(&mut self, index: NcPaletteIndex)

Sets the background NcPaletteIndex.

Also sets NCALPHA_BG_PALETTE and NCALPHA_OPAQUE, and clears out NCALPHA_BGDEFAULT_MASK.

C style function: nccell_set_bg_palindex().

pub fn set_bg_rgb(&mut self, rgb: NcRgb)

Sets the background NcRgb and marks it as not using the default color.

C style function: nccell_set_bg_rgb().

pub fn set_bg_rgb8(
    &mut self,
    red: NcComponent,
    green: NcComponent,
    blue: NcComponent
)

Sets the background RGB NcComponents, and marks it as not using the “default color”.

C style function: nccell_set_bg_rgb8().

pub fn set_fg_alpha(&mut self, alpha: NcAlphaBits)

Sets the foreground NcAlphaBits.

C style function: nccell_set_fg_alpha().

pub fn set_fg_default(&mut self)

Indicates to use the “default color” for the foreground NcChannel.

C style function: nccell_set_fg_default().

pub fn set_fg_palindex(&mut self, index: NcPaletteIndex)

Sets the foreground NcPaletteIndex.

Also sets NCALPHA_FG_PALETTE and NCALPHA_OPAQUE, and clears out NCALPHA_BGDEFAULT_MASK.

C style function: nccell_set_fg_palindex().

pub fn set_fg_rgb(&mut self, rgb: NcRgb)

Sets the foreground NcRgb and marks it as not using the default color.

C style function: nccell_set_fg_rgb().

pub fn set_fg_rgb8(
    &mut self,
    red: NcComponent,
    green: NcComponent,
    blue: NcComponent
)

Sets the foreground RGB NcComponents, and marks it as not using the “default color”.

C style function: nccell_set_fg_rgb8().

impl NcCell

NcCell methods: other components

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

Returns true if the two cells have distinct EGCs, attributes, or NcChannels.

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().

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

Saves the NcStyle and the NcChannels, and returns the EGC. (These are the three elements of an NcCell).

C style function: nccell_fg_alpha().

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

Returns the EGC of the NcCell.

See also: extended_gcluster method.

(No equivalent C style function)

pub fn styles(&mut self) -> NcStyle

Returns the NcStyle bits.

C style function: nccell_styles().

pub fn styles_off(&mut self, stylebits: NcStyle)

Removes the specified NcStyle bits.

C style function: nccell_off_styles().

pub fn styles_on(&mut self, stylebits: NcStyle)

Adds the specified NcStyle bits.

C style function: nccell_on_styles().

pub fn styles_set(&mut self, stylebits: NcStyle)

Sets just the specified NcStyle bits.

C style function: nccell_set_styles().

impl NcCell

NcCell methods: text

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

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().

pub fn double_wide_p(&self) -> bool

Does this NcCell contain a wide codepoint?

C style function: nccell_double_wide_p().

pub fn wide_left_p(&self) -> bool

Is this the left half of a wide character?

C style function: nccell_wide_left_p().

pub fn wide_right_p(&self) -> bool

Is this the right side of a wide character?

C style function: nccell_wide_right_p().

impl NcCell

NcCell methods: boxes

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

Loads up six cells with the EGCs necessary to draw a box.

On error, any NcCells this function might have loaded before the error are released. There must be at least six EGCs in gcluster.

C style function: nccells_load_box().

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

NcCell.load_box() with the double box-drawing characters.

C style function: nccells_double_box().

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

NcCell.load_box() with the rounded box-drawing characters.

C style function: nccells_rounded_box().