1notcurses_visual(3) notcurses_visual(3)
2
6 notcurses_visual - notcurses multimedia
7
9 #include <notcurses/notcurses.h>
10 typedef enum {
12 NCSCALE_NONE,
13 NCSCALE_SCALE,
14 NCSCALE_STRETCH,
15 NCSCALE_NONE_HIRES,
16 NCSCALE_SCALE_HIRES,
17 } ncscale_e;
18 typedef enum {
20 NCBLIT_DEFAULT, // let the ncvisual pick
21 NCBLIT_1x1, // spaces only
22 NCBLIT_2x1, // halves + 1x1
23 NCBLIT_2x2, // quadrants + 2x1
24 NCBLIT_3x2, // sextants + 1x1
25 NCBLIT_4x1, // four vertical levels
26 NCBLIT_BRAILLE, // 4 rows, 2 cols (braille)
27 NCBLIT_8x1, // eight vertical levels
28 NCBLIT_PIXEL, // pixel graphics
29 } ncblitter_e;
30 #define NCVISUAL_OPTION_NODEGRADE 0x0001
32 #define NCVISUAL_OPTION_BLEND 0x0002
33 struct ncvisual_options {
35 struct ncplane* n;
36 ncscale_e scaling;
37 int y, x;
38 int begy, begx; // origin of rendered section
39 int leny, lenx; // size of rendered section
40 ncblitter_e blitter; // glyph set to use
41 uint64_t flags; // bitmask over NCVISUAL_OPTION_*
42 };
43 typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
45 struct ncvisual* ncvisual_from_file(const char* file);
47 struct ncvisual* ncvisual_from_rgba(const void* rgba, int rows, int
49 rowstride, int cols);
50 struct ncvisual* ncvisual_from_bgra(const void* bgra, int rows, int
52 rowstride, int cols);
53 struct ncvisual* ncvisual_from_plane(struct ncplane* n, ncblitter_e
55 blit, int begy, int begx, int leny, int lenx);
56 int ncvisual_geom(const struct notcurses* nc, const struct ncvisual* n,
58 const struct ncvisual_options* vopts, int* y, int* x, int* toy, int*
59 tox);
60 void ncvisual_destroy(struct ncvisual* ncv);
62 int ncvisual_decode(struct ncvisual* ncv);
64 int ncvisual_decode_loop(struct ncvisual* ncv);
66 struct ncplane* ncvisual_render(struct notcurses* nc, struct ncvisual*
68 ncv, const struct ncvisual_options* vopts);
69 int ncvisual_simple_streamer(struct ncplane* n, struct ncvisual* ncv,
71 const struct timespec* disptime, void* curry);
72 int ncvisual_stream(struct notcurses* nc, struct ncvisual* ncv, float
74 timescale, streamcb streamer, const struct ncvisual_options* vopts,
75 void* curry);
76 int ncvisual_rotate(struct ncvisual* n, double rads);
78 int ncvisual_resize(struct ncvisual* n, int rows, int cols);
80 int ncvisual_polyfill_yx(struct ncvisual* n, int y, int x, uint32_t rg‐
82 ba);
83 int ncvisual_at_yx(const struct ncvisual* n, int y, int x, uint32_t*
85 pixel);
86 int ncvisual_set_yx(const struct ncvisual* n, int y, int x, uint32_t
88 pixel);
89 char* ncvisual_subtitle(const struct ncvisual* ncv);
91 int notcurses_lex_scalemode(const char* op, ncscale_e* scaling);
93 const char* notcurses_str_scalemode(ncscale_e scaling);
95 int notcurses_lex_blitter(const char* op, ncblitter_e* blitter);
97 const char* notcurses_str_blitter(ncblitter_e blitter);
99 ncblitter_e ncvisual_media_defblitter(const struct notcurses nc, nc‐
101 scale_e scaling);
102 int ncplane_qrcode(struct ncplane* n, int* ymax, int* xmax, const void*
104 data, size_t len)
105 int notcurses_check_pixel_support(struct notcurses* nc);
107
109 An ncvisual is a virtual pixel framebuffer. They can be created from
110 RGBA/BGRA data in memory (ncvisual_from_rgba/ncvisual_from_bgra), or
111 from the content of a suitable ncplane (ncvisual_from_ncplane). If
112 Notcurses was built against a multimedia engine (FFMpeg or OpenIm‐
113 ageIO), image and video files can be loaded into visuals using ncvisu‐
114 al_from_file. ncvisual_from_file discovers the container and codecs,
115 but does not verify that the entire file is well-formed. ncvisual_de‐
116 code ought be invoked to recover subsequent frames, once per frame.
117 ncvisual_decode_loop will return to the first frame, as if ncvisual_de‐
118 code had never been called.
119 Once the visual is loaded, it can be transformed using ncvisual_rotate
121 and ncvisual_resize. These are persistent operations, unlike any scal‐
122 ing that takes place at render time. If a subtitle is associated with
123 the frame, it can be acquired with ncvisual_subtitle.
124 ncvisual_from_rgba and ncvisual_from_bgra both require a number of
126 rows, a number of image columns cols, and a virtual row length of row‐
127 stride / 4 columns. The input data must provide 32 bits per pixel, and
128 thus must be at least rowstride * rows bytes, of which a cols * rows *
129 4-byte subset is used. It is not possible to mmap(2) an image file and
130 use it directly--decompressed, decoded data is necessary. The result‐
131 ing plane will be ceil(rows/2) rows, and cols columns. ncvisu‐
132 al_from_plane requires specification of a rectangle via begy, begx, le‐
133 ny, and lenx. The only valid characters within this region are those
134 used by the NCBLIT_2x2 blitter, though this may change in the future.
135 ncvisual_rotate executes a rotation of rads radians, in the clockwise
137 (positive) or counterclockwise (negative) direction.
138 ncvisual_subtitle will return a UTF-8-encoded subtitle corresponding to
140 the current frame if such a subtitle was decoded. Note that a subtitle
141 might be returned for multiple frames, or might not.
142 ncvisual_render blits the visual to an ncplane, based on the contents
144 of its struct ncvisual_options. If n is not NULL, it specifies the
145 plane on which to render, and y/x specify a location within that plane.
146 Otherwise, a new plane will be created, and placed at y/x relative to
147 the rendering area. begy/begx specify the upper left corner of a sub‐
148 section of the ncvisual to render, while leny/lenx specify the geometry
149 of same. flags is a bitfield over:
150 · NCVISUAL_OPTION_NODEGRADE If the specified blitter is not available,
152 fail rather than degrading.
153 · NCVISUAL_OPTION_BLEND: Render with CELL_ALPHA_BLEND.
155 ncplane_qrcode draws an ISO/IEC 18004:2015 QR Code for the len bytes of
157 data using NCBLIT_2x1 (this is the only blitter that will work with QR
158 Code scanners, due to its 1:1 aspect ratio).
159
161 The different ncblitter_e values select from among available glyph
162 sets:
163 · NCBLIT_DEFAULT: Let the ncvisual choose its own blitter.
165 · NCBLIT_1x1: Spaces only. Works in ASCII, unlike other blitters.
167 · NCBLIT_2x1: Adds the half blocks (▄▀) to NCBLIT_1x1.
169 · NCBLIT_2x2: Adds left and right half blocks (▌▐) and quadrants (▖▗▟▙)
171 to NCBLIT_2x1.
172 · NCBLIT_3x2: Adds sextants to NCBLIT_1x1.
174 · NCBLIT_4x1: Adds ¼ and ¾ blocks (▂▆) to NCBLIT_2x1.
176 · NCBLIT_BRAILLE: 4 rows and 2 columns of braille
178 (⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿).
179 · NCBLIT_8x1: Adds ⅛, ⅜, ⅝, and ⅞ blocks (▇▅▃▁) to NCBLIT_4x1.
181 · NCBLIT_PIXEL: Adds pixel graphics.
183 NCBLIT_4x1 and NCBLIT_8x1 are intended for use with plots, and are not
185 really applicable for general visuals. NCBLIT_BRAILLE doesn't tend to
186 work out very well for images, but (depending on the font) can be very
187 good for plots.
188 A string can be transformed to a blitter with notcurses_lex_blitter,
190 recognizing ascii, half, quad, sex, fourstep, braille, eightstep, and
191 pixel. Conversion in the opposite direction is performed with notcurs‐
192 es_str_blitter.
193 In the absence of scaling, for a given set of pixels, more rows and
195 columns in the blitter will result in a smaller output image. An image
196 rendered with NCBLIT_1x1 will be twice as tall as the same image ren‐
197 dered with NCBLIT_2x1, which will be twice as wide as the same image
198 rendered with NCBLIT_2x2. The same image rendered with NCBLIT_3x2 will
199 be one-third as tall and one-half as wide as the original NCBLIT_1x1
200 render (again, this depends on NCSCALE_NONE). If the output size is
201 held constant (using for instance NCSCALE_SCALE_HIRES and a large im‐
202 age), more rows and columns will result in more effective resolution.
203 A string can be transformed to a scaling mode with notcurses_lex_scale‐
205 mode, recognizing stretch, scalehi, hires, scale, and none. Conversion
206 in the opposite direction is performed with notcurses_str_scalemode.
207 Assuming a cell is twice as tall as it is wide, NCBLIT_1x1 (and indeed
209 any NxN blitter) will stretch an image by a factor of 2 in the vertical
210 dimension. NCBLIT_2x1 will not distort the image whatsoever, as it
211 maps a vector two pixels high and one pixel wide to a single cell.
212 NCBLIT_3x2 will stretch an image by a factor of 1.5.
213 The cell's dimension in pixels is ideally evenly divisible by the blit‐
215 ter geometry. If NCBLIT_3x2 is used together with a cell 8 pixels wide
216 and 14 pixels tall, two of the vertical segments will be 5 pixels tall,
217 while one will be 4 pixels tall. Such unequal distributions are more
218 likely with larger blitter geometries. Likewise, there are only ever
219 two colors available to us in a given cell. NCBLIT_1x1 and NCBLIT_2x2
220 can be perfectly represented with two colors per cell. Blitters of
221 higher geometry are increasingly likely to require some degree of in‐
222 terpolation. Transparency is always honored with complete fidelity.
223 Finally, rendering operates slightly differently when two planes have
225 both been blitted, and one lies atop the other. See notcurses_ren‐
226 der(3) for more information.
227
229 Some terminals support pixel-based output, either via Sixel or some be‐
230 spoke mechanism. Checking for Sixel support requires interrogating the
231 terminal and reading a response. This takes time, and will never com‐
232 plete if the terminal doesn't respond. Before NCBLIT_PIXEL can be
233 used, it is thus necessary to check for support with notcurs‐
234 es_check_pixel_support. If this function has not successfully re‐
235 turned, attempts to use NCBLIT_PIXEL will fall back to NCBLIT_3x2 (or
236 fail, if NCVISUAL_OPTION_NODEGRADE is used).
237
239 ncvisual_from_file returns an ncvisual object on success, or NULL on
240 failure. Success indicates that the specified file was opened, and
241 enough data was read to make a firm codec identification. It does not
242 imply that the entire file is properly-formed.
243 ncvisual_decode returns 0 on success, or 1 on end of file, or -1 on
245 failure. It is only necessary for multimedia-based visuals. It ad‐
246 vances one frame for each call. ncvisual_decode_loop has the same re‐
247 turn values: when called following decoding of the last frame, it will
248 return 1, but a subsequent ncvisual_render will return the first frame.
249 ncvisual_from_plane returns NULL if the ncvisual cannot be created and
251 bound. This is usually due to illegal content in the source ncplane.
252 ncvisual_render returns NULL on error, and otherwise the plane to which
254 the visual was rendered. If opts->n is provided, this will be opts->n.
255 Otherwise, a plane will be created, perfectly sized for the visual and
256 the specified blitter.
257 ncvisual_geom returns non-zero if the blitter is invalid.
259 ncvisual_media_defblitter returns the blitter selected by NCBLIT_DE‐
261 FAULT in the specified configuration. If UTF8 is not enabled, this
262 will always be NCBLIT_1x1. If scale is NCSCALE_NONE or NCSCALE_SCALE,
263 the aspect-preserving NCBLIT_2x1 will be returned. If sextants are
264 available (see notcurses_cansextant), this will be NCBLIT_3x2, or oth‐
265 erwise NCBLIT_2x2.
266
268 Multimedia decoding requires that Notcurses be built with either FFmpeg
269 or OpenImageIO support. What formats can be decoded is totally depen‐
270 dent on the linked library. OpenImageIO does not support subtitles.
271
273 ncvisual_rotate currently supports only M_PI/2 and -M_PI/2 radians for
274 rads, but this will change soon.
275 Bad font support can ruin NCBLIT_2x2, NCBLIT_3x2, NCBLIT_4x1,
277 NCBLIT_BRAILLE, and NCBLIT_8x1. Braille glyphs ought ideally draw only
278 the raised dots, rather than drawing all eight dots with two different
279 styles. It's often best for the emulator to draw these glyphs itself.
280
282 notcurses(3), notcurses_capabilities(3), notcurses_plane(3), notcurs‐
283 es_render(3), utf-8(7)
284
286 nick black <nickblack@linux.com>.
287 v2.2.3 notcurses_visual(3)