From 7a164c30091b4650ff372c310e4e984d360a6bf6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Mon, 9 Nov 2020 19:13:13 +0100 Subject: [PATCH] rust: continue reworking the API & improve documentation - remove macros module and move macros to types submodules. - document the macros. - add ncmetric macros. - add missing constants for NcVisual and ncmetric. - add missing function ncstrwidth - remove types/colors module and move the content to types/channel - add more doc comments. --- rust/src/bindings.rs | 17 +++++++++ rust/src/macros.rs | 34 ++++++++++++++++++ rust/src/types/channel.rs | 73 +++++++++++++++++++++++++++++++++++++++ rust/src/types/colors.rs | 72 -------------------------------------- rust/src/types/misc.rs | 43 +++++++++++++++++++++++ rust/src/types/mod.rs | 25 +++++++++----- rust/src/types/plane.rs | 6 ++++ 7 files changed, 189 insertions(+), 81 deletions(-) delete mode 100644 rust/src/types/colors.rs create mode 100644 rust/src/types/misc.rs diff --git a/rust/src/bindings.rs b/rust/src/bindings.rs index 8214f8b2f..a4ec8a10a 100644 --- a/rust/src/bindings.rs +++ b/rust/src/bindings.rs @@ -29,6 +29,9 @@ pub use bindgen::{ // structs __va_list_tag, timespec, + + // functions + ncstrwidth, }; // blitset --------------------------------------------------------------------- @@ -272,6 +275,16 @@ pub use bindgen::{ // ncmetric -------------------------------------------------------------------- +pub(crate) use bindgen::{ + // constants + PREFIXCOLUMNS, + PREFIXSTRLEN, + BPREFIXCOLUMNS, + BPREFIXSTRLEN, + IPREFIXCOLUMNS, + IPREFIXSTRLEN, +}; + #[doc(inline)] pub use bindgen::{ // structs @@ -586,6 +599,10 @@ pub(crate) use bindgen::{ // structs ncvisual, ncvisual_options, + + // constants + NCVISUAL_OPTION_BLEND, + NCVISUAL_OPTION_NODEGRADE, }; #[doc(inline)] diff --git a/rust/src/macros.rs b/rust/src/macros.rs index 0a9e11f73..035283cfb 100644 --- a/rust/src/macros.rs +++ b/rust/src/macros.rs @@ -1,6 +1,11 @@ #[allow(unused_imports)] + use crate::Cell; +// Cell ------------------------------------------------------------------------ + +/// Initializes a cell providing an [`Egc`](type.Egc.html), +/// a [`StyleMask`](type.StyleMask.html) and [`Channels`](type.Channels.html) #[macro_export] macro_rules! cell_initializer { ( $c:expr, $s:expr, $chan:expr ) => { @@ -14,6 +19,7 @@ macro_rules! cell_initializer { }; } +/// Initializes a cell providing just an [`Egc`](type.Egc.html), #[macro_export] macro_rules! cell_char_initializer { ( $c:expr ) => { @@ -21,9 +27,37 @@ macro_rules! cell_char_initializer { }; } +/// Initializes an empty cell #[macro_export] macro_rules! cell_trivial_initializer { ( ) => { cell_char_initializer![0] }; } + +// ncmetric -------------------------------------------------------------------- + +// /// Used as arguments to a variable field width (i.e. "%*s" -- these are the *). +// /// +// /// We need this convoluted grotesquery to properly handle 'µ'. +// // +// // TODO: TEST +// // +// // NCMETRICFWIDTH(x, cols) ((int)(strlen(x) - ncstrwidth(x) + (cols))) +// #[macro_export] +// macro_rules! NCMETRICFWIDTH { +// ( $x:expr, $cols:expr ) => { +// libc::strlen($x) as i32 - ncstrwidth($x) as i32 + $cols as i32 +// } +// } +// +// Proof of concept as const fn (wont work because strlen call) +// pub const unsafe fn NCMETRICFWIDTH(x: i8, cols: usize) -> usize { +// libc::strlen(&x) - crate::ncstrwidth(&x) as usize + cols +// } + +// #define NCMETRICFWIDTH(x, cols) ((int)(strlen(x) - ncstrwidth(x) + (cols))) +// #define PREFIXFMT(x) NCMETRICFWIDTH((x), PREFIXCOLUMNS), (x) +// #define IPREFIXFMT(x) NCMETRIXFWIDTH((x), IPREFIXCOLUMNS), (x) +// #define BPREFIXFMT(x) NCMETRICFWIDTH((x), BPREFIXCOLUMNS), (x) + diff --git a/rust/src/types/channel.rs b/rust/src/types/channel.rs index ccdef0866..0e8bf7bfb 100644 --- a/rust/src/types/channel.rs +++ b/rust/src/types/channel.rs @@ -98,3 +98,76 @@ pub type AlphaBits = u32; /// `type in C: channels (uint64_t)` /// pub type Channels = u64; + +// Rgb +// +/// 24 bits broken into 3x 8bpp channels. +/// +/// ```txt +/// -------- RRRRRRRR GGGGGGGG BBBBBBBB +/// ``` +/// +/// `type in C: no data type` +/// +pub type Rgb = u32; + +// Color +// +/// 8 bits representing a R/G/B color or alpha channel +/// +/// ```txt +/// CCCCCCCC (1 Byte) +/// ``` +/// +/// `type in C: no data type` +/// +pub type Color = u8; + +// NcPixel (RGBA) +/// 32 bits broken into RGB + 8-bit alpha +/// +/// ```txt +/// AAAAAAAA GGGGGGGG BBBBBBBB RRRRRRRR +/// ``` +/// +/// NcPixel has 8 bits of alpha, more or less linear, contributing +/// directly to the usual alpha blending equation. +/// +/// We map the 8 bits of alpha to 2 bits of alpha via a level function: +/// https://nick-black.com/dankwiki/index.php?title=Notcurses#Transparency.2FContrasting +/// +/// `type in C: ncpixel (uint32_t)` +/// +// NOTE: the order of the colors is different than in Channel. +pub type NcPixel = u32; + +/// Palette structure consisting of an array of 256 [`Channel`](type.Channel.html)s +/// +/// Some terminals only support 256 colors, but allow the full +/// palette to be specified with arbitrary RGB colors. In all cases, it's more +/// performant to use indexed colors, since it's much less data to write to the +/// terminal. If you can limit yourself to 256 colors, that's probably best. +/// +/// `type in C: ncpalette256 (struct)` +/// +pub type Palette = crate::palette256; + +/// 8-bit value used for indexing into a [`Palette`](type.Palette.html) +/// +pub type PaletteIndex = u8; + +/// Context for a palette fade operation +pub type NcFadeCtx = crate::ncfadectx; + +/// the [`Egc`](type.Egc.html)s which form the various levels +/// of a given geometry. +/// +/// If the geometry is wide, things are arranged with the rightmost side +/// increasing most quickly, i.e. it can be indexed as height arrays of +/// 1 + height glyphs. +/// i.e. The first five braille EGCs are all 0 on the left, +/// [0..4] on the right. +/// +/// `type in C: blitset (struct)` +/// +pub type BlitSet = crate::blitset; diff --git a/rust/src/types/colors.rs b/rust/src/types/colors.rs deleted file mode 100644 index e251e0788..000000000 --- a/rust/src/types/colors.rs +++ /dev/null @@ -1,72 +0,0 @@ -// Rgb -// -/// 24 bits broken into 3x 8bpp channels. -/// -/// ```txt -/// -------- RRRRRRRR GGGGGGGG BBBBBBBB -/// ``` -/// -/// `type in C: no data type` -/// -pub type Rgb = u32; - -// Color -// -/// 8 bits representing a R/G/B color or alpha channel -/// -/// ```txt -/// CCCCCCCC (1 Byte) -/// ``` -/// -/// `type in C: no data type` -/// -pub type Color = u8; - -// NcPixel (RGBA) -/// 32 bits broken into RGB + 8-bit alpha -/// -/// ```txt -/// AAAAAAAA GGGGGGGG BBBBBBBB RRRRRRRR -/// ``` -/// -/// NcPixel has 8 bits of alpha, more or less linear, contributing -/// directly to the usual alpha blending equation. -/// -/// We map the 8 bits of alpha to 2 bits of alpha via a level function: -/// https://nick-black.com/dankwiki/index.php?title=Notcurses#Transparency.2FContrasting -/// -/// `type in C: ncpixel (uint32_t)` -/// -// NOTE: the order of the colors is different than in Channel. -pub type NcPixel = u32; - -/// Palette structure consisting of an array of 256 [`Channel`](type.Channel.html)s -/// -/// Some terminals only support 256 colors, but allow the full -/// palette to be specified with arbitrary RGB colors. In all cases, it's more -/// performant to use indexed colors, since it's much less data to write to the -/// terminal. If you can limit yourself to 256 colors, that's probably best. -/// -/// `type in C: ncpalette256 (struct)` -/// -pub type Palette = crate::palette256; - -/// 8-bit value used for indexing into a [`Palette`](type.Palette.html) -/// -pub type PaletteIndex = u8; - -/// Context for a palette fade operation -pub type NcFadeCtx = crate::ncfadectx; - -/// the [`Egc`](type.Egc.html)s which form the various levels -/// of a given geometry. -/// -/// If the geometry is wide, things are arranged with the rightmost side -/// increasing most quickly, i.e. it can be indexed as height arrays of -/// 1 + height glyphs. -/// i.e. The first five braille EGCs are all 0 on the left, -/// [0..4] on the right. -/// -/// `type in C: blitset (struct)` -/// -pub type BlitSet = crate::blitset; diff --git a/rust/src/types/misc.rs b/rust/src/types/misc.rs new file mode 100644 index 000000000..10befa087 --- /dev/null +++ b/rust/src/types/misc.rs @@ -0,0 +1,43 @@ +//! Miscellaneous types and constants +//! + +// error handling -------------------------------------------------------------- + +/// `i32` value used to return errors, when value < 0, (usually -1) +pub type IntResult = i32; + +// ncmetric -------------------------------------------------------------------- + +// TODO: clarify, update and visibilize doc-comments + +// The number of columns is one fewer, as the STRLEN expressions must leave +// an extra byte open in case 'µ' (U+00B5, 0xC2 0xB5) shows up. + +// This is the true number of columns; +// +// to set up a printf()-style maximum field width, +// you should use [IB]PREFIXFMT (see below). +pub const PREFIXCOLUMNS: u32 = crate::bindings::PREFIXCOLUMNS; + +// The maximum number of columns used by a mult == 1000 (standard) +// ncmetric() call. +pub const BPREFIXCOLUMNS: u32 = crate::bindings::BPREFIXCOLUMNS; + +// IPREFIXCOLUMNS is the maximum number of columns used by a mult == 1024 +// (digital information) ncmetric(). +pub const IPREFIXCOLUMNS: u32 = crate::bindings::IPREFIXCOLUMNS; + +// +// Does not include a '\0' (xxx.xxU) +pub const PREFIXSTRLEN: u32 = crate::bindings::PREFIXSTRLEN; + +// The maximum number of columns used by a mult == 1024 call making use of +// the 'i' suffix. +// Does not include a '\0' (xxxx.xxUi), i == prefix +pub const BPREFIXSTRLEN: u32 = crate::bindings::BPREFIXSTRLEN; + +// Does not include a '\0' (xxxx.xxU) +pub const IPREFIXSTRLEN: u32 = crate::bindings::IPREFIXSTRLEN; + +// TODO:? +// WCHAR_MAX_UTF8BYTES diff --git a/rust/src/types/mod.rs b/rust/src/types/mod.rs index bc9347e6e..645c03219 100644 --- a/rust/src/types/mod.rs +++ b/rust/src/types/mod.rs @@ -3,14 +3,19 @@ //! These types wrap the ones used in the C library, including structs, //! constants, and primitives when used as parameters or return values. //! -//! This is in order to enforce type checking when possible and also to follow -//! the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/naming.html) +//! This is in order to: +//! +//! - Enforce type checking. +//! - Follow the +//! [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/naming.html). +//! - Add or improve the doc-comments to the type. +//! - Add constructors to the type aliased structures. //! #![allow(dead_code)] mod cell; mod channel; -mod colors; +mod misc; mod plane; mod terminal; mod widgets; @@ -21,14 +26,19 @@ pub use cell::{ CELL_BG_PALETTE, CELL_BG_RGB_MASK, CELL_FGDEFAULT_MASK, CELL_FG_ALPHA_MASK, CELL_FG_PALETTE, CELL_FG_RGB_MASK, CELL_NOBACKGROUND_MASK, CELL_WIDEASIAN_MASK, }; -pub use channel::{AlphaBits, Channel, Channels, CHANNEL_ALPHA_MASK}; -pub use colors::{BlitSet, Color, NcFadeCtx, NcPixel, Palette, PaletteIndex, Rgb}; +pub use channel::{ + AlphaBits, BlitSet, Channel, Channels, Color, NcFadeCtx, NcPixel, Palette, PaletteIndex, Rgb, + CHANNEL_ALPHA_MASK, +}; +pub use misc::{ + IntResult, PREFIXCOLUMNS, BPREFIXCOLUMNS, IPREFIXCOLUMNS, PREFIXSTRLEN, BPREFIXSTRLEN, IPREFIXSTRLEN +}; pub use plane::{ NCBLIT_1x1, NCBLIT_2x1, NCBLIT_2x2, NCBLIT_3x2, NCBLIT_4x1, NCBLIT_8x1, NcAlign, NcBlitter, NcFdPlane, NcFdPlaneOptions, NcPlane, NcPlaneOptionHoriz, NcPlaneOptions, NcScale, NcVisual, NcVisualOptions, NCALIGN_CENTER, NCALIGN_LEFT, NCALIGN_RIGHT, NCALIGN_UNALIGNED, NCBLIT_BRAILLE, NCBLIT_DEFAULT, NCBLIT_SIXEL, NCPLANE_OPTION_HORALIGNED, NCSCALE_NONE, - NCSCALE_SCALE, NCSCALE_STRETCH, + NCSCALE_SCALE, NCSCALE_STRETCH, NCVISUAL_OPTION_BLEND, NCVISUAL_OPTION_NODEGRADE, }; pub use terminal::{ NcDirect, NcDirectFlags, NcInput, NcLogLevel, Notcurses, NotcursesOptions, @@ -46,6 +56,3 @@ pub use widgets::{ NCREADER_OPTION_NOCMDKEYS, NCREADER_OPTION_VERSCROLL, NCREEL_OPTION_CIRCULAR, NCREEL_OPTION_INFINITESCROLL, }; - -/// `i32` value used to return errors, when value < 0, (usually -1) -pub type IntResult = i32; diff --git a/rust/src/types/plane.rs b/rust/src/types/plane.rs index 9fbccdd72..e4ea2002c 100644 --- a/rust/src/types/plane.rs +++ b/rust/src/types/plane.rs @@ -105,3 +105,9 @@ pub const NCSCALE_STRETCH: NcScale = crate::ncscale_e_NCSCALE_STRETCH; pub type NcVisual = crate::ncvisual; /// Options struct for [`NcVisual`](type.NcVisual.html) pub type NcVisualOptions = crate::ncvisual_options; + +/// Use [`CELL_ALPHA_BLEND`](constant.CELL_ALPHA_BLEND.html) with visual +pub const NCVISUAL_OPTION_BLEND: u32 = crate::bindings::NCVISUAL_OPTION_BLEND; + +/// Fail rather than degrade +pub const NCVISUAL_OPTION_NODEGRADE: u32 = crate::bindings::NCVISUAL_OPTION_NODEGRADE;