notcurses_direct(3) notcurses_direct(3) NAME notcurses_direct - the Direct Mode API 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 struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t flags); unsigned ncdirect_palette_size(const struct ncdirect* nc); int ncdirect_set_bg_rgb8(struct ncdirect* nc, unsigned r, unsigned g, un- signed b); int ncdirect_set_fg_rgb8(struct ncdirect* nc, unsigned r, unsigned g, un- signed b); int ncdirect_set_fg_rgb(struct ncdirect* nc, unsigned rgb); int ncdirect_set_bg_rgb(struct ncdirect* nc, unsigned rgb); int ncdirect_set_fg_default(struct ncdirect* nc); int ncdirect_set_bg_default(struct ncdirect* nc); int ncdirect_set_fg_palindex(struct ncdirect* nc, int pidx); int ncdirect_set_bg_palindex(struct ncdirect* nc, int pidx); unsigned ncdirect_dim_x(const struct ncdirect* nc); unsigned ncdirect_dim_y(const struct ncdirect* nc); unsigned ncdirect_supported_styles(const struct ncdirect* nc); int ncdirect_styles_set(struct ncdirect* n, unsigned stylebits); int ncdirect_styles_on(struct ncdirect* n, unsigned stylebits); int ncdirect_styles_off(struct ncdirect* n, unsigned stylebits); unsigned ncdirect_styles(struct ncdirect* n); int ncdirect_clear(struct ncdirect* nc) int ncdirect_stop(struct ncdirect* nc); int ncdirect_cursor_move_yx(struct ncdirect* n, int y, int x); int ncdirect_cursor_yx(struct ncdirect* n, unsigned* y, unsigned* x); int ncdirect_cursor_enable(struct ncdirect* nc); int ncdirect_cursor_disable(struct ncdirect* nc); int ncdirect_cursor_up(struct ncdirect* nc, int num); int ncdirect_cursor_left(struct ncdirect* nc, int num); int ncdirect_cursor_right(struct ncdirect* nc, int num); int ncdirect_cursor_down(struct ncdirect* nc, int num); int ncdirect_putstr(struct ncdirect* nc, uint64_t channels, const char* utf8); int ncdirect_putegc(struct ncdirect* nc, uint64_t channels, const char* utf8, int* sbytes); int ncdirect_printf_aligned(struct ncdirect* n, int y, ncalign_e align, const char* fmt, ...); const char* ncdirect_detected_terminal(const struct ncdirect* n); int ncdirect_hline_interp(struct ncdirect* n, const char* egc, unsigned len, uint64_t h1, uint64_t h2); int ncdirect_vline_interp(struct ncdirect* n, const char* egc, unsigned len, uint64_t h1, uint64_t h2); int ncdirect_box(struct ncdirect* n, uint64_t ul, uint64_t ur, uint64_t ll, uint64_t lr, const wchar_t* wchars, int ylen, int xlen, unsigned ctlword); int ncdirect_rounded_box(struct ncdirect* n, uint64_t ul, uint64_t ur, uint64_t ll, uint64_t lr, int ylen, int xlen, unsigned ctlword); int ncdirect_double_box(struct ncdirect* n, uint64_t ul, uint64_t ur, uint64_t ll, uint64_t lr, int ylen, int xlen, unsigned ctlword); ncdirectv* ncdirect_render_frame(struct ncdirect* n, const char* filename, ncblitter_e blitter, ncscale_e scale, int maxy, int maxx); char* ncdirect_readline(struct ncdirect* n, const char* prompt); bool ncdirect_cantruecolor(const struct ncdirect* nc); bool ncdirect_canchangecolor(const struct ncdirect* nc); bool ncdirect_canfade(const struct ncdirect* nc); bool ncdirect_canopen_images(const struct ncdirect* nc); bool ncdirect_canopen_videos(const struct ncdirect* nc); bool ncdirect_canutf8(const struct ncdirect* nc); int ncdirect_check_pixel_support(const struct ncdirect* nc); bool ncdirect_canhalfblock(const struct ncdirect* nc); bool ncdirect_canquadrant(const struct ncdirect* nc); bool ncdirect_cansextant(const struct ncdirect* nc); bool ncdirect_canoctant(const struct ncdirect* nc); bool ncdirect_canbraille(const struct ncdirect* nc); bool ncdirect_canget_cursor(const struct ncdirect* nc); uint32_t ncdirect_get(struct ncdirect* n, const struct timespec* absdl, nc- input* 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; int ncdirect_render_image(struct ncdirect* n, const char* filename, ncblit- ter_e blitter, ncscale_e scale); int ncdirect_raster_frame(struct ncdirect* n, ncdirectv* ncdv, ncalign_e align); int ncdirect_stream(struct ncdirect* n, const char* filename, ncstreamcb streamer, struct ncvisual_options* vopts, void* curry); int ncdirect_raster_frame(struct ncdirect* n, ncdirectv* ncdv, ncalign_e align); struct ncdirectf* ncdirectf_from_file(struct ncdirect* n, const char* file- name);* void ncdirectf_free(struct ncdirectf* frame); ncdirectv* ncdirectf_render(struct ncdirect* n, struct ncdirectf* frame, const struct ncvisual_options vopts); int ncdirectf_geom(struct ncdirect* n, struct ncdirectf* frame, const struct ncvisual_options vopts, ncvgeom* geom); DESCRIPTION ncdirect_init prepares the FILE provided as fp for colorizing and styling. On success, a pointer to a valid struct ncdirect is returned. NULL is re- turned 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 setlo- cale(LC_ALL, ""). This will attempt to set the locale based off the LANG environment variable. Your program should call setlocale(3) itself, usu- ally 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 mes- sages. It will furthermore avoid wasting time processing useless input. * NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be in- stalled 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 NCDIRECT_OPTION_VERBOSE. The loglevel can also be set externally using the NOTCURSES_LOGLEVEL envi- ronment variable. See notcurses_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 in- valid terminfo specification can lead to reduced performance, reduced dis- play 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 ter- minfo. 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 immediately. 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, sup- porting some libreadline-style line-editing controls. NCDIRECT_OPTION_IN- HIBIT_CBREAK should not be used if you intend to use ncdirect_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) be- fore 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, respectively. Passing 0 means "use as much space as is necessary". It is an error to pass a negative number for either. RETURN VALUES ncdirect_init returns NULL on failure. Otherwise, the return value points to a valid struct ncdirect, which can be used until it is provided to ncdi- rect_stop. ncdirect_printf_aligned returns the number of bytes written on success. On failure, it returns some negative number. ncdirect_putstr returns a nonnegative number on success, and EOF on fail- ure. 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 writ- ten 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 NC- STYLE_ constants. All other functions return 0 on success, and non-zero on error. NOTES You are recommended to accept -v and -vv as command-line options, mapping them to NCDIRECT_OPTION_VERBOSE and NCDIRECT_OPTION_VERY_VERBOSE respec- tively. SEE ALSO getenv(3), notcurses(3), notcurses_init(3), notcurses_plane(3), notcurses_visual(3), terminfo(5), termios(3) AUTHORS nick black nickblack@linux.com v3.0.16 notcurses_direct(3)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | NOTES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=notcurses_direct&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>