.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_direct" "3" "v3.0.0" "" ""
.hy
.SH NAME
.PP
notcurses_direct - the Direct Mode API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <notcurses/direct.h>

#define NCDIRECT_OPTION_INHIBIT_SETLOCALE   0x0001ull
#define NCDIRECT_OPTION_INHIBIT_CBREAK      0x0002ull
#define NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS 0x0008ull
#define NCDIRECT_OPTION_VERBOSE             0x0010ull
#define NCDIRECT_OPTION_VERY_VERBOSE        0x0020ull
\f[R]
.fi
.PP
\f[B]struct ncdirect* ncdirect_init(const char*
\f[R]\f[I]termtype\f[R]\f[B], FILE* \f[R]\f[I]fp\f[R]\f[B], uint64_t
\f[R]\f[I]flags\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned ncdirect_palette_size(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_bg_rgb8(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
unsigned \f[R]\f[I]r\f[R]\f[B], unsigned \f[R]\f[I]g\f[R]\f[B], unsigned
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_fg_rgb8(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
unsigned \f[R]\f[I]r\f[R]\f[B], unsigned \f[R]\f[I]g\f[R]\f[B], unsigned
\f[R]\f[I]b\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_fg_rgb(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
unsigned \f[R]\f[I]rgb\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_bg_rgb(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
unsigned \f[R]\f[I]rgb\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_fg_default(struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_bg_default(struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_fg_palindex(struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]pidx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_set_bg_palindex(struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]pidx\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned ncdirect_dim_x(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned ncdirect_dim_y(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned ncdirect_supported_styles(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_styles_set(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_styles_on(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_styles_off(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R]
.PP
\f[B]unsigned ncdirect_styles(struct ncdirect*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_clear(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B])\f[R]
.PP
\f[B]int ncdirect_stop(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_cursor_move_yx(struct ncdirect* \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]);\f[R]
.PP
\f[B]int ncdirect_cursor_yx(struct ncdirect* \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]);\f[R]
.PP
\f[B]int ncdirect_cursor_enable(struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_cursor_disable(struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_cursor_up(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], int
\f[R]\f[I]num\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_cursor_left(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
int \f[R]\f[I]num\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_cursor_right(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
int \f[R]\f[I]num\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_cursor_down(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
int \f[R]\f[I]num\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_putstr(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
uint64_t \f[R]\f[I]channels\f[R]\f[B], const char*
\f[R]\f[I]utf8\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_putegc(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B],
uint64_t \f[R]\f[I]channels\f[R]\f[B], const char*
\f[R]\f[I]utf8\f[R]\f[B], int* \f[R]\f[I]sbytes\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_printf_aligned(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]y\f[R]\f[B], ncalign_e \f[R]\f[I]align\f[R]\f[B], const
char* \f[R]\f[I]fmt\f[R]\f[B], \f[R]\f[I]...\f[R]\f[B]);\f[R]
.PP
\f[B]const char* ncdirect_detected_terminal(const struct ncdirect*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_hline_interp(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]egc\f[R]\f[B], unsigned \f[R]\f[I]len\f[R]\f[B],
uint64_t \f[R]\f[I]h1\f[R]\f[B], uint64_t \f[R]\f[I]h2\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_vline_interp(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]egc\f[R]\f[B], unsigned \f[R]\f[I]len\f[R]\f[B],
uint64_t \f[R]\f[I]h1\f[R]\f[B], uint64_t \f[R]\f[I]h2\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_box(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], uint64_t
\f[R]\f[I]ul\f[R]\f[B], uint64_t \f[R]\f[I]ur\f[R]\f[B], uint64_t
\f[R]\f[I]ll\f[R]\f[B], uint64_t \f[R]\f[I]lr\f[R]\f[B], const wchar_t*
\f[R]\f[I]wchars\f[R]\f[B], int \f[R]\f[I]ylen\f[R]\f[B], int
\f[R]\f[I]xlen\f[R]\f[B], unsigned \f[R]\f[I]ctlword\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_rounded_box(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
uint64_t \f[R]\f[I]ul\f[R]\f[B], uint64_t \f[R]\f[I]ur\f[R]\f[B],
uint64_t \f[R]\f[I]ll\f[R]\f[B], uint64_t \f[R]\f[I]lr\f[R]\f[B], int
\f[R]\f[I]ylen\f[R]\f[B], int \f[R]\f[I]xlen\f[R]\f[B], unsigned
\f[R]\f[I]ctlword\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_double_box(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
uint64_t \f[R]\f[I]ul\f[R]\f[B], uint64_t \f[R]\f[I]ur\f[R]\f[B],
uint64_t \f[R]\f[I]ll\f[R]\f[B], uint64_t \f[R]\f[I]lr\f[R]\f[B], int
\f[R]\f[I]ylen\f[R]\f[B], int \f[R]\f[I]xlen\f[R]\f[B], unsigned
\f[R]\f[I]ctlword\f[R]\f[B]);\f[R]
.PP
\f[B]ncdirectv* ncdirect_render_frame(struct ncdirect*
\f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]filename\f[R]\f[B],
ncblitter_e \f[R]\f[I]blitter\f[R]\f[B], ncscale_e
\f[R]\f[I]scale\f[R]\f[B], int \f[R]\f[I]maxy\f[R]\f[B], int
\f[R]\f[I]maxx\f[R]\f[B]);\f[R]
.PP
\f[B]char* ncdirect_readline(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]prompt\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_cantruecolor(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canchangecolor(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canfade(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canopen_images(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canopen_videos(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canutf8(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_check_pixel_support(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canhalfblock(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canquadrant(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_cansextant(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canbraille(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncdirect_canget_cursor(const struct ncdirect*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]uint32_t ncdirect_get(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], const
struct timespec* \f[R]\f[I]absdl\f[R]\f[B], ncinput*
\f[R]\f[I]ni\f[R]\f[B]);\f[R]
.IP
.nf
\f[C]
typedef struct ncvgeom {
  int pixy, pixx;     // true pixel geometry of ncvisual data
  int cdimy, cdimx;   // terminal cell geometry when this was calculated
  int rpixy, rpixx;   // rendered pixel geometry
  int rcelly, rcellx; // rendered cell geometry
  int scaley, scalex; // pixels per filled cell
  // only defined for NCBLIT_PIXEL
  int maxpixely, maxpixelx;
} ncvgeom;
\f[R]
.fi
.PP
\f[B]int ncdirect_render_image(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]filename\f[R]\f[B], ncblitter_e
\f[R]\f[I]blitter\f[R]\f[B], ncscale_e \f[R]\f[I]scale\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_raster_frame(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
ncdirectv* \f[R]\f[I]ncdv\f[R]\f[B], ncalign_e
\f[R]\f[I]align\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirect_stream(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], const
char* \f[R]\f[I]filename\f[R]\f[B], ncstreamcb
\f[R]\f[I]streamer\f[R]\f[B], 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 ncdirect_raster_frame(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
ncdirectv* \f[R]\f[I]ncdv\f[R]\f[B], ncalign_e
\f[R]\f[I]align\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncdirectf* ncdirectf_from_file(struct ncdirect*
\f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]filename\f[R]\f[B]);\f[R]*
.PP
\f[B]void ncdirectf_free(struct ncdirectf*
\f[R]\f[I]frame\f[R]\f[B]);\f[R]
.PP
\f[B]ncdirectv* ncdirectf_render(struct ncdirect* \f[R]\f[I]n\f[R]\f[B],
struct ncdirectf* \f[R]\f[I]frame\f[R]\f[B], const struct
ncvisual_options \f[R]\f[I]vopts\f[R]\f[B]);\f[R]
.PP
\f[B]int ncdirectf_geom(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], struct
ncdirectf* \f[R]\f[I]frame\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]
.SH DESCRIPTION
.PP
\f[B]ncdirect_init\f[R] prepares the \f[B]FILE\f[R] provided as
\f[B]fp\f[R] for colorizing and styling.
On success, a pointer to a valid \f[B]struct ncdirect\f[R] is returned.
\f[B]NULL\f[R] is returned on failure.
Before the process exits, \f[B]ncdirect_stop\f[R] should be called to
reset the terminal and free up resources.
\f[B]ncdirect_init\f[R] places the terminal into \[dq]cbreak\[dq] (also
known as \[dq]rare\[dq]) mode, disabling line-buffering and echo of
input.
\f[B]ncdirect_stop\f[R] restores the terminal state as it was when the
corresponding \f[B]ncdirect_init\f[R] call was made.
A process can have only one context active at once.
.PP
The following flags are defined:
.IP \[bu] 2
\f[B]NCDIRECT_OPTION_INHIBIT_SETLOCALE\f[R]: Unless this flag is set,
\f[B]ncdirect_init\f[R] will call \f[B]setlocale(LC_ALL, NULL)\f[R].
If the result is either \[dq]\f[B]C\f[R]\[dq] or
\[dq]\f[B]POSIX\f[R]\[dq], it will print a diagnostic to
\f[B]stderr\f[R], and then call \f[B]setlocale(LC_ALL, \[dq]\[dq]).\f[R]
This will attempt to set the locale based off the \f[B]LANG\f[R]
environment variable.
Your program should call \f[B]setlocale(3)\f[R] itself, usually as one
of the first lines.
.IP \[bu] 2
\f[B]NCDIRECT_OPTION_INHIBIT_CBREAK\f[R]: Unless this flag is set,
\f[B]ncdirect_init\f[R] will place the terminal into cbreak mode (i.e.
disabling echo and line buffering; see \f[B]tcgetattr(3)\f[R]).
.IP \[bu] 2
\f[B]NCDIRECT_OPTION_DRAIN_INPUT\f[R]: Standard input may be freely
discarded.
If you do not intend to process input, pass this flag.
Otherwise, input can buffer up, eventually preventing Notcurses from
processing terminal messages.
It will furthermore avoid wasting time processing useless input.
.IP \[bu] 2
\f[B]NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS\f[R]: A signal handler will
usually be installed for \f[B]SIGABRT\f[R], \f[B]SIGBUS\f[R],
\f[B]SIGFPE\f[R], \f[B]SIGILL\f[R], \f[B]SIGINT\f[R], \f[B]SIGQUIT\f[R],
\f[B]SIGSEGV\f[R], and \f[B]SIGTERM\f[R], cleaning up the terminal on
such exceptions.
With this flag, the handler will not be installed.
.IP \[bu] 2
\f[B]NCDIRECT_OPTION_VERBOSE\f[R]: Enable diagnostics to
\f[B]stderr\f[R] at the level of \f[B]NCLOGLEVEL_WARNING\f[R].
.IP \[bu] 2
\f[B]NCDIRECT_OPTION_VERY_VERBOSE\f[R]: Enable all diagnostics
(equivalent to \f[B]NCLOGLEVEL_TRACE\f[R]).
Implies \f[B]NCDIRECT_OPTION_VERBOSE\f[R].
.PP
The loglevel can also be set externally using the
\f[B]NOTCURSES_LOGLEVEL\f[R] environment variable.
See \f[B]notcurses_init(3)\f[R] for more information.
.PP
An appropriate \f[B]terminfo(5)\f[R] entry must exist for the terminal.
This entry is usually selected using the value of the \f[B]TERM\f[R]
environment variable (see \f[B]getenv(3)\f[R]), but a non-\f[B]NULL\f[R]
value for \f[B]termtype\f[R] will override this.
An invalid terminfo specification can lead to reduced performance,
reduced display capabilities, and/or display errors.
notcurses natively targets 24bpp/8bpc RGB color, and it is thus
desirable to use a terminal with the \f[B]rgb\f[R] capability (e.g.
xterm\[aq]s \f[B]xterm-direct\f[R]).
.PP
\f[B]ncdirect_dim_x\f[R] returns the current number of columns, and
\f[B]ncdirect_dim_y\f[R] the current number of rows.
.PP
\f[B]ncdirect_clear\f[R] clears the screen using a control code if one
exists in terminfo.
Otherwise, it prints successive newlines to scroll everything off.
.PP
\f[B]ncdirect_cursor_move_yx\f[R] moves the cursor to the specified
coordinate.
-1 can be specified for either \f[B]y\f[R] or \f[B]x\f[R] to leave that
axis unchanged.
.PP
\f[B]ncdirect_enable_cursor\f[R] and \f[B]ncdirect_disable_cursor\f[R]
always flush the output stream, taking effect immediately.
.PP
\f[B]ncdirect_cursor_up\f[R] and friends all move relative to the
current position.
Attempting to e.g.
move up while on the top row will return 0, but have no effect.
.PP
\f[B]ncdirect_readline\f[R] reads a (heap-allocated) line of arbitrary
length, supporting some libreadline-style line-editing controls.
\f[B]NCDIRECT_OPTION_INHIBIT_CBREAK\f[R] should not be used if you
intend to use \f[B]ncdirect_readline\f[R]; if used, line-editing
keybindings cannot be implemented.
Input will be echoed whether this option is used or not.
.PP
\f[B]ncdirect_check_pixel_support\f[R] must be called (and successfully
return) before \f[B]NCBLIT_PIXEL\f[R] can be used to render images; see
\f[B]notcurses_visual(3)\f[R] for more details.
.PP
When rendering an image, \f[B]\f[BI]maxy\f[B]\f[R] and
\f[B]\f[BI]maxx\f[B]\f[R] specify a maximum number of (cell) rows and
columns to use, respectively.
Passing 0 means \[dq]use as much space as is necessary\[dq].
It is an error to pass a negative number for either.
.SH RETURN VALUES
.PP
\f[B]ncdirect_init\f[R] returns \f[B]NULL\f[R] on failure.
Otherwise, the return value points to a valid \f[B]struct ncdirect\f[R],
which can be used until it is provided to \f[B]ncdirect_stop\f[R].
.PP
\f[B]ncdirect_printf_aligned\f[R] returns the number of bytes written on
success.
On failure, it returns some negative number.
.PP
\f[B]ncdirect_putstr\f[R] returns a nonnegative number on success, and
\f[B]EOF\f[R] on failure.
.PP
\f[B]ncdirect_putegc\f[R] returns the number of columns consumed on
success, or -1 on failure.
If \f[B]\f[BI]sbytes\f[B]\f[R] is not \f[B]NULL\f[R], the number of
bytes consumed will be written to it.
.PP
\f[B]ncdirect_check_pixel_support\f[R] returns -1 on error, 0 if there
is no pixel support, and 1 if pixel support is successfully detected.
.PP
\f[B]ncdirect_styles\f[R] returns the current styling, a bitmask over
the various \f[B]NCSTYLE_\f[R] constants.
.PP
All other functions return 0 on success, and non-zero on error.
.SH NOTES
.PP
You are recommended to accept \f[B]-v\f[R] and \f[B]-vv\f[R] as
command-line options, mapping them to \f[B]NCDIRECT_OPTION_VERBOSE\f[R]
and \f[B]NCDIRECT_OPTION_VERY_VERBOSE\f[R] respectively.
.SH SEE ALSO
.PP
\f[B]getenv(3)\f[R], \f[B]notcurses(3)\f[R],
\f[B]notcurses_init(3)\f[R], \f[B]notcurses_plane(3)\f[R],
\f[B]notcurses_visual(3)\f[R], \f[B]terminfo(5)\f[R],
\f[B]termios(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.