frame_buffer.c File Reference

Buffered terminal frame rendering implementation. More...

Go to the source code of this file.

Data Structures
struct	frame_buffer
	Frame buffer structure. More...

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.
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.
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)
int	frame_buffer_render_centered (frame_buffer_t *buf, const char *text, int cols)
	Render centered text (used by both splash and status screens)

Detailed Description

Buffered terminal frame rendering implementation.

Accumulates terminal output into a growable buffer and flushes atomically.

Definition in file frame_buffer.c.

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 67 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 frame_buffer_clear_screen(), and frame_buffer_cursor_home().

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 144 of file frame_buffer.c.

                                                    {
  if (!buf) {
    return;
  }
 
  // Combine clear screen and home in one operation
  frame_buffer_append(buf, "\033[2J\033[H", 8);
}

References frame_buffer_append().

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 29 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 terminal_screen_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 136 of file frame_buffer.c.

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

References frame_buffer_append().

Referenced by terminal_screen_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 50 of file frame_buffer.c.

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

References frame_buffer::data, and SAFE_FREE.

Referenced by terminal_screen_cleanup(), and terminal_screen_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 156 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;
    }
  }
 
  platform_write_all(g_terminal_screen_output_fd, output, output_len);
  SAFE_FREE(output);
}

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

Referenced by terminal_screen_render().

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 212 of file frame_buffer.c.

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

References frame_buffer::data.

Referenced by terminal_screen_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 205 of file frame_buffer.c.

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

References frame_buffer::len.

Referenced by terminal_screen_render().

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 201 of file frame_buffer.c.

                                            {
  return g_terminal_screen_output_fd;
}

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 98 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_border(), frame_buffer_render_centered(), and terminal_screen_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 219 of file frame_buffer.c.

                                                                                  {
  if (!buf || cols <= 0) {
    return;
  }
 
  if (color) {
    frame_buffer_printf(buf, "%s━", color);
  } else {
    frame_buffer_printf(buf, "━");
  }
  for (int i = 1; i < cols - 1; i++) {
    frame_buffer_printf(buf, "━");
  }
  if (color) {
    frame_buffer_printf(buf, "\033[0m");
  }
  frame_buffer_printf(buf, "\n");
}

References frame_buffer_printf().

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 238 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_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 59 of file frame_buffer.c.

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

References frame_buffer::len.

Referenced by terminal_screen_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 197 of file frame_buffer.c.

                                               {
  g_terminal_screen_output_fd = fd;
}

Referenced by terminal_screen_set_output_fd().