pulsing text declarations

README.md

@@ -1047,6 +1047,11 @@ ncplane_double_box_sized(struct ncplane* n, uint32_t attr, uint64_t channels,
 My 14 year-old self would never forgive me if we didn't have sweet palette fades.
 
 ```c
+// Called for each delta performed in a fade on ncp. If anything but 0 is returned,
+// the fading operation ceases immediately, and that value is propagated out. If provided
+// and not NULL, the faders will not themselves call notcurses_render().
+typedef int (*fadecb)(struct notcurses* nc, struct ncplane* ncp);
+
 // Fade the ncplane out over the provided time, calling the specified function
 // when done. Requires a terminal which supports direct color, or at least
 // palette modification (if the terminal uses a palette, our ability to fade
@@ -1058,6 +1063,13 @@ int ncplane_fadeout(struct ncplane* n, const struct timespec* ts);
 // target cells without rendering, then call this function. When it's done, the
 // ncplane will have reached the target levels, starting from zeroes.
 int ncplane_fadein(struct ncplane* n, const struct timespec* ts);
+
+// Pulse the plane in and out until the callback returns non-zero, relying on
+// the callback 'fader' to initiate rendering. 'ts' defines the half-period
+// (i.e. the transition from black to full brightness, or back again). Proper
+// use involves preparing (but not rendering) an ncplane, then calling
+// ncplane_pulse(), which will fade in from black to the specified colors.
+int ncplane_pulse(struct ncplane* n, const struct timespec* ts, fadecb fader);
 ```
 
 #### Plane channels API

doc/man/man3/notcurses.3.md

@@ -111,8 +111,8 @@ previous action.
 
 # SEE ALSO
 
-**notcurses-demo(1)**, **notcurses_cell(3)**, **notcurses_init(3)**,
-**notcurses_channels(3)**, **notcurses_input(3)**, **notcurses_ncplane(3)**,
-**ncplane_new(3)**, **notcurses_output(3)**, **notcurses_render(3)**,
-**notcurses_stdplane(3)**, **notcurses_stop(3)**, **ncurses(3NCURSES)**,
-**terminfo(5)**, **ascii(7)**, **unicode(7)**
+**notcurses-demo(1)**, **notcurses_cell(3)**, **notcurses_channels(3)**,
+**notcurses_fade(3)**, **notcurses_init(3)**, **notcurses_input(3)**,
+**notcurses_lines(3)**, **notcurses_ncplane(3)**, **notcurses_output(3)**,
+**notcurses_render(3)**, **notcurses_stdplane(3)**, **notcurses_stop(3)**,
+**ncurses(3NCURSES)**, **terminfo(5)**, **ascii(7)**, **unicode(7)**

doc/man/man3/notcurses_fade.3.md

@@ -0,0 +1,33 @@
+% notcurses_fade(3)
+% nick black <nickblack@linux.com>
+% v1.0.2
+
+# NAME
+
+notcurses_fade - fade ncplanes in and out
+
+# SYNOPSIS
+
+**#include <notcurses.h>**
+
+```c
+typedef int (*fadecb)(struct notcurses* nc, struct ncplane* ncp);
+```
+
+**int ncplane_fadeout(struct ncplane* n, const struct timespec* ts);**
+
+**int ncplane_fadein(struct ncplane* n, const struct timespec* ts);**
+
+**int notcurses_pulsing_yx(struct ncplane* n, int y, int x, const char* s, uint32_t attr, uint64_t channels, fadecb fader);**
+
+**int ncplane_pulse(struct ncplane* n, const struct timespec* ts, fadecb fader);**
+
+# DESCRIPTION
+
+# RETURN VALUES
+
+# BUGS
+
+# SEE ALSO
+
+**notcurses(3)**, **notcurses_ncplane(3)**

include/notcurses.h

@@ -1363,6 +1363,13 @@ API int ncplane_fadeout(struct ncplane* n, const struct timespec* ts, fadecb fad
 // ncplane will have reached the target levels, starting from zeroes.
 API int ncplane_fadein(struct ncplane* n, const struct timespec* ts, fadecb fader);
 
+// Pulse the plane in and out until the callback returns non-zero, relying on
+// the callback 'fader' to initiate rendering. 'ts' defines the half-period
+// (i.e. the transition from black to full brightness, or back again). Proper
+// use involves preparing (but not rendering) an ncplane, then calling
+// ncplane_pulse(), which will fade in from black to the specified colors.
+API int ncplane_pulse(struct ncplane* n, const struct timespec* ts, fadecb fader);
+
 // Working with cells
 
 #define CELL_TRIVIAL_INITIALIZER { .gcluster = '\0', .attrword = 0, .channels = 0, }