Struct libnotcurses_sys::ffi::nccell

#[repr(C)]
pub struct nccell {
    pub gcluster: u32,
    pub gcluster_backstop: u8,
    pub width: u8,
    pub stylemask: u16,
    pub channels: u64,
}

An nccell corresponds to a single character cell on some plane, which can be occupied by a single grapheme cluster (some root spacing glyph, along with possible combining characters, which might span multiple columns). At any cell, we can have a theoretically arbitrarily long UTF-8 EGC, a foreground color, a background color, and an 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.

Multi-column characters can only have a single style/color throughout. Existence is suffering, and thus 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. True display width is a function of the font and terminal. Among the longest Unicode codepoints is

U+FDFD ARABIC LIGATURE BISMILLAH AR-RAHMAN AR-RAHEEM ﷽

wcwidth() rather optimistically claims this most exalted glyph to occupy a single column. BiDi text is too complicated for me to even get into here. Be assured there are no easy answers; ours is indeed a disturbing Universe.

Each nccell 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.

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, its foreground color is used unchanged. If its alpha is 10, its foreground color is derived entirely from cells underneath it. Otherwise, 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 requests high-contrast text (relative to the computed background). A background alpha of 11 is currently forbidden.

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.

This structure is exposed only so that most functions can be inlined. Do not directly modify or access the fields of this structure; use the API.

Fields

gcluster: u32

4B → 4B little endian EGC

gcluster_backstop: u8

1B → 5B (8 bits of zero)

width: u8

1B → 6B (8 bits of EGC column width)

stylemask: u16

2B → 8B (16 bits of NCSTYLE_* attributes)

channels: u64

• 8B == 16B

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

Trait Implementations

impl Clone for nccell

fn clone(&self) -> nccell

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for nccell

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for nccell

fn default() -> nccell

Returns the “default value” for a type.

impl Hash for nccell

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for nccell

fn cmp(&self, other: &nccell) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<nccell> for nccell

fn eq(&self, other: &nccell) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &nccell) -> bool

This method tests for !=.

impl PartialOrd<nccell> for nccell

fn partial_cmp(&self, other: &nccell) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for nccell

impl Eq for nccell

impl StructuralEq for nccell

impl StructuralPartialEq for nccell