Terminal Display

🖥️ Terminal rendering, TTY management, and frame output More...

Files
file	display.c
	💻 Client terminal display: TTY detection, frame rendering, and interactive/stdout output routing
file	display.h
	ascii-chat Client Display Management Interface

Functions
void	display_set_context (session_display_ctx_t *display_ctx)
	Set the display context created by session_client_like framework.
int	display_init ()
	Initialize what is necessary to display ascii frames.
bool	display_has_tty ()
	Check if display has TTY capability.
void	display_full_reset ()
	Perform full display reset.
void	display_reset_for_new_connection ()
	Reset display state for new connection.
void	display_disable_logging_for_first_frame ()
	Disable terminal logging for first frame.
void	display_render_frame (const char *frame_data)
	Render ASCII frame to display.
void	display_cleanup ()
	Cleanup display subsystem.

Detailed Description

🖥️ Terminal rendering, TTY management, and frame output

Terminal Display

Overview

The terminal display subsystem manages terminal initialization, ASCII frame rendering, TTY capability detection, and terminal cleanup.

Implementation: src/client/display.c, src/client/display.h

Initialization

int display_init(void)
{
  // Check if stdout is a TTY
  if (!isatty(STDOUT_FILENO)) {
    log_warn("stdout is not a TTY - frames may not render correctly");
    g_has_tty = false;
    return 0;
  }
 
  g_has_tty = true;
 
  // Initialize TTY for raw mode
  if (tty_init(&g_tty_info) != 0) {
    log_error("Failed to initialize TTY");
    return -1;
  }
 
  return 0;
}

Frame Rendering

void display_render_frame(const char *frame_data, bool is_snapshot_frame)
{
  // Disable logging for first frame to prevent corruption
  if (g_is_first_frame) {
    display_disable_logging_for_first_frame();
    g_is_first_frame = false;
  }
 
  if (g_has_tty) {
    // Clear screen and home cursor
    printf("\033[2J\033[H");
    fflush(stdout);
  }
 
  // Output frame data
  printf("%s", frame_data);
  fflush(stdout);
 
  // Snapshot mode: leave cursor at end
  if (!is_snapshot_frame && g_has_tty) {
    // Home cursor for next frame
    printf("\033[H");
    fflush(stdout);
  }
}

First Frame Optimization

Problem: Log messages corrupt first frame display

Solution:

• Suppress terminal logging before first frame render
• Re-enable logging after first frame displayed
• Prevents log messages from appearing in frame area

void display_disable_logging_for_first_frame(void)
{
  // Temporarily disable terminal logging
  logging_set_terminal_enabled(false);
 
  // Will be re-enabled after first frame
}

Display Reset

Full Reset

void display_full_reset(void)
{
  if (g_has_tty) {
    printf("\033[2J\033[H");  // Clear screen and home cursor
    fflush(stdout);
  }
}

Connection Reset

void display_reset_for_new_connection(void)
{
  // Reset first frame flag for reconnection
  g_is_first_frame = true;
}

Cleanup

void display_cleanup(void)
{
  if (g_has_tty) {
    // Restore terminal settings
    tty_restore(&g_tty_info);
 
    // Clear screen and show cursor
    printf("\033[2J\033[H\033[?25h");
    fflush(stdout);
  }
}

See also

src/client/display.c

src/client/display.h

lib/platform/terminal.h

Client Overview

Function Documentation

display_cleanup()

void display_cleanup

(

)

#include <display.c>

Cleanup display subsystem.

Destroys session display context and releases all resources including keyboard input handling.

Definition at line 362 of file src/client/display.c.

                       {
  // Cleanup keyboard input if it was initialized
  if (g_keyboard_enabled) {
    keyboard_destroy();
    g_keyboard_enabled = false;
  }
 
  // Cleanup optional local media capture context if it was created
  if (g_display_capture_ctx) {
    session_capture_destroy(g_display_capture_ctx);
    g_display_capture_ctx = NULL;
  }
 
  // Display context is now managed by session_client_like framework
  // Do not destroy it here - the framework will handle cleanup
  g_display_ctx = NULL;
}

References session_capture_destroy().

display_disable_logging_for_first_frame()

void display_disable_logging_for_first_frame

(

)

#include <display.c>

Disable terminal logging for first frame.

Disables terminal logging before clearing the display for the first frame to prevent log output from interfering with ASCII display.

Call this before clearing the display for the first frame to prevent log output from interfering with ASCII display.

Definition at line 292 of file src/client/display.c.

                                               {
  // Disable terminal logging before clearing display and rendering first frame
  if (atomic_load(&g_is_first_frame_of_connection)) {
    log_set_terminal_output(false);
    atomic_store(&g_is_first_frame_of_connection, false);
 
    // Signal the intro splash screen to stop - first frame is ready to render
    splash_intro_done();
  }
}

References log_set_terminal_output(), and splash_intro_done().

Referenced by display_render_frame().

display_full_reset()

void display_full_reset

(

)

#include <display.c>

Perform full display reset.

Executes complete terminal reset sequence for clean display state. Safe to call multiple times and handles mode-specific behavior.

Definition at line 266 of file src/client/display.c.

                          {
  if (g_display_ctx && !should_exit()) {
    session_display_reset(g_display_ctx);
  }
}

References session_display_reset(), and should_exit().

Referenced by server_connection_lost().

display_has_tty()

bool display_has_tty

(

)

#include <display.c>

Check if display has TTY capability.

Returns

true if TTY is available for interactive output, false otherwise

true if TTY available, false otherwise

Definition at line 254 of file src/client/display.c.

                       {
  return session_display_has_tty(g_display_ctx);
}

References session_display_has_tty().

display_init()

int display_init

(

)

#include <display.c>

Initialize what is necessary to display ascii frames.

Initialize display subsystem.

Creates session display context for TTY management and frame rendering. Must be called once during client startup.

Returns

0 on success, negative on error

0 on success, negative on error

Definition at line 180 of file src/client/display.c.

                   {
  // Build display configuration from options
  session_display_config_t config = {
      .snapshot_mode = GET_OPTION(snapshot_mode),
      .palette_type = GET_OPTION(palette_type),
      .custom_palette = GET_OPTION(palette_custom_set) ? GET_OPTION(palette_custom) : NULL,
      .color_mode = TERM_COLOR_AUTO // Will be overridden by command-line options
  };
 
  // Create display context using session library
  g_display_ctx = session_display_create(&config);
  if (!g_display_ctx) {
    SET_ERRNO(ERROR_DISPLAY, "Failed to initialize display");
    return -1;
  }
 
  // Check if client mode should load local media (--file or --url)
  const char *media_url = GET_OPTION(media_url);
  const char *media_file = GET_OPTION(media_file);
 
  if ((media_url && strlen(media_url) > 0) || (media_file && strlen(media_file) > 0)) {
    // Client mode with local media file/URL - create capture context for keyboard controls
    session_capture_config_t capture_config = {0};
    capture_config.target_fps = 60;
    capture_config.resize_for_network = false;
    capture_config.should_exit_callback = NULL;
    capture_config.callback_data = NULL;
 
    if (media_url && strlen(media_url) > 0) {
      capture_config.type = MEDIA_SOURCE_FILE;
      capture_config.path = media_url;
    } else {
      if (strcmp(media_file, "-") == 0) {
        capture_config.type = MEDIA_SOURCE_STDIN;
        capture_config.path = NULL;
      } else {
        capture_config.type = MEDIA_SOURCE_FILE;
        capture_config.path = media_file;
      }
    }
 
    capture_config.loop = GET_OPTION(media_loop);
    capture_config.initial_seek_timestamp = GET_OPTION(media_seek_timestamp);
 
    g_display_capture_ctx = session_capture_create(&capture_config);
    if (!g_display_capture_ctx) {
      log_warn("Failed to create capture context for local media - keyboard seek/pause disabled");
      g_display_capture_ctx = NULL;
    }
  }
 
  // Initialize keyboard input for interactive controls (volume, color mode, flip, seek, pause)
  // Only initialize in TTY mode to avoid interfering with piped/redirected I/O
  if (terminal_is_stdin_tty()) {
    asciichat_error_t kb_result = keyboard_init();
    if (kb_result == ASCIICHAT_OK) {
      g_keyboard_enabled = true;
    } else {
      // Non-fatal: client can work without keyboard support
      log_warn("Failed to initialize keyboard input: %s", asciichat_error_string(kb_result));
      g_keyboard_enabled = false;
    }
  }
 
  return 0;
}

References session_capture_create(), session_display_create(), session_display_ctx::snapshot_mode, and terminal_is_stdin_tty().

display_render_frame()

void display_render_frame

(

const char *

frame_data

)

#include <display.c>

Render ASCII frame to display.

Render ASCII frame to display

Uses session display library for frame output routing based on display mode and snapshot requirements. Also polls for keyboard input for interactive controls (volume, color mode, flip).

Parameters

frame_data	ASCII frame data to render
is_snapshot_frame	Whether this is the final snapshot frame
frame_data	ASCII frame data to render

Definition at line 315 of file src/client/display.c.

                                                  {
  if (!frame_data) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Attempted to render NULL frame data");
    return;
  }
 
  // Stop splash screen animation on first frame
  // This must be called BEFORE any frame rendering to prevent splash/frame flickering
  display_disable_logging_for_first_frame();
 
  // Render help screen if active (suppresses frame rendering)
  if (session_display_is_help_active(g_display_ctx)) {
    session_display_render_help(g_display_ctx);
 
    // Still poll keyboard for interactive controls while help is visible
    if (g_keyboard_enabled) {
      keyboard_key_t key = keyboard_read_nonblocking();
      if (key != KEY_NONE) {
        session_handle_keyboard_input(g_display_capture_ctx, g_display_ctx, key);
      }
    }
    return; // Skip normal frame rendering
  }
 
  // Use session display library for frame rendering
  session_display_render_frame(g_display_ctx, frame_data);
 
  // Poll for keyboard input and handle interactive controls
  // - If client mode has local media (--file/--url), pass capture context for full controls
  //   (seek, pause, play, volume, color mode, flip)
  // - If client mode is network-only, pass NULL (volume, color mode, flip work; seek/pause ignored)
  if (g_keyboard_enabled) {
    keyboard_key_t key = keyboard_read_nonblocking();
    if (key != KEY_NONE) {
      session_handle_keyboard_input(g_display_capture_ctx, g_display_ctx, key);
    }
  }
}

References display_disable_logging_for_first_frame(), session_display_is_help_active(), session_display_render_frame(), session_display_render_help(), and session_handle_keyboard_input().

display_reset_for_new_connection()

void display_reset_for_new_connection

(

)

#include <display.c>

Reset display state for new connection.

Resets the first frame tracking flag to prepare for a new connection. Call this when starting a new connection to reset first frame tracking.

Call this when starting a new connection to reset first frame tracking.

Definition at line 280 of file src/client/display.c.

                                        {
  atomic_store(&g_is_first_frame_of_connection, true);
}

Referenced by protocol_start_connection().

display_set_context()

void display_set_context

(

session_display_ctx_t *

display_ctx

)

#include <display.c>

Set the display context created by session_client_like framework.

Set the display context (framework integration)

Client mode doesn't create its own display context anymore. Instead, session_client_like_run() creates it and passes it to client_run(). This setter allows client_run() to make the framework-created context available to protocol threads that need to render frames.

Parameters

display_ctx

Display context created by framework (may be NULL)

Called by client_run() to pass the display context created by session_client_like_run() to the display module so protocol threads can render frames.

Parameters

display_ctx

Display context from framework (may be NULL)

Definition at line 162 of file src/client/display.c.

                                                             {
  g_display_ctx = display_ctx;
}