renderer.h File Reference

Terminal-to-pixel renderer and render-file output (audio + video) More...

Go to the source code of this file.

Data Structures
struct	term_renderer_config_t

Typedefs
typedef struct terminal_renderer_s	terminal_renderer_t
typedef struct render_file_ctx_s	render_file_ctx_t

Enumerations
enum	term_renderer_theme_t { TERM_RENDERER_THEME_DARK = 0 , TERM_RENDERER_THEME_LIGHT = 1 , TERM_RENDERER_THEME_AUTO = 2 }
	Terminal rendering theme. More...

Functions
asciichat_error_t	term_renderer_create (const term_renderer_config_t *cfg, terminal_renderer_t **out)
asciichat_error_t	term_renderer_feed (terminal_renderer_t *r, const char *ansi_frame, size_t len)
const uint8_t *	term_renderer_pixels (terminal_renderer_t *r)
int	term_renderer_width_px (terminal_renderer_t *r)
int	term_renderer_height_px (terminal_renderer_t *r)
int	term_renderer_pitch (terminal_renderer_t *r)
void	term_renderer_destroy (terminal_renderer_t *r)
asciichat_error_t	render_file_create (const char *output_path, int cols, int rows, int fps, int theme, render_file_ctx_t **out)
asciichat_error_t	render_file_write_frame (render_file_ctx_t *ctx, const char *ansi_frame, uint64_t captured_ns)
void	render_file_set_live_timing (render_file_ctx_t *ctx)
void	render_file_set_snapshot_actual_duration (render_file_ctx_t *ctx, double actual_duration_sec)
asciichat_error_t	render_file_destroy (render_file_ctx_t *ctx)

Detailed Description

Terminal-to-pixel renderer and render-file output (audio + video)

Supports theme-aware rendering that adapts colors based on the terminal's background theme (dark or light) for optimal readability.

Definition in file renderer.h.

Typedef Documentation

render_file_ctx_t

typedef struct render_file_ctx_s render_file_ctx_t

Definition at line 54 of file renderer.h.

terminal_renderer_t

typedef struct terminal_renderer_s terminal_renderer_t

Definition at line 17 of file renderer.h.

Enumeration Type Documentation

term_renderer_theme_t

enum term_renderer_theme_t

Terminal rendering theme.

Determines color palette for pixel-based ANSI text rendering. When TERM_RENDERER_THEME_AUTO is used, theme is detected from terminal_has_dark_background() to adapt colors to user's theme.

Enumerator
TERM_RENDERER_THEME_DARK	Dark theme: use light colors for dark background
TERM_RENDERER_THEME_LIGHT	Light theme: use dark colors for light background
TERM_RENDERER_THEME_AUTO	Auto-detect theme from terminal (default)

Definition at line 26 of file renderer.h.

             {
  TERM_RENDERER_THEME_DARK = 0,  
  TERM_RENDERER_THEME_LIGHT = 1, 
  TERM_RENDERER_THEME_AUTO = 2,  
} term_renderer_theme_t;

Function Documentation

render_file_create()

asciichat_error_t render_file_create	(	const char *	output_path,
		int	cols,
		int	rows,
		int	fps,
		int	theme,
		render_file_ctx_t **	out
	)

Definition at line 33 of file renderer.c.

                                                              {
  log_info("[RENDER_FILE_CREATE] CALLED with output_path=%s, cols=%d, rows=%d, fps=%d, theme=%d, out=%p",
           output_path ? output_path : "(null)", cols, rows, fps, theme, (void *)out);
  render_file_ctx_t *ctx = SAFE_CALLOC(1, sizeof(*ctx), render_file_ctx_t *);
 
  // Resolve font spec → platform-appropriate file path, family name, or bundled data.
  char font_spec[512] = {0};
  bool font_is_path = false;
  const uint8_t *font_data = NULL;
  size_t font_data_size = 0;
  const char *raw_font = GET_OPTION(render_font);
 
  // Log the font option value from GET_OPTION (for WASM font debugging)
  log_info("[WASM_FONT_GETTER] GET_OPTION(render_font) returned: '%s' (empty=%d), GET_OPTION(matrix_rain)=%d",
           raw_font ? raw_font : "(null)", (!raw_font || raw_font[0] == '\0') ? 1 : 0, GET_OPTION(matrix_rain));
 
  // Auto-select matrix font when --matrix flag is set, unless user explicitly overrides with --render-font
  log_debug("raw_font=%s, matrix_rain=%d", raw_font, GET_OPTION(matrix_rain));
  if ((!raw_font || raw_font[0] == '\0') && GET_OPTION(matrix_rain)) {
    raw_font = "matrix";
    log_debug("render_file_create: [MATRIX] Using matrix font (enabled by --matrix flag)");
  }
 
  asciichat_error_t fe =
      platform_font_resolve(raw_font, font_spec, sizeof(font_spec), &font_is_path, &font_data, &font_data_size);
  if (fe != ASCIICHAT_OK) {
    log_warn("renderer: font resolution failed for '%s' — using bundled default",
             raw_font ? raw_font : "(explicit system)");
    fe = platform_font_resolve("default", font_spec, sizeof(font_spec), &font_is_path, &font_data, &font_data_size);
    if (fe != ASCIICHAT_OK) {
      SAFE_FREE(ctx);
      return fe;
    }
  }
 
  log_debug("render_file_create: Font resolved: font_spec='%s', font_is_path=%d, font_data=%p (size=%zu)", font_spec,
            font_is_path, (void *)font_data, font_data_size);
 
  // Use reasonable default font size for render-file quality
  double font_size_pt = GET_OPTION(render_font_size);
  term_renderer_theme_t resolved_theme = (term_renderer_theme_t)theme;
  if (resolved_theme == TERM_RENDERER_THEME_AUTO) {
    resolved_theme = terminal_has_dark_background() ? TERM_RENDERER_THEME_DARK : TERM_RENDERER_THEME_LIGHT;
    log_debug("render_file_create: auto theme resolved to %s",
              resolved_theme == TERM_RENDERER_THEME_DARK ? "dark" : "light");
  }
 
  term_renderer_config_t tr_cfg = {
      .cols = cols,
      .rows = rows,
      .font_size_pt = font_size_pt,
      .theme = resolved_theme,
      .font_is_path = font_is_path,
      .font_data = font_data,
      .font_data_size = font_data_size,
  };
  SAFE_STRNCPY(tr_cfg.font_spec, font_spec, sizeof(tr_cfg.font_spec));
 
  asciichat_error_t err = term_renderer_create(&tr_cfg, &ctx->renderer);
  if (err != ASCIICHAT_OK) {
    log_error("render_file_create: term_renderer_create failed: %s", asciichat_error_string(err));
    SAFE_FREE(ctx);
    return err;
  }
  int actual_width_px = term_renderer_width_px(ctx->renderer);
  int actual_height_px = term_renderer_height_px(ctx->renderer);
  log_info("render_file_create: GRID DIMENSIONS: %ux%u cells -> PIXEL DIMENSIONS: %dx%d px", cols, rows,
           actual_width_px, actual_height_px);
  log_debug("render_file_create: term_renderer created (%dx%d cells, %dx%d px)", cols, rows, actual_width_px,
            actual_height_px);
 
  err = ffmpeg_encoder_create(output_path, actual_width_px, actual_height_px, fps, &ctx->encoder);
  if (err != ASCIICHAT_OK) {
    log_error("render_file_create: ffmpeg_encoder_create failed: %s", asciichat_error_string(err));
    term_renderer_destroy(ctx->renderer);
    SAFE_FREE(ctx);
    return err;
  }
  log_debug("render_file_create: ffmpeg_encoder created successfully");
 
  // Initialize audio fields
  ctx->audio_sample_rate = 48000; // Audio pipeline is 48kHz
  ctx->fps = fps;
  // Allocate large buffer for snapshot mode (5 seconds at 48kHz with ~14 FPS = 3,428 samples per frame)
  // Use 8192 to comfortably handle snapshot reads without excessive overhead
  ctx->audio_buf_size = 8192; // Temporary buffer for reading audio (in floats)
  ctx->audio_read_buf = SAFE_MALLOC(ctx->audio_buf_size * sizeof(float), float *);
 
  err = audio_recording_create(&ctx->recording);
  if (err != ASCIICHAT_OK) {
    ffmpeg_encoder_destroy(ctx->encoder);
    term_renderer_destroy(ctx->renderer);
    SAFE_FREE(ctx->audio_read_buf);
    SAFE_FREE(ctx);
    return err;
  }
  log_info("renderer: initialized encoder for %s", output_path);
 
  // Register render file context for debugging
  NAMED_REGISTER_CONTEXT(ctx, "render_file_ctx", output_path, NULL);
 
  *out = ctx;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, render_file_ctx_s::audio_buf_size, render_file_ctx_s::audio_read_buf, audio_recording_create(), render_file_ctx_s::audio_sample_rate, term_renderer_config_t::cols, render_file_ctx_s::encoder, ffmpeg_encoder_create(), ffmpeg_encoder_destroy(), term_renderer_config_t::font_spec, render_file_ctx_s::fps, GET_OPTION, log_debug, log_error, log_info, log_warn, NAMED_REGISTER_CONTEXT, platform_font_resolve(), render_file_ctx_s::recording, render_file_ctx_s::renderer, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, term_renderer_create(), term_renderer_destroy(), term_renderer_height_px(), TERM_RENDERER_THEME_AUTO, TERM_RENDERER_THEME_DARK, TERM_RENDERER_THEME_LIGHT, term_renderer_width_px(), and terminal_has_dark_background().

Referenced by session_display_init_render_file().

render_file_destroy()

asciichat_error_t render_file_destroy

(

render_file_ctx_t *

ctx

)

Definition at line 247 of file renderer.c.

                                                              {
  if (!ctx)
    return ASCIICHAT_OK;
  uint64_t target = ctx->audio_target;
  asciichat_error_t err = ASCIICHAT_OK;
  while (ctx->audio_samples_written < target) {
    int count = (int)((target - ctx->audio_samples_written) > (uint64_t)ctx->audio_buf_size
                          ? (uint64_t)ctx->audio_buf_size
                          : target - ctx->audio_samples_written);
    audio_recording_read(ctx->recording, ctx->audio_read_buf, count);
    err = ffmpeg_encoder_write_audio(ctx->encoder, ctx->audio_read_buf, count);
    if (err != ASCIICHAT_OK)
      break;
    ctx->audio_samples_written += count;
  }
  audio_recording_destroy(ctx->recording);
  asciichat_error_t close_err = ffmpeg_encoder_destroy(ctx->encoder);
  if (err == ASCIICHAT_OK)
    err = close_err;
  term_renderer_destroy(ctx->renderer);
  SAFE_FREE(ctx->audio_read_buf);
  SAFE_FREE(ctx);
  return err;
}

References ASCIICHAT_OK, render_file_ctx_s::audio_buf_size, render_file_ctx_s::audio_read_buf, audio_recording_destroy(), audio_recording_read(), render_file_ctx_s::audio_samples_written, render_file_ctx_s::audio_target, render_file_ctx_s::encoder, ffmpeg_encoder_destroy(), ffmpeg_encoder_write_audio(), render_file_ctx_s::recording, render_file_ctx_s::renderer, SAFE_FREE, and term_renderer_destroy().

Referenced by session_display_destroy().

render_file_set_live_timing()

void render_file_set_live_timing

(

render_file_ctx_t *

ctx

)

Definition at line 139 of file renderer.c.

                                                         {
  if (ctx) {
    ctx->live_timing = true;
    ffmpeg_encoder_set_live_timing(ctx->encoder);
  }
}

References render_file_ctx_s::encoder, ffmpeg_encoder_set_live_timing(), and render_file_ctx_s::live_timing.

Referenced by session_display_render_frame(), and session_display_set_render_live_timing().

render_file_set_snapshot_actual_duration()

void render_file_set_snapshot_actual_duration	(	render_file_ctx_t *	ctx,
		double	actual_duration_sec
	)

Definition at line 241 of file renderer.c.

                                                                                                  {
  if (!ctx || !ctx->encoder)
    return;
  ffmpeg_encoder_set_snapshot_actual_duration(ctx->encoder, actual_duration_sec);
}

References render_file_ctx_s::encoder, and ffmpeg_encoder_set_snapshot_actual_duration().

Referenced by session_display_set_snapshot_actual_duration().

render_file_write_frame()

asciichat_error_t render_file_write_frame	(	render_file_ctx_t *	ctx,
		const char *	ansi_frame,
		uint64_t	captured_ns
	)

Definition at line 146 of file renderer.c.

                                                                                                                {
 
  log_info("render_file_write_frame: CALLED - ctx=%p, captured_ns=%llu", (void *)ctx, (unsigned long long)captured_ns);
 
  if (!ctx) {
    log_warn("render_file_write_frame: ctx is NULL");
    return ASCIICHAT_OK;
  }
 
  if (!ansi_frame) {
    log_warn("render_file_write_frame: ansi_frame is NULL");
    return ASCIICHAT_OK;
  }
 
  size_t frame_len = strlen(ansi_frame);
  uint64_t frame_index = ctx->frames_written;
  if (ctx->live_timing && ctx->frames_written > 0) {
    uint64_t elapsed = captured_ns > ctx->first_frame_ns ? captured_ns - ctx->first_frame_ns : 0;
    frame_index = elapsed / 1000000000ULL * ctx->fps + elapsed % 1000000000ULL * ctx->fps / 1000000000ULL;
    if (frame_index <= ctx->last_frame_index)
      return ASCIICHAT_OK;
  }
  log_info("render_file_write_frame: processing frame (len=%zu)", frame_len);
  if (frame_len > 0) {
    log_info("  first 100 chars: %.100s", ansi_frame);
  }
 
  asciichat_error_t err = term_renderer_feed(ctx->renderer, ansi_frame, frame_len);
  if (err != ASCIICHAT_OK) {
    log_warn("render_file_write_frame: term_renderer_feed failed: %s", asciichat_error_string(err));
    return err;
  }
 
  const uint8_t *pixels = term_renderer_pixels(ctx->renderer);
  int pitch = term_renderer_pitch(ctx->renderer);
  int width_px = term_renderer_width_px(ctx->renderer);
  int height_px = term_renderer_height_px(ctx->renderer);
 
  log_info("render_file_write_frame: pixels=%p pitch=%d dims=%dx%d", (void *)pixels, pitch, width_px, height_px);
 
  if (pixels) {
    uint8_t sample_r = pixels[0], sample_g = pixels[1], sample_b = pixels[2], sample_a = pixels[3];
    size_t mid_offset = (size_t)(height_px / 2) * (size_t)pitch + (size_t)(width_px / 2) * 4;
    uint8_t sample_r_mid = pixels[mid_offset], sample_g_mid = pixels[mid_offset + 1],
            sample_b_mid = pixels[mid_offset + 2], sample_a_mid = pixels[mid_offset + 3];
 
    log_info("  pixel[0,0]: RGBA(%u,%u,%u,%u), pixel[%d,%d]: RGBA(%u,%u,%u,%u)", sample_r, sample_g, sample_b, sample_a,
             width_px / 2, height_px / 2, sample_r_mid, sample_g_mid, sample_b_mid, sample_a_mid);
  }
 
  // term_renderer_pixels() returns a pointer to the renderer's internal buffer which gets
  // overwritten on the next frame. We must copy the data before passing to the encoder.
  uint8_t *pixels_copy = NULL;
  if (pixels) {
    size_t pixel_buffer_size = (size_t)pitch * (size_t)height_px;
    pixels_copy = SAFE_MALLOC(pixel_buffer_size, uint8_t *);
    memcpy(pixels_copy, pixels, pixel_buffer_size);
    log_info("render_file_write_frame: copied %zu bytes of pixel data (was at %p, now at %p)", pixel_buffer_size,
             (void *)pixels, (void *)pixels_copy);
  }
 
  err = ffmpeg_encoder_write_frame(ctx->encoder, pixels_copy, pitch, captured_ns);
  if (err != ASCIICHAT_OK) {
    log_warn("render_file_write_frame: ffmpeg_encoder_write_frame failed: %s", asciichat_error_string(err));
  }
 
  // Free the pixel copy (ffmpeg_encoder_write_frame reads and converts it immediately)
  SAFE_FREE(pixels_copy);
 
  if (err == ASCIICHAT_OK) {
    if (ctx->frames_written == 0) {
      ctx->first_frame_ns = captured_ns;
      audio_recording_start(ctx->recording, captured_ns);
    }
    ctx->frames_written++;
    ctx->last_frame_index = frame_index;
    uint64_t target = (ctx->live_timing ? frame_index + 1 : ctx->frames_written) * ctx->audio_sample_rate / ctx->fps;
    ctx->audio_target = target;
    /* Keep 100 ms pending so audio callbacks can deliver samples before encoding. */
    uint64_t ready = target > 4800 ? target - 4800 : 0;
    while (ctx->audio_samples_written < ready) {
      int count = (int)((ready - ctx->audio_samples_written) > (uint64_t)ctx->audio_buf_size
                            ? (uint64_t)ctx->audio_buf_size
                            : ready - ctx->audio_samples_written);
      audio_recording_read(ctx->recording, ctx->audio_read_buf, count);
      err = ffmpeg_encoder_write_audio(ctx->encoder, ctx->audio_read_buf, count);
      if (err != ASCIICHAT_OK)
        break;
      ctx->audio_samples_written += count;
    }
  }
 
  return err;
}

References ASCIICHAT_OK, render_file_ctx_s::audio_buf_size, render_file_ctx_s::audio_read_buf, audio_recording_read(), audio_recording_start(), render_file_ctx_s::audio_sample_rate, render_file_ctx_s::audio_samples_written, render_file_ctx_s::audio_target, render_file_ctx_s::encoder, ffmpeg_encoder_write_audio(), ffmpeg_encoder_write_frame(), render_file_ctx_s::first_frame_ns, render_file_ctx_s::fps, render_file_ctx_s::frames_written, render_file_ctx_s::last_frame_index, render_file_ctx_s::live_timing, log_info, log_warn, render_file_ctx_s::recording, render_file_ctx_s::renderer, SAFE_FREE, SAFE_MALLOC, term_renderer_feed(), term_renderer_height_px(), term_renderer_pitch(), term_renderer_pixels(), and term_renderer_width_px().

Referenced by session_display_encode_frame(), and session_display_render_frame().

term_renderer_create()

asciichat_error_t term_renderer_create	(	const term_renderer_config_t *	cfg,
		terminal_renderer_t **	out
	)

Definition at line 261 of file media/render/terminal.c.

                                                                                                     {
  terminal_renderer_t *r = SAFE_CALLOC(1, sizeof(*r), terminal_renderer_t *);
  r->cols = cfg->cols;
  r->rows = cfg->rows;
  r->theme = cfg->theme;
 
  if (FT_Init_FreeType(&r->ft_lib)) {
    SAFE_FREE(r);
    return SET_ERRNO(ERROR_INIT, "FreeType init failed");
  }
 
  if (cfg->font_data && cfg->font_data_size > 0) {
    if (FT_New_Memory_Face(r->ft_lib, cfg->font_data, (FT_Long)cfg->font_data_size, 0, &r->ft_face)) {
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_INIT, "FreeType: cannot load bundled font");
    }
  } else {
    if (FT_New_Face(r->ft_lib, cfg->font_spec, 0, &r->ft_face)) {
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_NOT_FOUND, "FreeType: cannot load font '%s'", cfg->font_spec);
    }
  }
 
  // Detect if this is the matrix font (needs character mapping to Private Use Area)
  r->is_matrix_font = (strstr(cfg->font_spec, "matrix") != NULL || strstr(cfg->font_spec, "Matrix") != NULL) ||
                      (cfg->font_data != NULL && GET_OPTION(matrix_rain));
  if (r->is_matrix_font) {
    log_debug("term_renderer_create: Detected matrix font - will use Private Use Area character mapping");
  }
 
  // Handle scalable vs bitmap fonts differently
  // Bitmap fonts (like matrix) don't respond to FT_Set_Char_Size
  // Instead, use FT_Set_Pixel_Sizes to request a specific pixel size
  if (r->ft_face->num_fixed_sizes > 0) {
    // Bitmap font: use FT_Set_Pixel_Sizes to select appropriate size (12px is reasonable for ASCII)
    int err = FT_Set_Pixel_Sizes(r->ft_face, 12, 12);
    log_debug("term_renderer_create: [BITMAP] FT_Set_Pixel_Sizes(12, 12) returned %d", err);
 
    // If that fails, try FT_Select_Size as fallback
    if (err != 0) {
      err = FT_Select_Size(r->ft_face, 0); // Use first available strike
      log_debug("term_renderer_create: [BITMAP FALLBACK] FT_Select_Size(0) returned %d", err);
    }
  } else {
    // Scalable font: use FT_Set_Char_Size
    // FT_Set_Char_Size takes 1/64pt units and DPI — supports fractional point sizes.
    // 96 DPI is the standard screen DPI used here; the 64 factor is the 26.6 fixed-point scale.
    int err = FT_Set_Char_Size(r->ft_face, 0, (FT_F26Dot6)(cfg->font_size_pt * 64.0), 96, 96);
    log_debug("term_renderer_create: [SCALABLE] FT_Set_Char_Size(size_pt=%.1f → %ld 1/64pt) returned %d",
              cfg->font_size_pt, (long)(cfg->font_size_pt * 64.0), err);
  }
 
  // For matrix fonts, try PUA glyph first (U+E900) since ASCII chars might not have bitmap data
  // For other fonts, start with 'M'
  int load_err;
  if (r->is_matrix_font) {
    log_debug("Matrix font detected: trying PUA glyph U+E900 first");
    load_err = FT_Load_Char(r->ft_face, 0xE900, FT_LOAD_RENDER);
    log_debug("FT_Load_Char(U+E900) returned %d", load_err);
 
    // If PUA glyph fails, try ASCII fallback
    if (load_err != 0) {
      log_debug("U+E900 failed, trying fallback character 'M'");
      load_err = FT_Load_Char(r->ft_face, 'M', FT_LOAD_RENDER);
      log_debug("FT_Load_Char('M') returned %d", load_err);
    }
  } else {
    // For non-matrix fonts, standard approach
    load_err = FT_Load_Char(r->ft_face, 'M', FT_LOAD_RENDER);
    log_debug("DEBUG: FT_Load_Char('M', FT_LOAD_RENDER) returned %d", load_err);
 
    // For bitmap fonts (like matrix), FT_Load_Char may fail if the character doesn't exist.
    // Try a fallback character if 'M' fails.
    if (load_err != 0 && r->ft_face->num_fixed_sizes > 0) {
      log_debug("FT_Load_Char('M') failed for bitmap font, trying fallback character 'A'");
      load_err = FT_Load_Char(r->ft_face, 'A', FT_LOAD_RENDER);
      log_debug("FT_Load_Char('A') returned %d", load_err);
 
      if (load_err != 0) {
        // Last resort: try a PUA glyph for unknown bitmap fonts
        log_debug("FT_Load_Char('A') also failed, trying PUA glyph U+E900");
        load_err = FT_Load_Char(r->ft_face, 0xE900, FT_LOAD_RENDER);
        log_debug("FT_Load_Char(U+E900) returned %d", load_err);
      }
    }
  }
 
  // For monospace ASCII grid: use advance.x (proper character spacing) and rendered height
  FT_Pos advance_x_26_6 = r->ft_face->glyph->advance.x;
  log_debug("DEBUG: advance.x (26.6pt)=%ld", advance_x_26_6);
 
  // Calculate cell width from font metrics
  r->cell_w = (int)(advance_x_26_6 >> 6);
 
  // Safeguard: for bitmap fonts, cell_w might be wrong if the font metrics are off
  // Ensure we have a reasonable minimum width
  if (r->cell_w <= 0) {
    log_warn("term_renderer_create: cell_w is %d (invalid), using default 10px", r->cell_w);
    r->cell_w = 10;
  }
 
  // Only add spacing to fill entire frame if --stretch is specified
  bool stretch_mode = GET_OPTION(stretch);
  if (stretch_mode) {
    r->cell_w++;
    log_debug("ADVANCE_X: value=%ld (26.6pt) → cell_w=%d (advance + 1 for stretch), cols=%d → width_px=%d",
              advance_x_26_6, r->cell_w, r->cols, r->cols * r->cell_w);
  } else {
    log_debug("ADVANCE_X: value=%ld (26.6pt) → cell_w=%d (preserve aspect ratio), cols=%d → width_px=%d",
              advance_x_26_6, r->cell_w, r->cols, r->cols * r->cell_w);
  }
 
  // For both bitmap and scalable fonts, use the actual glyph bitmap height
  // This ensures text doesn't overflow cells. Using size->metrics.height (line spacing)
  // instead of bitmap.rows causes cells to be too large and text to overflow.
  r->cell_h = r->ft_face->glyph->bitmap.rows;
  int raw_bitmap_top = r->ft_face->glyph->bitmap_top;
  log_debug("DEBUG: cell_h=%d (from bitmap.rows), raw_bitmap_top=%d", r->cell_h, raw_bitmap_top);
 
  // Fallback: if cell_h is 0 (bitmap failed to load), use aspect ratio calculation
  if (r->cell_h <= 0) {
    log_warn("term_renderer_create: cell_h is 0 (FT_Load_Char failed or no bitmap), using aspect ratio fallback");
    r->cell_h = r->cell_w * 2;
    log_debug("FALLBACK: cell_h set to %d (2x width=%d)", r->cell_h, r->cell_w);
  }
 
  // Apply aspect ratio correction unless --stretch is specified
  // Terminal characters are typically 2:1 (height:width) to appear normal
  // BUT: only correct if the loaded glyph height is reasonably close (±30%)
  // This prevents huge jumps from small glyphs (e.g., 8px → 32px)
  if (!stretch_mode && r->cell_h > 0) {
    int corrected_h = r->cell_w * 2;
    int min_acceptable = (corrected_h * 70) / 100;  // 70% of target
    int max_acceptable = (corrected_h * 130) / 100; // 130% of target
 
    if (r->cell_h < min_acceptable || r->cell_h > max_acceptable) {
      // Loaded height is far from expected, apply correction
      log_debug("ASPECT_RATIO: Correcting cell_h from %d to %d (out of range [%d,%d], 2x width=%d)", r->cell_h,
                corrected_h, min_acceptable, max_acceptable, r->cell_w);
      r->cell_h = corrected_h;
    } else if (corrected_h != r->cell_h) {
      // Loaded height is close to expected, fine-tune by small amount only
      int delta = corrected_h - r->cell_h;
      if (delta > 4 || delta < -4) {
        // Only apply if difference is more than 4px
        log_debug("ASPECT_RATIO: Fine-tuning cell_h from %d to %d (within acceptable range, 2x width=%d)", r->cell_h,
                  corrected_h, r->cell_w);
        r->cell_h = corrected_h;
      } else {
        log_debug("ASPECT_RATIO: Keeping cell_h=%d (close to target %d, delta=%d)", r->cell_h, corrected_h, delta);
      }
    }
  }
 
  // Position baseline vertically within the cell.
  // Baseline should be positioned at approximately 75% of cell height to allow proper
  // glyph rendering with space both above and below. This prevents glyphs from being
  // clipped at the cell boundaries.
  //
  // Baseline position: y_glyph = py + r->baseline - g->bitmap_top
  // We want: 0 <= baseline - bitmap_top < cell_h (glyph fits within cell)
  // Choose: baseline = (3 * cell_h) / 4 (positions at 75% height)
  r->baseline = (3 * r->cell_h) / 4;
  log_debug("DEBUG: baseline set to %d (75%% of cell_h=%d)", r->baseline, r->cell_h);
 
  r->width_px = r->cols * r->cell_w;
  r->height_px = r->rows * r->cell_h;
  log_debug("DEBUG: calculated dimensions: width_px=%d (cols=%d * cell_w=%d), height_px=%d (rows=%d * cell_h=%d)",
            r->width_px, r->cols, r->cell_w, r->height_px, r->rows, r->cell_h);
  // Pitch in bytes: each pixel is 4 bytes (RGBA), already aligned to 4-byte boundary
  int base_pitch = r->width_px * 4;
  r->pitch = base_pitch;
  log_debug("PITCH_CALC: width_px=%d, base_pitch=%d, final_pitch=%d (RGBA, no padding needed)", r->width_px, base_pitch,
            r->pitch);
  log_debug("DEBUG: Allocating framebuffer: %d bytes total (%d pitch * %d height)",
            (int)((size_t)r->pitch * r->height_px), r->pitch, r->height_px);
  r->framebuffer = SAFE_MALLOC((size_t)r->pitch * r->height_px, uint8_t *);
 
  r->vt = vterm_new(r->rows, r->cols);
  r->vts = vterm_obtain_screen(r->vt);
 
  // Enable UTF-8 encoding so vterm correctly parses multi-byte characters
  vterm_set_utf8(r->vt, 1);
 
  // Set size BEFORE reset to ensure screen is allocated with correct dimensions
  vterm_set_size(r->vt, r->rows, r->cols);
  log_debug("DEBUG: vterm_set_size called with rows=%d cols=%d", r->rows, r->cols);
 
  vterm_screen_set_callbacks(r->vts, &g_vterm_cbs, r);
  // Reset MUST come before any input writing to initialize state correctly
  vterm_screen_reset(r->vts, 1);
 
  // Verify the size was set correctly after reset
  int vt_rows, vt_cols;
  vterm_get_size(r->vt, &vt_rows, &vt_cols);
  log_debug("DEBUG: vterm_get_size returned rows=%d cols=%d (expected %d,%d)", vt_rows, vt_cols, r->rows, r->cols);
 
  // CRITICAL: Set size AGAIN after reset, as reset may have affected it
  vterm_set_size(r->vt, r->rows, r->cols);
  log_debug("DEBUG: vterm_set_size called AGAIN after reset");
 
  // Initialize per-renderer glyph cache (empty, will populate on demand)
  r->glyph_cache = NULL;
 
  *out = r;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, terminal_renderer_s::baseline, terminal_renderer_s::cell_h, terminal_renderer_s::cell_w, term_renderer_config_t::cols, terminal_renderer_s::cols, ERROR_INIT, ERROR_NOT_FOUND, term_renderer_config_t::font_data, term_renderer_config_t::font_data_size, term_renderer_config_t::font_size_pt, term_renderer_config_t::font_spec, terminal_renderer_s::framebuffer, terminal_renderer_s::ft_face, terminal_renderer_s::ft_lib, GET_OPTION, terminal_renderer_s::glyph_cache, terminal_renderer_s::height_px, terminal_renderer_s::is_matrix_font, log_debug, log_warn, terminal_renderer_s::pitch, term_renderer_config_t::rows, terminal_renderer_s::rows, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, term_renderer_config_t::theme, terminal_renderer_s::theme, terminal_renderer_s::vt, terminal_renderer_s::vts, and terminal_renderer_s::width_px.

Referenced by render_file_create().

term_renderer_destroy()

void term_renderer_destroy

(

terminal_renderer_t *

r

)

Definition at line 685 of file media/render/terminal.c.

                                                   {
  if (!r)
    return;
  vterm_free(r->vt);
  FT_Done_Face(r->ft_face);
  FT_Done_FreeType(r->ft_lib);
  SAFE_FREE(r->framebuffer);
  glyph_cache_destroy(&r->glyph_cache);
  SAFE_FREE(r);
}

References terminal_renderer_s::framebuffer, terminal_renderer_s::ft_face, terminal_renderer_s::ft_lib, terminal_renderer_s::glyph_cache, SAFE_FREE, and terminal_renderer_s::vt.

Referenced by render_file_create(), and render_file_destroy().

term_renderer_feed()

asciichat_error_t term_renderer_feed	(	terminal_renderer_t *	r,
		const char *	ansi_frame,
		size_t	len
	)

Definition at line 471 of file media/render/terminal.c.

                                                                                                 {
  if (!r || (!ansi_frame && len > 0)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "term_renderer_feed: renderer or frame is invalid");
  }
 
  // libvterm natively implements CSI REP.  Expanding those runs here turns a
  // compact network frame into synchronous browser-main-thread work before
  // every paint.
  const char *frame = ansi_frame;
  const size_t frame_len = len;
 
  // Clear framebuffer to ensure no leftover pixels from previous frames
  uint8_t def_fg_r, def_fg_g, def_fg_b;
  uint8_t def_bg_r, def_bg_g, def_bg_b;
  terminal_get_default_foreground_color(r->theme, &def_fg_r, &def_fg_g, &def_fg_b);
  terminal_get_default_background_color(r->theme, &def_bg_r, &def_bg_g, &def_bg_b);
  uint8_t def_bg = def_bg_r;
  memset(r->framebuffer, def_bg, (size_t)r->pitch * r->height_px);
 
  // Reset scrolling region and cursor position to prevent vertical shifts
  static const char reset_sequence[] = "\033[2J\033[H\033[r\033[?7l";
  vterm_input_write(r->vt, reset_sequence, sizeof(reset_sequence) - 1);
 
  // Count newlines to determine CRLF conversion size
  int newline_count = 0;
  for (size_t i = 0; i < frame_len; i++) {
    if (frame[i] == '\n')
      newline_count++;
  }
 
  // Convert LF-only line endings to CRLF (vterm expects CRLF)
  // This fixes cursor positioning on alternate rows
  char *fixed_frame = SAFE_MALLOC(frame_len + (size_t)newline_count, char *);
  if (!fixed_frame) {
    log_error("failed to allocate memory for CRLF conversion");
    return SET_ERRNO(ERROR_MEMORY, "CRLF conversion allocation failed");
  }
 
  size_t fixed_pos = 0;
  int frame_row = 0;
  for (size_t i = 0; i < frame_len; i++) {
    // A video frame is a fixed grid, not a scrolling terminal transcript.
    // A trailing newline on the bottom row must not scroll the whole image.
    if (frame[i] == '\n' && frame_row >= r->rows - 1) {
      continue;
    }
    fixed_frame[fixed_pos++] = frame[i];
    if (frame[i] == '\n' && (i == 0 || frame[i - 1] != '\r')) {
      // Insert carriage return before LF if not already preceded by CR
      fixed_frame[fixed_pos - 1] = '\r';
      fixed_frame[fixed_pos++] = '\n';
    }
    if (frame[i] == '\n') frame_row++;
  }
 
  vterm_input_write(r->vt, fixed_frame, fixed_pos);
  SAFE_FREE(fixed_frame);
 
  // Calculate centering offsets to position grid in center of canvas
  int grid_width_px = r->cols * r->cell_w;
  int grid_height_px = r->rows * r->cell_h;
  int offset_x = (r->width_px - grid_width_px) / 2;
  int offset_y = (r->height_px - grid_height_px) / 2;
 
  static int frame_count = 0;
  static char prev_row_sigs[52][5] = {0}; // Store signatures of previous frame's rows
  frame_count++;
 
  // Log if any row signature changed to detect vertical shifts
  if (frame_count % 10 == 0) {
    char curr_row_sigs[52][5];
    for (int row = 0; row < r->rows && row < 52; row++) {
      // Get first 4 chars as signature
      for (int col = 0; col < 4 && col < r->cols; col++) {
        VTermScreenCell cell;
        vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
        curr_row_sigs[row][col] = (cell.chars[0] >= 32 && cell.chars[0] <= 126) ? cell.chars[0] : '.';
      }
      curr_row_sigs[row][4] = 0;
    }
    memcpy(prev_row_sigs, curr_row_sigs, sizeof(curr_row_sigs));
  }
 
  int glyph_rendered_count = 0;
  int occupied_cell_count = 0;
  int glyph_missing_count = 0;
  // ANSI 16/256 colors are indexed.  Converting them through libvterm for
  // every cell is especially expensive in the single-threaded WASM renderer.
  // A terminal palette has at most 256 entries and is stable for a frame.
  uint32_t indexed_rgb[256] = {0};
  bool indexed_rgb_valid[256] = {false};
  for (int row = 0; row < r->rows; row++) {
    for (int col = 0; col < r->cols; col++) {
      VTermScreenCell cell;
      vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
 
      uint8_t fr, fg, fb, br, bg, bb;
      if (VTERM_COLOR_IS_RGB(&cell.fg)) {
        fr = cell.fg.rgb.red;
        fg = cell.fg.rgb.green;
        fb = cell.fg.rgb.blue;
      } else if (VTERM_COLOR_IS_INDEXED(&cell.fg)) {
        const uint8_t index = cell.fg.indexed.idx;
        if (!indexed_rgb_valid[index]) {
          VTermColor foreground = cell.fg;
          vterm_screen_convert_color_to_rgb(r->vts, &foreground);
          indexed_rgb[index] = ((uint32_t)foreground.rgb.red << 16) |
                               ((uint32_t)foreground.rgb.green << 8) |
                               foreground.rgb.blue;
          indexed_rgb_valid[index] = true;
        }
        fr = (uint8_t)(indexed_rgb[index] >> 16);
        fg = (uint8_t)(indexed_rgb[index] >> 8);
        fb = (uint8_t)indexed_rgb[index];
      } else {
        fr = def_fg_r;
        fg = def_fg_g;
        fb = def_fg_b;
      }
 
      if (VTERM_COLOR_IS_RGB(&cell.bg)) {
        br = cell.bg.rgb.red;
        bg = cell.bg.rgb.green;
        bb = cell.bg.rgb.blue;
      } else if (VTERM_COLOR_IS_INDEXED(&cell.bg)) {
        const uint8_t index = cell.bg.indexed.idx;
        if (!indexed_rgb_valid[index]) {
          VTermColor background = cell.bg;
          vterm_screen_convert_color_to_rgb(r->vts, &background);
          indexed_rgb[index] = ((uint32_t)background.rgb.red << 16) |
                               ((uint32_t)background.rgb.green << 8) |
                               background.rgb.blue;
          indexed_rgb_valid[index] = true;
        }
        br = (uint8_t)(indexed_rgb[index] >> 16);
        bg = (uint8_t)(indexed_rgb[index] >> 8);
        bb = (uint8_t)indexed_rgb[index];
      } else {
        br = def_bg_r;
        bg = def_bg_g;
        bb = def_bg_b;
      }
 
      int px = offset_x + col * r->cell_w, py = offset_y + row * r->cell_h;
      for (int dy = 0; dy < r->cell_h; dy++) {
        int y = py + dy;
        if (y < 0 || y >= r->height_px)
          continue;
        uint8_t *line = r->framebuffer + y * r->pitch + px * 4;
        for (int dx = 0; dx < r->cell_w; dx++) {
          int x = px + dx;
          if (x < 0 || x >= r->width_px)
            continue;
          line[dx * 4] = br;
          line[dx * 4 + 1] = bg;
          line[dx * 4 + 2] = bb;
          line[dx * 4 + 3] = 255;
        }
      }
 
      if (cell.chars[0] && cell.chars[0] != ' ') {
        occupied_cell_count++;
        // For matrix font, map ASCII characters to Private Use Area glyphs (U+E900-U+E91A)
        uint32_t char_to_render = r->is_matrix_font ? matrix_char_map(cell.chars[0]) : cell.chars[0];
 
        // Use per-renderer glyph cache to avoid rasterizing every glyph every frame
        FT_Bitmap *cached_bitmap = glyph_cache_get(r, r->ft_face, char_to_render);
        if (cached_bitmap && cached_bitmap->width > 0 && cached_bitmap->rows > 0) {
          // Find cache entry to get positioning offsets
          glyph_cache_entry_t *cache_entry = NULL;
          HASH_FIND_INT(r->glyph_cache, &char_to_render, cache_entry);
          if (cache_entry) {
            blit_glyph(r, cached_bitmap, px + cache_entry->bitmap_left, py + r->baseline - cache_entry->bitmap_top, fr,
                       fg, fb, br, bg, bb);
            glyph_rendered_count++;
          }
        } else {
          glyph_missing_count++;
        }
      }
    }
  }
  log_debug_every(5 * US_PER_SEC_INT,
                  "term_renderer_feed: Rendered %d glyphs from %d occupied cells (%d missing) out of %d cells",
                  glyph_rendered_count, occupied_cell_count, glyph_missing_count, r->rows * r->cols);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, terminal_renderer_s::baseline, glyph_cache_entry_t::bitmap_left, glyph_cache_entry_t::bitmap_top, terminal_renderer_s::cell_h, terminal_renderer_s::cell_w, terminal_renderer_s::cols, ERROR_INVALID_PARAM, ERROR_MEMORY, frame, terminal_renderer_s::framebuffer, terminal_renderer_s::ft_face, terminal_renderer_s::glyph_cache, terminal_renderer_s::height_px, terminal_renderer_s::is_matrix_font, log_debug_every, log_error, terminal_renderer_s::pitch, terminal_renderer_s::rows, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, terminal_get_default_background_color(), terminal_get_default_foreground_color(), terminal_renderer_s::theme, US_PER_SEC_INT, terminal_renderer_s::vt, terminal_renderer_s::vts, and terminal_renderer_s::width_px.

Referenced by render_file_write_frame().

term_renderer_height_px()

int term_renderer_height_px

(

terminal_renderer_t *

r

)

Definition at line 666 of file media/render/terminal.c.

                                                    {
  return r->height_px;
}

References terminal_renderer_s::height_px.

Referenced by render_file_create(), and render_file_write_frame().

term_renderer_pitch()

int term_renderer_pitch

(

terminal_renderer_t *

r

)

Definition at line 669 of file media/render/terminal.c.

                                                {
  return r->pitch;
}

References terminal_renderer_s::pitch.

Referenced by render_file_write_frame().

term_renderer_pixels()

const uint8_t * term_renderer_pixels

(

terminal_renderer_t *

r

)

Definition at line 660 of file media/render/terminal.c.

                                                            {
  return r->framebuffer;
}

References terminal_renderer_s::framebuffer.

Referenced by render_file_write_frame().

term_renderer_width_px()

int term_renderer_width_px

(

terminal_renderer_t *

r

)

Definition at line 663 of file media/render/terminal.c.

                                                   {
  return r->width_px;
}

References terminal_renderer_s::width_px.

Referenced by render_file_create(), and render_file_write_frame().