diff --git a/NEWS.md b/NEWS.md index 55c77d40e..c296008aa 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,9 @@ This document attempts to list user-visible changes and any major internal rearrangements of Notcurses. +* 2.0.2 (not yet released) + * Add `ncvisual_rewind()`. + * 2.0.1 (2020-10-19) * Add `ncmenu_item_set_status()` for disabling or enabling menu items. * Disabled menu items cannot be selected. diff --git a/USAGE.md b/USAGE.md index a5d14ca60..1223af098 100644 --- a/USAGE.md +++ b/USAGE.md @@ -2662,6 +2662,10 @@ And finally, the `ncvisual` can be blitted to one or more `ncplane`s: struct ncplane* ncvisual_render(struct notcurses* nc, struct ncvisual* ncv, const struct ncvisual_options* vopts); +// rewind to the first frame of the ncvisual. a subsequent `ncvisual_render()` +// will render the first frame, as if the ncvisual had been closed and reopened. +int ncvisual_rewind(struct ncvisual* nc); + // each has the empty cell in addition to the product of its dimensions. i.e. // NCBLIT_1x1 has two states: empty and full block. NCBLIT_1x1x4 has five // states: empty, the three shaded blocks, and the full block. diff --git a/data/normal.png b/data/normal.png index 8ccfae0c6..4cae17e8d 100644 Binary files a/data/normal.png and b/data/normal.png differ diff --git a/doc/man/man3/notcurses_visual.3.md b/doc/man/man3/notcurses_visual.3.md index 02469df9b..ea7bb1a3a 100644 --- a/doc/man/man3/notcurses_visual.3.md +++ b/doc/man/man3/notcurses_visual.3.md @@ -64,6 +64,8 @@ typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*); **int ncvisual_decode(struct ncvisual* nc);** +**int ncvisual_rewind(struct ncvisual* nc);** + **struct ncplane* ncvisual_render(struct notcurses* nc, struct ncvisual* ncv, const struct ncvisual_options* vopts);** **int ncvisual_simple_streamer(struct ncplane* n, struct ncvisual* ncv, const struct timespec* disptime, void* curry);** @@ -102,7 +104,8 @@ 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. **ncvisual_decode** ought be invoked to recover subsequent frames, once -per frame. +per frame. **ncvisual_rewind** will return to the beginning of a multiframe +visual, as if **ncvisual_decode** had never been called on it. Once the visual is loaded, it can be transformed using **ncvisual_rotate** and **ncvisual_resize**. These are persistent operations, unlike any scaling diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index f9e72b271..30f1a58e1 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -2316,6 +2316,10 @@ API void ncvisual_destroy(struct ncvisual* ncv); // success, and -1 on failure. API int ncvisual_decode(struct ncvisual* nc); +// rewind to the first frame of the ncvisual. a subsequent `ncvisual_render()` +// will render the first frame, as if the ncvisual had been closed and reopened. +API int ncvisual_rewind(struct ncvisual* nc); + // Rotate the visual 'rads' radians. Only M_PI/2 and -M_PI/2 are // supported at the moment, but this will change FIXME. API int ncvisual_rotate(struct ncvisual* n, double rads);