1notcurses_direct(3) notcurses_direct(3)
2
6 notcurses_direct - the Direct Mode API
7
9 #include <notcurses/direct.h>
10 #define NCDIRECT_OPTION_INHIBIT_SETLOCALE 0x0001ull
12 #define NCDIRECT_OPTION_INHIBIT_CBREAK 0x0002ull
13 #define NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS 0x0008ull
14 #define NCDIRECT_OPTION_VERBOSE 0x0010ull
15 #define NCDIRECT_OPTION_VERY_VERBOSE 0x0020ull
16 struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t
18 flags);
19 unsigned ncdirect_palette_size(const struct ncdirect* nc);
21 int ncdirect_set_bg_rgb8(struct ncdirect* nc, unsigned r, unsigned g,
23 unsigned b);
24 int ncdirect_set_fg_rgb8(struct ncdirect* nc, unsigned r, unsigned g,
26 unsigned b);
27 int ncdirect_set_fg_rgb(struct ncdirect* nc, unsigned rgb);
29 int ncdirect_set_bg_rgb(struct ncdirect* nc, unsigned rgb);
31 int ncdirect_set_fg_default(struct ncdirect* nc);
33 int ncdirect_set_bg_default(struct ncdirect* nc);
35 int ncdirect_set_fg_palindex(struct ncdirect* nc, int pidx);
37 int ncdirect_set_bg_palindex(struct ncdirect* nc, int pidx);
39 unsigned ncdirect_dim_x(const struct ncdirect* nc);
41 unsigned ncdirect_dim_y(const struct ncdirect* nc);
43 unsigned ncdirect_supported_styles(const struct ncdirect* nc);
45 int ncdirect_styles_set(struct ncdirect* n, unsigned stylebits);
47 int ncdirect_styles_on(struct ncdirect* n, unsigned stylebits);
49 int ncdirect_styles_off(struct ncdirect* n, unsigned stylebits);
51 unsigned ncdirect_styles(struct ncdirect* n);
53 int ncdirect_clear(struct ncdirect* nc)
55 int ncdirect_stop(struct ncdirect* nc);
57 int ncdirect_cursor_move_yx(struct ncdirect* n, int y, int x);
59 int ncdirect_cursor_yx(struct ncdirect* n, unsigned* y, unsigned* x);
61 int ncdirect_cursor_enable(struct ncdirect* nc);
63 int ncdirect_cursor_disable(struct ncdirect* nc);
65 int ncdirect_cursor_up(struct ncdirect* nc, int num);
67 int ncdirect_cursor_left(struct ncdirect* nc, int num);
69 int ncdirect_cursor_right(struct ncdirect* nc, int num);
71 int ncdirect_cursor_down(struct ncdirect* nc, int num);
73 int ncdirect_putstr(struct ncdirect* nc, uint64_t channels, const char*
75 utf8);
76 int ncdirect_putegc(struct ncdirect* nc, uint64_t channels, const char*
78 utf8, int* sbytes);
79 int ncdirect_printf_aligned(struct ncdirect* n, int y, ncalign_e align,
81 const char* fmt, ...);
82 const char* ncdirect_detected_terminal(const struct ncdirect* n);
84 int ncdirect_hline_interp(struct ncdirect* n, const char* egc, unsigned
86 len, uint64_t h1, uint64_t h2);
87 int ncdirect_vline_interp(struct ncdirect* n, const char* egc, unsigned
89 len, uint64_t h1, uint64_t h2);
90 int ncdirect_box(struct ncdirect* n, uint64_t ul, uint64_t ur, uint64_t
92 ll, uint64_t lr, const wchar_t* wchars, int ylen, int xlen, unsigned
93 ctlword);
94 int ncdirect_rounded_box(struct ncdirect* n, uint64_t ul, uint64_t ur,
96 uint64_t ll, uint64_t lr, int ylen, int xlen, unsigned ctlword);
97 int ncdirect_double_box(struct ncdirect* n, uint64_t ul, uint64_t ur,
99 uint64_t ll, uint64_t lr, int ylen, int xlen, unsigned ctlword);
100 ncdirectv* ncdirect_render_frame(struct ncdirect* n, const char* file‐
102 name, ncblitter_e blitter, ncscale_e scale, int maxy, int maxx);
103 char* ncdirect_readline(struct ncdirect* n, const char* prompt);
105 bool ncdirect_cantruecolor(const struct ncdirect* nc);
107 bool ncdirect_canchangecolor(const struct ncdirect* nc);
109 bool ncdirect_canfade(const struct ncdirect* nc);
111 bool ncdirect_canopen_images(const struct ncdirect* nc);
113 bool ncdirect_canopen_videos(const struct ncdirect* nc);
115 bool ncdirect_canutf8(const struct ncdirect* nc);
117 int ncdirect_check_pixel_support(const struct ncdirect* nc);
119 bool ncdirect_canhalfblock(const struct ncdirect* nc);
121 bool ncdirect_canquadrant(const struct ncdirect* nc);
123 bool ncdirect_cansextant(const struct ncdirect* nc);
125 bool ncdirect_canbraille(const struct ncdirect* nc);
127 bool ncdirect_canget_cursor(const struct ncdirect* nc);
129 uint32_t ncdirect_get(struct ncdirect* n, const struct timespec* absdl,
131 ncinput* ni);
132 typedef struct ncvgeom {
134 int pixy, pixx; // true pixel geometry of ncvisual data
135 int cdimy, cdimx; // terminal cell geometry when this was calculated
136 int rpixy, rpixx; // rendered pixel geometry
137 int rcelly, rcellx; // rendered cell geometry
138 int scaley, scalex; // pixels per filled cell
139 // only defined for NCBLIT_PIXEL
140 int maxpixely, maxpixelx;
141 } ncvgeom;
142 int ncdirect_render_image(struct ncdirect* n, const char* filename,
144 ncblitter_e blitter, ncscale_e scale);
145 int ncdirect_raster_frame(struct ncdirect* n, ncdirectv* ncdv,
147 ncalign_e align);
148 int ncdirect_stream(struct ncdirect* n, const char* filename, ncstream‐
150 cb streamer, struct ncvisual_options* vopts, void* curry);
151 int ncdirect_raster_frame(struct ncdirect* n, ncdirectv* ncdv,
153 ncalign_e align);
154 struct ncdirectf* ncdirectf_from_file(struct ncdirect* n, const char*
156 filename);*
157 void ncdirectf_free(struct ncdirectf* frame);
159 ncdirectv* ncdirectf_render(struct ncdirect* n, struct ncdirectf*
161 frame, const struct ncvisual_options vopts);
162 int ncdirectf_geom(struct ncdirect* n, struct ncdirectf* frame, const
164 struct ncvisual_options vopts, ncvgeom* geom);
165
167 ncdirect_init prepares the FILE provided as fp for colorizing and
168 styling. On success, a pointer to a valid struct ncdirect is returned.
169 NULL is returned on failure. Before the process exits, ncdirect_stop
170 should be called to reset the terminal and free up resources. ncdi‐
171 rect_init places the terminal into "cbreak" (also known as "rare")
172 mode, disabling line-buffering and echo of input. ncdirect_stop re‐
173 stores the terminal state as it was when the corresponding ncdi‐
174 rect_init call was made. A process can have only one context active at
175 once.
176 The following flags are defined:
178 • NCDIRECT_OPTION_INHIBIT_SETLOCALE: Unless this flag is set, ncdi‐
180 rect_init will call setlocale(LC_ALL, NULL). If the result is either
181 "C" or "POSIX", it will print a diagnostic to stderr, and then call
182 setlocale(LC_ALL, ""). This will attempt to set the locale based off
183 the LANG environment variable. Your program should call setlocale(3)
184 itself, usually as one of the first lines.
185 • NCDIRECT_OPTION_INHIBIT_CBREAK: Unless this flag is set, ncdi‐
187 rect_init will place the terminal into cbreak mode (i.e. disabling
188 echo and line buffering; see tcgetattr(3)).
189 • NCDIRECT_OPTION_DRAIN_INPUT: Standard input may be freely discarded.
191 If you do not intend to process input, pass this flag. Otherwise,
192 input can buffer up, eventually preventing Notcurses from processing
193 terminal messages. It will furthermore avoid wasting time processing
194 useless input.
195 • NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be
197 installed for SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGINT, SIGQUIT,
198 SIGSEGV, and SIGTERM, cleaning up the terminal on such exceptions.
199 With this flag, the handler will not be installed.
200 • NCDIRECT_OPTION_VERBOSE: Enable diagnostics to stderr at the level of
202 NCLOGLEVEL_WARNING.
203 • NCDIRECT_OPTION_VERY_VERBOSE: Enable all diagnostics (equivalent to
205 NCLOGLEVEL_TRACE). Implies NCDIRECT_OPTION_VERBOSE.
206 The loglevel can also be set externally using the NOTCURSES_LOGLEVEL
208 environment variable. See notcurses_init(3) for more information.
209 An appropriate terminfo(5) entry must exist for the terminal. This en‐
211 try is usually selected using the value of the TERM environment vari‐
212 able (see getenv(3)), but a non-NULL value for termtype will override
213 this. An invalid terminfo specification can lead to reduced perfor‐
214 mance, reduced display capabilities, and/or display errors. notcurses
215 natively targets 24bpp/8bpc RGB color, and it is thus desirable to use
216 a terminal with the rgb capability (e.g. xterm's xterm-direct).
217 ncdirect_dim_x returns the current number of columns, and ncdi‐
219 rect_dim_y the current number of rows.
220 ncdirect_clear clears the screen using a control code if one exists in
222 terminfo. Otherwise, it prints successive newlines to scroll every‐
223 thing off.
224 ncdirect_cursor_move_yx moves the cursor to the specified coordinate.
226 -1 can be specified for either y or x to leave that axis unchanged.
227 ncdirect_enable_cursor and ncdirect_disable_cursor always flush the
229 output stream, taking effect immediately.
230 ncdirect_cursor_up and friends all move relative to the current posi‐
232 tion. Attempting to e.g. move up while on the top row will return 0,
233 but have no effect.
234 ncdirect_readline reads a (heap-allocated) line of arbitrary length,
236 supporting some libreadline-style line-editing controls. NCDIRECT_OP‐
237 TION_INHIBIT_CBREAK should not be used if you intend to use ncdi‐
238 rect_readline; if used, line-editing keybindings cannot be implemented.
239 Input will be echoed whether this option is used or not.
240 ncdirect_check_pixel_support must be called (and successfully return)
242 before NCBLIT_PIXEL can be used to render images; see notcurses_vis‐
243 ual(3) for more details.
244 When rendering an image, maxy and maxx specify a maximum number of
246 (cell) rows and columns to use, respectively. Passing 0 means "use as
247 much space as is necessary". It is an error to pass a negative number
248 for either.
249
251 ncdirect_init returns NULL on failure. Otherwise, the return value
252 points to a valid struct ncdirect, which can be used until it is pro‐
253 vided to ncdirect_stop.
254 ncdirect_printf_aligned returns the number of bytes written on success.
256 On failure, it returns some negative number.
257 ncdirect_putstr returns a nonnegative number on success, and EOF on
259 failure.
260 ncdirect_putegc returns the number of columns consumed on success, or
262 -1 on failure. If sbytes is not NULL, the number of bytes consumed
263 will be written to it.
264 ncdirect_check_pixel_support returns -1 on error, 0 if there is no pix‐
266 el support, and 1 if pixel support is successfully detected.
267 ncdirect_styles returns the current styling, a bitmask over the various
269 NCSTYLE_ constants.
270 All other functions return 0 on success, and non-zero on error.
272
274 You are recommended to accept -v and -vv as command-line options, map‐
275 ping them to NCDIRECT_OPTION_VERBOSE and NCDIRECT_OPTION_VERY_VERBOSE
276 respectively.
277
279 getenv(3), notcurses(3), notcurses_init(3), notcurses_plane(3),
280 notcurses_visual(3), terminfo(5), termios(3)
281
283 nick black <nickblack@linux.com>.
284 v3.0.8 notcurses_direct(3)