From ff2a22a9a95ea84f2353a050a2aa87325fd177f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Mon, 28 Dec 2020 17:59:27 +0100 Subject: [PATCH] rust: Finish adding NcChannel* methods. - make channels_set[f|b]g_rgb() functions (and corresponding methods) return the NcChannelPair, taking advantage of the fact that those functions can't fail in Rust. - documentation fixes. - fix NCSCALE definition typo. --- rust/src/channel/methods.rs | 341 +++++++++++++++++++++++++++++- rust/src/channel/mod.rs | 50 ++--- rust/src/channel/reimplemented.rs | 43 ++-- rust/src/visual.rs | 2 +- 4 files changed, 392 insertions(+), 44 deletions(-) diff --git a/rust/src/channel/methods.rs b/rust/src/channel/methods.rs index d183be853..3657381ee 100644 --- a/rust/src/channel/methods.rs +++ b/rust/src/channel/methods.rs @@ -1,12 +1,14 @@ //! `NcChannel*` methods and associated functions. -use crate::{NcAlphaBits, NcChannel, NcChannelPair, NcColor, NcRgb}; +use crate::{NcAlphaBits, NcChannel, NcChannelPair, NcColor, NcPaletteIndex, NcRgb}; /// Enables the [NcChannel] methods. pub trait NcChannelMethods { fn alpha(&self) -> NcAlphaBits; fn set_alpha(&mut self, alpha: NcAlphaBits); + fn set(&mut self, rgb: NcRgb); + fn rgb8(&self) -> (NcColor, NcColor, NcColor); fn set_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor); fn r(&self) -> NcColor; @@ -22,23 +24,85 @@ pub trait NcChannelMethods { fn default_p(&self) -> bool; fn set_default(&mut self) -> NcChannel; - // + fn palindex_p(&self) -> bool; + + fn fcombine(&self, bchannel: NcChannel) -> NcChannelPair; + fn bcombine(&self, fchannel: NcChannel) -> NcChannelPair; } /// Enables the [NcChannelPair] methods. pub trait NcChannelPairMethods { + fn fchannel(&self) -> NcChannel; + fn bchannel(&self) -> NcChannel; + fn set_fchannel(&mut self, fchannel: NcChannel) -> NcChannelPair; + fn set_bchannel(&mut self, bchannel: NcChannel) -> NcChannelPair; + fn fg_alpha(&self) -> NcAlphaBits; fn bg_alpha(&self) -> NcAlphaBits; fn set_fg_alpha(&mut self, alpha: NcAlphaBits); fn set_bg_alpha(&mut self, alpha: NcAlphaBits); + + fn fg_rgb(&self) -> NcRgb; + fn bg_rgb(&self) -> NcRgb; fn set_fg_rgb(&mut self, alpha: NcAlphaBits); fn set_bg_rgb(&mut self, alpha: NcAlphaBits); + + fn fg_rgb8(&self) -> (NcColor, NcColor, NcColor); + fn bg_rgb8(&self) -> (NcColor, NcColor, NcColor); + fn set_fg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> NcChannelPair; + fn set_bg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> NcChannelPair; + fn fg_r(&self) -> NcColor; + fn fg_g(&self) -> NcColor; + fn fg_b(&self) -> NcColor; + fn bg_r(&self) -> NcColor; + fn bg_g(&self) -> NcColor; + fn bg_b(&self) -> NcColor; + fn fg_set_r(&mut self, r: NcColor) -> NcChannelPair; + fn fg_set_g(&mut self, g: NcColor) -> NcChannelPair; + fn fg_set_b(&mut self, b: NcColor) -> NcChannelPair; + fn bg_set_r(&mut self, r: NcColor) -> NcChannelPair; + fn bg_set_g(&mut self, g: NcColor) -> NcChannelPair; + fn bg_set_b(&mut self, b: NcColor) -> NcChannelPair; + + fn fg_default_p(&self) -> bool; + fn bg_default_p(&self) -> bool; + fn set_fg_default(&mut self) -> NcChannelPair; + fn set_bg_default(&mut self) -> NcChannelPair; + + fn fg_palindex_p(&self) -> bool; + fn bg_palindex_p(&self) -> bool; + fn set_fg_palindex(&mut self, index: NcPaletteIndex); + fn set_bg_palindex(&mut self, index: NcPaletteIndex); + + fn combine(fchannel: NcChannel, bchannel: NcChannel) -> NcChannelPair; } // NcChannel ------------------------------------------------------------------- /// # `NcChannel` Methods impl NcChannelMethods for NcChannel { + // Combine + + /// Combines this [NcChannel] as foreground, with another as background + /// into an [NcChannelPair]. + /// + /// *C style function: [channels_combine()][crate::channels_combine].* + // + // Not in the C API + fn fcombine(&self, bchannel: NcChannel) -> NcChannelPair { + crate::channels_combine(*self, bchannel) + } + + /// Combines this [NcChannel] as background, with another as foreground + /// into an [NcChannelPair]. + /// + /// *C style function: [channels_combine()][crate::channels_combine].* + // + // Not in the C API + fn bcombine(&self, fchannel: NcChannel) -> NcChannelPair { + crate::channels_combine(fchannel, *self) + } + // Alpha /// Gets the [NcAlphaBits]. @@ -55,6 +119,16 @@ impl NcChannelMethods for NcChannel { crate::channel_set_alpha(self, alpha) } + // NcRgb + + /// Sets the [NcRgb], and marks the NcChannel as NOT using the + /// "default color", retaining the other bits unchanged. + /// + /// *C style function: [channel_set()][crate::channel_set].* + fn set(&mut self, rgb: NcRgb) { + crate::channel_set(self, rgb); + } + // NcColor /// Gets the three [NcColor]s. @@ -141,7 +215,7 @@ impl NcChannelMethods for NcChannel { crate::channel_set(self, rgb); } - // Default + // default color /// Is this NcChannel using the "default color" rather than RGB/palette-indexed? /// @@ -156,12 +230,53 @@ impl NcChannelMethods for NcChannel { fn set_default(&mut self) -> NcChannel { crate::channel_set_default(self) } + + // NcPaletteIndex + + /// Is this NcChannel using palette-indexed color rather than RGB? + /// + /// *C style function: [channel_set_default()][crate::channel_set_default].* + fn palindex_p(&self) -> bool { + crate::channel_palindex_p(*self) + } } // NcChannelPair --------------------------------------------------------------- /// # `NcChannelPair` Methods impl NcChannelPairMethods for NcChannelPair { + // NcChannel + + /// Extracts the foreground [NcChannel]. + /// + /// *C style function: [channels_fchannel()][crate::channels_fchannel].* + fn fchannel(&self) -> NcChannel { + crate::channels_fchannel(*self) + } + + /// Extracts the background [NcChannel]. + /// + /// *C style function: [channels_bchannel()][crate::channels_bchannel].* + fn bchannel(&self) -> NcChannel { + crate::channels_bchannel(*self) + } + + /// Sets the foreground [NcChannel]. + /// + /// *C style function: [channels_set_fchannel()][crate::channels_set_fchannel].* + fn set_fchannel(&mut self, fchannel: NcChannel) -> NcChannelPair { + crate::channels_set_fchannel(self, fchannel) + } + + /// Sets the background [NcChannel]. + /// + /// *C style function: [channels_set_bchannel()][crate::channels_set_bchannel].* + fn set_bchannel(&mut self, bchannel: NcChannel) -> NcChannelPair { + crate::channels_set_bchannel(self, bchannel) + } + + // Alpha + /// Gets the foreground [NcAlphaBits]. /// /// *C style function: [channels_fg_alpha()][crate::channels_fg_alpha].* @@ -190,6 +305,22 @@ impl NcChannelPairMethods for NcChannelPair { crate::channels_set_bg_alpha(self, alpha) } + // NcRgb + + /// Gets the foreground [NcRgb]. + /// + /// *C style function: [channels_fg_rgb()][crate::channels_fg_rgb].* + fn fg_rgb(&self) -> NcRgb { + crate::channels_fg_rgb(*self) + } + + /// Gets the background [NcRgb]. + /// + /// *C style function: [channels_bg_rgb()][crate::channels_bg_rgb].* + fn bg_rgb(&self) -> NcRgb { + crate::channels_bg_rgb(*self) + } + /// Sets the foreground [NcRgb]. /// /// *C style function: [channels_set_fg_rgb()][crate::channels_set_fg_rgb].* @@ -203,4 +334,208 @@ impl NcChannelPairMethods for NcChannelPair { fn set_bg_rgb(&mut self, rgb: NcRgb) { crate::channels_set_bg_rgb(self, rgb) } + + // NcColor + + /// Gets the three foreground [NcColor]s (r, g, b). + /// + /// *C style function: [channels_fg_rgb8()][crate::channels_fg_rgb8].* + fn fg_rgb8(&self) -> (NcColor, NcColor, NcColor) { + let (mut r, mut g, mut b) = (0, 0, 0); + crate::channels_fg_rgb8(*self, &mut r, &mut g, &mut b); + (r, g, b) + } + + /// Gets the three background [NcColor]s (r, g, b). + /// + /// *C style function: [channels_bg_rgb8()][crate::channels_bg_rgb8].* + fn bg_rgb8(&self) -> (NcColor, NcColor, NcColor) { + let (mut r, mut g, mut b) = (0, 0, 0); + crate::channels_bg_rgb8(*self, &mut r, &mut g, &mut b); + (r, g, b) + } + + /// Sets the three foreground [NcColor]s (r, g, b), and + /// marks the foreground [NcChannel] as not using the "default color". + /// + /// *C style function: [channels_set_fg_rgb8()][crate::channels_set_fg_rgb8].* + fn set_fg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> NcChannelPair { + crate::channels_set_fg_rgb8(self, r, g, b) + } + + /// Sets the three background [NcColor]s (r, g, b), and + /// marks the background [NcChannel] as not using the "default color". + /// + /// *C style function: [channels_set_bg_rgb8()][crate::channels_set_bg_rgb8].* + fn set_bg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> NcChannelPair { + crate::channels_set_bg_rgb8(self, r, g, b) + } + + /// Gets the foreground red [NcColor]. + /// + /// *(No equivalent C style function)* + fn fg_r(&self) -> NcColor { + crate::channel_r(crate::channels_fchannel(*self)) + } + + /// Gets the foreground green [NcColor]. + /// + /// *(No equivalent C style function)* + fn fg_g(&self) -> NcColor { + crate::channel_g(crate::channels_fchannel(*self)) + } + + /// Gets the foreground blue [NcColor]. + /// + /// *(No equivalent C style function)* + fn fg_b(&self) -> NcColor { + crate::channel_b(crate::channels_fchannel(*self)) + } + + /// Gets the background red [NcColor]. + /// + /// *(No equivalent C style function)* + fn bg_r(&self) -> NcColor { + crate::channel_r(crate::channels_bchannel(*self)) + } + + /// Gets the background green [NcColor]. + /// + /// *(No equivalent C style function)* + fn bg_g(&self) -> NcColor { + crate::channel_g(crate::channels_bchannel(*self)) + } + + /// Gets the background blue [NcColor]. + /// + /// *(No equivalent C style function)* + fn bg_b(&self) -> NcColor { + crate::channel_b(crate::channels_bchannel(*self)) + } + + /// Sets the foreground red [NcColor], and returns the new NcChannelPair. + /// + /// *(No equivalent C style function)* + fn fg_set_r(&mut self, r: NcColor) -> NcChannelPair { + let (_, g, b) = self.bg_rgb8(); + crate::channels_set_fg_rgb8(self, r, g, b) + } + + /// Sets the foreground green [NcColor], and returns the new NcChannelPair. + /// + /// *(No equivalent C style function)* + fn fg_set_g(&mut self, g: NcColor) -> NcChannelPair { + let (r, _, b) = self.bg_rgb8(); + crate::channels_set_fg_rgb8(self, r, g, b) + } + + /// Sets the foreground blue [NcColor], and returns the new NcChannelPair. + /// + /// *(No equivalent C style function)* + fn fg_set_b(&mut self, b: NcColor) -> NcChannelPair { + let (r, g, _) = self.bg_rgb8(); + crate::channels_set_fg_rgb8(self, r, g, b) + } + + /// Sets the background red [NcColor], and returns the new NcChannelPair. + /// + /// *(No equivalent C style function)* + fn bg_set_r(&mut self, r: NcColor) -> NcChannelPair { + let (_, g, b) = self.bg_rgb8(); + crate::channels_set_bg_rgb8(self, r, g, b) + } + + /// Sets the background green [NcColor], and returns the new NcChannelPair. + /// + /// *(No equivalent C style function)* + fn bg_set_g(&mut self, g: NcColor) -> NcChannelPair { + let (r, _, b) = self.bg_rgb8(); + crate::channels_set_bg_rgb8(self, r, g, b) + } + + /// Sets the background blue [NcColor], and returns the new NcChannelPair. + /// + /// *(No equivalent C style function)* + fn bg_set_b(&mut self, b: NcColor) -> NcChannelPair { + let (r, g, _) = self.bg_rgb8(); + crate::channels_set_bg_rgb8(self, r, g, b) + } + + // default color + + /// Is the background using the "default background color"? + /// + /// *C style function: [channels_fg_default_p()][crate::channels_fg_default_p].* + fn fg_default_p(&self) -> bool { + crate::channels_fg_default_p(*self) + } + + /// 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()][crate::channels_bg_default_p].* + fn bg_default_p(&self) -> bool { + crate::channels_bg_default_p(*self) + } + + /// Marks the foreground as using its "default color", and + /// returns the new [NcChannelPair]. + /// + /// *C style function: [channels_set_fg_default()][crate::channels_set_fg_default].* + fn set_fg_default(&mut self) -> NcChannelPair { + crate::channels_set_fg_default(self) + } + + /// Marks the background as using its "default color", and + /// returns the new [NcChannelPair]. + /// + /// *C style function: [channels_set_bg_default()][crate::channels_set_bg_default].* + fn set_bg_default(&mut self) -> NcChannelPair { + crate::channels_set_bg_default(self) + } + + // NcPaletteIndex + + /// Is the foreground of using an [indexed][NcPaletteIndex] + /// [NcPalette][crate::NcPalette] color? + /// + /// *C style function: [channels_fg_palindex_p()][crate::channels_fg_palindex_p].* + fn fg_palindex_p(&self) -> bool { + crate::channels_fg_palindex_p(*self) + } + + /// Is the background of using an [indexed][NcPaletteIndex] + /// [NcPalette][crate::NcPalette] color? + /// + /// *C style function: [channels_bg_palindex_p()][crate::channels_bg_palindex_p].* + fn bg_palindex_p(&self) -> bool { + crate::channels_bg_palindex_p(*self) + } + + /// Sets the foreground of an [NcChannelPair] as using an + /// [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color. + /// + /// *C style function: [channels_set_fg_palindex()][crate::channels_set_fg_palindex].* + fn set_fg_palindex(&mut self, index: NcPaletteIndex) { + crate::channels_set_fg_palindex(self, index) + } + + /// Sets the background of an [NcChannelPair] as using an + /// [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color. + /// + /// *C style function: [channels_set_bg_palindex()][crate::channels_set_bg_palindex].* + fn set_bg_palindex(&mut self, index: NcPaletteIndex) { + crate::channels_set_bg_palindex(self, index) + } + + // Combine + + /// Combines two [NcChannel]s into an [NcChannelPair]. + /// + /// *C style function: [channels_combine()][crate::channels_combine].* + fn combine(fchannel: NcChannel, bchannel: NcChannel) -> NcChannelPair { + crate::channels_combine(fchannel, bchannel) + } } diff --git a/rust/src/channel/mod.rs b/rust/src/channel/mod.rs index 60ac98c92..7e9fd361b 100644 --- a/rust/src/channel/mod.rs +++ b/rust/src/channel/mod.rs @@ -18,47 +18,47 @@ // (X) wont: 3 // (+) done: 36 / 0 // (#) test: 19 -// (W) wrap: 13 +// (W) wrap: 36 // ------------------------------------------ //W# channel_alpha //W# channel_b //W# channel_default_p //W# channel_g -// # channel_palindex_p +//W# channel_palindex_p //W# channel_r //W# channel_rgb8 -// + channel_set +//W+ channel_set //W# channel_set_alpha //W# channel_set_default //W# channel_set_rgb8 -// X channel_set_rgb_clipped --- -// # channels_bchannel +// X channel_set_rgb_clipped // not needed +//W# channels_bchannel //W+ channels_bg_alpha -// + channels_bg_default_p -// # channels_bg_palindex_p -// + channels_bg_rgb -// + channels_bg_rgb8 -// # channels_combine -// # channels_fchannel +//W+ channels_bg_default_p +//W# channels_bg_palindex_p +//W+ channels_bg_rgb +//W+ channels_bg_rgb8 +//W# channels_combine +//W# channels_fchannel //W+ channels_fg_alpha -// + channels_fg_default_p -// # channels_fg_palindex_p -// + channels_fg_rgb -// + channels_fg_rgb8 -// # channels_set_bchannel +//W+ channels_fg_default_p +//W# channels_fg_palindex_p +//W+ channels_fg_rgb +//W+ channels_fg_rgb8 +//W# channels_set_bchannel //W+ channels_set_bg_alpha -// + channels_set_bg_default -// # channels_set_bg_palindex +//W+ channels_set_bg_default +//W# channels_set_bg_palindex //W+ channels_set_bg_rgb -// + channels_set_bg_rgb8 -// X channels_set_bg_rgb8_clipped -// # channels_set_fchannel +//W+ channels_set_bg_rgb8 +// X channels_set_bg_rgb8_clipped // not needed +//W# channels_set_fchannel //W+ channels_set_fg_alpha -// + channels_set_fg_default -// # channels_set_fg_palindex +//W+ channels_set_fg_default +//W# channels_set_fg_palindex //W+ channels_set_fg_rgb -// + channels_set_fg_rgb8 -// X channels_set_fg_rgb8_clipped +//W+ channels_set_fg_rgb8 +// X channels_set_fg_rgb8_clipped // not needed #[cfg(test)] mod test; diff --git a/rust/src/channel/reimplemented.rs b/rust/src/channel/reimplemented.rs index a7db529a1..b3fb40a9a 100644 --- a/rust/src/channel/reimplemented.rs +++ b/rust/src/channel/reimplemented.rs @@ -107,7 +107,7 @@ pub fn channels_set_fchannel(channels: &mut NcChannelPair, fchannel: NcChannel) *channels } -/// Combines two [NcChannel]s into a [NcChannelPair]. +/// Combines two [NcChannel]s into an [NcChannelPair]. /// /// *Method: NcChannelPair.[combine()][NcChannelPair#method.combine]* #[inline] @@ -234,23 +234,39 @@ pub fn channels_bg_rgb8( /// Sets the three foreground RGB [NcColor]s of an [NcChannelPair], and /// marks it as not using the "default color". /// +/// Unlike the original C API, it also returns the new NcChannelPair. +/// /// *Method: NcChannelPair.[set_fg_rgb8()][NcChannelPair#method.set_fg_rgb8]* #[inline] -pub fn channels_set_fg_rgb8(channels: &mut NcChannelPair, r: NcColor, g: NcColor, b: NcColor) { +pub fn channels_set_fg_rgb8( + channels: &mut NcChannelPair, + r: NcColor, + g: NcColor, + b: NcColor, +) -> NcChannelPair { let mut channel = channels_fchannel(*channels); channel_set_rgb8(&mut channel, r, g, b); *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64; + *channels } /// Sets the three background RGB [NcColor]s of an [NcChannelPair], and /// marks it as not using the "default color". /// +/// Unlike the original C API, it also returns the new NcChannelPair. +/// /// *Method: NcChannelPair.[set_bg_rgb8()][NcChannelPair#method.set_bg_rgb8]* #[inline] -pub fn channels_set_bg_rgb8(channels: &mut NcChannelPair, r: NcColor, g: NcColor, b: NcColor) { +pub fn channels_set_bg_rgb8( + channels: &mut NcChannelPair, + r: NcColor, + g: NcColor, + b: NcColor, +) -> NcChannelPair { let mut channel = channels_bchannel(*channels); channel_set_rgb8(&mut channel, r, g, b); channels_set_bchannel(channels, channel); + *channels } // NcRgb ----------------------------------------------------------------------- @@ -259,7 +275,7 @@ pub fn channels_set_bg_rgb8(channels: &mut NcChannelPair, r: NcColor, g: NcColor /// /// *Method: NcChannelPair.[fg_rgb()][NcChannelPair#method.fg_rgb]* #[inline] -pub fn channels_fg_rgb(channels: NcChannelPair) -> NcChannel { +pub fn channels_fg_rgb(channels: NcChannelPair) -> NcRgb { channels_fchannel(channels) & NCCELL_BG_RGB_MASK } @@ -267,7 +283,7 @@ pub fn channels_fg_rgb(channels: NcChannelPair) -> NcChannel { /// /// *Method: NcChannelPair.[bg_rgb()][NcChannelPair#method.bg_rgb]* #[inline] -pub fn channels_bg_rgb(channels: NcChannelPair) -> NcChannel { +pub fn channels_bg_rgb(channels: NcChannelPair) -> NcRgb { channels_bchannel(channels) & NCCELL_BG_RGB_MASK } @@ -341,8 +357,9 @@ pub fn channels_fg_default_p(channels: NcChannelPair) -> bool { channel_default_p(channels_fchannel(channels)) } -/// Is the background using the "default background color"? The "default -/// background color" must generally be used to take advantage of +/// Is the background using the "default background color"? +/// +/// The "default background color" must generally be used to take advantage of /// terminal-effected transparency. /// /// *Method: NcChannelPair.[bg_default_p()][NcChannelPair#method.bg_default_p]* @@ -403,10 +420,8 @@ pub fn channels_bg_palindex_p(channels: NcChannelPair) -> bool { channel_palindex_p(channels_bchannel(channels)) } -/// Sets an [NcCell][crate::NcCell]'s foreground [NcPaletteIndex]. -/// -/// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE], -/// and clears out [NCCELL_FGDEFAULT_MASK]. +/// Sets the foreground of an [NcChannelPair] as using an +/// [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color. /// /// *Method: NcChannelPair.[set_fg_palindex()][NcChannelPair#method.set_fg_palindex]* #[inline] @@ -418,10 +433,8 @@ pub fn channels_set_fg_palindex(channels: &mut NcChannelPair, index: NcPaletteIn *channels |= (index as NcChannelPair) << 32; } -/// Sets an [NcCell][crate::NcCell]'s background [NcPaletteIndex]. -/// -/// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE], -/// and clears out [NCCELL_BGDEFAULT_MASK]. +/// Sets the background of an [NcChannelPair] as using an +/// [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color. /// /// *Method: NcChannelPair.[set_bg_palindex()][NcChannelPair#method.set_bg_palindex]* #[inline] diff --git a/rust/src/visual.rs b/rust/src/visual.rs index 5df1bb013..65fe4e99a 100644 --- a/rust/src/visual.rs +++ b/rust/src/visual.rs @@ -51,7 +51,7 @@ pub const NCSCALE_NONE_HIRES: NcScale = crate::bindings::ffi::ncscale_e_NCSCALE_ /// Maintain aspect ratio, admitting high-resolution blitters /// that don't preserve aspect ratio. -pub const NCSCALE_NONE_HIRES: NcScale = crate::bindings::ffi::ncscale_e_NCSCALE_NONE_HIRES; +pub const NCSCALE_SCALE_HIRES: NcScale = crate::bindings::ffi::ncscale_e_NCSCALE_SCALE_HIRES; /// A visual bit of multimedia opened with LibAV|OIIO pub type NcVisual = crate::bindings::ffi::ncvisual;