Skip to main content

Crate phosphor

Crate phosphor 

Source
Expand description

§Phosphor

A high-performance GPU-accelerated waveform visualization library for Rust that renders waveforms with CRT-oscilloscope-like intensity grading.

In-browser demo. Press the play button! (Details below.)

§Quick Start

Add to your Cargo.toml:

[dependencies]
phosphor = { path = "phosphor" }

The easiest way to use Phosphor is headless mode, where Phosphor itself manages the WGPU context.

use phosphor::{PhosphorHeadless, gradient::RgbColor, headless::Bitmap};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create headless renderer
    // This is an async operation. We use `pollster` as an adapter.
    let mut renderer = pollster::block_on(PhosphorHeadless::new((512, 128).into()))?;

    // Set waveform data
    const N: usize = 10_000;
    let samples: Vec<f32> = (0..N)
            .map(|i| i as f32 / N as f32 * 8.)
            .map(|x| x.powf(3.).sin() * (0.5 + 0.4 * (2. * x).sin()))
            .collect();
    renderer.set_waveform_yt(&samples);

    // Configure appearance
    renderer.set_intensity(0.1);
    renderer.set_xlim(0.0, N as f32);
    renderer.set_ylim(-1.1, 1.1);
    renderer.set_beam_width(8.); 

    // Render to bitmap
    let bitmap = renderer.render_to_buffer()?;
    // `bitmap.buffer` contains RGBA pixel data. We use the `image` library to export to
    // a PNG file.
    let image =
        image::RgbaImage::from_raw(bitmap.size.width, bitmap.size.height, bitmap.buffer).unwrap();
    image.save("../assets/quickstart.png");

    Ok(())
}

The generated image:

quickstart.png

(Link may be broken if you’re not viewing this readme on Gitlab.)

To integrate Phosphor into a GUI application that already uses wgpu for rendering, you will get better performance by drawing directly to the screen.

§Features

  • GPU-accelerated rendering: Uses wgpu for high-performance visualization
  • Automatic intensity adjustment: Optional feature for optimal brightness normalization
  • Customizable colormaps
  • Headless rendering: Off-screen rendering support
  • Cross-platform: Windows, macOS, Linux, and WebAssembly

§Architecture

The waveform is rendered in multiple steps.

  1. Waveform rendering: Line segments rendered as oriented quads into an intermediate texture.
  2. Auto-intensity (optional): Automatic brightness normalization via compute shader
  3. Post-processing: The intermediate texture is rendered to the screen, while applying the false-color mapping.

§Running the Demos

Phosphor currently comes with 2 demos.

  1. The first one is a real-time visualizer for the Oscillofun track. It’s a song that, when both audio channels are connected to an oscilloscope in XY mode, draws a neat animation.

    The demo is available online. Press the ‘Play’ button after it is done loading.

  2. A simple interactive time-domain visualization of a long waveform. The demo does compile to WASM, but is not available online yet. Clone the repository, and run:

    cargo run --bin demo-egui

Re-exports§

pub use headless::PhosphorHeadless;
pub use renderer::Renderer;

Modules§

gradient
Color gradients and RGB color utilities.
headless
Headless (off-screen) rendering support.
renderer