tachyonfx 0.5.0

A ratatui library for creating shader-like effects in TUIs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

## tachyonfx

[![Crate Badge]][Crate] [![API Badge]][API] [![Deps.rs
Badge]][Deps.rs]

tachyonfx is a [ratatui][ratatui] library for creating shader-like effects in terminal UIs.
This library provides a collection of effects that can be used to enhance the
visual appeal of terminal applications, offering capabilities such as color
transformations, animations, and complex effect combinations.

![demo](images/demo.gif)

 [ratatui]: https://ratatui.rs/

## Installation
Add tachyonfx to your `Cargo.toml`:

```toml
tachyonfx = "0.5.0"
```

## Overview


### Effects

The library includes a variety of effects, loosely categorized as follows:

#### Color Effects
- **fade_from:**      Fades from the specified background and foreground colors
- **fade_from_fg:**   Fades the foreground color from a specified color.
- **fade_to:**        Fades to the specified background and foreground colors.
- **fade_to_fg:**     Fades the foreground color to a specified color.
- **hsl_shift:**      Changes the hue, saturation, and lightness of the foreground and background colors.
- **hsl_shift_fg:**   Shifts the foreground color by the specified hue, saturation, and lightness over the specified duration.
- **term256_colors:** Downsamples to 256 color mode.

#### Text/Character Effects
- **coalesce:**   The reverse of dissolve, coalesces text over the specified duration.
- **dissolve:**   Dissolves the current text over the specified duration.
- **slide_in:**   Applies a directional sliding in effect to terminal cells.
- **slide_out:**  Applies a directional sliding out effect to terminal cells.
- **sweep_in:**   Sweeps in from the specified color.
- **sweep_out:**  Sweeps out to the specified color.

#### Timing and Control Effects
- **consume_tick:**         Consumes a single tick.
- **never_complete:**       Makes an effect run indefinitely.
- **ping_pong:**            Plays the effect forwards and then backwards.
- **prolong_start**:        Extends the start of an effect by a specified duration.
- **prolong_end**:          Extends the end of an effect by a specified duration.
- **repeat:**               Repeats an effect indefinitely or for a specified number of times or duration.
- **repeating:**            Repeats the effect indefinitely.
- **sleep:**                Pauses for a specified duration.
- **timed_never_complete:** Creates an effect that runs indefinitely but has an enforced duration.
- **with_duration:**        Wraps an effect and enforces a duration on it.

#### Geometry Effects
- **translate:**     Moves the effect area by a specified amount.
- **translate_buf:** Copies the contents from an aux buffer, moving it by a specified amount.
- **resize_area:**   Resizes the area of the wrapped effect.

#### Combination Effects
- **parallel:** Runs effects in parallel, all at the same time. Reports completion once all effects have completed.
- **sequence:** Runs effects in sequence, one after the other. Reports completion once the last effect has completed.

#### Other Effects
- **effect_fn:**        Creates custom effects from user-defined functions, operating over `CellIterator`.
- **effect_fn_buf:**    Creates custom effects from functions, operating over `Buffer`.
- **offscreen_buffer:** Wraps an existing effect and redirects its rendering to a separate buffer.


### EffectTimer and Interpolations

The EffectTimer is used to control the duration and interpolation of effects. It
allows for precise timing and synchronization of visual effects within your application.

### Cell Selection and Area

Effects can be applied to specific cells in the terminal UI, allowing for targeted visual
modifications and animations.

```rust
// only apply to cells with `Light2` foreground color
fx::sweep_in(Direction::UpToDown, 15, Dark0, timer)
    .with_cell_selection(CellFilter::FgColor(Light2.into()))
```

`CellFilter`s can be combined to form complex selection criteria.

```rust
// apply effect to cells on the outer border of the area
let margin = Margin::new(1, 1);
let border_text = CellFilter::AllOf(vec![
    CellFilter::Outer(margin),
    CellFilter::Text
]);

sequence(vec![
    with_duration(duration, never_complete(fx::fade_to(Dark0, Dark0, 0))),
    fx::fade_from(Dark0, Dark0, (320, QuadOut)),
]).with_cell_selection(border_text)
```

## Examples

### Example: `tweens`
![tweens](images/example-tweens.png)

```
cargo run --release --example=tweens 
```

### Example: `basic-effects`
![basic effeects](images/example-basic-effects.png)
```
cargo run --release --example=basic-effects 
```


### Example: `open-window`

```
cargo run --release --example=open-window  
```

### Example: fx-chart
![fx-chart](images/effect-timeline-widget.png)

A demo of the `EffectTimelineWidget` showcasing the composition of effects. The widget is a "plain" widget
without any effects as part of its rendering. The effects are instead applied after rendering the widget.

```
cargo run --release --example=fx-chart  
```


  [API Badge]: https://docs.rs/tachyonfx/badge.svg
  [API]: https://docs.rs/tachyonfx
  [Crate Badge]: https://img.shields.io/crates/v/tachyonfx.svg
  [Crate]: https://crates.io/crates/tachyonfx
  [Deps.rs Badge]: https://deps.rs/repo/github/junkdog/tachyonfx/status.svg
  [Deps.rs]: https://deps.rs/repo/github/junkdog/tachyonfx