Struct libnotcurses_sys::c_api::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 fn from_char7b(ch: char) -> NcResult<Self>

New NcCell, expects a 7-bit char.

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

New NcCell, from a char.

Expects a plane where to save the extra data if it’s greater than 4 bytes.

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

New NcCell, from a &str.

Expects a plane where to save the extra data if it’s greater than 4 bytes.

pub 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: impl Into<NcStyle>,
    channels: impl Into<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, common_plane: &mut NcPlane) -> NcResult<NcCell>

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 bchannel(&self) -> NcChannel

Gets the background alpha and coloring bits from the cell NcChannels as an NcChannel.

C style function: nccell_bchannel().

pub fn fchannel(&self) -> NcChannel

Gets the foreground alpha and coloring bits from the cell NcChannels as an NcChannel.

C style function: nccell_fchannel().

pub fn channels(&self) -> NcChannels

Gets the alpha and coloring bits from the cell NcChannels.

C style function: nccell_channels().

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

Sets the background alpha and coloring bits of the cell NcChannels, returning the new NcChannels_u64.

C style function: nccell_bchannel().

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

Sets the foreground alpha and coloring bits from the cell NcChannels, returning the new NcChannels_u64.

C style function: nccell_set_fchannel().

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

Sets the alpha and coloring bits of the cell NcChannels from another NcChannels, returning the new NcChannels.

C style function: nccell_set_channels().

pub fn bg_alpha(&self) -> NcAlpha

Gets the background NcAlpha (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 fg_alpha(&self) -> NcAlpha

Gets the foreground NcAlpha (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 set_bg_alpha(&mut self, alpha: impl Into<NcAlpha>)

Sets the background NcAlpha.

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: impl Into<NcPaletteIndex>)

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

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

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

C style function: nccell_set_bg_rgb().

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

Sets the foreground NcAlpha.

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: impl Into<NcPaletteIndex>)

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

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

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

C style function: nccell_set_fg_rgb().

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: impl Into<NcStyle>)

Removes the specified NcStyle bits.

C style function: nccell_off_styles().

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

Adds the specified NcStyle bits.

C style function: nccell_on_styles().

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

Sets just the specified NcStyle bits.

C style function: nccell_set_styles().

impl nccell

NcCell methods: text

pub const fn cols(&self) -> u8

Returns the number of columns occupied by the cell.

See ncstrwidth for an equivalent for multiple EGCs.

C style function: nccell_cols().

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

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

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: impl Into<NcStyle> + Copy,
    channels: impl Into<NcChannels> + Copy,
    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: 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<()>

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

C style function: nccells_double_box().

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

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

C style function: nccells_rounded_box().

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

NcCell.load_box() with ASCII characters.

C style function: nccells_ascii_box().

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

NcCell.load_box() with the heavy line box-drawing characters.

C style function: nccells_heavy_box().

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

NcCell.load_box() with the light line box-drawing characters.

C style function: nccells_light_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.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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.

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

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

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

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

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

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

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