frame_buffer.h File Reference

Buffered terminal frame rendering. More...

Go to the source code of this file.

Typedefs
typedef struct frame_buffer	frame_buffer_t
	Opaque frame buffer handle.

Functions
frame_buffer_t *	frame_buffer_create (int rows, int cols)
	Create a new frame buffer.
void	frame_buffer_destroy (frame_buffer_t *buf)
	Destroy a frame buffer.
void	frame_buffer_reset (frame_buffer_t *buf)
	Clear buffer contents while keeping allocation.
void	frame_buffer_append (frame_buffer_t *buf, const char *str, size_t len)
	Append raw bytes to the buffer.
void	frame_buffer_printf (frame_buffer_t *buf, const char *fmt,...)
	Printf-style append to the buffer.
void	frame_buffer_cursor_home (frame_buffer_t *buf)
	Append cursor home escape code (\033[H).
void	frame_buffer_clear_screen (frame_buffer_t *buf)
	Append clear screen and home escape codes (\033[2J\033[H).
void	frame_buffer_flush (frame_buffer_t *buf)
	Flush the entire buffer to stdout in one atomic write.
size_t	frame_buffer_get_length (const frame_buffer_t *buf)
	Get the current content length of the frame buffer.
const char *	frame_buffer_get_content (const frame_buffer_t *buf)
	Get a pointer to the buffer content.
void	frame_buffer_render_border (frame_buffer_t *buf, int cols, const char *color)
	Render a horizontal border line (used by both splash and status screens).
void	frame_buffer_render_divider (frame_buffer_t *buf, int width, bool use_utf8, bool use_colors)
int	frame_buffer_render_centered (frame_buffer_t *buf, const char *text, int cols)
	Render centered text (used by both splash and status screens).
void	frame_buffer_set_screen_output_fd (int fd)
	Set output file descriptor for terminal screen (splash/status) rendering.
int	frame_buffer_get_screen_output_fd (void)
	Get current output file descriptor for terminal screens.

Detailed Description

Buffered terminal frame rendering.

Accumulates terminal output (ANSI codes, text, colors) into a single buffer, then flushes the entire frame in one atomic write. This eliminates the flicker that occurs when clearing the screen and rendering line-by-line.

Usage pattern: frame_buffer_t *buf = frame_buffer_create(rows, cols); frame_buffer_clear_screen(buf); frame_buffer_printf(buf, "Header line 1\n"); frame_buffer_printf(buf, "Header line 2\n"); frame_buffer_flush(buf); // Later, reuse the buffer: frame_buffer_reset(buf); frame_buffer_printf(buf, "New content\n"); frame_buffer_flush(buf);

Definition in file frame_buffer.h.

Typedef Documentation

frame_buffer_t

typedef struct frame_buffer frame_buffer_t

Opaque frame buffer handle.

Definition at line 32 of file frame_buffer.h.

Function Documentation

frame_buffer_append()

void frame_buffer_append	(	frame_buffer_t *	buf,
		const char *	str,
		size_t	len )

Append raw bytes to the buffer.

Parameters

buf	Frame buffer
str	Pointer to data (may contain ANSI codes, not NULL-terminated)
len	Number of bytes to append

Grows the buffer as needed. Does not add newlines or NULL terminators.

Definition at line 80 of file frame_buffer.c.

                                                                           {
  if (!buf || !str || len == 0) {
    return;
  }
 
  // Grow buffer if needed
  if (buf->len + len > buf->capacity) {
    size_t new_capacity = buf->capacity * 2;
    while (new_capacity < buf->len + len) {
      new_capacity *= 2;
    }
 
    char *new_data = SAFE_MALLOC(new_capacity, char *);
    if (!new_data) {
      return; // Failed to grow, silently ignore
    }
 
    if (buf->len > 0 && buf->data) {
      memcpy(new_data, buf->data, buf->len);
    }
 
    SAFE_FREE(buf->data);
    buf->data = new_data;
    buf->capacity = new_capacity;
  }
 
  // Append the data
  memcpy(buf->data + buf->len, str, len);
  buf->len += len;
}

References frame_buffer::capacity, frame_buffer::data, frame_buffer::len, SAFE_FREE, and SAFE_MALLOC.

Referenced by ascii_create_grid(), frame_buffer_clear_screen(), frame_buffer_cursor_home(), terminal_screen_compose(), ui_controller_write(), ui_error_popup_preserve(), ui_error_popup_render(), ui_input_render(), ui_media_panel_render(), ui_notice_flush_snapshot(), ui_notice_present(), ui_notice_render(), ui_scrollbar_render(), ui_session_media(), ui_session_render(), ui_text_render_values(), and ui_too_small_render().

frame_buffer_clear_screen()

void frame_buffer_clear_screen

(

frame_buffer_t *

buf

)

Append clear screen and home escape codes (\033[2J\033[H).

Parameters

buf	Frame buffer

Combines clear screen and cursor home into a single operation for atomicity.

Definition at line 157 of file frame_buffer.c.

                                                    {
  if (!buf) {
    return;
  }
 
  // Combine clear screen and home in one operation
  static const char clear[] = "\033[2J\033[H";
  frame_buffer_append(buf, clear, sizeof(clear) - 1);
}

References frame_buffer_append().

Referenced by ui_session_render().

frame_buffer_create()

frame_buffer_t * frame_buffer_create	(	int	rows,
		int	cols )

Create a new frame buffer.

Parameters

rows	Terminal row count (used for initial capacity estimate)
cols	Terminal column count (used for initial capacity estimate)

Returns

Newly allocated frame buffer, or NULL on allocation failure

Initial capacity is set to rows * cols * 16 to account for ANSI escape overhead.

Definition at line 42 of file frame_buffer.c.

                                                        {
  frame_buffer_t *buf = SAFE_MALLOC(sizeof(frame_buffer_t), frame_buffer_t *);
  if (!buf) {
    return NULL;
  }
 
  // Initial capacity: rows * cols * 16 to account for ANSI codes
  size_t initial_capacity = (rows > 0 && cols > 0) ? (size_t)rows * cols * 16 : 4096;
 
  buf->data = SAFE_MALLOC(initial_capacity, char *);
  if (!buf->data) {
    SAFE_FREE(buf);
    return NULL;
  }
 
  buf->len = 0;
  buf->capacity = initial_capacity;
 
  return buf;
}

References frame_buffer::capacity, frame_buffer::data, frame_buffer::len, SAFE_FREE, and SAFE_MALLOC.

Referenced by ascii_create_grid(), terminal_screen_compose(), tui_stats_render(), ui_error_popup_preserve(), ui_notice_flush_snapshot(), ui_notice_present(), ui_session_context_help_render(), ui_session_create(), and ui_session_help_render().

frame_buffer_cursor_home()

void frame_buffer_cursor_home

(

frame_buffer_t *

buf

)

Append cursor home escape code (\033[H).

Parameters

buf	Frame buffer

Definition at line 149 of file frame_buffer.c.

                                                   {
  if (!buf) {
    return;
  }
 
  frame_buffer_append(buf, "\033[H", 3);
}

References frame_buffer_append().

Referenced by tui_stats_render().

frame_buffer_destroy()

void frame_buffer_destroy

(

frame_buffer_t *

buf

)

Destroy a frame buffer.

Parameters

buf	Frame buffer to destroy (may be NULL)

Definition at line 63 of file frame_buffer.c.

                                               {
  if (!buf) {
    return;
  }
 
  SAFE_FREE(buf->data);
  SAFE_FREE(buf);
}

References frame_buffer::data, and SAFE_FREE.

Referenced by ascii_create_grid(), terminal_screen_compose(), tui_stats_render(), ui_error_popup_preserve(), ui_notice_flush_snapshot(), ui_notice_present(), ui_session_context_help_render(), ui_session_destroy(), and ui_session_help_render().

frame_buffer_flush()

void frame_buffer_flush

(

frame_buffer_t *

buf

)

Flush the entire buffer to stdout in one atomic write.

Parameters

buf	Frame buffer

Writes all accumulated content to stdout via platform_write_all(), bypassing libc buffering. Safe for high-frequency rendering.

Definition at line 170 of file frame_buffer.c.

                                             {
  if (!buf || buf->len == 0 || !buf->data) {
    return;
  }
 
  // Repaint from the top while erasing each line before writing it. A full
  // screen erase on every animation frame exposes a black frame on Windows
  // terminals and makes the splash appear to flicker.
  size_t line_count = 1;
  for (size_t i = 0; i < buf->len; i++) {
    if (buf->data[i] == '\n') {
      line_count++;
    }
  }
 
  size_t output_size = 3 + buf->len + (line_count * 4);
  char *output = SAFE_MALLOC(output_size, char *);
  if (!output) {
    return;
  }
 
  size_t output_len = 0;
  memcpy(output + output_len, "\033[H", 3);
  output_len += 3;
  bool at_line_start = true;
  for (size_t i = 0; i < buf->len; i++) {
    if (at_line_start) {
      memcpy(output + output_len, "\033[2K", 4);
      output_len += 4;
      at_line_start = false;
    }
    output[output_len++] = buf->data[i];
    if (buf->data[i] == '\n') {
      at_line_start = true;
    }
  }
 
  ui_output_write(g_terminal_screen_output_fd, output, output_len);
  SAFE_FREE(output);
}

References frame_buffer::data, frame_buffer::len, SAFE_FREE, SAFE_MALLOC, and ui_output_write().

frame_buffer_get_content()

const char * frame_buffer_get_content

(

const frame_buffer_t *

buf

)

Get a pointer to the buffer content.

Parameters

buf	Frame buffer

Returns

Pointer to the buffer data (NULL if buffer is empty or NULL)

Returns the raw buffer content for reading. The content is NOT null-terminated. Use frame_buffer_get_length() to get the actual size.

Definition at line 227 of file frame_buffer.c.

                                                                {
  if (!buf || !buf->data) {
    return NULL;
  }
  return buf->data;
}

References frame_buffer::data.

Referenced by ascii_create_grid(), terminal_screen_compose(), tui_stats_render(), ui_error_popup_preserve(), ui_notice_flush_snapshot(), ui_notice_present(), ui_session_context_help_render(), ui_session_help_render(), and ui_session_render().

frame_buffer_get_length()

size_t frame_buffer_get_length

(

const frame_buffer_t *

buf

)

Get the current content length of the frame buffer.

Parameters

buf	Frame buffer

Returns

Number of bytes currently in the buffer

Useful for debugging and verifying frame consistency.

Definition at line 220 of file frame_buffer.c.

                                                          {
  if (!buf) {
    return 0;
  }
  return buf->len;
}

References frame_buffer::len.

Referenced by ascii_create_grid(), terminal_screen_compose(), tui_stats_render(), ui_error_popup_preserve(), ui_notice_flush_snapshot(), ui_notice_present(), ui_session_context_help_render(), ui_session_frame_length(), ui_session_help_render(), and ui_session_tick().

frame_buffer_get_screen_output_fd()

int frame_buffer_get_screen_output_fd

(

void

)

Get current output file descriptor for terminal screens.

Returns

File descriptor (STDOUT_FILENO or STDERR_FILENO)

Definition at line 216 of file frame_buffer.c.

                                            {
  return g_terminal_screen_output_fd;
}

Referenced by ui_buttons_render(), ui_error_popup_render(), ui_media_panel_render(), and ui_status_render_header().

frame_buffer_printf()

void frame_buffer_printf	(	frame_buffer_t *	buf,
		const char *	fmt,
			... )

Printf-style append to the buffer.

Parameters

buf	Frame buffer
fmt	Format string (standard printf syntax)
...	Arguments

Formats the string into the buffer using snprintf. Grows buffer as needed.

Definition at line 111 of file frame_buffer.c.

                                                                    {
  if (!buf || !fmt) {
    return;
  }
 
  // Ensure we have space for a formatted string
  // Start with a reasonable buffer size
  size_t remaining = buf->capacity - buf->len;
  if (remaining < 256) {
    // Grow buffer to have at least 512 bytes of space
    size_t new_capacity = buf->capacity + 512;
    char *new_data = SAFE_MALLOC(new_capacity, char *);
    if (!new_data) {
      return;
    }
 
    if (buf->len > 0 && buf->data) {
      memcpy(new_data, buf->data, buf->len);
    }
 
    SAFE_FREE(buf->data);
    buf->data = new_data;
    buf->capacity = new_capacity;
    remaining = buf->capacity - buf->len;
  }
 
  // Format the string into the buffer
  va_list args;
  va_start(args, fmt);
  int written = vsnprintf(buf->data + buf->len, remaining, fmt, args);
  va_end(args);
 
  if (written > 0 && written < (int)remaining) {
    buf->len += (size_t)written;
  }
  // If vsnprintf failed or truncated, we silently ignore (buffer may be full)
}

References args, frame_buffer::capacity, frame_buffer::data, frame_buffer::len, SAFE_FREE, and SAFE_MALLOC.

Referenced by frame_buffer_render_centered(), invitation_render(), terminal_screen_compose(), tui_stats_render(), ui_buttons_render(), ui_error_popup_preserve(), ui_error_popup_render(), ui_input_render(), ui_media_panel_render(), ui_notice_render(), ui_popup_frame(), ui_popup_frame_titled(), ui_popup_render(), ui_popup_rule(), ui_scrollbar_render(), ui_session_render(), ui_session_splash_render(), ui_spinner_render(), ui_status_render_header(), and ui_table_render().

frame_buffer_render_border()

void frame_buffer_render_border	(	frame_buffer_t *	buf,
		int	cols,
		const char *	color )

Render a horizontal border line (used by both splash and status screens).

Parameters

buf	Frame buffer to write into
cols	Terminal width (number of columns)
color	ANSI color code (e.g., "\033[1;36m" for cyan) or NULL for no color

Definition at line 246 of file frame_buffer.c.

                                                                                  {
  render_rule(buf, cols - 1, color, terminal_should_use_utf8(GET_OPTION(force_utf8)));
}

References GET_OPTION.

Referenced by tui_stats_render().

frame_buffer_render_centered()

int frame_buffer_render_centered	(	frame_buffer_t *	buf,
		const char *	text,
		int	cols )

Render centered text (used by both splash and status screens).

Parameters

buf	Frame buffer to write into
text	Text to center (may contain ANSI codes)
cols	Terminal width

Returns

Padding added on left side (for manual padding if needed)

Automatically centers the text accounting for ANSI escape codes.

Definition at line 254 of file frame_buffer.c.

                                                                                  {
  if (!buf || !text || cols <= 0) {
    return 0;
  }
 
  // Calculate visible width accounting for ANSI codes
  int visible_width = display_width(text);
  if (visible_width < 0) {
    visible_width = (int)strlen(text);
  }
 
  int padding = (cols - visible_width) / 2;
  if (padding < 0) {
    padding = 0;
  }
 
  for (int i = 0; i < padding; i++) {
    frame_buffer_printf(buf, " ");
  }
  frame_buffer_printf(buf, "%s\n", text);
 
  return padding;
}

References display_width(), and frame_buffer_printf().

frame_buffer_render_divider()

void frame_buffer_render_divider	(	frame_buffer_t *	buf,
		int	width,
		bool	use_utf8,
		bool	use_colors )

Theme-blue divider of exactly width cells, followed by a newline.

Definition at line 250 of file frame_buffer.c.

                                                                                                 {
  render_rule(buf, width, use_colors ? ui_text_color_prefix(LOG_COLOR_DEBUG) : NULL, use_utf8);
}

References LOG_COLOR_DEBUG, ui_text_color_prefix(), and width.

Referenced by ui_session_splash_render(), and ui_status_render_header().

frame_buffer_reset()

void frame_buffer_reset

(

frame_buffer_t *

buf

)

Clear buffer contents while keeping allocation.

Resets the buffer for a new frame without deallocating the underlying memory. More efficient than destroy/create for repeated frame rendering.

Parameters

buf	Frame buffer to reset

Definition at line 72 of file frame_buffer.c.

                                             {
  if (!buf) {
    return;
  }
 
  buf->len = 0;
}

References frame_buffer::len.

Referenced by ui_session_clear(), ui_session_media(), and ui_session_render().

frame_buffer_set_screen_output_fd()

void frame_buffer_set_screen_output_fd

(

int

fd

)

Set output file descriptor for terminal screen (splash/status) rendering.

Parameters

fd	File descriptor (STDOUT_FILENO for TTY, STDERR_FILENO for piped output)

Controls where splash and status screens write their output. Used internally by terminal_screen_render() for consistent output routing.

Definition at line 211 of file frame_buffer.c.

                                               {
  g_terminal_screen_output_fd = fd;
  colored_string_set_output_fd(fd);
}

References colored_string_set_output_fd().

Referenced by terminal_screen_set_output_fd().