ascii.h File Reference

Go to the source code of this file.

Data Structures
struct	ascii_frame_source_t
	Frame source structure for grid layout. More...

Macros
#define	ASCII_LUMINANCE_LEVELS   256
	Number of luminance levels supported (256).
#define	ASCII_SLEEP_NS   50000L
	Sleep duration in nanoseconds between frames (50000 ns = 50 μs).
#define	ANSI_FG_PREFIX   "\033[38;2;"
	ANSI foreground color prefix (truecolor mode).
#define	ANSI_BG_PREFIX   "\033[48;2;"
	ANSI background color prefix (truecolor mode).
#define	ANSI_COLOR_SUFFIX   "m"
	ANSI color suffix.
#define	print(s)
	Print string to stdout.
#define	console_clear(fd)
	Clear console and move cursor to home position.
#define	cursor_reset(fd)
	Reset cursor to home position.
#define	ascii_clear_screen(fd)
	Clear terminal screen.
#define	ascii_zzz()
	Sleep for frame rate limiting.

Functions
asciichat_error_t	ascii_write_init (int fd, bool reset_terminal)
	Initialize ASCII write subsystem.
char *	ascii_convert (image_t *original, const ssize_t width, const ssize_t height, const bool color, const bool aspect_ratio, const bool stretch, const char *palette_chars, const char luminance_palette[ASCII_LUMINANCE_LEVELS])
	Convert image to ASCII art.
char *	ascii_convert_with_capabilities (image_t *original, const ssize_t width, const ssize_t height, const terminal_capabilities_t *caps, const bool use_aspect_ratio, const bool stretch, const char *palette_chars)
	Convert image to ASCII art with terminal capability awareness.
char *	ascii_convert_with_capabilities_fit (image_t *original, const ssize_t width, const ssize_t height, const terminal_capabilities_t *caps, const bool use_aspect_ratio, const bool stretch, const char *palette_chars, const bool contain)
char *	ascii_convert_with_capabilities_workspace (image_t *original, const ssize_t width, const ssize_t height, const terminal_capabilities_t *caps, const bool use_aspect_ratio, const bool stretch, const char *palette_chars, const bool contain, image_t **workspace)
char *	ascii_convert_with_buffers (image_t *original, const ssize_t width, const ssize_t height, const terminal_capabilities_t *caps, const bool use_aspect_ratio, const bool stretch, const char *palette_chars, const bool contain, image_t **workspace, outbuf_t *output)
char *	ascii_convert_with_buffers_stabilized (image_t *original, const ssize_t width, const ssize_t height, const terminal_capabilities_t *caps, const bool use_aspect_ratio, const bool stretch, const char *palette_chars, const bool contain, image_t **workspace, outbuf_t *output, ascii_stabilizer_t *stabilizer)
char *	image_print_with_capabilities (const image_t *image, const terminal_capabilities_t *caps, const char *palette)
	Convert image to ASCII art with terminal capabilities.
asciichat_error_t	ascii_write (const char *frame)
	Write ASCII frame to terminal.
void	ascii_write_destroy (int fd, bool reset_terminal)
	Destroy ASCII write subsystem.
char *	ascii_pad_frame_width (const char *frame, size_t pad)
	Add leading spaces (left-padding) to each line of a frame.
char *	ascii_pad_frame_height (const char *frame, size_t pad_top)
	Add blank lines (vertical padding) to center a frame vertically.
asciichat_error_t	ascii_grid_layout (int source_count, int width, int height, int *grid_cols, int *grid_rows)
char *	ascii_create_grid (ascii_frame_source_t *sources, int source_count, int width, int height, size_t *out_size)
	Create a grid layout from multiple ASCII frames.
char *	get_lum_palette (void)
	Get luminance palette for character mapping.

Variables
char	ascii_palette []
	Non-owning source reference used when laying out an ASCII frame. frame_data points to the source text and frame_size tells the compositor how many bytes are valid; the source must remain alive until layout and copy-out finish.

Function Documentation

ascii_convert_with_buffers()

char * ascii_convert_with_buffers	(	image_t *	original,
		const ssize_t	width,
		const ssize_t	height,
		const terminal_capabilities_t *	caps,
		const bool	use_aspect_ratio,
		const bool	stretch,
		const char *	palette_chars,
		const bool	contain,
		image_t **	workspace,
		outbuf_t *	output )

Borrow output from the caller-owned buffer until its next conversion or release. Both workspaces require a single owner; passing NULL output keeps owned-output semantics.

Definition at line 286 of file ascii.c.

                                                                                                                       {
  return ascii_convert_with_buffers_stabilized(original, width, height, caps, use_aspect_ratio, stretch, palette_chars,
                                               contain, workspace, output, NULL);
}

References ascii_convert_with_buffers_stabilized(), height, and width.

Referenced by ascii_convert_with_capabilities_workspace().

ascii_convert_with_buffers_stabilized()

char * ascii_convert_with_buffers_stabilized	(	image_t *	original,
		const ssize_t	width,
		const ssize_t	height,
		const terminal_capabilities_t *	caps,
		const bool	use_aspect_ratio,
		const bool	stretch,
		const char *	palette_chars,
		const bool	contain,
		image_t **	workspace,
		outbuf_t *	output,
		ascii_stabilizer_t *	stabilizer )

Convert with a history owned by this stream; reset it when the source changes.

Definition at line 293 of file ascii.c.

                                                                                                                   {
  if (original == NULL || caps == NULL) {
    log_error("Invalid parameters for ascii_convert_with_capabilities");
    return NULL;
  }
 
  // Validate original image dimensions to detect corruption
  if (original->w <= 0 || original->w > 10000 || original->h <= 0 || original->h > 10000) {
    log_error("Invalid original image dimensions detected: w=%d, h=%d (likely corrupted)", original->w, original->h);
    return NULL;
  }
 
  if (original->pixels == NULL) {
    log_error("Original image pixels pointer is NULL");
    return NULL;
  }
 
  // Start with the target dimensions requested by the user.
  ssize_t resized_width = width;
  ssize_t resized_height = height;
 
  // Both contain and cover produce a complete viewport, including any black bars.
 
  // Preserve an 8x8 sample grid for each glyph in the experimental renderer.
  bool explicit_palette = caps->palette_explicit;
  if (caps->text_renderer == ASCII_RENDERER_GLYPH && explicit_palette &&
      !ascii_glyph_palette_supported(palette_chars)) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Glyph palette contains characters without glyph masks");
    return NULL;
  }
  bool glyph_match = caps->text_renderer == ASCII_RENDERER_GLYPH && caps->render_mode != RENDER_MODE_HALF_BLOCK &&
                     resized_width > 0 && resized_height > 0 && resized_width <= IMAGE_MAX_WIDTH / 8 &&
                     resized_height <= IMAGE_MAX_HEIGHT / 8;
  if (glyph_match) {
    resized_width *= 8;
    resized_height *= 8;
  }
 
  // Half-block mode doubles height for 2x vertical resolution (AFTER aspect ratio)
  if (caps->render_mode == RENDER_MODE_HALF_BLOCK) {
    resized_height = resized_height * 2;
  }
 
  // Fitting is performed inside the pixel viewport, so ANSI padding is not needed.
  size_t pad_width = 0;
  size_t pad_height = 0;
 
  // Resize the captured frame to the aspect-correct dimensions
  if (resized_width <= 0 || resized_height <= 0) {
    log_error("Invalid dimensions for resize: width=%zd, height=%zd", resized_width, resized_height);
    return NULL;
  }
 
  // Validate dimensions fit in image_t's int fields before casting
  if (resized_width > INT_MAX || resized_height > INT_MAX) {
    log_error("Dimensions exceed INT_MAX: width=%zd, height=%zd", resized_width, resized_height);
    return NULL;
  }
 
  // PROFILING: Time image allocation and resize
  uint64_t prof_alloc_start_ns = time_get_ns();
 
  if (workspace && *workspace && ((*workspace)->w != resized_width || (*workspace)->h != resized_height)) {
    image_destroy(*workspace);
    *workspace = NULL;
  }
  image_t *resized = workspace ? *workspace : NULL;
  if (!resized)
    resized = image_new((size_t)resized_width, (size_t)resized_height);
  if (workspace)
    *workspace = resized;
  if (!resized) {
    log_error("Failed to allocate resized image");
    return NULL;
  }
 
  image_clear(resized);
 
  uint64_t prof_alloc_end_ns = time_get_ns();
 
  uint64_t prof_resize_start_ns = prof_alloc_end_ns;
 
  if (use_aspect_ratio && !stretch) {
    // Fit using terminal cells; half-block pixel height is only the sampling resolution.
    if (contain)
      image_resize_contain(original, resized, width, height);
    else
      image_resize_cover(original, resized, width, height);
  } else {
    image_resize(original, resized);
  }
 
  uint64_t prof_resize_end_ns = time_get_ns();
 
  // Check original image before resize (validate dimensions to prevent integer overflow)
  int orig_black = 0, orig_total = 0;
  if (original->w > 0 && original->w <= 10000 && original->h > 0 && original->h <= 10000) {
    int64_t total_pixels = (int64_t)original->w * original->h;
    int sample_size = (total_pixels < 1000) ? (int)total_pixels : 1000;
    for (int i = 0; i < sample_size; i++) {
      rgb_pixel_t p = original->pixels[i];
      orig_total++;
      if (p.r == 0 && p.g == 0 && p.b == 0)
        orig_black++;
    }
    log_debug_every(5 * NS_PER_SEC_INT,
                    ">>> ORIGINAL image: %d/%d pixels are black (%.1f%%), first pixel=RGB(%d,%d,%d)\n", orig_black,
                    orig_total, orig_total > 0 ? 100.0 * orig_black / orig_total : 0, original->pixels[0].r,
                    original->pixels[0].g, original->pixels[0].b);
  } else {
    log_warn("Skipping debug check: corrupted image dimensions (w=%d, h=%d)", original->w, original->h);
  }
 
  // PROFILING: Time ASCII print
  uint64_t prof_print_start_ns = prof_resize_end_ns;
 
  // DEBUG: Log dimensions going to renderer
  log_debug_every(10 * US_PER_SEC_INT, "original=%dx%d, requested=%zdx%zd, resized=%dx%d, pad=%zux%zu (mode=%d)",
                  original->w, original->h, width, height, resized->w, resized->h, pad_width, pad_height,
                  caps->render_mode);
 
  // Check if image is all black
  int black_pixels = 0, total_pixels = 0;
  for (int i = 0; i < resized->w * resized->h && i < 1000; i++) {
    rgb_pixel_t p = resized->pixels[i];
    total_pixels++;
    if (p.r == 0 && p.g == 0 && p.b == 0)
      black_pixels++;
  }
  log_debug_every(5 * NS_PER_SEC_INT,
                  ">>> Resized image check: %d/%d pixels are black (%.1f%%), first pixel=RGB(%d,%d,%d)\n", black_pixels,
                  total_pixels, total_pixels > 0 ? 100.0 * black_pixels / total_pixels : 0, resized->pixels[0].r,
                  resized->pixels[0].g, resized->pixels[0].b);
 
  // Apply the target client's filter after resizing, so it is scoped to this
  // client and never mutates the shared source frame.
  if (caps->color_filter != COLOR_FILTER_NONE) {
    const float time_seconds = (float)time_get_ns() / (float)NS_PER_SEC_INT;
    if (apply_color_filter((uint8_t *)resized->pixels, (uint32_t)resized->w, (uint32_t)resized->h,
                           (uint32_t)(resized->w * sizeof(rgb_pixel_t)), caps->color_filter, time_seconds) != 0) {
      log_warn("Failed to apply client color filter %d", caps->color_filter);
    }
  }
 
  // Use the capability-aware image printing function with client's palette
  // History belongs to this stream and is scoped to the current thread's conversion.
  ascii_stabilizer_t *active_stabilizer = NULL;
  if (stabilizer) {
    uint64_t configuration = 1469598103934665603ULL;
    const unsigned values[] = {(unsigned)caps->text_renderer,
                               (unsigned)caps->color_level,
                               (unsigned)caps->render_mode,
                               (unsigned)caps->color_filter,
                               (unsigned)explicit_palette,
                               (unsigned)use_aspect_ratio,
                               (unsigned)stretch,
                               (unsigned)contain,
                               (unsigned)original->w,
                               (unsigned)original->h};
    for (size_t i = 0; i < sizeof(values) / sizeof(values[0]); ++i) {
      configuration ^= values[i];
      // FNV multiplication intentionally wraps modulo 2^64.
      (void)__builtin_mul_overflow(configuration, 1099511628211ULL, &configuration);
    }
    if (palette_chars) {
      for (const unsigned char *p = (const unsigned char *)palette_chars; *p; ++p) {
        configuration ^= *p;
        (void)__builtin_mul_overflow(configuration, 1099511628211ULL, &configuration);
      }
    }
    size_t history_height = (size_t)height * (caps->render_mode == RENDER_MODE_HALF_BLOCK ? 2u : 1u);
    if (ascii_stabilizer_prepare(stabilizer, (size_t)width, history_height, configuration) == ASCIICHAT_OK) {
      uint64_t now = time_get_ns();
      stabilizer->elapsed_ns = stabilizer->fixed_step_ns
                                   ? stabilizer->fixed_step_ns
                                   : (stabilizer->last_timestamp_ns && now >= stabilizer->last_timestamp_ns
                                          ? now - stabilizer->last_timestamp_ns
                                          : UINT64_MAX);
      stabilizer->last_timestamp_ns = now;
      active_stabilizer = stabilizer;
    }
  }
  ascii_stabilizer_t *previous_stabilizer = ascii_stabilizer_set_target(active_stabilizer);
  outbuf_t *previous_output = ascii_render_set_output_target(output);
  ascii_color_t glyph_color = caps->color_level == TERM_COLOR_TRUECOLOR ? ASCII_COLOR_TRUE
                              : caps->color_level == TERM_COLOR_256     ? ASCII_COLOR_256
                              : caps->color_level == TERM_COLOR_16      ? ASCII_COLOR_16
                                                                        : ASCII_COLOR_NONE;
  char *ascii = glyph_match ? ascii_render_glyph_match_mode(resized, glyph_color, simd_cells_backend(),
                                                            explicit_palette ? palette_chars : NULL,
                                                            caps->render_mode == RENDER_MODE_BACKGROUND)
                            : image_print_with_capabilities(resized, caps, palette_chars);
  ascii_render_set_output_target(previous_output);
  ascii_stabilizer_set_target(previous_stabilizer);
 
  uint64_t prof_print_end_ns = time_get_ns();
 
  uint64_t alloc_time_us = time_ns_to_us(time_elapsed_ns(prof_alloc_start_ns, prof_alloc_end_ns));
  uint64_t resize_time_us = time_ns_to_us(time_elapsed_ns(prof_resize_start_ns, prof_resize_end_ns));
  uint64_t print_time_us = time_ns_to_us(time_elapsed_ns(prof_print_start_ns, prof_print_end_ns));
 
  // PROFILING: Time padding
  uint64_t prof_pad_start_ns = time_get_ns();
 
  if (!ascii) {
    log_error("Failed to convert image to ASCII using terminal capabilities");
    if (!workspace)
      image_destroy(resized);
    return NULL;
  }
 
  size_t ascii_len = strlen(ascii);
  if (ascii_len == 0) {
    log_error("Capability-aware ASCII conversion returned empty string (resized dimensions: %dx%d)", resized->w,
              resized->h);
    if (!output)
      SAFE_FREE(ascii);
    if (!workspace)
      image_destroy(resized);
    return NULL;
  }
 
  // Pixel fitting already produced the complete viewport. Return that buffer
  // directly instead of allocating two identical copies for zero padding.
  char *ascii_padded = ascii;
 
  uint64_t prof_pad_end_ns = time_get_ns();
 
  uint64_t pad_time_ns = time_elapsed_ns(prof_pad_start_ns, prof_pad_end_ns);
  log_debug_every(US_PER_SEC_INT, "ASCII_STAGE: alloc_ms=%.3f resize_ms=%.3f glyph_ms=%.3f padding_ms=%.3f bytes=%zu",
                  (double)alloc_time_us / 1000, (double)resize_time_us / 1000, (double)print_time_us / 1000,
                  (double)pad_time_ns / NS_PER_MS_INT, ascii_len);
 
  if (!workspace)
    image_destroy(resized);
 
  return ascii_padded;
}

References apply_color_filter(), ASCII_COLOR_16, ASCII_COLOR_256, ASCII_COLOR_NONE, ASCII_COLOR_TRUE, ascii_glyph_palette_supported(), ascii_render_glyph_match_mode(), ascii_render_set_output_target(), ASCII_RENDERER_GLYPH, ascii_stabilizer_prepare(), ascii_stabilizer_set_target(), ASCIICHAT_OK, rgb_pixel_t::b, ascii_stabilizer_t::elapsed_ns, ERROR_INVALID_PARAM, ascii_stabilizer_t::fixed_step_ns, rgb_pixel_t::g, image_t::h, height, image_clear(), image_destroy(), IMAGE_MAX_HEIGHT, IMAGE_MAX_WIDTH, image_new(), image_print_with_capabilities(), image_resize(), ascii_stabilizer_t::last_timestamp_ns, log_debug_every, log_error, log_warn, NS_PER_MS_INT, NS_PER_SEC_INT, image_t::pixels, rgb_pixel_t::r, SAFE_FREE, SET_ERRNO, simd_cells_backend(), time_elapsed_ns(), US_PER_SEC_INT, image_t::w, and width.

Referenced by ascii_convert_with_buffers(), and mirror_convert_frame().

ascii_convert_with_capabilities_fit()

char * ascii_convert_with_capabilities_fit	(	image_t *	original,
		const ssize_t	width,
		const ssize_t	height,
		const terminal_capabilities_t *	caps,
		const bool	use_aspect_ratio,
		const bool	stretch,
		const char *	palette_chars,
		const bool	contain )

Convert with explicit contain (true) or cover (false) viewport fitting.

Definition at line 269 of file ascii.c.

                                                                                                             {
 
  return ascii_convert_with_capabilities_workspace(original, width, height, caps, use_aspect_ratio, stretch,
                                                   palette_chars, contain, NULL);
}

References ascii_convert_with_capabilities_workspace(), height, and width.

Referenced by ascii_convert_with_capabilities().

ascii_convert_with_capabilities_workspace()

char * ascii_convert_with_capabilities_workspace	(	image_t *	original,
		const ssize_t	width,
		const ssize_t	height,
		const terminal_capabilities_t *	caps,
		const bool	use_aspect_ratio,
		const bool	stretch,
		const char *	palette_chars,
		const bool	contain,
		image_t **	workspace )

Caller owns the reusable resize image; calls using it must be serialized.

Definition at line 277 of file ascii.c.

                                                                     {
 
  return ascii_convert_with_buffers(original, width, height, caps, use_aspect_ratio, stretch, palette_chars, contain,
                                    workspace, NULL);
}

References ascii_convert_with_buffers(), height, and width.

Referenced by ascii_convert_with_capabilities_fit().

ascii_grid_layout()

asciichat_error_t ascii_grid_layout	(	int	source_count,
		int	width,
		int	height,
		int *	grid_cols,
		int *	grid_rows )

Calculate the shared grid layout before sizing source video tiles.

Definition at line 659 of file ascii.c.

                                                                                                             {
  if (source_count <= 0 || width <= 0 || height <= 0 || !grid_cols || !grid_rows)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid grid dimensions");
  // Multiple sources: create grid layout
  // Calculate grid dimensions that maximize the use of terminal space
  // Character aspect ratio: terminal chars are typically ~2x taller than wide
  float char_aspect = 2.0f;
 
  float best_score = -1.0f;
  int best_cols = 1;
  int best_rows = source_count;
 
  // Try all possible grid configurations
  for (int test_cols = 1; test_cols <= source_count; test_cols++) {
    int test_rows = (int)ceil((double)source_count / test_cols);
 
    // Skip configurations with too many empty cells
    int empty_cells = (test_cols * test_rows) - source_count;
    if (empty_cells > source_count / 2)
      continue; // Don't waste more than 50% space
 
    // Calculate the size each cell would have
    int cell_width = (width - (test_cols - 1)) / test_cols;   // -1 per separator
    int cell_height = (height - (test_rows - 1)) / test_rows; // -1 per separator
 
    // Skip if cells would be too small
    if (cell_width < 10 || cell_height < 3)
      continue;
 
    // Calculate the aspect ratio of each cell (accounting for char aspect)
    float cell_aspect = ((float)cell_width / (float)cell_height) / char_aspect;
 
    // Score based on how close to square (1:1) each video cell would be
    // This naturally adapts to any terminal size
    float aspect_score = 1.0f - fabsf(logf(cell_aspect)); // log makes it symmetric around 1
    if (aspect_score < 0)
      aspect_score = 0;
 
    // Bonus for better space utilization
    float utilization = (float)source_count / (float)(test_cols * test_rows);
 
    // For 2 clients specifically, heavily weight the aspect score
    // This makes 2 clients naturally go horizontal on wide terminals and vertical on tall ones
    float total_score;
    if (source_count == 2) {
      // For 2 clients, we want the layout that gives the most square-ish cells
      total_score = aspect_score * 0.9f + utilization * 0.1f;
    } else {
      // For 3+ clients, balance aspect ratio with space utilization
      total_score = aspect_score * 0.7f + utilization * 0.3f;
    }
 
    // Small bonus for simpler grids (prefer 2x2 over 3x1, etc.)
    if (test_cols == test_rows) {
      total_score += 0.05f; // Slight preference for square grids
    }
 
    if (total_score > best_score) {
      best_score = total_score;
      best_cols = test_cols;
      best_rows = test_rows;
    }
  }
 
  *grid_cols = best_cols;
  *grid_rows = best_rows;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, height, SET_ERRNO, and width.

Referenced by ascii_create_grid().