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_set_zalgo (terminal_renderer_t *r, int level)
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)
int	term_renderer_get_cols (terminal_renderer_t *r)
int	term_renderer_get_rows (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)
void	render_file_begin_drain (render_file_ctx_t *ctx, uint64_t total, bool total_known)
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 63 of file renderer.h.

terminal_renderer_t

typedef struct terminal_renderer_s terminal_renderer_t

Definition at line 18 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 27 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_begin_drain()

void render_file_begin_drain	(	render_file_ctx_t *	ctx,
		uint64_t	total,
		bool	total_known )

Definition at line 364 of file renderer.c.

                                                                                       {
  if (ctx)
    render_progress_begin(ctx->progress, total, total_known);
}

References render_file_ctx_s::progress, and render_progress_begin().

Referenced by session_display_begin_drain().

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 53 of file renderer.c.

                                                              {
  if (!output_path || !out || cols <= 0 || rows <= 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing render output, grid, or context");
  *out = NULL;
  log_info("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 *);
  if (strcmp(output_path, "/dev/null") == 0) {
    ctx->discard = true;
    ctx->error = ASCIICHAT_OK;
    *out = ctx;
    return ASCIICHAT_OK;
  }
  ctx->kitty_only = strcmp(output_path, "--kitty") == 0;
  ctx->kitty = ctx->kitty_only || GET_OPTION(render_kitty);
  if (ctx->kitty && !GET_OPTION(snapshot_mode)) {
    SAFE_FREE(ctx);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Kitty graphics output requires --snapshot");
  }
  if (ctx->kitty && (strcmp(output_path, "-") == 0 || strcmp(output_path, "pipe:") == 0)) {
    SAFE_FREE(ctx);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Kitty graphics and binary media cannot share stdout");
  }
  const char *term = SAFE_GETENV("TERM");
  if (ctx->kitty && terminal_is_stdout_tty() &&
      (!term || strcmp(term, "dumb") == 0 || strcmp(term, "linux") == 0 || strcmp(term, "vt100") == 0)) {
    SAFE_FREE(ctx);
    return SET_ERRNO(ERROR_NOT_SUPPORTED,
                     "Kitty graphics require a capable terminal; redirect stdout to export the protocol");
  }
 
  // Resolve font spec → platform-appropriate file path, family name, or bundled data.
  char font_spec[PLATFORM_MAX_PATH_LENGTH] = {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("[MATRIX] Using matrix font (enabled by --matrix flag)");
  }
 
  platform_font_register("matrix", g_font_matrix_resurrected, g_font_matrix_resurrected_size);
  platform_font_register("default", g_font_default, g_font_default_size);
  platform_font_register("DejaVu Sans Mono", g_font_default, g_font_default_size);
  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) {
    if (raw_font && raw_font[0]) {
      SAFE_FREE(ctx);
      return fe;
    }
    log_warn("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("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);
 
  // A zero size selects a compact default for video; explicit font sizes keep
  // their exact dimensions. Images and Kitty snapshots retain the 12 pt default.
  double font_size_pt = GET_OPTION(render_font_size);
  const char *extension = strrchr(output_path, '.');
  bool is_image =
      extension && (!strcmp(extension, ".png") || !strcmp(extension, ".jpg") || !strcmp(extension, ".jpeg") ||
                    !strcmp(extension, ".bmp") || !strcmp(extension, ".webp"));
  bool automatic_video_size = font_size_pt == 0.0 && !is_image && !ctx->kitty;
  if (font_size_pt == 0.0) {
    font_size_pt = RENDER_AUTO_FONT_SIZE_PT;
    if (automatic_video_size) {
      double width_scale = (double)RENDER_AUTO_VIDEO_MAX_DIMENSION / ((double)cols * 10.0);
      double height_scale = (double)RENDER_AUTO_VIDEO_MAX_DIMENSION / ((double)rows * 20.0);
      double scale = width_scale < height_scale ? width_scale : height_scale;
      if (scale < 1.0)
        font_size_pt *= scale;
      if (font_size_pt < RENDER_AUTO_MIN_FONT_SIZE_PT)
        font_size_pt = RENDER_AUTO_MIN_FONT_SIZE_PT;
    }
  }
  term_renderer_theme_t resolved_theme = (term_renderer_theme_t)theme;
  if (resolved_theme == TERM_RENDERER_THEME_AUTO) {
    resolved_theme =
        colorscheme_current_background() == TERM_BACKGROUND_DARK ? TERM_RENDERER_THEME_DARK : TERM_RENDERER_THEME_LIGHT;
    log_debug("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("term_renderer_create failed: %s", asciichat_error_format(NULL, 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);
  // Hinting and font metrics vary. Recalculate once if the initial estimate
  // exceeds the target, retaining the original renderer if a bitmap font
  // cannot be scaled down.
  if (automatic_video_size &&
      (actual_width_px > RENDER_AUTO_VIDEO_MAX_DIMENSION || actual_height_px > RENDER_AUTO_VIDEO_MAX_DIMENSION) &&
      font_size_pt > RENDER_AUTO_MIN_FONT_SIZE_PT) {
    double width_scale = (double)RENDER_AUTO_VIDEO_MAX_DIMENSION / actual_width_px;
    double height_scale = (double)RENDER_AUTO_VIDEO_MAX_DIMENSION / actual_height_px;
    double scale = width_scale < height_scale ? width_scale : height_scale;
    double smaller = font_size_pt * scale * 0.98;
    if (smaller < RENDER_AUTO_MIN_FONT_SIZE_PT)
      smaller = RENDER_AUTO_MIN_FONT_SIZE_PT;
    tr_cfg.font_size_pt = smaller;
    terminal_renderer_t *candidate = NULL;
    err = term_renderer_create(&tr_cfg, &candidate);
    if (err == ASCIICHAT_OK) {
      int candidate_width = term_renderer_width_px(candidate);
      int candidate_height = term_renderer_height_px(candidate);
      if (candidate_width <= actual_width_px && candidate_height <= actual_height_px &&
          (candidate_width < actual_width_px || candidate_height < actual_height_px)) {
        term_renderer_destroy(ctx->renderer);
        ctx->renderer = candidate;
        actual_width_px = candidate_width;
        actual_height_px = candidate_height;
      } else {
        term_renderer_destroy(candidate);
      }
    } else {
      term_renderer_destroy(ctx->renderer);
      SAFE_FREE(ctx);
      return err;
    }
  }
  log_info("GRID DIMENSIONS: %ux%u cells -> PIXEL DIMENSIONS: %dx%d px", cols, rows, actual_width_px, actual_height_px);
  log_debug("term_renderer created (%dx%d cells, %dx%d px)", cols, rows, actual_width_px, actual_height_px);
 
  if (ctx->kitty_only) {
    ctx->fps = fps;
    ctx->progress = render_progress_create(true, "terminal");
    NAMED_REGISTER_CONTEXT(ctx, "render_file_ctx", output_path, NULL);
    ui_controller_title_render(UI_TITLE_RENDERING);
    *out = ctx;
    return ASCIICHAT_OK;
  }
  int output_width_px = actual_width_px;
  int output_height_px = actual_height_px;
  if (automatic_video_size &&
      (output_width_px > RENDER_AUTO_VIDEO_MAX_DIMENSION || output_height_px > RENDER_AUTO_VIDEO_MAX_DIMENSION)) {
    double scale_x = (double)RENDER_AUTO_VIDEO_MAX_DIMENSION / output_width_px;
    double scale_y = (double)RENDER_AUTO_VIDEO_MAX_DIMENSION / output_height_px;
    double scale = scale_x < scale_y ? scale_x : scale_y;
    output_width_px = ((int)(output_width_px * scale)) & ~1;
    output_height_px = ((int)(output_height_px * scale)) & ~1;
    if (output_width_px < 2)
      output_width_px = 2;
    if (output_height_px < 2)
      output_height_px = 2;
  }
  err = ffmpeg_encoder_create_scaled(output_path, actual_width_px, actual_height_px, output_width_px, output_height_px,
                                     fps, &ctx->encoder);
  if (err != ASCIICHAT_OK) {
    log_error("ffmpeg_encoder_create failed: %s", asciichat_error_format(NULL, err));
    term_renderer_destroy(ctx->renderer);
    SAFE_FREE(ctx);
    return err;
  }
  log_debug("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_channels(&ctx->recording, 2);
  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("initialized encoder for %s", output_path);
 
  // Register render file context for debugging
  NAMED_REGISTER_CONTEXT(ctx, "render_file_ctx", output_path, NULL);
 
  bool binary_stdout = strcmp(output_path, "-") == 0 || strcmp(output_path, "pipe:") == 0;
  ctx->progress = render_progress_create(!binary_stdout, output_path);
  ui_controller_title_render(UI_TITLE_RENDERING);
  *out = ctx;
  return ASCIICHAT_OK;
}

References asciichat_error_format(), ASCIICHAT_OK, render_file_ctx_s::audio_buf_size, render_file_ctx_s::audio_read_buf, audio_recording_create_channels(), render_file_ctx_s::audio_sample_rate, colorscheme_current_background(), render_file_ctx_s::discard, render_file_ctx_s::encoder, render_file_ctx_s::error, ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, ffmpeg_encoder_create_scaled(), ffmpeg_encoder_destroy(), term_renderer_config_t::font_size_pt, term_renderer_config_t::font_spec, render_file_ctx_s::fps, g_font_default, g_font_default_size, g_font_matrix_resurrected, g_font_matrix_resurrected_size, GET_OPTION, render_file_ctx_s::kitty, render_file_ctx_s::kitty_only, log_debug, log_error, log_info, log_warn, NAMED_REGISTER_CONTEXT, out, PLATFORM_MAX_PATH_LENGTH, render_file_ctx_s::progress, render_file_ctx_s::recording, RENDER_AUTO_FONT_SIZE_PT, RENDER_AUTO_MIN_FONT_SIZE_PT, RENDER_AUTO_VIDEO_MAX_DIMENSION, render_progress_create(), render_file_ctx_s::renderer, SAFE_CALLOC, SAFE_FREE, SAFE_GETENV, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, TERM_BACKGROUND_DARK, 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(), ui_controller_title_render(), and UI_TITLE_RENDERING.

Referenced by session_display_init_render_file().

render_file_destroy()

asciichat_error_t render_file_destroy

(

render_file_ctx_t *

ctx

)

Definition at line 375 of file renderer.c.

                                                              {
  if (!ctx)
    return ASCIICHAT_OK;
  if (ctx->discard) {
    SAFE_FREE(ctx);
    return ASCIICHAT_OK;
  }
  NAMED_UNREGISTER(ctx);
  ui_controller_title_render(ctx->error == ASCIICHAT_OK ? UI_TITLE_FINALIZING : UI_TITLE_FAILED);
  render_progress_finalize(ctx->progress);
  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;
  if (ctx->error != ASCIICHAT_OK)
    err = ctx->error;
  render_progress_destroy(ctx->progress);
  if (err == ASCIICHAT_OK && ctx->kitty && ctx->frames_written == 0)
    err = SET_ERRNO(ERROR_MEDIA_INIT, "No snapshot was rendered for Kitty output");
  if (err == ASCIICHAT_OK && ctx->kitty && ctx->frames_written > 0)
    err = kitty_image_write(stdout, term_renderer_pixels(ctx->renderer), term_renderer_width_px(ctx->renderer),
                            term_renderer_height_px(ctx->renderer), term_renderer_pitch(ctx->renderer));
  ui_controller_title_render(err == ASCIICHAT_OK ? UI_TITLE_IDLE : UI_TITLE_FAILED);
  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::discard, render_file_ctx_s::encoder, render_file_ctx_s::error, ERROR_MEDIA_INIT, ffmpeg_encoder_destroy(), ffmpeg_encoder_write_audio(), render_file_ctx_s::frames_written, render_file_ctx_s::kitty, kitty_image_write(), NAMED_UNREGISTER, render_file_ctx_s::progress, render_file_ctx_s::recording, render_progress_destroy(), render_progress_finalize(), render_file_ctx_s::renderer, SAFE_FREE, SET_ERRNO, term_renderer_destroy(), term_renderer_height_px(), term_renderer_pitch(), term_renderer_pixels(), term_renderer_width_px(), ui_controller_title_render(), UI_TITLE_FAILED, UI_TITLE_FINALIZING, and UI_TITLE_IDLE.

Referenced by session_display_finish_render_file().

render_file_set_live_timing()

void render_file_set_live_timing

(

render_file_ctx_t *

ctx

)

Definition at line 266 of file renderer.c.

                                                         {
  if (ctx) {
    ctx->live_timing = true;
    if (ctx->encoder)
      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 369 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 348 of file renderer.c.

                                                                                                           {
  if (!ctx || !frame)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing render context or frame");
  if (ctx->error != ASCIICHAT_OK)
    return ctx->error;
  if (ctx->discard)
    return ASCIICHAT_OK;
  asciichat_error_t err = render_file_write_frame_internal(ctx, frame, captured_ns);
  if (err != ASCIICHAT_OK)
    ui_controller_title_render(UI_TITLE_FAILED);
  render_progress_frame(ctx->progress, frame, err == ASCIICHAT_OK);
  if (err != ASCIICHAT_OK)
    ctx->error = err;
  return err;
}

References ASCIICHAT_OK, render_file_ctx_s::discard, render_file_ctx_s::error, ERROR_INVALID_PARAM, render_file_ctx_s::progress, render_progress_frame(), SET_ERRNO, ui_controller_title_render(), and UI_TITLE_FAILED.

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 314 of file media/render/terminal.c.

                                                                                                     {
  if (!cfg || !out || cfg->cols <= 0 || cfg->rows <= 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing font renderer configuration or output");
  *out = NULL;
  if (cfg->font_data_size > LONG_MAX || (cfg->font_data_size && !cfg->font_data))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid font data or size");
  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");
  }
 
  FT_Error face_error;
  if (cfg->font_data && cfg->font_data_size > 0) {
    face_error = FT_New_Memory_Face(r->ft_lib, cfg->font_data, (FT_Long)cfg->font_data_size, 0, &r->ft_face);
  } else {
    face_error = FT_New_Face(r->ft_lib, cfg->font_spec, 0, &r->ft_face);
  }
  if (face_error) {
    FT_Done_FreeType(r->ft_lib);
    SAFE_FREE(r);
    if (face_error == FT_Err_Cannot_Open_Resource)
      return SET_ERRNO(ERROR_NOT_FOUND, "Cannot open font '%s' (FreeType error %d)", cfg->font_spec, face_error);
    // Older FreeType versions recognize an HVF SFNT wrapper, then reject its
    // missing TrueType outline tables instead of reporting an unknown format.
    if (face_error == FT_Err_Unknown_File_Format || face_error == FT_Err_Unimplemented_Feature ||
        face_error == FT_Err_Locations_Missing)
      return SET_ERRNO(ERROR_NOT_SUPPORTED,
                       "Unsupported font format: '%s' (FreeType error %d). HVF fonts require HVF-enabled FreeType "
                       "2.15+ on macOS 15.4+ or iOS 18.4+",
                       cfg->font_spec, face_error);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid font '%s' (FreeType error %d)", cfg->font_spec, face_error);
  }
 
  // Some older FreeType drivers can open an SFNT container without supporting
  // its outlines. Check the parsed table directory before accepting that face.
  FT_ULong hvf_size = 0;
  bool is_hvf = FT_IS_SFNT(r->ft_face) &&
                FT_Load_Sfnt_Table(r->ft_face, FT_MAKE_TAG('h', 'v', 'g', 'l'), 0, NULL, &hvf_size) == 0;
  const char *font_format = FT_Get_Font_Format(r->ft_face);
  if (is_hvf) {
    bool supported = false;
#ifdef __APPLE__
    if (__builtin_available(macOS 15.4, iOS 18.4, *))
      supported = font_format && strcmp(font_format, "HVF") == 0;
#endif
    if (!supported) {
      FT_Done_Face(r->ft_face);
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_NOT_SUPPORTED,
                       "Unsupported HVF font '%s': requires HVF-enabled FreeType 2.15+ on macOS 15.4+ or iOS 18.4+",
                       cfg->font_spec);
    }
  }
  log_debug("Loaded font '%s' using FreeType format %s", cfg->font_spec, font_format ? font_format : "unknown");
 
  // 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("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("[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("[BITMAP FALLBACK] FT_Select_Size(0) returned %d", err);
    }
    if (err != 0) {
      FT_Done_Face(r->ft_face);
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' has no usable bitmap size (FreeType error %d)", cfg->font_spec,
                       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("[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);
    if (err != 0) {
      FT_Done_Face(r->ft_face);
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' cannot be sized (FreeType error %d)", cfg->font_spec, 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("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);
      }
    }
  }
 
  if (load_err != 0) {
    FT_Done_Face(r->ft_face);
    FT_Done_FreeType(r->ft_lib);
    SAFE_FREE(r);
    return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' cannot render glyphs (FreeType error %d)", cfg->font_spec,
                     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("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("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("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("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("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("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("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("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("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("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_INVALID_PARAM, ERROR_NOT_FOUND, ERROR_NOT_SUPPORTED, 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, out, 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(), and TerminalRendererBinding::TerminalRendererBinding().

term_renderer_destroy()

void term_renderer_destroy

(

terminal_renderer_t *

r

)

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

                                                   {
  if (!r)
    return;
  vterm_free(r->vt);
  if (r->zalgo_face)
    FT_Done_Face(r->zalgo_face);
  glyph_cache_destroy(&r->zalgo_cache);
  FT_Done_Face(r->ft_face);
  FT_Done_FreeType(r->ft_lib);
  SAFE_FREE(r->framebuffer);
  glyph_cache_destroy(&r->glyph_cache);
  for (size_t i = 0; i < CELL_CACHE_SIZE; i++)
    SAFE_FREE(r->cells[i].pixels);
  SAFE_FREE(r);
}

References CELL_CACHE_SIZE, terminal_renderer_s::cells, terminal_renderer_s::framebuffer, terminal_renderer_s::ft_face, terminal_renderer_s::ft_lib, terminal_renderer_s::glyph_cache, rendered_cell_t::pixels, SAFE_FREE, terminal_renderer_s::vt, terminal_renderer_s::zalgo_cache, and terminal_renderer_s::zalgo_face.

Referenced by render_file_create(), render_file_destroy(), and TerminalRendererBinding::~TerminalRendererBinding().

term_renderer_feed()

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

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

                                                                                                 {
  if (!r || (!ansi_frame && len > 0)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "renderer or frame is invalid");
  }
 
  uint64_t stage_start_ns = time_get_ns();
  // 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);
  uint64_t parsed_ns = time_get_ns();
  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[RENDER_DEBUG_SIGNATURE_ROWS][RENDER_DEBUG_SIGNATURE_BUFFER_SIZE] = {
      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[RENDER_DEBUG_SIGNATURE_ROWS][RENDER_DEBUG_SIGNATURE_BUFFER_SIZE];
    for (int row = 0; row < r->rows && row < RENDER_DEBUG_SIGNATURE_ROWS; row++) {
      // Get first 4 chars as signature
      for (int col = 0; col < RENDER_DEBUG_SIGNATURE_COLUMNS && 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][RENDER_DEBUG_SIGNATURE_COLUMNS] = 0;
    }
    memcpy(prev_row_sigs, curr_row_sigs, sizeof(curr_row_sigs));
  }
 
  int glyph_rendered_count = 0;
  int occupied_cell_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[ASCII_LUMINANCE_LEVELS] = {0};
  bool indexed_rgb_valid[ASCII_LUMINANCE_LEVELS] = {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;
      uint32_t foreground = ((uint32_t)fr << 16) | ((uint32_t)fg << 8) | fb;
      uint32_t background = ((uint32_t)br << 16) | ((uint32_t)bg << 8) | bb;
      // Retain the low 32 bits without overflowing the intermediate products.
      uint32_t cell_hash = (uint32_t)((uint64_t)cell.chars[0] * UINT64_C(2654435761) ^
                                      (uint64_t)foreground * UINT64_C(2246822519) ^ background);
      cell_hash ^= cell_hash >> 16;
      rendered_cell_t *cached_cell = &r->cells[cell_hash % CELL_CACHE_SIZE];
      bool contained = px >= 0 && py >= 0 && px + r->cell_w <= r->width_px && py + r->cell_h <= r->height_px;
      if (contained && cached_cell->valid && cached_cell->character == cell.chars[0] &&
          cached_cell->foreground == foreground && cached_cell->background == background) {
        for (int dy = 0; dy < r->cell_h; dy++) {
          memcpy(r->framebuffer + (py + dy) * r->pitch + px * 4, cached_cell->pixels + dy * r->cell_w * 4,
                 (size_t)r->cell_w * 4);
        }
        if (cell.chars[0] && cell.chars[0] != ' ') {
          occupied_cell_count++;
          glyph_rendered_count++;
        }
        continue;
      }
      // Block elements represent cell geometry, independent of font bearings and line spacing.
      bool block = cell.chars[0] == 0x2580 || cell.chars[0] == 0x2584 || cell.chars[0] == 0x2588;
      for (int dy = 0; dy < r->cell_h; dy++) {
        bool block_foreground =
            block && (cell.chars[0] == 0x2588 || (cell.chars[0] == 0x2580 ? dy < r->cell_h / 2 : dy >= r->cell_h / 2));
        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] = block_foreground ? fr : br;
          line[dx * 4 + 1] = block_foreground ? fg : bg;
          line[dx * 4 + 2] = block_foreground ? fb : bb;
          line[dx * 4 + 3] = 255;
        }
      }
 
      if (block) {
        occupied_cell_count++;
        glyph_rendered_count++;
      } else 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) {
            // Overhanging glyphs must retain the normal cross-cell drawing order.
            contained = contained && cache_entry->bitmap_left >= 0 &&
                        cache_entry->bitmap_left + cache_entry->width <= r->cell_w &&
                        r->baseline - cache_entry->bitmap_top >= 0 &&
                        r->baseline - cache_entry->bitmap_top + cache_entry->rows <= r->cell_h;
            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 if (cell.chars[0] >= 0x2800 && cell.chars[0] <= 0x28ff) {
          // The bundled font lacks Braille. Draw its eight-dot pattern in the
          // cell when the selected font cannot supply the requested glyph.
          static const unsigned dot_bits[4][2] = {{0, 3}, {1, 4}, {2, 5}, {6, 7}};
          unsigned pattern = cell.chars[0] - 0x2800;
          int dot_w = r->cell_w / 4 > 0 ? r->cell_w / 4 : 1;
          int dot_h = r->cell_h / 8 > 0 ? r->cell_h / 8 : 1;
          for (int row = 0; row < 4; row++) {
            for (int col = 0; col < 2; col++) {
              if (!(pattern & (1U << dot_bits[row][col])))
                continue;
              int left = px + (2 * col + 1) * r->cell_w / 4 - dot_w / 2;
              int top = py + (2 * row + 1) * r->cell_h / 8 - dot_h / 2;
              for (int dy = 0; dy < dot_h; dy++) {
                for (int dx = 0; dx < dot_w; dx++) {
                  int x = left + dx, y = top + dy;
                  if (x < px || x >= px + r->cell_w || y < py || y >= py + r->cell_h || x < 0 || x >= r->width_px ||
                      y < 0 || y >= r->height_px)
                    continue;
                  uint8_t *pixel = r->framebuffer + y * r->pitch + x * 4;
                  pixel[0] = fr;
                  pixel[1] = fg;
                  pixel[2] = fb;
                  pixel[3] = 255;
                }
              }
            }
          }
          glyph_rendered_count++;
        } else {
          return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font cannot render Unicode character U+%04X", cell.chars[0]);
        }
      }
      if (contained) {
        if (!cached_cell->pixels)
          cached_cell->pixels = SAFE_MALLOC((size_t)r->cell_w * r->cell_h * 4, uint8_t *);
        if (cached_cell->pixels) {
          for (int dy = 0; dy < r->cell_h; dy++) {
            memcpy(cached_cell->pixels + dy * r->cell_w * 4, r->framebuffer + (py + dy) * r->pitch + px * 4,
                   (size_t)r->cell_w * 4);
          }
          cached_cell->character = cell.chars[0];
          cached_cell->foreground = foreground;
          cached_cell->background = background;
          cached_cell->valid = true;
        }
      }
    }
  }
  render_zalgo(r, offset_x, offset_y);
  uint64_t rendered_ns = time_get_ns();
  log_debug_every(US_PER_SEC_INT, "RECORD_RASTER: input_bytes=%zu parse_ms=%.2f paint_ms=%.2f cells=%dx%d", len,
                  (double)(parsed_ns - stage_start_ns) / NS_PER_MS_INT,
                  (double)(rendered_ns - parsed_ns) / NS_PER_MS_INT, r->cols, r->rows);
  log_debug_every(5 * US_PER_SEC_INT, "Rendered %d glyphs from %d occupied cells out of %d cells", glyph_rendered_count,
                  occupied_cell_count, r->rows * r->cols);
 
  return ASCIICHAT_OK;
}

References ASCII_LUMINANCE_LEVELS, ASCIICHAT_OK, rendered_cell_t::background, terminal_renderer_s::baseline, glyph_cache_entry_t::bitmap_left, glyph_cache_entry_t::bitmap_top, CELL_CACHE_SIZE, terminal_renderer_s::cell_h, terminal_renderer_s::cell_w, terminal_renderer_s::cells, rendered_cell_t::character, terminal_renderer_s::cols, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NOT_SUPPORTED, rendered_cell_t::foreground, terminal_renderer_s::framebuffer, terminal_renderer_s::ft_face, terminal_renderer_s::glyph_cache, terminal_renderer_s::height_px, index, terminal_renderer_s::is_matrix_font, log_debug_every, log_error, NS_PER_MS_INT, terminal_renderer_s::pitch, rendered_cell_t::pixels, RENDER_DEBUG_SIGNATURE_BUFFER_SIZE, RENDER_DEBUG_SIGNATURE_COLUMNS, RENDER_DEBUG_SIGNATURE_ROWS, glyph_cache_entry_t::rows, terminal_renderer_s::rows, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, terminal_renderer_s::theme, US_PER_SEC_INT, rendered_cell_t::valid, terminal_renderer_s::vt, terminal_renderer_s::vts, glyph_cache_entry_t::width, and terminal_renderer_s::width_px.

Referenced by TerminalRendererBinding::feed().

term_renderer_get_cols()

int term_renderer_get_cols

(

terminal_renderer_t *

r

)

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

                                                   {
  if (!r)
    return 0;
  return r->cols;
}

References terminal_renderer_s::cols.

Referenced by TerminalRendererBinding::cols().

term_renderer_get_rows()

int term_renderer_get_rows

(

terminal_renderer_t *

r

)

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

                                                   {
  if (!r)
    return 0;
  return r->rows;
}

References terminal_renderer_s::rows.

Referenced by TerminalRendererBinding::rows().

term_renderer_height_px()

int term_renderer_height_px

(

terminal_renderer_t *

r

)

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

                                                    {
  return r->height_px;
}

References terminal_renderer_s::height_px.

Referenced by TerminalRendererBinding::height(), render_file_create(), and render_file_destroy().

term_renderer_pitch()

int term_renderer_pitch

(

terminal_renderer_t *

r

)

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

                                                {
  return r->pitch;
}

References terminal_renderer_s::pitch.

Referenced by TerminalRendererBinding::copyPixels(), and render_file_destroy().

term_renderer_pixels()

const uint8_t * term_renderer_pixels

(

terminal_renderer_t *

r

)

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

                                                            {
  return r->framebuffer;
}

References terminal_renderer_s::framebuffer.

Referenced by TerminalRendererBinding::copyPixels(), and render_file_destroy().

term_renderer_set_zalgo()

asciichat_error_t term_renderer_set_zalgo	(	terminal_renderer_t *	r,
		int	level )

Enable raster Zalgo (1-10), or disable with zero.

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

                                                                             {
  if (!r || level < 0 || level > 10)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Zalgo raster level must be 0-10");
  if (level && !r->zalgo_face) {
    if (FT_New_Memory_Face(r->ft_lib, g_font_default, (FT_Long)g_font_default_size, 0, &r->zalgo_face))
      return SET_ERRNO(ERROR_INIT, "Cannot load Zalgo combining font");
    if (FT_Set_Pixel_Sizes(r->zalgo_face, 0, (FT_UInt)(r->cell_w * 2))) {
      FT_Done_Face(r->zalgo_face);
      r->zalgo_face = NULL;
      return SET_ERRNO(ERROR_INIT, "Cannot size Zalgo combining font");
    }
  }
  r->zalgo_level = level;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, terminal_renderer_s::cell_w, ERROR_INIT, ERROR_INVALID_PARAM, terminal_renderer_s::ft_lib, g_font_default, g_font_default_size, SET_ERRNO, terminal_renderer_s::zalgo_face, and terminal_renderer_s::zalgo_level.

Referenced by TerminalRendererBinding::setZalgo().

term_renderer_width_px()

int term_renderer_width_px

(

terminal_renderer_t *

r

)

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

                                                   {
  return r->width_px;
}

References terminal_renderer_s::width_px.

Referenced by render_file_create(), render_file_destroy(), and TerminalRendererBinding::width().