Type Definition libnotcurses_sys::NcChannels

pub type NcChannels = u64;

64 bits containing a foreground and background NcChannel (alias of u64).

At render time, both 24-bit NcRgb values are quantized down to terminal capabilities, if necessary. There’s a clear path to 10-bit support should we one day need it.

Default Color

The “default color” is best explained by color(3NCURSES) and default_colors(3NCURSES). Ours is the same concept.

Until the “not default color” bit is set, any color you load will be ignored.

Diagram

~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB║~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
↑↑↑↑↑↑↑↑↑↑↑↑ foreground ↑↑↑↑↑↑↑↑↑↑↑║↑↑↑↑↑↑↑↑↑↑↑↑ background ↑↑↑↑↑↑↑↑↑↑↑

Detailed info (specially on the context-dependent bits on each NcChannel’s 4th byte):

                            ~foreground channel~
reserved, must be 0                                  ↓bits view↓               ↓hex mask↓
0·······|········|········|········║········|········|········|········  =  8·······|········

NcChannels::FG_DEFAULT_MASK: foreground is NOT "default color"
·1······|········|········|········║········|········|········|········  =  4·······|········

NcChannels::FG_ALPHA_MASK: foreground alpha (2bits)
··11····|········|········|········║········|········|········|········  =  3·······|········

NcChannels::FG_PALETTE: foreground uses palette index
····1···|········|········|········║········|········|········|········  =  ·8······|········

NcChannels::NOBACKGROUND_MASK: glyph is entirely foreground
·····1··|········|········|········║········|········|········|········  =  ·4······|········

reserved, must be 0
······00|········|········|········║········|········|········|········  =  ·3······|········

NcChannels::FG_RGB_MASK: foreground in 3x8 RGB (rrggbb)
········|11111111|11111111|11111111║········|········|········|········  =  ··FFFFFF|········

                            ~background channel~
reserved, must be 0                                  ↓bits view↓               ↓hex mask↓
········|········|········|········║0·······|········|········|········  =  ········|8·······

NcChannels::BGDEFAULT_MASK: background is NOT "default color"
········|········|········|········║·1······|········|········|········  =  ········|4·······

NcChannels::BG_ALPHA_MASK: background alpha (2 bits)
········|········|········|········║··11····|········|········|········  =  ········|3·······

NcChannels::BG_PALETTE: background uses palette index
········|········|········|········║····1···|········|········|········  =  ········|·8······

reserved, must be 0
········|········|········|········║·····000|········|········|········  =  ········|·7······

NcChannels::BG_RGB_MASK: background in 3x8 RGB (rrggbb)
········|········|········|········║········|11111111|11111111|11111111  =  ········|··FFFFFF

type in C: channels (uint64_t)

NcChannels Mask Flags

• NcChannels::BG_DEFAULT_MASK
• NcChannels::BG_ALPHA_MASK
• NcChannels::BG_PALETTE
• NcChannels::BG_RGB_MASK
• NcChannels::FG_DEFAULT_MASK
• NcChannels::FG_ALPHA_MASK
• NcChannels::FG_PALETTE
• NcChannels::FG_RGB_MASK

Trait Implementations

impl NcChannelsApi for NcChannels

NcChannels Methods

const BG_DEFAULT_MASK: u32

If this bit is set, we are not using the default background color.

See the detailed diagram at NcChannels

const BG_ALPHA_MASK: u32

Extract these bits to get the background NcAlpha mask.

See the detailed diagram at NcChannels

const BG_PALETTE_MASK: u32

If this bit and BG_DEFAULT_MASK are set, we’re using a palette-indexed background color.

See the detailed diagram at NcChannels

const BG_RGB_MASK: u32

Extract these bits to get the background NcRgb value.

fn new() -> Self

New NcChannels, set to black and NOT using the “default color”.

fn with_default() -> Self

New NcChannels, set to black and using the “default color”.

fn from_rgb(fg_rgb: NcRgb, bg_rgb: NcRgb) -> Self

New NcChannels, expects two separate NcRgbs for the foreground and background channels.

fn from_rgb_both(rgb: NcRgb) -> Self

New NcChannels, expects a single NcRgb for both foreground and background channels.

fn from_rgb_alpha(
    fg_rgb: NcRgb,
    fg_alpha: NcAlpha,
    bg_rgb: NcRgb,
    bg_alpha: NcAlpha
) -> Self

New NcChannels, expects two separate NcRgb & NcAlpha for the foreground and background channels.

fn from_rgb_alpha_both(rgb: NcRgb, alpha: NcAlpha) -> Self

New NcChannels, expects NcRgb & NcAlpha for both channels.

fn from_rgb8(
    fg_r: NcComponent,
    fg_g: NcComponent,
    fg_b: NcComponent,
    bg_r: NcComponent,
    bg_g: NcComponent,
    bg_b: NcComponent
) -> Self

New NcChannels, expects three RGB NcComponent components for each channel.

fn from_rgb8_both(r: NcComponent, g: NcComponent, b: NcComponent) -> Self

New NcChannels, expects three RGB NcComponent components for both the foreground and background channels.

fn from_rgb8_alpha(
    fg_r: NcComponent,
    fg_g: NcComponent,
    fg_b: NcComponent,
    fg_alpha: NcAlpha,
    bg_r: NcComponent,
    bg_g: NcComponent,
    bg_b: NcComponent,
    bg_alpha: NcAlpha
) -> Self

New NcChannels, expects three RGB NcComponents and NcAlpha, for both the foreground and background channels.

fn from_rgb8_alpha_both(
    r: NcComponent,
    g: NcComponent,
    b: NcComponent,
    alpha: NcAlpha
) -> Self

New NcChannel, expects three RGB NcComponents.

fn combine(fchannel: NcChannel, bchannel: NcChannel) -> Self

Combines two NcChannels into an NcChannels.

C style function: channels_combine().

fn reverse(&mut self) -> Self

Returns the NcChannels with the fore- and background’s color information swapped, but without touching housekeeping bits.

Alpha is retained unless it would lead to an illegal state: HIGHCONTRAST, TRANSPARENT and BLEND are taken to OPAQUE unless the new value is RGB.

HIGHCONTRAST TRANSPARENT BLEND OPAQUE

C style function: ncchannels_reverse().

fn fchannel(&self) -> NcChannel

Extracts the foreground NcChannel.

C style function: ncchannels_fchannel().

fn bchannel(&self) -> NcChannel

Extracts the background NcChannel.

C style function: ncchannels_bchannel().

fn set_fchannel(&mut self, fchannel: NcChannel) -> Self

Sets the foreground NcChannel.

C style function: ncchannels_set_fchannel().

fn set_bchannel(&mut self, bchannel: NcChannel) -> Self

Sets the background NcChannel.

C style function: ncchannels_set_bchannel().

fn fg_alpha(&self) -> NcAlpha

Gets the foreground NcAlpha.

C style function: ncchannels_fg_alpha().

fn bg_alpha(&self) -> NcAlpha

Gets the background NcAlpha.

C style function: ncchannels_bg_alpha().

fn set_fg_alpha(&mut self, alpha: NcAlpha) -> NcResult<()>

Sets the foreground NcAlpha.

C style function: ncchannels_set_fg_alpha().

fn set_bg_alpha(&mut self, alpha: NcAlpha) -> NcResult<()>

Sets the background NcAlpha.

C style function: ncchannels_set_bg_alpha().

fn fg_rgb_p(&self) -> bool

Returns true if the foreground channel is set to RGB color.

C style function: ncchannels_fg_rgb_p().

fn bg_rgb_p(&self) -> bool

Returns true if the background channel is set to RGB color.

C style function: ncchannels_bg_rgb_p().

fn fg_rgb(&self) -> NcRgb

Gets the foreground NcRgb.

C style function: ncchannels_fg_rgb().

fn bg_rgb(&self) -> NcRgb

Gets the background NcRgb.

C style function: ncchannels_bg_rgb().

fn set_fg_rgb(&mut self, rgb: NcRgb) -> Self

Sets the foreground NcRgb.

C style function: channels_set_fg_rgb().

fn set_bg_rgb(&mut self, rgb: NcRgb) -> Self

Sets the background NcRgb.

C style function: channels_set_bg_rgb().

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

Gets the three foreground RGB NcComponents (r, g, b).

C style function: channels_fg_rgb8().

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

Gets the three background RGB NcComponents (r, g, b).

C style function: channels_bg_rgb8().

fn set_fg_rgb8(
    &mut self,
    r: NcComponent,
    g: NcComponent,
    b: NcComponent
) -> Self

Sets the three foreground RGB NcComponents (r, g, b), and marks the foreground NcChannel as not using the “default color”.

C style function: channels_set_fg_rgb8().

fn set_bg_rgb8(
    &mut self,
    r: NcComponent,
    g: NcComponent,
    b: NcComponent
) -> Self

Sets the three background RGB NcComponents (r, g, b), and marks the background NcChannel as not using the “default color”.

C style function: channels_set_bg_rgb8().

fn fg_r(&self) -> NcComponent

Gets the foreground red NcComponent.

(No equivalent C style function)

fn fg_g(&self) -> NcComponent

Gets the foreground green NcComponent.

(No equivalent C style function)

fn fg_b(&self) -> NcComponent

Gets the foreground blue NcComponent.

(No equivalent C style function)

fn bg_r(&self) -> NcComponent

Gets the background red NcComponent.

(No equivalent C style function)

fn bg_g(&self) -> NcComponent

Gets the background green NcComponent.

(No equivalent C style function)

fn bg_b(&self) -> NcComponent

Gets the background blue NcComponent.

(No equivalent C style function)

fn fg_set_r(&mut self, r: NcComponent) -> Self

Sets the foreground red NcComponent, and returns the new NcChannels.

(No equivalent C style function)

fn fg_set_g(&mut self, g: NcComponent) -> Self

Sets the foreground green NcComponent, and returns the new NcChannels.

(No equivalent C style function)

fn fg_set_b(&mut self, b: NcComponent) -> Self

Sets the foreground blue NcComponent, and returns the new NcChannels.

(No equivalent C style function)

fn bg_set_r(&mut self, r: NcComponent) -> Self

Sets the background red NcComponent, and returns the new NcChannels.

(No equivalent C style function)

fn bg_set_g(&mut self, g: NcComponent) -> Self

Sets the background green NcComponent, and returns the new NcChannels.

(No equivalent C style function)

fn bg_set_b(&mut self, b: NcComponent) -> Self

Sets the background blue NcComponent, and returns the new NcChannels.

(No equivalent C style function)

fn fg_default_p(&self) -> bool

Is the background using the “default background color”?

C style function: channels_fg_default_p().

fn bg_default_p(&self) -> bool

Is the background using the “default background color”?

The “default background color” must generally be used to take advantage of terminal-effected transparency.

C style function: channels_bg_default_p().

fn set_fg_default(&mut self) -> Self

Marks the foreground as using its “default color”, and returns the new NcChannels.

C style function: channels_set_fg_default().

fn set_bg_default(&mut self) -> Self

Marks the background as using its “default color”, and returns the new NcChannels.

C style function: channels_set_bg_default().

fn set_fg_not_default(&mut self) -> Self

Marks the foreground as NOT using its “default color”, and returns the new NcChannels.

C style function: channels_set_fg_default().

fn set_bg_not_default(&mut self) -> Self

Marks the background as NOT using its “default color”, and returns the new NcChannels.

C style function: channels_set_bg_not_default().

fn set_default(&mut self) -> Self

Marks both the foreground and background as using its “default color”, and returns the new NcChannels.

fn set_not_default(&mut self) -> Self

Marks both the foreground and background as NOT using its “default color”, and returns the new NcChannels.

fn fg_palindex(&self) -> NcPaletteIndex

Extracts the NcPaletteIndex from the foreground NcChannel.

C style function: channels_fg_palindex().

fn bg_palindex(&self) -> NcPaletteIndex

Extracts the NcPaletteIndex from the background NcChannel.

C style function: channels_bg_palindex().

fn fg_palindex_p(&self) -> bool

Is the foreground of using an indexed NcPalette color?

C style function: channels_fg_palindex_p().

fn bg_palindex_p(&self) -> bool

Is the background of using an indexed NcPalette color?

C style function: channels_bg_palindex_p().

fn set_fg_palindex(&mut self, index: NcPaletteIndex) -> Self

Sets the foreground of an NcChannels as using an indexed NcPalette color.

C style function: channels_set_fg_palindex().

fn set_bg_palindex(&mut self, index: NcPaletteIndex) -> Self

Sets the background of an NcChannels as using an indexed NcPalette color.

C style function: channels_set_bg_palindex().

const NOBACKGROUND_MASK: u64

Does this glyph completely obscure the background? If so, there’s no need to emit a background when rasterizing, a small optimization. These are also used to track regions into which we must not cellblit.