ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
lib/media/render/terminal.c
Go to the documentation of this file.
15
16/* Storage capacities in elements; text buffers include the terminating NUL. */
17#define RENDER_DEBUG_SIGNATURE_ROWS 52
18#define RENDER_DEBUG_SIGNATURE_COLUMNS 4
19#define RENDER_DEBUG_SIGNATURE_BUFFER_SIZE (RENDER_DEBUG_SIGNATURE_COLUMNS + 1)
20
24#include <libplatform/memory.h>
25#include <libplatform/terminal.h>
26#include <ascii-chat/log/log.h>
27#include <options/options.h>
28#include <ascii-chat/uthash.h>
29#include <ascii-chat/font.h>
31#include <vterm.h>
32#include <ft2build.h>
33#include FT_FREETYPE_H
34#include FT_GLYPH_H
35#include FT_FONT_FORMATS_H
36#include FT_TRUETYPE_TABLES_H
37#include <string.h>
38#include <stddef.h>
39#include <stdint.h>
40#include <limits.h>
41
42// ============================================================================
43// Glyph Cache
44// ============================================================================
45
58typedef struct {
59 uint32_t codepoint; // Hash key (character code)
60 uint8_t *bitmap_buf; // Normalized 8-bit alpha bitmap
61 int width; // Bitmap dimensions (in pixels)
62 int rows; // Bitmap height (in rows)
63 int pitch; // Bytes per row
64 int bitmap_left; // Glyph positioning offsets
66 UT_hash_handle hh; // uthash handle
68
72static void glyph_cache_destroy(glyph_cache_entry_t **cache) {
73 glyph_cache_entry_t *curr, *tmp;
74 HASH_ITER(hh, *cache, curr, tmp) {
75 HASH_DEL(*cache, curr);
76 SAFE_FREE(curr->bitmap_buf);
77 SAFE_FREE(curr);
78 }
79}
80
81// Cache complete cells so repeated glyph/color combinations need only row copies.
82#define CELL_CACHE_SIZE 512
88
106
112static FT_Bitmap *glyph_cache_get(terminal_renderer_t *r, FT_Face face, uint32_t codepoint) {
113 glyph_cache_entry_t *entry = NULL;
114
115 // Lookup in renderer's per-font cache
116 HASH_FIND_INT(r->glyph_cache, &codepoint, entry);
117 if (entry) {
118 // Return cached bitmap
119 static FT_Bitmap cached_result;
120 cached_result.width = entry->width;
121 cached_result.rows = entry->rows;
122 cached_result.pitch = entry->pitch;
123 cached_result.buffer = entry->bitmap_buf;
124 return &cached_result;
125 }
126
127 // Not in cache — load and render glyph
128 FT_UInt gi = FT_Get_Char_Index(face, codepoint);
129 if (!gi || FT_Load_Glyph(face, gi, FT_LOAD_RENDER) != 0) {
130 return NULL; // Glyph not found or load failed
131 }
132
133 FT_Bitmap *src_bitmap = &face->glyph->bitmap;
134 if (!src_bitmap->buffer || src_bitmap->width == 0 || src_bitmap->rows == 0 || src_bitmap->width > INT_MAX || src_bitmap->rows > INT_MAX) {
135 return NULL;
136 }
137
138 // FreeType bitmaps may use packed mono/gray pixels and either pitch
139 // direction. Normalize them once so blit_glyph can safely read one alpha
140 // byte per pixel for every cached glyph.
141 int64_t signed_pitch = src_bitmap->pitch;
142 size_t source_pitch = (size_t)(signed_pitch < 0 ? -signed_pitch : signed_pitch);
143 size_t minimum_source_pitch = 0;
144 switch (src_bitmap->pixel_mode) {
145 case FT_PIXEL_MODE_MONO:
146 minimum_source_pitch = ((size_t)src_bitmap->width + 7) / 8;
147 break;
148 case FT_PIXEL_MODE_GRAY2:
149 minimum_source_pitch = ((size_t)src_bitmap->width + 3) / 4;
150 break;
151 case FT_PIXEL_MODE_GRAY4:
152 minimum_source_pitch = ((size_t)src_bitmap->width + 1) / 2;
153 break;
154 case FT_PIXEL_MODE_GRAY:
155 minimum_source_pitch = src_bitmap->width;
156 break;
157 case FT_PIXEL_MODE_BGRA:
158 minimum_source_pitch = (size_t)src_bitmap->width * 4;
159 break;
160 default:
161 return NULL;
162 }
163 if (source_pitch == 0 || source_pitch < minimum_source_pitch || src_bitmap->rows > SIZE_MAX / source_pitch || src_bitmap->rows > SIZE_MAX / (size_t)src_bitmap->width) {
164 return NULL;
165 }
166
167 size_t bitmap_size = (size_t)src_bitmap->width * src_bitmap->rows;
168
169 // Create and populate cache entry
171 if (!entry) {
172 return NULL;
173 }
174
175 entry->codepoint = codepoint;
176 entry->bitmap_buf = SAFE_MALLOC(bitmap_size, uint8_t *);
177 if (!entry->bitmap_buf) {
178 SAFE_FREE(entry);
179 return NULL;
180 }
181
182 for (unsigned row = 0; row < src_bitmap->rows; row++) {
183 unsigned source_row = signed_pitch < 0 ? src_bitmap->rows - row - 1 : row;
184 const uint8_t *source = src_bitmap->buffer + (size_t)source_row * source_pitch;
185 uint8_t *destination = entry->bitmap_buf + (size_t)row * src_bitmap->width;
186 for (unsigned col = 0; col < src_bitmap->width; col++) {
187 switch (src_bitmap->pixel_mode) {
188 case FT_PIXEL_MODE_MONO:
189 destination[col] = (source[col / 8] & (0x80U >> (col % 8))) ? 255 : 0;
190 break;
191 case FT_PIXEL_MODE_GRAY2:
192 destination[col] = (uint8_t)(((source[col / 4] >> (6 - (col % 4) * 2)) & 0x03U) * 85U);
193 break;
194 case FT_PIXEL_MODE_GRAY4:
195 destination[col] = (uint8_t)(((source[col / 2] >> (col % 2 == 0 ? 4 : 0)) & 0x0fU) * 17U);
196 break;
197 case FT_PIXEL_MODE_GRAY:
198 destination[col] = src_bitmap->num_grays > 1 && src_bitmap->num_grays != 256 ? (uint8_t)((source[col] * 255U) / (src_bitmap->num_grays - 1)) : source[col];
199 break;
200 case FT_PIXEL_MODE_BGRA:
201 destination[col] = source[col * 4 + 3];
202 break;
203 default:
204 break;
205 }
206 }
207 }
208 entry->width = src_bitmap->width;
209 entry->rows = src_bitmap->rows;
210 entry->pitch = (int)src_bitmap->width;
211 entry->bitmap_left = face->glyph->bitmap_left;
212 entry->bitmap_top = face->glyph->bitmap_top;
213
214 // Add to renderer's per-font hash table
215 HASH_ADD_INT(r->glyph_cache, codepoint, entry);
216
217 // Return the cached bitmap
218 static FT_Bitmap new_result;
219 new_result.width = entry->width;
220 new_result.rows = entry->rows;
221 new_result.pitch = entry->pitch;
222 new_result.buffer = entry->bitmap_buf;
223 return &new_result;
224}
225
226static int screen_damage(VTermRect r, void *u) {
227 (void)r;
228 (void)u;
229 return 1;
230}
231
232static VTermScreenCallbacks g_vterm_cbs = {.damage = screen_damage};
233
239static uint32_t matrix_char_map(uint32_t ascii_char) {
240 // Matrix font glyphs: U+E900 to U+E91A (27 glyphs total)
241 const uint32_t matrix_start = 0xE900;
242 const uint32_t matrix_count = 27;
243
244 // If it's already in the PUA range, return as-is
245 if (ascii_char >= 0xE900 && ascii_char <= 0xE91A) {
246 return ascii_char;
247 }
248
249 // Map printable ASCII (32-126) to matrix glyphs
250 if (ascii_char >= 32 && ascii_char <= 126) {
251 // Cycle through available glyphs
252 // Coverage order measured from the bundled Matrix-Resurrected font at 10px.
253 // Adjacent alternatives preserve image shading when the rain mutates symbols.
254 static const uint8_t glyphs[6][4] = {{15, 18, 19, 15}, {20, 1, 26, 25}, {23, 0, 3, 13}, {12, 16, 24, 17}, {9, 4, 22, 21}, {2, 11, 14, 5}};
255 int group = digital_rain_glyph_group(ascii_char);
256 if (group >= 0)
257 return matrix_start + glyphs[group][ascii_char % 4];
258 return matrix_start + (ascii_char - 32) % matrix_count;
259 }
260
261 // Return unmapped characters as-is (will have no glyph)
262 return ascii_char;
263}
264
268static void blit_glyph(terminal_renderer_t *r, FT_Bitmap *bm, int px, int py, uint8_t fr, uint8_t fg, uint8_t fb, uint8_t br, uint8_t bg, uint8_t bb) {
269 // Clip once, outside the pixel loop, so WASM can vectorize alpha blending.
270 int first_col = px < 0 ? -px : 0;
271 int last_col = (int)bm->width;
272 if (px + last_col > r->width_px)
273 last_col = r->width_px - px;
274 int first_row = py < 0 ? -py : 0;
275 int last_row = (int)bm->rows;
276 if (py + last_row > r->height_px)
277 last_row = r->height_px - py;
278 if (first_col >= last_col || first_row >= last_row)
279 return;
280 for (int row = first_row; row < last_row; row++) {
281 const uint8_t *alpha = bm->buffer + row * bm->pitch + first_col;
282 uint8_t *line = r->framebuffer + (py + row) * r->pitch + (px + first_col) * 4;
283 for (int col = 0; col < last_col - first_col; col++) {
284 unsigned a = alpha[col];
285 if (r->is_matrix_font && fr > 64 && fg > 64 && fb > 64 && (fr > 200 || fg > 200 || fb > 200)) {
286 // A small local bloom softens pale rain heads without blurring the body.
287 int x = first_col + col;
288 unsigned glow = 0;
289 if (x > 0)
290 glow += bm->buffer[row * bm->pitch + x - 1];
291 if (x + 1 < (int)bm->width)
292 glow += bm->buffer[row * bm->pitch + x + 1];
293 if (row > 0)
294 glow += bm->buffer[(row - 1) * bm->pitch + x];
295 if (row + 1 < (int)bm->rows)
296 glow += bm->buffer[(row + 1) * bm->pitch + x];
297 a += (255 - a) * glow / (255 * 24);
298 }
299 uint8_t *dst = line + col * 4;
300 dst[0] = (uint8_t)((fr * a + br * (255 - a)) / 255);
301 dst[1] = (uint8_t)((fg * a + bg * (255 - a)) / 255);
302 dst[2] = (uint8_t)((fb * a + bb * (255 - a)) / 255);
303 dst[3] = 255;
304 }
305 }
306}
307
309 if (!cfg || !out || cfg->cols <= 0 || cfg->rows <= 0)
310 return SET_ERRNO(ERROR_INVALID_PARAM, "Missing font renderer configuration or output");
311 *out = NULL;
312 if (cfg->font_data_size > LONG_MAX || (cfg->font_data_size && !cfg->font_data))
313 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid font data or size");
315 r->cols = cfg->cols;
316 r->rows = cfg->rows;
317 r->theme = cfg->theme;
318
319 if (FT_Init_FreeType(&r->ft_lib)) {
320 SAFE_FREE(r);
321 return SET_ERRNO(ERROR_INIT, "FreeType init failed");
322 }
323
324 FT_Error face_error;
325 if (cfg->font_data && cfg->font_data_size > 0) {
326 face_error = FT_New_Memory_Face(r->ft_lib, cfg->font_data, (FT_Long)cfg->font_data_size, 0, &r->ft_face);
327 } else {
328 face_error = FT_New_Face(r->ft_lib, cfg->font_spec, 0, &r->ft_face);
329 }
330 if (face_error) {
331 FT_Done_FreeType(r->ft_lib);
332 SAFE_FREE(r);
333 if (face_error == FT_Err_Cannot_Open_Resource)
334 return SET_ERRNO(ERROR_NOT_FOUND, "Cannot open font '%s' (FreeType error %d)", cfg->font_spec, face_error);
335 // Older FreeType versions recognize an HVF SFNT wrapper, then reject its
336 // missing TrueType outline tables instead of reporting an unknown format.
337 if (face_error == FT_Err_Unknown_File_Format || face_error == FT_Err_Unimplemented_Feature || face_error == FT_Err_Locations_Missing)
339 "Unsupported font format: '%s' (FreeType error %d). HVF fonts require HVF-enabled FreeType "
340 "2.15+ on macOS 15.4+ or iOS 18.4+",
341 cfg->font_spec, face_error);
342 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid font '%s' (FreeType error %d)", cfg->font_spec, face_error);
343 }
344
345 // Some older FreeType drivers can open an SFNT container without supporting
346 // its outlines. Check the parsed table directory before accepting that face.
347 FT_ULong hvf_size = 0;
348 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;
349 const char *font_format = FT_Get_Font_Format(r->ft_face);
350 if (is_hvf) {
351 bool supported = false;
352#ifdef __APPLE__
353 if (__builtin_available(macOS 15.4, iOS 18.4, *))
354 supported = font_format && strcmp(font_format, "HVF") == 0;
355#endif
356 if (!supported) {
357 FT_Done_Face(r->ft_face);
358 FT_Done_FreeType(r->ft_lib);
359 SAFE_FREE(r);
360 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);
361 }
362 }
363 log_debug("Loaded font '%s' using FreeType format %s", cfg->font_spec, font_format ? font_format : "unknown");
364
365 // Detect if this is the matrix font (needs character mapping to Private Use Area)
366 r->is_matrix_font = (strstr(cfg->font_spec, "matrix") != NULL || strstr(cfg->font_spec, "Matrix") != NULL) || (cfg->font_data != NULL && GET_OPTION(matrix_rain));
367 if (r->is_matrix_font) {
368 log_debug("Detected matrix font - will use Private Use Area character mapping");
369 }
370
371 // Handle scalable vs bitmap fonts differently
372 // Bitmap fonts (like matrix) don't respond to FT_Set_Char_Size
373 // Instead, use FT_Set_Pixel_Sizes to request a specific pixel size
374 if (r->ft_face->num_fixed_sizes > 0) {
375 // Bitmap font: use FT_Set_Pixel_Sizes to select appropriate size (12px is reasonable for ASCII)
376 int err = FT_Set_Pixel_Sizes(r->ft_face, 12, 12);
377 log_debug("[BITMAP] FT_Set_Pixel_Sizes(12, 12) returned %d", err);
378
379 // If that fails, try FT_Select_Size as fallback
380 if (err != 0) {
381 err = FT_Select_Size(r->ft_face, 0); // Use first available strike
382 log_debug("[BITMAP FALLBACK] FT_Select_Size(0) returned %d", err);
383 }
384 if (err != 0) {
385 FT_Done_Face(r->ft_face);
386 FT_Done_FreeType(r->ft_lib);
387 SAFE_FREE(r);
388 return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' has no usable bitmap size (FreeType error %d)", cfg->font_spec, err);
389 }
390 } else {
391 // Scalable font: use FT_Set_Char_Size
392 // FT_Set_Char_Size takes 1/64pt units and DPI — supports fractional point sizes.
393 // 96 DPI is the standard screen DPI used here; the 64 factor is the 26.6 fixed-point scale.
394 int err = FT_Set_Char_Size(r->ft_face, 0, (FT_F26Dot6)(cfg->font_size_pt * 64.0), 96, 96);
395 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);
396 if (err != 0) {
397 FT_Done_Face(r->ft_face);
398 FT_Done_FreeType(r->ft_lib);
399 SAFE_FREE(r);
400 return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' cannot be sized (FreeType error %d)", cfg->font_spec, err);
401 }
402 }
403
404 // For matrix fonts, try PUA glyph first (U+E900) since ASCII chars might not have bitmap data
405 // For other fonts, start with 'M'
406 int load_err;
407 if (r->is_matrix_font) {
408 log_debug("Matrix font detected: trying PUA glyph U+E900 first");
409 load_err = FT_Load_Char(r->ft_face, 0xE900, FT_LOAD_RENDER);
410 log_debug("FT_Load_Char(U+E900) returned %d", load_err);
411
412 // If PUA glyph fails, try ASCII fallback
413 if (load_err != 0) {
414 log_debug("U+E900 failed, trying fallback character 'M'");
415 load_err = FT_Load_Char(r->ft_face, 'M', FT_LOAD_RENDER);
416 log_debug("FT_Load_Char('M') returned %d", load_err);
417 }
418 } else {
419 // For non-matrix fonts, standard approach
420 load_err = FT_Load_Char(r->ft_face, 'M', FT_LOAD_RENDER);
421 log_debug("FT_Load_Char('M', FT_LOAD_RENDER) returned %d", load_err);
422
423 // For bitmap fonts (like matrix), FT_Load_Char may fail if the character doesn't exist.
424 // Try a fallback character if 'M' fails.
425 if (load_err != 0 && r->ft_face->num_fixed_sizes > 0) {
426 log_debug("FT_Load_Char('M') failed for bitmap font, trying fallback character 'A'");
427 load_err = FT_Load_Char(r->ft_face, 'A', FT_LOAD_RENDER);
428 log_debug("FT_Load_Char('A') returned %d", load_err);
429
430 if (load_err != 0) {
431 // Last resort: try a PUA glyph for unknown bitmap fonts
432 log_debug("FT_Load_Char('A') also failed, trying PUA glyph U+E900");
433 load_err = FT_Load_Char(r->ft_face, 0xE900, FT_LOAD_RENDER);
434 log_debug("FT_Load_Char(U+E900) returned %d", load_err);
435 }
436 }
437 }
438
439 if (load_err != 0) {
440 FT_Done_Face(r->ft_face);
441 FT_Done_FreeType(r->ft_lib);
442 SAFE_FREE(r);
443 return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' cannot render glyphs (FreeType error %d)", cfg->font_spec, load_err);
444 }
445
446 // For monospace ASCII grid: use advance.x (proper character spacing) and rendered height
447 FT_Pos advance_x_26_6 = r->ft_face->glyph->advance.x;
448 log_debug("advance.x (26.6pt)=%ld", advance_x_26_6);
449
450 // Calculate cell width from font metrics
451 r->cell_w = (int)(advance_x_26_6 >> 6);
452
453 // Safeguard: for bitmap fonts, cell_w might be wrong if the font metrics are off
454 // Ensure we have a reasonable minimum width
455 if (r->cell_w <= 0) {
456 log_warn("cell_w is %d (invalid), using default 10px", r->cell_w);
457 r->cell_w = 10;
458 }
459
460 // Only add spacing to fill entire frame if --stretch is specified
461 bool stretch_mode = GET_OPTION(stretch);
462 if (stretch_mode) {
463 r->cell_w++;
464 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);
465 } else {
466 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);
467 }
468
469 // For both bitmap and scalable fonts, use the actual glyph bitmap height
470 // This ensures text doesn't overflow cells. Using size->metrics.height (line spacing)
471 // instead of bitmap.rows causes cells to be too large and text to overflow.
472 r->cell_h = r->ft_face->glyph->bitmap.rows;
473 int raw_bitmap_top = r->ft_face->glyph->bitmap_top;
474 log_debug("cell_h=%d (from bitmap.rows), raw_bitmap_top=%d", r->cell_h, raw_bitmap_top);
475
476 // Fallback: if cell_h is 0 (bitmap failed to load), use aspect ratio calculation
477 if (r->cell_h <= 0) {
478 log_warn("cell_h is 0 (FT_Load_Char failed or no bitmap), using aspect ratio fallback");
479 r->cell_h = r->cell_w * 2;
480 log_debug("FALLBACK: cell_h set to %d (2x width=%d)", r->cell_h, r->cell_w);
481 }
482
483 // Apply aspect ratio correction unless --stretch is specified
484 // Terminal characters are typically 2:1 (height:width) to appear normal
485 // BUT: only correct if the loaded glyph height is reasonably close (±30%)
486 // This prevents huge jumps from small glyphs (e.g., 8px → 32px)
487 if (!stretch_mode && r->cell_h > 0) {
488 int corrected_h = r->cell_w * 2;
489 int min_acceptable = (corrected_h * 70) / 100; // 70% of target
490 int max_acceptable = (corrected_h * 130) / 100; // 130% of target
491
492 if (r->cell_h < min_acceptable || r->cell_h > max_acceptable) {
493 // Loaded height is far from expected, apply correction
494 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);
495 r->cell_h = corrected_h;
496 } else if (corrected_h != r->cell_h) {
497 // Loaded height is close to expected, fine-tune by small amount only
498 int delta = corrected_h - r->cell_h;
499 if (delta > 4 || delta < -4) {
500 // Only apply if difference is more than 4px
501 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);
502 r->cell_h = corrected_h;
503 } else {
504 log_debug("ASPECT_RATIO: Keeping cell_h=%d (close to target %d, delta=%d)", r->cell_h, corrected_h, delta);
505 }
506 }
507 }
508
509 // Position baseline vertically within the cell.
510 // Baseline should be positioned at approximately 75% of cell height to allow proper
511 // glyph rendering with space both above and below. This prevents glyphs from being
512 // clipped at the cell boundaries.
513 //
514 // Baseline position: y_glyph = py + r->baseline - g->bitmap_top
515 // We want: 0 <= baseline - bitmap_top < cell_h (glyph fits within cell)
516 // Choose: baseline = (3 * cell_h) / 4 (positions at 75% height)
517 r->baseline = (3 * r->cell_h) / 4;
518 log_debug("baseline set to %d (75%% of cell_h=%d)", r->baseline, r->cell_h);
519
520 r->width_px = r->cols * r->cell_w;
521 r->height_px = r->rows * r->cell_h;
522 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);
523 // Pitch in bytes: each pixel is 4 bytes (RGBA), already aligned to 4-byte boundary
524 int base_pitch = r->width_px * 4;
525 r->pitch = base_pitch;
526 log_debug("PITCH_CALC: width_px=%d, base_pitch=%d, final_pitch=%d (RGBA, no padding needed)", r->width_px, base_pitch, r->pitch);
527 log_debug("Allocating framebuffer: %d bytes total (%d pitch * %d height)", (int)((size_t)r->pitch * r->height_px), r->pitch, r->height_px);
528 r->framebuffer = SAFE_MALLOC((size_t)r->pitch * r->height_px, uint8_t *);
529
530 r->vt = vterm_new(r->rows, r->cols);
531 r->vts = vterm_obtain_screen(r->vt);
532
533 // Enable UTF-8 encoding so vterm correctly parses multi-byte characters
534 vterm_set_utf8(r->vt, 1);
535
536 // Set size BEFORE reset to ensure screen is allocated with correct dimensions
537 vterm_set_size(r->vt, r->rows, r->cols);
538 log_debug("vterm_set_size called with rows=%d cols=%d", r->rows, r->cols);
539
540 vterm_screen_set_callbacks(r->vts, &g_vterm_cbs, r);
541 // Reset MUST come before any input writing to initialize state correctly
542 vterm_screen_reset(r->vts, 1);
543
544 // Verify the size was set correctly after reset
545 int vt_rows, vt_cols;
546 vterm_get_size(r->vt, &vt_rows, &vt_cols);
547 log_debug("vterm_get_size returned rows=%d cols=%d (expected %d,%d)", vt_rows, vt_cols, r->rows, r->cols);
548
549 // CRITICAL: Set size AGAIN after reset, as reset may have affected it
550 vterm_set_size(r->vt, r->rows, r->cols);
551 log_debug("vterm_set_size called AGAIN after reset");
552
553 // Initialize per-renderer glyph cache (empty, will populate on demand)
554 r->glyph_cache = NULL;
555
556 *out = r;
557 return ASCIICHAT_OK;
558}
559
561 if (!r || level < 0 || level > 10)
562 return SET_ERRNO(ERROR_INVALID_PARAM, "Zalgo raster level must be 0-10");
563 if (level && !r->zalgo_face) {
564 if (FT_New_Memory_Face(r->ft_lib, g_font_default, (FT_Long)g_font_default_size, 0, &r->zalgo_face))
565 return SET_ERRNO(ERROR_INIT, "Cannot load Zalgo combining font");
566 if (FT_Set_Pixel_Sizes(r->zalgo_face, 0, (FT_UInt)(r->cell_w * 2))) {
567 FT_Done_Face(r->zalgo_face);
568 r->zalgo_face = NULL;
569 return SET_ERRNO(ERROR_INIT, "Cannot size Zalgo combining font");
570 }
571 }
572 r->zalgo_level = level;
573 return ASCIICHAT_OK;
574}
575
577static void render_zalgo(terminal_renderer_t *r, int offset_x, int offset_y) {
578 if (!r->zalgo_level)
579 return;
580 // Reuse the glyph cache machinery with a separate cache for the combining font.
581 glyph_cache_entry_t *base_cache = r->glyph_cache;
582 r->glyph_cache = r->zalgo_cache;
583 for (int row = 0; row < r->rows; row++) {
584 for (int col = 0; col < r->cols; col++) {
585 VTermScreenCell cell;
586 vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
587 if (cell.chars[0] <= ' ' || cell.chars[0] >= 0x7f)
588 continue;
590 unsigned count = zalgo_cell_marks((uint32_t)row, (uint32_t)col, r->zalgo_level, marks);
591 VTermColor color = cell.fg;
592 vterm_screen_convert_color_to_rgb(r->vts, &color);
593 int above = 0, below = 0;
594 for (unsigned i = 0; i < count; i++) {
595 uint32_t cp = marks[i];
596 FT_Bitmap *bitmap = glyph_cache_get(r, r->zalgo_face, cp);
597 glyph_cache_entry_t *entry = NULL;
598 HASH_FIND_INT(r->glyph_cache, &cp, entry);
599 if (!bitmap || !entry)
600 continue;
601 int x = offset_x + col * r->cell_w + (r->cell_w - (int)bitmap->width) / 2;
602 int y = offset_y + row * r->cell_h + r->baseline - entry->bitmap_top;
603 if (i && cp < 0x0320) {
604 y -= above;
605 above += (int)bitmap->rows + 1;
606 } else if (i) {
607 y += below;
608 below += (int)bitmap->rows + 1;
609 }
610 for (unsigned by = 0; by < bitmap->rows; by++) {
611 int dy = y + (int)by;
612 if (dy < 0 || dy >= r->height_px)
613 continue;
614 for (unsigned bx = 0; bx < bitmap->width; bx++) {
615 int dx = x + (int)bx;
616 if (dx < 0 || dx >= r->width_px)
617 continue;
618 unsigned alpha = bitmap->buffer[by * bitmap->pitch + bx];
619 uint8_t *dst = r->framebuffer + dy * r->pitch + dx * 4;
620 dst[0] = (uint8_t)((color.rgb.red * alpha + dst[0] * (255 - alpha)) / 255);
621 dst[1] = (uint8_t)((color.rgb.green * alpha + dst[1] * (255 - alpha)) / 255);
622 dst[2] = (uint8_t)((color.rgb.blue * alpha + dst[2] * (255 - alpha)) / 255);
623 }
624 }
625 }
626 }
627 }
628 r->zalgo_cache = r->glyph_cache;
629 r->glyph_cache = base_cache;
630}
631
632asciichat_error_t term_renderer_feed(terminal_renderer_t *r, const char *ansi_frame, size_t len) {
633 if (!r || (!ansi_frame && len > 0)) {
634 return SET_ERRNO(ERROR_INVALID_PARAM, "renderer or frame is invalid");
635 }
636
637 uint64_t stage_start_ns = time_get_ns();
638 // libvterm natively implements CSI REP. Expanding those runs here turns a
639 // compact network frame into synchronous browser-main-thread work before
640 // every paint.
641 const char *frame = ansi_frame;
642 const size_t frame_len = len;
643
644 // Clear framebuffer to ensure no leftover pixels from previous frames
645 uint8_t def_fg_r, def_fg_g, def_fg_b;
646 uint8_t def_bg_r, def_bg_g, def_bg_b;
647 terminal_get_default_foreground_color(r->theme, &def_fg_r, &def_fg_g, &def_fg_b);
648 terminal_get_default_background_color(r->theme, &def_bg_r, &def_bg_g, &def_bg_b);
649 uint8_t def_bg = def_bg_r;
650 memset(r->framebuffer, def_bg, (size_t)r->pitch * r->height_px);
651
652 // Reset scrolling region and cursor position to prevent vertical shifts
653 static const char reset_sequence[] = "\033[2J\033[H\033[r\033[?7l";
654 vterm_input_write(r->vt, reset_sequence, sizeof(reset_sequence) - 1);
655
656 // Count newlines to determine CRLF conversion size
657 int newline_count = 0;
658 for (size_t i = 0; i < frame_len; i++) {
659 if (frame[i] == '\n')
660 newline_count++;
661 }
662
663 // Convert LF-only line endings to CRLF (vterm expects CRLF)
664 // This fixes cursor positioning on alternate rows
665 char *fixed_frame = SAFE_MALLOC(frame_len + (size_t)newline_count, char *);
666 if (!fixed_frame) {
667 log_error("failed to allocate memory for CRLF conversion");
668 return SET_ERRNO(ERROR_MEMORY, "CRLF conversion allocation failed");
669 }
670
671 size_t fixed_pos = 0;
672 int frame_row = 0;
673 for (size_t i = 0; i < frame_len; i++) {
674 // A video frame is a fixed grid, not a scrolling terminal transcript.
675 // A trailing newline on the bottom row must not scroll the whole image.
676 if (frame[i] == '\n' && frame_row >= r->rows - 1) {
677 continue;
678 }
679 fixed_frame[fixed_pos++] = frame[i];
680 if (frame[i] == '\n' && (i == 0 || frame[i - 1] != '\r')) {
681 // Insert carriage return before LF if not already preceded by CR
682 fixed_frame[fixed_pos - 1] = '\r';
683 fixed_frame[fixed_pos++] = '\n';
684 }
685 if (frame[i] == '\n')
686 frame_row++;
687 }
688
689 vterm_input_write(r->vt, fixed_frame, fixed_pos);
690 uint64_t parsed_ns = time_get_ns();
691 SAFE_FREE(fixed_frame);
692
693 // Calculate centering offsets to position grid in center of canvas
694 int grid_width_px = r->cols * r->cell_w;
695 int grid_height_px = r->rows * r->cell_h;
696 int offset_x = (r->width_px - grid_width_px) / 2;
697 int offset_y = (r->height_px - grid_height_px) / 2;
698
699 static int frame_count = 0;
700 static char prev_row_sigs[RENDER_DEBUG_SIGNATURE_ROWS][RENDER_DEBUG_SIGNATURE_BUFFER_SIZE] = {0}; // Store signatures of previous frame's rows
701 frame_count++;
702
703 // Log if any row signature changed to detect vertical shifts
704 if (frame_count % 10 == 0) {
706 for (int row = 0; row < r->rows && row < RENDER_DEBUG_SIGNATURE_ROWS; row++) {
707 // Get first 4 chars as signature
708 for (int col = 0; col < RENDER_DEBUG_SIGNATURE_COLUMNS && col < r->cols; col++) {
709 VTermScreenCell cell;
710 vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
711 curr_row_sigs[row][col] = (cell.chars[0] >= 32 && cell.chars[0] <= 126) ? cell.chars[0] : '.';
712 }
713 curr_row_sigs[row][RENDER_DEBUG_SIGNATURE_COLUMNS] = 0;
714 }
715 memcpy(prev_row_sigs, curr_row_sigs, sizeof(curr_row_sigs));
716 }
717
718 int glyph_rendered_count = 0;
719 int occupied_cell_count = 0;
720 // ANSI 16/256 colors are indexed. Converting them through libvterm for
721 // every cell is especially expensive in the single-threaded WASM renderer.
722 // A terminal palette has at most 256 entries and is stable for a frame.
723 uint32_t indexed_rgb[ASCII_LUMINANCE_LEVELS] = {0};
724 bool indexed_rgb_valid[ASCII_LUMINANCE_LEVELS] = {false};
725 for (int row = 0; row < r->rows; row++) {
726 for (int col = 0; col < r->cols; col++) {
727 VTermScreenCell cell;
728 vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
729
730 uint8_t fr, fg, fb, br, bg, bb;
731 if (VTERM_COLOR_IS_RGB(&cell.fg)) {
732 fr = cell.fg.rgb.red;
733 fg = cell.fg.rgb.green;
734 fb = cell.fg.rgb.blue;
735 } else if (VTERM_COLOR_IS_INDEXED(&cell.fg)) {
736 const uint8_t index = cell.fg.indexed.idx;
737 if (!indexed_rgb_valid[index]) {
738 VTermColor foreground = cell.fg;
739 vterm_screen_convert_color_to_rgb(r->vts, &foreground);
740 indexed_rgb[index] = ((uint32_t)foreground.rgb.red << 16) | ((uint32_t)foreground.rgb.green << 8) | foreground.rgb.blue;
741 indexed_rgb_valid[index] = true;
742 }
743 fr = (uint8_t)(indexed_rgb[index] >> 16);
744 fg = (uint8_t)(indexed_rgb[index] >> 8);
745 fb = (uint8_t)indexed_rgb[index];
746 } else {
747 fr = def_fg_r;
748 fg = def_fg_g;
749 fb = def_fg_b;
750 }
751
752 if (VTERM_COLOR_IS_RGB(&cell.bg)) {
753 br = cell.bg.rgb.red;
754 bg = cell.bg.rgb.green;
755 bb = cell.bg.rgb.blue;
756 } else if (VTERM_COLOR_IS_INDEXED(&cell.bg)) {
757 const uint8_t index = cell.bg.indexed.idx;
758 if (!indexed_rgb_valid[index]) {
759 VTermColor background = cell.bg;
760 vterm_screen_convert_color_to_rgb(r->vts, &background);
761 indexed_rgb[index] = ((uint32_t)background.rgb.red << 16) | ((uint32_t)background.rgb.green << 8) | background.rgb.blue;
762 indexed_rgb_valid[index] = true;
763 }
764 br = (uint8_t)(indexed_rgb[index] >> 16);
765 bg = (uint8_t)(indexed_rgb[index] >> 8);
766 bb = (uint8_t)indexed_rgb[index];
767 } else {
768 br = def_bg_r;
769 bg = def_bg_g;
770 bb = def_bg_b;
771 }
772
773 int px = offset_x + col * r->cell_w, py = offset_y + row * r->cell_h;
774 uint32_t foreground = ((uint32_t)fr << 16) | ((uint32_t)fg << 8) | fb;
775 uint32_t background = ((uint32_t)br << 16) | ((uint32_t)bg << 8) | bb;
776 // Retain the low 32 bits without overflowing the intermediate products.
777 uint32_t cell_hash = (uint32_t)((uint64_t)cell.chars[0] * UINT64_C(2654435761) ^ (uint64_t)foreground * UINT64_C(2246822519) ^ background);
778 cell_hash ^= cell_hash >> 16;
779 rendered_cell_t *cached_cell = &r->cells[cell_hash % CELL_CACHE_SIZE];
780 bool contained = px >= 0 && py >= 0 && px + r->cell_w <= r->width_px && py + r->cell_h <= r->height_px;
781 if (contained && cached_cell->valid && cached_cell->character == cell.chars[0] && cached_cell->foreground == foreground && cached_cell->background == background) {
782 for (int dy = 0; dy < r->cell_h; dy++) {
783 memcpy(r->framebuffer + (py + dy) * r->pitch + px * 4, cached_cell->pixels + dy * r->cell_w * 4, (size_t)r->cell_w * 4);
784 }
785 if (cell.chars[0] && cell.chars[0] != ' ') {
786 occupied_cell_count++;
787 glyph_rendered_count++;
788 }
789 continue;
790 }
791 // Block elements represent cell geometry, independent of font bearings and line spacing.
792 bool block = cell.chars[0] == 0x2580 || cell.chars[0] == 0x2584 || cell.chars[0] == 0x2588;
793 for (int dy = 0; dy < r->cell_h; dy++) {
794 bool block_foreground = block && (cell.chars[0] == 0x2588 || (cell.chars[0] == 0x2580 ? dy < r->cell_h / 2 : dy >= r->cell_h / 2));
795 int y = py + dy;
796 if (y < 0 || y >= r->height_px)
797 continue;
798 uint8_t *line = r->framebuffer + y * r->pitch + px * 4;
799 for (int dx = 0; dx < r->cell_w; dx++) {
800 int x = px + dx;
801 if (x < 0 || x >= r->width_px)
802 continue;
803 line[dx * 4] = block_foreground ? fr : br;
804 line[dx * 4 + 1] = block_foreground ? fg : bg;
805 line[dx * 4 + 2] = block_foreground ? fb : bb;
806 line[dx * 4 + 3] = 255;
807 }
808 }
809
810 if (block) {
811 occupied_cell_count++;
812 glyph_rendered_count++;
813 } else if (cell.chars[0] && cell.chars[0] != ' ') {
814 occupied_cell_count++;
815 // For matrix font, map ASCII characters to Private Use Area glyphs (U+E900-U+E91A)
816 uint32_t char_to_render = r->is_matrix_font ? matrix_char_map(cell.chars[0]) : cell.chars[0];
817
818 // Use per-renderer glyph cache to avoid rasterizing every glyph every frame
819 FT_Bitmap *cached_bitmap = glyph_cache_get(r, r->ft_face, char_to_render);
820 if (cached_bitmap && cached_bitmap->width > 0 && cached_bitmap->rows > 0) {
821 // Find cache entry to get positioning offsets
822 glyph_cache_entry_t *cache_entry = NULL;
823 HASH_FIND_INT(r->glyph_cache, &char_to_render, cache_entry);
824 if (cache_entry) {
825 // Overhanging glyphs must retain the normal cross-cell drawing order.
826 contained = contained && cache_entry->bitmap_left >= 0 && cache_entry->bitmap_left + cache_entry->width <= r->cell_w && r->baseline - cache_entry->bitmap_top >= 0 &&
827 r->baseline - cache_entry->bitmap_top + cache_entry->rows <= r->cell_h;
828 blit_glyph(r, cached_bitmap, px + cache_entry->bitmap_left, py + r->baseline - cache_entry->bitmap_top, fr, fg, fb, br, bg, bb);
829 glyph_rendered_count++;
830 }
831 } else if (cell.chars[0] >= 0x2800 && cell.chars[0] <= 0x28ff) {
832 // The bundled font lacks Braille. Draw its eight-dot pattern in the
833 // cell when the selected font cannot supply the requested glyph.
834 static const unsigned dot_bits[4][2] = {{0, 3}, {1, 4}, {2, 5}, {6, 7}};
835 unsigned pattern = cell.chars[0] - 0x2800;
836 int dot_w = r->cell_w / 4 > 0 ? r->cell_w / 4 : 1;
837 int dot_h = r->cell_h / 8 > 0 ? r->cell_h / 8 : 1;
838 for (int row = 0; row < 4; row++) {
839 for (int col = 0; col < 2; col++) {
840 if (!(pattern & (1U << dot_bits[row][col])))
841 continue;
842 int left = px + (2 * col + 1) * r->cell_w / 4 - dot_w / 2;
843 int top = py + (2 * row + 1) * r->cell_h / 8 - dot_h / 2;
844 for (int dy = 0; dy < dot_h; dy++) {
845 for (int dx = 0; dx < dot_w; dx++) {
846 int x = left + dx, y = top + dy;
847 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)
848 continue;
849 uint8_t *pixel = r->framebuffer + y * r->pitch + x * 4;
850 pixel[0] = fr;
851 pixel[1] = fg;
852 pixel[2] = fb;
853 pixel[3] = 255;
854 }
855 }
856 }
857 }
858 glyph_rendered_count++;
859 } else {
860 return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font cannot render Unicode character U+%04X", cell.chars[0]);
861 }
862 }
863 if (contained) {
864 if (!cached_cell->pixels)
865 cached_cell->pixels = SAFE_MALLOC((size_t)r->cell_w * r->cell_h * 4, uint8_t *);
866 if (cached_cell->pixels) {
867 for (int dy = 0; dy < r->cell_h; dy++) {
868 memcpy(cached_cell->pixels + dy * r->cell_w * 4, r->framebuffer + (py + dy) * r->pitch + px * 4, (size_t)r->cell_w * 4);
869 }
870 cached_cell->character = cell.chars[0];
871 cached_cell->foreground = foreground;
872 cached_cell->background = background;
873 cached_cell->valid = true;
874 }
875 }
876 }
877 }
878 render_zalgo(r, offset_x, offset_y);
879 uint64_t rendered_ns = time_get_ns();
880 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,
881 (double)(rendered_ns - parsed_ns) / NS_PER_MS_INT, r->cols, r->rows);
882 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);
883
884 return ASCIICHAT_OK;
885}
886
897 return r->pitch;
898}
899
901 if (!r)
902 return 0;
903 return r->cols;
904}
905
907 if (!r)
908 return 0;
909 return r->rows;
910}
911
913 if (!r)
914 return;
915 vterm_free(r->vt);
916 if (r->zalgo_face)
917 FT_Done_Face(r->zalgo_face);
918 glyph_cache_destroy(&r->zalgo_cache);
919 FT_Done_Face(r->ft_face);
920 FT_Done_FreeType(r->ft_lib);
922 glyph_cache_destroy(&r->glyph_cache);
923 for (size_t i = 0; i < CELL_CACHE_SIZE; i++)
924 SAFE_FREE(r->cells[i].pixels);
925 SAFE_FREE(r);
926}
#define SET_ERRNO(code,...)
Matrix-style digital rain effect for ASCII frames.
audio_visualization_source_t source
Definition fft.c:25
unsigned short uint16_t
unsigned int uint32_t
#define SAFE_FREE(ptr)
#define SAFE_MALLOC(size, cast)
#define SAFE_CALLOC(count, size, cast)
unsigned long long uint64_t
unsigned char uint8_t
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_NOT_FOUND
@ ERROR_MEMORY
Definition error_codes.h:55
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_INIT
Definition error_codes.h:60
@ ERROR_INVALID_PARAM
@ ERROR_NOT_SUPPORTED
Definition error_codes.h:73
#define log_warn(...)
Log a WARN message.
Definition log/log.h:615
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
#define NS_PER_MS_INT
Definition time.h:172
#define US_PER_SEC_INT
Definition time.h:177
#define GET_OPTION(field)
Definition options.h:1333
#define ASCII_LUMINANCE_LEVELS
Number of luminance levels supported (256).
Definition ascii.h:438
int digital_rain_glyph_group(uint32_t codepoint)
Font resolution and bundled font data.
const size_t g_font_default_size
const unsigned char g_font_default[]
SIMD-optimized ASCII conversion interface.
int term_renderer_get_rows(terminal_renderer_t *r)
int term_renderer_get_cols(terminal_renderer_t *r)
int term_renderer_width_px(terminal_renderer_t *r)
const uint8_t * term_renderer_pixels(terminal_renderer_t *r)
asciichat_error_t term_renderer_create(const term_renderer_config_t *cfg, terminal_renderer_t **out)
void term_renderer_destroy(terminal_renderer_t *r)
#define RENDER_DEBUG_SIGNATURE_ROWS
#define RENDER_DEBUG_SIGNATURE_COLUMNS
#define CELL_CACHE_SIZE
#define RENDER_DEBUG_SIGNATURE_BUFFER_SIZE
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)
int term_renderer_pitch(terminal_renderer_t *r)
int term_renderer_height_px(terminal_renderer_t *r)
📝 Logging API with multiple log levels and terminal output control
#define log_debug_every(interval_us, fmt,...)
Rate-limited DEBUG logging.
Definition log/log.h:743
⚙️ Unified options parsing system for ascii-chat with builder pattern and lock-free access
static bool size_t index
Definition queries.h:8
static bool size_t gotel_query_t * out
Definition queries.h:8
Terminal-to-pixel renderer and render-file output (audio + video).
struct terminal_renderer_s terminal_renderer_t
Definition renderer.h:22
term_renderer_theme_t
Terminal rendering theme.
Definition renderer.h:31
void terminal_get_default_background_color(int theme, uint8_t *r, uint8_t *g, uint8_t *b)
void terminal_get_default_foreground_color(int theme, uint8_t *r, uint8_t *g, uint8_t *b)
🔤 String Manipulation and Shell Escaping Utilities
Owns the temporary storage used by glyph cache entry. The data pointers and size or cursor fields des...
UT_hash_handle hh
uint32_t codepoint
int bitmap_left
uint8_t * bitmap_buf
int bitmap_top
int rows
int width
int pitch
const uint8_t * font_data
Definition renderer.h:44
term_renderer_theme_t theme
Definition renderer.h:41
char font_spec[PLATFORM_MAX_PATH_LENGTH]
Definition renderer.h:42
term_renderer_theme_t theme
glyph_cache_entry_t * zalgo_cache
glyph_cache_entry_t * glyph_cache
⏱️ High-precision timing utilities using sokol_time.h and uthash
unsigned zalgo_cell_marks(uint32_t row, uint32_t col, int level, uint16_t marks[ZALGO_MAX_MARKS])
Definition zalgo.c:19
#define ZALGO_MAX_MARKS
Definition zalgo.h:4