Struct Renderer 

pub struct Renderer<B, M>
where
    B: ScreenBuffer,
    B::Drawer: CellDrawer,
{ /* private fields */ }

Implementations

impl<B, M> Renderer<B, M>

where B: ScreenBuffer, B::Drawer: CellDrawer, M: RenderModeBehavior,

pub fn set_update_interval(&mut self, amount: usize)

set how aggrisive draw batches should try to merge

pub fn get_terminal_size(&self) -> (u16, u16)

pub fn create_renderer(size: (u16, u16)) -> Self

Create a new renderer with an initial terminal size.

Examples found in repository

examples/screens.rs (lines 118-120)

pub fn main() -> Result<(), AppError> {
    init_terminal!();
    init_logger("./screens_showcase.log")?;

    let (cols, rows) = size()?;
    let renderer = Renderer::<DefaultScreenBuffer<CrosstermCellDrawer>, Instant>::create_renderer(
        (cols, rows),
    );
    let (mut r, ev_handler, _ev_manager) = start_renderer_with_input(renderer);
    r.set_update_interval(1)?;

    let mut hook = ev_handler.create_hook();

    let mut ad_screens = AdjustableScreens::new_uniform_grid(WIDTH, HEIGHT, &mut r)?;

    for screen in &mut ad_screens {
        let builder = DrawObjectBuilder::default();
        let d_key = builder
            .layer(100)
            .rect_drawable(|r| {
                r.border_style(
                ltrender::terminal_buffer::standard_drawables::rect_drawable::BorderStyle::Custom {
                    top: TerminalChar::from_char('T'),
                    bottom: TerminalChar::from_char('B'),
                    left: TerminalChar::from_char('L'),
                    right: TerminalChar::from_char('R'),
                },
            )
            .border_thickness(1)
            .fill_style(' ')
            .rect(Rect::from_coords(0, 0, 2, 2))
            .screen_fit(ScreenFitType::Full)
            })?
            .add_lifetime(ObjectLifetime::ExplicitRemove)
            .screen(screen)
            .build(&mut r)?;
        info!("manually rendering drawable: {:?}", d_key);
        r.render_drawable(d_key)?;
    }

    let (s, recv) = mpsc::channel();
    let builder = DrawObjectBuilder::default();
    let text_stream = builder
        .layer(200)
        .videostream_drawable(|b| b.position((0, 0)).recv(recv))?
        .add_lifetime(ObjectLifetime::ExplicitRemove)
        .screen(0)
        .build(&mut r)?;
    let callback_hook = ev_handler.create_hook();
    let callback_renderh: RenderHandle<Instant> = r.clone();
    hook.on_mouse_button_press(MouseButtons::Left, move |_| {
        if let TargetScreen::Screen(id) = callback_hook.current_selected_screen() {
            let msg = format!("selected_screen: {} ", id);
            info!("{}", msg);
            let mut data = Vec::new();
            for chr in msg.chars() {
                data.push(Some(TerminalChar::from_char(chr)));
            }
            let _ = s.send(StreamFrame {
                size: (data.len() as u16, 1),
                data,
            });
            let _ = callback_renderh.render_drawable(text_stream);
        }
    })?;
    loop {
        if hook.is_pressed(InputButton::Key(KeyCode::Char('c'))) {
            info!("breaking out of the loop");
            break;
        }

        let cur_size = size()?;
        let rendered_size = r.get_terminal_size()?;
        if cur_size != rendered_size {
            info!(
                "redrawing with cur_size: {:?}, rendered: {:?}",
                cur_size, rendered_size
            );
            r.handle_resize(cur_size)?;
            ad_screens.place_screens_uniformly(&mut r)?;
        }
    }
    restore_terminal()?;
    info!("returning with ok");
    Ok(())
}

examples/swarm.rs (lines 196-198)

pub fn main() -> Result<(), AppError> {
    init_terminal!();
    init_logger("./organic_swarm.log")?;

    // creating the tick manager for syncing the waves with the main swarm
    let (_manager, manager_handle) = TickManager::new(tick_manager_rs::Speed::Fps(50));
    let main_member = tick_manager_rs::TickMember::new(manager_handle.clone(), 1);
    let bg_member = tick_manager_rs::TickMember::new(manager_handle, 6);

    let (cols, rows) = size()?;
    let renderer = Renderer::<DefaultScreenBuffer<CrosstermCellDrawer>, Buffered>::create_renderer(
        (cols, rows),
    );
    let mut r = start_renderer(renderer);
    r.set_update_interval(16)?;

    let screen = r.create_screen(AreaRect::FullScreen, 5)?;

    let (tx, video_drawable) = make_videostream_drawable((0, 0), 1)?;
    let video_id = DrawObjectBuilder::default()
        .layer(1)
        .screen(screen)
        .drawable(video_drawable)
        .shader(Grayscale)
        .add_lifetime(ObjectLifetime::ExplicitRemove)
        .build(&mut r)?;
    spawn_soft_wave(
        tx,
        RenderHandle::<Buffered>::clone(&r),
        video_id,
        (cols, rows),
        bg_member,
    );

    // Optional: tiny sprite clock in the corner (if you have a .ascv around, otherwise harmless).
    if let Ok(sprite) = r.register_sprite_from_source("./assets/debugging/test_video.ascv") {
        let spr_draw = SpriteDrawableBuilder::default()
            .sprite_id(sprite)
            .position((0, 50))
            .animation_type(AnimationInfo::Video {
                loop_type: VideoLoopType::Loop,
                speed: VideoSpeed::Fps(4),
                start_frame: FrameIdent::FirstFrame,
                end_frame: FrameIdent::LastFrame,
            })
            .build()?;
        let _spr_id = DrawObjectBuilder::default()
            .layer(2)
            .screen(screen)
            .drawable(spr_draw)
            .add_lifetime(ObjectLifetime::ExplicitRemove)
            .build(&mut r)?;
    }
    let rect_id: DrawObjectKey = DrawObjectBuilder::default()
        .layer(100)
        .screen(screen)
        .rect_drawable(|r| {
            r.border_style(
                ltrender::terminal_buffer::standard_drawables::rect_drawable::BorderStyle::Custom {
                    top: TerminalChar::from_char('T'),
                    bottom: TerminalChar::from_char('B'),
                    left: TerminalChar::from_char('L'),
                    right: TerminalChar::from_char('R'),
                },
            )
            .border_thickness(2)
            .fill_style(' ')
            .rect(Rect::from_coords(20, 20, 40, 40))
        })?
        .add_lifetime(ObjectLifetime::ExplicitRemove)
        .build(&mut r)?;

    // HUD text (toggle with 'h').
    let mut show_hud = true;
    let hud_drawable = Box::new(text_drawable::TextDrawable {
        area: Rect::from_coords(1, 1, 50, 10),
        lines: vec![text_drawable::LineInfo {
            text: String::from(
                "organic swarm — drag mouse, left: attract, right: repel, scroll: strength, n: reseed, h: HUD, q: quit",
            ),
            spans: vec![],
            alignment: text_drawable::TextAlignment::Left,
            default_style: text_drawable::TextStyle {
                foreground: Some(Color::White),
                bold: Some(true),
                ..Default::default()
            },
        }],
        wrapping: true,
        scroll_y: 0,
    });
    let hud_id = DrawObjectBuilder::default()
        .layer(9)
        .screen(screen)
        .drawable(hud_drawable)
        .add_lifetime(ObjectLifetime::ExplicitRemove)
        .build(&mut r)?;

    // Seed agents.
    let mut agents = seeded_swarm(&mut r, screen, 140, cols, rows);

    // Input and timing state.
    let start = Instant::now();
    let mut mouse = MouseState {
        x: (cols / 2) as i32,
        y: (rows / 2) as i32,
        left: false,
        right: false,
        strength: 18.0,
    };
    let mut running = true;

    let mut render_start;
    let mut fps_vec: Vec<f64> = Vec::new();
    let mut time_since_last_fps_log = Instant::now();

    while running {
        render_start = Instant::now();
        // Input ----------------------------------------------------
        if poll(Duration::from_millis(0))? {
            match read()? {
                Event::Key(k) => {
                    match k.code {
                        KeyCode::Esc | KeyCode::Char('q') => running = false,
                        KeyCode::Char('n') => {
                            // Reseed: drop old agents visually and create new ones.
                            for a in &agents {
                                r.explicit_remove_drawable(&a.id)?;
                            }
                            agents = seeded_swarm(&mut r, screen, 140, cols, rows);
                        }
                        KeyCode::Char('h') => {
                            show_hud = !show_hud;
                            if show_hud {
                                r.render_drawable(hud_id)?;
                            } else {
                                r.explicit_remove_drawable(&hud_id)?;
                            }
                        }
                        _ => {}
                    }
                }
                Event::Mouse(me) => match me.kind {
                    MouseEventKind::Moved | MouseEventKind::Drag(_) => {
                        mouse.x = me.column as i32;
                        mouse.y = me.row as i32;
                    }
                    MouseEventKind::Down(btn) => {
                        use crossterm::event::MouseButton;
                        match btn {
                            MouseButton::Left => mouse.left = true,
                            MouseButton::Right => mouse.right = true,
                            MouseButton::Middle => {
                                mouse.strength = 12.0;
                            }
                        }
                    }
                    MouseEventKind::Up(btn) => {
                        use crossterm::event::MouseButton;
                        match btn {
                            MouseButton::Left => mouse.left = false,
                            MouseButton::Right => mouse.right = false,
                            MouseButton::Middle => {}
                        }
                    }
                    MouseEventKind::ScrollDown => {
                        mouse.strength = (mouse.strength - 2.0).max(4.0);
                    }
                    MouseEventKind::ScrollUp => {
                        mouse.strength = (mouse.strength + 2.0).min(40.0);
                    }
                    _ => {}
                },
                Event::Resize(c, rws) => {
                    r.handle_resize((c, rws))?;
                }
                _ => {}
            }
        }

        // Simulation ----------------------------------------------
        let (cw, ch) = (cols as f64, rows as f64);
        let t = start.elapsed().as_secs_f64();

        for a in &mut agents {
            let fx = ((a.pos.1 * 0.05 + t * 0.3).sin() * 0.8) + (t * 0.1 + a.wobble).cos() * 0.2;
            let fy = ((a.pos.0 * 0.05 - t * 0.25).cos() * 0.8) + (t * 0.13).sin() * 0.2;

            let mut steer_x = fx;
            let mut steer_y = fy;

            // Mouse field
            let dx = mouse.x as f64 - a.pos.0;
            let dy = mouse.y as f64 - a.pos.1;
            let d2 = (dx * dx + dy * dy).max(0.0001);
            let inv = 1.0 / d2.sqrt();
            let toward = (dx * inv, dy * inv);

            if mouse.left {
                // attract
                steer_x += toward.0 * (mouse.strength * inv);
                steer_y += toward.1 * (mouse.strength * inv);
            }
            if mouse.right {
                // repel
                steer_x -= toward.0 * (mouse.strength * inv);
                steer_y -= toward.1 * (mouse.strength * inv);
            }

            // Convert steer into angle change.
            let desired = steer_y.atan2(steer_x);
            let mut diff = desired - a.dir;
            while diff > std::f64::consts::PI {
                diff -= std::f64::consts::TAU;
            }
            while diff < -std::f64::consts::PI {
                diff += std::f64::consts::TAU;
            }

            a.dir += diff * 0.15 + (t * a.wobble).sin() * 0.02;
            a.speed = lerp(a.speed, 1.2 + (t * 0.7 + a.wobble).sin().abs(), 0.05);

            // Integrate position with gentle easing near mouse to make it feel alive.
            let step = a.speed;
            a.pos.0 = wrap(a.pos.0 + a.dir.cos() * step, cw);
            a.pos.1 = wrap(a.pos.1 + a.dir.sin() * step, ch);

            // Push to renderer
            let pts = triangle_points(a.pos.0, a.pos.1, a.dir, a.size);
            r.replace_drawable_points(a.id, pts)?;
            r.render_drawable(a.id)?;
        }

        r.render_drawable(rect_id)?;

        let frame_preperation_duration = render_start.elapsed();

        if show_hud {
            let fps = 1.0 / frame_preperation_duration.as_secs_f64();
            fps_vec.push(fps);

            if time_since_last_fps_log.elapsed() > Duration::from_secs(5) {
                let count = fps_vec.len();

                if count > 0 {
                    let sum: f64 = fps_vec.iter().sum();
                    let avg_fps = sum / count as f64;
                    info!("Avg FPS over the last 5s: {:.2} ", avg_fps);
                }
                fps_vec.clear();
                time_since_last_fps_log = Instant::now();
            }

            let txt = format!(
                "time spent rendering frame: ~{fps:.1} | agents: {} | force: {:.1} | mouse: ({}, {}) L:{} R:{}",
                agents.len(),
                mouse.strength,
                mouse.x,
                mouse.y,
                mouse.left as u8,
                mouse.right as u8
            );

            let hud = text_drawable::TextDrawable {
                area: Rect::from_coords(1, 1, 100, 6),
                lines: vec![text_drawable::LineInfo {
                    text: txt,
                    spans: vec![],
                    alignment: text_drawable::TextAlignment::Left,
                    default_style: text_drawable::TextStyle {
                        foreground: Some(Color::White),
                        bold: Some(true),
                        ..Default::default()
                    },
                }],
                wrapping: true,
                scroll_y: 0,
            };
            r.replace_drawable(hud_id, Box::new(hud))?;
            r.render_drawable(hud_id)?;
        }
        main_member.wait_for_tick();
        r.render_frame()?;
    }

    // cleanup
    for a in &agents {
        r.explicit_remove_drawable(&a.id)?;
    }
    r.explicit_remove_drawable(&video_id)?;

    ltrender::restore_terminal()?;
    Ok(())
}

pub fn create_screen(&mut self, rect: AreaRect, layer: usize) -> ScreenKey

Create a new screen and return its key.

pub fn change_screen_area( &mut self, screen_id: ScreenKey, new_area: AreaRect, ) -> Result<(), DrawError>

pub fn change_screen_layer( &mut self, screen_id: ScreenKey, new_layer: usize, ) -> Result<(), DrawError>

pub fn register_drawable( &mut self, screen_id: ScreenKey, obj: DrawObject, ) -> Result<DrawObjectKey, DrawError>

Register a drawable object on a screen.

pub fn remove_drawable(&mut self, id: DrawObjectKey) -> Result<(), DrawError>

pub fn explicit_remove_drawable( &mut self, id: &DrawObjectKey, ) -> Result<(), DrawError>

pub fn replace_drawable( &mut self, id: DrawObjectKey, drawable: Box<dyn Drawable>, ) -> Result<(), DrawError>

pub fn check_if_object_lifetime_ended(&mut self) -> Result<(), DrawError>

checks if any of the currently existing drawobjects should be removed, because its duration on screen has ended

pub fn register_sprite_from_source( &mut self, path: &str, ) -> Result<SpriteId, AppError>

Load a sprite from an ASCII video file.

pub fn render_drawable( &mut self, object_key: DrawObjectKey, ) -> Result<(), DrawError>

Render a single drawable object.

pub fn handle_resize(&mut self, new_size: (u16, u16)) -> Result<(), DrawError>

pub fn generate_screen_key(&self) -> ScreenKey

Generate a unique screen key.

pub fn move_drawable_to( &mut self, handle: DrawObjectKey, new_pos: Point<i32>, ) -> Result<(), DrawError>

pub fn move_drawable_by( &mut self, handle: DrawObjectKey, dx: i32, dy: i32, ) -> Result<(), DrawError>

pub fn move_drawable_point( &mut self, handle: DrawObjectKey, point_index: usize, new_pos: Point<i32>, ) -> Result<(), DrawError>

pub fn move_multipoint_drawable_point( &mut self, handle: DrawObjectKey, point_index: usize, new_pos: Point<i32>, ) -> Result<(), DrawError>

pub fn replace_drawable_points( &mut self, handle: DrawObjectKey, new_points: Vec<Point<i32>>, ) -> Result<(), DrawError>

replace a drawables points

pub fn run_drawable_screen_fitting( &mut self, handle: DrawObjectKey, unadjusted_screen_area: Rect<i32>, ) -> Result<(), DrawError>

pub fn get_amount_of_points( &mut self, handle: DrawObjectKey, ) -> Result<Option<usize>, DrawError>

pub fn handle_screen_selection(&self, hook: &EventHook) -> Result<(), AppError>

selects a different screen, if a mouse button has been clicked the EventHook is needed to access the mouse’s current position

pub fn add_screen_select_handler( &mut self, screen_select_handler: ScreenSelectHandler, )

pub fn into_buffered(self) -> Renderer<B, M>

pub fn into_instant(self) -> Renderer<B, M>

impl<B, Buffered> Renderer<B, Buffered>

where B: ScreenBuffer, B::Drawer: CellDrawer, Buffered: RenderModeBehavior,

pub fn render_frame(&mut self) -> Result<(), DrawError>

pub fn remove_all_framebased_objects(&mut self) -> Result<(), DrawError>

removes all the objects from screen, that have frame-based removal