.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_visual" "3" "v3.0.0" "" ""
.hy
.SH NAME
.PP
notcurses_visual - notcurses multimedia
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
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;
\f[R]
.fi
.PP
\f[B]struct ncvisual* ncvisual_from_file(const char*
\f[R]\f[I]file\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncvisual* ncvisual_from_rgba(const void*
\f[R]\f[I]rgba\f[R]\f[B], int \f[R]\f[I]rows\f[R]\f[B], int
\f[R]\f[I]rowstride\f[R]\f[B], int \f[R]\f[I]cols\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncvisual* ncvisual_from_rgb_packed(const void*
\f[R]\f[I]rgba\f[R]\f[B], int \f[R]\f[I]rows\f[R]\f[B], int
\f[R]\f[I]rowstride\f[R]\f[B], int \f[R]\f[I]cols\f[R]\f[B], int
\f[R]\f[I]alpha\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncvisual* ncvisual_from_rgb_loose(const void*
\f[R]\f[I]rgba\f[R]\f[B], int \f[R]\f[I]rows\f[R]\f[B], int
\f[R]\f[I]rowstride\f[R]\f[B], int \f[R]\f[I]cols\f[R]\f[B], int
\f[R]\f[I]alpha\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncvisual* ncvisual_from_bgra(const void*
\f[R]\f[I]bgra\f[R]\f[B], int \f[R]\f[I]rows\f[R]\f[B], int
\f[R]\f[I]rowstride\f[R]\f[B], int \f[R]\f[I]cols\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncvisual* ncvisual_from_palidx(const void*
\f[R]\f[I]data\f[R]\f[B], int \f[R]\f[I]rows\f[R]\f[B], int
\f[R]\f[I]rowstride\f[R]\f[B], int \f[R]\f[I]cols\f[R]\f[B], int
\f[R]\f[I]palsize\f[R]\f[B], int \f[R]\f[I]pstride\f[R]\f[B], const
uint32_t* \f[R]\f[I]palette\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncvisual* ncvisual_from_plane(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], ncblitter_e \f[R]\f[I]blit\f[R]\f[B], unsigned
\f[R]\f[I]begy\f[R]\f[B], unsigned \f[R]\f[I]begx\f[R]\f[B], unsigned
\f[R]\f[I]leny\f[R]\f[B], unsigned \f[R]\f[I]lenx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_geom(const struct notcurses* \f[R]\f[I]nc\f[R]\f[B],
const struct ncvisual* \f[R]\f[I]n\f[R]\f[B], const struct
ncvisual_options* \f[R]\f[I]vopts\f[R]\f[B], ncvgeom*
\f[R]\f[I]geom\f[R]\f[B]);\f[R]
.PP
\f[B]void ncvisual_destroy(struct ncvisual*
\f[R]\f[I]ncv\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_decode(struct ncvisual* \f[R]\f[I]ncv\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_decode_loop(struct ncvisual*
\f[R]\f[I]ncv\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncvisual_blit(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], struct ncvisual* \f[R]\f[I]ncv\f[R]\f[B], const
struct ncvisual_options* \f[R]\f[I]vopts\f[R]\f[B]);\f[R]
.PP
\f[B]static inline struct ncplane* ncvisualplane_create(struct
notcurses* \f[R]\f[I]nc\f[R]\f[B], const struct ncplane_options*
\f[R]\f[I]opts\f[R]\f[B], struct ncvisual* \f[R]\f[I]ncv\f[R]\f[B],
struct ncvisual_options* \f[R]\f[I]vopts\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_simple_streamer(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
struct ncvisual* \f[R]\f[I]ncv\f[R]\f[B], const struct timespec*
\f[R]\f[I]disptime\f[R]\f[B], void* \f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_stream(struct notcurses* \f[R]\f[I]nc\f[R]\f[B],
struct ncvisual* \f[R]\f[I]ncv\f[R]\f[B], float
\f[R]\f[I]timescale\f[R]\f[B], streamcb \f[R]\f[I]streamer\f[R]\f[B],
const struct ncvisual_options* \f[R]\f[I]vopts\f[R]\f[B], void*
\f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_rotate(struct ncvisual* \f[R]\f[I]n\f[R]\f[B], double
\f[R]\f[I]rads\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_resize(struct ncvisual* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]rows\f[R]\f[B], int \f[R]\f[I]cols\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_resize_noninterpolative(struct ncvisual*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]rows\f[R]\f[B], int
\f[R]\f[I]cols\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_polyfill_yx(struct ncvisual* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], uint32_t
\f[R]\f[I]rgba\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_at_yx(const struct ncvisual* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]y\f[R]\f[B], unsigned \f[R]\f[I]x\f[R]\f[B],
uint32_t* \f[R]\f[I]pixel\f[R]\f[B]);\f[R]
.PP
\f[B]int ncvisual_set_yx(const struct ncvisual* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]y\f[R]\f[B], unsigned \f[R]\f[I]x\f[R]\f[B], uint32_t
\f[R]\f[I]pixel\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncvisual_subtitle_plane(struct ncplane*
\f[R]\f[I]parent\f[R]\f[B], const struct ncvisual*
\f[R]\f[I]ncv\f[R]\f[B]);\f[R]
.PP
\f[B]int notcurses_lex_scalemode(const char* \f[R]\f[I]op\f[R]\f[B],
ncscale_e* \f[R]\f[I]scaling\f[R]\f[B]);\f[R]
.PP
\f[B]const char* notcurses_str_scalemode(ncscale_e
\f[R]\f[I]scaling\f[R]\f[B]);\f[R]
.PP
\f[B]int notcurses_lex_blitter(const char* \f[R]\f[I]op\f[R]\f[B],
ncblitter_e* \f[R]\f[I]blitter\f[R]\f[B]);\f[R]
.PP
\f[B]const char* notcurses_str_blitter(ncblitter_e
\f[R]\f[I]blitter\f[R]\f[B]);\f[R]
.PP
\f[B]ncblitter_e ncvisual_media_defblitter(const struct notcurses
\f[R]\f[I]nc\f[R]\f[B], ncscale_e \f[R]\f[I]scaling\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_qrcode(struct ncplane* \f[R]\f[I]n\f[R]\f[B], unsigned*
\f[R]\f[I]ymax\f[R]\f[B], unsigned* \f[R]\f[I]xmax\f[R]\f[B], const
void* \f[R]\f[I]data\f[R]\f[B], size_t \f[R]\f[I]len\f[R]\f[B])\f[R]
.SH DESCRIPTION
.PP
An \f[B]ncvisual\f[R] is a virtual pixel framebuffer.
They can be created from RGBA/BGRA data in memory
(\f[B]ncvisual_from_rgba\f[R]/\f[B]ncvisual_from_bgra\f[R]), or from the
content of a suitable \f[B]ncplane\f[R]
(\f[B]ncvisual_from_ncplane\f[R]).
If Notcurses was built against a multimedia engine (FFMpeg or
OpenImageIO), image and video files can be loaded into visuals using
\f[B]ncvisual_from_file\f[R].
\f[B]ncvisual_from_file\f[R] discovers the container and codecs, but
does not verify that the entire file is well-formed.
\f[B]ncvisual_decode\f[R] ought be invoked to recover subsequent frames,
once per frame.
\f[B]ncvisual_decode_loop\f[R] will return to the first frame, as if
\f[B]ncvisual_decode\f[R] had never been called.
.PP
Once the visual is loaded, it can be transformed using
\f[B]ncvisual_rotate\f[R], \f[B]ncvisual_resize\f[R], and
\f[B]ncvisual_resize_noninterpolative\f[R].
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
\f[B]ncvisual_subtitle_plane\f[R].
\f[B]ncvisual_resize\f[R] uses the media layer\[aq]s best scheme to
enlarge or shrink the original data, typically involving some
interpolation.
\f[B]ncvisual_resize_noninterpolative\f[R] performs a naive linear
sampling, retaining only original colors.
.PP
\f[B]ncvisual_from_rgba\f[R] and \f[B]ncvisual_from_bgra\f[R] both
require a number of \f[B]\f[BI]rows\f[B]\f[R], a number of image columns
\f[B]cols\f[R], and a virtual row length of
\f[B]\f[BI]rowstride\f[B]\f[R] / 4 columns.
The input data must provide 32 bits per pixel, and thus must be at least
\f[B]\f[BI]rowstride\f[B]\f[R] * \f[B]\f[BI]rows\f[B]\f[R] bytes, of
which a \f[B]\f[BI]cols\f[B]\f[R] * \f[B]\f[BI]rows\f[B]\f[R] * 4-byte
subset is used.
It is not possible to \f[B]mmap(2)\f[R] an image file and use it
directly--decompressed, decoded data is necessary.
The resulting plane will be ceil(\f[B]rows\f[R]/2) rows, and
\f[B]cols\f[R] columns.
.PP
\f[B]ncvisual_from_rgb_packed\f[R] performs the same using 3-byte RGB
source data.
\f[B]ncvisual_from_rgb_loose\f[R] uses 4-byte RGBx source data.
Both will fill in the alpha component of every target pixel with the
specified \f[B]alpha\f[R].
.PP
\f[B]ncvisual_from_palidx\f[R] requires a \f[B]\f[BI]palette\f[B]\f[R]
of at least \f[B]\f[BI]palsize\f[B]\f[R] \f[B]ncchannel\f[R]s.
Pixels are \f[B]\f[BI]pstride\f[B]\f[R] bytes each, arranged as
\f[B]\f[BI]cols\f[B]\f[R] pixels per row, with each row occupying
\f[B]\f[BI]rowstride\f[B]\f[R] bytes, across \f[B]\f[BI]rows\f[B]\f[R]
rows.
.PP
\f[B]ncvisual_from_plane\f[R] requires specification of a rectangle via
\f[B]\f[BI]begy\f[B]\f[R], \f[B]\f[BI]begx\f[B]\f[R],
\f[B]\f[BI]leny\f[B]\f[R], and \f[B]\f[BI]lenx\f[B]\f[R], and also a
blitter.
The only valid glyphs within this region are those used by the specified
blitter.
.PP
\f[B]ncvisual_rotate\f[R] executes a rotation of
\f[B]\f[BI]rads\f[B]\f[R] radians, in the clockwise (positive) or
counterclockwise (negative) direction.
.PP
\f[B]ncvisual_subtitle_plane\f[R] returns a \f[B]struct ncplane\f[R]
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.
.PP
\f[B]ncvisual_blit\f[R] draws the visual to an \f[B]ncplane\f[R], based
on the contents of its \f[B]struct ncvisual_options\f[R].
If \f[B]\f[BI]n\f[B]\f[R] is not \f[B]NULL\f[R], it specifies the plane
on which to render, and \f[B]\f[BI]y\f[B]\f[R]/\f[B]\f[BI]x\f[B]\f[R]
specify a location within that plane.
Otherwise, a new plane will be created, and placed at
\f[B]\f[BI]y\f[B]\f[R]/\f[B]\f[BI]x\f[B]\f[R] relative to the rendering
area.
\f[B]\f[BI]begy\f[B]\f[R]/\f[B]\f[BI]begx\f[B]\f[R] specify the upper
left corner of a subregion of the \f[B]ncvisual\f[R] to render, while
\f[B]\f[BI]leny\f[B]\f[R]/\f[B]\f[BI]lenx\f[B]\f[R] specify the geometry
of same.
\f[B]\f[BI]flags\f[B]\f[R] is a bitfield over:
.IP \[bu] 2
\f[B]NCVISUAL_OPTION_NODEGRADE\f[R] If the specified blitter is not
available, fail rather than degrading.
.IP \[bu] 2
\f[B]NCVISUAL_OPTION_BLEND\f[R]: Render with \f[B]NCALPHA_BLEND\f[R].
Not available with \f[B]NCBLIT_PIXEL\f[R] when using Sixel graphics.
When used with \f[B]NCBLIT_PIXEL\f[R] when using Kitty graphics, the
alpha channel is divided by 2 for each pixel.
.IP \[bu] 2
\f[B]NCVISUAL_OPTION_HORALIGNED\f[R]: Interpret \f[B]\f[BI]x\f[B]\f[R]
as an \f[B]ncalign_e\f[R].
.IP \[bu] 2
\f[B]NCVISUAL_OPTION_VERALIGNED\f[R]: Interpret \f[B]\f[BI]y\f[B]\f[R]
as an \f[B]ncalign_e\f[R].
.IP \[bu] 2
\f[B]NCVISUAL_OPTION_ADDALPHA\f[R]: Interpret the lower 24 bits of
\f[B]\f[BI]transcolor\f[B]\f[R] as a transparent color.
.IP \[bu] 2
\f[B]NCVISUAL_OPTION_CHILDPLANE\f[R]: Make a new plane, as a child of
\f[B]\f[BI]n\f[B]\f[R].
.PP
\f[B]ncvisual_geom\f[R] allows the caller to determine any or all of the
visual\[aq]s pixel geometry, the blitter to be used, and that
blitter\[aq]s scaling in both dimensions.
Any but the final argument may be \f[B]NULL\f[R], though at least one of
\f[B]\f[BI]nc\f[B]\f[R] and \f[B]\f[BI]n\f[B]\f[R] must be
non-\f[B]NULL\f[R].
If \f[B]\f[BI]nc\f[B]\f[R] is \f[B]NULL\f[R], only properties intrinsic
to the visual are returned (i.e.
its original pixel geometry).
If \f[B]\f[BI]n\f[B]\f[R] is \f[B]NULL\f[R], 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 \f[B]ncvgeom\f[R] structure are
filled in.
.PP
\f[B]ncplane_qrcode\f[R] draws an ISO/IEC 18004:2015 QR Code for the
\f[B]len\f[R] bytes of \f[B]data\f[R] using \f[B]NCBLIT_2x1\f[R] (this
is the only blitter that will work with QR Code scanners, due to its 1:1
aspect ratio).
.SH OPTIONS
.PP
\f[B]\f[BI]begy\f[B]\f[R] and \f[B]\f[BI]begx\f[B]\f[R] specify the
upper left corner of the image to start drawing.
\f[B]\f[BI]leny\f[B]\f[R] and \f[B]\f[BI]lenx\f[B]\f[R] specify the area
of the subimage drawn.
\f[B]\f[BI]leny\f[B]\f[R] and/or \f[B]\f[BI]lenx\f[B]\f[R] may be
specified as a negative number to draw through the bottom right corner
of the image.
.PP
The \f[B]\f[BI]n\f[B]\f[R] field specifies the plane to use.
If this is \f[B]NULL\f[R], 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.
.PP
\f[B]\f[BI]y\f[B]\f[R] and \f[B]\f[BI]x\f[B]\f[R] have different
meanings depending on whether or not \f[B]\f[BI]n\f[B]\f[R] is
\f[B]NULL\f[R].
If not (drawing onto a preexisting plane), they specify where in the
plane to start drawing.
If \f[B]n\f[R] was \f[B]NULL\f[R] (new plane), they specify the origin
of the new plane relative to the visible area.
If the \f[B]\f[BI]flags\f[B]\f[R] field contains
\f[B]NCVISUAL_OPTION_HORALIGNED\f[R], the \f[B]\f[BI]x\f[B]\f[R]
parameter is interpreted as an \f[B]ncalign_e\f[R] rather than an
absolute position.
If the \f[B]\f[BI]flags\f[B]\f[R] field contains
\f[B]NCVISUAL_OPTION_VERALIGNED\f[R], the \f[B]\f[BI]y\f[B]\f[R]
parameter is interpreted as an \f[B]ncalign_e\f[R] rather than an
absolute position.
If the \f[B]\f[BI]flags\f[B]\f[R] field contains
\f[B]NCVISUAL_OPTION_CHILDPLANE\f[R], \f[B]\f[BI]n\f[B]\f[R] must be
non-\f[B]NULL\f[R], and the \f[B]\f[BI]x\f[B]\f[R] and
\f[B]\f[BI]y\f[B]\f[R] parameters are interpreted relative to that
plane.
.SH BLITTERS
.PP
The different \f[B]ncblitter_e\f[R] values select from among available
glyph sets:
.IP \[bu] 2
\f[B]NCBLIT_DEFAULT\f[R]: Let the \f[B]ncvisual\f[R] choose its own
blitter.
.IP \[bu] 2
\f[B]NCBLIT_1x1\f[R]: Spaces only.
Works in ASCII, unlike most other blitters.
.IP \[bu] 2
\f[B]NCBLIT_2x1\f[R]: Adds the half blocks (\[u2584]\[u2580]) to
\f[B]NCBLIT_1x1\f[R].
.IP \[bu] 2
\f[B]NCBLIT_2x2\f[R]: Adds left and right half blocks (\[u258C]\[u2590])
and quadrants (\[u2596]\[u2597]\[u259F]\[u2599]) to
\f[B]NCBLIT_2x1\f[R].
.IP \[bu] 2
\f[B]NCBLIT_3x2\f[R]: Adds sextants to \f[B]NCBLIT_1x1\f[R].
.IP \[bu] 2
\f[B]NCBLIT_BRAILLE\f[R]: 4 rows and 2 columns of braille
(\[u2840]\[u2844]\[u2846]\[u2847]\[u2880]\[u28C0]\[u28C4]\[u28C6]\[u28C7]\[u28A0]\[u28E0]\[u28E4]\[u28E6]\[u28E7]\[u28B0]\[u28F0]\[u28F4]\[u28F6]\[u28F7]\[u28B8]\[u28F8]\[u28FC]\[u28FE]\[u28FF]).
.IP \[bu] 2
\f[B]NCBLIT_PIXEL\f[R]: Adds pixel graphics (these also work in ASCII).
.PP
Two more blitters exist for plots, but are unsuitable for generic media:
.IP \[bu] 2
\f[B]NCBLIT_4x1\f[R]: Adds \[14] and \[34] blocks (\[u2582]\[u2586]) to
\f[B]NCBLIT_2x1\f[R].
.IP \[bu] 2
\f[B]NCBLIT_8x1\f[R]: Adds \[18], \[38], \[58], and \[78] blocks
(\[u2587]\[u2585]\[u2583]\[u2581]) to \f[B]NCBLIT_4x1\f[R].
.PP
\f[B]NCBLIT_4x1\f[R] and \f[B]NCBLIT_8x1\f[R] are intended for use with
plots, and are not really applicable for general visuals.
\f[B]NCBLIT_BRAILLE\f[R] doesn\[aq]t tend to work out very well for
images, but (depending on the font) can be very good for plots.
.PP
A string can be transformed to a blitter with
\f[B]notcurses_lex_blitter\f[R], recognizing \f[B]ascii\f[R],
\f[B]half\f[R], \f[B]quad\f[R], \f[B]sex\f[R], \f[B]fourstep\f[R],
\f[B]braille\f[R], \f[B]eightstep\f[R], and \f[B]pixel\f[R].
Conversion in the opposite direction is performed with
\f[B]notcurses_str_blitter\f[R].
.PP
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 \f[B]NCBLIT_1x1\f[R] will be twice as tall as the
same image rendered with \f[B]NCBLIT_2x1\f[R], which will be twice as
wide as the same image rendered with \f[B]NCBLIT_2x2\f[R].
The same image rendered with \f[B]NCBLIT_3x2\f[R] will be one-third as
tall and one-half as wide as the original \f[B]NCBLIT_1x1\f[R] render
(again, this depends on \f[B]NCSCALE_NONE\f[R]).
If the output size is held constant (using for instance
\f[B]NCSCALE_SCALE_HIRES\f[R] and a large image), more rows and columns
will result in more effective resolution.
.PP
A string can be transformed to a scaling mode with
\f[B]notcurses_lex_scalemode\f[R], recognizing \f[B]stretch\f[R],
\f[B]scalehi\f[R], \f[B]hires\f[R], \f[B]scale\f[R], and \f[B]none\f[R].
Conversion in the opposite direction is performed with
\f[B]notcurses_str_scalemode\f[R].
.PP
Assuming a cell is twice as tall as it is wide, \f[B]NCBLIT_1x1\f[R]
(and indeed any NxN blitter) will stretch an image by a factor of 2 in
the vertical dimension.
\f[B]NCBLIT_2x1\f[R] will not distort the image whatsoever, as it maps a
vector two pixels high and one pixel wide to a single cell.
\f[B]NCBLIT_3x2\f[R] will stretch an image by a factor of 1.5.
.PP
The cell\[aq]s dimension in pixels is ideally evenly divisible by the
blitter geometry.
If \f[B]NCBLIT_3x2\f[R] 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.
\f[B]NCBLIT_1x1\f[R] and \f[B]NCBLIT_2x2\f[R] 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.
.PP
Finally, rendering operates slightly differently when two planes have
both been blitted, and one lies atop the other.
See \f[B]notcurses_render(3)\f[R] for more information.
.SH PIXEL BLITTING
.PP
Some terminals support pixel-based output via one of a number of
protocols.
\f[B]NCBLIT_PIXEL\f[R] has some stringent requirements on the type of
planes it can be used with; it is usually best to let
\f[B]ncvisual_blit\f[R] create the backing plane by providing a
\f[B]NULL\f[R] value for \f[B]n\f[R].
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 \f[B]NCSCALE_STRETCH\f[R] 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.
.PP
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.
.PP
\f[B]pxoffy\f[R] and \f[B]pxoffx\f[R] 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 \f[B]pxoffy\f[R] exceeds the cell height in pixels, or
\f[B]pxoffx\f[R] exceeds the cell width in pixels.
If \f[B]NCBLIT_PIXEL\f[R] is not used, these fields are ignored.
.SH RETURN VALUES
.PP
\f[B]ncvisual_from_file\f[R] returns an \f[B]ncvisual\f[R] object on
success, or \f[B]NULL\f[R] on failure.
Success indicates that the specified \f[B]file\f[R] was opened, and
enough data was read to make a firm codec identification.
It does not imply that the entire file is properly-formed.
.PP
\f[B]ncvisual_decode\f[R] 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.
\f[B]ncvisual_decode_loop\f[R] has the same return values: when called
following decoding of the last frame, it will return 1, but a subsequent
\f[B]ncvisual_blit\f[R] will return the first frame.
.PP
\f[B]ncvisual_from_plane\f[R] returns \f[B]NULL\f[R] if the
\f[B]ncvisual\f[R] cannot be created and bound.
This is usually due to illegal content in the source \f[B]ncplane\f[R].
.PP
\f[B]ncvisual_blit\f[R] returns \f[B]NULL\f[R] on error, and otherwise
the plane to which the visual was rendered.
If \f[B]opts->n\f[R] is provided, this will be \f[B]opts->n\f[R].
Otherwise, a plane will be created, perfectly sized for the visual and
the specified blitter.
.PP
\f[B]ncvisual_geom\f[R] returns non-zero if the specified configuration
is invalid, or if both \f[B]\f[BI]nc\f[B]\f[R] and
\f[B]\f[BI]n\f[B]\f[R] are \f[B]NULL\f[R].
.PP
\f[B]ncvisual_media_defblitter\f[R] returns the blitter selected by
\f[B]NCBLIT_DEFAULT\f[R] in the specified configuration.
If UTF8 is not enabled, this will always be \f[B]NCBLIT_1x1\f[R].
If \f[B]\f[BI]scale\f[B]\f[R] is \f[B]NCSCALE_NONE\f[R] or
\f[B]NCSCALE_SCALE\f[R], the aspect-preserving \f[B]NCBLIT_2x1\f[R] will
be returned.
If sextants are available (see \f[B]notcurses_cansextant\f[R]), this
will be \f[B]NCBLIT_3x2\f[R], or otherwise \f[B]NCBLIT_2x2\f[R].
.SH NOTES
.PP
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
\f[B]ncvisual_from_file\f[R] and \f[B]ncvisual_subtitle_plane\f[R].
.PP
Sixel documentation can be found at
Dankwiki (https://nick-black.com/dankwiki/index.php?title=Sixel).
Kitty\[aq]s graphics protocol is specified in its
documentation (https://sw.kovidgoyal.net/kitty/graphics-protocol.html).
.PP
Bad font support can ruin \f[B]NCBLIT_2x2\f[R], \f[B]NCBLIT_3x2\f[R],
\f[B]NCBLIT_4x1\f[R], \f[B]NCBLIT_BRAILLE\f[R], and
\f[B]NCBLIT_8x1\f[R].
Braille glyphs ought ideally draw only the raised dots, rather than
drawing all eight dots with two different styles.
It\[aq]s often best for the emulator to draw these glyphs itself.
.PP
Several emulators claim to implement Sixel, but do so in a more or less
broken fashion.
I consider \f[B]XTerm\f[R] and \f[B]foot\f[R] to be reference Sixel
implementations on X.org and Wayland, respectively.
.PP
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.
.PP
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.
.PP
The results of \f[B]ncvisual_geom\f[R] are invalidated by a terminal
resize.
.SH BUGS
.PP
Functions which describe rendered state such as \f[B]ncplane_at_yx\f[R]
and \f[B]notcurses_at_yx\f[R] will return an \f[B]nccell\f[R] with a
sprixel ID, but this sprixel cannot be accessed.
.PP
\f[B]ncvisual_rotate\f[R] currently supports only \f[B]M_PI\f[R]/2 and
-\f[B]M_PI\f[R]/2 radians for \f[B]rads\f[R], but this will change soon.
.PP
\f[B]ncvisual_blit\f[R] should be able to create new planes in piles
other than the standard pile.
This ought become a reality soon.
.PP
\f[B]ncvisual_stream\f[R] currently requires a multimedia engine, which
is silly.
This will change in the near future.
.PP
Sprixels interact poorly with multiple planes, and such usage is
discouraged.
This situation might improve in the future.
.PP
Multiple threads may not currently call \f[B]ncvisual_blit\f[R]
concurrently using the same \f[B]ncvisual\f[R], even if targeting
distinct \f[B]ncplane\f[R]s.
This will likely change in the future.
.PP
\f[B]pxoffy\f[R] and \f[B]pxoffx\f[R] are not yet implemented.
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_capabilities(3)\f[R],
\f[B]notcurses_plane(3)\f[R], \f[B]notcurses_render(3)\f[R],
\f[B]utf-8(7)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.