display.c File Reference

🖥️ Unified terminal display implementation More...

Go to the source code of this file.

Data Structures
struct	session_display_ctx
	Internal session display context structure. More...

Typedefs
typedef struct session_display_ctx	session_display_ctx_t
	Internal session display context structure.

Functions
session_display_ctx_t *	session_display_create (const session_display_config_t *config)
void	session_display_destroy (session_display_ctx_t *ctx)
bool	session_display_has_tty (session_display_ctx_t *ctx)
const terminal_capabilities_t *	session_display_get_caps (session_display_ctx_t *ctx)
const char *	session_display_get_palette_chars (session_display_ctx_t *ctx)
size_t	session_display_get_palette_len (session_display_ctx_t *ctx)
const char *	session_display_get_luminance_palette (session_display_ctx_t *ctx)
int	session_display_get_tty_fd (session_display_ctx_t *ctx)
char *	session_display_convert_to_ascii (session_display_ctx_t *ctx, const image_t *image)
void	session_display_render_frame (session_display_ctx_t *ctx, const char *frame_data)
void	session_display_write_raw (session_display_ctx_t *ctx, const char *data, size_t len)
void	session_display_reset (session_display_ctx_t *ctx)
void	session_display_clear (session_display_ctx_t *ctx)
void	session_display_cursor_home (session_display_ctx_t *ctx)
void	session_display_set_cursor_visible (session_display_ctx_t *ctx, bool visible)
bool	session_display_has_audio_playback (session_display_ctx_t *ctx)
asciichat_error_t	session_display_write_audio (session_display_ctx_t *ctx, const float *buffer, size_t num_samples)
void	session_display_toggle_help (session_display_ctx_t *ctx)
	Toggle help screen on/off (implemented in display.c for struct access)
bool	session_display_is_help_active (session_display_ctx_t *ctx)
	Check if help screen is currently active (implemented in display.c for struct access)

Detailed Description

🖥️ Unified terminal display implementation

Implements the session display abstraction layer for unified terminal rendering across client, mirror, and discovery modes.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Definition in file lib/session/display.c.

Typedef Documentation

session_display_ctx_t

typedef struct session_display_ctx session_display_ctx_t

Internal session display context structure.

Contains all state for terminal display including TTY info, capabilities, palette, and rendering state.

Function Documentation

session_display_clear()

void session_display_clear

(

session_display_ctx_t *

ctx

)

Definition at line 671 of file lib/session/display.c.

                                                       {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL or uninitialized");
    return;
  }
 
  // Skip terminal clear in snapshot mode to preserve rendered output
  if (ctx->snapshot_mode) {
    return;
  }
 
  // Only perform terminal operations when we have a valid TTY (not when piping)
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    (void)terminal_clear_screen();
    (void)terminal_cursor_home(ctx->tty_info.fd);
  }
}

References session_display_ctx::has_tty, session_display_ctx::initialized, session_display_ctx::snapshot_mode, and session_display_ctx::tty_info.

session_display_convert_to_ascii()

char * session_display_convert_to_ascii	(	session_display_ctx_t *	ctx,
		const image_t *	image
	)

Definition at line 337 of file lib/session/display.c.

                                                                                         {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "session_display_convert_to_ascii: ctx is NULL");
    return NULL;
  }
 
  if (!ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_STATE, "session_display_convert_to_ascii: ctx not initialized");
    return NULL;
  }
 
  if (!image) {
    SET_ERRNO(ERROR_INVALID_PARAM, "session_display_convert_to_ascii: image is NULL");
    return NULL;
  }
 
  // Get conversion parameters from command-line options
  unsigned short int width = GET_OPTION(width);
  unsigned short int height = GET_OPTION(height);
  bool stretch = GET_OPTION(stretch);
  bool preserve_aspect_ratio = !stretch;
 
  // Determine if we should apply flip_x (with macOS webcam caveat)
  bool flip_x_enabled = GET_OPTION(flip_x);
  bool flip_y_enabled = GET_OPTION(flip_y);
 
  // On macOS, webcam respects platform default but ignores the flip_x flag
  // (like FaceTime - always flipped by default regardless of user preference)
#ifdef __APPLE__
  // Check if this frame is from a webcam source
  // For now, we apply the same default but ignore user toggle
  // TODO: Add source tracking to know if frame is from webcam
  flip_x_enabled = false; // Ignore flip_x for now on macOS (will be enhanced with source tracking)
#endif
 
  color_filter_t color_filter = GET_OPTION(color_filter);
 
  // Make a mutable copy of terminal capabilities for ascii_convert_with_capabilities
  terminal_capabilities_t caps_copy = ctx->caps;
 
  // MEASURE EVERY OPERATION - Debug systematic timing
  uint64_t t_flip_start = time_get_ns();
 
  // Apply horizontal and/or vertical flips if requested
  image_t *flipped_image = NULL;
  const image_t *display_image = image;
 
  if ((flip_x_enabled || flip_y_enabled) && image->w > 1 && image->h > 1 && image->pixels) {
    START_TIMER("image_flip");
    uint64_t t_flip_alloc_start = time_get_ns();
    flipped_image = image_new((size_t)image->w, (size_t)image->h);
    uint64_t t_flip_alloc_end = time_get_ns();
 
    if (flipped_image) {
      uint64_t t_flip_memcpy_start = time_get_ns();
      // OPTIMIZATION: Copy entire image first (sequential memory access - cache-friendly)
      memcpy(flipped_image->pixels, image->pixels, (size_t)image->w * (size_t)image->h * sizeof(rgb_pixel_t));
      uint64_t t_flip_memcpy_end = time_get_ns();
 
      uint64_t t_flip_reverse_start = time_get_ns();
 
      // Apply horizontal flip (X-axis)
      if (flip_x_enabled) {
#if SIMD_SUPPORT_NEON
        // Use NEON-accelerated flip on ARM processors
        image_flip_horizontal_neon(flipped_image);
#else
        // Scalar fallback for non-NEON systems
        for (int y = 0; y < image->h; y++) {
          rgb_pixel_t *row = &flipped_image->pixels[y * image->w];
          for (int x = 0; x < image->w / 2; x++) {
            rgb_pixel_t temp = row[x];
            row[x] = row[image->w - 1 - x];
            row[image->w - 1 - x] = temp;
          }
        }
#endif
      }
 
      // Apply vertical flip (Y-axis)
      if (flip_y_enabled) {
        for (int y = 0; y < image->h / 2; y++) {
          rgb_pixel_t *top_row = &flipped_image->pixels[y * image->w];
          rgb_pixel_t *bottom_row = &flipped_image->pixels[(image->h - 1 - y) * image->w];
          for (int x = 0; x < image->w; x++) {
            rgb_pixel_t temp = top_row[x];
            top_row[x] = bottom_row[x];
            bottom_row[x] = temp;
          }
        }
      }
 
      uint64_t t_flip_reverse_end = time_get_ns();
      display_image = flipped_image;
 
      log_dev("TIMING_FLIP: alloc=%llu us, memcpy=%llu us, flip=%llu us (x=%d, y=%d)",
              (t_flip_alloc_end - t_flip_alloc_start) / 1000, (t_flip_memcpy_end - t_flip_memcpy_start) / 1000,
              (t_flip_reverse_end - t_flip_reverse_start) / 1000, flip_x_enabled, flip_y_enabled);
    }
    STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 3 * NS_PER_MS_INT, "image_flip",
                             "IMAGE_FLIP: Flip complete (%.2f ms)");
  }
  uint64_t t_flip_end = time_get_ns();
 
  uint64_t t_filter_start = time_get_ns();
  // No pixel-based filtering for rainbow (ANSI replacement happens later)
  uint64_t t_filter_end = time_get_ns();
 
  uint64_t t_convert_start = time_get_ns();
  // Call the standard ASCII conversion using the display image (unfiltered)
  // This ensures character selection is based on original image brightness
  START_TIMER("ascii_convert_with_capabilities");
  char *result = ascii_convert_with_capabilities(display_image, width, height, &caps_copy, preserve_aspect_ratio,
                                                 stretch, ctx->palette_chars);
  STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 5 * NS_PER_MS_INT, "ascii_convert_with_capabilities",
                           "ASCII_CONVERT: Conversion complete (%.2f ms)");
  uint64_t t_convert_end = time_get_ns();
 
  // Apply rainbow color filter to ANSI output by replacing RGB values
  // This preserves character selection while applying the filter colors
  if (result && color_filter == COLOR_FILTER_RAINBOW) {
    uint64_t t_color_replace_start = time_get_ns();
    float time_seconds = (float)t_filter_start / (float)NS_PER_SEC_INT;
 
    char *rainbow_result = rainbow_replace_ansi_colors(result, time_seconds);
    if (rainbow_result) {
      SAFE_FREE(result);
      result = rainbow_result;
    }
 
    uint64_t t_color_replace_end = time_get_ns();
    log_dev("COLOR_REPLACE: %.2f ms", (double)(t_color_replace_end - t_color_replace_start) / (double)NS_PER_MS_INT);
  }
 
  // Apply digital rain effect if enabled
  if (result && ctx->digital_rain) {
    uint64_t t_rain_start = time_get_ns();
    uint64_t current_time_ns = t_rain_start;
    float delta_time = (float)(current_time_ns - ctx->last_frame_time_ns) / (float)NS_PER_SEC_INT;
    ctx->last_frame_time_ns = current_time_ns;
 
    char *rain_result = digital_rain_apply(ctx->digital_rain, result, delta_time);
    if (rain_result) {
      SAFE_FREE(result);
      result = rain_result;
    }
 
    uint64_t t_rain_end = time_get_ns();
    log_dev("DIGITAL_RAIN: Effect applied (%.2f ms)", (double)(t_rain_end - t_rain_start) / (double)NS_PER_MS_INT);
  }
 
  uint64_t t_cleanup_start = time_get_ns();
  // Clean up flipped image if created
  START_TIMER("ascii_convert_cleanup");
  if (flipped_image) {
    image_destroy(flipped_image);
  }
  STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 2 * NS_PER_MS_INT, "ascii_convert_cleanup",
                           "ASCII_CONVERT_CLEANUP: Cleanup complete (%.2f ms)");
  uint64_t t_cleanup_end = time_get_ns();
 
  // Log total breakdown with actual measured times
  log_dev("CONVERT_TIMING: flip=%llu us, filter=%llu us, convert=%llu us, cleanup=%llu us, TOTAL=%llu us",
          (t_flip_end - t_flip_start) / 1000, (t_filter_end - t_filter_start) / 1000,
          (t_convert_end - t_convert_start) / 1000, (t_cleanup_end - t_cleanup_start) / 1000,
          (t_cleanup_end - t_flip_start) / 1000);
 
  return result;
}

References ascii_convert_with_capabilities(), session_display_ctx::caps, session_display_ctx::digital_rain, digital_rain_apply(), image_destroy(), image_new(), session_display_ctx::initialized, session_display_ctx::last_frame_time_ns, session_display_ctx::palette_chars, rainbow_replace_ansi_colors(), and time_get_ns().

Referenced by session_render_loop().

session_display_create()

session_display_ctx_t * session_display_create

(

const session_display_config_t *

config

)

Definition at line 121 of file lib/session/display.c.

                                                                                      {
  // Auto-create config from command-line options if NULL
  session_display_config_t auto_config = {0};
  if (!config) {
    auto_config.snapshot_mode = GET_OPTION(snapshot_mode);
    auto_config.palette_type = GET_OPTION(palette_type);
    auto_config.custom_palette = GET_OPTION(palette_custom_set) ? GET_OPTION(palette_custom) : NULL;
    auto_config.color_mode = TERM_COLOR_AUTO;
    config = &auto_config;
  }
 
  // Check if we should exit before starting initialization
  if (config->should_exit_callback && config->should_exit_callback(config->callback_data)) {
    return NULL;
  }
 
  // Allocate context
  session_display_ctx_t *ctx = SAFE_CALLOC(1, sizeof(session_display_ctx_t), session_display_ctx_t *);
 
  // Store configuration
  ctx->snapshot_mode = config->snapshot_mode;
  ctx->palette_type = config->palette_type;
  ctx->audio_playback_enabled = config->enable_audio_playback;
  ctx->audio_ctx = config->audio_ctx;
  atomic_init(&ctx->first_frame, true);
  atomic_init(&ctx->help_screen_active, false);
 
  // Get TTY info for direct terminal access
  ctx->tty_info = get_current_tty();
 
  // Determine if we have a valid TTY
  // Check if stdout is a TTY, not just any fd (stdin/stderr could be TTY while stdout is piped).
  // If stdout is piped/redirected, never perform terminal operations regardless of other fds.
  if (ctx->tty_info.fd >= 0) {
    ctx->has_tty = (platform_isatty(ctx->tty_info.fd) != 0) && terminal_is_stdout_tty();
  }
 
  // In piped mode, force all logs to stderr to prevent frame data corruption
  if (terminal_should_force_stderr()) {
    log_set_force_stderr(true);
    // Set stdout to line buffering to ensure output is flushed at newlines
    // This helps with snapshot mode where each frame ends with a newline
    //(void)setvbuf(stdout, NULL, _IOLBF, 0);
  }
 
  // Detect terminal capabilities
  ctx->caps = detect_terminal_capabilities();
 
  // Set wants_padding based on snapshot mode and TTY status
  // Disable padding when:
  // - In snapshot mode (one frame and exit)
  // - When stdout is not a TTY (piped/redirected output)
  // Enable padding for interactive terminal sessions
  bool is_snapshot_mode = config->snapshot_mode;
  bool is_interactive = terminal_is_interactive();
  ctx->caps.wants_padding = is_interactive && !is_snapshot_mode;
 
  log_debug("Padding mode: wants_padding=%d (snapshot=%d, interactive=%d, stdin_tty=%d, stdout_tty=%d)",
            ctx->caps.wants_padding, is_snapshot_mode, is_interactive, terminal_is_stdin_tty(),
            terminal_is_stdout_tty());
 
  // Apply color mode override if specified
  if (config->color_mode != TERM_COLOR_AUTO) {
    ctx->caps.color_level = config->color_mode;
  }
 
  // Apply command-line overrides
  ctx->caps = apply_color_mode_override(ctx->caps);
 
  // Initialize palette
  int palette_result = initialize_client_palette(config->palette_type, config->custom_palette, ctx->palette_chars,
                                                 &ctx->palette_len, ctx->luminance_palette);
  if (palette_result != ASCIICHAT_OK) {
    log_warn("Failed to initialize palette, using default");
    // Fall back to standard palette
    (void)initialize_client_palette(PALETTE_STANDARD, NULL, ctx->palette_chars, &ctx->palette_len,
                                    ctx->luminance_palette);
  }
 
  // Pre-warm UTF-8 palette cache during initialization (not during rendering)
  // This is expensive on first use (creates lookup tables), so warm it up now to avoid frame lag
  // This function is imported from lib/video/simd/common.h
  extern utf8_palette_cache_t *get_utf8_palette_cache(const char *ascii_chars);
  (void)get_utf8_palette_cache((const char *)ctx->palette_chars);
  log_debug("UTF-8 palette cache pre-warmed during display initialization");
 
  // Initialize ANSI fast lookup tables based on terminal capabilities
  if (ctx->caps.color_level == TERM_COLOR_TRUECOLOR) {
    ansi_fast_init();
  } else if (ctx->caps.color_level == TERM_COLOR_256) {
    ansi_fast_init_256color();
  } else if (ctx->caps.color_level == TERM_COLOR_16) {
    ansi_fast_init_16color();
  }
  // TERM_COLOR_MONO requires no init
 
  // Initialize ASCII output system if we have a TTY
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    ascii_write_init(ctx->tty_info.fd, false);
  }
 
  // Initialize digital rain effect if enabled
  if (GET_OPTION(matrix_rain)) {
    // Get terminal dimensions for grid size
    unsigned short int width_us = (unsigned short int)GET_OPTION(width);
    unsigned short int height_us = (unsigned short int)GET_OPTION(height);
 
    // If dimensions are not set, detect from terminal
    if (width_us == 0 || height_us == 0) {
      (void)get_terminal_size(&width_us, &height_us);
    }
 
    int width = (int)width_us;
    int height = (int)height_us;
 
    ctx->digital_rain = digital_rain_init(width, height);
    if (ctx->digital_rain) {
      // Set color from color filter if active
      color_filter_t filter = GET_OPTION(color_filter);
      digital_rain_set_color_from_filter(ctx->digital_rain, filter);
      log_info("Digital rain effect enabled: %dx%d grid", width, height);
    } else {
      log_warn("Failed to initialize digital rain effect");
    }
    ctx->last_frame_time_ns = time_get_ns();
  }
 
  ctx->initialized = true;
  return ctx;
}

References ansi_fast_init(), ansi_fast_init_16color(), ansi_fast_init_256color(), ascii_write_init(), session_display_ctx::audio_ctx, session_display_ctx::audio_playback_enabled, session_display_ctx::caps, detect_terminal_capabilities(), session_display_ctx::digital_rain, digital_rain_init(), digital_rain_set_color_from_filter(), session_display_ctx::first_frame, get_terminal_size(), get_utf8_palette_cache(), session_display_ctx::has_tty, session_display_ctx::help_screen_active, initialize_client_palette(), session_display_ctx::initialized, session_display_ctx::last_frame_time_ns, log_set_force_stderr(), session_display_ctx::luminance_palette, session_display_ctx::palette_chars, session_display_ctx::palette_len, session_display_ctx::palette_type, platform_isatty(), session_display_ctx::snapshot_mode, terminal_is_interactive(), terminal_is_stdin_tty(), terminal_is_stdout_tty(), terminal_should_force_stderr(), time_get_ns(), and session_display_ctx::tty_info.

Referenced by display_init(), and session_client_like_run().

session_display_cursor_home()

void session_display_cursor_home

(

session_display_ctx_t *

ctx

)

Definition at line 689 of file lib/session/display.c.

                                                             {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL or uninitialized");
    return;
  }
 
  int fd = ctx->has_tty ? ctx->tty_info.fd : STDOUT_FILENO;
  if (fd >= 0) {
    (void)terminal_cursor_home(fd);
  }
}

References session_display_ctx::has_tty, session_display_ctx::initialized, and session_display_ctx::tty_info.

session_display_destroy()

void session_display_destroy

(

session_display_ctx_t *

ctx

)

Definition at line 252 of file lib/session/display.c.

                                                         {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return;
  }
 
  // Cleanup ASCII rendering if we had a TTY
  // Don't reset terminal in snapshot mode to preserve the rendered output
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    ascii_write_destroy(ctx->tty_info.fd, !ctx->snapshot_mode);
  }
 
  // Close the controlling terminal if we opened it
  if (ctx->tty_info.owns_fd && ctx->tty_info.fd >= 0) {
    (void)platform_close(ctx->tty_info.fd);
    ctx->tty_info.fd = -1;
    ctx->tty_info.owns_fd = false;
  }
 
  // Cleanup digital rain effect
  if (ctx->digital_rain) {
    digital_rain_destroy(ctx->digital_rain);
    ctx->digital_rain = NULL;
  }
 
  ctx->initialized = false;
  SAFE_FREE(ctx);
}

References ascii_write_destroy(), session_display_ctx::digital_rain, digital_rain_destroy(), session_display_ctx::has_tty, session_display_ctx::initialized, platform_close(), session_display_ctx::snapshot_mode, and session_display_ctx::tty_info.

Referenced by session_client_like_run().

session_display_get_caps()

const terminal_capabilities_t * session_display_get_caps

(

session_display_ctx_t *

ctx

)

Definition at line 293 of file lib/session/display.c.

                                                                                    {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return &ctx->caps;
}

References session_display_ctx::caps, and session_display_ctx::initialized.

session_display_get_luminance_palette()

const char * session_display_get_luminance_palette

(

session_display_ctx_t *

ctx

)

Definition at line 317 of file lib/session/display.c.

                                                                              {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return ctx->luminance_palette;
}

References session_display_ctx::initialized, and session_display_ctx::luminance_palette.

session_display_get_palette_chars()

const char * session_display_get_palette_chars

(

session_display_ctx_t *

ctx

)

Definition at line 301 of file lib/session/display.c.

                                                                          {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return ctx->palette_chars;
}

References session_display_ctx::initialized, and session_display_ctx::palette_chars.

session_display_get_palette_len()

size_t session_display_get_palette_len

(

session_display_ctx_t *

ctx

)

Definition at line 309 of file lib/session/display.c.

                                                                   {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return 0;
  }
  return ctx->palette_len;
}

References session_display_ctx::initialized, and session_display_ctx::palette_len.

session_display_get_tty_fd()

int session_display_get_tty_fd

(

session_display_ctx_t *

ctx

)

Definition at line 325 of file lib/session/display.c.

                                                           {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return -1;
  }
  return ctx->tty_info.fd;
}

References session_display_ctx::initialized, and session_display_ctx::tty_info.

Referenced by session_display_render_help().

session_display_has_audio_playback()

bool session_display_has_audio_playback

(

session_display_ctx_t *

ctx

)

Definition at line 713 of file lib/session/display.c.

                                                                    {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL or uninitialized");
    return false;
  }
  return ctx->audio_playback_enabled;
}

References session_display_ctx::audio_playback_enabled, and session_display_ctx::initialized.

session_display_has_tty()

bool session_display_has_tty

(

session_display_ctx_t *

ctx

)

Definition at line 285 of file lib/session/display.c.

                                                         {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return false;
  }
  return ctx->has_tty;
}

References session_display_ctx::has_tty, and session_display_ctx::initialized.

Referenced by display_has_tty(), and session_display_render_help().

session_display_is_help_active()

bool session_display_is_help_active

(

session_display_ctx_t *

ctx

)

Check if help screen is currently active (implemented in display.c for struct access)

Definition at line 792 of file lib/session/display.c.

                                                                {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return false;
  }
 
  return atomic_load(&ctx->help_screen_active);
}

References session_display_ctx::help_screen_active.

Referenced by display_render_frame(), session_handle_keyboard_input(), and session_render_loop().

session_display_render_frame()

void session_display_render_frame	(	session_display_ctx_t *	ctx,
		const char *	frame_data
	)

Definition at line 511 of file lib/session/display.c.

                                                                                      {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Display context is NULL or uninitialized");
    return;
  }
 
  if (!frame_data) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Frame data is NULL");
    return;
  }
 
  // Suppress frame rendering when help screen is active
  // Network reception continues in background, frames are just not displayed
  if (atomic_load(&ctx->help_screen_active)) {
    return;
  }
 
  // Calculate frame length
  size_t frame_len = strnlen(frame_data, 1024 * 1024); // Max 1MB frame
  if (frame_len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Frame data is empty");
    return;
  }
 
  // Debug: check for lines that might shoot off to the right
  // Find longest line in frame data (visible characters between newlines, excluding ANSI codes)
  size_t max_line_chars = 0;
  size_t current_line_chars = 0;
  bool in_ansi_code = false;
 
  for (size_t i = 0; i < frame_len; i++) {
    char c = frame_data[i];
 
    if (c == '\033') {
      // Start of ANSI escape sequence
      in_ansi_code = true;
    } else if (in_ansi_code && c == 'm') {
      // End of ANSI escape sequence
      in_ansi_code = false;
    } else if (!in_ansi_code && c == '\n') {
      // End of line
      if (current_line_chars > max_line_chars) {
        max_line_chars = current_line_chars;
      }
      current_line_chars = 0;
    } else if (!in_ansi_code) {
      // Regular character (not ANSI code)
      current_line_chars++;
    }
  }
 
  if (current_line_chars > 0) {
    if (current_line_chars > max_line_chars) {
      max_line_chars = current_line_chars;
    }
  }
 
  unsigned short int term_width = GET_OPTION(width);
  if (max_line_chars > term_width) {
    log_warn("FRAME_ANALYSIS: Line %zu chars exceeds terminal width %u - this may cause wrapping!", max_line_chars,
             term_width);
  }
 
  // Handle first frame - perform initial terminal reset only
  if (atomic_load(&ctx->first_frame)) {
    atomic_store(&ctx->first_frame, false);
 
    // NOTE: log_set_terminal_output(false) skipped here to avoid deadlocks with audio worker threads
    // Terminal logging will continue during rendering but won't corrupt the final frame
 
    // Perform initial terminal reset
    if (ctx->has_tty) {
      full_terminal_reset_internal(ctx->snapshot_mode);
    }
  }
 
  // Output routing logic:
  // - TTY mode: always render with cursor control (including snapshot mode for animation)
  // - Snapshot mode on non-TTY: render only final frame WITHOUT cursor control
  // - Piped mode: render every frame WITHOUT cursor control (allows continuous output to files)
  bool use_tty_control = ctx->has_tty;
 
  START_TIMER("frame_write");
  if (use_tty_control) {
    // TTY mode: just reset cursor to home and redraw frame without clearing
    // This avoids flashing at high framerates and is more efficient than clearing
    (void)terminal_cursor_home(STDOUT_FILENO);
    // Send frame data (overwrites previous frame from cursor position)
    (void)platform_write_all(STDOUT_FILENO, frame_data, frame_len);
    (void)terminal_flush(STDOUT_FILENO);
  } else if (terminal_is_interactive()) {
    // Piped to an interactive terminal: output ASCII frames
    // Combine frame and newline into single write call
    // Allocate temporary buffer for frame + newline to minimize syscalls
    char *write_buf = SAFE_MALLOC(frame_len + 1, char *);
    if (write_buf) {
      memcpy(write_buf, frame_data, frame_len);
      write_buf[frame_len] = '\n';
 
      // Use thread-safe console lock for proper synchronization
      bool prev_lock_state = log_lock_terminal();
      (void)platform_write_all(STDOUT_FILENO, write_buf, frame_len + 1);
      log_unlock_terminal(prev_lock_state);
 
      SAFE_FREE(write_buf);
    } else {
      // Fallback: two writes if allocation fails
      (void)platform_write_all(STDOUT_FILENO, frame_data, frame_len);
      bool prev_lock_state = log_lock_terminal();
      const char newline = '\n';
      (void)platform_write_all(STDOUT_FILENO, &newline, 1);
      log_unlock_terminal(prev_lock_state);
    }
 
    // Flush kernel write buffer so piped data appears immediately to readers
    (void)terminal_flush(STDOUT_FILENO);
  }
  STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 5 * NS_PER_MS_INT, "frame_write",
                           "FRAME_WRITE: Write and flush complete (%.2f ms)");
}

References session_display_ctx::first_frame, session_display_ctx::has_tty, session_display_ctx::help_screen_active, session_display_ctx::initialized, log_lock_terminal(), log_unlock_terminal(), platform_write_all(), session_display_ctx::snapshot_mode, terminal_flush(), and terminal_is_interactive().

Referenced by display_render_frame(), and session_render_loop().

session_display_reset()

void session_display_reset

(

session_display_ctx_t *

ctx

)

Definition at line 652 of file lib/session/display.c.

                                                       {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL or uninitialized");
    return;
  }
 
  // Skip terminal reset in snapshot mode to preserve rendered output
  if (ctx->snapshot_mode) {
    return;
  }
 
  // Only perform terminal operations if we have a valid TTY
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    (void)terminal_reset(ctx->tty_info.fd);
    (void)terminal_hide_cursor(ctx->tty_info.fd, false); // Show cursor
    (void)terminal_flush(ctx->tty_info.fd);
  }
}

References session_display_ctx::has_tty, session_display_ctx::initialized, session_display_ctx::snapshot_mode, terminal_flush(), and session_display_ctx::tty_info.

Referenced by display_full_reset().

session_display_set_cursor_visible()

void session_display_set_cursor_visible	(	session_display_ctx_t *	ctx,
		bool	visible
	)

Definition at line 701 of file lib/session/display.c.

                                                                                  {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL or uninitialized");
    return;
  }
 
  // Only perform terminal operations when we have a valid TTY (not when piping)
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    (void)terminal_hide_cursor(ctx->tty_info.fd, !visible);
  }
}

References session_display_ctx::has_tty, session_display_ctx::initialized, and session_display_ctx::tty_info.

session_display_toggle_help()

void session_display_toggle_help

(

session_display_ctx_t *

ctx

)

Toggle help screen on/off (implemented in display.c for struct access)

Definition at line 779 of file lib/session/display.c.

                                                             {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return;
  }
 
  bool current = atomic_load(&ctx->help_screen_active);
  atomic_store(&ctx->help_screen_active, !current);
}

References session_display_ctx::help_screen_active.

Referenced by session_handle_keyboard_input().

session_display_write_audio()

asciichat_error_t session_display_write_audio	(	session_display_ctx_t *	ctx,
		const float *	buffer,
		size_t	num_samples
	)

Definition at line 721 of file lib/session/display.c.

                                                                                                                   {
  if (!ctx || !ctx->initialized || !buffer || num_samples == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%zu", ctx, buffer,
                     num_samples);
  }
 
  if (!ctx->audio_playback_enabled || !ctx->audio_ctx) {
    // Audio not enabled, but not an error - just skip silently
    return ASCIICHAT_OK;
  }
 
  // For mirror mode with local files: write samples directly without jitter buffering
  // The jitter buffer is designed for network scenarios with irregular packet arrivals
  // For local playback, we just want raw samples flowing to the speakers
  audio_context_t *audio_ctx = (audio_context_t *)ctx->audio_ctx;
  if (audio_ctx && audio_ctx->playback_buffer) {
    audio_ring_buffer_t *rb = audio_ctx->playback_buffer;
 
    // Simple direct write: append samples to ring buffer without network-oriented complexity
    uint32_t write_idx = atomic_load(&rb->write_index);
    uint32_t read_idx = atomic_load(&rb->read_index);
 
    // Calculate available space in ring buffer
    uint32_t available = (read_idx - write_idx - 1) & (AUDIO_RING_BUFFER_SIZE - 1);
 
    if ((uint32_t)num_samples > available) {
      // Buffer full - just skip this write to avoid distortion from overwriting old audio
      return ASCIICHAT_OK;
    }
 
    // Direct memcpy to ring buffer, handling wrap-around
    uint32_t space_before_wrap = AUDIO_RING_BUFFER_SIZE - write_idx;
    if ((uint32_t)num_samples <= space_before_wrap) {
      memcpy(&rb->data[write_idx], buffer, num_samples * sizeof(float));
    } else {
      // Split write: first part to end of buffer, second part wraps to beginning
      uint32_t first_part = space_before_wrap;
      uint32_t second_part = num_samples - first_part;
      memcpy(&rb->data[write_idx], buffer, first_part * sizeof(float));
      memcpy(&rb->data[0], &buffer[first_part], second_part * sizeof(float));
    }
 
    // Update write index atomically
    atomic_store(&rb->write_index, (write_idx + num_samples) % AUDIO_RING_BUFFER_SIZE);
 
    return ASCIICHAT_OK;
  }
 
  return ASCIICHAT_OK;
}

References session_display_ctx::audio_ctx, session_display_ctx::audio_playback_enabled, and session_display_ctx::initialized.

session_display_write_raw()

void session_display_write_raw	(	session_display_ctx_t *	ctx,
		const char *	data,
		size_t	len
	)

Definition at line 632 of file lib/session/display.c.

                                                                                         {
  if (!ctx || !ctx->initialized || !data || len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, data=%p, len=%zu", ctx, data, len);
    return;
  }
 
  int fd = -1;
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    fd = ctx->tty_info.fd;
  } else {
    fd = STDOUT_FILENO;
  }
 
  // Write all data with automatic retry on transient errors
  (void)platform_write_all(fd, data, len);
 
  // Flush immediately after write to TTY to ensure data is sent
  (void)terminal_flush(fd);
}

References session_display_ctx::has_tty, session_display_ctx::initialized, platform_write_all(), terminal_flush(), and session_display_ctx::tty_info.

Referenced by session_display_render_help().