1notcurses_direct(3)                                        notcurses_direct(3)
2
3
4

NAME

6       notcurses_direct - the Direct Mode API
7

SYNOPSIS

9              #include <notcurses/direct.h>
10
11              #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
17       struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t
18       flags);
19
20       unsigned ncdirect_palette_size(const struct ncdirect* nc);
21
22       int ncdirect_set_bg_rgb8(struct ncdirect* nc, unsigned r,  unsigned  g,
23       unsigned b);
24
25       int  ncdirect_set_fg_rgb8(struct  ncdirect* nc, unsigned r, unsigned g,
26       unsigned b);
27
28       int ncdirect_set_fg_rgb(struct ncdirect* nc, unsigned rgb);
29
30       int ncdirect_set_bg_rgb(struct ncdirect* nc, unsigned rgb);
31
32       int ncdirect_set_fg_default(struct ncdirect* nc);
33
34       int ncdirect_set_bg_default(struct ncdirect* nc);
35
36       int ncdirect_set_fg_palindex(struct ncdirect* nc, int pidx);
37
38       int ncdirect_set_bg_palindex(struct ncdirect* nc, int pidx);
39
40       unsigned ncdirect_dim_x(const struct ncdirect* nc);
41
42       unsigned ncdirect_dim_y(const struct ncdirect* nc);
43
44       unsigned ncdirect_supported_styles(const struct ncdirect* nc);
45
46       int ncdirect_styles_set(struct ncdirect* n, unsigned stylebits);
47
48       int ncdirect_styles_on(struct ncdirect* n, unsigned stylebits);
49
50       int ncdirect_styles_off(struct ncdirect* n, unsigned stylebits);
51
52       unsigned ncdirect_styles(struct ncdirect* n);
53
54       int ncdirect_clear(struct ncdirect* nc)
55
56       int ncdirect_stop(struct ncdirect* nc);
57
58       int ncdirect_cursor_move_yx(struct ncdirect* n, int y, int x);
59
60       int ncdirect_cursor_yx(struct ncdirect* n, unsigned* y, unsigned* x);
61
62       int ncdirect_cursor_enable(struct ncdirect* nc);
63
64       int ncdirect_cursor_disable(struct ncdirect* nc);
65
66       int ncdirect_cursor_up(struct ncdirect* nc, int num);
67
68       int ncdirect_cursor_left(struct ncdirect* nc, int num);
69
70       int ncdirect_cursor_right(struct ncdirect* nc, int num);
71
72       int ncdirect_cursor_down(struct ncdirect* nc, int num);
73
74       int ncdirect_putstr(struct ncdirect* nc, uint64_t channels, const char*
75       utf8);
76
77       int ncdirect_putegc(struct ncdirect* nc, uint64_t channels, const char*
78       utf8, int* sbytes);
79
80       int ncdirect_printf_aligned(struct ncdirect* n, int y, ncalign_e align,
81       const char* fmt, ...);
82
83       const char* ncdirect_detected_terminal(const struct ncdirect* n);
84
85       int ncdirect_hline_interp(struct ncdirect* n, const char* egc, unsigned
86       len, uint64_t h1, uint64_t h2);
87
88       int ncdirect_vline_interp(struct ncdirect* n, const char* egc, unsigned
89       len, uint64_t h1, uint64_t h2);
90
91       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
95       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
98       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
101       ncdirectv*  ncdirect_render_frame(struct ncdirect* n, const char* file‐
102       name, ncblitter_e blitter, ncscale_e scale, int maxy, int maxx);
103
104       char* ncdirect_readline(struct ncdirect* n, const char* prompt);
105
106       bool ncdirect_cantruecolor(const struct ncdirect* nc);
107
108       bool ncdirect_canchangecolor(const struct ncdirect* nc);
109
110       bool ncdirect_canfade(const struct ncdirect* nc);
111
112       bool ncdirect_canopen_images(const struct ncdirect* nc);
113
114       bool ncdirect_canopen_videos(const struct ncdirect* nc);
115
116       bool ncdirect_canutf8(const struct ncdirect* nc);
117
118       int ncdirect_check_pixel_support(const struct ncdirect* nc);
119
120       bool ncdirect_canhalfblock(const struct ncdirect* nc);
121
122       bool ncdirect_canquadrant(const struct ncdirect* nc);
123
124       bool ncdirect_cansextant(const struct ncdirect* nc);
125
126       bool ncdirect_canbraille(const struct ncdirect* nc);
127
128       bool ncdirect_canget_cursor(const struct ncdirect* nc);
129
130       uint32_t ncdirect_get(struct ncdirect* n, const struct timespec* absdl,
131       ncinput* ni);
132
133              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
143       int  ncdirect_render_image(struct  ncdirect*  n,  const char* filename,
144       ncblitter_e blitter, ncscale_e scale);
145
146       int  ncdirect_raster_frame(struct   ncdirect*   n,   ncdirectv*   ncdv,
147       ncalign_e align);
148
149       int ncdirect_stream(struct ncdirect* n, const char* filename, ncstream‐
150       cb streamer, struct ncvisual_options* vopts, void* curry);
151
152       int  ncdirect_raster_frame(struct   ncdirect*   n,   ncdirectv*   ncdv,
153       ncalign_e align);
154
155       struct  ncdirectf*  ncdirectf_from_file(struct ncdirect* n, const char*
156       filename);*
157
158       void ncdirectf_free(struct ncdirectf* frame);
159
160       ncdirectv*  ncdirectf_render(struct  ncdirect*  n,  struct   ncdirectf*
161       frame, const struct ncvisual_options vopts);
162
163       int  ncdirectf_geom(struct  ncdirect* n, struct ncdirectf* frame, const
164       struct ncvisual_options vopts, ncvgeom* geom);
165

DESCRIPTION

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
177       The following flags are defined:
178
179NCDIRECT_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
186NCDIRECT_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
190NCDIRECT_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
196NCDIRECT_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
201NCDIRECT_OPTION_VERBOSE: Enable diagnostics to stderr at the level of
202         NCLOGLEVEL_WARNING.
203
204NCDIRECT_OPTION_VERY_VERBOSE:  Enable  all diagnostics (equivalent to
205         NCLOGLEVEL_TRACE).  Implies NCDIRECT_OPTION_VERBOSE.
206
207       The loglevel can also be set externally  using  the  NOTCURSES_LOGLEVEL
208       environment variable.  See notcurses_init(3) for more information.
209
210       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
218       ncdirect_dim_x  returns  the  current  number  of  columns,  and  ncdi‐
219       rect_dim_y the current number of rows.
220
221       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
225       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
228       ncdirect_enable_cursor  and  ncdirect_disable_cursor  always  flush the
229       output stream, taking effect immediately.
230
231       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
235       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
241       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
245       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

RETURN VALUES

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
255       ncdirect_printf_aligned returns the number of bytes written on success.
256       On failure, it returns some negative number.
257
258       ncdirect_putstr returns a nonnegative number on  success,  and  EOF  on
259       failure.
260
261       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
265       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
268       ncdirect_styles returns the current styling, a bitmask over the various
269       NCSTYLE_ constants.
270
271       All other functions return 0 on success, and non-zero on error.
272

NOTES

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

SEE ALSO

279       getenv(3),    notcurses(3),    notcurses_init(3),   notcurses_plane(3),
280       notcurses_visual(3), terminfo(5), termios(3)
281

AUTHORS

283       nick black <nickblack@linux.com>.
284
285
286
287                                    v3.0.8                 notcurses_direct(3)
Impressum