.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_fade" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_fade - fade ncplanes in and out
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[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, const struct timespec*, void* curry);
\f[R]
.fi
.PP
\f[B]bool notcurses_canfade(const struct notcurses*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_fadeout(struct ncplane* \f[R]\f[I]n\f[R]\f[B], const
struct timespec* \f[R]\f[I]ts\f[R]\f[B], fadecb
\f[R]\f[I]fader\f[R]\f[B], void* \f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_fadein(struct ncplane* \f[R]\f[I]n\f[R]\f[B], const
struct timespec* \f[R]\f[I]ts\f[R]\f[B], fadecb
\f[R]\f[I]fader\f[R]\f[B], void* \f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_pulse(struct ncplane* \f[R]\f[I]n\f[R]\f[B], const
struct timespec* \f[R]\f[I]ts\f[R]\f[B], fadecb
\f[R]\f[I]fader\f[R]\f[B], void* \f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncfadectx* ncfadectx_setup(struct ncplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncfadectx_iterations(const struct ncfadectx*
\f[R]\f[I]nctx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_fadeout_iteration(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], struct ncfadectx* \f[R]\f[I]nctx\f[R]\f[B], int
\f[R]\f[I]iter\f[R]\f[B], fadecb \f[R]\f[I]fader\f[R]\f[B], void*
\f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_fadein_iteration(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
struct ncfadectx* \f[R]\f[I]nctx\f[R]\f[B], int
\f[R]\f[I]iter\f[R]\f[B], fadecb \f[R]\f[I]fader\f[R]\f[B], void*
\f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]void ncfadectx_free(struct ncfadectx*
\f[R]\f[I]nctx\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
\f[B]ncplane_fadeout\f[R], \f[B]ncplane_fadein\f[R], and
\f[B]ncplane_pulse\f[R] 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 \f[B]ts\f[R] 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).
.PP
These are wrappers around the more flexible \f[B]ncfadectx\f[R] API.
Create an \f[B]ncfadectx\f[R] with \f[B]ncfadectx_setup\f[R].
The number of possible state changes (iterations) can be accessed with
\f[B]ncfadectx_iterations\f[R].
A state can be reached with \f[B]ncplane_fadeout_iteration\f[R] or
\f[B]ncplane_fadein_iteration\f[R].
Finally, destroy the \f[B]ncfadectx\f[R] with \f[B]ncfadectx_free\f[R].
.SH RETURN VALUES
.PP
\f[B]ncplane_fadeout_iteration\f[R] and
\f[B]ncplane_fadein_iteration\f[R] will propagate out any non-zero
return value from the callback \f[B]fader\f[R].
.SH BUGS
.PP
Palette reprogramming can affect other contents of the terminal in
complex ways.
This is not a problem when the RGB method is used.
.SH SEE ALSO
.PP
\f[B]clock_nanosleep(2)\f[R], \f[B]notcurses(3)\f[R],
\f[B]notcurses_plane(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.