Anonymous

Notcurses: Difference between revisions

From dankwiki
(→‎Releases: fix 1.2.0 link)
 
(72 intermediate revisions by the same user not shown)
Line 2: Line 2:
notcurses is a library for building complex, vibrant textual user interfaces (TUIs) on modern terminal emulators. It does not use [[Ncurses]] (though it does make use of libtinfo from that package), nor is it an X/Open Curses source-compatible replacement. It is written in [[C]], with C++-safe headers. [https://crates.io/crates/notcurses Rust], [https://github.com/dankamongmen/notcurses/issues/212 C++], and [https://pypi.org/project/notcurses Python] wrappers are available.
notcurses is a library for building complex, vibrant textual user interfaces (TUIs) on modern terminal emulators. It does not use [[Ncurses]] (though it does make use of libtinfo from that package), nor is it an X/Open Curses source-compatible replacement. It is written in [[C]], with C++-safe headers. [https://crates.io/crates/notcurses Rust], [https://github.com/dankamongmen/notcurses/issues/212 C++], and [https://pypi.org/project/notcurses Python] wrappers are available.


Source and issue-tracking live at [https://github.com/dankamongmen/notcurses Github]. Mailing list is at [https://groups.google.com/forum/#!forum/notcurses GoogleGroups].
Source and issuetracking live at [https://github.com/dankamongmen/notcurses Github]. Mailing list is at [https://groups.google.com/forum/#!forum/notcurses GoogleGroups].


A full [https://nick-black.com/notcurses/ API reference] is just about complete; file bugs on any missing elements. There's also preliminary [https://nick-black.com/notcurses/html Doxygen].
A full [https://nick-black.com/notcurses/ API reference] is available as man pages. Please file bugs on any missing or inaccurate elements. There's also [https://nick-black.com/notcurses/html Doxygen] output.


I published a coherent guidebook, "[https://www.amazon.com/dp/B086PNVNC9 Hacking the Planet! with Notcurses]", in April 2020. More details are available [[Hacking_The_Planet!_with_Notcurses|here]].
I published a coherent textbook, "[https://www.amazon.com/dp/B086PNVNC9 Hacking the Planet! with Notcurses]", in April 2020. More details are available [[Hacking_The_Planet!_with_Notcurses|here]].


I recorded a [[DANKTECH]] video, "[https://www.youtube.com/watch?v=mOmMcFXdd6k Console sex with Notcurses]" as a gentle intro (its demo has been superseded by the [https://www.youtube.com/watch?v=-H1WkopWJNM 1.1.0 demo]). You can run this same demo on your local machine with <tt>[https://nick-black.com/notcurses/notcurses-demo.1.html notcurses-demo]</tt>.
I recorded a [[DANKTECH]] video, "[https://www.youtube.com/watch?v=mOmMcFXdd6k Console sex with Notcurses]" as a gentle intro (its demo has been superseded by the [https://www.youtube.com/watch?v=dcjkezf1ARY NOTCURSES III demo]). You can run this same demo on your local machine with <tt>[https://nick-black.com/notcurses/notcurses-demo.1.html notcurses-demo]</tt>.


==Features==
==Features==
* Advanced and extensive runtime querying for terminal capabilities
* Optional use of "alternate screen" where available (<tt>enter_ca_mode</tt>/<tt>exit_ca_mode</tt> terminfo capabilities)
* Optional use of "alternate screen" where available (<tt>enter_ca_mode</tt>/<tt>exit_ca_mode</tt> terminfo capabilities)
* All APIs use 24-bit 8bpc RGB color natively
* All APIs use 24-bit 8bpc RGB color natively
Line 18: Line 19:
** [[#Sprites|Sprites!]]
** [[#Sprites|Sprites!]]
* Full support for [[#Unicode|Unicode]], including wide glyphs and bidirectional text
* Full support for [[#Unicode|Unicode]], including wide glyphs and bidirectional text
** Composed keys (number pad, etc.) are mapped into [https://unicode.org/charts/PDF/U100000.pdf Private Supplementary Area B]
** Composed keys (number pad, etc.) are mapped outside the defined Unicode regions
* Image/video support via ffmpeg
* Image/video support via ffmpeg or OpenImageIO
* Subregion fade in/out
* Subregion fade in/out, text pulsing
* [[#Linear_interpolation|Linear interpolation]] for coloring geometric objects
* [[#Linear_interpolation|Linear interpolation]] for coloring geometric objects
* Multiple cell and pixel [[#Blitters|blitters]], rotation, and arbitrary scaling


==Rendering==
==Rendering==
[[File:Notcurses-Model.png|Data structures of a Notcurses context|thumb|right]]
The vast majority of functions draw to <tt>ncplane</tt> objects. A partial order (currently a total order) always exists over the planes. There is always at least one plane, the "standard plane". This plane cannot be resized, deleted, moved relative to the visible area, or reparented. Whenever notcurses updates its idea of the visible area's dimensions, it will resize the standard plane (references to the standard plane are <b>not</b> invalidated). Planes may otherwise be any size (invisible regions will not be rendered, and count only against memory), and can be moved to any position relative to the visible area. All planes, including the standard plane, can be freely moved along the z axis.
The vast majority of functions draw to <tt>ncplane</tt> objects. A partial order (currently a total order) always exists over the planes. There is always at least one plane, the "standard plane". This plane cannot be resized, deleted, moved relative to the visible area, or reparented. Whenever notcurses updates its idea of the visible area's dimensions, it will resize the standard plane (references to the standard plane are <b>not</b> invalidated). Planes may otherwise be any size (invisible regions will not be rendered, and count only against memory), and can be moved to any position relative to the visible area. All planes, including the standard plane, can be freely moved along the z axis.


Line 44: Line 47:


==Unicode==
==Unicode==
notcurses understands Unicode wide characters, and accounts for them. It is not possible to split the colors or styling of a wide glyph. It is not possible to print half of a glyph. It is not possible to print a narrow glyph over half of a wide glyph without obliterating the other half. These are all terminal emulator limitations.
Notcurses understands Unicode wide characters, and accounts for them. It is not possible to split the colors or styling of a wide glyph. It is not possible to print half of a glyph. It is not possible to print a narrow glyph over half of a wide glyph without obliterating the other half. These are all terminal emulator limitations.


Whether and how a given Unicode codepoint will be rendered depends almost entirely on font support. In general, <i>with sufficient fonts</i>, emoji and other pictographs will be properly rendered as expected. The Linux console has particularly limited fonts, and most characters beyond ASCII are not reliable in that environment. Certain Unicode glyphs are used by notcurses for drawing. Failure to render these glyphs reasonably will have a negative impact on notcurses functionality. Most important of these are the [https://unicode.org/charts/PDF/U2500.pdf Box Drawing Characters], the [https://unicode.org/charts/PDF/U2580.pdf Block Elements], and the [https://unicode.org/charts/PDF/U2800.pdf Braille Patterns].
Whether and how a given Unicode codepoint will be rendered depends almost entirely on font support. In general, <i>with sufficient fonts</i>, emoji and other pictographs will be properly rendered as expected. The Linux console has particularly limited fonts, and most characters beyond ASCII are not reliable in that environment. Certain Unicode glyphs are used by notcurses for drawing. Failure to render these glyphs reasonably will have a negative impact on notcurses functionality. Most important of these are the [https://unicode.org/charts/PDF/U2500.pdf Box Drawing Characters], the [https://unicode.org/charts/PDF/U2580.pdf Block Elements], and the [https://unicode.org/charts/PDF/U2800.pdf Braille Patterns].
Line 51: Line 54:


notcurses does not currently handle right-to-left text in any special way, but terminals often apply their own heuristics and stylings. Generally this means that a series of glyphs from right-to-left languages will be reversed in the terminal, but this will <b>not</b> be detectable by notcurses's reflective calls (e.g. <tt>ncplane_at_yx()</tt>).
notcurses does not currently handle right-to-left text in any special way, but terminals often apply their own heuristics and stylings. Generally this means that a series of glyphs from right-to-left languages will be reversed in the terminal, but this will <b>not</b> be detectable by notcurses's reflective calls (e.g. <tt>ncplane_at_yx()</tt>).
==Blitters==
Multiple blitters are provided, and can be selected whenever pixel data is being rendered. This includes <tt>ncvisual</tt> objects and qrcodes. If Notcurses is started in ASCII mode (as opposed to UTF-8), all blitters will degrade to <tt>NCBLITTER_1x1</tt> (unless <tt>NCVISUAL_OPTION_NODEGRADE</tt> is provided).
{| class="wikitable"
! Value !! Geometry !! Comments
|-
| <tt>NCBLITTER_1x1</tt>
| 1x1->1
| Uses spaces and sets the background color. The only blitter available in ASCII mode, and the only reliable blitter on the console. Pixel aspect ratio is equivalent to cell aspect ratio, usually resulting in vertical stretching. Lossless. Reliable no matter the font.
|-
| <tt>NCBLITTER_2x1</tt>
| 2x1->1
| Default blitter. Pixel aspect ratio is one-half the cell aspect ratio, which is usually right where you want it. Uses Unicode upper- and lower-half blocks, and spaces. Lossless.
|-
| <tt>NCBLITTER_2x2</tt>
| 2x2->1
| Pixel aspect ratio is equivalent to cell aspect ratio, usually resulting in vertical stretching. Uses Unicode quadrant and three-quarter blocks (in addition to upper- and lower-half blocks, and spaces). Lossy whenever more than two colors are used within a 2x2 pixel square, lossless otherwise (bi- and tri-linear interpolation is used for more than two colors).
|-
| <tt>NCBLITTER_3x2</tt>
| 3x2->1
| Highest quality for most large images. Pixel aspect ratio improves over NCBLITTER_2x2 but is less perfect than NCBLITTER_2x1, leading to slight vertical stretching. Uses Unicode sextants, left and right half blocks, and spaces). Lossy whenever more than two colors are used within a 3x2 pixel square, lossless otherwise (generalized linear interpolation is used for more than two colors).
|-
| <tt>NCBLITTER_4x2</tt>
| 4x2->1
| Uses Braille characters, which have spotty font support.
|-
| <tt>NCBLITTER_PIXEL</tt>
| variable->1
| Pixel blitter (see below)
|-
|}
[[File:Worldmap-sexblitter..png|800px|center]]
===Pixel blitters===
[[File:pixel-orca.png|thumb|right|Ramble on, orca]]
Some terminals support pixel graphics, including the [[Sixel]] system pioneered by DEC. Notcurses can employ pixel graphics using the <tt>NCBLIT_PIXEL</tt> blitter.
* Sixel: xterm, mlterm, Alacritty (outstanding patch), WezTerm, foot, contour
* Kitty supports its own method (which is also supported by WezTerm)
* as does ITerm2 (which is also supported by WezTerm)
* the Linux framebuffer console supports its own graphics (via memory map)
Notcurses does not currently output ReGIS vector graphics, nor the iTerm2 protocol.
Some timings from notcurses 2.3.17, taken 2021-08-28 using:
{| class="wikitable"
|+ <tt>ncplayer -bpixel ../data/notcursesIII.mkv -d0 -t0 -q</tt>
! term
! version
! pgeom
! cgeom
! times
|-
| mlterm
| 3.9.0
| 880x1406
| 80x61
| 1m5.142s 1m.3.731s 1m3.631s
|-
| XTerm
| 368
| 880x1403
| 88x74
| 55.655s 55.433s 55.841s
|-
| alacritty
| 0.13.1
| 880x1400
| 88x70
| 55.716s 55.902s 55.709s
|-
| kitty
| 0.23.1
| 880x1440
| 88x70
| 33.179s 33.477s 33.385s
|-
| kitty
| 0.19.3
|880x1440
|88x70
| 54.722s 54.473s 54.867s
|-
|}


==Input==
==Input==
Notcurses provides input from keyboards and mice. Single Unicode codepoints are received from the keyboard, directly encoded as <tt>char32_t</tt>s. The input system must deal with numerous keyboard signals which do not map to Unicode code points. This includes the keypad arrows and function keys. These "synthesized" codepoints are enumerated in <tt>notcurses.h</tt>, and mapped into the [https://unicode.org/charts/PDF/U100000.pdf Supplementary Private Use Area-B] (U+100000..U+10FFFD). Mouse button events are similarly mapped into the SPUA-B.
Notcurses provides input from keyboards and mice. Single Unicode codepoints are received from the keyboard, directly encoded as <tt>char32_t</tt>s. The input system must deal with numerous keyboard signals which do not map to Unicode code points. This includes the keypad arrows and function keys. These "synthesized" codepoints are enumerated in <tt>notcurses.h</tt>, and mapped into the [https://unicode.org/charts/PDF/U100000.pdf Supplementary Private Use Area-B] (U+100000..U+10FFFD). Mouse button events are similarly mapped into the SPUA-B.


All events carry a <tt>ncinput</tt> structure with them. For mouse events, the x and y coordinates are reported within this struct. For all events, modifiers (e.g. "Alt") are carried as bools in this struct.
All events carry a <tt>ncinput</tt> structure with them. For mouse events, the x and y coordinates are reported within this struct. For all events, modifiers (e.g. "Alt") are carried as the <tt>modifiers</tt> bitfield in this struct.


==Transparency/Contrasting==
==Transparency/Contrasting==
Line 76: Line 165:


High-contrast text is not strictly defined. notcurses will attempt to make the glyph as readable as possible, given the background color <i>computed at the cell</i>.
High-contrast text is not strictly defined. notcurses will attempt to make the glyph as readable as possible, given the background color <i>computed at the cell</i>.
Note that a cell with the zero glyph will not have its channels considered. The containing plane's default channels will instead be factored into any color/transparency calculations (if a default glyph has been defined for the plane). A cell containing a zero glyph on a plane with a default zero glyph cannot impact the rendered scene; any associated channels will be ignored.


If loaded multimedia supports transparency (e.g. PNGs), transparent pixels will be considered as if <tt>CELL_ALPHA_TRANSPARENT</tt> was used.
If loaded multimedia supports transparency (e.g. PNGs), transparent pixels will be considered as if <tt>CELL_ALPHA_TRANSPARENT</tt> was used.
Line 88: Line 175:


==Terminal emulators==
==Terminal emulators==
More information is available from the source tree in [https://github.com/dankamongmen/notcurses/blob/master/TERMINALS.md TERMINALS.md].
The two primary environmental factors affecting notcurses performance are the terminal emulator and the configured fonts.
The two primary environmental factors affecting notcurses performance are the terminal emulator and the configured fonts.


Line 173: Line 262:


===Notes on particular terminals===
===Notes on particular terminals===
The [https://github.com/dankamongmen/notcurses/blob/master/TERMINALS.md TERMINALS.md] document in Notcurses is (hopefully) well worth checking out.


* [https://invisible-island.net/xterm/ xterm], the first and (in many ways) the best.
* [https://invisible-island.net/xterm/ xterm], the first and (in many ways) the best.
Line 183: Line 273:
===Screen multiplexers===
===Screen multiplexers===
* <tt>screen</tt>: i've yet to see anything but a mess in screen
* <tt>screen</tt>: i've yet to see anything but a mess in screen
* <tt>tmux</tt>: i've only seen 256 colors work in tmux
* <tt>tmux</tt>: works decently well, aside from consuming bitmaps
* <tt>mosh</tt>: we look like shit in mosh and i wish we didn't


==Releases==
===Linux [[Consoles|console]]===
The Linux "system console" is a virtual device mapping to some device. We're primarily interested in the VGA text console, and the framebuffer console. The console supports only 256 different glyphs (512 with diminished color support), and never more than 16 colors (8 with 512 glyphs).


====fbterm====
You'll typically need to be a member of the <tt>video</tt> group to run <tt>fbterm</tt>. It offers much better Unicode glyph coverage than the raw console, but still offers only 16 (programmable) colors.
====kmscon====
==Major Releases==
{| class="wikitable"
{| class="wikitable"
! Release !! Date !! Key features
! Release !! Date !! Key features
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v3.0.0 3.0.0] || 2021-12-01
| New input system, kitty keyboard/GPM/XTMODKEYS support
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v2.4.0 2.4.0] || 2021-09-06
| Microsoft Windows and macOS support, Linux framebuffer graphics, "CLI mode"
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v2.3.0 2.3.0] || 2021-05-09
| Tree selector, tabbed interface, pixel blitting
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v2.2.0 2.2.0] || 2021-02-08
| libreadline, progress bars, notcurses-core extraction
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v2.1.0 2.1.0] || 2020-12-13
| Sexblitter, ncneofetch
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v2.0.0 2.0.0] || 2020-10-12
| Stable API!
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.7.0 1.7.0] || 2020-08-30
| Linux font table reprogramming, EGC inlining, better Rust wrappers
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.6.0 1.6.0] || 2020-07-04
| True three-channel transparency (glyph, fg, bg), Quadblitter default, beefed up ncdirect
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.5.0 1.5.0] || 2020-06-08
| Quadblitter
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.4.0 1.4.0] || 2020-05-10
| Fdplane and subproc widgets, reader widget, true scrolling
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.3.0 1.3.0] || 2020-04-13
| Multiselector widget, plot widget, multiline output, margins, staining
|-
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.2.0 1.2.0] || 2020-02-17
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.2.0 1.2.0] || 2020-02-17
Line 198: Line 329:
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.0.0 1.0.0] || 2019-01-04
| [https://github.com/dankamongmen/notcurses/releases/tag/v1.0.0 1.0.0] || 2019-01-04
| First GA release
| First GA release
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v0.9.9 0.9.9] || 2019-01-01
| Fixed wide glyph/plane interaction, video playback sync to PTS
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v0.9.3 0.9.3] || 2019-12-25
| Mouse support, panelreel fixes, linear interpolation fixed for long lines
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v0.9.2 0.9.2] || 2019-12-21
| Fixed unit tests for locales using decimal separators other then periods
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v0.9.1 0.9.1] || 2019-12-21
| Visual-adaptive planes, true ncvisual transparency, <tt>char32_t</tt> input
|-
|-
| [https://github.com/dankamongmen/notcurses/releases/tag/v0.9.0 0.9.0] || 2019-12-18
| [https://github.com/dankamongmen/notcurses/releases/tag/v0.9.0 0.9.0] || 2019-12-18
Line 229: Line 348:


==See Also==
==See Also==
* [[outcurses]], my effects and widgets library for [[Ncurses]]
* The [https://vt100.net/emu/dec_ansi_parser Paul Williams] automaton for lexing DECspeak
* [https://invisible-island.net/xterm/ctlseqs/ctlseqs.html XTerm] control sequences
* [https://sw.kovidgoyal.net/kitty/protocol-extensions.html Kitty-specific] functionality
* [https://iterm2.com/documentation-escape-codes.html iTerm2 extension] escape sequences
* [https://jexer.sourceforge.io/ Jexer], a Java library of similar power
* [https://wezfurlong.org/wezterm/escape-sequences.html Wezterm extension] escape sequences
* [[outcurses]], my earlier effects/widgets library for [[Ncurses]]


[[File:Notcurses-0.4.0-bling.png|640px|center|Contact sheet from Notcurses 0.4.0 demo]]
[[File:Notcurses-0.4.0-bling.png|640px|center|Contact sheet from Notcurses 0.4.0 demo]]
[[CATEGORY: Terminals]]
[[CATEGORY: Projects]]