Archives
/
notcurses
mirror of https://github.com/dankamongmen/notcurses
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

rust: continue reworking the API & improve documentation

Browse Source 
- 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.
dankamongmen/clock_nanosleep_portable
joseLuís 4 years ago
parent 219bc34128
commit 7a164c3009
7 changed files with 189 additions and 81 deletions
Show Stats Download Patch File Download Diff File

17
rust/src/bindings.rs
Unescape Escape View File

@ -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)]

34
rust/src/macros.rs
Unescape Escape View File

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

73
rust/src/types/channel.rs
Unescape Escape View File

@ -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;

72
rust/src/types/colors.rs
Unescape Escape View File

@ -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;

43
rust/src/types/misc.rs
Unescape Escape View File

@ -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

25
rust/src/types/mod.rs
Unescape Escape View File

@ -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;

6
rust/src/types/plane.rs
Unescape Escape View File

@ -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;

Write Preview
Loading…
Cancel
Save