Crate libnotcurses_sys[−][src]

Expand description

libnotcurses-sys is a low-level Rust wrapper for the notcurses C library

This is a work in progress.

This library is built with several layers of zero-overhead abstractions over the C functions and pointers accessed through FFI.

How to use this library

There are basically two ways: The Rust way, and the C way. (Or a mix of both).

1. The Rust way

Where you use the safely wrapped types, with its methods and constructors, and painless error handling, like this:

Example

use libnotcurses_sys::*;

fn main() -> NcResult<()> {
    let mut nc = Nc::with_flags(NCOPTION_NO_ALTERNATE_SCREEN)?;
    let plane = nc.stdplane();
    plane.putstr("hello world")?;
    nc.render()?;
    nc.stop()?;
    Ok(())
}

Although you still have to manually call the stop() method for Nc and NcDirect objects, and the destroy() method for the rest of types that allocate, (like NcPlane, NcVisual…) at the end of their scope, since the Drop trait is not implemented for any wrapping type in libnotcurses-sys.

But they do implement methods and use NcResult as the return type, for handling errors in the way we are used to in Rust.

For the types that don’t allocate, most are based on primitives like i32, u32, u64… without a name in the C library. In Rust they are type aliased (e.g.: NcChannel, NcChannels, NcRgb, NcComponent…), to leverage type checking, and they implement methods through traits (e.g. NcChannelMethods must be in scope to use the NcChannel methods.

2. The C way

You can always use the C API functions directly if you prefer, in a very similar way as the C library is used.

It requires the use of unsafe, since most functions are wrapped directly by bindgen marked as such.

Error handling is done this way by checking the returned NcIntResult, or in case of receiving a pointer, by comparing it to null_mut().

Example

use core::ptr::{null, null_mut};
use std::process::exit;

use libnotcurses_sys::*;

fn main() {
    let options = ffi::notcurses_options {
        termtype: null(),
        renderfp: null_mut(),
        loglevel: 0,
        margin_t: 0,
        margin_r: 0,
        margin_b: 0,
        margin_l: 0,
        flags: NCOPTION_NO_ALTERNATE_SCREEN,
    };
    unsafe {
        let nc = notcurses_init(&options, null_mut());
        if nc.is_null() {
            exit(1);
        }
        let plane = notcurses_stdplane(nc);
        let cols = ncplane_putstr(&mut *plane, "hello world");
        if cols < NCRESULT_OK {
            notcurses_stop(nc);
            exit(cols.abs());
        }
        if notcurses_stop(nc) < NCRESULT_OK {
            exit(2);
        }
    }
}

The `notcurses` C API docs

Modules

ffi	Rust FFI bindings, automatically generated with bindgen.
widgets	All the notcurses widgets.

Macros

nrs	notcurses render sleep: `Nc::render`(`$nc`)? + `sleep![$sleep_args]`.
prs	plane render sleep: `NcPlane::render`(`$p`)? + `NcPlane::rasterize`(`$p`)? + `sleep![$sleep_args]`.
sleep	Sleeps for `$s` seconds + `$ms` milliseconds + `$us` microseconds + `$ns` nanoseconds

Structs

NcError	The error type for the Rust methods API.
NcFile	A wrapper struct around `libc::FILE`
NcPixelGeometry	Contains the pixel geometry information as returned by the NcPlane.pixelgeom() method.

Constants

NCALIGN_CENTER	Center alignment within an `NcPlane` or terminal.
NCALIGN_LEFT	Left alignment within an `NcPlane` or terminal.
NCALIGN_RIGHT	Right alignment within an `NcPlane` or terminal.
NCALIGN_UNALIGNED	Do not align an `NcPlane` or terminal.
NCALPHA_BGDEFAULT_MASK	If this bit is set, we are not using the default background color
NCALPHA_BG_ALPHA_MASK	Extract these bits to get the background alpha mask (`NcAlphaBits`)
NCALPHA_BG_PALETTE	If this bit and `NCALPHA_BGDEFAULT_MASK` are set, we’re using a palette-indexed background color
NCALPHA_BG_RGB_MASK	Extract these bits to get the background `NcRgb` value
NCALPHA_BLEND	`NcAlphaBits` bits indicating `NcCell`’s foreground or background color will be a composite between its color and the `NcCell`s’ corresponding colors underneath it
NCALPHA_FGDEFAULT_MASK	If this bit is set, we are not using the default foreground color
NCALPHA_FG_ALPHA_MASK	Extract these bits to get the foreground alpha mask (`NcAlphaBits`)
NCALPHA_FG_PALETTE	If this bit and `NCALPHA_FGDEFAULT_MASK` are set, we’re using a palette-indexed background color
NCALPHA_FG_RGB_MASK	Extract these bits to get the foreground `NcRgb` value
NCALPHA_HIGHCONTRAST	`NcAlphaBits` bits indicating `NcCell`’s foreground color will be high-contrast (relative to the computed background). Background cannot be highcontrast
NCALPHA_OPAQUE	`NcAlphaBits` bits indicating `NcCell`’s foreground or background color is used unchanged
NCALPHA_TRANSPARENT	`NcAlphaBits` bits indicating `NcCell`’s foreground or background color is derived entirely from the `NcCell`s underneath it
NCBLIT_1x1	`NcBlitter` mode using: space, compatible with ASCII
NCBLIT_2x1	`NcBlitter` mode using: halves + 1x1 (space) ▄▀
NCBLIT_2x2	`NcBlitter` mode using: quadrants + 2x1 ▗▐ ▖▀▟▌▙
NCBLIT_3x2	`NcBlitter` mode using: sextants 🬀🬁🬂🬃🬄🬅🬆🬇🬈🬉🬊🬋🬌🬍🬎🬏🬐🬑🬒🬓🬔🬕🬖🬗🬘🬙🬚🬛🬜🬝🬞🬟🬠🬡🬢🬣🬤🬥🬦🬧🬨🬩🬪🬫🬬🬭🬮🬯🬰🬱🬲🬳🬴🬵🬶🬷🬸🬹🬺🬻
NCBLIT_4x1	`NcBlitter` mode using: four vertical levels █▆▄▂
NCBLIT_8x1	`NcBlitter` mode using: eight vertical levels █▇▆▅▄▃▂▁
NCBLIT_BRAILLE	`NcBlitter` mode using: 4 rows, 2 cols (braille) ⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿
NCBLIT_DEFAULT	`NcBlitter` mode where the blitter is automatically chosen
NCBLIT_PIXEL	Sixel/Pixel mode
NCBOXCORNER_MASK	NcBoxMask corner mask to control the drawing of boxes corners.
NCBOXCORNER_SHIFT	The number of bits NCBOXCORNER_MASK is shifted in NcBoxMask.
NCBOXGRAD_BOTTOM	NcBoxMask bottom gradient mask.
NCBOXGRAD_LEFT	NcBoxMask left gradient mask.
NCBOXGRAD_RIGHT	NcBoxMask right gradient mask.
NCBOXGRAD_TOP	NcBoxMask top gradient mask.
NCBOXMASK_BOTTOM	NcBoxMask bottom border mask.
NCBOXMASK_LEFT	NcBoxMask left border mask.
NCBOXMASK_RIGHT	NcBoxMask right border mask.
NCBOXMASK_TOP	NcBoxMask top border mask.
NCCHANNEL_ALPHA_MASK	Extract these bits to get a channel’s alpha value
NCDIRECT_OPTION_INHIBIT_CBREAK	Flag that avoids placing the terminal into cbreak mode (disabling echo and line buffering)
NCDIRECT_OPTION_INHIBIT_SETLOCALE	Flag that avoids calling setlocale(LC_ALL, NULL)
NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS	Flag that inhibits registration of the SIGINT, SIGSEGV, SIGABRT & SIGQUIT signal handlers.
NCDIRECT_OPTION_VERBOSE	Flag that enables showing detailed information.
NCDIRECT_OPTION_VERY_VERBOSE	Flag that enables showing all diagnostics (equivalent to `NCLOGLEVEL_TRACE`). Implies `NCDIRECT_OPTION_VERBOSE`.
NCKEY_BACKSPACE	backspace (sometimes)
NCKEY_BEGIN
NCKEY_BUTTON1
NCKEY_BUTTON2
NCKEY_BUTTON3
NCKEY_BUTTON4	scrollwheel up
NCKEY_BUTTON5	scrollwheel down
NCKEY_BUTTON6
NCKEY_BUTTON7
NCKEY_BUTTON8
NCKEY_BUTTON9
NCKEY_BUTTON10
NCKEY_BUTTON11
NCKEY_CANCEL
NCKEY_CENTER	the most truly neutral of keypresses
NCKEY_CLOSE
NCKEY_CLS	“clear-screen or erase”
NCKEY_COMMAND
NCKEY_COPY
NCKEY_DEL
NCKEY_DLEFT	down + left on keypad
NCKEY_DOWN
NCKEY_DRIGHT
NCKEY_END
NCKEY_ENTER
NCKEY_ESC
NCKEY_EXIT
NCKEY_F00
NCKEY_F01
NCKEY_F02
NCKEY_F03
NCKEY_F04
NCKEY_F05
NCKEY_F06
NCKEY_F07
NCKEY_F08
NCKEY_F09
NCKEY_F10
NCKEY_F11
NCKEY_F12
NCKEY_F13
NCKEY_F14
NCKEY_F15
NCKEY_F16
NCKEY_F17
NCKEY_F18
NCKEY_F19
NCKEY_F20
NCKEY_F21
NCKEY_F22
NCKEY_F23
NCKEY_F24
NCKEY_F25
NCKEY_F26
NCKEY_F27
NCKEY_F28
NCKEY_F29
NCKEY_F30
NCKEY_F31
NCKEY_F32
NCKEY_F33
NCKEY_F34
NCKEY_F35
NCKEY_F36
NCKEY_F37
NCKEY_F38
NCKEY_F39
NCKEY_F40
NCKEY_F41
NCKEY_F42
NCKEY_F43
NCKEY_F44
NCKEY_F45
NCKEY_F46
NCKEY_F47
NCKEY_F48
NCKEY_F49
NCKEY_F50
NCKEY_F51
NCKEY_F52
NCKEY_F53
NCKEY_F54
NCKEY_F55
NCKEY_F56
NCKEY_F57
NCKEY_F58
NCKEY_F59
NCKEY_F60
NCKEY_HOME
NCKEY_INS
NCKEY_INVALID
NCKEY_LEFT
NCKEY_PGDOWN
NCKEY_PGUP
NCKEY_PRINT
NCKEY_REFRESH
NCKEY_RELEASE
NCKEY_RESIZE	generated interally in response to SIGWINCH
NCKEY_RETURN
NCKEY_RIGHT
NCKEY_SCROLL_DOWN
NCKEY_SCROLL_UP
NCKEY_SPACE
NCKEY_ULEFT	up + left on keypad
NCKEY_UP
NCKEY_URIGHT
NCLOGLEVEL_DEBUG	this is honestly a bit much
NCLOGLEVEL_ERROR	we can’t keep doin’ this, but we can do other things
NCLOGLEVEL_FATAL	we’re hanging around, but we’ve had a horrible fault
NCLOGLEVEL_INFO	“detailed information
NCLOGLEVEL_PANIC	print diagnostics immediately related to crashing
NCLOGLEVEL_SILENT	default. print nothing once fullscreen service begins
NCLOGLEVEL_TRACE	there’s probably a better way to do what you want
NCLOGLEVEL_VERBOSE	“detailed information
NCLOGLEVEL_WARNING	you probably don’t want what’s happening to happen
NCMETRIC_BPREFIXCOLUMNS
NCMETRIC_BPREFIXSTRLEN
NCMETRIC_IPREFIXCOLUMNS
NCMETRIC_IPREFIXSTRLEN
NCMETRIC_PREFIXCOLUMNS
NCMETRIC_PREFIXSTRLEN
NCOPTION_INHIBIT_SETLOCALE	Do not call setlocale()
NCOPTION_NO_ALTERNATE_SCREEN	Do not enter alternate mode.
NCOPTION_NO_CLEAR_BITMAPS	Do not try to clear any preexisting bitmaps.
NCOPTION_NO_FONT_CHANGES	Do not modify the font.
NCOPTION_NO_QUIT_SIGHANDLERS	Do not handle SIG{ING, SEGV, ABRT, QUIT}.
NCOPTION_NO_WINCH_SIGHANDLER	Do not handle SIGWINCH.
NCOPTION_PRESERVE_CURSOR	Initialize the standard plane’s virtual cursor to match the physical cursor at context creation time.
NCOPTION_SUPPRESS_BANNERS	Do not print banners.
NCPALETTESIZE
NCPLANE_OPTION_HORALIGNED	Horizontal alignment relative to the parent plane. Use NcAlign for ‘x’.
NCPLANE_OPTION_MARGINALIZED	Maximize relative to the parent plane, modulo the provided margins.
NCPLANE_OPTION_VERALIGNED	Vertical alignment relative to the parent plane. Use NcAlign for ‘y’.
NCRESULT_ERR	ERROR value, for the functions that return an `NcIntResult`.
NCRESULT_MAX	MAX value, for the functions that return `NcIntResult`.
NCRESULT_OK	OK value, for the functions that return `NcIntResult`.
NCSCALE_NONE	Maintains original size.
NCSCALE_NONE_HIRES	Maintains original size, admitting high-resolution blitters that don’t preserve aspect ratio.
NCSCALE_SCALE	Maintains aspect ratio.
NCSCALE_SCALE_HIRES	Maintains aspect ratio, admitting high-resolution blitters that don’t preserve aspect ratio.
NCSCALE_STRETCH	Throws away aspect ratio.
NCSTYLE_BLINK
NCSTYLE_BOLD
NCSTYLE_ITALIC
NCSTYLE_MASK
NCSTYLE_NONE
NCSTYLE_STRUCK
NCSTYLE_UNDERCURL
NCSTYLE_UNDERLINE
NCVISUAL_OPTION_ADDALPHA	Treats as transparent the color specified in the `transcolor` field.
NCVISUAL_OPTION_BLEND	Uses `NCALPHA_BLEND` with visual.
NCVISUAL_OPTION_CHILDPLANE	allows you to indicate that the n field of ncvisual_options refers not to the plane onto which you’d like to blit, but the parent of a new plane.
NCVISUAL_OPTION_HORALIGNED	X is an alignment, not absolute.
NCVISUAL_OPTION_NODEGRADE	Fails rather than gracefully degrade. See NcBlitter.
NCVISUAL_OPTION_NOINTERPOLATE	Uses non-interpolative scaling.
NCVISUAL_OPTION_VERALIGNED	Y is an alignment, not absolute.

Statics

APPEND_ONLY	Intended to be passed into the CFile::open method. It will only allow data to be appended to the end of the file.
APPEND_READ	Intended to be passed into the CFile::open method. It will allow data to be appended to the end of the file, and data to be read from the file. It will create the file if it doesn’t exist.
RANDOM_ACCESS_MODE	Intended to be passed into the CFile::open method. It will open the file in a way that will allow reading and writing, including overwriting old data. It will not create the file if it does not exist.
READ_ONLY	Intended to be passed into the CFile::open method. It will only allow reading.
TRUNCATE_RANDOM_ACCESS_MODE	Intended to be passed into the CFile::open method. It will open the file in a way that will allow reading and writing, including overwriting old data. It will create the file if it doesn’t exist
UPDATE	Intended to be passed into the CFile::open method. It will open the file in a way that will allow reading and writing, including overwriting old data
WRITE_ONLY	Intended to be passed into the CFile::open method. It will only allow writing.

Traits

NcChannelMethods	Enables the `NcChannel` methods.
NcChannelsMethods	Enables the `NcChannels` methods.
NcPixelMethods	Enables the NcPixel methods.
NcResizeCbMethods	Enables the NcResizeCb methods.
NcStyleMethods	Enables the `NcStyle` methods.

Functions

ncblit_bgrx ^⚠	Same as ncblit_rgba(), but for BGRx.
ncblit_rgb_loose ^⚠	Supply an alpha value [0..255] to be applied throughout. linesize must be a multiple of 4 for this RGBx data.
ncblit_rgb_packed ^⚠	Supply an alpha value [0..255] to be applied throughout.
ncblit_rgba ^⚠	Blit a flat array ‘data’ of RGBA 32-bit values to the ncplane ‘vopts->n’, which mustn’t be NULL. the blit begins at ‘vopts->y’ and ‘vopts->x’ relative to the specified plane. Each source row ought occupy ‘linesize’ bytes (this might be greater than ‘vopts->lenx’ * 4 due to padding or partial blits). A subregion of the input can be specified with the ‘begy’x’begx’ and ‘leny’x’lenx’ fields from ‘vopts’. Returns the number of pixels blitted, or -1 on error.
nccapability_canchangecolor	Can we set the “hardware” palette?
nccell_bg_alpha	Extracts the background `NcAlphaBits` from an `NcCell` (shifted to LSBs).
nccell_bg_default_p	Is the background `NcChannel` of this `NcCell` using the “default background color”?
nccell_bg_palindex	Gets the `NcPaletteIndex` of the background `NcChannel` of the `NcCell`.
nccell_bg_palindex_p	Is the background `NcChannel` of this `NcCell` using an `NcPaletteIndex` indexed `NcPalette` color?
nccell_bg_rgb	Gets the background `NcRgb` from an `NcCell` (shifted to LSBs).
nccell_bg_rgb8	Gets the background `NcComponent`s of an `NcCell`, and returns the `NcChannel` (which can have some extra bits set).
nccell_cols	Returns the number of columns occupied by ‘c’. see ncstrwidth() for an equivalent for multiple EGCs.
nccell_double_wide_p	Does the `NcCell` contain an East Asian Wide codepoint?
nccell_duplicate ^⚠	Duplicate ‘c’ into ‘targ’; both must be/will be bound to ‘n’. Returns -1 on failure, and 0 on success.
nccell_extended_gcluster ^⚠	return a pointer to the NUL-terminated EGC referenced by ‘c’. this pointer can be invalidated by any further operation on the plane ‘n’, so…watch out!
nccell_extract	Saves the `NcStyle` and the `NcChannels`, and returns the `EGC`, of an `NcCell`.
nccell_fg_alpha	Extracts the foreground `NcAlphaBits` from an `NcCell` (shifted to LSBs).
nccell_fg_default_p	Is the foreground `NcChannel` of this `NcCell` using the “default foreground color”?
nccell_fg_palindex	Gets the `NcPaletteIndex` of the foreground `NcChannel` of the `NcCell`.
nccell_fg_palindex_p	Is the foreground `NcChannel` of this `NcCell` using an `NcPaletteIndex` indexed `NcPalette` color?
nccell_fg_rgb	Gets the foreground `NcRgb` from an `NcCell` (shifted to LSBs).
nccell_fg_rgb8	Gets the foreground `NcComponent`s of an `NcCell`, and returns the `NcChannel` (which can have some extra bits set).
nccell_init	Initializes (zeroes out) an `NcCell`.
nccell_load ^⚠	Breaks the UTF-8 string in ‘gcluster’ down, setting up the nccell ‘c’. Returns the number of bytes copied out of ‘gcluster’, or -1 on failure. The styling of the cell is left untouched, but any resources are released.
nccell_off_styles	Removes the specified `NcStyle` bits from an `NcCell`’s existing spec.
nccell_on_styles	Adds the specified `NcStyle` bits to an `NcCell`’s existing spec., whether they’re actively supported or not.
nccell_prime	Same as `nccell_load`, plus blasts the styling with `style` and `channels`.
nccell_release ^⚠	Release resources held by the nccell ‘c’.
nccell_set_bg_alpha	Sets the background `NcAlphaBits` of an `NcCell`.
nccell_set_bg_default	Indicates to use the “default color” for the background `NcChannel` of an `NcCell`.
nccell_set_bg_palindex	Sets an `NcCell`’s background `NcPaletteIndex`.
nccell_set_bg_rgb	Sets the background `NcRgb` of an `NcCell`, and marks it as not using the default color.
nccell_set_bg_rgb8	Sets the background `NcComponent`s of the `NcCell`, and marks it as not using the “default color”.
nccell_set_fg_alpha	Sets the foreground `NcAlphaBits` of an `NcCell`.
nccell_set_fg_default	Indicates to use the “default color” for the foreground `NcChannel` of an `NcCell`.
nccell_set_fg_palindex	Sets an `NcCell`’s foreground `NcPaletteIndex`.
nccell_set_fg_rgb	Sets the foreground `NcRgb` of an `NcCell`, and marks it as not using the default color.
nccell_set_fg_rgb8	Sets the foreground `NcComponent`s of the `NcCell`, and marks it as not using the “default color”.
nccell_set_styles	Sets just the specified `NcStyle` bits for an `NcCell`, whether they’re actively supported or not.
nccell_strdup	Copies the UTF8-encoded `EGC` out of the `NcCell`, whether simple or complex.
nccell_styles	Extracts the `NcStyle` bits from an `NcCell`.
nccell_wide_left_p	Is this the left half of a wide character?
nccell_wide_right_p	Is this the right half of a wide character?
nccell_width	Deprecated
nccellcmp	Returns true if the two cells are distinct `EGC`s, attributes, or channels.
nccells_double_box ^⚠
nccells_load_box	Loads up six cells with the `EGC`s necessary to draw a box.
nccells_rounded_box ^⚠
ncchannel_alpha	Gets the `NcAlphaBits` from an `NcChannel`.
ncchannel_b	Gets the blue `NcComponent` from an `NcChannel`.
ncchannel_default_p	Is this `NcChannel` using the “default color” rather than RGB/palette-indexed?
ncchannel_g	Gets the green `NcComponent` from an `NcChannel`.
ncchannel_palindex_p	Is this `NcChannel` using palette-indexed color rather than RGB?
ncchannel_r	Gets the red `NcComponent` from an `NcChannel`.
ncchannel_rgb	Gets the `NcRgb` of an `NcChannel`.
ncchannel_rgb8	Gets the three RGB `NcComponent`s from an `NcChannel`, and returns it.
ncchannel_set	Sets the `NcRgb` of an `NcChannel`, and marks it as NOT using the “default color”, retaining the other bits unchanged.
ncchannel_set_alpha	Sets the `NcAlphaBits` of an `NcChannel`.
ncchannel_set_b	Sets the blue `NcComponent` of an `NcChannel`, and returns it.
ncchannel_set_default	Marks an `NcChannel` as using its “default color”, which also marks it opaque.
ncchannel_set_g	Sets the green `NcComponent` of an `NcChannel`, and returns it.
ncchannel_set_not_default	Marks an `NcChannel` as NOT using its “default color”, retaining the other bits unchanged.
ncchannel_set_r	Sets the red `NcComponent` of an `NcChannel`, and returns it.
ncchannel_set_rgb8	Sets the three RGB `NcComponent`s an `NcChannel`, and marks it as NOT using the “default color”, retaining the other bits unchanged.
ncchannels_bchannel	Extracts the background `NcChannel` from a `NcChannels`.
ncchannels_bg_alpha	Gets the background `NcAlphaBits` from an `NcChannels`, shifted to LSBs.
ncchannels_bg_default_p	Is the background using the “default background color”?
ncchannels_bg_palindex_p	Is the background of an `NcChannels` using an indexed `NcPalette` color?
ncchannels_bg_rgb	Gets the background `NcRgb` from an `NcChannels`, shifted to LSBs.
ncchannels_bg_rgb8	Gets the three background RGB `NcComponent`s from an `NcChannels`, and returns the background `NcChannel` (which can have some extra bits set).
ncchannels_combine	Combines two `NcChannel`s into an `NcChannels`.
ncchannels_fchannel	Extracts the foreground `NcChannel` from an `NcChannels`.
ncchannels_fg_alpha	Gets the foreground `NcAlphaBits` from an `NcChannels`, shifted to LSBs.
ncchannels_fg_default_p	Is the foreground of an `NcChannels` using the “default foreground color”?
ncchannels_fg_palindex_p	Is the foreground of an `NcChannels` using an indexed `NcPalette` color?
ncchannels_fg_rgb	Gets the foreground `NcRgb` from an `NcChannels`, shifted to LSBs.
ncchannels_fg_rgb8	Gets the three foreground RGB `NcComponent`s from an `NcChannels`, and returns the foreground `NcChannel` (which can have some extra bits set).
ncchannels_set_bchannel	Sets the background `NcChannel` of an `NcChannels`.
ncchannels_set_bg_alpha	Sets the `NcAlphaBits` of the background `NcChannel` of an `NcChannels`.
ncchannels_set_bg_default	Marks the background of an `NcChannels` as using its “default color”, which also marks it opaque, and returns the new `NcChannels`.
ncchannels_set_bg_not_default	Marks the background of an `NcChannels` as NOT using its “default color”, retaining the other bits unchanged, and returns the new `NcChannels`.
ncchannels_set_bg_palindex	Sets the background of an `NcChannels` as using an indexed `NcPalette` color.
ncchannels_set_bg_rgb	Sets the foreground `NcRgb` of an `NcChannels`, and marks it as NOT using the “default color”, retaining the other bits unchanged.
ncchannels_set_bg_rgb8	Sets the three background RGB `NcComponent`s of an `NcChannels`, and marks it as NOT using the “default color”, retaining the other bits unchanged.
ncchannels_set_default	Marks both the foreground and background of an `NcChannels` as using their “default color”, which also marks them opaque, and returns the new `NcChannels`.
ncchannels_set_fchannel	Sets the foreground `NcChannel` of an `NcChannels`.
ncchannels_set_fg_alpha	Sets the `NcAlphaBits` of the foreground `NcChannel` of an `NcChannels`.
ncchannels_set_fg_default	Marks the foreground of an `NcChannels` as using its “default color”, which also marks it opaque, and returns the new `NcChannels`.
ncchannels_set_fg_not_default	Marks the foreground of an `NcChannels` as NOT using its “default color”, retaining the other bits unchanged, and returns the new `NcChannels`.
ncchannels_set_fg_palindex	Sets the foreground of an `NcChannels` as using an indexed `NcPalette` color.
ncchannels_set_fg_rgb	Sets the foreground `NcRgb` of an `NcChannels`, and marks it as NOT using the “default color”, retaining the other bits unchanged.
ncchannels_set_fg_rgb8	Sets the three foreground RGB `NcComponent`s of an `NcChannels`, and marks it as NOT using the “default color”, retaining the other bits unchanged.
ncchannels_set_not_default	Marks both the foreground and background of an `NcChannels` as NOT using their “default color”, retaining the other bits unchanged, and returns the new `NcChannels`.
ncdirect_box ^⚠	Draw a box with its upper-left corner at the current cursor position, having dimensions \|ylen\|x\|xlen\|. See ncplane_box() for more information. The minimum box size is 2x2, and it cannot be drawn off-screen. \|wchars\| is an array of 6 wide characters: UL, UR, LL, LR, HL, VL.
ncdirect_canbraille	Can we reliably use Unicode Braille?
ncdirect_canchangecolor	Can we set the “hardware” palette? Requires the “ccc” terminfo capability.
ncdirect_canfade	Can we fade? Fading requires either the “rgb” or “ccc” terminfo capability.
ncdirect_canget_cursor ^⚠	Is there support for acquiring the cursor’s current position? Requires the u7 terminfo capability, and that we are connected to an actual terminal.
ncdirect_canhalfblock	Can we reliably use Unicode halfblocks?
ncdirect_canopen_images ^⚠	Can we load images? This requires being built against FFmpeg/OIIO.
ncdirect_canopen_videos	Can we load videos? This requires being built against FFmpeg.
ncdirect_canquadrant	Can we reliably use Unicode quadrants?
ncdirect_cansextant	Can we reliably use Unicode 13 sextants?
ncdirect_cantruecolor	Can we directly specify RGB values per cell, or only use palettes?
ncdirect_canutf8 ^⚠	Is our encoding UTF-8? Requires LANG being set to a UTF8 locale.
ncdirect_capabilities	Returns the detected `NcCapabilities`.
ncdirect_check_pixel_support ^⚠	Can we blit pixel-accurate bitmaps?
ncdirect_clear ^⚠	Clear the screen.
ncdirect_core_init ^⚠	The same as ncdirect_init(), but without any multimedia functionality, allowing for a svelter binary. Link with notcurses-core if this is used.
ncdirect_cursor_disable ^⚠
ncdirect_cursor_down ^⚠
ncdirect_cursor_enable ^⚠
ncdirect_cursor_left ^⚠
ncdirect_cursor_move_yx ^⚠	Move the cursor in direct mode. -1 to retain current location on that axis.
ncdirect_cursor_pop ^⚠
ncdirect_cursor_push ^⚠	Push or pop the cursor location to the terminal’s stack. The depth of this stack, and indeed its existence, is terminal-dependent.
ncdirect_cursor_right ^⚠
ncdirect_cursor_up ^⚠
ncdirect_cursor_yx ^⚠	Get the cursor position, when supported. This requires writing to the terminal, and then reading from it. If the terminal doesn’t reply, or doesn’t reply in a way we understand, the results might be deleterious.
ncdirect_detected_terminal ^⚠	Capabilites
ncdirect_dim_x ^⚠	Get the current number of columns/rows.
ncdirect_dim_y ^⚠
ncdirect_double_box ^⚠	ncdirect_box() with the double box-drawing characters
ncdirect_flush ^⚠	Force a flush. Returns 0 on success, -1 on failure.
ncdirect_getc ^⚠	Deprecated, to be removed for ABI3. Use ncdirect_get() in new code.
ncdirect_getc_blocking	‘input’ may be NULL if the caller is uninterested in event details. Blocks until an event is processed or a signal is received.
ncdirect_getc_nblock	If no event is ready, returns 0.
ncdirect_hline_interp	Draws horizontal lines using the specified NcChannelss, interpolating between them as we go.
ncdirect_init ^⚠	Initialize a direct-mode Notcurses context on the connected terminal at ‘fp’. ‘fp’ must be a tty. You’ll usually want stdout. Direct mode supports a limited subset of Notcurses routines which directly affect ‘fp’, and neither supports nor requires notcurses_render(). This can be used to add color and styling to text in the standard output paradigm. ‘flags’ is a bitmask over NCDIRECT_OPTION_*. Returns NULL on error, including any failure initializing terminfo.
ncdirect_inputready_fd ^⚠	Get a file descriptor suitable for input event poll()ing. When this descriptor becomes available, you can call ncdirect_getc_nblock(), and input ought be ready. This file descriptor is not necessarily the file descriptor associated with stdin (but it might be!).
ncdirect_off_styles ^⚠
ncdirect_on_styles ^⚠
ncdirect_palette_size ^⚠	Returns the number of simultaneous colors claimed to be supported, or 1 if there is no color support. Note that several terminal emulators advertise more colors than they actually support, downsampling internally.
ncdirect_putstr ^⚠	Output the string \|utf8\| according to the channels \|channels\|. Note that ncdirect_putstr() does not explicitly flush output buffers, so it will not necessarily be immediately visible.
ncdirect_raster_frame ^⚠	Takes the result of ncdirect_render_frame() and writes it to the output, freeing it on all paths.
ncdirect_readline ^⚠	Read a (heap-allocated) line of text using the Readline library Initializes Readline the first time it’s called. For input to be echoed to the terminal, it is necessary that NCDIRECT_OPTION_INHIBIT_CBREAK be provided to ncdirect_init(). Returns NULL on error.
ncdirect_render_frame ^⚠	Render an image using the specified blitter and scaling, but do not write the result. The image may be arbitrarily many rows – the output will scroll – but will only occupy the column of the cursor, and those to the right. To actually write (and free) this, invoke ncdirect_raster_frame(). ‘maxx’ and ‘maxy’ (cell geometry, not pixel), if greater than 0, are used for scaling; the terminal’s geometry is otherwise used.
ncdirect_render_image ^⚠	Display an image using the specified blitter and scaling. The image may be arbitrarily many rows – the output will scroll – but will only occupy the column of the cursor, and those to the right. The render/raster process can be split by using ncdirect_render_frame() and ncdirect_raster_frame().
ncdirect_rounded_box ^⚠	ncdirect_box() with the rounded box-drawing characters
ncdirect_set_bg_default ^⚠
ncdirect_set_bg_palindex ^⚠
ncdirect_set_bg_rgb ^⚠
ncdirect_set_bg_rgb8	Sets the background NcComponent components.
ncdirect_set_fg_default ^⚠
ncdirect_set_fg_palindex ^⚠
ncdirect_set_fg_rgb ^⚠	Direct mode. This API can be used to colorize and stylize output generated outside of notcurses, without ever calling notcurses_render(). These should not be intermixed with standard Notcurses rendering.
ncdirect_set_fg_rgb8	Sets the foreground NcComponent components.
ncdirect_set_styles ^⚠	ncplane_styles_*() analogues
ncdirect_stop ^⚠	Release ‘nc’ and any associated resources. 0 on success, non-0 on failure.
ncdirect_stream ^⚠	Load successive frames from a file, invoking ‘streamer’ on each.
ncdirect_styles ^⚠
ncdirect_supported_styles ^⚠	Returns a 16-bit bitmask of supported curses-style attributes (NCSTYLE_UNDERLINE, NCSTYLE_BOLD, etc.) The attribute is only indicated as supported if the terminal can support it together with color. For more information, see the “ncv” capability in terminfo(5).
ncdirect_vline_interp	Draws horizontal lines using the specified NcChannelss, interpolating between them as we go.
ncdirectf_free ^⚠	Free a ncdirectf returned from ncdirectf_from_file().
ncdirectf_from_file ^⚠	Load media from disk, but do not yet render it (presumably because you want to get its geometry via ncdirectf_geom(), or to use the same file with ncdirect_render_loaded_frame() multiple times). You must destroy the result with ncdirectf_free();
ncdirectf_geom ^⚠	Having loaded the frame ‘frame’, get the geometry of a potential render.
ncdirectf_render ^⚠	Same as ncdirect_render_frame(), except ‘frame’ must already have been loaded. A loaded frame may be rendered in different ways before it is destroyed.
ncdplot_add_sample ^⚠
ncdplot_create ^⚠
ncdplot_destroy ^⚠
ncdplot_plane ^⚠
ncdplot_sample ^⚠
ncdplot_set_sample ^⚠
ncfadectx_free ^⚠	Release the resources associated with ‘nctx’.
ncfadectx_iterations ^⚠	Return the number of iterations through which ‘nctx’ will fade.
ncfadectx_setup ^⚠	Rather than the simple ncplane_fade{in/out}(), ncfadectx_setup() can be paired with a loop over ncplane_fade{in/out}_iteration() + ncfadectx_free().
ncfdplane_create ^⚠	Create an ncfdplane around the fd ‘fd’. Consider this function to take ownership of the file descriptor, which will be closed in ncfdplane_destroy().
ncfdplane_destroy ^⚠
ncfdplane_plane ^⚠
ncinput_equal_p	Compares two ncinput structs for data equality by doing a field-by-field comparison for equality (excepting seqnum).
ncinput_nomod_p	Are all the modifiers off (alt, control, shift)?
nckey_mouse_p	Is the event a synthesized mouse event?
nckey_supppuab_p	Is this char a Supplementary Private Use Area-B codepoint?
ncmenu_create ^⚠	Create a menu with the specified options, bound to the specified plane.
ncmenu_destroy ^⚠	Destroy a menu created with ncmenu_create().
ncmenu_item_set_status ^⚠	Disable or enable a menu item. Returns 0 if the item was found.
ncmenu_mouse_selected ^⚠	Return the item description corresponding to the mouse click ‘click’. The item must be on an actively unrolled section, and the click must be in the area of a valid item. If ‘ni’ is not NULL, and the selected item has a shortcut, ‘ni’ will be filled in with the shortcut.
ncmenu_nextitem ^⚠	Move to the previous/next item within the currently unrolled section. If no section is unrolled, the first section will be unrolled.
ncmenu_nextsection ^⚠	Unroll the previous/next section (relative to current unrolled). If no section is unrolled, the first section will be unrolled.
ncmenu_offer_input ^⚠	Offer the input to the ncmenu. If it’s relevant, this function returns true, and the input ought not be processed further. If it’s irrelevant to the menu, false is returned. Relevant inputs include:
ncmenu_plane ^⚠	Return the ncplane backing this ncmenu.
ncmenu_previtem ^⚠
ncmenu_prevsection ^⚠
ncmenu_rollup ^⚠	Roll up any unrolled menu section, and hide the menu if using hiding.
ncmenu_selected ^⚠	Return the selected item description, or NULL if no section is unrolled. If ‘ni’ is not NULL, and the selected item has a shortcut, ‘ni’ will be filled in with that shortcut–this can allow faster matching.
ncmenu_unroll ^⚠	Unroll the specified menu section, making the menu visible if it was invisible, and rolling up any menu section that is already unrolled.
ncmetric	Takes an arbitrarily large number, and prints it into a fixed-size buffer by adding the necessary SI suffix.
ncmultiselector_create ^⚠
ncmultiselector_destroy ^⚠	Destroy the ncmultiselector.
ncmultiselector_offer_input ^⚠	Offer the input to the ncmultiselector. If it’s relevant, this function returns true, and the input ought not be processed further. If it’s irrelevant to the multiselector, false is returned. Relevant inputs include:
ncmultiselector_plane ^⚠	Return a reference to the ncmultiselector’s underlying ncplane.
ncmultiselector_selected ^⚠	Return selected vector. An array of bools must be provided, along with its length. If that length doesn’t match the itemcount, it is an error.
ncpalette_free ^⚠	Free the palette store ‘p’.
ncpalette_get_rgb8	Extracts the RGB `NcComponent`s from an `NcChannel` entry inside an `NcPalette`, and returns the `NcChannel`.
ncpalette_new ^⚠	Create a new palette store. It will be initialized with notcurses’ best knowledge of the currently configured palette. The palette upon startup cannot be reliably detected, sadly.
ncpalette_set	Sets the `NcRgb` value of the `NcChannel` entry inside an `NcPalette`.
ncpalette_set_rgb8	Sets the RGB `NcComponent`s of the `NcChannel` entry inside an `NcPalette`.
ncpalette_use ^⚠	Attempt to configure the terminal with the provided palette ‘p’. Does not transfer ownership of ‘p’; ncpalette_free() can (ought) still be called.
ncpile_bottom ^⚠	Return the bottommost plane of the pile containing ‘n’.
ncpile_create ^⚠	Same as ncplane_create(), but creates a new pile. The returned plane will be the top, bottom, and root of this new pile.
ncpile_rasterize ^⚠	Make the physical screen match the last rendered frame from the pile of which ‘n’ is a part. This is a blocking call. Don’t call this before the pile has been rendered (doing so will likely result in a blank screen).
ncpile_render ^⚠	Renders the pile of which ‘n’ is a part. Rendering this pile again will blow away the render. To actually write out the render, call ncpile_rasterize().
ncpile_top ^⚠	Return the topmost plane of the pile containing ‘n’.
ncpixel	Constructs a libav-compatible ABGR pixel from RGB `NcComponent`s.
ncpixel_a	Extracts the 8-bit alpha `NcComponent` from an ABGR pixel.
ncpixel_b	Extracts the 8 bit blue `NcComponent` from an ABGR pixel.
ncpixel_g	Extracts the 8 bit green `NcComponent` from an ABGR pixel.
ncpixel_r	Extracts the 8 bit red `NcComponent` from an ABGR pixel.
ncpixel_set_a	Sets the 8-bit alpha `NcComponent` of an ABGR pixel.
ncpixel_set_b	Sets the 8-bit blue `NcComponent` of an ABGR pixel.
ncpixel_set_g	Sets the 8-bit green `NcComponent` of an ABGR pixel.
ncpixel_set_r	Sets the 8-bit red `NcComponent` of an ABGR pixel.
ncpixel_set_rgb8	Sets the RGB `NcComponent`s of an ABGR pixel.
ncplane_above ^⚠	Return the plane above this one, or NULL if this is at the top.
ncplane_abs_x ^⚠
ncplane_abs_y ^⚠
ncplane_abs_yx ^⚠	Get the origin of plane ‘n’ relative to its pile. Either or both of ‘x’ and ‘y’ may be NULL.
ncplane_as_rgba ^⚠	Create an RGBA flat array from the selected region of the ncplane ‘nc’. Start at the plane’s ‘begy’x’begx’ coordinate (which must lie on the plane), continuing for ‘leny’x’lenx’ cells. Either or both of ‘leny’ and ‘lenx’ can be specified as -1 to go through the boundary of the plane. Only glyphs from the specified ncblitset may be present. If ‘pxdimy’ and/or ‘pxdimx’ are non-NULL, they will be filled in with the pixel geometry.
ncplane_at_cursor ^⚠	Retrieve the current contents of the cell under the cursor. The EGC is returned, or NULL on error. This EGC must be free()d by the caller. The stylemask and channels are written to ‘stylemask’ and ‘channels’, respectively.
ncplane_at_cursor_cell ^⚠	Retrieve the current contents of the cell under the cursor into ‘c’. This cell is invalidated if the associated plane is destroyed. Returns the number of bytes in the EGC, or -1 on error.
ncplane_at_yx ^⚠	Retrieve the current contents of the specified cell. The EGC is returned, or NULL on error. This EGC must be free()d by the caller. The stylemask and channels are written to ‘stylemask’ and ‘channels’, respectively. The return represents how the cell will be used during rendering, and thus integrates any base cell where appropriate. If called upon the secondary columns of a wide glyph, the EGC will be returned (i.e. this function does not distinguish between the primary and secondary columns of a wide glyph).
ncplane_at_yx_cell ^⚠	Retrieve the current contents of the specified cell into ‘c’. This cell is invalidated if the associated plane is destroyed. Returns the number of bytes in the EGC, or -1 on error. Unlike ncplane_at_yx(), when called upon the secondary columns of a wide glyph, the return can be distinguished from the primary column (nccell_wide_right_p(c) will return true).
ncplane_base ^⚠	Extract the ncplane’s base nccell into ‘c’. The reference is invalidated if ‘ncp’ is destroyed.
ncplane_bchannel	Gets the background NcChannel from an NcPlane.
ncplane_below ^⚠	Return the plane below this one, or NULL if this is at the bottom.
ncplane_bg_alpha	Gets the background NcAlphaBits from the NcPlane, shifted to LSBs.
ncplane_bg_default_p	Is the plane’s background using the “default background color”?
ncplane_bg_rgb	Gets the background NcRgb from an NcPlane, shifted to LSBs.
ncplane_bg_rgb8	Gets the background RGB NcComponents from an NcPlane, and returns the background NcChannel.
ncplane_box ^⚠	Draw a box with its upper-left corner at the current cursor position, and its lower-right corner at ‘ystop’x’xstop’. The 6 cells provided are used to draw the upper-left, ur, ll, and lr corners, then the horizontal and vertical lines. ‘ctlword’ is defined in the least significant byte, where bits [7, 4] are a gradient mask, and [3, 0] are a border mask:
ncplane_box_sized	Draws a box with its upper-left corner at the current cursor position, having dimensions `y_len` * `x_len`.
ncplane_center_abs ^⚠
ncplane_channels	Gets the NcChannels of an NcPlane.
ncplane_contents ^⚠	Create a flat string from the EGCs of the selected region of the ncplane ‘n’. Start at the plane’s ‘begy’x’begx’ coordinate (which must lie on the plane), continuing for ‘leny’x’lenx’ cells. Either or both of ‘leny’ and ‘lenx’ can be specified as -1 to go through the boundary of the plane.
ncplane_create ^⚠	Create a new ncplane bound to plane ‘n’, at the offset ‘y’x’x’ (relative to the origin of ‘n’) and the specified size. The number of ‘rows’ and ‘cols’ must both be positive. This plane is initially at the top of the z-buffer, as if ncplane_move_top() had been called on it. The void* ‘userptr’ can be retrieved (and reset) later. A ‘name’ can be set, used in debugging.
ncplane_cursor_move_yx ^⚠	Move the cursor to the specified position (the cursor needn’t be visible). Pass -1 as either coordinate to hold that axis constant. Returns -1 if the move would place the cursor outside the plane.
ncplane_cursor_yx ^⚠	Get the current position of the cursor within n. y and/or x may be NULL.
ncplane_destroy ^⚠	Destroy the specified ncplane. None of its contents will be visible after the next call to notcurses_render(). It is an error to attempt to destroy the standard plane.
ncplane_dim_x	Gets the columns of the NcPlane.
ncplane_dim_y	Gets the rows of the NcPlane.
ncplane_dim_yx ^⚠	Return the dimensions of this ncplane. y or x may be NULL.
ncplane_double_box	Method: NcPlane.double_box().
ncplane_double_box_sized	Method: NcPlane.double_box_sized().
ncplane_dup ^⚠	Duplicate an existing ncplane. The new plane will have the same geometry, will duplicate all content, and will start with the same rendering state. The new plane will be immediately above the old one on the z axis, and will be bound to the same parent. Bound planes are not duplicated; the new plane is bound to the parent of ‘n’, but has no bound planes.
ncplane_erase ^⚠	Erase every cell in the ncplane (each cell is initialized to the null glyph and the default channels/styles). All cells associated with this ncplane are invalidated, and must not be used after the call, excluding the base cell. The cursor is homed. The plane’s active attributes are unaffected.
ncplane_erase_region ^⚠	Erase every cell in the region starting at {ystart, xstart} and having size {ylen, xlen}. It is an error if any of ystart, xstart, ylen, or xlen is negative. A value of 0 may be provided for ylen and/or xlen, meaning to erase everything along that dimension. It is an error if ystart + ylen or xstart + xlen is not in the plane.
ncplane_fadein ^⚠	Fade the ncplane in over the specified time. Load the ncplane with the target cells without rendering, then call this function. When it’s done, the ncplane will have reached the target levels, starting from zeroes.
ncplane_fadein_iteration ^⚠	Fade in through ‘iter’ iterations, where ‘iter’ < ‘ncfadectx_iterations(nctx)’.
ncplane_fadeout ^⚠	Fade the ncplane out over the provided time, calling ‘fader’ at each iteration. Requires a terminal which supports truecolor, or at least palette modification (if the terminal uses a palette, our ability to fade planes is limited, and affected by the complexity of the rest of the screen).
ncplane_fadeout_iteration ^⚠	Fade out through ‘iter’ iterations, where ‘iter’ < ‘ncfadectx_iterations(nctx)’.
ncplane_fchannel	Gets the foreground NcChannel from an NcPlane.
ncplane_fg_alpha	Gets the foreground NcAlphaBits from the NcPlane, shifted to LSBs.
ncplane_fg_default_p	Is the plane’s foreground using the “default foreground color”?
ncplane_fg_rgb	Gets the foreground NcRgb from an NcPlane, shifted to LSBs.
ncplane_fg_rgb8	Gets the foreground RGB NcComponents from an NcPlane. and returns the background NcChannel.
ncplane_format ^⚠	Set the given style throughout the specified region, keeping content and channels unchanged. Returns the number of cells set, or -1 on failure.
ncplane_gradient	Draws a gradient with its upper-left corner at the current cursor position, stopping at `ystop`×`xstop`.
ncplane_gradient_sized	Draw a gradient with its upper-left corner at the current cursor position, having dimensions `y_len` * `x_len`.
ncplane_greyscale ^⚠	Convert the plane’s content to greyscale.
ncplane_halign	Returns the column at which `cols` columns ought start in order to be aligned according to `align` within this NcPlane.
ncplane_highgradient ^⚠	Do a high-resolution gradient using upper blocks and synced backgrounds. This doubles the number of vertical gradations, but restricts you to half blocks (appearing to be full blocks). Returns the number of cells filled on success, or -1 on error.
ncplane_highgradient_sized ^⚠	ncplane_gradent_sized() meets ncplane_highgradient().
ncplane_hline	Draws horizontal lines using the specified NcCell, starting at the current cursor position.
ncplane_hline_interp ^⚠	Draw horizontal or vertical lines using the specified cell, starting at the current cursor position. The cursor will end at the cell following the last cell output (even, perhaps counter-intuitively, when drawing vertical lines), just as if ncplane_putc() was called at that spot. Return the number of cells drawn on success. On error, return the negative number of cells drawn.
ncplane_home ^⚠	Move the cursor to 0, 0. Can’t fail.
ncplane_mergedown ^⚠	Merge the ncplane ‘src’ down onto the ncplane ‘dst’. This is most rigorously defined as “write to ‘dst’ the frame that would be rendered were the entire stack made up only of the specified subregion of ‘src’ and, below it, the subregion of ‘dst’ having the specified origin. Merging is independent of the position of ‘src’ viz ‘dst’ on the z-axis. It is an error to define a subregion of zero area, or that is not entirely contained within ‘src’. It is an error to define a target origin such that the projected subregion is not entirely contained within ‘dst’. Behavior is undefined if ‘src’ and ‘dst’ are equivalent. ‘dst’ is modified, but ‘src’ remains unchanged. neither ‘src’ nor ‘dst’ may have sprixels.
ncplane_mergedown_simple ^⚠	Merge the entirety of ‘src’ down onto the ncplane ‘dst’. If ‘src’ does not intersect with ‘dst’, ‘dst’ will not be changed, but it is not an error.
ncplane_move_above ^⚠	Splice ncplane ‘n’ out of the z-buffer, and reinsert it above ‘above’. Returns non-zero if ‘n’ is already in the desired location. ‘n’ and ‘above’ must not be the same plane.
ncplane_move_below ^⚠	Splice ncplane ‘n’ out of the z-buffer, and reinsert it below ‘below’. Returns non-zero if ‘n’ is already in the desired location. ‘n’ and ‘below’ must not be the same plane.
ncplane_move_bottom ^⚠
ncplane_move_top ^⚠	Splice ncplane ‘n’ out of the z-buffer, and reinsert it at the top or bottom.
ncplane_move_yx ^⚠	Move this plane relative to the standard plane, or the plane to which it is bound (if it is bound to a plane). It is an error to attempt to move the standard plane.
ncplane_moverel	Moves this `NcPlane` relative to its current location.
ncplane_notcurses ^⚠	Extract the Notcurses context to which this plane is attached.
ncplane_notcurses_const ^⚠
ncplane_off_styles ^⚠	Remove the specified styles from the ncplane’s existing spec.
ncplane_on_styles ^⚠	Add the specified styles to the ncplane’s existing spec.
ncplane_parent ^⚠	Get the plane to which the plane ‘n’ is bound, if any.
ncplane_parent_const ^⚠
ncplane_perimeter	Method: NcPlane.perimeter().
ncplane_perimeter_double	Method: NcPlane.perimeter_double().
ncplane_perimeter_rounded	Method: NcPlane.perimeter_rounded().
ncplane_pixelgeom ^⚠	Retrieve pixel geometry for the display region (‘pxy’, ‘pxx’), each cell (‘celldimy’, ‘celldimx’), and the maximum displayable bitmap (‘maxbmapy’, ‘maxbmapx’). If bitmaps are not supported, ‘maxbmapy’ and ‘maxbmapx’ will be 0. Any of the geometry arguments may be NULL.
ncplane_polyfill_yx ^⚠	Starting at the specified coordinate, if its glyph is different from that of ‘c’, ‘c’ is copied into it, and the original glyph is considered the fill target. We do the same to all cardinally-connected cells having this same fill target. Returns the number of cells polyfilled. An invalid initial y, x is an error. Returns the number of cells filled, or -1 on error.
ncplane_pulse ^⚠	Pulse the plane in and out until the callback returns non-zero, relying on the callback ‘fader’ to initiate rendering. ‘ts’ defines the half-period (i.e. the transition from black to full brightness, or back again). Proper use involves preparing (but not rendering) an ncplane, then calling ncplane_pulse(), which will fade in from black to the specified colors.
ncplane_putc	Calls ncplane_putc_yx() for the current cursor location.
ncplane_putc_yx ^⚠	Replace the cell at the specified coordinates with the provided cell ‘c’, and advance the cursor by the width of the cell (but not past the end of the plane). On success, returns the number of columns the cursor was advanced. ‘c’ must already be associated with ‘n’. On failure, -1 is returned.
ncplane_putchar	Calls ncplane_putchar_yx() at the current cursor location.
ncplane_putchar_stained ^⚠	Replace the EGC underneath us, but retain the styling. The current styling of the plane will not be changed.
ncplane_putchar_yx	Replaces the NcCell at the specified coordinates with the provided char. Advances the cursor by 1.
ncplane_putegc_stained ^⚠	Replace the EGC underneath us, but retain the styling. The current styling of the plane will not be changed.
ncplane_putegc_yx ^⚠	Replace the cell at the specified coordinates with the provided EGC, and advance the cursor by the width of the cluster (but not past the end of the plane). On success, returns the number of columns the cursor was advanced. On failure, -1 is returned. The number of bytes converted from gclust is written to ‘sbytes’ if non-NULL.
ncplane_putnstr	Method: NcPlane.putnstr().
ncplane_putnstr_aligned ^⚠
ncplane_putnstr_yx ^⚠	Write a series of EGCs to the current location, using the current style. They will be interpreted as a series of columns (according to the definition of ncplane_putc()). Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success. On error, a non-positive number is returned, indicating the number of columns which were written before the error. No more than ‘s’ bytes will be written.
ncplane_putstr	Writes a series of `EGC`s to the current location, using the current style.
ncplane_putstr_aligned ^⚠
ncplane_putstr_stained ^⚠	Replace a string’s worth of glyphs at the current cursor location, but retain the styling. The current styling of the plane will not be changed.
ncplane_putstr_yx ^⚠	Write a series of EGCs to the current location, using the current style. They will be interpreted as a series of columns (according to the definition of ncplane_putc()). Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success. On error, a non-positive number is returned, indicating the number of columns which were written before the error.
ncplane_puttext ^⚠	Write the specified text to the plane, breaking lines sensibly, beginning at the specified line. Returns the number of columns written. When breaking a line, the line will be cleared to the end of the plane (the last line will not be so cleared). The number of bytes written from the input is written to ‘bytes’ if it is not NULL. Cleared columns are included in the return value, but not* included in the number of bytes written. Leaves the cursor at the end of output. A partial write will be accomplished as far as it can; determine whether the write completed by inspecting ‘*bytes’. Can output to multiple rows even in the absence of scrolling, but not more rows than are available. With scrolling enabled, arbitrary amounts of data can be emitted. All provided whitespace is preserved – ncplane_puttext() followed by an appropriate ncplane_contents() will read back the original output.
ncplane_putwegc_stained ^⚠	Replace the EGC underneath us, but retain the styling. The current styling of the plane will not be changed.
ncplane_putwstr_stained ^⚠
ncplane_qrcode ^⚠	Draw a QR code at the current position on the plane. If there is insufficient room to draw the code here, or there is any other error, non-zero will be returned. Otherwise, the QR code “version” (size) is returned. The QR code is (version * 4 + 17) columns wide, and ⌈version * 4 + 17⌉ rows tall (the properly-scaled values are written back to ‘ymax’ and ‘xmax’).
ncplane_reparent ^⚠	Plane ‘n’ will be unbound from its parent plane, and will be made a bound child of ‘newparent’. It is an error if ‘n’ or ‘newparent’ are NULL. If ‘newparent’ is equal to ‘n’, ‘n’ becomes the root of a new pile, unless ‘n’ is already the root of a pile, in which case this is a no-op. Returns ‘n’. The standard plane cannot be reparented. Any planes bound to ‘n’ are reparented to the previous parent of ‘n’.
ncplane_reparent_family ^⚠	The same as ncplane_reparent(), except any planes bound to ‘n’ come along with it to its new destination. Their z-order is maintained. If ‘newparent’ is an ancestor of ‘n’, NULL is returned, and no changes are made.
ncplane_resize ^⚠	Resize the specified ncplane. The four parameters ‘keepy’, ‘keepx’, ‘keepleny’, and ‘keeplenx’ define a subset of the ncplane to keep, unchanged. This may be a section of size 0, though none of these four parameters may be negative. ‘keepx’ and ‘keepy’ are relative to the ncplane. They must specify a coordinate within the ncplane’s totality. ‘yoff’ and ‘xoff’ are relative to ‘keepy’ and ‘keepx’, and place the upper-left corner of the resized ncplane. Finally, ‘ylen’ and ‘xlen’ are the dimensions of the ncplane after resizing. ‘ylen’ must be greater than or equal to ‘keepleny’, and ‘xlen’ must be greater than or equal to ‘keeplenx’. It is an error to attempt to resize the standard plane. If either of ‘keepleny’ or ‘keeplenx’ is non-zero, both must be non-zero.
ncplane_resize_marginalized ^⚠	Suitable for use as a ‘resizecb’ with planes created with NCPLANE_OPTION_MARGINALIZED. This will resize the plane ‘n’ against its parent, attempting to enforce the supplied margins.
ncplane_resize_maximize ^⚠	Suitable for use as a ‘resizecb’, this will resize the plane to the visual region’s size. It is used for the standard plane.
ncplane_resize_realign ^⚠	Suitable for use as a ‘resizecb’. This will realign the plane ‘n’ against its parent, using the alignment specified at ncplane_create()-time.
ncplane_resize_simple	Resizes the plane, retaining what data we can (everything, unless we’re shrinking in some dimension). Keep the origin where it is.
ncplane_resizecb ^⚠	Returns the ncplane’s current resize callback.
ncplane_rotate_ccw ^⚠
ncplane_rotate_cw ^⚠	Rotate the plane π/2 radians clockwise or counterclockwise. This cannot be performed on arbitrary planes, because glyphs cannot be arbitrarily rotated. The glyphs which can be rotated are limited: line-drawing characters, spaces, half blocks, and full blocks. The plane must have an even number of columns. Use the ncvisual rotation for a more flexible approach.
ncplane_rounded_box	Method: NcPlane.rounded_box().
ncplane_rounded_box_sized	Method: NcPlane.rounded_box_sized().
ncplane_scrolling_p ^⚠
ncplane_set_base ^⚠	Set the ncplane’s base nccell. It will be used for purposes of rendering anywhere that the ncplane’s gcluster is 0. Note that the base cell is not affected by ncplane_erase(). ‘egc’ must be an extended grapheme cluster. Returns the number of bytes copied out of ‘gcluster’, or -1 on failure.
ncplane_set_base_cell ^⚠	Set the ncplane’s base nccell to ‘c’. The base cell is used for purposes of rendering anywhere that the ncplane’s gcluster is 0. Note that the base cell is not affected by ncplane_erase(). ‘c’ must not be a secondary cell from a multicolumn EGC.
ncplane_set_bchannel	Sets the background NcChannel on an NcPlane, and returns the new NcChannels.
ncplane_set_bg_alpha ^⚠
ncplane_set_bg_default ^⚠
ncplane_set_bg_not_default	Marks the background as NOT using the “default color”, and returns the new NcChannels.
ncplane_set_bg_palindex ^⚠
ncplane_set_bg_rgb ^⚠
ncplane_set_bg_rgb8 ^⚠
ncplane_set_bg_rgb8_clipped ^⚠	Same, but clipped to [0..255].
ncplane_set_channels	Sets the NcChannels of an NcPlane.
ncplane_set_default	Marks both the foreground and background as using the “default color”, and returns the new NcChannels.
ncplane_set_fchannel	Sets the foreground NcChannel on an NcPlane, and returns the new NcChannels.
ncplane_set_fg_alpha ^⚠	Set the alpha parameters for ncplane ‘n’.
ncplane_set_fg_default ^⚠	Use the default color for the foreground/background.
ncplane_set_fg_not_default	Marks the foreground as NOT using the “default color”, and returns the new NcChannels.
ncplane_set_fg_palindex ^⚠	Set the ncplane’s foreground palette index, set the foreground palette index bit, set it foreground-opaque, and clear the foreground default color bit.
ncplane_set_fg_rgb ^⚠	Same, but with rgb assembled into a channel (i.e. lower 24 bits).
ncplane_set_fg_rgb8 ^⚠	Set the current fore/background color using RGB specifications. If the terminal does not support directly-specified 3x8b cells (24-bit “TrueColor”, indicated by the “RGB” terminfo capability), the provided values will be interpreted in some lossy fashion. None of r, g, or b may exceed 255. “HP-like” terminals require setting foreground and background at the same time using “color pairs”; Notcurses will manage color pairs transparently.
ncplane_set_fg_rgb8_clipped ^⚠
ncplane_set_not_default	Marks both the foreground and background as NOT using the “default color”, and returns the new NcChannels.
ncplane_set_resizecb ^⚠	Replace the ncplane’s existing resizecb with ‘resizecb’ (which may be NULL). The standard plane’s resizecb may not be changed.
ncplane_set_scrolling ^⚠	All planes are created with scrolling disabled. Scrolling can be dynamically controlled with ncplane_set_scrolling(). Returns true if scrolling was previously enabled, or false if it was disabled.
ncplane_set_styles ^⚠	Set the specified style bits for the ncplane ‘n’, whether they’re actively supported or not.
ncplane_set_userptr ^⚠	Manipulate the opaque user pointer associated with this plane. ncplane_set_userptr() returns the previous userptr after replacing it with ‘opaque’. the others simply return the userptr.
ncplane_stain ^⚠	Set the given channels throughout the specified region, keeping content and attributes unchanged. Returns the number of cells set, or -1 on failure.
ncplane_styles ^⚠	Return the current styling for this ncplane.
ncplane_styles_off ^⚠
ncplane_styles_on ^⚠
ncplane_styles_set ^⚠
ncplane_translate ^⚠	provided a coordinate relative to the origin of ‘src’, map it to the same absolute coordinate relative to the origin of ‘dst’. either or both of ‘y’ and ‘x’ may be NULL. if ‘dst’ is NULL, it is taken to be the standard plane.
ncplane_translate_abs ^⚠	Fed absolute ‘y’/‘x’ coordinates, determine whether that coordinate is within the ncplane ‘n’. If not, return false. If so, return true. Either way, translate the absolute coordinates relative to ‘n’. If the point is not within ‘n’, these coordinates will not be within the dimensions of the plane.
ncplane_userptr ^⚠
ncplane_valign	Returns the row at which `rows` rows ought start in order to be aligned according to `align` within this NcPlane.
ncplane_vline	Draws vertical lines using the specified NcCell, starting at the current cursor position.
ncplane_vline_interp ^⚠
ncplane_vprintf_aligned ^⚠	The ncplane equivalents of printf(3) and vprintf(3).
ncplane_vprintf_stained ^⚠
ncplane_vprintf_yx ^⚠
ncplane_x ^⚠
ncplane_y ^⚠
ncplane_yx ^⚠	Get the origin of plane ‘n’ relative to its bound plane, or pile (if ‘n’ is a root plane). To get absolute coordinates, use ncplane_abs_yx().
ncprogbar_create ^⚠	Takes ownership of the ncplane ‘n’, which will be destroyed by ncprogbar_destroy(). The progress bar is initially at 0%.
ncprogbar_destroy ^⚠	Destroy the progress bar and its underlying ncplane.
ncprogbar_plane ^⚠	Return a reference to the ncprogbar’s underlying ncplane.
ncprogbar_progress ^⚠	Get the progress bar’s completion, a double on [0, 1].
ncprogbar_set_progress ^⚠	Set the progress bar’s completion, a double 0 <= ‘p’ <= 1.
ncreader_clear ^⚠	empty the ncreader of any user input, and home the cursor.
ncreader_contents ^⚠	return a heap-allocated copy of the current (UTF-8) contents.
ncreader_create ^⚠	ncreaders provide freeform input in a (possibly multiline) region, supporting optional readline keybindings. takes ownership of ‘n’, destroying it on any error (ncreader_destroy() otherwise destroys the ncplane).
ncreader_destroy ^⚠	destroy the reader and its bound plane. if ‘contents’ is not NULL, the UTF-8 input will be heap-duplicated and written to ‘contents’.
ncreader_move_down ^⚠
ncreader_move_left ^⚠	Atttempt to move in the specified direction. Returns 0 if a move was successfully executed, -1 otherwise. Scrolling is taken into account.
ncreader_move_right ^⚠
ncreader_move_up ^⚠
ncreader_offer_input ^⚠	Offer the input to the ncreader. If it’s relevant, this function returns true, and the input ought not be processed further. Almost all inputs are relevant to an ncreader, save synthesized ones.
ncreader_plane ^⚠
ncreader_write_egc ^⚠	Destructively write the provided EGC to the current cursor location. Move the cursor as necessary, scrolling if applicable.
ncreel_add ^⚠	Add a new nctablet to the provided ncreel ‘nr’, having the callback object ‘opaque’. Neither, either, or both of ‘after’ and ‘before’ may be specified. If neither is specified, the new tablet can be added anywhere on the reel. If one or the other is specified, the tablet will be added before or after the specified tablet. If both are specified, the tablet will be added to the resulting location, assuming it is valid (after->next == before->prev); if it is not valid, or there is any other error, NULL will be returned.
ncreel_create ^⚠	Take over the ncplane ‘nc’ and use it to draw a reel according to ‘popts’. The plane will be destroyed by ncreel_destroy(); this transfers ownership.
ncreel_del ^⚠	Delete the tablet specified by t from the ncreel ‘nr’. Returns -1 if the tablet cannot be found.
ncreel_destroy ^⚠	Destroy an ncreel allocated with ncreel_create().
ncreel_focused ^⚠	Return the focused tablet, if any tablets are present. This is not a copy; be careful to use it only for the duration of a critical section.
ncreel_next ^⚠	Change focus to the next tablet, if one exists
ncreel_offer_input ^⚠	Offer input ‘ni’ to the ncreel ‘nr’. If it’s relevant, this function returns true, and the input ought not be processed further. If it’s irrelevant to the reel, false is returned. Relevant inputs include:
ncreel_plane ^⚠	Returns the ncplane on which this ncreel lives.
ncreel_prev ^⚠	Change focus to the previous tablet, if one exists
ncreel_redraw ^⚠	Redraw the ncreel ‘nr’ in its entirety. The reel will be cleared, and tablets will be lain out, using the focused tablet as a fulcrum. Tablet drawing callbacks will be invoked for each visible tablet.
ncreel_tabletcount ^⚠	Return the number of nctablets in the ncreel ‘nr’.
ncresizecb_to_c	Converts NcResizeCb to NcResizeCbUnsafe.
ncresizecb_to_rust	Converts NcResizeCbUnsafe to NcResizeCb.
ncselector_additem ^⚠	Dynamically add or delete items. It is usually sufficient to supply a static list of items via ncselector_options->items.
ncselector_create ^⚠
ncselector_delitem ^⚠
ncselector_destroy ^⚠	Destroy the ncselector. If ‘item’ is not NULL, the last selected option will be strdup()ed and assigned to ‘*item’ (and must be free()d by the caller).
ncselector_nextitem ^⚠
ncselector_offer_input ^⚠	Offer the input to the ncselector. If it’s relevant, this function returns true, and the input ought not be processed further. If it’s irrelevant to the selector, false is returned. Relevant inputs include:
ncselector_plane ^⚠	Return a reference to the ncselector’s underlying ncplane.
ncselector_previtem ^⚠	Move up or down in the list. A reference to the newly-selected item is returned, or NULL if there are no items in the list.
ncselector_selected ^⚠	Return reference to the selected option, or NULL if there are no items.
ncstrwidth ^⚠	Returns the number of columns occupied by a multibyte (UTF-8) string, or -1 if a non-printable/illegal character is encountered. FIXME becomes a static inline in ABI3.
nctablet_plane ^⚠	Access the ncplane associated with nctablet ‘t’, if one exists.
nctablet_userptr ^⚠	Returns a pointer to a user pointer associated with this nctablet.
nctree_create ^⚠	\|opts\| may not be NULL, since it is necessary to define a callback function.
nctree_destroy ^⚠	Destroy the nctree.
nctree_focused ^⚠	Return the focused item, if any items are present. This is not a copy; be careful to use it only for the duration of a critical section.
nctree_goto ^⚠	Go to the item specified by the array \|spec\|, terminated by UINT_MAX. If the spec is invalid, NULL is returned, and the depth of the first invalid spec is written to \|failspec\|. Otherwise, the true depth is written to \|failspec\|, and the curry is returned (\|failspec\| is necessary because the curry could itself be NULL).
nctree_next ^⚠	Change focus to the next item.
nctree_offer_input ^⚠	Offer input ‘ni’ to the nctree ‘n’. If it’s relevant, this function returns true, and the input ought not be processed further. If it’s irrelevant to the tree, false is returned. Relevant inputs include:
nctree_plane ^⚠	Returns the ncplane on which this nctree lives.
nctree_prev ^⚠	Change focus to the previous item.
nctree_redraw ^⚠	Redraw the nctree ‘n’ in its entirety. The tree will be cleared, and items will be lain out, using the focused item as a fulcrum. Item-drawing callbacks will be invoked for each visible item.
ncuplot_add_sample ^⚠	Add to or set the value corresponding to this x. If x is beyond the current x window, the x window is advanced to include x, and values passing beyond the window are lost. The first call will place the initial window. The plot will be redrawn, but notcurses_render() is not called.
ncuplot_create ^⚠	Use the provided plane ‘n’ for plotting according to the options ‘opts’. The plot will make free use of the entirety of the plane. For domain autodiscovery, set miny == maxy == 0. ncuplot holds uint64_ts, while ncdplot holds doubles.
ncuplot_destroy ^⚠
ncuplot_plane ^⚠	Return a reference to the ncplot’s underlying ncplane.
ncuplot_sample ^⚠
ncuplot_set_sample ^⚠
ncvisual_at_yx ^⚠	Get the specified pixel from the specified ncvisual.
ncvisual_blitter_geom ^⚠	Get the size and ratio of ncvisual pixels to output cells along the y and x axes. The input size (in pixels) will be written to ‘y’ and ‘x’. The scaling will be written to ‘scaley’ and ‘scalex’. With these: rows = (y / scaley) + !!(y % scaley) or (y + scaley - 1) / scaley cols = (x / scalex) + !!(x % scalex) or (x + scalex - 1) / scalex Returns non-zero for an invalid ‘vopts’. The blitter that will be used is returned in ‘*blitter’.
ncvisual_decode ^⚠	extract the next frame from an ncvisual. returns 1 on end of file, 0 on success, and -1 on failure.
ncvisual_decode_loop ^⚠	decode the next frame ala ncvisual_decode(), but if we have reached the end, rewind to the first frame of the ncvisual. a subsequent ‘ncvisual_render()’ will render the first frame, as if the ncvisual had been closed and reopened. the return values remain the same as those of ncvisual_decode().
ncvisual_destroy ^⚠	Destroy an ncvisual. Rendered elements will not be disrupted, but the visual can be neither decoded nor rendered any further.
ncvisual_from_bgra ^⚠	ncvisual_from_rgba(), but ‘bgra’ is arranged as BGRA. note that this is a byte-oriented layout, despite being bunched in 32-bit pixels; the lowest memory address ought be B, and A is reached by adding 3 to that address.
ncvisual_from_file ^⚠	Open a visual at ‘file’, extract a codec and parameters, decode the first image to memory.
ncvisual_from_plane ^⚠	Promote an ncplane ‘n’ to an ncvisual. The plane may contain only spaces, half blocks, and full blocks. The latter will be checked, and any other glyph will result in a NULL being returned. This function exists so that planes can be subjected to ncvisual transformations. If possible, it’s better to create the ncvisual from memory using ncvisual_from_rgba().
ncvisual_from_rgb_loose ^⚠	ncvisual_from_rgba(), but the pixels are 4-byte RGBx. A is filled in throughout using ‘alpha’. rowstride must be a multiple of 4.
ncvisual_from_rgb_packed ^⚠	ncvisual_from_rgba(), but the pixels are 3-byte RGB. A is filled in throughout using ‘alpha’.
ncvisual_from_rgba ^⚠	Prepare an ncvisual, and its underlying plane, based off RGBA content in memory at ‘rgba’. ‘rgba’ is laid out as ‘rows’ lines, each of which is ‘rowstride’ bytes in length. Each line has ‘cols’ 32-bit 8bpc RGBA pixels followed by possible padding (there will be ‘rowstride’ - ‘cols’ * 4 bytes of padding). The total size of ‘rgba’ is thus (rows * rowstride) bytes, of which (rows * cols * 4) bytes are actual non-padding data.
ncvisual_media_defblitter ^⚠	Get the default media (not plot) blitter for this environment when using the specified scaling method. Currently, this means:
ncvisual_polyfill_yx ^⚠	Polyfill at the specified location within the ncvisual ‘n’, using ‘rgba’.
ncvisual_render ^⚠	Render the decoded frame to the specified ncplane. If one is not provided, one will be created, having the exact size necessary to display the visual. A subregion of the visual can be rendered using ‘begx’, ‘begy’, ‘lenx’, and ‘leny’. Negative values for ‘begy’ or ‘begx’ are an error. It is an error to specify any region beyond the boundaries of the frame. Returns the (possibly newly-created) plane to which we drew.
ncvisual_resize ^⚠	Scale the visual to ‘rows’ X ‘columns’ pixels, using the best scheme available. This is a lossy transformation, unless the size is unchanged.
ncvisual_resize_noninterpolative ^⚠	Scale the visual to ‘rows’ X ‘columns’ pixels, using non-interpolative (naive) scaling. No new colors will be introduced as a result.
ncvisual_rotate ^⚠	Rotate the visual ‘rads’ radians. Only M_PI/2 and -M_PI/2 are supported at the moment, but this will change FIXME.
ncvisual_set_yx ^⚠	Set the specified pixel in the specified ncvisual.
ncvisual_simple_streamer ^⚠	Shut up and display my frames! Provide as an argument to ncvisual_stream(). If you’d like subtitles to be decoded, provide an ncplane as the curry. If the curry is NULL, subtitles will not be displayed.
ncvisual_stream ^⚠	Stream the entirety of the media, according to its own timing. Blocking, obviously. streamer may be NULL; it is otherwise called for each frame, and its return value handled as outlined for streamcb. If streamer() returns non-zero, the stream is aborted, and that value is returned. By convention, return a positive number to indicate intentional abort from within streamer(). ‘timescale’ allows the frame duration time to be scaled. For a visual naturally running at 30FPS, a ‘timescale’ of 0.1 will result in 300FPS, and a ‘timescale’ of 10 will result in 3FPS. It is an error to supply ‘timescale’ less than or equal to 0.
ncvisual_subtitle ^⚠
notcurses_align	Returns the offset into `availcols` at which `cols` ought be output given the requirements of `align`.
notcurses_at_yx ^⚠	Retrieve the contents of the specified cell as last rendered. Returns the EGC or NULL on error. This EGC must be free()d by the caller. The stylemask and channels are written to ‘stylemask’ and ‘channels’, respectively.
notcurses_bottom ^⚠	Return the bottommost ncplane of the standard pile.
notcurses_canbraille ^⚠	Can we reliably use Unicode Braille?
notcurses_canchangecolor ^⚠
notcurses_canfade ^⚠	Can we fade? Fading requires either the “rgb” or “ccc” terminfo capability.
notcurses_canhalfblock ^⚠	Can we reliably use Unicode halfblocks?
notcurses_canopen_images ^⚠	Can we load images? This requires being built against FFmpeg/OIIO.
notcurses_canopen_videos ^⚠	Can we load videos? This requires being built against FFmpeg.
notcurses_canquadrant ^⚠	Can we reliably use Unicode quadrants?
notcurses_cansextant ^⚠	Can we reliably use Unicode 13 sextants?
notcurses_cantruecolor ^⚠	Can we directly specify RGB values per cell, or only use palettes?
notcurses_canutf8 ^⚠	Is our encoding UTF-8? Requires LANG being set to a UTF8 locale.
notcurses_check_pixel_support ^⚠	Can we blit pixel-accurate bitmaps?
notcurses_core_init ^⚠	The same as notcurses_init(), but without any multimedia functionality, allowing for a svelter binary. Link with notcurses-core if this is used.
notcurses_cursor_disable ^⚠	Disable the hardware cursor. It is an error to call this while the cursor is already disabled.
notcurses_cursor_enable ^⚠	Enable or disable the terminal’s cursor, if supported, placing it at ‘y’, ‘x’. Immediate effect (no need for a call to notcurses_render()). It is an error if ‘y’, ‘x’ lies outside the standard plane. Can be called while already visible to move the cursor.
notcurses_cursor_yx ^⚠	Get the current location of the terminal’s cursor, whether visible or not.
notcurses_debug ^⚠	Dump selected Notcurses state to the supplied ‘debugfp’. Output is freeform, newline-delimited, and subject to change. It includes geometry of all planes, from all piles. No line has more than 80 columns’ worth of output.
notcurses_detected_terminal ^⚠	Returns the name (and sometimes version) of the terminal, as Notcurses has been best able to determine.
notcurses_drop_planes ^⚠	Destroy all ncplanes other than the stdplane.
notcurses_getc ^⚠	Backwards-compatibility wrapper; this will be removed for ABI3. Use notcurses_get() in new code.
notcurses_getc_blocking	Blocks until an event is processed or a signal is received.
notcurses_getc_nblock	If no event is ready, returns 0.
notcurses_init ^⚠	Initialize a Notcurses context on the connected terminal at ‘fp’. ‘fp’ must be a tty. You’ll usually want stdout. NULL can be supplied for ‘fp’, in which case /dev/tty will be opened. Returns NULL on error, including any failure initializing terminfo.
notcurses_inputready_fd ^⚠	Get a file descriptor suitable for input event poll()ing. When this descriptor becomes available, you can call notcurses_getc_nblock(), and input ought be ready. This file descriptor is not necessarily the file descriptor associated with stdin (but it might be!).
notcurses_lex_blitter ^⚠	Lex a blitter.
notcurses_lex_margins ^⚠	Lex a margin argument according to the standard Notcurses definition. There can be either a single number, which will define all margins equally, or there can be four numbers separated by commas.
notcurses_lex_scalemode ^⚠	Lex a scaling mode (one of “none”, “stretch”, “scale”, “hires”, “scalehi”, or “inflate”).
notcurses_linesigs_disable ^⚠	Disable signals originating from the terminal’s line discipline, i.e. SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z). They are enabled by default.
notcurses_linesigs_enable ^⚠	Restore signals originating from the terminal’s line discipline, i.e. SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z), if disabled.
notcurses_mouse_disable ^⚠	Disable mouse events. Any events in the input queue can still be delivered.
notcurses_mouse_enable ^⚠	Enable the mouse in “button-event tracking” mode with focus detection and UTF8-style extended coordinates. On failure, -1 is returned. On success, 0 is returned, and mouse events will be published to notcurses_get().
notcurses_palette_size ^⚠	Returns the number of simultaneous colors claimed to be supported, or 1 if there is no color support. Note that several terminal emulators advertise more colors than they actually support, downsampling internally.
notcurses_refresh ^⚠	Refresh the physical screen to match what was last rendered (i.e., without reflecting any changes since the last call to notcurses_render()). This is primarily useful if the screen is externally corrupted, or if an NCKEY_RESIZE event has been read and you’re not yet ready to render. The current screen geometry is returned in ‘y’ and ‘x’, if they are not NULL.
notcurses_render ^⚠	Renders and rasterizes the standard pile in one shot. Blocking call.
notcurses_render_to_buffer ^⚠
notcurses_render_to_file ^⚠
notcurses_stats ^⚠	Acquire an atomic snapshot of the Notcurses object’s stats.
notcurses_stats_alloc ^⚠	Allocate an ncstats object. Use this rather than allocating your own, since future versions of Notcurses might enlarge this structure.
notcurses_stats_reset ^⚠	Reset all cumulative stats (immediate ones, such as fbbytes, are not reset), first copying them into \|*stats\| (if \|stats\| is not NULL).
notcurses_stddim_yx	notcurses_stdplane(), plus free bonus dimensions written to non-NULL y/x!
notcurses_stddim_yx_const	notcurses_stdplane_const(), plus free bonus dimensions written to non-NULL y/x!
notcurses_stdplane ^⚠	Get a reference to the standard plane (one matching our current idea of the terminal size) for this terminal. The standard plane always exists, and its origin is always at the uppermost, leftmost cell of the terminal.
notcurses_stdplane_const ^⚠
notcurses_stop ^⚠	Destroy a Notcurses context.
notcurses_str_blitter ^⚠	Get the name of a blitter.
notcurses_str_scalemode ^⚠	Get the name of a scaling mode.
notcurses_supported_styles ^⚠	Returns a 16-bit bitmask of supported curses-style attributes (NCSTYLE_UNDERLINE, NCSTYLE_BOLD, etc.) The attribute is only indicated as supported if the terminal can support it together with color. For more information, see the “ncv” capability in terminfo(5).
notcurses_term_dim_yx	Returns our current idea of the terminal dimensions in rows and cols.
notcurses_top ^⚠	Return the topmost ncplane of the standard pile.
notcurses_ucs32_to_utf8 ^⚠	input functions like notcurses_get() return ucs32-encoded uint32_t. convert a series of uint32_t to utf8. result must be at least 4 bytes per input uint32_t (6 bytes per uint32_t will future-proof against Unicode expansion). the number of bytes used is returned, or -1 if passed illegal ucs32, or too small of a buffer.
notcurses_version ^⚠	Get a human-readable string describing the running Notcurses version.
notcurses_version_components ^⚠	Cannot be inline, as we want to get the versions of the actual Notcurses library we loaded, not what we compile against.

Type Definitions

FILE_LIBC	See NcFile. The `libc` crate expects this type of `*FILE` (an opaque enum)
FILE_NC	See NcFile. Notcurses functions expects this type of `*FILE` (a struct)
Nc	The full notcurses context.
NcAlign	Alignment within a plane or terminal. Left/right-justified, or centered.
NcAlphaBits	2 bits of alpha (surrounded by context dependent bits). It is part of an `NcChannel`.
NcBlitter	The blitter mode to use for rasterizing an `NcVisual`.
NcBoxMask	Controls the drawing of borders, gradients and corners.
NcCapabilities	Capabilities, derived from terminfo, environment variables, and queries.
NcCell	A coordinate on an `NcPlane` storing 128 bits of data.
NcChannel	32 bits of context-dependent info containing RGB + 2 bits of alpha + extra
NcChannels	64 bits containing a foreground and background `NcChannel`
NcComponent	8 bits representing an R/G/B color component or an alpha channel component.
NcDim	Represents a dimension in rows or columns. Can’t be negative.
NcDirect	Minimal notcurses instance for styling text.
NcDirectF	A type alias of `NcVisual` (NcDirect Frame) intended to be used with its `ncdirectf_*` methods, in `NcDirect` mode.
NcDirectFlags	Flags (options) for `NcDirect`
NcEgcBackstop	An `u8` always at zero, part of the `NcCell` struct
NcFadeCb	Called for each fade iteration on the NcPlane.
NcFadeCtx	Context for a palette fade operation
NcFdPlane	I/O wrapper to dump file descriptor to `NcPlane`
NcFdPlaneOptions	Options struct for `NcFdPlane`
NcInput	Reads and decodes input events
NcIntResult	The `i32` value used to return errors by the underlying C API.
NcLogLevel	Log level for `NcOptions`
NcOffset	Represents an offset in rows or columns. Can be negative.
NcOptions	Options struct for [`Notcurses`]
NcPalette	NcPalette structure consisting of an array of 256 `NcChannel`s.
NcPaletteIndex	8-bit value used for indexing into a `NcPalette`
NcPixel	An ABGR pixel.
NcPlane	Fundamental drawing surface.
NcPlaneOptions	Options struct for `NcPlane`
NcResizeCb	A callback function called when an NcPlane is resized.
NcResizeCbUnsafe	The unsafe version of NcResizeCb expected by the notcurses C API.
NcResult	The result type for the Rust methods API.
NcRgb	24 bits broken into 3x 8bpp channels.
NcRgba	32 bits broken into 3x 8bpp RGB channels + 8ppp alpha.
NcScale	Indicates how to scale an `NcVisual` during rendering.
NcStats	notcurses runtime statistics
NcStyle	An `u16` of `NCSTYLE_*` boolean styling attribute flags
NcTime
NcVGeom	Describes all geometries of an `NcVisual` ncvisual–both those which are inherent, and those in a given rendering regime.
NcVisual	A visual bit of multimedia.
NcVisualOptions	Options struct for `NcVisual`