1notcurses_fade(3)                                            notcurses_fade(3)
2
3
4

NAME

6       notcurses_fade - fade ncplanes in and out
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              struct ncfadectx;
12
13              // Called for each delta performed in a fade on ncp. If anything but 0 is
14              // returned, the fading operation ceases immediately, and that value is
15              // propagated out. If provided and not NULL, the faders will not themselves
16              // call notcurses_render().
17              typedef int (*fadecb)(struct notcurses* nc, struct ncplane* ncp,
18                                    const struct timespec*, void* curry);
19
20       bool notcurses_canfade(const struct notcurses* nc);
21
22       int  ncplane_fadeout(struct  ncplane*  n,  const  struct  timespec* ts,
23       fadecb fader, void* curry);
24
25       int ncplane_fadein(struct ncplane* n, const struct timespec* ts, fadecb
26       fader, void* curry);
27
28       int  ncplane_pulse(struct ncplane* n, const struct timespec* ts, fadecb
29       fader, void* curry);
30
31       struct ncfadectx* ncfadectx_setup(struct ncplane* n);
32
33       int ncfadectx_iterations(const struct ncfadectx* nctx);
34
35       int ncplane_fadeout_iteration(struct ncplane* n, struct ncfadectx*  nc‐
36       tx, int iter, fadecb fader, void* curry);
37
38       int ncplane_fadein_iteration(struct ncplane* n, struct ncfadectx* nctx,
39       int iter, fadecb fader, void* curry);
40
41       void ncfadectx_free(struct ncfadectx* nctx);
42

DESCRIPTION

44       ncplane_fadeout, ncplane_fadein, and ncplane_pulse are simple APIs  for
45       fading  planes in and out.  Fades require either RGB support or palette
46       reprogramming support from the terminal (the RGB method  is  preferred,
47       and  will  be  used whenever possible).  The ts parameter specifies the
48       total amount of time for the fade operation.  The operation  itself  is
49       time-adaptive  (i.e.   if  it finds itself falling behind, it will skip
50       iterations; if it is proceeding too quickly, it will sleep).
51
52       These are wrappers around the more flexible ncfadectx API.   Create  an
53       ncfadectx  with  ncfadectx_setup.  The number of possible state changes
54       (iterations) can be accessed with ncfadectx_iterations.  A state can be
55       reached  with  ncplane_fadeout_iteration  or  ncplane_fadein_iteration.
56       Finally, destroy the ncfadectx with ncfadectx_free.
57

RETURN VALUES

59       ncplane_fadeout_iteration and ncplane_fadein_iteration  will  propagate
60       out any non-zero return value from the callback fader.
61

BUGS

63       Palette reprogramming can affect other contents of the terminal in com‐
64       plex ways.  This is not a problem when the RGB method is used.
65

SEE ALSO

67       clock_nanosleep(2), notcurses(3), notcurses_plane(3)
68

AUTHORS

70       nick black <nickblack@linux.com>.
71
72
73
74                                    v2.3.1                   notcurses_fade(3)