Struct Renderer 

pub struct Renderer { /* private fields */ }

Renderer for the terminal using custom wgpu cell renderer

Implementations

impl Renderer

pub fn update_graphics( &mut self, graphics: &[TerminalGraphic], view_scroll_offset: usize, scrollback_len: usize, visible_rows: usize, ) -> Result<(), Error>

Update graphics textures (Sixel, iTerm2, Kitty)

Arguments

• graphics - Graphics from the terminal with RGBA data
• view_scroll_offset - Current view scroll offset (0 = viewing current content)
• scrollback_len - Total lines in scrollback buffer
• visible_rows - Number of visible rows in terminal

pub fn clear_sixel_cache(&mut self)

Clear all cached sixel textures

pub fn sixel_cache_size(&self) -> usize

Get the number of cached sixel textures

pub fn remove_sixel_texture(&mut self, id: u64)

Remove a specific sixel texture from cache

impl Renderer

pub fn set_custom_shader_animation(&mut self, enabled: bool)

Enable or disable animation for the custom shader at runtime

pub fn set_shader_mouse_position(&mut self, x: f32, y: f32)

Update mouse position for custom shader (iMouse uniform)

Arguments

• x - Mouse X position in pixels (0 = left edge)
• y - Mouse Y position in pixels (0 = top edge)

pub fn set_shader_mouse_button(&mut self, pressed: bool, x: f32, y: f32)

Update mouse button state for custom shader (iMouse uniform)

Arguments

• pressed - True if left mouse button is pressed
• x - Mouse X position at time of click/release
• y - Mouse Y position at time of click/release

pub fn update_key_press_time(&mut self)

Update key press time for custom shaders (iTimeKeyPress uniform)

Call this when a key is pressed to enable key-press-based shader effects like screen pulses, typing animations, or keystroke visualizations.

pub fn update_shader_cursor( &mut self, col: usize, row: usize, opacity: f32, color: [f32; 4], style: CursorStyle, )

Update cursor state for custom shader (Ghostty-compatible cursor uniforms)

This enables cursor trail effects and other cursor-based animations in custom shaders.

Arguments

• col - Cursor column position (0-based)
• row - Cursor row position (0-based)
• opacity - Cursor opacity (0.0 = invisible, 1.0 = fully visible)
• color - Cursor RGBA color
• style - Cursor style (Block, Beam, Underline)

pub fn update_shader_progress( &mut self, state: f32, percent: f32, is_active: f32, active_count: f32, )

Update progress bar state for custom shaders (iProgress uniform)

Arguments

• state - Progress state (0=hidden, 1=normal, 2=error, 3=indeterminate, 4=warning)
• percent - Progress percentage as 0.0-1.0
• is_active - 1.0 if any progress bar is active, 0.0 otherwise
• active_count - Total count of active bars (simple + named)

pub fn update_cursor_shader_config( &mut self, color: [u8; 3], trail_duration: f32, glow_radius: f32, glow_intensity: f32, )

Update cursor shader configuration from config values. Glow radius is in logical pixels and will be scaled to physical pixels internally.

Arguments

• color - Cursor color for shader effects [R, G, B] (0-255)
• trail_duration - Duration of cursor trail effect in seconds
• glow_radius - Radius of cursor glow effect in logical pixels
• glow_intensity - Intensity of cursor glow effect (0.0-1.0)

pub fn set_cursor_shader_enabled( &mut self, enabled: bool, path: Option<&str>, window_opacity: f32, animation_enabled: bool, animation_speed: f32, ) -> Result<(), String>

Enable or disable the cursor shader at runtime

Arguments

• enabled - Whether to enable the cursor shader
• path - Optional shader path (relative to shaders folder or absolute)
• window_opacity - Current window opacity
• animation_enabled - Whether animation is enabled
• animation_speed - Animation speed multiplier

Returns

Ok(()) if successful, Err with error message if compilation fails

pub fn cursor_shader_path(&self) -> Option<&str>

Get the current cursor shader path

pub fn reload_cursor_shader_from_source( &mut self, source: &str, ) -> Result<(), Error>

Reload the cursor shader from source code

pub fn reload_shader_from_source(&mut self, source: &str) -> Result<(), Error>

Reload the custom shader from source code

This method compiles the new shader source and replaces the current pipeline. If compilation fails, returns an error and the old shader remains active.

Arguments

• source - The GLSL shader source code

Returns

Ok(()) if successful, Err with error message if compilation fails

pub fn set_custom_shader_enabled( &mut self, enabled: bool, shader_path: Option<&str>, window_opacity: f32, animation_enabled: bool, animation_speed: f32, full_content: bool, brightness: f32, channel_paths: &[Option<PathBuf>; 4], cubemap_path: Option<&Path>, ) -> Result<(), String>

Enable/disable custom shader at runtime. When enabling, tries to (re)load the shader from the given path; when disabling, drops the renderer instance.

Returns Ok(()) on success, or Err with error message on failure.

pub fn set_use_background_as_channel0(&mut self, use_background: bool)

Set whether to use the background image as iChannel0 for the custom shader.

When enabled, the app’s configured background image is bound as iChannel0 instead of the custom_shader_channel0 texture file.

pub fn sync_background_texture_to_shader(&mut self)

Update the background texture for use as iChannel0 in shaders.

Call this whenever the background image changes to sync the shader’s channel0 texture. This only has an effect if use_background_as_channel0 is enabled.

pub fn update_background_as_channel0(&mut self, use_background: bool)

Update both the use_background_as_channel0 flag and sync the texture.

This method should be called when:

• The use_background_as_channel0 setting changes
• The background image or solid color changes (to sync the new texture)
• Per-shader config changes

The background texture is always synced to ensure changes are reflected.

pub fn update_background_as_channel0_with_mode( &mut self, use_background: bool, background_mode: BackgroundMode, color: [u8; 3], )

Update background as channel0 with solid color support.

This method handles the case where background_mode is Color and we need to create a solid color texture to pass as iChannel0 instead of an image.

Arguments

• use_background - Whether to use background as iChannel0
• background_mode - The current background mode (Default, Color, or Image)
• color - The solid background color (used if mode is Color)

impl Renderer

pub async fn new( window: Arc<Window>, font_family: Option<&str>, font_family_bold: Option<&str>, font_family_italic: Option<&str>, font_family_bold_italic: Option<&str>, font_ranges: &[FontRange], font_size: f32, window_padding: f32, line_spacing: f32, char_spacing: f32, scrollbar_position: &str, scrollbar_width: f32, scrollbar_thumb_color: [f32; 4], scrollbar_track_color: [f32; 4], enable_text_shaping: bool, enable_ligatures: bool, enable_kerning: bool, font_antialias: bool, font_hinting: bool, font_thin_strokes: ThinStrokesMode, minimum_contrast: f32, vsync_mode: VsyncMode, power_preference: PowerPreference, window_opacity: f32, background_color: [u8; 3], background_image_path: Option<&str>, background_image_enabled: bool, background_image_mode: BackgroundImageMode, background_image_opacity: f32, custom_shader_path: Option<&str>, custom_shader_enabled: bool, custom_shader_animation: bool, custom_shader_animation_speed: f32, custom_shader_full_content: bool, custom_shader_brightness: f32, custom_shader_channel_paths: &[Option<PathBuf>; 4], custom_shader_cubemap_path: Option<&Path>, use_background_as_channel0: bool, image_scaling_mode: ImageScalingMode, image_preserve_aspect_ratio: bool, cursor_shader_path: Option<&str>, cursor_shader_enabled: bool, cursor_shader_animation: bool, cursor_shader_animation_speed: f32, ) -> Result<Renderer, Error>

Create a new renderer

pub fn resize(&mut self, new_size: PhysicalSize<u32>) -> (usize, usize)

Resize the renderer and recalculate grid dimensions based on padding/font metrics

pub fn handle_scale_factor_change( &mut self, scale_factor: f64, new_size: PhysicalSize<u32>, ) -> (usize, usize)

Update scale factor and resize so the PTY grid matches the new DPI.

pub fn update_cells(&mut self, cells: &[Cell])

Update the terminal cells

pub fn clear_all_cells(&mut self)

Clear all cells in the renderer. Call this when switching tabs to ensure a clean slate.

pub fn update_cursor( &mut self, position: (usize, usize), opacity: f32, style: CursorStyle, )

Update cursor position and style for geometric rendering

pub fn clear_cursor(&mut self)

Clear cursor (hide it)

pub fn update_scrollbar( &mut self, scroll_offset: usize, visible_lines: usize, total_lines: usize, marks: &[ScrollbackMark], )

Update scrollbar state

Arguments

• scroll_offset - Current scroll offset (0 = at bottom)
• visible_lines - Number of lines visible on screen
• total_lines - Total number of lines including scrollback
• marks - Scrollback marks for visualization on the scrollbar

pub fn set_visual_bell_intensity(&mut self, intensity: f32)

Set the visual bell flash intensity

Arguments

• intensity - Flash intensity from 0.0 (no flash) to 1.0 (full white flash)

pub fn update_opacity(&mut self, opacity: f32)

Update window opacity in real-time

pub fn update_cursor_color(&mut self, color: [u8; 3])

Update cursor color for cell rendering

pub fn update_cursor_text_color(&mut self, color: Option<[u8; 3]>)

Update cursor text color (color of text under block cursor)

pub fn set_cursor_hidden_for_shader(&mut self, hidden: bool)

Set whether cursor should be hidden when cursor shader is active

pub fn set_focused(&mut self, focused: bool)

Set window focus state (affects unfocused cursor rendering)

pub fn update_cursor_guide(&mut self, enabled: bool, color: [u8; 4])

Update cursor guide settings

pub fn update_cursor_shadow( &mut self, enabled: bool, color: [u8; 4], offset: [f32; 2], blur: f32, )

Update cursor shadow settings. Offset and blur are in logical pixels and will be scaled to physical pixels internally.

pub fn update_cursor_boost(&mut self, intensity: f32, color: [u8; 3])

Update cursor boost settings

pub fn update_unfocused_cursor_style(&mut self, style: UnfocusedCursorStyle)

Update unfocused cursor style

pub fn update_command_separator( &mut self, enabled: bool, logical_thickness: f32, opacity: f32, exit_color: bool, color: [u8; 3], )

Update command separator settings from config. Thickness is in logical pixels and will be scaled to physical pixels internally.

pub fn set_separator_marks( &mut self, marks: Vec<(usize, Option<i32>, Option<(u8, u8, u8)>)>, )

Set the visible separator marks for the current frame (single-pane path)

pub fn set_transparency_affects_only_default_background(&mut self, value: bool)

Set whether transparency affects only default background cells. When true, non-default (colored) backgrounds remain opaque for readability.

pub fn set_keep_text_opaque(&mut self, value: bool)

Set whether text should always be rendered at full opacity. When true, text remains opaque regardless of window transparency settings.

pub fn set_link_underline_style(&mut self, style: LinkUnderlineStyle)

pub fn set_cursor_shader_disabled_for_alt_screen(&mut self, disabled: bool)

Set whether cursor shader should be disabled due to alt screen being active

When alt screen is active (e.g., vim, htop, less), cursor shader effects are disabled since TUI applications typically have their own cursor handling.

pub fn update_window_padding( &mut self, logical_padding: f32, ) -> Option<(usize, usize)>

Update window padding in real-time without full renderer rebuild. Accepts logical pixels (from config); scales to physical pixels internally. Returns Some((cols, rows)) if grid size changed and terminal needs resize.

pub fn set_background_image_enabled( &mut self, enabled: bool, path: Option<&str>, mode: BackgroundImageMode, opacity: f32, )

Enable/disable background image and reload if needed

pub fn set_background( &mut self, mode: BackgroundMode, color: [u8; 3], image_path: Option<&str>, image_mode: BackgroundImageMode, image_opacity: f32, image_enabled: bool, )

Set background based on mode (Default, Color, or Image).

This unified method handles all background types and syncs with shaders.

pub fn update_scrollbar_appearance( &mut self, logical_width: f32, thumb_color: [f32; 4], track_color: [f32; 4], )

Update scrollbar appearance in real-time. Width is in logical pixels and will be scaled to physical pixels internally.

pub fn update_scrollbar_position(&mut self, position: &str)

Update scrollbar position (left/right) in real-time

pub fn update_background_image_opacity(&mut self, opacity: f32)

Update background image opacity in real-time

pub fn load_pane_background(&mut self, path: &str) -> Result<bool, Error>

Load a per-pane background image into the texture cache. Delegates to CellRenderer::load_pane_background.

pub fn update_image_scaling_mode(&mut self, scaling_mode: ImageScalingMode)

Update inline image scaling mode (nearest vs linear filtering).

Recreates the GPU sampler and clears the texture cache so images are re-rendered with the new filter mode.

pub fn update_image_preserve_aspect_ratio(&mut self, preserve: bool)

Update whether inline images preserve their aspect ratio.

pub fn needs_continuous_render(&self) -> bool

Check if animation requires continuous rendering

Returns true if shader animation is enabled or a cursor trail animation might still be in progress.

pub fn render( &mut self, egui_data: Option<(FullOutput, &Context)>, force_egui_opaque: bool, show_scrollbar: bool, pane_background: Option<&PaneBackground>, ) -> Result<bool, Error>

Render a frame with optional egui overlay Returns true if rendering was performed, false if skipped

pub fn render_panes( &mut self, panes: &[PaneRenderInfo<'_>], egui_data: Option<(FullOutput, &Context)>, force_egui_opaque: bool, ) -> Result<bool, Error>

Render multiple panes to the surface

This method renders each pane’s content to its viewport region, handling focus indicators and inactive pane dimming.

Arguments

• panes - List of panes to render with their viewport info
• egui_data - Optional egui overlay data
• force_egui_opaque - Force egui to render at full opacity

Returns

true if rendering was performed, false if skipped

pub fn render_split_panes( &mut self, panes: &[PaneRenderInfo<'_>], dividers: &[DividerRenderInfo], pane_titles: &[PaneTitleInfo], focused_viewport: Option<&PaneViewport>, divider_settings: &PaneDividerSettings, egui_data: Option<(FullOutput, &Context)>, force_egui_opaque: bool, ) -> Result<bool, Error>

Render split panes with dividers and focus indicator

This is the main entry point for rendering a split pane layout. It handles:

1. Clearing the surface
2. Rendering each pane’s content
3. Rendering dividers between panes
4. Rendering focus indicator around the focused pane
5. Rendering egui overlay if provided
6. Presenting the surface

Arguments

• panes - List of panes to render with their viewport info
• dividers - List of dividers between panes with hover state
• focused_viewport - Viewport of the focused pane (for focus indicator)
• divider_settings - Settings for divider and focus indicator appearance
• egui_data - Optional egui overlay data
• force_egui_opaque - Force egui to render at full opacity

Returns

true if rendering was performed, false if skipped

pub fn render_dividers( &mut self, surface_view: &TextureView, dividers: &[DividerRenderInfo], settings: &PaneDividerSettings, ) -> Result<(), Error>

Render pane dividers on top of pane content

This should be called after rendering pane content but before egui.

Arguments

• surface_view - The texture view to render to
• dividers - List of dividers to render with hover state
• settings - Divider appearance settings

pub fn render_focus_indicator( &mut self, surface_view: &TextureView, viewport: &PaneViewport, settings: &PaneDividerSettings, ) -> Result<(), Error>

Render focus indicator around a pane

This draws a colored border around the focused pane to highlight it.

Arguments

• surface_view - The texture view to render to
• viewport - The focused pane’s viewport
• settings - Divider/focus settings

pub fn render_pane_titles( &mut self, surface_view: &TextureView, titles: &[PaneTitleInfo], ) -> Result<(), Error>

Render pane title bars (background rectangles + text)

Title bars are rendered on top of pane content and dividers. Each title bar consists of a colored background rectangle and centered text.

pub fn size(&self) -> PhysicalSize<u32>

Get the current size

pub fn grid_size(&self) -> (usize, usize)

Get the current grid dimensions (columns, rows)

pub fn cell_width(&self) -> f32

Get cell width in pixels

pub fn cell_height(&self) -> f32

Get cell height in pixels

pub fn window_padding(&self) -> f32

Get window padding in physical pixels (scaled by DPI)

pub fn content_offset_y(&self) -> f32

Get the vertical content offset in physical pixels (e.g., tab bar height scaled by DPI)

pub fn scale_factor(&self) -> f32

Get the display scale factor (e.g., 2.0 on Retina displays)

pub fn set_content_offset_y( &mut self, logical_offset: f32, ) -> Option<(usize, usize)>

Set the vertical content offset (e.g., tab bar height) in logical pixels. The offset is scaled by the display scale factor to physical pixels internally, since the cell renderer works in physical pixel coordinates while egui (tab bar) uses logical pixels. Returns Some((cols, rows)) if grid size changed, None otherwise.

pub fn content_offset_x(&self) -> f32

Get the horizontal content offset in physical pixels

pub fn set_content_offset_x( &mut self, logical_offset: f32, ) -> Option<(usize, usize)>

Set the horizontal content offset (e.g., tab bar on left) in logical pixels. Returns Some((cols, rows)) if grid size changed, None otherwise.

pub fn content_inset_bottom(&self) -> f32

Get the bottom content inset in physical pixels

pub fn content_inset_right(&self) -> f32

Get the right content inset in physical pixels

pub fn set_content_inset_bottom( &mut self, logical_inset: f32, ) -> Option<(usize, usize)>

Set the bottom content inset (e.g., tab bar at bottom) in logical pixels. Returns Some((cols, rows)) if grid size changed, None otherwise.

pub fn set_content_inset_right( &mut self, logical_inset: f32, ) -> Option<(usize, usize)>

Set the right content inset (e.g., AI Inspector panel) in logical pixels. Returns Some((cols, rows)) if grid size changed, None otherwise.

pub fn set_egui_bottom_inset( &mut self, logical_inset: f32, ) -> Option<(usize, usize)>

Set the additional bottom inset from egui panels (status bar, tmux bar).

This inset reduces the terminal grid height so content does not render behind the status bar. Also affects scrollbar bounds. Returns Some((cols, rows)) if the grid was resized.

pub fn set_egui_right_inset(&mut self, logical_inset: f32)

Set the additional right inset from egui panels (AI Inspector).

This inset is added to content_inset_right for scrollbar bounds only. egui panels already claim space before wgpu rendering, so this doesn’t affect the terminal grid sizing.

pub fn scrollbar_contains_point(&self, x: f32, y: f32) -> bool

Check if a point (in pixel coordinates) is within the scrollbar bounds

Arguments

• x - X coordinate in pixels (from left edge)
• y - Y coordinate in pixels (from top edge)

pub fn scrollbar_thumb_bounds(&self) -> Option<(f32, f32)>

Get the scrollbar thumb bounds (top Y, height) in pixels

pub fn scrollbar_track_contains_x(&self, x: f32) -> bool

Check if an X coordinate is within the scrollbar track

pub fn scrollbar_mouse_y_to_scroll_offset(&self, mouse_y: f32) -> Option<usize>

Convert a mouse Y position to a scroll offset

Arguments

• mouse_y - Mouse Y coordinate in pixels (from top edge)

Returns

The scroll offset corresponding to the mouse position, or None if scrollbar is not visible

pub fn scrollbar_mark_at_position( &self, mouse_x: f32, mouse_y: f32, tolerance: f32, ) -> Option<&ScrollbackMark>

Find a scrollbar mark at the given mouse position for tooltip display.

Arguments

• mouse_x - Mouse X coordinate in pixels
• mouse_y - Mouse Y coordinate in pixels
• tolerance - Maximum distance in pixels to match a mark

Returns

The mark at that position, or None if no mark is within tolerance

pub fn is_dirty(&self) -> bool

Check if the renderer needs to be redrawn

pub fn mark_dirty(&mut self)

Mark the renderer as dirty, forcing a redraw on next render call

pub fn render_debug_overlay(&mut self, text: &str)

Set debug overlay text to be rendered

pub fn reconfigure_surface(&mut self)

Reconfigure the surface (call when surface becomes outdated or lost) This typically happens when dragging the window between displays

pub fn is_vsync_mode_supported(&self, mode: VsyncMode) -> bool

Check if a vsync mode is supported

pub fn update_vsync_mode(&mut self, mode: VsyncMode) -> (VsyncMode, bool)

Update the vsync mode. Returns the actual mode applied (may differ if requested mode unsupported). Also returns whether the mode was changed.

pub fn current_vsync_mode(&self) -> VsyncMode

Get the current vsync mode

pub fn clear_glyph_cache(&mut self)

Clear the glyph cache to force re-rasterization Useful after display changes where font rendering may differ

pub fn update_font_antialias(&mut self, enabled: bool) -> bool

Update font anti-aliasing setting Returns true if the setting changed (requiring glyph cache clear)

pub fn update_font_hinting(&mut self, enabled: bool) -> bool

Update font hinting setting Returns true if the setting changed (requiring glyph cache clear)

pub fn update_font_thin_strokes(&mut self, mode: ThinStrokesMode) -> bool

Update thin strokes mode Returns true if the setting changed (requiring glyph cache clear)

pub fn update_minimum_contrast(&mut self, ratio: f32) -> bool

Update minimum contrast ratio Returns true if the setting changed (requiring redraw)

pub fn pause_shader_animations(&mut self)

Pause shader animations (e.g., when window loses focus) This reduces GPU usage when the terminal is not actively being viewed

pub fn resume_shader_animations( &mut self, custom_shader_animation: bool, cursor_shader_animation: bool, )

Resume shader animations (e.g., when window regains focus) Only resumes if the user’s config has animation enabled

pub fn take_screenshot( &mut self, ) -> Result<ImageBuffer<Rgba<u8>, Vec<u8>>, Error>

Take a screenshot of the current terminal content Returns an RGBA image that can be saved to disk

This captures the fully composited output including shader effects.