notcurses_direct - the Direct Mode API

Authors

       nick black <nickblack@linux.com>.

                                                     v3.0.7                                  notcurses_direct(3)

Description

ncdirect_init prepares the FILE provided as fp for colorizing and styling. On success, a pointer to a
valid structncdirect is returned. NULL is returned on failure. Before the process exits, ncdirect_stop
should be called to reset the terminal and free up resources. ncdirect_init places the terminal into
"cbreak" (also known as "rare") mode, disabling line-buffering and echo of input. ncdirect_stop restores
the terminal state as it was when the corresponding ncdirect_init call was made. A process can have only
one context active at once.

The following flags are defined:

• NCDIRECT_OPTION_INHIBIT_SETLOCALE: Unless this flag is set, ncdirect_init will call setlocale(LC_ALL,NULL). If the result is either "C" or "POSIX", it will print a diagnostic to stderr, and then call
setlocale(LC_ALL,""). This will attempt to set the locale based off the LANG environment variable.
Your program should call setlocale(3) itself, usually as one of the first lines.

• NCDIRECT_OPTION_INHIBIT_CBREAK: Unless this flag is set, ncdirect_init will place the terminal into
cbreak mode (i.e. disabling echo and line buffering; see tcgetattr(3)).

• NCDIRECT_OPTION_DRAIN_INPUT: 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.

• NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be installed for SIGABRT, SIGBUS,
SIGFPE, SIGILL, SIGINT, SIGQUIT, SIGSEGV, and SIGTERM, cleaning up the terminal on such exceptions.
With this flag, the handler will not be installed.

• NCDIRECT_OPTION_VERBOSE: Enable diagnostics to stderr at the level of NCLOGLEVEL_WARNING.

• NCDIRECT_OPTION_VERY_VERBOSE: Enable all diagnostics (equivalent to NCLOGLEVEL_TRACE). Implies NCDI‐RECT_OPTION_VERBOSE.

The loglevel can also be set externally using the NOTCURSES_LOGLEVEL environment variable. See notcurs‐es_init(3) for more information.

An appropriate terminfo(5) entry must exist for the terminal. This entry is usually selected using the
value of the TERM environment variable (see getenv(3)), but a non-NULL value for termtype 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 rgb capability (e.g. xterm's xterm-direct).

ncdirect_dim_x returns the current number of columns, and ncdirect_dim_y the current number of rows.

ncdirect_clear clears the screen using a control code if one exists in terminfo. Otherwise, it prints
successive newlines to scroll everything off.

ncdirect_cursor_move_yx moves the cursor to the specified coordinate. -1 can be specified for either y
or x to leave that axis unchanged.

ncdirect_enable_cursor and ncdirect_disable_cursor always flush the output stream, taking effect immedi‐
ately.

ncdirect_cursor_up 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.

ncdirect_readline reads a (heap-allocated) line of arbitrary length, supporting some libreadline-style
line-editing controls. NCDIRECT_OPTION_INHIBIT_CBREAK should not be used if you intend to use ncdi‐rect_readline; if used, line-editing keybindings cannot be implemented. Input will be echoed whether
this option is used or not.

ncdirect_check_pixel_support must be called (and successfully return) before NCBLIT_PIXEL can be used to
render images; see notcurses_visual(3) for more details.

When rendering an image, maxy and maxx specify a maximum number of (cell) rows and columns to use, re‐
spectively. Passing 0 means "use as much space as is necessary". It is an error to pass a negative num‐
ber for either.

Name

       notcurses_direct - the Direct Mode API

Notes

       You are recommended to accept -v and -vv as command-line options, mapping them to NCDIRECT_OPTION_VERBOSE
       and NCDIRECT_OPTION_VERY_VERBOSE respectively.

Return Values

ncdirect_init returns NULL on failure.  Otherwise, the return value points to a  valid  structncdirect,
       which can be used until it is provided to ncdirect_stop.

       ncdirect_printf_aligned returns the number of bytes written on success.  On failure, it returns some neg‐
       ative number.

       ncdirect_putstr returns a nonnegative number on success, and EOF on failure.

       ncdirect_putegc  returns  the  number of columns consumed on success, or -1 on failure.  If sbytes is not
       NULL, the number of bytes consumed will be written to it.

       ncdirect_check_pixel_support returns -1 on error, 0 if there is no pixel support, and 1 if pixel  support
       is successfully detected.

       ncdirect_styles returns the current styling, a bitmask over the various NCSTYLE_ constants.

       All other functions return 0 on success, and non-zero on error.

Synopsis

              #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

       structncdirect*ncdirect_init(constchar*termtype,FILE*fp,uint64_tflags);unsignedncdirect_palette_size(conststructncdirect*nc);intncdirect_set_bg_rgb8(structncdirect*nc,unsignedr,unsignedg,unsignedb);intncdirect_set_fg_rgb8(structncdirect*nc,unsignedr,unsignedg,unsignedb);intncdirect_set_fg_rgb(structncdirect*nc,unsignedrgb);intncdirect_set_bg_rgb(structncdirect*nc,unsignedrgb);intncdirect_set_fg_default(structncdirect*nc);intncdirect_set_bg_default(structncdirect*nc);intncdirect_set_fg_palindex(structncdirect*nc,intpidx);intncdirect_set_bg_palindex(structncdirect*nc,intpidx);unsignedncdirect_dim_x(conststructncdirect*nc);unsignedncdirect_dim_y(conststructncdirect*nc);unsignedncdirect_supported_styles(conststructncdirect*nc);intncdirect_styles_set(structncdirect*n,unsignedstylebits);intncdirect_styles_on(structncdirect*n,unsignedstylebits);intncdirect_styles_off(structncdirect*n,unsignedstylebits);unsignedncdirect_styles(structncdirect*n);intncdirect_clear(structncdirect*nc)intncdirect_stop(structncdirect*nc);intncdirect_cursor_move_yx(structncdirect*n,inty,intx);intncdirect_cursor_yx(structncdirect*n,unsigned*y,unsigned*x);intncdirect_cursor_enable(structncdirect*nc);intncdirect_cursor_disable(structncdirect*nc);intncdirect_cursor_up(structncdirect*nc,intnum);intncdirect_cursor_left(structncdirect*nc,intnum);intncdirect_cursor_right(structncdirect*nc,intnum);intncdirect_cursor_down(structncdirect*nc,intnum);intncdirect_putstr(structncdirect*nc,uint64_tchannels,constchar*utf8);intncdirect_putegc(structncdirect*nc,uint64_tchannels,constchar*utf8,int*sbytes);intncdirect_printf_aligned(structncdirect*n,inty,ncalign_ealign,constchar*fmt,...);constchar*ncdirect_detected_terminal(conststructncdirect*n);intncdirect_hline_interp(structncdirect*n,constchar*egc,unsignedlen,uint64_th1,uint64_th2);intncdirect_vline_interp(structncdirect*n,constchar*egc,unsignedlen,uint64_th1,uint64_th2);intncdirect_box(structncdirect*n,uint64_tul,uint64_tur,uint64_tll,uint64_tlr,constwchar_t*wchars,intylen,intxlen,unsignedctlword);intncdirect_rounded_box(structncdirect*n,uint64_tul,uint64_tur,uint64_tll,uint64_tlr,intylen,intxlen,unsignedctlword);intncdirect_double_box(structncdirect*n,uint64_tul,uint64_tur,uint64_tll,uint64_tlr,intylen,intxlen,unsignedctlword);ncdirectv*ncdirect_render_frame(structncdirect*n,constchar*filename,ncblitter_eblitter,ncscale_escale,intmaxy,intmaxx);char*ncdirect_readline(structncdirect*n,constchar*prompt);boolncdirect_cantruecolor(conststructncdirect*nc);boolncdirect_canchangecolor(conststructncdirect*nc);boolncdirect_canfade(conststructncdirect*nc);boolncdirect_canopen_images(conststructncdirect*nc);boolncdirect_canopen_videos(conststructncdirect*nc);boolncdirect_canutf8(conststructncdirect*nc);intncdirect_check_pixel_support(conststructncdirect*nc);boolncdirect_canhalfblock(conststructncdirect*nc);boolncdirect_canquadrant(conststructncdirect*nc);boolncdirect_cansextant(conststructncdirect*nc);boolncdirect_canbraille(conststructncdirect*nc);boolncdirect_canget_cursor(conststructncdirect*nc);uint32_tncdirect_get(structncdirect*n,conststructtimespec*absdl,ncinput*ni);

              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;

       intncdirect_render_image(structncdirect*n,constchar*filename,ncblitter_eblitter,ncscale_escale);intncdirect_raster_frame(structncdirect*n,ncdirectv*ncdv,ncalign_ealign);intncdirect_stream(structncdirect*n,constchar*filename,ncstreamcbstreamer,structncvisual_op‐tions*vopts,void*curry);intncdirect_raster_frame(structncdirect*n,ncdirectv*ncdv,ncalign_ealign);structncdirectf*ncdirectf_from_file(structncdirect*n,constchar*filename);*

       voidncdirectf_free(structncdirectf*frame);ncdirectv*ncdirectf_render(structncdirect*n,structncdirectf*frame,conststructncvisual_optionsvopts);intncdirectf_geom(structncdirect*n,structncdirectf*frame,conststructncvisual_optionsvopts,ncv‐geom*geom);