From 23b5078ed12f1779e80f27c2bb043b839b9a2cd0 Mon Sep 17 00:00:00 2001
From: nick black <dankamongmen@gmail.com>
Date: Mon, 13 Jan 2020 16:29:53 -0500
Subject: [PATCH] pulsing text declarations

---
 README.md                        | 12 ++++++++++++
 doc/man/man3/notcurses.3.md      | 10 +++++-----
 doc/man/man3/notcurses_fade.3.md | 33 ++++++++++++++++++++++++++++++++
 include/notcurses.h              |  7 +++++++
 4 files changed, 57 insertions(+), 5 deletions(-)
 create mode 100644 doc/man/man3/notcurses_fade.3.md

diff --git a/README.md b/README.md
index b4cf96e50..d3cbdb455 100644
--- a/README.md
+++ b/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
diff --git a/doc/man/man3/notcurses.3.md b/doc/man/man3/notcurses.3.md
index 7eb34ad7b..da3a6c20d 100644
--- a/doc/man/man3/notcurses.3.md
+++ b/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)**
diff --git a/doc/man/man3/notcurses_fade.3.md b/doc/man/man3/notcurses_fade.3.md
new file mode 100644
index 000000000..cdba9c59a
--- /dev/null
+++ b/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)**
diff --git a/include/notcurses.h b/include/notcurses.h
index 01d29a4a1..d8bbaf2e4 100644
--- a/include/notcurses.h
+++ b/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, }