2020-06-03 20:32:27 +00:00
% notcurses_visual(3)
2020-01-02 02:23:11 +00:00
% nick black < nickblack @ linux . com >
2021-01-04 00:55:32 +00:00
% v2.1.4
2020-01-02 02:23:11 +00:00
# NAME
2020-06-03 20:32:27 +00:00
notcurses_visual - notcurses multimedia
2020-01-02 02:23:11 +00:00
# SYNOPSIS
2020-04-19 22:46:32 +00:00
**#include < notcurses / notcurses . h > **
2020-01-02 02:23:11 +00:00
2020-01-04 07:37:55 +00:00
```c
typedef enum {
NCSCALE_NONE,
NCSCALE_SCALE,
NCSCALE_STRETCH,
2020-12-25 23:25:44 +00:00
NCSCALE_NONE_HIRES,
NCSCALE_SCALE_HIRES,
2020-01-04 07:37:55 +00:00
} ncscale_e;
2020-01-14 20:50:17 +00:00
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
typedef enum {
2020-07-25 22:36:15 +00:00
NCBLIT_DEFAULT, // let the ncvisual pick
2020-10-25 22:49:57 +00:00
NCBLIT_1x1, // spaces only
NCBLIT_2x1, // halves + 1x1
NCBLIT_2x2, // quadrants + 2x1
NCBLIT_3x2, // sextants + 1x1
NCBLIT_4x1, // four vertical levels
NCBLIT_BRAILLE, // 4 rows, 2 cols (braille)
NCBLIT_8x1, // eight vertical levels
2020-11-11 08:12:37 +00:00
NCBLIT_SIXEL, // not yet implemented
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
} ncblitter_e;
2020-06-05 12:05:02 +00:00
#define NCVISUAL_OPTION_NODEGRADE 0x0001
#define NCVISUAL_OPTION_BLEND 0x0002
2020-05-29 05:24:34 +00:00
struct ncvisual_options {
struct ncplane* n;
ncscale_e scaling;
2020-11-06 21:10:58 +00:00
int ** *y***, x;
2020-05-29 05:24:34 +00:00
int begy, begx; // origin of rendered section
int leny, lenx; // size of rendered section
2020-10-25 22:49:57 +00:00
ncblitter_e blitter; // glyph set to use
2020-05-29 18:53:53 +00:00
uint64_t flags; // bitmask over NCVISUAL_OPTION_*
2020-05-29 05:24:34 +00:00
};
2020-05-29 05:47:53 +00:00
typedef int
2020-01-04 07:37:55 +00:00
```
2020-11-06 21:10:58 +00:00
**bool notcurses_canopen_images(const struct notcurses* ** *nc***);**
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
2020-11-06 21:10:58 +00:00
**bool notcurses_canopen_videos(const struct notcurses* ** *nc***);**
2020-01-17 14:30:53 +00:00
2020-11-06 21:10:58 +00:00
**bool notcurses_cansixel(const struct notcurses* ** *nc***);**
2020-01-17 14:30:53 +00:00
2020-11-06 21:10:58 +00:00
**struct ncvisual* ncvisual_from_file(const char* ** *file***);**
2020-01-04 07:37:55 +00:00
2020-11-06 21:10:58 +00:00
**struct ncvisual* ncvisual_from_rgba(const void* ** *rgba***, int ** *rows***, int ** *rowstride***, int ** *cols***);**
2020-05-04 08:55:10 +00:00
2020-11-06 21:10:58 +00:00
**struct ncvisual* ncvisual_from_bgra(const void* ** *bgra***, int ** *rows***, int ** *rowstride***, int ** *cols***);**
2020-05-04 08:55:10 +00:00
2020-11-06 21:10:58 +00:00
**struct ncvisual* ncvisual_from_plane(struct ncplane* ** *n***, ncblitter_e ** *blit***, int ** *begy***, int ** *begx***, int ** *leny***, int ** *lenx***);**
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_geom(const struct notcurses* ** *nc***, const struct ncvisual* ** *n***, const struct ncvisual_options* ** *vopts***, int* ** *y***, int* ** *x***, int* ** *toy***, int* ** *tox***);**
2020-05-07 00:10:01 +00:00
2020-11-06 21:10:58 +00:00
**void ncvisual_destroy(struct ncvisual* ** *ncv***);**
2020-01-04 07:37:55 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_decode(struct ncvisual* ** *ncv***);**
2020-01-04 07:37:55 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_decode_loop(struct ncvisual* ** *ncv***);**
2020-10-19 22:42:09 +00:00
2020-11-06 21:10:58 +00:00
**struct ncplane* ncvisual_render(struct notcurses* ** *nc***, struct ncvisual* ** *ncv***, const struct ncvisual_options* ** *vopts***);**
2020-01-04 07:37:55 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_simple_streamer(struct ncplane* ** *n***, struct ncvisual* ** *ncv***, const struct timespec* ** *disptime***, void* ** *curry***);**
2020-01-04 07:37:55 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_stream(struct notcurses* ** *nc***, struct ncvisual* ** *ncv***, float ** *timescale***, streamcb ** *streamer***, const struct ncvisual_options* ** *vopts***, void* ** *curry***);**
2020-01-04 07:37:55 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_rotate(struct ncvisual* ** *n***, double ** *rads***);**
2020-05-04 04:51:42 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_resize(struct ncvisual* ** *n***, int ** *rows***, int ** *cols***);**
2020-06-06 09:11:45 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_polyfill_yx(struct ncvisual* ** *n***, int ** *y***, int ** *x***, uint32_t ** *rgba***);**
2020-06-06 09:11:45 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_at_yx(const struct ncvisual* ** *n***, int ** *y***, int ** *x***, uint32_t* ** *pixel***);**
2020-06-06 09:11:45 +00:00
2020-11-06 21:10:58 +00:00
**int ncvisual_set_yx(const struct ncvisual* ** *n***, int ** *y***, int ** *x***, uint32_t ** *pixel***);**
2020-06-07 01:38:05 +00:00
2020-11-06 21:10:58 +00:00
**char* ncvisual_subtitle(const struct ncvisual* ** *ncv***);**
2020-05-04 04:51:42 +00:00
2020-11-06 21:10:58 +00:00
**int notcurses_lex_scalemode(const char* ** *op***, ncscale_e* ** *scaling***);**
2020-07-20 01:53:01 +00:00
2020-11-06 21:10:58 +00:00
**const char* notcurses_str_scalemode(ncscale_e ** *scaling***);**
2020-07-20 01:53:01 +00:00
2020-11-06 21:10:58 +00:00
**int notcurses_lex_blitter(const char* ** *op***, ncblitter_e* ** *blitter***);**
2020-07-20 01:53:01 +00:00
2020-11-06 21:10:58 +00:00
**const char* notcurses_str_blitter(ncblitter_e ** *blitter***);**
2020-07-19 06:54:53 +00:00
2020-12-25 22:37:27 +00:00
**ncblitter_e ncvisual_media_defblitter(const struct notcurses ** *nc***, ncscale_e ** *scaling***);**
2020-09-06 16:56:16 +00:00
2020-01-02 02:23:11 +00:00
# DESCRIPTION
2020-05-29 05:47:53 +00:00
An **ncvisual** is a virtual pixel framebuffer. They can be created from
RGBA/BGRA data in memory (**ncvisual_from_rgba**/**ncvisual_from_bgra**),
or from the content of a suitable **ncplane** (**ncvisual_from_ncplane**).
If Notcurses was built against a multimedia engine (FFMpeg or OpenImageIO),
image and video files can be loaded into visuals using
**ncvisual_from_file**. **ncvisual_from_file** discovers the container
and codecs, but does not verify that the entire file is well-formed.
2020-05-29 12:39:11 +00:00
**ncvisual_decode** ought be invoked to recover subsequent frames, once
2020-10-20 23:35:16 +00:00
per frame. **ncvisual_decode_loop** will return to the first frame,
as if **ncvisual_decode** had never been called.
2020-05-29 05:47:53 +00:00
Once the visual is loaded, it can be transformed using **ncvisual_rotate**
and **ncvisual_resize** . These are persistent operations, unlike any scaling
that takes place at render time. If a subtitle is associated with the frame,
it can be acquired with **ncvisual_subtitle** .
**ncvisual_from_rgba** and **ncvisual_from_bgra** both require a number of
**rows**, a number of image columns **cols** , and a virtual row length of
**rowstride** / 4 columns. The input data must provide 32 bits per pixel, and
2020-11-02 05:40:54 +00:00
thus must be at least **rowstride** * * *rows** bytes, of which a
**cols** * * *rows** * 4-byte subset is used. It is not possible to * *mmap(2)** an image
2020-05-29 05:47:53 +00:00
file and use it directly--decompressed, decoded data is necessary. The
resulting plane will be ceil(**rows**/2) rows, and **cols** columns.
**ncvisual_from_plane** requires specification of a rectangle via **begy** ,
**begx**, **leny** , and **lenx** . The only valid characters within this
region are those used by the **NCBLIT_2x2** blitter, though this may change
in the future.
2020-05-07 00:10:01 +00:00
2020-05-06 09:49:22 +00:00
**ncvisual_rotate** executes a rotation of **rads** radians, in the clockwise
2020-06-03 16:22:46 +00:00
(positive) or counterclockwise (negative) direction.
2020-05-04 04:51:42 +00:00
2020-05-04 04:56:52 +00:00
**ncvisual_subtitle** will return a UTF-8-encoded subtitle corresponding to
the current frame if such a subtitle was decoded. Note that a subtitle might
be returned for multiple frames, or might not.
2020-06-05 12:05:02 +00:00
**ncvisual_render** blits the visual to an **ncplane** , based on the contents
of its **struct ncvisual_options** . If **n** is not **NULL** , it specifies the
plane on which to render, and **y** /**x** specify a location within that plane.
Otherwise, a new plane will be created, and placed at **y** /**x** relative to
the rendering area. **begy** /**begx** specify the upper left corner of a
subsection of the **ncvisual** to render, while **leny** /**lenx** specify the
geometry of same. **flags** is a bitfield over:
* **NCVISUAL_OPTION_NODEGRADE** If the specified blitter is not available, fail rather than degrading.
* **NCVISUAL_OPTION_BLEND**: Render with **CELL_ALPHA_BLEND** .
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
# BLITTERS
The different **ncblitter_e** values select from among available glyph sets:
* **NCBLIT_DEFAULT**: Let the **ncvisual** choose its own blitter.
2020-10-25 22:49:57 +00:00
* **NCBLIT_1x1**: Spaces only. Works in ASCII, unlike other blitters.
* **NCBLIT_2x1**: Adds the half blocks (▄▀) to **NCBLIT_1x1** .
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
* **NCBLIT_2x2**: Adds left and right half blocks (▌▐) and quadrants (▖▗▟▙) to **NCBLIT_2x1** .
2020-10-25 22:49:57 +00:00
* **NCBLIT_3x2**: Adds sextants to **NCBLIT_1x1** .
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
* **NCBLIT_4x1**: Adds ¼ and ¾ blocks (▂▆) to **NCBLIT_2x1** .
* **NCBLIT_BRAILLE**: 4 rows and 2 columns of braille (⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿).
* **NCBLIT_8x1**: Adds ⅛, ⅜, ⅝, and ⅞ blocks (▇▅▃▁) to **NCBLIT_4x1** .
2020-11-11 08:12:37 +00:00
* **NCBLIT_SIXEL**: Not yet implemented.
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
2020-10-19 03:15:50 +00:00
**NCBLIT_4x1** and **NCBLIT_8x1** are intended for use with plots, and are
not really applicable for general visuals.
2020-01-02 02:23:11 +00:00
# RETURN VALUES
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
**notcurses_canopen_images** and **notcurses_canopen_videos** returns true if
images and videos, respecitvely, can be decoded, or false if Notcurses was
built with insufficient multimedia support.
**ncvisual_from_file** returns an **ncvisual** object on success, or **NULL**
on failure. Success indicates that the specified **file** was opened, and
enough data was read to make a firm codec identification. It does not imply
2020-08-24 05:23:35 +00:00
that the entire file is properly-formed.
**ncvisual_decode** returns 0 on success, or 1 on end of file, or -1 on
failure. It is only necessary for multimedia-based visuals. It advances one
2020-10-20 23:35:16 +00:00
frame for each call. **ncvisual_decode_loop** has the same return values: when
called following decoding of the last frame, it will return 1, but a subsequent
**ncvisual_render** will return the first frame.
2020-04-24 07:17:34 +00:00
2020-05-07 00:10:01 +00:00
**ncvisual_from_plane** returns **NULL** if the **ncvisual** cannot be created
and bound. This is usually due to illegal content in the source **ncplane** .
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
**ncvisual_render** returns **NULL** on error, and otherwise the plane to
which the visual was rendered. If **opts->n** is provided, this will be
**opts->n**. Otherwise, a plane will be created, perfectly sized for the
visual and the specified blitter.
**ncvisual_geom** returns non-zero if the **blitter** is invalid.
2020-12-25 22:37:27 +00:00
**ncvisual_media_defblitter** returns the blitter selected by **NCBLIT_DEFAULT**
2020-11-01 12:19:02 +00:00
in the specified configuration. If UTF8 is not enabled, this will always be
2020-12-25 22:37:27 +00:00
**NCBLIT_1x1**. If ** *scale*** is **NCSCALE_NONE** or **NCSCALE_SCALE** , the
aspect-preserving **NCBLIT_2x1** will be returned. If sextants are available
(see **notcurses_cansextant** ), this will be **NCBLIT_3x2** , or otherwise
**NCBLIT_2x2**.
2020-11-01 12:19:02 +00:00
2020-04-24 07:17:34 +00:00
# NOTES
Multimedia decoding requires that Notcurses be built with either FFmpeg or
OpenImageIO support. What formats can be decoded is totally dependent on the
2020-05-04 04:56:52 +00:00
linked library. OpenImageIO does not support subtitles.
2020-03-24 22:43:10 +00:00
2020-05-06 09:49:22 +00:00
# BUGS
**ncvisual_rotate** currently supports only **M_PI** /2 and -**M_PI**/2
radians for **rads** , but this will change soon.
2020-10-19 03:15:50 +00:00
**NCBLIT_SIXEL** is not yet implemented, and is only infrequently supported
among terminals.
2020-11-11 08:12:37 +00:00
Bad font support can ruin **NCBLIT_2x2** , **NCBLIT_3x2** , **NCBLIT_4x1** ,
**NCBLIT_BRAILLE**, and **NCBLIT_8x1** .
2020-10-19 03:15:50 +00:00
2020-01-02 02:23:11 +00:00
# SEE ALSO
2020-05-04 04:56:52 +00:00
**notcurses(3)**,
2020-12-25 22:37:27 +00:00
**notcurses_capabilities(3)**,
2020-05-09 00:56:39 +00:00
**notcurses_plane(3)**,
2020-05-04 04:56:52 +00:00
**utf-8(7)**
