Provided by: libnotcurses-core-dev_3.0.7+dfsg.1-1ubuntu5_amd64 
NAME
notcurses_visual - notcurses multimedia
SYNOPSIS
#include <notcurses/notcurses.h>
typedef enum {
NCSCALE_NONE,
NCSCALE_SCALE,
NCSCALE_STRETCH,
NCSCALE_NONE_HIRES,
NCSCALE_SCALE_HIRES,
} ncscale_e;
typedef enum {
NCBLIT_DEFAULT, // let the ncvisual pick
NCBLIT_1x1, // spaces only
NCBLIT_2x1, // halves + 1x1
NCBLIT_2x2, // quadrants + 2x1
NCBLIT_3x2, // sextants + 1x1
NCBLIT_BRAILLE, // 4 rows, 2 cols (braille)
NCBLIT_PIXEL, // pixel graphics
NCBLIT_4x1, // four vertical levels, (plots)
NCBLIT_8x1, // eight vertical levels, (plots)
} ncblitter_e;
#define NCVISUAL_OPTION_NODEGRADE 0x0001ull
#define NCVISUAL_OPTION_BLEND 0x0002ull
#define NCVISUAL_OPTION_HORALIGNED 0x0004ull
#define NCVISUAL_OPTION_VERALIGNED 0x0008ull
#define NCVISUAL_OPTION_ADDALPHA 0x0010ull
#define NCVISUAL_OPTION_CHILDPLANE 0x0020ull
#define NCVISUAL_OPTION_NOINTERPOLATE 0x0040ull
struct ncvisual_options {
struct ncplane* n;
ncscale_e scaling;
int y, x;
int begy, begx; // origin of rendered region
int leny, lenx; // size of rendered region
ncblitter_e blitter; // glyph set to use
uint64_t flags; // bitmask over NCVISUAL_OPTION_*
uint32_t transcolor; // use this color for ADDALPHA
unsigned pxoffy, pxoffx; // pixel offset from origin
};
typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
typedef struct ncvgeom {
unsigned pixy, pixx; // true pixel geometry of ncvisual data
unsigned cdimy, cdimx; // terminal cell geometry when this was calculated
unsigned rpixy, rpixx; // rendered pixel geometry (per visual_options)
unsigned rcelly, rcellx; // rendered cell geometry (per visual_options)
unsigned scaley, scalex; // pixels per filled cell (scale == c for bitmaps)
unsigned begy, begx; // upper-left corner of used region
unsigned leny, lenx; // geometry of used region
unsigned maxpixely, maxpixelx; // only defined for NCBLIT_PIXEL
ncblitter_e blitter;i // blitter that will be used
} ncvgeom;
struct ncvisual* ncvisual_from_file(const char* file);
struct ncvisual* ncvisual_from_rgba(const void* rgba, int rows, int rowstride, int cols);
struct ncvisual* ncvisual_from_rgb_packed(const void* rgba, int rows, int rowstride, int
cols, int alpha);
struct ncvisual* ncvisual_from_rgb_loose(const void* rgba, int rows, int rowstride, int
cols, int alpha);
struct ncvisual* ncvisual_from_bgra(const void* bgra, int rows, int rowstride, int cols);
struct ncvisual* ncvisual_from_palidx(const void* data, int rows, int rowstride, int cols,
int palsize, int pstride, const uint32_t* palette);
struct ncvisual* ncvisual_from_plane(struct ncplane* n, ncblitter_e blit, unsigned begy,
unsigned begx, unsigned leny, unsigned lenx);
int ncvisual_geom(const struct notcurses* nc, const struct ncvisual* n, const struct
ncvisual_options* vopts, ncvgeom* geom);
void ncvisual_destroy(struct ncvisual* ncv);
int ncvisual_decode(struct ncvisual* ncv);
int ncvisual_decode_loop(struct ncvisual* ncv);
struct ncplane* ncvisual_blit(struct notcurses* nc, struct ncvisual* ncv, const struct
ncvisual_options* vopts);
static inline struct ncplane* ncvisualplane_create(struct notcurses* nc, const struct
ncplane_options* opts, struct ncvisual* ncv, struct ncvisual_options* vopts);
int ncvisual_simple_streamer(struct ncplane* n, struct ncvisual* ncv, const struct
timespec* disptime, void* curry);
int ncvisual_stream(struct notcurses* nc, struct ncvisual* ncv, float timescale, streamcb
streamer, const struct ncvisual_options* vopts, void* curry);
int ncvisual_rotate(struct ncvisual* n, double rads);
int ncvisual_resize(struct ncvisual* n, int rows, int cols);
int ncvisual_resize_noninterpolative(struct ncvisual* n, int rows, int cols);
int ncvisual_polyfill_yx(struct ncvisual* n, int y, int x, uint32_t rgba);
int ncvisual_at_yx(const struct ncvisual* n, unsigned y, unsigned x, uint32_t* pixel);
int ncvisual_set_yx(const struct ncvisual* n, unsigned y, unsigned x, uint32_t pixel);
struct ncplane* ncvisual_subtitle_plane(struct ncplane* parent, const struct ncvisual*
ncv);
int notcurses_lex_scalemode(const char* op, ncscale_e* scaling);
const char* notcurses_str_scalemode(ncscale_e scaling);
int notcurses_lex_blitter(const char* op, ncblitter_e* blitter);
const char* notcurses_str_blitter(ncblitter_e blitter);
ncblitter_e ncvisual_media_defblitter(const struct notcurses nc, ncscale_e scaling);
int ncplane_qrcode(struct ncplane* n, unsigned* ymax, unsigned* xmax, const void* data,
size_t len)
struct ncvisual* ncvisual_from_sixel(const char* s, unsigned leny, unsigned lenx);
DESCRIPTION
An ncvisual is a virtual pixel framebuffer. They can be created from RGBA/BGRA data in
memory (ncvisual_from_rgba/ncvisual_from_bgra), or from the content of a suitable ncplane
(ncvisual_from_ncplane). If Notcurses was built against a multimedia engine (FFMpeg or
OpenImageIO), image and video files can be loaded into visuals using ncvisual_from_file.
ncvisual_from_file discovers the container and codecs, but does not verify that the entire
file is well-formed. ncvisual_decode ought be invoked to recover subsequent frames, once
per frame. ncvisual_decode_loop will return to the first frame, as if ncvisual_decode had
never been called.
Once the visual is loaded, it can be transformed using ncvisual_rotate, ncvisual_resize,
and ncvisual_resize_noninterpolative. These are persistent operations, unlike any scaling
that takes place at render time. If a subtitle is associated with the frame, it can be
acquired with ncvisual_subtitle_plane. ncvisual_resize uses the media layer's best scheme
to enlarge or shrink the original data, typically involving some interpolation.
ncvisual_resize_noninterpolative performs a naive linear sampling, retaining only original
colors.
ncvisual_from_rgba and ncvisual_from_bgra both require a number of rows, a number of image
columns cols, and a virtual row length of rowstride / 4 columns. The input data must
provide 32 bits per pixel, and thus must be at least rowstride * rows bytes, of which a
cols * rows * 4-byte subset is used. It is not possible to mmap(2) an image file and use
it directly--decompressed, decoded data is necessary. The resulting plane will be
ceil(rows/2) rows, and cols columns.
ncvisual_from_rgb_packed performs the same using 3-byte RGB source data.
ncvisual_from_rgb_loose uses 4-byte RGBx source data. Both will fill in the alpha
component of every target pixel with the specified alpha.
ncvisual_from_palidx requires a palette of at least palsize ncchannels. Pixels are
pstride bytes each, arranged as cols pixels per row, with each row occupying rowstride
bytes, across rows rows.
ncvisual_from_plane requires specification of a rectangle via begy, begx, leny, and lenx,
and also a blitter. The only valid glyphs within this region are those used by the
specified blitter.
ncvisual_rotate executes a rotation of rads radians, in the clockwise (positive) or
counterclockwise (negative) direction.
ncvisual_subtitle_plane returns a struct ncplane suitable for display, if the current
frame had such a subtitle. Note that the same subtitle might be returned for multiple
frames, or might not. It is atypical for all frames to have subtitles. Subtitles can be
text or graphics.
ncvisual_blit draws the visual to an ncplane, based on the contents of its struct
ncvisual_options. If n is not NULL, it specifies the plane on which to render, and y/x
specify a location within that plane. Otherwise, a new plane will be created, and placed
at y/x relative to the rendering area. begy/begx specify the upper left corner of a
subregion of the ncvisual to render, while leny/lenx specify the geometry of same. flags
is a bitfield over:
• NCVISUAL_OPTION_NODEGRADE If the specified blitter is not available, fail rather than
degrading.
• NCVISUAL_OPTION_BLEND: Render with NCALPHA_BLEND. Not available with NCBLIT_PIXEL when
using Sixel graphics. When used with NCBLIT_PIXEL when using Kitty graphics, the alpha
channel is divided by 2 for each pixel.
• NCVISUAL_OPTION_HORALIGNED: Interpret x as an ncalign_e.
• NCVISUAL_OPTION_VERALIGNED: Interpret y as an ncalign_e.
• NCVISUAL_OPTION_ADDALPHA: Interpret the lower 24 bits of transcolor as a transparent
color.
• NCVISUAL_OPTION_CHILDPLANE: Make a new plane, as a child of n.
ncvisual_geom allows the caller to determine any or all of the visual's pixel geometry,
the blitter to be used, and that blitter's scaling in both dimensions. Any but the final
argument may be NULL, though at least one of nc and n must be non-NULL. If nc is NULL,
only properties intrinsic to the visual are returned (i.e. its original pixel geometry).
If n is NULL, only properties independent of the visual are returned (i.e. cell-pixel
geometry and maximum bitmap geometry). If both are supplied, all fields of the ncvgeom
structure are filled in.
ncplane_qrcode draws an ISO/IEC 18004:2015 QR Code for the len bytes of data using
NCBLIT_2x1 (this is the only blitter that will work with QR Code scanners, due to its 1:1
aspect ratio).
OPTIONS
begy and begx specify the upper left corner of the image to start drawing. leny and lenx
specify the area of the subimage drawn. leny and/or lenx may be specified as a negative
number to draw through the bottom right corner of the image.
The n field specifies the plane to use. If this is NULL, a new plane will be created,
having the precise geometry necessary to blit the specified region of the image. This
might be larger (or smaller) than the visual area.
y and x have different meanings depending on whether or not n is NULL. If not (drawing
onto a preexisting plane), they specify where in the plane to start drawing. If n was
NULL (new plane), they specify the origin of the new plane relative to the visible area.
If the flags field contains NCVISUAL_OPTION_HORALIGNED, the x parameter is interpreted as
an ncalign_e rather than an absolute position. If the flags field contains
NCVISUAL_OPTION_VERALIGNED, the y parameter is interpreted as an ncalign_e rather than an
absolute position. If the flags field contains NCVISUAL_OPTION_CHILDPLANE, n must be non-
NULL, and the x and y parameters are interpreted relative to that plane.
BLITTERS
The different ncblitter_e values select from among available glyph sets:
• NCBLIT_DEFAULT: Let the ncvisual choose its own blitter.
• NCBLIT_1x1: Spaces only. Works in ASCII, unlike most other blitters.
• NCBLIT_2x1: Adds the half blocks (▄▀) to NCBLIT_1x1.
• NCBLIT_2x2: Adds left and right half blocks (▌▐) and quadrants (▖▗▟▙) to NCBLIT_2x1.
• NCBLIT_3x2: Adds sextants to NCBLIT_1x1.
• NCBLIT_BRAILLE: 4 rows and 2 columns of braille (⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿).
• NCBLIT_PIXEL: Adds pixel graphics (these also work in ASCII).
Two more blitters exist for plots, but are unsuitable for generic media:
• NCBLIT_4x1: Adds ¼ and ¾ blocks (▂▆) to NCBLIT_2x1.
• NCBLIT_8x1: Adds ⅛, ⅜, ⅝, and ⅞ blocks (▇▅▃▁) to NCBLIT_4x1.
NCBLIT_4x1 and NCBLIT_8x1 are intended for use with plots, and are not really applicable
for general visuals. NCBLIT_BRAILLE doesn't tend to work out very well for images, but
(depending on the font) can be very good for plots.
A string can be transformed to a blitter with notcurses_lex_blitter, recognizing ascii,
half, quad, sex, fourstep, braille, eightstep, and pixel. Conversion in the opposite
direction is performed with notcurses_str_blitter.
In the absence of scaling, for a given set of pixels, more rows and columns in the blitter
will result in a smaller output image. An image rendered with NCBLIT_1x1 will be twice as
tall as the same image rendered with NCBLIT_2x1, which will be twice as wide as the same
image rendered with NCBLIT_2x2. The same image rendered with NCBLIT_3x2 will be one-third
as tall and one-half as wide as the original NCBLIT_1x1 render (again, this depends on
NCSCALE_NONE). If the output size is held constant (using for instance
NCSCALE_SCALE_HIRES and a large image), more rows and columns will result in more
effective resolution.
A string can be transformed to a scaling mode with notcurses_lex_scalemode, recognizing
stretch, scalehi, hires, scale, and none. Conversion in the opposite direction is
performed with notcurses_str_scalemode.
Assuming a cell is twice as tall as it is wide, NCBLIT_1x1 (and indeed any NxN blitter)
will stretch an image by a factor of 2 in the vertical dimension. NCBLIT_2x1 will not
distort the image whatsoever, as it maps a vector two pixels high and one pixel wide to a
single cell. NCBLIT_3x2 will stretch an image by a factor of 1.5.
The cell's dimension in pixels is ideally evenly divisible by the blitter geometry. If
NCBLIT_3x2 is used together with a cell 8 pixels wide and 14 pixels tall, two of the
vertical segments will be 5 pixels tall, while one will be 4 pixels tall. Such unequal
distributions are more likely with larger blitter geometries. Likewise, there are only
ever two colors available to us in a given cell. NCBLIT_1x1 and NCBLIT_2x2 can be
perfectly represented with two colors per cell. Blitters of higher geometry are
increasingly likely to require some degree of interpolation. Transparency is always
honored with complete fidelity.
Finally, rendering operates slightly differently when two planes have both been blitted,
and one lies atop the other. See notcurses_render(3) for more information.
PIXEL BLITTING
Some terminals support pixel-based output via one of a number of protocols. NCBLIT_PIXEL
has some stringent requirements on the type of planes it can be used with; it is usually
best to let ncvisual_blit create the backing plane by providing a NULL value for n. If
you must bring your own plane, it must be perfectly sized for the bitmap (i.e. large
enough, and not more than a full cell larger in either dimension--the bitmap, always
placed at the origin, must at least partially cover every cell of the plane). Using
NCSCALE_STRETCH means that the second condition will always be met. Once a sprixel is
blitted to a plane, cell methods (including cell blitting) may not be used with it.
Resizing the plane eliminates the sprixel, as does destroying the plane. A sprixelated
plane may be moved in all three dimensions, duplicated, and reparented. The base cell of
a sprixelated plane is meaningless; if the sprixel is not an even multiple of the cell
geometry, any excess cell material is ignored during rendering.
Only one bitmap can be blitted onto a plane at a time (but multiple planes with bitmaps
may be visible); blitting a second to the same plane will delete the original.
pxoffy and pxoffx can specify an offset from the origin of the upper left cell. This can
be used for absolute positioning of a bitmap, or for smooth movement of same. It is an
error if pxoffy exceeds the cell height in pixels, or pxoffx exceeds the cell width in
pixels. If NCBLIT_PIXEL is not used, these fields are ignored.
RETURN VALUES
ncvisual_from_file returns an ncvisual object on success, or NULL on failure. Success
indicates that the specified file was opened, and enough data was read to make a firm
codec identification. It does not imply that the entire file is properly-formed.
ncvisual_decode returns 0 on success, or 1 on end of file, or -1 on failure. It is only
necessary for multimedia-based visuals. It advances one frame for each call.
ncvisual_decode_loop has the same return values: when called following decoding of the
last frame, it will return 1, but a subsequent ncvisual_blit will return the first frame.
ncvisual_from_plane returns NULL if the ncvisual cannot be created and bound. This is
usually due to illegal content in the source ncplane.
ncvisual_blit returns NULL on error, and otherwise the plane to which the visual was
rendered. If opts->n is provided, this will be opts->n. Otherwise, a plane will be
created, perfectly sized for the visual and the specified blitter.
ncvisual_geom returns non-zero if the specified configuration is invalid, or if both nc
and n are NULL.
ncvisual_media_defblitter returns the blitter selected by NCBLIT_DEFAULT in the specified
configuration. If UTF8 is not enabled, this will always be NCBLIT_1x1. If scale is
NCSCALE_NONE or NCSCALE_SCALE, the aspect-preserving NCBLIT_2x1 will be returned. If
sextants are available (see notcurses_cansextant), this will be NCBLIT_3x2, or otherwise
NCBLIT_2x2.
NOTES
Multimedia decoding requires that Notcurses be built with either FFmpeg or OpenImageIO
support. What formats can be decoded is totally dependent on the linked library.
OpenImageIO does not support subtitles. Functions requiring a multimedia backend include
ncvisual_from_file and ncvisual_subtitle_plane.
Sixel documentation can be found at Dankwiki (https://nick-
black.com/dankwiki/index.php?title=Sixel). Kitty's graphics protocol is specified in its
documentation (https://sw.kovidgoyal.net/kitty/graphics-protocol.html).
Bad font support can ruin NCBLIT_2x2, NCBLIT_3x2, NCBLIT_4x1, NCBLIT_BRAILLE, and
NCBLIT_8x1. Braille glyphs ought ideally draw only the raised dots, rather than drawing
all eight dots with two different styles. It's often best for the emulator to draw these
glyphs itself.
Several emulators claim to implement Sixel, but do so in a more or less broken fashion. I
consider XTerm and foot to be reference Sixel implementations on X.org and Wayland,
respectively.
Sixels are fundamentally expressed in terms of six-line bands. If the rendered bitmap is
not a multiple of six rows, the necessary rows will be faked via transparent rows. All
sprixels have a height in rows, and if this height is not a multiple of the cell height in
rows, the last rows will only partially obstruct a row of cells. This can lead to
undesirable redraws and flicker if the cells underneath the sprixel change. A sprixel
which is both a multiple of the cell height and a multiple of six is the most predictable
possible sprixel.
When using non-interpolative blitting together with scaling, unless your goal includes
minimizing the total area required, lower-resolution blitters will generally look just as
good as higher resolution blitters, and be faster.
The results of ncvisual_geom are invalidated by a terminal resize.
BUGS
Functions which describe rendered state such as ncplane_at_yx and notcurses_at_yx will
return an nccell with a sprixel ID, but this sprixel cannot be accessed.
ncvisual_rotate currently supports only M_PI/2 and -M_PI/2 radians for rads, but this will
change soon.
ncvisual_blit should be able to create new planes in piles other than the standard pile.
This ought become a reality soon.
ncvisual_stream currently requires a multimedia engine, which is silly. This will change
in the near future.
Sprixels interact poorly with multiple planes, and such usage is discouraged. This
situation might improve in the future.
Multiple threads may not currently call ncvisual_blit concurrently using the same
ncvisual, even if targeting distinct ncplanes. This will likely change in the future.
pxoffy and pxoffx are not yet implemented.
SEE ALSO
notcurses(3), notcurses_capabilities(3), notcurses_plane(3), notcurses_render(3), utf-8(7)
AUTHORS
nick black <nickblack@linux.com>.
v3.0.7 notcurses_visual(3)