ncfadectx_setup(): remove timespec param #659

USAGE.md

@@ -1227,7 +1227,7 @@ The more flexible fade API allows for fine control of the process.
 
 ```c
 // paired with a loop over ncplane_fade{in/out}_iteration() + ncfadectx_free().
-struct ncfadectx* ncfadectx_setup(struct ncplane* n, const struct timespec* ts);
+struct ncfadectx* ncfadectx_setup(struct ncplane* n);
 
 // Return the number of iterations through which 'nctx' will fade.
 int ncfadectx_iterations(const struct ncfadectx* nctx);

doc/man/man3/notcurses_fade.3.md

@@ -11,11 +11,13 @@ notcurses_fade - fade ncplanes in and out
 **#include <notcurses/notcurses.h>**
 
 ```c
+struct ncfadectx;
+
 // 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);
+typedef int (*fadecb)(struct notcurses* nc, struct ncplane* ncp, const struct timespec*, void* curry);
 ```
 
 **bool notcurses_canfade(const struct notcurses* nc);**
@@ -26,13 +28,44 @@ typedef int (*fadecb)(struct notcurses* nc, struct ncplane* ncp);
 
 **int ncplane_pulse(struct ncplane* n, const struct timespec* ts, fadecb fader, void* curry);**
 
+**struct ncfadectx* ncfadectx_setup(struct ncplane* n);**
+
+**int ncfadectx_iterations(const struct ncfadectx* nctx);**
+
+**int ncplane_fadeout_iteration(struct ncplane* n, struct ncfadectx* nctx, int iter, fadecb fader, void* curry);**
+
+**int ncplane_fadein_iteration(struct ncplane* n, struct ncfadectx* nctx, int iter, fadecb fader, void* curry);**
+
+**void ncfadectx_free(struct ncfadectx* nctx);**
+
 # DESCRIPTION
 
+**ncplane_fadeout**, **ncplane_fadein**, and **ncplane_pulse** are simple
+APIs for fading planes in and out. Fades require either RGB support or
+palette reprogramming support from the terminal (the RGB method is
+preferred, and will be used whenever possible). The **ts** parameter
+specifies the total amount of time for the fade operation. The operation
+itself is time-adaptive (i.e. if it finds itself falling behind, it will
+skip iterations; if it is proceeding too quickly, it will sleep).
+
+These are wrappers around the more flexible **ncfadectx** API. Create an
+**ncfadectx** with **ncfadectx_setup**. The number of possible state changes
+(iterations) can be accessed with **ncfadectx_iterations**. A state can be
+reached with **ncplane_fadeout_iteration** or **ncplane_fadein_iteration**.
+Finally, destroy the **ncfadectx** with **ncfadectx_free**.
+
 # RETURN VALUES
 
+**ncplane_fadeout_iteration** and **ncplane_fadein_iteration** will propagate
+out any non-zero return value from the callback **fader**.
+
 # BUGS
 
+Palette reprogramming can affect other contents of the terminal in complex
+ways. This is not a problem when the RGB method is used.
+
 # SEE ALSO
 
+**clock_nanosleep(2)**,
 **notcurses(3)**,
 **notcurses_plane(3)**

include/notcurses/notcurses.h

@@ -1987,7 +1987,7 @@ API int ncplane_fadein(struct ncplane* n, const struct timespec* ts,
 
 // Rather than the simple ncplane_fade{in/out}(), ncfadectx_setup() can be
 // paired with a loop over ncplane_fade{in/out}_iteration() + ncfadectx_free().
-API struct ncfadectx* ncfadectx_setup(struct ncplane* n, const struct timespec* ts);
+API struct ncfadectx* ncfadectx_setup(struct ncplane* n);
 
 // Return the number of iterations through which 'nctx' will fade.
 API int ncfadectx_iterations(const struct ncfadectx* nctx);

src/lib/fade.c

@@ -228,7 +228,8 @@ int ncplane_fadeout_iteration(ncplane* n, ncfadectx* nctx, int iter,
   return ret;
 }
 
-ncfadectx* ncfadectx_setup(ncplane* n, const struct timespec* ts){
+static ncfadectx* 
+ncfadectx_setup_internal(ncplane* n, const struct timespec* ts){
   if(!n->nc->tcache.RGBflag && !n->nc->tcache.CCCflag){ // terminal can't fade
     return NULL;
   }
@@ -242,6 +243,10 @@ ncfadectx* ncfadectx_setup(ncplane* n, const struct timespec* ts){
   return NULL;
 }
 
+ncfadectx* ncfadectx_setup(ncplane* n){
+  return ncfadectx_setup_internal(n, NULL);
+}
+
 void ncfadectx_free(ncfadectx* nctx){
   if(nctx){
     free(nctx->channels);
@@ -250,7 +255,7 @@ void ncfadectx_free(ncfadectx* nctx){
 }
 
 int ncplane_fadeout(ncplane* n, const struct timespec* ts, fadecb fader, void* curry){
-  ncfadectx* pp = ncfadectx_setup(n, ts);
+  ncfadectx* pp = ncfadectx_setup_internal(n, ts);
   if(!pp){
     return -1;
   }
@@ -274,7 +279,7 @@ int ncplane_fadeout(ncplane* n, const struct timespec* ts, fadecb fader, void* c
 }
 
 int ncplane_fadein(ncplane* n, const struct timespec* ts, fadecb fader, void* curry){
-  ncfadectx* nctx = ncfadectx_setup(n, ts);
+  ncfadectx* nctx = ncfadectx_setup_internal(n, ts);
   if(nctx == NULL){
     struct timespec now;
     clock_gettime(CLOCK_MONOTONIC, &now);

src/lib/oiio.cpp

@@ -125,7 +125,7 @@ nc_err_e ncvisual_blit(struct ncvisual* ncv, int rows, int cols,
     stride = ncv->rowstride;
   }
   if(rgba_blit_dispatch(n, bset, placey, placex, stride, data, begy, begx,
-                        leny, lenx, blendcolors)) <= 0){
+                        leny, lenx, blendcolors) <= 0){
     return NCERR_DECODE;
   }
   return NCERR_SUCCESS;

tests/fade.cpp

@@ -104,7 +104,7 @@ TEST_CASE("Fade") {
 
   // drive fadeout with the more flexible api
   SUBCASE("FadeOutFlexible") {
-    auto nctx = ncfadectx_setup(n_, nullptr);
+    auto nctx = ncfadectx_setup(n_);
     REQUIRE(nctx);
     auto maxiter = ncfadectx_iterations(nctx);
     CHECK(0 < maxiter);
@@ -115,7 +115,7 @@ TEST_CASE("Fade") {
   }
 
   SUBCASE("FadeOutFlexibleAbort") {
-    auto nctx = ncfadectx_setup(n_, nullptr);
+    auto nctx = ncfadectx_setup(n_);
     REQUIRE(nctx);
     auto maxiter = ncfadectx_iterations(nctx);
     CHECK(0 < maxiter);
@@ -127,7 +127,7 @@ TEST_CASE("Fade") {
 
   // drive fadein with the more flexible api
   SUBCASE("FadeInFlexible") {
-    auto nctx = ncfadectx_setup(n_, nullptr);
+    auto nctx = ncfadectx_setup(n_);
     REQUIRE(nctx);
     auto maxiter = ncfadectx_iterations(nctx);
     CHECK(0 < maxiter);
@@ -138,7 +138,7 @@ TEST_CASE("Fade") {
   }
 
   SUBCASE("FadeInFlexibleAbort") {
-    auto nctx = ncfadectx_setup(n_, nullptr);
+    auto nctx = ncfadectx_setup(n_);
     REQUIRE(nctx);
     auto maxiter = ncfadectx_iterations(nctx);
     CHECK(0 < maxiter);