ncvisual_rewind

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.

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.

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

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);