{"id":13598570,"url":"https://github.com/junkdog/tachyonfx","last_synced_at":"2025-04-13T04:55:53.464Z","repository":{"id":243442654,"uuid":"812197206","full_name":"junkdog/tachyonfx","owner":"junkdog","description":"shader-like effects library for ratatui applications","archived":false,"fork":false,"pushed_at":"2025-04-07T01:43:15.000Z","size":41436,"stargazers_count":873,"open_issues_count":1,"forks_count":9,"subscribers_count":4,"default_branch":"development","last_synced_at":"2025-04-13T04:55:44.294Z","etag":null,"topics":["ratatui","tui","tweening"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/junkdog.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-08T08:00:49.000Z","updated_at":"2025-04-03T18:30:51.000Z","dependencies_parsed_at":"2024-08-26T07:23:39.121Z","dependency_job_id":"c557849e-32be-47da-b80f-2b8dc94a8d23","html_url":"https://github.com/junkdog/tachyonfx","commit_stats":{"total_commits":148,"total_committers":4,"mean_commits":37.0,"dds":"0.060810810810810856","last_synced_commit":"76dba6e713604e1478d6235046060987937f0fb8"},"previous_names":["junkdog/tachyonfx"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Ftachyonfx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Ftachyonfx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Ftachyonfx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Ftachyonfx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junkdog","download_url":"https://codeload.github.com/junkdog/tachyonfx/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665763,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ratatui","tui","tweening"],"created_at":"2024-08-01T17:00:53.781Z","updated_at":"2025-04-13T04:55:53.446Z","avatar_url":"https://github.com/junkdog.png","language":"Rust","funding_links":[],"categories":["Rust","📦 Libraries"],"sub_categories":["🔧 Utilities"],"readme":"## tachyonfx\n\n[![Crate Badge]][Crate] [![API Badge]][API] [![Deps.rs\nBadge]][Deps.rs]\n\ntachyonfx (_ˈtakɪɒn ˌɛfˈɛks_) is a [ratatui][ratatui] library for creating shader-like effects in terminal UIs. It\nprovides a collection of stateful effects that can enhance the visual appeal of terminal applications through color\ntransformations, animations, and complex effect combinations.\n\n![demo](images/demo-0.6.0.gif)\n\n[ratatui]: https://ratatui.rs/\n\n## Installation\nAdd tachyonfx to your `Cargo.toml`:\n\n```toml\ntachyonfx = \"0.13.0\"\n```\n\n## Core Concepts\n\n### Effects and State\nEffects in tachyonfx are stateful objects that evolve over time. When you create an effect, it typically maintains:\n\n- An internal timer or flag tracking progress\n- Effect-specific state (like transition progress)\n- Configuration (like styling, directions, or interpolation methods)\n\n```rust\nuse tachyonfx::fx::{fade_to_fg, Color};\n\n// Create the effect once\nlet mut fade_effect = fx::fade_to_fg(Color::Red, Duration::from_millis(1000));\n\n// In your render loop:\nloop {\n    widget.render(area, buf);\n\n    // Process the same effect each frame, updating its state\n    fade_effect.process(frame_duration, buf, area);\n    // Or use the helper trait:\n    // frame.render_effect(\u0026mut fade_effect, area, frame_duration);\n}\n```\n\n### Effects and Widgets\n\nEffects in tachyonfx operate on terminal cells after widgets have been rendered to the screen. When an effect is\napplied, it modifies properties of the already-rendered cells - like their colors, characters, or visibility. This means\nthe typical flow is:\n\n1. Render your widget to the screen\n2. Apply effects to transform the rendered content\n\n### Effect DSL (Domain-Specific Language)\n\ntachyonfx includes a rust-looking DSL for defining effects as text expressions that can be compiled at runtime.\nThis enables:\n\n- Fast iteration and prototyping of effects\n- Creating effects from configuration files or user input\n- Storing and serializing effect definitions\n\n```rust\nuse tachyonfx::dsl::EffectDsl;\n\n// Create a DSL compiler and bind variables\nlet effect = EffectDsl::new().compiler()\n    .bind(\"color\", Color::Red)\n    .compile(\"fx::fade_to_fg(color, (1000, QuadOut))\")\n    .expect(\"valid effect from dsl\");\n\n// Complex compositions\nlet expression = r#\"\n    fx::sequence(\u0026[\n        fx::fade_from(Color::Black, Color::Red, (500, LinearOut)),\n        fx::dissolve((300, BounceOut))\n    ])\n\"#;\n\nlet effect = EffectDsl::new()\n    .compiler()\n    .compile(expression)\n    .expect(\"valid effect from dsl\");\n```\n\nThe DSL supports let bindings, [method chaining][docs-supported-types], and serialization of effects\nwith `Effect::to_dsl`:\n\n\n [docs-supported-types]: https://docs.rs/tachyonfx/latest/tachyonfx/dsl/index.html#supported-types-and-methods\n\n### Types of Effects\n\nThe library includes a variety of effects, loosely categorized as follows:\n\n#### Color Effects\n- **fade_from:**      Fades from the specified background and foreground colors\n- **fade_from_fg:**   Fades the foreground color from a specified color.\n- **fade_to:**        Fades to the specified background and foreground colors.\n- **fade_to_fg:**     Fades the foreground color to a specified color.\n- **hsl_shift:**      Changes the hue, saturation, and lightness of the foreground and background colors.\n- **hsl_shift_fg:**   Shifts the foreground color by the specified hue, saturation, and lightness over the specified duration.\n- **term256_colors:** Downsamples to 256 color mode.\n\n#### Text/Character Effects\n- **coalesce:**   The reverse of dissolve, coalesces text over the specified duration.\n- **dissolve:**   Dissolves the current text over the specified duration.\n- **explode:**    Explodes the content dispersing it outward from the center.\n- **slide_in:**   Applies a directional sliding in effect to terminal cells.\n- **slide_out:**  Applies a directional sliding out effect to terminal cells.\n- **sweep_in:**   Sweeps in from the specified color.\n- **sweep_out:**  Sweeps out to the specified color.\n\n#### Timing and Control Effects\n- **consume_tick:**         Consumes a single tick.\n- **never_complete:**       Makes an effect run indefinitely.\n- **ping_pong:**            Plays the effect forwards and then backwards.\n- **prolong_start**:        Extends the start of an effect by a specified duration.\n- **prolong_end**:          Extends the end of an effect by a specified duration.\n- **repeat:**               Repeats an effect indefinitely or for a specified number of times or duration.\n- **repeating:**            Repeats the effect indefinitely.\n- **sleep:**                Pauses for a specified duration.\n- **timed_never_complete:** Creates an effect that runs indefinitely but has an enforced duration.\n- **with_duration:**        Wraps an effect and enforces a maximum duration on it.\n\n#### Geometry Effects\n- **translate:**     Moves the effect area by a specified amount.\n- **translate_buf:** Copies the contents from an aux buffer, moving it by a specified amount.\n- **resize_area:**   Resizes the area of the wrapped effect.\n\n#### Combination Effects\n- **parallel:** Runs effects in parallel, all at the same time. Reports completion once all effects have completed.\n- **sequence:** Runs effects in sequence, one after the other. Reports completion once the last effect has completed.\n\n#### Other Effects\n- **effect_fn:**        Creates custom effects from user-defined functions, operating over `CellIterator`.\n- **effect_fn_buf:**    Creates custom effects from functions, operating over `Buffer`.\n- **offscreen_buffer:** Wraps an existing effect and redirects its rendering to a separate buffer.\n- **unique:**           A unique effect that will cancel any existing effect with the same key.\n\nAdditional effects can be created by implementing the `Shader` trait.\n\n\n### EffectTimer and Interpolations\n\nMost effects are driven by an `EffectTimer` that controls their duration and interpolation. It\nallows for precise timing and synchronization of visual effects within your application.\n\n```rust\nfx::dissolve(EffectTimer::from_ms(500, BounceOut))\nfx::dissolve((500, BounceOut)) // shorthand for the above\nfx::dissolve(500)              // linear interpolation\n```\n\n### Cell Selection and Area\n\nEffects can be applied to specific cells in the terminal UI, allowing for targeted visual\nmodifications and animations.\n\n```rust\n// only apply to cells with `Light2` foreground color\nfx::sweep_in(Direction::UpToDown, 15, 0, Dark0, timer)\n    .with_filter(CellFilter::FgColor(Light2.into()))\n```\n\n`CellFilter`s can be combined to form complex selection criteria.\n\n```rust\n// apply effect to cells on the outer border of the area\nlet margin = Margin::new(1, 1);\nlet border_text = CellFilter::AllOf(\u0026[\n    CellFilter::Outer(margin),\n    CellFilter::Text\n]);\n\nprolong_start(duration, fx::fade_from(Dark0, Dark0, (320, QuadOut)),\n    .with_filter(border_text)\n```\n\n### Features\n- `dsl`: Enables the Effect DSL, allowing for runtime compilation of effect expressions. Enabled by default.\n- `sendable`: Enables the `Send` trait for effects, shaders, and associated parameters. This allows effects to be\n  safely transferred across thread boundaries. Note that enabling this feature requires all `Shader` implementations\n  to be `Send`, which may impose additional constraints on custom shader implementations.\n- `std-duration`:  Uses `std::time::Duration` instead of a custom 32-bit duration type.\n- `web-time`: Enables WebAssembly compatibility by providing alternative time handling implementations. This allows\n  tachyonfx to be used in browser-based WebAssembly applications where `std::time` is not available.\n\n\n## Examples\n\n### Example: [minimal](examples/minimal.rs)\n```\ncargo run --release --example=minimal \n```\n\n### Example: [tweens](examples/tweens.rs)\n![tweens](images/example-tweens.png)\n\n```\ncargo run --release --example=tweens \n```\n\n### Example: [basic-effects](examples/basic-effects.rs)\n![basic effeects](images/example-basic-effects.png)\n```\ncargo run --release --example=basic-effects \n```\n\n\n### Example: [open-window](examples/open-window.rs)\n\n```\ncargo run --release --example=open-window  \n```\n\n### Example: [fx-chart](examples/fx-chart.rs)\n![fx-chart](images/effect-timeline.gif)\n\nA demo of the `EffectTimelineWidget` showcasing the composition of effects. The widget is a \"plain\" widget\nwithout any effects as part of its rendering. The effects are instead applied after rendering the widget.\n\n```\ncargo run --release --example=fx-chart\n```\n\n### Example: [dsl-playground](examples/dsl-playground.rs)\n![dsl-playground](images/example-dsl-playground.gif)\n```\ncargo run --release --example=dsl-playground\n```\n\nA playground for experimenting with the DSL to create and combine effects interactively.\n\n\n[API Badge]: https://docs.rs/tachyonfx/badge.svg\n[API]: https://docs.rs/tachyonfx\n[Crate Badge]: https://img.shields.io/crates/v/tachyonfx.svg\n[Crate]: https://crates.io/crates/tachyonfx\n[Deps.rs Badge]: https://deps.rs/repo/github/junkdog/tachyonfx/status.svg\n[Deps.rs]: https://deps.rs/repo/github/junkdog/tachyonfx\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunkdog%2Ftachyonfx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunkdog%2Ftachyonfx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunkdog%2Ftachyonfx/lists"}