Video to ASCII Conversion

🖼️ Everything necessary to turn pixels into text art More...

Modules
	Video Frame Buffers
	📹 High-performance video frame management with double-buffering and lock-free operations

Files
file	ansi.c
	ANSI escape sequence utilities.
file	ansi.h
	ANSI escape sequence utilities.
file	ansi_fast.c
	⚡ Fast ANSI color code generation with SIMD-accelerated terminal output
file	ansi_fast.h
	Fast ANSI escape sequence generation.
file	ascii.c
	🖼️ Image-to-ASCII conversion with SIMD acceleration, color matching, and terminal optimization
file	ascii.h
	🖼️ ASCII Art Conversion and Output Interface
file	image.c
	🖨️ Image processing: format detection, decoding, scaling, and pixel format conversion
file	image.h
	Image Data Structures and Operations.
file	output_buffer.c
	📝 Output buffer helpers for efficient string building in ASCII rendering pipeline
file	output_buffer.h
	Dynamic Output Buffer with ANSI Sequence Support.
file	rle.c
	ANSI RLE (REP) sequence compression and expansion.
file	rle.h
	ANSI RLE (REP) sequence compression and expansion.
file	ascii_simd.c
	⚡ Main SIMD ASCII rendering dispatcher with architecture detection and fallback handling
file	ascii_simd.h
	SIMD-optimized ASCII conversion interface.
file	ascii_simd_color.c
	🎨 SIMD-accelerated color matching and palette lookup for ASCII rendering
file	avx2.c
	🚀 AVX2-accelerated ASCII rendering with 256-bit vector operations for x86_64
file	avx2.h
	AVX2-optimized ASCII rendering functions.
file	common.c
	🔧 Shared SIMD utilities: initialization, cleanup, and architecture-specific resource management
file	common.h
	Common SIMD utilities and structures.
file	neon.c
	⚡ ARM NEON-accelerated ASCII rendering with 128-bit vector operations for ARM64
file	neon.h
	NEON-optimized ASCII rendering functions.
file	sse2.c
	⚡ SSE2-accelerated ASCII rendering with 128-bit vector operations (x86 baseline)
file	sse2.h
	SSE2-optimized ASCII rendering functions.
file	ssse3.c
	🚀 SSSE3-accelerated ASCII rendering with advanced shuffle operations for x86
file	ssse3.h
	SSSE3-optimized ASCII rendering functions.
file	sve.c
	🚀 ARM SVE (Scalable Vector Extension) ASCII rendering with variable-length vectors
file	sve.h
	SVE-optimized ASCII rendering functions.

Data Structures
struct	ansi_timing_t
	Timing breakdown for performance measurement. More...
struct	ansi_rle_context_t
	Run-length encoded color output context. More...
struct	rgb_error_t
	RGB error structure for dithering. More...
struct	ascii_frame_source_t
	Frame source structure for grid layout. More...
struct	__attribute__
	RGB pixel structure. More...
struct	image_t
	Image structure. More...
struct	outbuf_t
	Dynamic output buffer (auto-expanding) More...
struct	dec3_t
	Decimal conversion cache structure (1-3 digits) More...
struct	global_dec3_cache_t
	Global decimal cache for digit conversion. More...
struct	Str
	Dynamic string buffer structure. More...
struct	RLEState
	Run-length encoding state for ANSI color optimization. More...
struct	ImageRGB
	ImageRGB structure for NEON renderers. More...
struct	simd_benchmark_t
	SIMD benchmark results structure. More...
struct	utf8_char_t
	UTF-8 character structure. More...
struct	utf8_palette_cache_s
	UTF-8 palette cache structure. 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)   fwrite(s, 1, sizeof(s) / sizeof((s)[0]), stdout)
	Print string to stdout.
#define	console_clear(fd)   (terminal_clear_screen(), terminal_cursor_home(fd))
	Clear console and move cursor to home position.
#define	cursor_reset(fd)   terminal_cursor_home(fd)
	Reset cursor to home position.
#define	ascii_clear_screen(fd)   terminal_clear_screen()
	Clear terminal screen.
#define	cursor_hide(fd)   terminal_hide_cursor(fd, true)
	Hide terminal cursor.
#define	cursor_show(fd)   terminal_hide_cursor(fd, false)
	Show terminal cursor.
#define	ascii_zzz()   nanosleep((struct timespec *)&ASCII_SLEEP_START, (struct timespec *)&ASCII_SLEEP_STOP)
	Sleep for frame rate limiting.
#define	IMAGE_MAX_WIDTH   3840
	Maximum image width (4K resolution)
#define	IMAGE_MAX_HEIGHT   2160
	Maximum image height (4K resolution)
#define	IMAGE_MAX_PIXELS_SIZE   (IMAGE_MAX_WIDTH * IMAGE_MAX_HEIGHT * sizeof(rgb_pixel_t))
	Maximum pixel data size in bytes.
#define	RAMP64_SIZE   64
	Ramp64 cache size (64 entries)

Typedefs
typedef struct utf8_palette_cache_s	utf8_palette_cache_t
	UTF-8 palette cache structure.

Enumerations
enum	ansi_color_mode_t { ANSI_MODE_FOREGROUND , ANSI_MODE_BACKGROUND , ANSI_MODE_FOREGROUND_BACKGROUND }
	Color mode for ANSI generation. More...
enum	image_alloc_method_t { IMAGE_ALLOC_SIMD = 0 , IMAGE_ALLOC_POOL = 1 }
	Pixel allocation method tracking. More...

Functions
void	ansi_fast_init (void)
	Initialize the decimal lookup table.
char *	append_truecolor_fg (char *dst, uint8_t r, uint8_t g, uint8_t b)
	Append truecolor foreground ANSI sequence.
char *	append_truecolor_bg (char *dst, uint8_t r, uint8_t g, uint8_t b)
	Append truecolor background ANSI sequence.
char *	append_truecolor_fg_bg (char *dst, uint8_t fg_r, uint8_t fg_g, uint8_t fg_b, uint8_t bg_r, uint8_t bg_g, uint8_t bg_b)
	Append truecolor foreground and background ANSI sequence.
void	ansi_rle_init (ansi_rle_context_t *ctx, char *buffer, size_t capacity, ansi_color_mode_t mode)
	Initialize run-length encoding context.
void	ansi_rle_add_pixel (ansi_rle_context_t *ctx, uint8_t r, uint8_t g, uint8_t b, char ascii_char)
	Add a pixel with run-length encoding.
void	ansi_rle_finish (ansi_rle_context_t *ctx)
	Finish RLE sequence.
void	ansi_fast_init_256color (void)
	Initialize 256-color mode lookup tables.
char *	append_256color_fg (char *dst, uint8_t color_index)
	Append 256-color foreground ANSI sequence.
uint8_t	rgb_to_256color (uint8_t r, uint8_t g, uint8_t b)
	Convert RGB to 256-color palette index.
void	ansi_fast_init_16color (void)
	Initialize 16-color mode lookup tables.
char *	append_16color_fg (char *dst, uint8_t color_index)
	Append 16-color foreground ANSI sequence.
char *	append_16color_bg (char *dst, uint8_t color_index)
	Append 16-color background ANSI sequence.
uint8_t	rgb_to_16color (uint8_t r, uint8_t g, uint8_t b)
	Convert RGB to 16-color ANSI index.
void	get_16color_rgb (uint8_t color_index, uint8_t *r, uint8_t *g, uint8_t *b)
	Get the actual RGB values for a 16-color ANSI index.
uint8_t	rgb_to_16color_dithered (int r, int g, int b, int x, int y, int width, int height, rgb_error_t *error_buffer)
	Convert RGB to 16-color with Floyd-Steinberg dithering.
char *	append_color_fg_for_mode (char *dst, uint8_t r, uint8_t g, uint8_t b, terminal_color_mode_t mode)
	Append color foreground sequence for specified mode.
asciichat_error_t	ascii_read_init (unsigned short int webcam_index)
	Initialize ASCII read subsystem (e.g., webcam)
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[256])
	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, const char luminance_palette[256])
	Convert image to ASCII art with terminal capability awareness.
asciichat_error_t	ascii_write (const char *frame)
	Write ASCII frame to terminal.
void	ascii_read_destroy (void)
	Destroy ASCII read subsystem.
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.
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.
image_t *	image_new (size_t width, size_t height)
	Create a new image with standard allocation.
void	image_destroy (image_t *p)
	Destroy an image allocated with image_new()
image_t *	image_new_from_pool (size_t width, size_t height)
	Create a new image from buffer pool.
void	image_destroy_to_pool (image_t *image)
	Destroy an image allocated from buffer pool.
void	image_clear (image_t *p)
	Clear image (set all pixels to black)
char *	image_print (const image_t *p, const char *palette)
	Print image as ASCII art (monochrome)
char *	image_print_color (const image_t *p, const char *palette)
	Print image as ASCII art with color.
char *	image_print_with_capabilities (const image_t *image, const terminal_capabilities_t *caps, const char *palette, const char luminance_palette[256])
	Print image with terminal capability awareness.
char *	image_print_256color (const image_t *image, const char *palette)
	Print image using 256-color ANSI mode.
char *	image_print_16color (const image_t *image, const char *palette)
	Print image using 16-color ANSI mode.
char *	image_print_16color_dithered (const image_t *image, const char *palette)
	Print image using 16-color ANSI mode with dithering.
char *	image_print_16color_dithered_with_background (const image_t *image, bool use_background, const char *palette)
	Print image using 16-color ANSI mode with dithering and background colors.
void	quantize_color (int *r, int *g, int *b, int levels)
	Quantize color to specified number of levels.
void	precalc_rgb_palettes (const float red, const float green, const float blue)
	Precalculate RGB palettes with color adjustment.
void	image_resize (const image_t *source, image_t *dest)
	Resize image using nearest-neighbor interpolation.
void	image_resize_interpolation (const image_t *source, image_t *dest)
	Resize image using bilinear interpolation.
char *	rgb_to_ansi_fg (int r, int g, int b)
	Convert RGB to ANSI foreground color code.
char *	rgb_to_ansi_bg (int r, int g, int b)
	Convert RGB to ANSI background color code.
void	rgb_to_ansi_8bit (int r, int g, int b, int *fg_code, int *bg_code)
	Convert RGB to 8-bit ANSI color codes.
void	ob_reserve (outbuf_t *ob, size_t need)
	Reserve buffer space for upcoming writes.
void	ob_putc (outbuf_t *ob, char c)
	Append a character to buffer.
void	ob_write (outbuf_t *ob, const char *s, size_t n)
	Append a string to buffer.
void	ob_term (outbuf_t *ob)
	Append null terminator to buffer.
void	ob_u8 (outbuf_t *ob, uint8_t v)
	Append unsigned 8-bit integer as decimal string.
void	ob_u32 (outbuf_t *ob, uint32_t v)
	Append unsigned 32-bit integer as decimal string.
void	emit_set_truecolor_fg (outbuf_t *ob, uint8_t r, uint8_t g, uint8_t b)
	Emit truecolor foreground ANSI sequence.
void	emit_set_truecolor_bg (outbuf_t *ob, uint8_t r, uint8_t g, uint8_t b)
	Emit truecolor background ANSI sequence.
void	emit_set_256_color_fg (outbuf_t *ob, uint8_t color_idx)
	Emit 256-color foreground ANSI sequence.
void	emit_set_256_color_bg (outbuf_t *ob, uint8_t color_idx)
	Emit 256-color background ANSI sequence.
void	emit_reset (outbuf_t *ob)
	Emit ANSI reset sequence.
bool	rep_is_profitable (uint32_t runlen)
	Check if run-length encoding is profitable.
void	emit_rep (outbuf_t *ob, uint32_t extra)
	Emit run-length encoded sequence.
void	emit_set_fg (outbuf_t *ob, uint8_t r, uint8_t g, uint8_t b)
	Emit foreground color sequence (auto-select mode)
void	emit_set_bg (outbuf_t *ob, uint8_t r, uint8_t g, uint8_t b)
	Emit background color sequence (auto-select mode)
char *	ansi_expand_rle (const char *input, size_t input_len)
	Expand RLE escape sequences in a string.
char *	ansi_compress_rle (const char *input, size_t input_len)
	Compress repeated characters using RLE escape sequences.
void	init_dec3 (void)
	Initialize decimal lookup table.
void	ascii_simd_init (void)
	Initialize SIMD subsystem.
void	init_default_luminance_palette (void)
	Initialize default luminance palette.
void	str_init (Str *s)
	Initialize string buffer.
void	str_free (Str *s)
	Free string buffer.
void	str_reserve (Str *s, size_t need)
	Reserve space in string buffer.
void	str_append_bytes (Str *s, const void *src, size_t n)
	Append bytes to string buffer.
void	str_append_c (Str *s, char c)
	Append character to string buffer.
void	str_printf (Str *s, const char *fmt,...)
	Append formatted string to buffer.
ImageRGB	alloc_image (int w, int h)
	Allocate a new ImageRGB (RGB8 format)
void	convert_pixels_scalar (const rgb_pixel_t *pixels, char *ascii_chars, int count, const char luminance_palette[256])
	Convert pixels to ASCII (scalar fallback)
char *	convert_pixels_scalar_with_newlines (image_t *image, const char luminance_palette[256])
	Convert image to ASCII with newlines (scalar fallback)
simd_benchmark_t	benchmark_simd_conversion (int width, int height, int iterations)
	Benchmark SIMD conversion methods (monochrome)
simd_benchmark_t	benchmark_simd_color_conversion (int width, int height, int iterations, bool background_mode)
	Benchmark SIMD color conversion methods.
simd_benchmark_t	benchmark_simd_conversion_with_source (int width, int height, int iterations, bool background_mode, const image_t *source_image, bool use_256color)
	Benchmark SIMD conversion with source image.
simd_benchmark_t	benchmark_simd_color_conversion_with_source (int width, int height, int iterations, bool background_mode, const image_t *source_image, bool use_256color)
	Benchmark SIMD color conversion with source image.
void	print_simd_capabilities (void)
	Print detected SIMD capabilities.
char *	image_print_simd (image_t *image, const char *ascii_chars)
	Print image as ASCII using SIMD (monochrome)
char *	image_print_color_simd (image_t *image, bool use_background_mode, bool use_256color, const char *ascii_chars)
	Print image as ASCII with color using SIMD.
void	set_color_quality_mode (bool high_quality)
	Set color quality mode.
bool	get_256_color_fast_path (void)
	Get 256-color fast path setting.
void	prewarm_sgr256_fg_cache (void)
	Prewarm 256-color foreground cache for benchmarks.
void	prewarm_sgr256_cache (void)
	Prewarm 256-color foreground/background cache for benchmarks.
char *	get_sgr256_fg_string (uint8_t fg, uint8_t *len_out)
	Get 256-color foreground ANSI sequence string.
char *	get_sgr256_fg_bg_string (uint8_t fg, uint8_t bg, uint8_t *len_out)
	Get 256-color foreground/background ANSI sequence string.
size_t	write_row_rep_from_arrays_enhanced (const uint8_t *fg_r, const uint8_t *fg_g, const uint8_t *fg_b, const uint8_t *bg_r, const uint8_t *bg_g, const uint8_t *bg_b, const uint8_t *fg_idx, const uint8_t *bg_idx, const char *ascii_chars, int width, char *dst, size_t cap, bool is_truecolor)
	Enhanced REP compression writer.
void	build_ramp64 (uint8_t ramp64[64], const char *ascii_chars)
	Build 64-entry character ramp cache.
double	calculate_cache_eviction_score (uint64_t last_access_time, uint32_t access_count, uint64_t creation_time, uint64_t current_time)
	Calculate cache eviction score.
uint64_t	get_current_time_ns (void)
	Get current time in nanoseconds.
utf8_palette_cache_t *	get_utf8_palette_cache (const char *ascii_chars)
	Get or create UTF-8 palette cache.
void	build_utf8_luminance_cache (const char *ascii_chars, utf8_char_t cache[256])
	Build UTF-8 luminance cache.
void	build_utf8_ramp64_cache (const char *ascii_chars, utf8_char_t cache64[64], uint8_t char_index_ramp[64])
	Build UTF-8 ramp64 cache.
void	simd_caches_destroy_all (void)
	Destroy all SIMD caches.
bool	has_sse2_support (void)
	Check if SSE2 is supported.
bool	has_ssse3_support (void)
	Check if SSSE3 is supported.
bool	has_avx2_support (void)
	Check if AVX2 is supported.
bool	has_neon_support (void)
	Check if NEON is supported.
bool	has_sve_support (void)
	Check if SVE is supported.
char *	append_sgr_truecolor_fg (char *dst, uint8_t r, uint8_t g, uint8_t b)
	Append truecolor foreground SGR sequence.
char *	append_sgr_truecolor_bg (char *dst, uint8_t r, uint8_t g, uint8_t b)
	Append truecolor background SGR sequence.
char *	append_sgr_truecolor_fg_bg (char *dst, uint8_t fr, uint8_t fg, uint8_t fb, uint8_t br, uint8_t bg, uint8_t bb)
	Append truecolor foreground and background SGR sequence.
char *	append_sgr_reset (char *dst)
	Append ANSI reset sequence.
size_t	write_rgb_triplet (uint8_t value, char *dst)
	Write decimal RGB triplet using dec3 cache.

Variables
dec3_t	dec3 [256]
	Access to internal decimal lookup table for testing.
char	ascii_palette []
	Default ASCII palette characters.
uint8_t	dec3_t::len
char	dec3_t::s [3]
dec3_t	global_dec3_cache_t::dec3_table [256]
bool	global_dec3_cache_t::dec3_initialized
global_dec3_cache_t	g_dec3_cache
	Global decimal cache instance.
char	g_default_luminance_palette [256]
	Default luminance palette (256 characters)
char *	Str::data
size_t	Str::len
size_t	Str::cap
int	RLEState::cFR
int	RLEState::cFG
int	RLEState::cFB
int	RLEState::cBR
int	RLEState::cBG
int	RLEState::cBB
int	RLEState::runLen
int	RLEState::seeded
int	ImageRGB::w
int	ImageRGB::h
uint8_t *	ImageRGB::pixels
double	simd_benchmark_t::scalar_time
double	simd_benchmark_t::sse2_time
double	simd_benchmark_t::ssse3_time
double	simd_benchmark_t::avx2_time
double	simd_benchmark_t::neon_time
double	simd_benchmark_t::sve_time
double	simd_benchmark_t::speedup_best
const char *	simd_benchmark_t::best_method
char	utf8_char_t::utf8_bytes [4]
uint8_t	utf8_char_t::byte_len
uint32_t	utf8_palette_cache_s::key
utf8_char_t	utf8_palette_cache_s::cache [256]
utf8_char_t	utf8_palette_cache_s::cache64 [64]
uint8_t	utf8_palette_cache_s::char_index_ramp [64]
char	utf8_palette_cache_s::palette_hash [64]
bool	utf8_palette_cache_s::is_valid
_Atomic uint64_t	utf8_palette_cache_s::last_access_time
_Atomic uint32_t	utf8_palette_cache_s::access_count
uint64_t	utf8_palette_cache_s::creation_time
size_t	utf8_palette_cache_s::heap_index
double	utf8_palette_cache_s::cached_score
UT_hash_handle	utf8_palette_cache_s::hh

Luminance Calculation Constants
#define	LUMA_RED   77
	Luminance red coefficient (0.299 * 256 = 77)
#define	LUMA_GREEN   150
	Luminance green coefficient (0.587 * 256 = 150)
#define	LUMA_BLUE   29
	Luminance blue coefficient (0.114 * 256 = 29)
#define	LUMA_THRESHOLD   128
	Luminance threshold for rounding.

Cache Eviction Algorithm Parameters
#define	CACHE_FREQUENCY_DECAY_TIME   300.0
	Frequency bonus decay time (5 minutes in seconds)
#define	CACHE_RECENCY_SCALE   60.0
	Recency importance scale (1 minute in seconds)
#define	CACHE_RECENT_ACCESS_THRESHOLD   10
	Recent access protection threshold (10 seconds)
#define	CACHE_MAX_LIFETIME   3600
	Maximum cache lifetime (1 hour in seconds)
#define	CACHE_MIN_ACCESS_THRESHOLD   3
	Minimum accesses for frequency protection.

Detailed Description

🖼️ Everything necessary to turn pixels into text art

This header provides optimized ANSI escape sequence generation using precomputed lookup tables and run-length encoding for efficient terminal output.

The interface provides:

• Fast truecolor ANSI sequence generation
• Run-length encoded color output
• 256-color and 16-color ANSI mode support
• Floyd-Steinberg dithering for color approximation
• Terminal capability-aware color functions

Note

Uses precomputed decimal lookup tables for maximum performance.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

This header provides comprehensive functions for converting images to ASCII art and outputting frames to the terminal. Supports multiple color modes, aspect ratio preservation, capability-aware conversion, and frame layout management.

CORE FEATURES:

• Image-to-ASCII conversion with color support
• Terminal capability-aware conversion (auto-selects optimal color mode)
• Aspect ratio preservation for proper image proportions
• Terminal frame output and management
• Frame padding and layout utilities (horizontal and vertical)
• Grid layout for multiple frames (multi-user support)
• Buffer pool integration for efficient memory management
• SIMD-optimized conversion for performance

CONVERSION MODES:

The system supports multiple conversion modes:

• Standard conversion: Basic image-to-ASCII with optional color
• Capability-aware: Automatically selects best color mode for terminal
• Aspect ratio preservation: Maintains image proportions (terminal correction)
• Stretch mode: Fills terminal dimensions exactly (may distort proportions)

FRAME MANAGEMENT:

Frame management includes:

• Terminal initialization and cleanup
• Frame output to terminal
• Frame padding (horizontal and vertical)
• Grid layout for multiple frames
• Frame source management

Note

All conversion functions return allocated strings that must be freed.

Terminal initialization functions must be matched with cleanup.

Capability-aware conversion is recommended for optimal results.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

This header provides comprehensive image data structures and operations for ascii-chat. Supports RGB images with standard and SIMD-optimized formats for efficient image processing and ASCII art conversion.

CORE FEATURES:

• RGB image data structures (packed and SIMD-aligned)
• Image allocation and memory management
• Buffer pool integration for video pipeline efficiency
• Image-to-ASCII conversion with multiple color modes
• Color quantization and palette generation
• Image resizing (nearest-neighbor and bilinear interpolation)
• ANSI color code generation and conversion
• Dithering support for improved color accuracy

IMAGE FORMATS:

The system supports:

• Standard RGB24 format (packed, 3 bytes per pixel)
• SIMD-aligned RGB format (4-byte aligned for NEON/AVX optimization)
• Maximum 4K resolution (3840x2160)
• Memory-efficient buffer pool allocation

COLOR MODES:

ASCII conversion supports multiple color modes:

• Monochrome: No color, character-based only
• 16-color: Standard ANSI colors
• 256-color: Extended ANSI palette
• Truecolor: 24-bit RGB (terminal-dependent)
• Dithering: Floyd-Steinberg dithering for color accuracy

Note

All image allocation functions must be matched with corresponding destroy functions (image_destroy() or image_destroy_to_pool()).

ASCII conversion functions return allocated strings that must be freed by the caller.

Image structures are compatible with webcam capture (image_t).

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

This header provides a dynamic output buffer system with automatic expansion and optimized ANSI escape sequence emission functions. The buffer is designed for efficient ASCII art frame construction and terminal output.

CORE FEATURES:

• Auto-expanding output buffer (grows as needed)
• Efficient buffer management operations
• Optimized ANSI escape sequence emission
• Run-length encoding (RLE) support for compression
• Color mode auto-selection (16-color, 256-color, truecolor)
• Integer-to-string conversion utilities

BUFFER MANAGEMENT:

The output buffer automatically expands when space is needed:

• Initial capacity is allocated on first reservation
• Buffer doubles in size when capacity is exceeded
• Memory is allocated on-demand (no upfront allocation)
• Buffer ownership: caller must free buffer when done

ANSI ESCAPE SEQUENCES:

The system emits ANSI escape sequences for:

• Color output (foreground and background)
• Cursor control and positioning
• Reset and formatting codes
• Run-length encoding for repeated characters

COLOR MODE AUTO-SELECTION:

Color emission functions automatically select optimal mode:

• 16-color: Uses standard ANSI color codes (0-15)
• 256-color: Uses extended palette (16-255)
• Truecolor: Uses 24-bit RGB escape sequences

Note

All buffer operations ensure null-terminated strings.

Buffer memory must be freed by caller using free() on buf pointer.

ANSI sequences are optimized for minimal terminal I/O.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

This module provides functions for working with ANSI RLE (Run-Length Encoding) escape sequences. The REP sequence (CSI Ps b) repeats the preceding graphic character Ps times.

RLE FORMAT:

The ANSI REP sequence format is: ESC [ N b

• ESC (0x1b) - Escape character
• [ - CSI introducer
• N - Decimal repeat count (how many times to repeat)
• b - REP command character

Example: "A\x1b[3b" means "A" followed by 3 more "A"s = "AAAA"

USE CASES:

• Compression: Reduce bandwidth for ASCII art with repeated characters
• Expansion: Convert RLE to plain text for file output or non-RLE terminals

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

December 2025

This header provides SIMD-optimized functions for converting images to ASCII art. Supports multiple architectures including SSE2, SSSE3, AVX2 (x86), NEON (ARM), and SVE (ARM).

The interface provides:

• SIMD initialization and setup
• Architecture-specific rendering functions
• Benchmarking utilities
• Cache management
• UTF-8 character handling

Note

SIMD support is automatically detected and enabled based on CPU capabilities. CMake controls SIMD levels via ENABLE_SIMD_* options.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

This header provides common utilities, cache systems, and helper functions shared across all SIMD implementations.

The interface provides:

• UTF-8 character caching system
• Cache eviction algorithms
• Architecture capability detection
• ANSI color sequence generation
• Helper functions for decimal conversion

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

This header provides NEON (Advanced SIMD) optimized functions for converting images to ASCII art on ARM processors.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

August 2025

This header provides SSE2 (Streaming SIMD Extensions 2) optimized functions for converting images to ASCII art on x86-64 CPUs.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

August 2025

This header provides SSSE3 (Supplemental Streaming SIMD Extensions 3) optimized functions for converting images to ASCII art on x86-64 CPUs.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

August 2025

This header provides SVE (Scalable Vector Extension) optimized functions for converting images to ASCII art on ARM processors with SVE support.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

August 2025

video README

The video module converts RGB image data into ASCII art suitable for terminal display, with SIMD-optimized processing for real-time video conversion at 60+ FPS.

Overview

ascii-chat renders live video as ASCII art in the terminal by:

1. Capturing RGB frames from webcam (1920x1080 or configured resolution)
2. Scaling frames to terminal dimensions (typically 80x24 to 200x60)
3. Converting RGB pixels to grayscale luminance
4. Mapping luminance values to ASCII characters from a palette
5. Optionally preserving color information via ANSI escape sequences
6. Generating optimized ANSI output for terminal rendering
7. Minimizing escape sequences to reduce bandwidth and rendering time

The module is highly optimized using SIMD instructions, achieving:

• 60+ FPS for 1920x1080 → 160x45 conversion
• <5% CPU usage on modern processors
• Sub-millisecond conversion latency

Features

Rendering Modes:

• Full-block mode: One character per pixel (standard resolution)
• Half-block mode: Two pixels per character using ▀ and ▄ (2x vertical resolution)
• Color mode: Preserves RGB color via ANSI 24-bit true color escape sequences
• Monochrome mode: Grayscale ASCII art using luminance only

SIMD Acceleration:

• SSE2: 16-byte parallel processing (x86_64 baseline)
• SSSE3: Enhanced shuffle operations for pixel reordering
• AVX2: 32-byte parallel processing (2x throughput vs SSE2)
• NEON: 16-byte parallel processing (ARM/ARM64)
• SVE: Scalable vector processing (ARM v8.2+)
• Runtime CPU detection: Automatically selects best SIMD level

Grid Layouts:

• Multi-client video grid (2x2, 3x3, up to 9 clients)
• Automatic aspect ratio correction for each grid cell
• Border characters between grid cells
• Client ID labels for each video stream

Palette Support:

• Customizable ASCII character sets
• UTF-8 multi-byte character support
• Built-in palettes: standard, dense, blocks, custom
• Brightness-based character selection

Aspect Ratio Correction:

• Terminal characters are ~2:1 height:width ratio
• Automatic scaling to maintain proper aspect ratio
• Prevents stretched/squished video

Rendering Pipeline

1. Image Scaling

Resize RGB image from webcam resolution to terminal dimensions:

• Input: RGB24 image (e.g., 1920x1080 = 6,220,800 bytes)
• Output: Scaled RGB24 image (e.g., 160x45 = 21,600 bytes)
• Algorithm: Bilinear interpolation for smooth scaling
• SIMD: Process 16 pixels at a time (SSE2) or 32 pixels (AVX2)
• Performance: ~200 µs for 1920x1080 → 160x45 on modern CPU

2. Brightness Calculation

Convert RGB pixels to luminance (grayscale):

• Formula: Y = 0.299*R + 0.587*G + 0.114*B (BT.601 standard)
• SIMD: Process 16 RGB triplets in parallel
• Input: RGB24 array (3 bytes per pixel)
• Output: Y8 array (1 byte per pixel)
• Performance: ~50 µs for 160x45 image

SIMD implementation (SSE2 example):

// Load 16 RGB pixels (48 bytes)
__m128i r = _mm_loadu_si128((__m128i*)(rgb + 0));  // R values
__m128i g = _mm_loadu_si128((__m128i*)(rgb + 16)); // G values
__m128i b = _mm_loadu_si128((__m128i*)(rgb + 32)); // B values
 
// Apply BT.601 coefficients (0.299, 0.587, 0.114)
__m128i y = _mm_add_epi16(
    _mm_mullo_epi16(r, _mm_set1_epi16(77)),   // 0.299 * 256 ≈ 77
    _mm_add_epi16(
        _mm_mullo_epi16(g, _mm_set1_epi16(150)), // 0.587 * 256 ≈ 150
        _mm_mullo_epi16(b, _mm_set1_epi16(29))   // 0.114 * 256 ≈ 29
    )
);
 
// Shift right by 8 to get final Y values
y = _mm_srli_epi16(y, 8);

3. Palette Mapping

Map brightness values to ASCII characters:

• Input: Luminance value (0-255)
• Output: ASCII character from palette
• Palette example: " .:-=+*#%@" (10 characters, dark to bright)
• Mapping: luminance / (256 / palette_length)
• SIMD: Lookup table with SSSE3 shuffle instruction

Half-block rendering uses special logic:

• Combines two vertically adjacent pixels into one character
• Uses ▀ (upper half block), ▄ (lower half block), or █ (full block)
• Effectively doubles vertical resolution
• Example: 80x48 terminal displays 80x96 effective resolution

4. ANSI Escape Sequence Generation

Generate optimized ANSI sequences for terminal:

• Color changes only when pixel color changes (stateful tracking)
• Cursor movement optimized (relative vs absolute positioning)
• Typical escape sequence: \x1b[38;2;R;G;Bm (24-bit color)
• Output buffering to minimize write() syscalls
• Pre-allocated buffer pool to avoid malloc overhead

Optimization techniques:

• Delta encoding: Only emit changes from previous frame
• Run-length encoding: Combine consecutive identical characters
• Color caching: Remember last foreground/background color
• Escape sequence caching: Pre-compute common sequences

Example output:

\x1b[38;2;255;128;64m###\x1b[38;2;200;100;50m***\x1b[38;2;150;75;37m+++

5. Terminal Output

Write ANSI output to terminal:

• Single write() call per frame (buffered output)
• Double-buffering: Compose frame while displaying previous
• Cursor hiding during frame update (reduces flicker)
• Cursor positioning to (1,1) for each frame
• Terminal raw mode for direct output control

SIMD Optimizations

SSE2 (x86_64 Baseline)

Capabilities:

• 128-bit vector registers (XMM0-XMM15)
• Process 16 bytes or 8 int16 or 4 int32 simultaneously
• Integer arithmetic, logic, compare operations
• Available on all x86_64 CPUs

Performance:

• RGB to luminance: ~4x speedup vs scalar
• Palette lookup: ~8x speedup vs scalar
• Frame conversion: ~60 FPS for 1920x1080 → 160x45

SSSE3 (Supplemental SSE3)

Additional capabilities beyond SSE2:

• PSHUFB: Arbitrary byte shuffle within 128-bit vector
• Enables fast palette lookup via table shuffle
• Horizontal operations for pixel combining

Performance improvement:

• Palette lookup: ~12x speedup vs scalar (1.5x vs SSE2)
• Reduced instruction count for complex permutations

AVX2 (Advanced Vector Extensions 2)

Capabilities:

• 256-bit vector registers (YMM0-YMM15)
• Process 32 bytes or 16 int16 or 8 int32 simultaneously
• Double throughput vs SSE2 for same operations
• Available on Intel Haswell+ (2013), AMD Excavator+ (2015)

Performance:

• RGB to luminance: ~8x speedup vs scalar (2x vs SSE2)
• Frame conversion: ~90 FPS for 1920x1080 → 160x45
• Reduced loop overhead (process 2x data per iteration)

NEON (ARM)

Capabilities:

• 128-bit vector registers (Q0-Q15 or D0-D31)
• Process 16 bytes or 8 int16 or 4 int32 simultaneously
• Similar performance to SSE2 on equivalent clock speeds
• Available on ARM Cortex-A series, Apple Silicon

Performance on Apple M1:

• RGB to luminance: ~6x speedup vs scalar
• Frame conversion: ~120 FPS for 1920x1080 → 160x45 (higher clock)

SVE (ARM Scalable Vector Extension)

Capabilities:

• Scalable vectors: 128-bit to 2048-bit (implementation defined)
• Future-proof: Code runs on any SVE vector length
• Predicate registers for advanced masking
• Available on ARM v8.2+ (AWS Graviton3, Fujitsu A64FX)

Performance potential:

• 512-bit vectors: ~4x SSE2 throughput
• Automatically scales with future CPU generations

Runtime CPU Detection

ascii-chat automatically detects and uses the best SIMD level:

// At startup, detect CPU capabilities
if (cpu_has_avx2()) {
    ascii_convert = ascii_convert_avx2;  // Best performance
} else if (cpu_has_ssse3()) {
    ascii_convert = ascii_convert_ssse3;
} else if (cpu_has_sse2()) {
    ascii_convert = ascii_convert_sse2;  // Baseline x86_64
} else if (cpu_has_neon()) {
    ascii_convert = ascii_convert_neon;  // ARM
} else {
    ascii_convert = ascii_convert_scalar; // Fallback
}

Usage Examples

Basic Conversion

// Initialize ASCII converter
ascii_context_t ascii_ctx;
ascii_config_t config = {
    .width = 160,
    .height = 45,
    .palette = " .:-=+*#%@",
    .color = true,
    .half_blocks = false
};
ascii_init(&ascii_ctx, &config);
 
// Convert RGB frame to ASCII
uint8_t *rgb_data = ...; // From webcam (1920x1080 RGB24)
char *ascii_output;
size_t output_len;
ascii_convert(&ascii_ctx, rgb_data, &ascii_output, &output_len);
 
// Write to terminal
write(STDOUT_FILENO, "\x1b[2J\x1b[H", 7); // Clear screen, home cursor
write(STDOUT_FILENO, ascii_output, output_len);
 
// Cleanup
ascii_destroy(&ascii_ctx);

Half-Block Mode

// Half-block mode for 2x vertical resolution
ascii_config_t config = {
    .width = 80,
    .height = 48,  // Will show 80x96 effective resolution
    .palette = " ▀▄█",  // Special half-block characters
    .color = true,
    .half_blocks = true
};
ascii_init(&ascii_ctx, &config);
 
// Conversion combines vertical pixel pairs
ascii_convert(&ascii_ctx, rgb_data, &ascii_output, &output_len);

Multi-Client Grid

// 2x2 grid for 4 clients
ascii_grid_config_t grid_config = {
    .grid_width = 2,
    .grid_height = 2,
    .cell_width = 80,
    .cell_height = 24,
    .border_char = '|',
    .show_labels = true
};
ascii_grid_t grid;
ascii_grid_init(&grid, &grid_config);
 
// Render each client's frame to grid cell
for (int i = 0; i < 4; i++) {
    ascii_grid_set_cell(&grid, i, client_frames[i], client_labels[i]);
}
 
// Composite final grid output
char *grid_output;
size_t grid_len;
ascii_grid_render(&grid, &grid_output, &grid_len);
 
write(STDOUT_FILENO, grid_output, grid_len);
ascii_grid_destroy(&grid);

Performance Benchmarks

Measured on Intel i7-10700K @ 3.8 GHz, 1920x1080 → 160x45 conversion:

Implementation	FPS	Latency	CPU %
Scalar	15	66 ms	25%
SSE2	60	16 ms	6%
SSSE3	75	13 ms	5%
AVX2	90	11 ms	4%

Measured on Apple M1 (ARM NEON):

• NEON: 120 FPS, 8 ms latency, 5% CPU

Memory usage:

• RGB frame buffer: 6 MB (1920x1080x3)
• Scaled frame: 21 KB (160x45x3)
• ASCII output: ~50 KB (with ANSI color codes)
• Total: ~6.1 MB per frame

Terminal Compatibility

ascii-chat supports various terminal features:

True Color (24-bit RGB):

• Supported: iTerm2, Alacritty, Windows Terminal, GNOME Terminal 3.16+
• Escape sequence: \x1b[38;2;R;G;Bm (foreground), \x1b[48;2;R;G;Bm (background)
• Falls back to 256-color if true color unavailable

256-Color Mode:

• Supported: Most modern terminals
• Escape sequence: \x1b[38;5;Nm where N is 0-255
• Color palette approximation for RGB values

UTF-8 Support:

• Required for half-block characters (▀▄█)
• Required for custom Unicode palettes
• Automatic detection via $LANG and $LC_ALL

Terminal Size Detection:

• Uses TIOCGWINSZ ioctl on POSIX (lib/platform/posix/terminal.c)
• Uses GetConsoleScreenBufferInfo on Windows (lib/platform/windows/terminal.c)
• Falls back to $COLUMNS and $LINES environment variables
• Default: 80x24 if detection fails

See also

video/ascii.h

video/ansi_fast.h

video/simd/ascii_simd.h

video/output_buffer.h

palette.h

Macro Definition Documentation

ANSI_BG_PREFIX

#define ANSI_BG_PREFIX   "\033[48;2;"

#include <ascii.h>

ANSI background color prefix (truecolor mode)

ANSI escape sequence prefix for 24-bit truecolor background colors. Format: ESC[48;2;r;g;bm (where r, g, b are RGB values).

Note

Use with ANSI_COLOR_SUFFIX to form complete escape sequence.

Example: ANSI_BG_PREFIX "255;0;0" ANSI_COLOR_SUFFIX (red background).

Definition at line 471 of file ascii.h.

ANSI_COLOR_SUFFIX

#define ANSI_COLOR_SUFFIX   "m"

#include <ascii.h>

ANSI color suffix.

ANSI escape sequence suffix for color escape sequences. Used with ANSI_FG_PREFIX or ANSI_BG_PREFIX to form complete escape sequences.

Note

Format: prefix + RGB + suffix = complete ANSI sequence.

Example: "\033[38;2;255;0;0m" (red foreground).

Definition at line 485 of file ascii.h.

ANSI_FG_PREFIX

#define ANSI_FG_PREFIX   "\033[38;2;"

#include <ascii.h>

ANSI foreground color prefix (truecolor mode)

ANSI escape sequence prefix for 24-bit truecolor foreground colors. Format: ESC[38;2;r;g;bm (where r, g, b are RGB values).

Note

Use with ANSI_COLOR_SUFFIX to form complete escape sequence.

Example: ANSI_FG_PREFIX "255;0;0" ANSI_COLOR_SUFFIX (red foreground).

Definition at line 458 of file ascii.h.

ascii_clear_screen

#define ascii_clear_screen

(

fd

)

terminal_clear_screen()

#include <ascii.h>

Clear terminal screen.

Parameters

fd	File descriptor for terminal

Clears terminal screen without moving cursor. Equivalent to terminal_clear_screen().

Definition at line 546 of file ascii.h.

ASCII_LUMINANCE_LEVELS

#define ASCII_LUMINANCE_LEVELS   256

#include <ascii.h>

Number of luminance levels supported (256)

Number of luminance levels used for character mapping. Each pixel's brightness value (0-255) maps to a character in the luminance palette.

Note

256 levels correspond to 8-bit pixel brightness values.

Luminance palette must have 256 elements.

Definition at line 427 of file ascii.h.

ASCII_SLEEP_NS

#define ASCII_SLEEP_NS   50000L

#include <ascii.h>

Sleep duration in nanoseconds between frames (50000 ns = 50 μs)

Sleep duration between frame outputs for frame rate limiting. Used to prevent excessive terminal I/O and control frame rate.

Note

50000 nanoseconds = 50 microseconds = 0.05 milliseconds

Used for frame rate limiting in video playback.

Definition at line 440 of file ascii.h.

ascii_zzz

#define ascii_zzz

(

)

nanosleep((struct timespec *)&ASCII_SLEEP_START, (struct timespec *)&ASCII_SLEEP_STOP)

#include <ascii.h>

Sleep for frame rate limiting.

Sleeps for a short duration (500 nanoseconds) to limit frame rate and prevent excessive terminal I/O. Uses nanosleep() for precise timing control.

Note

Sleep duration: 500 nanoseconds (very short, minimal overhead)

Used between frame outputs for rate limiting.

May not be needed on all systems (depends on terminal I/O speed).

Definition at line 602 of file ascii.h.

CACHE_FREQUENCY_DECAY_TIME

#define CACHE_FREQUENCY_DECAY_TIME   300.0

#include <common.h>

Frequency bonus decay time (5 minutes in seconds)

Definition at line 42 of file video/simd/common.h.

CACHE_MAX_LIFETIME

#define CACHE_MAX_LIFETIME   3600

#include <common.h>

Maximum cache lifetime (1 hour in seconds)

Definition at line 48 of file video/simd/common.h.

CACHE_MIN_ACCESS_THRESHOLD

#define CACHE_MIN_ACCESS_THRESHOLD   3

#include <common.h>

Minimum accesses for frequency protection.

Definition at line 50 of file video/simd/common.h.

CACHE_RECENCY_SCALE

#define CACHE_RECENCY_SCALE   60.0

#include <common.h>

Recency importance scale (1 minute in seconds)

Definition at line 44 of file video/simd/common.h.

CACHE_RECENT_ACCESS_THRESHOLD

#define CACHE_RECENT_ACCESS_THRESHOLD   10

#include <common.h>

Recent access protection threshold (10 seconds)

Definition at line 46 of file video/simd/common.h.

console_clear

#define console_clear

(

fd

)

(terminal_clear_screen(), terminal_cursor_home(fd))

#include <ascii.h>

Clear console and move cursor to home position.

Parameters

fd	File descriptor for terminal

Clears terminal screen and moves cursor to home position (top-left). Equivalent to terminal_clear_screen() followed by terminal_cursor_home().

Definition at line 524 of file ascii.h.

cursor_hide

#define cursor_hide

(

fd

)

terminal_hide_cursor(fd, true)

#include <ascii.h>

Hide terminal cursor.

Parameters

fd	File descriptor for terminal

Hides terminal cursor for clean ASCII art display. Equivalent to terminal_hide_cursor(fd, true).

Definition at line 557 of file ascii.h.

cursor_reset

#define cursor_reset

(

fd

)

terminal_cursor_home(fd)

#include <ascii.h>

Reset cursor to home position.

Parameters

fd	File descriptor for terminal

Moves cursor to home position (top-left, row 1, column 1). Equivalent to terminal_cursor_home().

Definition at line 535 of file ascii.h.

cursor_show

#define cursor_show

(

fd

)

terminal_hide_cursor(fd, false)

#include <ascii.h>

Show terminal cursor.

Parameters

fd	File descriptor for terminal

Shows terminal cursor. Equivalent to terminal_hide_cursor(fd, false).

Definition at line 568 of file ascii.h.

IMAGE_MAX_HEIGHT

#define IMAGE_MAX_HEIGHT   2160

#include <image.h>

Maximum image height (4K resolution)

Maximum supported image height in pixels. Set to 2160 pixels (4K UHD height) to support high-resolution video capture.

Note

Larger images may exceed memory limits.

Video pipeline may enforce lower limits for performance.

Definition at line 177 of file video/image.h.

IMAGE_MAX_PIXELS_SIZE

#define IMAGE_MAX_PIXELS_SIZE   (IMAGE_MAX_WIDTH * IMAGE_MAX_HEIGHT * sizeof(rgb_pixel_t))

#include <image.h>

Maximum pixel data size in bytes.

Maximum size in bytes for pixel data array. Calculated as: IMAGE_MAX_WIDTH * IMAGE_MAX_HEIGHT * sizeof(rgb_pixel_t) Used for buffer allocation and validation.

Note

This is approximately 24.88 MB for 4K RGB images.

Actual memory usage may be higher due to alignment.

Definition at line 191 of file video/image.h.

IMAGE_MAX_WIDTH

#define IMAGE_MAX_WIDTH   3840

#include <image.h>

Maximum image width (4K resolution)

Maximum supported image width in pixels. Set to 3840 pixels (4K UHD width) to support high-resolution video capture.

Note

Larger images may exceed memory limits.

Video pipeline may enforce lower limits for performance.

Definition at line 164 of file video/image.h.

LUMA_BLUE

#define LUMA_BLUE   29

#include <ascii_simd.h>

Luminance blue coefficient (0.114 * 256 = 29)

Definition at line 76 of file ascii_simd.h.

LUMA_GREEN

#define LUMA_GREEN   150

#include <ascii_simd.h>

Luminance green coefficient (0.587 * 256 = 150)

Definition at line 74 of file ascii_simd.h.

LUMA_RED

#define LUMA_RED   77

#include <ascii_simd.h>

Luminance red coefficient (0.299 * 256 = 77)

Definition at line 72 of file ascii_simd.h.

LUMA_THRESHOLD

#define LUMA_THRESHOLD   128

#include <ascii_simd.h>

Luminance threshold for rounding.

Definition at line 78 of file ascii_simd.h.

print

#define print

(

s

)

fwrite(s, 1, sizeof(s) / sizeof((s)[0]), stdout)

#include <ascii.h>

Print string to stdout.

Parameters

s	String literal to print

Utility macro for printing string literals to stdout. Uses fwrite() for efficient output without null terminator requirement.

Note

This is a macro that expands to fwrite() call.

Only works with string literals (compile-time known size).

Use fputs() or printf() for runtime strings.

Definition at line 505 of file ascii.h.

RAMP64_SIZE

#define RAMP64_SIZE   64

#include <common.h>

Ramp64 cache size (64 entries)

Definition at line 34 of file video/simd/common.h.

Typedef Documentation

utf8_palette_cache_t

typedef struct utf8_palette_cache_s utf8_palette_cache_t

#include <common.h>

UTF-8 palette cache structure.

Thread-safe cache system for UTF-8 character lookup with eviction tracking.

Enumeration Type Documentation

ansi_color_mode_t

enum ansi_color_mode_t

#include <ansi_fast.h>

Color mode for ANSI generation.

Enumerator
ANSI_MODE_FOREGROUND	Foreground color mode: \033[38;2;R;G;Bm
ANSI_MODE_BACKGROUND	Background color mode: \033[48;2;R;G;Bm
ANSI_MODE_FOREGROUND_BACKGROUND	Both foreground and background: \033[38;2;R;G;B;48;2;r;g;bm

Definition at line 40 of file ansi_fast.h.

             {
  ANSI_MODE_FOREGROUND,           
  ANSI_MODE_BACKGROUND,           
  ANSI_MODE_FOREGROUND_BACKGROUND 
} ansi_color_mode_t;

image_alloc_method_t

enum image_alloc_method_t

#include <image.h>

Pixel allocation method tracking.

Tracks which allocation method was used for image pixels to ensure correct deallocation. Must match the allocation method used when creating the image.

Enumerator
IMAGE_ALLOC_SIMD	Pixels allocated with SAFE_MALLOC_SIMD()
IMAGE_ALLOC_POOL	Pixels allocated with buffer_pool_alloc()

Definition at line 116 of file video/image.h.

             {
  IMAGE_ALLOC_SIMD = 0, 
  IMAGE_ALLOC_POOL = 1  
} image_alloc_method_t;

Function Documentation

alloc_image()

ImageRGB alloc_image	(	int	w,
		int	h
	)

#include <ascii_simd.h>

Allocate a new ImageRGB (RGB8 format)

Parameters

w	Image width
h	Image height

Returns

Allocated ImageRGB structure

Note

Aborts on out-of-memory condition.

Definition at line 98 of file ascii_simd.c.

                                   {
  ImageRGB out;
  out.w = w;
  out.h = h;
  size_t n = (size_t)w * (size_t)h * 3u;
  out.pixels = SAFE_MALLOC(n, uint8_t *);
  return out;
}

References ImageRGB::h, ImageRGB::pixels, SAFE_MALLOC, and ImageRGB::w.

ansi_compress_rle()

char * ansi_compress_rle	(	const char *	input,
		size_t	input_len
	)

#include <rle.h>

Compress repeated characters using RLE escape sequences.

Parameters

input	Input string (may contain ANSI escape codes)
input_len	Length of input string

Returns

Newly allocated string with RLE compression (caller must free)

Compresses runs of repeated printable characters using ANSI RLE sequences. Only compresses when profitable (run length > RLE overhead). Preserves all existing escape sequences.

Note

The returned string must be freed by the caller using free().

Returns NULL if input is NULL or allocation fails.

Only compresses runs where RLE saves bytes (typically 4+ chars).

Example

const char *frame = "AAAAAAA\x1b[31mBBBBB\n";
char *compressed = ansi_compress_rle(frame, strlen(frame));
// compressed = "A\x1b[6b\x1b[31mB\x1b[4b\n"
free(compressed);

Definition at line 98 of file rle.c.

                                                             {
  if (!input || input_len == 0) {
    return NULL;
  }
 
  outbuf_t ob = {0};
  ob_reserve(&ob, input_len);
 
  size_t i = 0;
  while (i < input_len) {
    // Check for ESC character (start of ANSI sequence)
    if (input[i] == '\x1b' && i + 1 < input_len && input[i + 1] == '[') {
      size_t seq_start = i;
      i += 2; // Skip ESC[
 
      // Skip parameter bytes
      while (i < input_len && ((input[i] >= '0' && input[i] <= '9') || input[i] == ';')) {
        i++;
      }
 
      // Skip final byte
      if (i < input_len) {
        i++;
      }
 
      // Copy entire escape sequence as-is
      ob_write(&ob, input + seq_start, i - seq_start);
    } else {
      // Regular character - check for runs
      char c = input[i];
 
      // Only compress printable characters (not newlines, not control chars)
      if (c >= 0x20 && c != 0x7F) {
        // Count run length
        size_t run_len = 1;
        i++;
 
        while (i < input_len && input[i] == c) {
          run_len++;
          i++;
        }
 
        // Emit first character
        ob_putc(&ob, c);
 
        // Use RLE if profitable (run > overhead of ESC[Nb)
        if (run_len > 1 && rep_is_profitable((uint32_t)run_len)) {
          emit_rep(&ob, (uint32_t)(run_len - 1));
        } else {
          // Emit remaining characters directly
          for (size_t k = 1; k < run_len; k++) {
            ob_putc(&ob, c);
          }
        }
      } else {
        // Non-compressible character (newline, etc.)
        ob_putc(&ob, c);
        i++;
      }
    }
  }
 
  ob_term(&ob);
  return ob.buf;
}

References outbuf_t::buf, emit_rep(), ob_putc(), ob_reserve(), ob_term(), ob_write(), and rep_is_profitable().

ansi_expand_rle()

char * ansi_expand_rle	(	const char *	input,
		size_t	input_len
	)

#include <rle.h>

Expand RLE escape sequences in a string.

Parameters

input	Input string containing ANSI escape codes
input_len	Length of input string

Returns

Newly allocated string with RLE expanded (caller must free)

Expands ANSI RLE (REP) sequences while preserving all other escape codes:

• RLE sequences (ESC[Nb) are expanded: previous character repeated N times
• All other escape sequences (colors, cursor, etc.) are preserved as-is

This is useful when outputting to files/pipes where terminals can't interpret RLE, but you still want to preserve color codes.

Note

The returned string must be freed by the caller using free().

Returns NULL if input is NULL or allocation fails.

Example

const char *frame = "A\x1b[3b\x1b[31mB\n";  // A + repeat 3 + red + B
char *expanded = ansi_expand_rle(frame, strlen(frame));
// expanded = "AAAA\x1b[31mB\n" (RLE expanded, color preserved)
free(expanded);

Definition at line 13 of file rle.c.

                                                           {
  if (!input || input_len == 0) {
    return NULL;
  }
 
  // RLE expansion can make output larger than input, start with 2x capacity
  outbuf_t ob = {0};
  ob_reserve(&ob, input_len * 2);
 
  // Track the last character/grapheme for RLE expansion
  // UTF-8 characters can be up to 4 bytes
  char last_char[5] = " ";
  size_t last_char_len = 1;
 
  size_t i = 0;
  while (i < input_len) {
    // Check for ESC character (start of ANSI sequence)
    if (input[i] == '\x1b' && i + 1 < input_len && input[i + 1] == '[') {
      size_t seq_start = i;
      i += 2; // Skip ESC[
 
      // Parse parameter bytes (digits and semicolons)
      uint32_t param = 0;
      while (i < input_len && ((input[i] >= '0' && input[i] <= '9') || input[i] == ';')) {
        if (input[i] >= '0' && input[i] <= '9') {
          param = param * 10 + (uint32_t)(input[i] - '0');
        } else if (input[i] == ';') {
          param = 0; // Reset for next parameter
        }
        i++;
      }
 
      // Check for final byte
      if (i < input_len) {
        char final_byte = input[i];
        i++;
 
        // Handle RLE: ESC[Nb repeats previous character N times
        if (final_byte == 'b' && param > 0) {
          for (uint32_t r = 0; r < param; r++) {
            ob_write(&ob, last_char, last_char_len);
          }
        } else {
          // Not RLE - copy the entire escape sequence as-is
          ob_write(&ob, input + seq_start, i - seq_start);
        }
      }
    } else {
      // Regular character - copy to output and track for RLE
      unsigned char c = (unsigned char)input[i];
      size_t char_len = 1;
 
      // Determine UTF-8 character length from first byte
      if ((c & 0x80) == 0) {
        char_len = 1; // ASCII
      } else if ((c & 0xE0) == 0xC0) {
        char_len = 2; // 2-byte UTF-8
      } else if ((c & 0xF0) == 0xE0) {
        char_len = 3; // 3-byte UTF-8
      } else if ((c & 0xF8) == 0xF0) {
        char_len = 4; // 4-byte UTF-8
      }
 
      // Make sure we don't read past end of input
      if (i + char_len > input_len) {
        char_len = input_len - i;
      }
 
      // Copy full UTF-8 character to output
      ob_write(&ob, input + i, char_len);
 
      // Track last printable character for RLE (skip control chars)
      if (c >= 0x20 && c != 0x7F) {
        SAFE_MEMCPY(last_char, sizeof(last_char), input + i, char_len);
        last_char[char_len] = '\0';
        last_char_len = char_len;
      }
      i += char_len;
    }
  }
 
  ob_term(&ob);
  return ob.buf;
}

References outbuf_t::buf, ob_reserve(), ob_term(), ob_write(), and SAFE_MEMCPY.

ansi_fast_init()

void ansi_fast_init

(

void

)

#include <ansi_fast.h>

Initialize the decimal lookup table.

Must be called once at startup before using any ANSI generation functions.

Definition at line 173 of file ansi_fast.c.

                          {
  // Initialize the dec3 cache used by truecolor functions
  ascii_simd_init();
}

References ascii_simd_init().

Referenced by mirror_main().

ansi_fast_init_16color()

void ansi_fast_init_16color

(

void

)

#include <ansi_fast.h>

Initialize 16-color mode lookup tables.

Must be called before using 16-color functions.

Definition at line 225 of file ansi_fast.c.

                                  {
  if (color16_initialized)
    return;
 
  // Standard ANSI color codes
  const char *fg_codes[] = {"30", "31", "32", "33", "34", "35", "36", "37",          // Normal colors (30-37)
                            "90", "91", "92", "93", "94", "95", "96", "97"};         // Bright colors (90-97)
  const char *bg_codes[] = {"40",  "41",  "42",  "43",  "44",  "45",  "46",  "47",   // Normal colors (40-47)
                            "100", "101", "102", "103", "104", "105", "106", "107"}; // Bright colors (100-107)
 
  for (int i = 0; i < 16; i++) {
    SAFE_SNPRINTF(color16_fg_strings[i], sizeof(color16_fg_strings[i]), "\033[%sm", fg_codes[i]);
    SAFE_SNPRINTF(color16_bg_strings[i], sizeof(color16_bg_strings[i]), "\033[%sm", bg_codes[i]);
  }
 
  color16_initialized = true;
}

References SAFE_SNPRINTF.

Referenced by append_16color_bg(), append_16color_fg(), image_print_16color(), image_print_16color_dithered(), image_print_16color_dithered_with_background(), and mirror_main().

ansi_fast_init_256color()

void ansi_fast_init_256color

(

void

)

#include <ansi_fast.h>

Initialize 256-color mode lookup tables.

Must be called before using 256-color functions.

Definition at line 179 of file ansi_fast.c.

                                   {
  if (color256_initialized)
    return;
 
  for (int i = 0; i < 256; i++) {
    SAFE_SNPRINTF(color256_strings[i], sizeof(color256_strings[i]), "\033[38;5;%dm", i);
  }
 
  color256_initialized = true;
}

References SAFE_SNPRINTF.

Referenced by mirror_main().

ansi_rle_add_pixel()

void ansi_rle_add_pixel	(	ansi_rle_context_t *	ctx,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b,
		char	ascii_char
	)

#include <ansi_fast.h>

Add a pixel with run-length encoding.

Parameters

ctx	RLE context structure
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)
ascii_char	ASCII character to output

Only emits SGR when color changes from previous pixel.

Definition at line 125 of file ansi_fast.c.

                                                                                                   {
  // Check if we need to emit a new SGR sequence
  bool color_changed = ctx->first_pixel || (r != ctx->last_r) || (g != ctx->last_g) || (b != ctx->last_b);
 
  if (color_changed && (ctx->length + 40 < ctx->capacity)) { // Reserve 40 bytes for SGR (FG+BG max is 38)
    char *pos = ctx->buffer + ctx->length;
 
    switch (ctx->mode) {
    case ANSI_MODE_FOREGROUND:
      pos = append_truecolor_fg(pos, r, g, b);
      break;
    case ANSI_MODE_BACKGROUND:
      pos = append_truecolor_bg(pos, r, g, b);
      break;
    case ANSI_MODE_FOREGROUND_BACKGROUND:
      // For FG+BG mode, use a default background (black) or implement dual-color logic
      pos = append_truecolor_fg_bg(pos, r, g, b, 0, 0, 0);
      break;
    }
 
    ctx->length = (size_t)(pos - ctx->buffer);
    ctx->last_r = r;
    ctx->last_g = g;
    ctx->last_b = b;
    ctx->first_pixel = false;
  }
 
  // Add the ASCII character
  if (ctx->length < ctx->capacity - 1) {
    ctx->buffer[ctx->length++] = ascii_char;
  }
}

References ANSI_MODE_BACKGROUND, ANSI_MODE_FOREGROUND, ANSI_MODE_FOREGROUND_BACKGROUND, append_truecolor_bg(), append_truecolor_fg(), append_truecolor_fg_bg(), ansi_rle_context_t::buffer, ansi_rle_context_t::capacity, ansi_rle_context_t::first_pixel, ansi_rle_context_t::last_b, ansi_rle_context_t::last_g, ansi_rle_context_t::last_r, ansi_rle_context_t::length, and ansi_rle_context_t::mode.

Referenced by image_print_color().

ansi_rle_finish()

void ansi_rle_finish

(

ansi_rle_context_t *

ctx

)

#include <ansi_fast.h>

Finish RLE sequence.

Parameters

ctx	RLE context structure

Adds ANSI reset sequence and null terminator.

Definition at line 159 of file ansi_fast.c.

                                              {
  // Add reset sequence
  if (ctx->length + 5 < ctx->capacity) {
    SAFE_MEMCPY(ctx->buffer + ctx->length, 4, "\033[0m", 4);
    ctx->length += 4;
  }
 
  // Null terminate
  if (ctx->length < ctx->capacity) {
    ctx->buffer[ctx->length] = '\0';
  }
}

References ansi_rle_context_t::buffer, ansi_rle_context_t::capacity, ansi_rle_context_t::length, and SAFE_MEMCPY.

Referenced by image_print_color().

ansi_rle_init()

void ansi_rle_init	(	ansi_rle_context_t *	ctx,
		char *	buffer,
		size_t	capacity,
		ansi_color_mode_t	mode
	)

#include <ansi_fast.h>

Initialize run-length encoding context.

Parameters

ctx	Context structure to initialize
buffer	Output buffer
capacity	Buffer capacity in bytes
mode	Color mode to use

Definition at line 112 of file ansi_fast.c.

                                                                                                   {
  ctx->buffer = buffer;
  ctx->capacity = capacity;
  ctx->length = 0;
  ctx->mode = mode;
  ctx->first_pixel = true;
  // Initialize with impossible color values to force first SGR
  ctx->last_r = 0xFF;
  ctx->last_g = 0xFF;
  ctx->last_b = 0xFF;
}

References ansi_rle_context_t::buffer, ansi_rle_context_t::capacity, ansi_rle_context_t::first_pixel, ansi_rle_context_t::last_b, ansi_rle_context_t::last_g, ansi_rle_context_t::last_r, ansi_rle_context_t::length, and ansi_rle_context_t::mode.

Referenced by image_print_color().

append_16color_bg()

char * append_16color_bg	(	char *	dst,
		uint8_t	color_index
	)

#include <ansi_fast.h>

Append 16-color background ANSI sequence.

Parameters

dst	Destination buffer pointer
color_index	16-color ANSI index (0-15)

Returns

Pointer to end of appended sequence

Definition at line 260 of file ansi_fast.c.

                                                        {
  if (!color16_initialized) {
    ansi_fast_init_16color();
  }
 
  if (color_index >= 16) {
    color_index = 0; // Default to black background
  }
 
  const char *color_str = color16_bg_strings[color_index];
  while (*color_str) {
    *dst++ = *color_str++;
  }
 
  return dst;
}

References ansi_fast_init_16color().

Referenced by image_print_16color_dithered_with_background().

append_16color_fg()

char * append_16color_fg	(	char *	dst,
		uint8_t	color_index
	)

#include <ansi_fast.h>

Append 16-color foreground ANSI sequence.

Parameters

dst	Destination buffer pointer
color_index	16-color ANSI index (0-15)

Returns

Pointer to end of appended sequence

Definition at line 243 of file ansi_fast.c.

                                                        {
  if (!color16_initialized) {
    ansi_fast_init_16color();
  }
 
  if (color_index >= 16) {
    color_index = 7; // Default to white
  }
 
  const char *color_str = color16_fg_strings[color_index];
  while (*color_str) {
    *dst++ = *color_str++;
  }
 
  return dst;
}

References ansi_fast_init_16color().

Referenced by append_color_fg_for_mode(), image_print_16color(), image_print_16color_dithered(), and image_print_16color_dithered_with_background().

append_256color_fg()

char * append_256color_fg	(	char *	dst,
		uint8_t	color_index
	)

#include <ansi_fast.h>

Append 256-color foreground ANSI sequence.

Parameters

dst	Destination buffer pointer
color_index	256-color palette index (0-255)

Returns

Pointer to end of appended sequence

Definition at line 191 of file ansi_fast.c.

                                                         {
  const char *color_str = color256_strings[color_index];
  size_t len = strlen(color_str);
  SAFE_MEMCPY(dst, len, color_str, len);
  return dst + len;
}

References SAFE_MEMCPY.

Referenced by append_color_fg_for_mode().

append_color_fg_for_mode()

char * append_color_fg_for_mode	(	char *	dst,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b,
		terminal_color_mode_t	mode
	)

#include <ansi_fast.h>

Append color foreground sequence for specified mode.

Parameters

dst	Destination buffer pointer
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)
mode	Color mode to use

Returns

Pointer to end of appended sequence

Automatically selects appropriate ANSI sequence based on color mode.

Definition at line 426 of file ansi_fast.c.

                                                                                                       {
  switch (mode) {
  case COLOR_MODE_TRUECOLOR:
    return append_truecolor_fg(dst, r, g, b);
 
  case COLOR_MODE_256_COLOR: {
    uint8_t color_index = rgb_to_256color(r, g, b);
    return append_256color_fg(dst, color_index);
  }
 
  case COLOR_MODE_16_COLOR: {
    uint8_t color_index = rgb_to_16color(r, g, b);
    return append_16color_fg(dst, color_index);
  }
 
  case COLOR_MODE_NONE:
  case COLOR_MODE_AUTO:
  default:
    // No color output for monochrome mode or auto mode (fallback)
    return dst;
  }
}

References append_16color_fg(), append_256color_fg(), append_truecolor_fg(), COLOR_MODE_16_COLOR, COLOR_MODE_256_COLOR, COLOR_MODE_AUTO, COLOR_MODE_NONE, COLOR_MODE_TRUECOLOR, rgb_to_16color(), and rgb_to_256color().

append_sgr_reset()

char * append_sgr_reset ( char *  dst )

inline

#include <common.h>

Append ANSI reset sequence.

Parameters

dst	Destination buffer pointer

Returns

Pointer to end of appended sequence

Definition at line 107 of file ascii_simd_color.c.

                                         {
  // "\x1b[0m"
  static const char RESET[] = "\033[0m";
  memcpy(dst, RESET, sizeof(RESET) - 1);
  return dst + (sizeof(RESET) - 1);
}

append_sgr_truecolor_bg()

char * append_sgr_truecolor_bg ( char *  dst, uint8_t  r, uint8_t  g, uint8_t  b  )

inline

#include <common.h>

Append truecolor background SGR sequence.

Parameters

dst	Destination buffer pointer
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

Pointer to end of appended sequence

Definition at line 176 of file ascii_simd_color.c.

                                                                                 {
  // Constructor ensures initialization
 
  // Direct character writes for "\033[48;2;"
  *dst++ = '\033';
  *dst++ = '[';
  *dst++ = '4';
  *dst++ = '8';
  *dst++ = ';';
  *dst++ = '2';
  *dst++ = ';';
 
  // Optimized digit copying
  const dec3_t *rd = &g_dec3_cache.dec3_table[r];
  if (rd->len == 1) {
    *dst++ = rd->s[0];
  } else if (rd->len == 2) {
    dst[0] = rd->s[0];
    dst[1] = rd->s[1];
    dst += 2;
  } else {
    dst[0] = rd->s[0];
    dst[1] = rd->s[1];
    dst[2] = rd->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  const dec3_t *gd = &g_dec3_cache.dec3_table[g];
  if (gd->len == 1) {
    *dst++ = gd->s[0];
  } else if (gd->len == 2) {
    dst[0] = gd->s[0];
    dst[1] = gd->s[1];
    dst += 2;
  } else {
    dst[0] = gd->s[0];
    dst[1] = gd->s[1];
    dst[2] = gd->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  const dec3_t *bd = &g_dec3_cache.dec3_table[b];
  if (bd->len == 1) {
    *dst++ = bd->s[0];
  } else if (bd->len == 2) {
    dst[0] = bd->s[0];
    dst[1] = bd->s[1];
    dst += 2;
  } else {
    dst[0] = bd->s[0];
    dst[1] = bd->s[1];
    dst[2] = bd->s[2];
    dst += 3;
  }
  *dst++ = 'm';
  return dst;
}

References global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, and dec3_t::s.

append_sgr_truecolor_fg()

char * append_sgr_truecolor_fg ( char *  dst, uint8_t  r, uint8_t  g, uint8_t  b  )

inline

#include <common.h>

Append truecolor foreground SGR sequence.

Parameters

dst	Destination buffer pointer
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

Pointer to end of appended sequence

Definition at line 115 of file ascii_simd_color.c.

                                                                                 {
  // Constructor ensures initialization
 
  // Direct character writes (compiler will optimize to word operations)
  *dst++ = '\033';
  *dst++ = '[';
  *dst++ = '3';
  *dst++ = '8';
  *dst++ = ';';
  *dst++ = '2';
  *dst++ = ';';
 
  // Fast digit copying for 1-3 digit numbers (avoid memcpy overhead)
  const dec3_t *rd = &g_dec3_cache.dec3_table[r];
  if (rd->len == 1) {
    *dst++ = rd->s[0];
  } else if (rd->len == 2) {
    dst[0] = rd->s[0];
    dst[1] = rd->s[1];
    dst += 2;
  } else {
    dst[0] = rd->s[0];
    dst[1] = rd->s[1];
    dst[2] = rd->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  const dec3_t *gd = &g_dec3_cache.dec3_table[g];
  if (gd->len == 1) {
    *dst++ = gd->s[0];
  } else if (gd->len == 2) {
    dst[0] = gd->s[0];
    dst[1] = gd->s[1];
    dst += 2;
  } else {
    dst[0] = gd->s[0];
    dst[1] = gd->s[1];
    dst[2] = gd->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  const dec3_t *bd = &g_dec3_cache.dec3_table[b];
  if (bd->len == 1) {
    *dst++ = bd->s[0];
  } else if (bd->len == 2) {
    dst[0] = bd->s[0];
    dst[1] = bd->s[1];
    dst += 2;
  } else {
    dst[0] = bd->s[0];
    dst[1] = bd->s[1];
    dst[2] = bd->s[2];
    dst += 3;
  }
  *dst++ = 'm';
  return dst;
}

References global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, and dec3_t::s.

append_sgr_truecolor_fg_bg()

char * append_sgr_truecolor_fg_bg ( char *  dst, uint8_t  fr, uint8_t  fg, uint8_t  fb, uint8_t  br, uint8_t  bg, uint8_t  bb  )

inline

#include <common.h>

Append truecolor foreground and background SGR sequence.

Parameters

dst	Destination buffer pointer
fr	Foreground red component (0-255)
fg	Foreground green component (0-255)
fb	Foreground blue component (0-255)
br	Background red component (0-255)
bg	Background green component (0-255)
bb	Background blue component (0-255)

Returns

Pointer to end of appended sequence

Definition at line 237 of file ascii_simd_color.c.

                                                    {
  // Constructor ensures initialization
 
  // Write "\033[38;2;" directly (7 chars)
  *dst++ = '\033';
  *dst++ = '[';
  *dst++ = '3';
  *dst++ = '8';
  *dst++ = ';';
  *dst++ = '2';
  *dst++ = ';';
 
  // Foreground RGB digits
  const dec3_t *d = &g_dec3_cache.dec3_table[fr];
  if (d->len == 1) {
    *dst++ = d->s[0];
  } else if (d->len == 2) {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst += 2;
  } else {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst[2] = d->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  d = &g_dec3_cache.dec3_table[fg];
  if (d->len == 1) {
    *dst++ = d->s[0];
  } else if (d->len == 2) {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst += 2;
  } else {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst[2] = d->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  d = &g_dec3_cache.dec3_table[fb];
  if (d->len == 1) {
    *dst++ = d->s[0];
  } else if (d->len == 2) {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst += 2;
  } else {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst[2] = d->s[2];
    dst += 3;
  }
 
  // Write ";48;2;" directly (6 chars)
  *dst++ = ';';
  *dst++ = '4';
  *dst++ = '8';
  *dst++ = ';';
  *dst++ = '2';
  *dst++ = ';';
 
  // Background RGB digits
  d = &g_dec3_cache.dec3_table[br];
  if (d->len == 1) {
    *dst++ = d->s[0];
  } else if (d->len == 2) {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst += 2;
  } else {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst[2] = d->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  d = &g_dec3_cache.dec3_table[bg];
  if (d->len == 1) {
    *dst++ = d->s[0];
  } else if (d->len == 2) {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst += 2;
  } else {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst[2] = d->s[2];
    dst += 3;
  }
  *dst++ = ';';
 
  d = &g_dec3_cache.dec3_table[bb];
  if (d->len == 1) {
    *dst++ = d->s[0];
  } else if (d->len == 2) {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst += 2;
  } else {
    dst[0] = d->s[0];
    dst[1] = d->s[1];
    dst[2] = d->s[2];
    dst += 3;
  }
 
  *dst++ = 'm';
  return dst;
}

References global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, and dec3_t::s.

append_truecolor_bg()

char * append_truecolor_bg	(	char *	dst,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <ansi_fast.h>

Append truecolor background ANSI sequence.

Parameters

dst	Destination buffer pointer
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

Pointer to end of appended sequence

Definition at line 49 of file ansi_fast.c.

                                                                      {
  SAFE_MEMCPY(dst, 19, "\033[48;2;", 7);
  dst += 7;
 
  SAFE_MEMCPY(dst, 12, g_dec3_cache.dec3_table[r].s, g_dec3_cache.dec3_table[r].len);
  dst += g_dec3_cache.dec3_table[r].len;
  *dst++ = ';';
 
  SAFE_MEMCPY(dst, 8, g_dec3_cache.dec3_table[g].s, g_dec3_cache.dec3_table[g].len);
  dst += g_dec3_cache.dec3_table[g].len;
  *dst++ = ';';
 
  SAFE_MEMCPY(dst, 4, g_dec3_cache.dec3_table[b].s, g_dec3_cache.dec3_table[b].len);
  dst += g_dec3_cache.dec3_table[b].len;
  *dst++ = 'm';
 
  return dst;
}

References global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, dec3_t::s, and SAFE_MEMCPY.

Referenced by ansi_rle_add_pixel().

append_truecolor_fg()

char * append_truecolor_fg	(	char *	dst,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <ansi_fast.h>

Append truecolor foreground ANSI sequence.

Parameters

dst	Destination buffer pointer
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

Pointer to end of appended sequence

Definition at line 24 of file ansi_fast.c.

                                                                      {
  // Static prefix - 7 bytes
  SAFE_MEMCPY(dst, 19, "\033[38;2;", 7);
  dst += 7;
 
  // Red component + semicolon
  SAFE_MEMCPY(dst, 12, g_dec3_cache.dec3_table[r].s, g_dec3_cache.dec3_table[r].len);
  dst += g_dec3_cache.dec3_table[r].len;
  *dst++ = ';';
 
  // Green component + semicolon
  SAFE_MEMCPY(dst, 8, g_dec3_cache.dec3_table[g].s, g_dec3_cache.dec3_table[g].len);
  dst += g_dec3_cache.dec3_table[g].len;
  *dst++ = ';';
 
  // Blue component + suffix
  SAFE_MEMCPY(dst, 4, g_dec3_cache.dec3_table[b].s, g_dec3_cache.dec3_table[b].len);
  dst += g_dec3_cache.dec3_table[b].len;
  *dst++ = 'm';
 
  return dst;
}

References global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, dec3_t::s, and SAFE_MEMCPY.

Referenced by ansi_rle_add_pixel(), and append_color_fg_for_mode().

append_truecolor_fg_bg()

char * append_truecolor_fg_bg	(	char *	dst,
		uint8_t	fg_r,
		uint8_t	fg_g,
		uint8_t	fg_b,
		uint8_t	bg_r,
		uint8_t	bg_g,
		uint8_t	bg_b
	)

#include <ansi_fast.h>

Append truecolor foreground and background ANSI sequence.

Parameters

dst	Destination buffer pointer
fg_r	Foreground red component (0-255)
fg_g	Foreground green component (0-255)
fg_b	Foreground blue component (0-255)
bg_r	Background red component (0-255)
bg_g	Background green component (0-255)
bg_b	Background blue component (0-255)

Returns

Pointer to end of appended sequence

Definition at line 70 of file ansi_fast.c.

                                           {
  SAFE_MEMCPY(dst, 38, "\033[38;2;", 7);
  dst += 7;
 
  // Foreground RGB (remaining: 31 bytes max)
  SAFE_MEMCPY(dst, 31, g_dec3_cache.dec3_table[fg_r].s, g_dec3_cache.dec3_table[fg_r].len);
  dst += g_dec3_cache.dec3_table[fg_r].len;
  *dst++ = ';';
 
  // Remaining: 27 bytes max
  SAFE_MEMCPY(dst, 27, g_dec3_cache.dec3_table[fg_g].s, g_dec3_cache.dec3_table[fg_g].len);
  dst += g_dec3_cache.dec3_table[fg_g].len;
  *dst++ = ';';
 
  // Remaining: 23 bytes max
  SAFE_MEMCPY(dst, 23, g_dec3_cache.dec3_table[fg_b].s, g_dec3_cache.dec3_table[fg_b].len);
  dst += g_dec3_cache.dec3_table[fg_b].len;
 
  // Background RGB (remaining: 20 bytes max)
  SAFE_MEMCPY(dst, 20, ";48;2;", 6);
  dst += 6;
 
  // Remaining: 14 bytes max
  SAFE_MEMCPY(dst, 14, g_dec3_cache.dec3_table[bg_r].s, g_dec3_cache.dec3_table[bg_r].len);
  dst += g_dec3_cache.dec3_table[bg_r].len;
  *dst++ = ';';
 
  // Remaining: 10 bytes max
  SAFE_MEMCPY(dst, 10, g_dec3_cache.dec3_table[bg_g].s, g_dec3_cache.dec3_table[bg_g].len);
  dst += g_dec3_cache.dec3_table[bg_g].len;
  *dst++ = ';';
 
  // Remaining: 6 bytes max
  SAFE_MEMCPY(dst, 6, g_dec3_cache.dec3_table[bg_b].s, g_dec3_cache.dec3_table[bg_b].len);
  dst += g_dec3_cache.dec3_table[bg_b].len;
  *dst++ = 'm';
 
  return dst;
}

References global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, dec3_t::s, and SAFE_MEMCPY.

Referenced by ansi_rle_add_pixel().

ascii_convert()

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[256]
	)

#include <ascii.h>

Convert image to ASCII art.

Parameters

original	Source image (must not be NULL)
width	Target width in characters (must be > 0)
height	Target height in characters (must be > 0)
color	Enable color output (true for color, false for monochrome)
aspect_ratio	Preserve aspect ratio (true to maintain proportions, false to fill dimensions)
stretch	Stretch to fit (if aspect_ratio is false, true to fill exactly, false to fit within)
palette_chars	Character palette to use (or NULL for default ASCII palette)
luminance_palette	Luminance-to-character mapping palette (must not be NULL, 256 elements)

Returns

Allocated ASCII frame string (caller must free), or NULL on error

Converts an image to ASCII art with specified dimensions and color mode. Uses character palette to map pixel luminance to ASCII characters and optionally applies color output using ANSI escape sequences.

CONVERSION PROCESS:

• Resizes image to target dimensions (with aspect ratio preservation if enabled)
• Maps each pixel's luminance to ASCII character using palette
• Optionally applies color output using ANSI escape sequences
• Returns null-terminated string containing ASCII frame

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Aspect ratio preservation uses terminal character correction.

Color output requires terminal color support for proper display.

Definition at line 67 of file ascii.c.

                                                       {
  if (original == NULL || !palette_chars || !luminance_palette) {
    log_error("ascii_convert: invalid parameters");
    return NULL;
  }
 
  // Check for empty strings
  if (palette_chars[0] == '\0' || luminance_palette[0] == '\0') {
    log_error("ascii_convert: empty palette strings");
    return NULL;
  }
 
  // Start with the target dimensions requested by the user (or detected from
  // the terminal). These can be modified by aspect_ratio() if stretching is
  // disabled and one of the dimensions was left to be calculated
  // automatically.
  ssize_t resized_width = width;
  ssize_t resized_height = height;
 
  // If stretch is enabled, use full dimensions, otherwise calculate aspect ratio
  if (_aspect_ratio) {
    // The server now provides images at width*2 x height pixels
    // The aspect_ratio function will handle terminal character aspect ratio
    aspect_ratio(original->w, original->h, resized_width, resized_height, stretch, &resized_width, &resized_height);
  }
 
  // Calculate padding for centering
  size_t pad_width = 0;
  size_t pad_height = 0;
 
  if (_aspect_ratio) {
    // Only calculate padding when not stretching
    ssize_t pad_width_ss = width > resized_width ? (width - resized_width) / 2 : 0;
    pad_width = (size_t)pad_width_ss;
 
    ssize_t pad_height_ss = height > resized_height ? (height - resized_height) / 2 : 0;
    pad_height = (size_t)pad_height_ss;
  }
 
  // 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;
  }
 
  // Always resize to target dimensions
  image_t *resized = image_new((size_t)resized_width, (size_t)resized_height);
  if (!resized) {
    log_error("Failed to allocate resized image");
    return NULL;
  }
 
  image_clear(resized);
  image_resize(original, resized);
 
  char *ascii;
  if (color) {
    // Check for half-block mode first (requires NEON)
    if (GET_OPTION(render_mode) == RENDER_MODE_HALF_BLOCK) {
#if SIMD_SUPPORT_NEON
      // Use NEON half-block renderer
      const uint8_t *rgb_data = (const uint8_t *)resized->pixels;
      ascii = rgb_to_truecolor_halfblocks_neon(rgb_data, resized->w, resized->h, 0);
#else
      log_error("Half-block mode requires NEON support (ARM architecture)");
      image_destroy(resized);
      return NULL;
#endif
    } else {
#ifdef SIMD_SUPPORT
      // Standard color modes (foreground/background)
      bool use_background = (GET_OPTION(render_mode) == RENDER_MODE_BACKGROUND);
      ascii = image_print_color_simd(resized, use_background, false, palette_chars);
#else
      ascii = image_print_color(resized, palette_chars);
#endif
    }
  } else {
    // Use grayscale/monochrome conversion with client's palette
#ifdef SIMD_SUPPORT
    ascii = image_print_simd(resized, luminance_palette);
#else
    ascii = image_print(resized, palette_chars);
#endif
  }
 
  if (!ascii) {
    log_error("Failed to convert image to ASCII");
    image_destroy(resized);
    return NULL;
  }
 
  size_t ascii_len = strlen(ascii);
  if (ascii_len == 0) {
    log_error("ASCII conversion returned empty string (resized dimensions: %dx%d)", resized->w, resized->h);
    SAFE_FREE(ascii);
    image_destroy(resized);
    return NULL;
  }
 
  char *ascii_width_padded = ascii_pad_frame_width(ascii, pad_width);
  SAFE_FREE(ascii);
 
  char *ascii_padded = ascii_pad_frame_height(ascii_width_padded, pad_height);
  SAFE_FREE(ascii_width_padded);
 
  // Only destroy resized if we allocated it (not when using original directly)
  image_destroy(resized);
 
  return ascii_padded;
}

References ascii_pad_frame_height(), ascii_pad_frame_width(), aspect_ratio(), GET_OPTION, image_t::h, image_clear(), image_destroy(), image_new(), image_print(), image_print_color(), image_print_color_simd(), image_print_simd(), image_resize(), log_error, image_t::pixels, RENDER_MODE_BACKGROUND, RENDER_MODE_HALF_BLOCK, SAFE_FREE, and image_t::w.

Referenced by benchmark_simd_color_conversion_with_source().

ascii_convert_with_capabilities()

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,
		const char	luminance_palette[256]
	)

#include <ascii.h>

Convert image to ASCII art with terminal capability awareness.

Parameters

original	Source image (must not be NULL)
width	Target width in characters (must be > 0)
height	Target height in characters (must be > 0)
caps	Terminal capabilities structure (must not be NULL)
use_aspect_ratio	Preserve aspect ratio (true to maintain proportions, false to fill dimensions)
stretch	Stretch to fit (if use_aspect_ratio is false, true to fill exactly, false to fit within)
palette_chars	Character palette to use (or NULL for default ASCII palette)
luminance_palette	Luminance-to-character mapping palette (must not be NULL, 256 elements)

Returns

Allocated ASCII frame string (caller must free), or NULL on error

Converts an image to ASCII art with automatic color mode selection based on terminal capabilities. Automatically chooses the best color mode (16-color, 256-color, or truecolor) for optimal display.

CAPABILITY-AWARE CONVERSION:

• Detects terminal color capabilities from structure
• Selects optimal color mode (truecolor > 256-color > 16-color > monochrome)
• Applies terminal character aspect ratio correction
• Uses capability-specific conversion algorithms

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Color mode is selected automatically based on terminal capabilities.

This is the recommended function for capability-aware ASCII conversion.

Definition at line 188 of file ascii.c.

                                                                         {
 
  if (original == NULL || caps == NULL) {
    log_error("Invalid parameters for ascii_convert_with_capabilities");
    return NULL;
  }
 
  // Start with the target dimensions requested by the user
  ssize_t resized_width = width;
  ssize_t resized_height = height;
 
  // Height doubling for half-block mode is now handled by the server
 
  // If stretch is enabled, use full dimensions, otherwise calculate aspect ratio
  if (use_aspect_ratio && caps->render_mode != RENDER_MODE_HALF_BLOCK) {
    // Normal modes: apply aspect ratio correction
    aspect_ratio(original->w, original->h, resized_width, resized_height, stretch, &resized_width, &resized_height);
  }
  // Half-block mode: skip aspect ratio to preserve full doubled dimensions for 2x resolution
 
  // Calculate padding for centering
  size_t pad_width = 0;
  size_t pad_height = 0;
 
  if (use_aspect_ratio) {
    ssize_t pad_width_ss = width > resized_width ? (width - resized_width) / 2 : 0;
    pad_width = (size_t)pad_width_ss;
 
    ssize_t pad_height_ss = height > resized_height ? (height - resized_height) / 2 : 0;
    pad_height = (size_t)pad_height_ss;
  }
 
  // 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
  struct timespec prof_alloc_start, prof_alloc_end, prof_resize_start, prof_resize_end;
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_alloc_start);
 
  image_t *resized = image_new((size_t)resized_width, (size_t)resized_height);
  if (!resized) {
    log_error("Failed to allocate resized image");
    return NULL;
  }
 
  image_clear(resized);
 
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_alloc_end);
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_resize_start);
 
  image_resize(original, resized);
 
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_resize_end);
 
  // PROFILING: Time ASCII print
  struct timespec prof_print_start, prof_print_end;
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_print_start);
 
  // Use the capability-aware image printing function with client's palette
  char *ascii = image_print_with_capabilities(resized, caps, palette_chars, luminance_palette);
 
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_print_end);
 
  uint64_t alloc_time_us = ((uint64_t)prof_alloc_end.tv_sec * 1000000 + (uint64_t)prof_alloc_end.tv_nsec / 1000) -
                           ((uint64_t)prof_alloc_start.tv_sec * 1000000 + (uint64_t)prof_alloc_start.tv_nsec / 1000);
  uint64_t resize_time_us = ((uint64_t)prof_resize_end.tv_sec * 1000000 + (uint64_t)prof_resize_end.tv_nsec / 1000) -
                            ((uint64_t)prof_resize_start.tv_sec * 1000000 + (uint64_t)prof_resize_start.tv_nsec / 1000);
  uint64_t print_time_us = ((uint64_t)prof_print_end.tv_sec * 1000000 + (uint64_t)prof_print_end.tv_nsec / 1000) -
                           ((uint64_t)prof_print_start.tv_sec * 1000000 + (uint64_t)prof_print_start.tv_nsec / 1000);
 
  // PROFILING: Time padding
  struct timespec prof_pad_start, prof_pad_end;
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_pad_start);
 
  if (!ascii) {
    log_error("Failed to convert image to ASCII using terminal capabilities");
    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);
    SAFE_FREE(ascii);
    image_destroy(resized);
    return NULL;
  }
 
  char *ascii_width_padded = ascii_pad_frame_width(ascii, pad_width);
  SAFE_FREE(ascii);
 
  char *ascii_padded = ascii_pad_frame_height(ascii_width_padded, pad_height);
  SAFE_FREE(ascii_width_padded);
 
  (void)clock_gettime(CLOCK_MONOTONIC, &prof_pad_end);
 
  uint64_t pad_time_us = ((uint64_t)prof_pad_end.tv_sec * 1000000 + (uint64_t)prof_pad_end.tv_nsec / 1000) -
                         ((uint64_t)prof_pad_start.tv_sec * 1000000 + (uint64_t)prof_pad_start.tv_nsec / 1000);
  (void)alloc_time_us;
  (void)resize_time_us;
  (void)print_time_us;
  (void)pad_time_us;
 
  image_destroy(resized);
 
  return ascii_padded;
}

References ascii_pad_frame_height(), ascii_pad_frame_width(), aspect_ratio(), image_t::h, image_clear(), image_destroy(), image_new(), image_print_with_capabilities(), image_resize(), log_error, terminal_capabilities_t::render_mode, RENDER_MODE_HALF_BLOCK, SAFE_FREE, and image_t::w.

Referenced by mirror_main().

ascii_create_grid()

char * ascii_create_grid	(	ascii_frame_source_t *	sources,
		int	source_count,
		int	width,
		int	height,
		size_t *	out_size
	)

#include <ascii.h>

Create a grid layout from multiple ASCII frames.

Parameters

sources	Array of frame sources (must not be NULL, must have source_count elements)
source_count	Number of frame sources (must be > 0)
width	Grid width in characters per frame (must be > 0)
height	Grid height in characters per frame (must be > 0)
out_size	Pointer to store output size in bytes (can be NULL)

Returns

Allocated grid frame string (caller must free), or NULL on error

Combines multiple ASCII frames into a single grid layout. Arranges frames in a grid pattern suitable for multi-user display. Each frame is positioned in the grid according to its index in the sources array.

GRID LAYOUT:

• Frames are arranged in grid pattern (rows and columns)
• Each frame has specified width and height in characters
• Grid dimensions are calculated based on source_count
• Output frame contains all frames arranged in grid

Note

Returns NULL on error (invalid sources, memory allocation failure).

Grid frame string must be freed by caller using free().

Frame sources must have valid frame_data and frame_size.

Grid layout is useful for multi-user video display.

Example

ascii_frame_source_t sources[4];
// Initialize sources...
char *grid = ascii_create_grid(sources, 4, 80, 40, NULL);
if (grid) {
    ascii_write(grid);
    free(grid);
}

Creates a grid layout from multiple ASCII frame sources with | and _ separators.

Parameters: sources Array of ASCII frame sources to combine source_count Number of sources in the array width Target width of the output grid height Target height of the output grid out_size Output parameter for the size of the returned buffer

Returns: A newly allocated, null-terminated string containing the grid layout, or NULL on error. Caller must free the returned buffer.

Definition at line 450 of file ascii.c.

                                                                                                                  {
  if (!sources || source_count <= 0 || width <= 0 || height <= 0 || !out_size) {
    return NULL;
  }
 
  // If no sources, return empty frame
 
  // If only one source, center it properly to maintain aspect ratio and look good
  if (source_count == 1) {
    // Create a frame of the target size filled with spaces
    // Check for integer overflow before multiplication
    size_t w = (size_t)width;
    size_t h = (size_t)height;
    size_t w_times_h;
    if (checked_size_mul(w, h, &w_times_h) != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_INVALID_PARAM, "ascii_create_grid: dimensions would overflow: %dx%d", width, height);
      return NULL;
    }
 
    size_t w_times_h_plus_h;
    if (checked_size_add(w_times_h, h, &w_times_h_plus_h) != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_INVALID_PARAM, "ascii_create_grid: buffer size would overflow: %dx%d", width, height);
      return NULL;
    }
 
    size_t target_size;
    if (checked_size_add(w_times_h_plus_h, 1, &target_size) != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_INVALID_PARAM, "ascii_create_grid: buffer size would overflow: %dx%d", width, height);
      return NULL;
    }
    char *result;
    result = SAFE_MALLOC(target_size, char *);
    SAFE_MEMSET(result, target_size, ' ', target_size - 1);
    result[target_size - 1] = '\0';
 
    // Add newlines at the end of each row
    for (int row = 0; row < height; row++) {
      result[row * (width + 1) + width] = '\n';
    }
 
    // Copy the source frame into the result, line by line, centering it
    // Handle NULL frame_data gracefully
    const char *src_data = sources[0].frame_data;
    int src_pos = 0;
    int src_size = (int)sources[0].frame_size;
 
    // If source data is NULL or empty, just return the empty frame
    if (!src_data || src_size <= 0) {
      *out_size = target_size - 1; // Don't count null terminator
      return result;
    }
 
    // Count lines in source to calculate vertical padding
    int src_lines = 0;
    for (int i = 0; i < src_size; i++) {
      if (src_data[i] == '\n')
        src_lines++;
    }
 
    int v_padding = (height - src_lines) / 2;
    if (v_padding < 0)
      v_padding = 0;
 
    int dst_row = v_padding;
    src_pos = 0;
 
    while (src_pos < src_size && dst_row < height) {
      // Find end of current line in source
      int line_start = src_pos;
      int line_len = 0;
      while (src_pos < src_size && src_data[src_pos] != '\n') {
        line_len++;
        src_pos++;
      }
 
      // Calculate horizontal padding to center the line
      int h_padding = (width - line_len) / 2;
      if (h_padding < 0)
        h_padding = 0;
 
      // Copy line to result with padding
      // Use size_t for position calculation to prevent integer underflow
      size_t row_offset = (size_t)dst_row * (size_t)(width + 1);
      size_t dst_pos = row_offset + (size_t)h_padding;
      int copy_len = (line_len > width - h_padding) ? width - h_padding : line_len;
 
      if (copy_len > 0 && dst_pos + (size_t)copy_len < target_size) {
        SAFE_MEMCPY(&result[dst_pos], target_size - dst_pos, &src_data[line_start], (size_t)copy_len);
      }
 
      // Skip newline in source
      if (src_pos < src_size && src_data[src_pos] == '\n') {
        src_pos++;
      }
 
      dst_row++;
    }
 
    *out_size = target_size - 1; // Don't count null terminator
    return result;
  }
 
  // 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;
 
  int grid_cols, grid_rows;
  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;
 
  // Calculate dimensions for each cell (leave 1 char for separators)
  int cell_width = (width - (grid_cols - 1)) / grid_cols;
  int cell_height = (height - (grid_rows - 1)) / grid_rows;
 
  if (cell_width < 10 || cell_height < 3) {
    // Too small for grid layout, just use first source
    char *result;
    result = SAFE_MALLOC(sources[0].frame_size + 1, char *);
    if (sources[0].frame_data && sources[0].frame_size > 0) {
      SAFE_MEMCPY(result, sources[0].frame_size + 1, sources[0].frame_data, sources[0].frame_size);
      result[sources[0].frame_size] = '\0';
      *out_size = sources[0].frame_size;
    } else {
      // Handle NULL or empty frame data
      result[0] = '\0';
      *out_size = 0;
    }
    return result;
  }
 
  // Allocate mixed frame buffer
  // Check for integer overflow before multiplication
  size_t w_sz = (size_t)width;
  size_t h_sz = (size_t)height;
  if (w_sz > SIZE_MAX / h_sz) {
    SET_ERRNO(ERROR_INVALID_PARAM, "ascii_create_grid: dimensions would overflow: %dx%d", width, height);
    return NULL;
  }
  size_t mixed_size = w_sz * h_sz + h_sz + 1; // +1 for null terminator, +height for newlines
  char *mixed_frame;
  mixed_frame = SAFE_MALLOC(mixed_size, char *);
 
  // Initialize mixed frame with spaces
  SAFE_MEMSET(mixed_frame, mixed_size, ' ', mixed_size - 1);
  mixed_frame[mixed_size - 1] = '\0';
 
  // Add newlines at the end of each row
  for (int row = 0; row < height; row++) {
    mixed_frame[row * (width + 1) + width] = '\n';
  }
 
  // Place each video source in the grid
  for (int src = 0; src < source_count; src++) {
    int grid_row = src / grid_cols;
    int grid_col = src % grid_cols;
 
    // Calculate position in mixed frame
    int start_row = grid_row * (cell_height + 1); // +1 for separator
    int start_col = grid_col * (cell_width + 1);  // +1 for separator
 
    // Parse source frame line by line and place in grid
    const char *src_data = sources[src].frame_data;
    int src_row = 0;
    int src_pos = 0;
 
    while (src_pos < (int)sources[src].frame_size && src_row < cell_height && start_row + src_row < height) {
      // Find end of current line in source
      int line_start = src_pos;
      while (src_pos < (int)sources[src].frame_size && src_data[src_pos] != '\n') {
        src_pos++;
      }
      int line_len = src_pos - line_start;
 
      // Copy line to mixed frame (truncate if too long)
      int copy_len = (line_len < cell_width) ? line_len : cell_width;
      if (copy_len > 0 && start_col + copy_len <= width) {
        int mixed_pos = (start_row + src_row) * (width + 1) + start_col;
        SAFE_MEMCPY(mixed_frame + mixed_pos, mixed_size - (size_t)mixed_pos, src_data + line_start, (size_t)copy_len);
      }
 
      // Move to next line
      if (src_pos < (int)sources[src].frame_size && src_data[src_pos] == '\n') {
        src_pos++;
      }
      src_row++;
    }
 
    // Draw separators with bounds checking to prevent buffer overflow
    if (grid_col < grid_cols - 1 && start_col + cell_width < width) {
      // Vertical separator
      for (int row = start_row; row < start_row + cell_height && row < height; row++) {
        size_t idx = (size_t)row * (size_t)(width + 1) + (size_t)(start_col + cell_width);
        if (idx < mixed_size - 1) { // -1 to preserve null terminator
          mixed_frame[idx] = '|';
        }
      }
    }
 
    if (grid_row < grid_rows - 1 && start_row + cell_height < height) {
      // Horizontal separator
      for (int col = start_col; col < start_col + cell_width && col < width; col++) {
        size_t idx = (size_t)(start_row + cell_height) * (size_t)(width + 1) + (size_t)col;
        if (idx < mixed_size - 1) { // -1 to preserve null terminator
          mixed_frame[idx] = '_';
        }
      }
      // Corner character where separators meet
      if (grid_col < grid_cols - 1 && start_col + cell_width < width) {
        size_t idx = (size_t)(start_row + cell_height) * (size_t)(width + 1) + (size_t)(start_col + cell_width);
        if (idx < mixed_size - 1) { // -1 to preserve null terminator
          mixed_frame[idx] = '+';
        }
      }
    }
  }
 
  *out_size = strlen(mixed_frame);
  return mixed_frame;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ascii_frame_source_t::frame_data, ascii_frame_source_t::frame_size, SAFE_MALLOC, SAFE_MEMCPY, SAFE_MEMSET, and SET_ERRNO.

ascii_pad_frame_height()

char * ascii_pad_frame_height	(	const char *	frame,
		size_t	pad_top
	)

#include <ascii.h>

Add blank lines (vertical padding) to center a frame vertically.

Parameters

frame	ASCII frame string (must not be NULL)
pad_top	Number of blank lines to add at top (must be >= 0)

Returns

Allocated padded frame string (caller must free with free()), or NULL on error

Adds blank lines (vertical padding) to the top of an ASCII frame. Useful for centering frames vertically or creating margins. Blank lines are added at the top of the frame.

Note

Returns NULL on error (invalid frame, memory allocation failure).

Padded frame string must be freed by caller using free().

Frame width is preserved (characters per line unchanged).

Frame height is increased by 'pad_top' lines.

Adds vertical padding (blank lines) to center a frame vertically.

Parameters: frame The input ASCII frame to pad vertically. pad_top Number of blank lines to add at the top.

Returns: A newly allocated, null-terminated string with vertical padding, or NULL if frame is NULL.

Definition at line 738 of file ascii.c.

                                                                {
  if (!frame) {
    return NULL;
  }
 
  if (pad_top == 0) {
    // Nothing to do; return a copy because the caller knows to free() the value.
    size_t orig_len = strlen(frame);
    char *copy;
    copy = SAFE_MALLOC(orig_len + 1, char *);
    SAFE_MEMCPY(copy, orig_len + 1, frame, orig_len + 1);
    return copy;
  }
 
  // Calculate buffer size needed
  size_t frame_len = strlen(frame);
  size_t top_padding_len = pad_top; // Just newlines, no spaces
  size_t total_len = top_padding_len + frame_len;
 
  char *buffer;
  buffer = SAFE_MALLOC(total_len + 1, char *);
 
  char *position = buffer;
 
  // Add top padding (blank lines - just newlines)
  for (size_t i = 0; i < pad_top; i++) {
    *position++ = '\n';
  }
 
  // Copy the original frame
  size_t remaining = total_len + 1 - pad_top;
  SAFE_MEMCPY(position, remaining, frame, frame_len);
  position += frame_len;
  *position = '\0';
 
  return buffer;
}

References SAFE_MALLOC, and SAFE_MEMCPY.

Referenced by ascii_convert(), and ascii_convert_with_capabilities().

ascii_pad_frame_width()

char * ascii_pad_frame_width	(	const char *	frame,
		size_t	pad
	)

#include <ascii.h>

Add leading spaces (left-padding) to each line of a frame.

Parameters

frame	ASCII frame string (must not be NULL)
pad	Number of spaces to pad on left (must be >= 0)

Returns

Allocated padded frame string (caller must free with free()), or NULL on error

Adds leading spaces (left-padding) to each line of an ASCII frame. Useful for centering frames horizontally or creating margins. Each line in the frame is padded with the specified number of spaces.

Note

Returns NULL on error (invalid frame, memory allocation failure).

Padded frame string must be freed by caller using free().

Frame height is preserved (number of lines unchanged).

Frame width is increased by 'pad' characters.

Definition at line 375 of file ascii.c.

                                                                {
  if (!frame) {
    return NULL;
  }
 
  if (pad_left == 0) {
    // Nothing to do; return a copy so the caller can free it safely without
    // worrying about the original allocation strategy.
    size_t orig_len = strlen(frame);
    char *copy;
    copy = SAFE_MALLOC(orig_len + 1, char *);
    SAFE_MEMCPY(copy, orig_len + 1, frame, orig_len + 1);
    return copy;
  }
 
  // Count how many visual rows we have (lines terminated by '\n') to determine
  // the final buffer size.
  size_t line_count = 1; // There is always at least the first line
  const char *char_in_frame = frame;
  while (*char_in_frame) {
    if (*char_in_frame == '\n') {
      line_count++;
    }
    char_in_frame++;
  }
 
  // Total length of the source plus padding.
  const size_t frame_len = strlen(frame);
  const size_t left_padding_len = line_count * pad_left;
  const size_t total_len = frame_len + left_padding_len;
 
  char *buffer;
  buffer = SAFE_MALLOC(total_len + 1, char *);
 
  // Build the padded frame.
  bool at_line_start = true;
  const char *src = frame;
  char *position = buffer;
 
  while (*src) {
    if (at_line_start) {
      // Insert the requested amount of spaces in front of every visual row.
      size_t remaining = (size_t)((ptrdiff_t)(buffer + total_len + 1) - (ptrdiff_t)position);
      SAFE_MEMSET(position, remaining, ' ', (size_t)pad_left);
      position += pad_left;
      at_line_start = false;
    }
 
    *position++ = *src;
 
    if (*src == '\n') {
      at_line_start = true;
    }
 
    src++;
  }
 
  *position = '\0';
  return buffer;
}

References SAFE_MALLOC, SAFE_MEMCPY, and SAFE_MEMSET.

Referenced by ascii_convert(), and ascii_convert_with_capabilities().

ascii_read_destroy()

void ascii_read_destroy

(

void

)

#include <ascii.h>

Destroy ASCII read subsystem.

Cleans up the ASCII read subsystem and releases resources. Closes webcam device and frees associated memory. Should be called when done with image capture.

Note

Safe to call multiple times (no-op after first call).

After cleanup, webcam capture will fail until re-initialized.

Definition at line 355 of file ascii.c.

                              {
  webcam_cleanup();
  log_debug("ASCII reader destroyed");
}

References log_debug, and webcam_cleanup().

ascii_read_init()

asciichat_error_t ascii_read_init

(

unsigned short int

webcam_index

)

#include <ascii.h>

Initialize ASCII read subsystem (e.g., webcam)

Parameters

webcam_index

Webcam device index (0 for default device)

Returns

ASCIICHAT_OK on success, error code on failure

Initializes the ASCII read subsystem for image capture. Opens webcam device and prepares it for frame capture. This is a convenience wrapper around webcam initialization.

Note

This function initializes webcam capture for ASCII conversion.

Must call ascii_read_destroy() when done.

Use webcam_read() to capture frames after initialization.

Warning

On failure, use webcam_print_init_error_help() for diagnostics.

Definition at line 34 of file ascii.c.

                                                                   {
  log_info("Initializing ASCII reader with webcam index %u", webcam_index);
  webcam_init(webcam_index);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, log_info, and webcam_init().

ascii_simd_init()

void ascii_simd_init

(

void

)

#include <ascii_simd.h>

Initialize SIMD subsystem.

Initializes all SIMD subsystems and caches. Must be called once at startup.

Definition at line 90 of file ascii_simd.c.

                           {
  // Initialize SIMD lookup tables manually (constructor disabled for musl compatibility)
  // Both init functions have guards to prevent double-initialization
  init_dec3();
  init_default_luminance_palette();
}

References init_dec3(), and init_default_luminance_palette().

Referenced by ansi_fast_init(), and server_main().

ascii_write()

asciichat_error_t ascii_write

(

const char *

frame

)

#include <ascii.h>

Write ASCII frame to terminal.

Parameters

frame

ASCII frame string to write (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Writes an ASCII frame string to the terminal output. Frame string may contain ANSI escape sequences for color output and cursor positioning. Output is written to the file descriptor configured during ascii_write_init().

Note

Frame string should be null-terminated.

ANSI escape sequences in frame string are processed by terminal.

Output is written immediately (no buffering).

Definition at line 312 of file ascii.c.

                                                 {
  if (frame == NULL) {
    log_warn("Attempted to write NULL frame");
    return ERROR_INVALID_PARAM;
  }
 
  // Skip cursor reset in snapshot mode or when testing - just print raw ASCII
  const char *testing_env = SAFE_GETENV("TESTING");
  if (!GET_OPTION(snapshot_mode) && testing_env == NULL) {
    cursor_reset(STDOUT_FILENO);
  }
 
  size_t frame_len = strlen(frame);
  size_t written = fwrite(frame, 1, frame_len, stdout);
  if (written != frame_len) {
    log_error("Failed to write ASCII frame");
    return ERROR_TERMINAL;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, cursor_reset, ERROR_INVALID_PARAM, ERROR_TERMINAL, GET_OPTION, log_error, log_warn, and SAFE_GETENV.

ascii_write_destroy()

void ascii_write_destroy	(	int	fd,
		bool	reset_terminal
	)

#include <ascii.h>

Destroy ASCII write subsystem.

Parameters

fd	File descriptor that was used for writing (must be valid)
reset_terminal	Whether to reset terminal on cleanup (true to restore state, false to preserve)

Cleans up the ASCII write subsystem and restores terminal state. Restores cursor visibility, clears screen, and resets terminal attributes if reset_terminal is true.

TERMINAL CLEANUP:

• Restores cursor visibility (if reset_terminal is true)
• Resets terminal attributes (if reset_terminal is true)
• Clears screen (if reset_terminal is true)
• Restores terminal to default state

Note

Safe to call multiple times (no-op after first call).

Reset terminal restores terminal to default state.

After cleanup, terminal output functions may fail until re-initialized.

Definition at line 334 of file ascii.c.

                                                      {
#if PLATFORM_WINDOWS
  (void)fd; // Unused on Windows - terminal operations use stdout directly
#endif
  // console_clear(fd);
  // cursor_reset(fd);
  // Skip cursor show in snapshot mode - leave terminal as-is
  if (!GET_OPTION(snapshot_mode) && reset_terminal) {
    // Show cursor using platform abstraction
    if (terminal_hide_cursor(fd, false) != 0) {
      log_warn("Failed to show cursor");
    }
 
    // Re-enable echo using platform abstraction
    if (terminal_set_echo(true) != 0) {
      log_warn("Failed to re-enable echo");
    }
  }
  log_debug("ASCII writer destroyed");
}

References GET_OPTION, log_debug, log_warn, terminal_hide_cursor(), and terminal_set_echo().

Referenced by display_cleanup().

ascii_write_init()

asciichat_error_t ascii_write_init	(	int	fd,
		bool	reset_terminal
	)

#include <ascii.h>

Initialize ASCII write subsystem.

Parameters

fd	File descriptor to write to (must be valid file descriptor)
reset_terminal	Whether to reset terminal on initialization (true to reset, false to preserve state)

Returns

ASCIICHAT_OK on success, error code on failure

Initializes the ASCII write subsystem for terminal output. Configures terminal for ASCII art display including cursor hiding, screen clearing, and terminal state management.

TERMINAL INITIALIZATION:

• Hides cursor (if reset_terminal is true)
• Clears screen (if reset_terminal is true)
• Configures terminal for raw output
• Prepares terminal for ASCII art display

Note

Must call ascii_write_destroy() when done.

Reset terminal clears screen and hides cursor for clean display.

File descriptor is used for terminal output (stdout, stderr, etc.).

Definition at line 40 of file ascii.c.

                                                                {
  // Validate file descriptor
  if (fd < 0) {
    log_error("Invalid file descriptor %d", fd);
    return ERROR_INVALID_PARAM;
  }
 
  // Skip terminal control sequences in snapshot mode or when testing - just print raw ASCII
  const char *testing_env = SAFE_GETENV("TESTING");
  if (!GET_OPTION(snapshot_mode) && reset_terminal && testing_env == NULL) {
    console_clear(fd);
    cursor_reset(fd);
 
    // Disable echo using platform abstraction
    if (terminal_set_echo(false) != 0) {
      log_error("Failed to disable echo for fd %d", fd);
      return ERROR_TERMINAL;
    }
    // Hide cursor using platform abstraction
    if (terminal_hide_cursor(fd, true) != 0) {
      log_warn("Failed to hide cursor");
    }
  }
  log_debug("ASCII writer initialized");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, console_clear, cursor_reset, ERROR_INVALID_PARAM, ERROR_TERMINAL, GET_OPTION, log_debug, log_error, log_warn, SAFE_GETENV, terminal_hide_cursor(), and terminal_set_echo().

Referenced by display_init().

benchmark_simd_color_conversion()

simd_benchmark_t benchmark_simd_color_conversion	(	int	width,
		int	height,
		int	iterations,
		bool	background_mode
	)

#include <ascii_simd.h>

Benchmark SIMD color conversion methods.

Parameters

width	Image width in pixels
height	Image height in pixels
iterations	Number of benchmark iterations
background_mode	Use background colors

Returns

Benchmark results structure

Definition at line 500 of file ascii_simd.c.

                                                                                                              {
  simd_benchmark_t result = {0};
 
  // Check for integer overflow in pixel count calculation
  size_t pixel_count;
  if (checked_size_mul((size_t)width, (size_t)height, &pixel_count) != ASCIICHAT_OK) {
    log_error("Image dimensions %d x %d too large (overflow)", width, height);
    return result;
  }
 
  // Estimate output buffer size for colored ASCII (much larger than monochrome)
  // Each pixel can generate ~25 bytes of ANSI escape codes + 1 char
  size_t output_buffer_size = pixel_count * 30 + (size_t)width * 10; // Extra for newlines/reset codes
 
  // Generate test data and test image for unified functions
  rgb_pixel_t *test_pixels;
  char *output_buffer;
  test_pixels = SAFE_CALLOC_SIMD(pixel_count, sizeof(rgb_pixel_t), rgb_pixel_t *);
  output_buffer = SAFE_MALLOC(output_buffer_size, char *);
 
  // Create test image for new unified functions
  image_t *frame = image_new(width, height);
  if (!frame) {
    SAFE_FREE(test_pixels);
    SAFE_FREE(output_buffer);
    return result;
  }
 
  // Use synthetic gradient data for consistent cross-platform benchmarking
  printf("Using coherent gradient data for realistic color testing\n");
  // NOLINTNEXTLINE(bugprone-random-generator-seed)
  srand(12345); // For consistent gradient variation across runs
  for (size_t i = 0; i < pixel_count; i++) {
    int x = i % width;
    int y = i / width;
    // Create smooth gradients with some variation (mimics real images)
    int base_r = (x * 255) / width;
    int base_g = (y * 255) / height;
    int base_b = ((x + y) * 127) / (width + height);
 
    // Add realistic variation
    int temp_r = base_r + (rand() % 32 - 16); // NOLINT(cert-msc30-c,cert-msc50-cpp)
    int temp_g = base_g + (rand() % 32 - 16); // NOLINT(cert-msc30-c,cert-msc50-cpp)
    int temp_b = base_b + (rand() % 32 - 16); // NOLINT(cert-msc30-c,cert-msc50-cpp)
 
    test_pixels[i].r = clamp_rgb(temp_r);
    test_pixels[i].g = clamp_rgb(temp_g);
    test_pixels[i].b = clamp_rgb(temp_b);
  }
 
  // Populate test image with same data as test_pixels
  frame->pixels = test_pixels;
 
  const char *mode_str = background_mode ? "background" : "foreground";
  printf("Benchmarking COLOR %s %dx%d (%zu pixels) x %d iterations...\n", mode_str, width, height, pixel_count,
         iterations);
 
  // Benchmark scalar color version
  double start = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *result_str = image_print_color(frame, DEFAULT_ASCII_PALETTE);
    if (result_str)
      SAFE_FREE(result_str);
  }
  result.scalar_time = get_time_seconds() - start;
 
#if SIMD_SUPPORT_SSE2
  // Benchmark SSE2 color using unified function
  start = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *ascii_output = render_ascii_sse2_unified_optimized(frame, background_mode, true, DEFAULT_ASCII_PALETTE);
    if (ascii_output)
      SAFE_FREE(ascii_output);
  }
  result.sse2_time = get_time_seconds() - start;
#endif
 
#if SIMD_SUPPORT_SSSE3
  // Benchmark SSSE3 color using unified function
  start = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *ascii_output = render_ascii_ssse3_unified_optimized(frame, background_mode, true, DEFAULT_ASCII_PALETTE);
    if (ascii_output)
      SAFE_FREE(ascii_output);
  }
  result.ssse3_time = get_time_seconds() - start;
#endif
 
#if SIMD_SUPPORT_AVX2
  // Benchmark AVX2 color using unified function
  start = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *ascii_output = render_ascii_avx2_unified_optimized(frame, background_mode, true, DEFAULT_ASCII_PALETTE);
    if (ascii_output)
      SAFE_FREE(ascii_output);
  }
  result.avx2_time = get_time_seconds() - start;
#endif
 
#if SIMD_SUPPORT_NEON
  // Benchmark NEON color
  start = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    // Create temporary image for unified function
    image_t temp_image = {.pixels = test_pixels, .w = width, .h = height, .alloc_method = IMAGE_ALLOC_SIMD};
    char *ascii_output = render_ascii_neon_unified_optimized(&temp_image, background_mode, true, DEFAULT_ASCII_PALETTE);
    if (ascii_output)
      SAFE_FREE(ascii_output);
  }
  result.neon_time = get_time_seconds() - start;
#endif
 
  // Find best method
  double best_time = result.scalar_time;
  result.best_method = "scalar";
 
#if SIMD_SUPPORT_SSE2
  if (result.sse2_time > 0 && result.sse2_time < best_time) {
    best_time = result.sse2_time;
    result.best_method = "SSE2";
  }
#endif
 
#if SIMD_SUPPORT_SSSE3
  if (result.ssse3_time > 0 && result.ssse3_time < best_time) {
    best_time = result.ssse3_time;
    result.best_method = "SSSE3";
  }
#endif
 
#if SIMD_SUPPORT_AVX2
  if (result.avx2_time > 0 && result.avx2_time < best_time) {
    best_time = result.avx2_time;
    result.best_method = "AVX2";
  }
#endif
 
#if SIMD_SUPPORT_NEON
  if (result.neon_time > 0 && result.neon_time < best_time) {
    best_time = result.neon_time;
    result.best_method = "NEON";
  }
#endif
 
  result.speedup_best = result.scalar_time / best_time;
 
  // Cleanup - frame owns test_pixels now
  frame->pixels = NULL; // Don't double-free
  image_destroy(frame);
  SAFE_FREE(test_pixels);
  SAFE_FREE(output_buffer);
 
  return result;
}

References ASCIICHAT_OK, simd_benchmark_t::avx2_time, simd_benchmark_t::best_method, DEFAULT_ASCII_PALETTE, IMAGE_ALLOC_SIMD, image_destroy(), image_new(), image_print_color(), log_error, simd_benchmark_t::neon_time, image_t::pixels, SAFE_CALLOC_SIMD, SAFE_FREE, SAFE_MALLOC, simd_benchmark_t::scalar_time, simd_benchmark_t::speedup_best, simd_benchmark_t::sse2_time, and simd_benchmark_t::ssse3_time.

benchmark_simd_color_conversion_with_source()

simd_benchmark_t benchmark_simd_color_conversion_with_source	(	int	width,
		int	height,
		int	iterations,
		bool	background_mode,
		const image_t *	source_image,
		bool	use_256color
	)

#include <ascii_simd.h>

Benchmark SIMD color conversion with source image.

Parameters

width	Image width in pixels
height	Image height in pixels
iterations	Number of benchmark iterations
background_mode	Use background colors
source_image	Source image for conversion
use_256color	Use 256-color mode

Returns

Benchmark results structure

benchmark_simd_conversion()

simd_benchmark_t benchmark_simd_conversion	(	int	width,
		int	height,
		int	iterations
	)

#include <ascii_simd.h>

Benchmark SIMD conversion methods (monochrome)

Parameters

width	Image width in pixels
height	Image height in pixels
iterations	Number of benchmark iterations

Returns

Benchmark results structure

benchmark_simd_conversion_with_source()

simd_benchmark_t benchmark_simd_conversion_with_source	(	int	width,
		int	height,
		int	iterations,
		bool	background_mode,
		const image_t *	source_image,
		bool	use_256color
	)

#include <ascii_simd.h>

Benchmark SIMD conversion with source image.

Parameters

width	Image width in pixels
height	Image height in pixels
iterations	Number of benchmark iterations
background_mode	Use background colors
source_image	Source image for conversion
use_256color	Use 256-color mode

Returns

Benchmark results structure

Definition at line 656 of file ascii_simd.c.

                                                                                                       {
  simd_benchmark_t result = {0};
  (void)background_mode; // Suppress unused parameter warning
  (void)use_256color;    // Suppress unused parameter warning
 
  // Check for integer overflow in pixel count calculation
  size_t pixel_count;
  if (checked_size_mul((size_t)width, (size_t)height, &pixel_count) != ASCIICHAT_OK) {
    log_error("Image dimensions %d x %d too large (overflow)", width, height);
    return result;
  }
 
  // Generate test data
  rgb_pixel_t *test_pixels;
  char *output_buffer;
  const size_t output_buffer_size = pixel_count * 16;
  test_pixels = SAFE_CALLOC_SIMD(pixel_count, sizeof(rgb_pixel_t), rgb_pixel_t *);
  output_buffer = SAFE_MALLOC(output_buffer_size, char *);
 
  if (source_image && source_image->pixels) {
    printf("Using provided image data (%dx%d) for testing\n", source_image->w, source_image->h);
 
    // Resize source image to test dimensions if needed
    if (source_image->w == width && source_image->h == height) {
      // Direct copy
      for (size_t i = 0; i < pixel_count; i++) {
        test_pixels[i].r = source_image->pixels[i].r;
        test_pixels[i].g = source_image->pixels[i].g;
        test_pixels[i].b = source_image->pixels[i].b;
      }
    } else {
      // Simple nearest-neighbor resize
      for (int y = 0; y < height; y++) {
        for (int x = 0; x < width; x++) {
          int src_x = (x * source_image->w) / width;
          int src_y = (y * source_image->h) / height;
          // Use size_t for index calculations to prevent integer overflow
          size_t src_idx = (size_t)src_y * (size_t)source_image->w + (size_t)src_x;
          size_t dst_idx = (size_t)y * (size_t)width + (size_t)x;
 
          if (src_idx < (size_t)source_image->w * (size_t)source_image->h) {
            test_pixels[dst_idx].r = source_image->pixels[src_idx].r;
            test_pixels[dst_idx].g = source_image->pixels[src_idx].g;
            test_pixels[dst_idx].b = source_image->pixels[src_idx].b;
          }
        }
      }
      printf("Resized image data from %dx%d to %dx%d\n", source_image->w, source_image->h, width, height);
    }
  } else {
    // Fall back to synthetic gradient data
    printf("No source image provided, using synthetic gradient data\n");
    srand(12345); // NOLINT(cert-msc32-c,cert-msc51-cpp,bugprone-random-generator-seed)
    for (size_t i = 0; i < pixel_count; i++) {
      int x = i % width;
      int y = i / width;
      int base_r = (x * 255 / width);
      int base_g = (y * 255 / height);
      int base_b = ((x + y) * 127 / (width + height));
 
      int temp_r = base_r + (rand() % 16 - 8); // NOLINT(cert-msc30-c,cert-msc50-cpp)
      int temp_g = base_g + (rand() % 16 - 8); // NOLINT(cert-msc30-c,cert-msc50-cpp)
      int temp_b = base_b + (rand() % 16 - 8); // NOLINT(cert-msc30-c,cert-msc50-cpp)
 
      test_pixels[i].r = clamp_rgb(temp_r);
      test_pixels[i].g = clamp_rgb(temp_g);
      test_pixels[i].b = clamp_rgb(temp_b);
    }
  }
 
  // Calculate adaptive iterations for reliable timing
  int adaptive_iterations = calculate_adaptive_iterations(pixel_count, 10.0);
  printf("Benchmarking %dx%d (%zu pixels) using %d adaptive iterations (ignoring passed iterations)...\n", width,
         height, pixel_count, adaptive_iterations);
 
  // Benchmark all available SIMD variants using unified image-based API
  image_t *frame = image_new(width, height);
  memcpy(frame->pixels, test_pixels, pixel_count * sizeof(rgb_pixel_t));
 
  // Benchmark scalar using color conversion
  ensure_default_palette_ready();
  double start_scalar = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *result_str = image_print_color(frame, DEFAULT_ASCII_PALETTE);
    if (result_str)
      SAFE_FREE(result_str);
  }
  result.scalar_time = (get_time_seconds() - start_scalar) / iterations;
 
#if SIMD_SUPPORT_SSE2
  // Benchmark SSE2 using unified optimized renderer
  // Benchmark SSE2 color rendering
  ensure_default_palette_ready();
  double start_sse2_color = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *result_str = render_ascii_sse2_unified_optimized(frame, background_mode, use_256color, DEFAULT_ASCII_PALETTE);
    if (result_str)
      SAFE_FREE(result_str);
  }
  result.sse2_time = (get_time_seconds() - start_sse2_color) / iterations;
#endif
 
#if SIMD_SUPPORT_SSSE3
  // Benchmark SSSE3 using unified optimized renderer
  // Benchmark SSSE3 color rendering
  ensure_default_palette_ready();
  double start_ssse3_color = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *result_str =
        render_ascii_ssse3_unified_optimized(frame, background_mode, use_256color, DEFAULT_ASCII_PALETTE);
    if (result_str)
      SAFE_FREE(result_str);
  }
  result.ssse3_time = (get_time_seconds() - start_ssse3_color) / iterations;
#endif
 
#if SIMD_SUPPORT_AVX2
  // Benchmark AVX2 using unified optimized renderer
  // Benchmark AVX2 color rendering
  ensure_default_palette_ready();
  double start_avx2_color = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *result_str = render_ascii_avx2_unified_optimized(frame, background_mode, use_256color, DEFAULT_ASCII_PALETTE);
    if (result_str)
      SAFE_FREE(result_str);
  }
  result.avx2_time = (get_time_seconds() - start_avx2_color) / iterations;
#endif
 
#if SIMD_SUPPORT_NEON
  // Benchmark NEON using unified optimized renderer
  // Benchmark NEON color rendering
  ensure_default_palette_ready();
  double start_neon_color = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *result_str = render_ascii_neon_unified_optimized(frame, background_mode, use_256color, DEFAULT_ASCII_PALETTE);
    if (result_str)
      SAFE_FREE(result_str);
  }
  result.neon_time = (get_time_seconds() - start_neon_color) / iterations;
#endif
 
#if SIMD_SUPPORT_SVE
  // Benchmark SVE using unified optimized renderer
  // Benchmark SVE color rendering
  ensure_default_palette_ready();
  double start_sve_color = get_time_seconds();
  for (int i = 0; i < iterations; i++) {
    char *result_str = render_ascii_sve_unified_optimized(frame, background_mode, use_256color, DEFAULT_ASCII_PALETTE);
    if (result_str)
      SAFE_FREE(result_str);
  }
  result.sve_time = (get_time_seconds() - start_sve_color) / iterations;
#endif
 
  // Find best method
  double best_time = result.scalar_time;
  result.best_method = "scalar";
 
#if SIMD_SUPPORT_SSE2
  if (result.sse2_time > 0 && result.sse2_time < best_time) {
    best_time = result.sse2_time;
    result.best_method = "SSE2";
  }
#endif
 
#if SIMD_SUPPORT_SSSE3
  if (result.ssse3_time > 0 && result.ssse3_time < best_time) {
    best_time = result.ssse3_time;
    result.best_method = "SSSE3";
  }
#endif
 
#if SIMD_SUPPORT_AVX2
  if (result.avx2_time > 0 && result.avx2_time < best_time) {
    best_time = result.avx2_time;
    result.best_method = "AVX2";
  }
#endif
 
#if SIMD_SUPPORT_NEON
  if (result.neon_time > 0 && result.neon_time < best_time) {
    best_time = result.neon_time;
    result.best_method = "NEON";
  }
#endif
 
  result.speedup_best = result.scalar_time / best_time;
 
#if SIMD_SUPPORT_SVE
  if (result.sve_time > 0 && result.sve_time < best_time) {
    best_time = result.sve_time;
    result.best_method = "SVE";
  }
#endif
 
  image_destroy(frame);
  SAFE_FREE(test_pixels);
  SAFE_FREE(output_buffer);
 
  return result;
}

References ASCIICHAT_OK, simd_benchmark_t::avx2_time, simd_benchmark_t::best_method, DEFAULT_ASCII_PALETTE, image_t::h, image_destroy(), image_new(), image_print_color(), log_error, simd_benchmark_t::neon_time, image_t::pixels, SAFE_CALLOC_SIMD, SAFE_FREE, SAFE_MALLOC, simd_benchmark_t::scalar_time, simd_benchmark_t::speedup_best, simd_benchmark_t::sse2_time, simd_benchmark_t::ssse3_time, simd_benchmark_t::sve_time, and image_t::w.

build_ramp64()

void build_ramp64	(	uint8_t	ramp64[64],
		const char *	ascii_chars
	)

#include <common.h>

Build 64-entry character ramp cache.

Parameters

ramp64	Output array for ramp indices
ascii_chars	Character palette string

Definition at line 31 of file video/simd/common.c.

                                                                        {
  if (!ascii_chars) {
    // Fallback to space character
    for (int i = 0; i < RAMP64_SIZE; i++) {
      ramp64[i] = ' ';
    }
    return;
  }
 
  // Use UTF-8 palette functions for proper character handling
  utf8_palette_t *utf8_pal = utf8_palette_create(ascii_chars);
  if (!utf8_pal) {
    // Fallback to space character
    for (int i = 0; i < RAMP64_SIZE; i++) {
      ramp64[i] = ' ';
    }
    return;
  }
 
  size_t char_count = utf8_palette_get_char_count(utf8_pal);
  if (char_count == 0) {
    // No valid characters found, use space
    for (int i = 0; i < RAMP64_SIZE; i++) {
      ramp64[i] = ' ';
    }
    utf8_palette_destroy(utf8_pal);
    return;
  }
 
  // Build the ramp64 lookup using UTF-8 character indices
  for (int i = 0; i < RAMP64_SIZE; i++) {
    // Map 0-63 to 0-(char_count-1) using proper character indexing
    size_t char_idx = (i * (char_count - 1) + (RAMP64_SIZE - 1) / 2) / (RAMP64_SIZE - 1);
    if (char_idx >= char_count) {
      char_idx = char_count - 1;
    }
 
    // Get the first byte of the character at this character index
    const utf8_char_info_t *char_info = utf8_palette_get_char(utf8_pal, char_idx);
    if (char_info) {
      ramp64[i] = (uint8_t)char_info->bytes[0];
    } else {
      ramp64[i] = ' '; // Fallback
    }
  }
 
  utf8_palette_destroy(utf8_pal);
}

References utf8_char_info_t::bytes, RAMP64_SIZE, utf8_palette_create(), utf8_palette_destroy(), utf8_palette_get_char(), and utf8_palette_get_char_count().

build_utf8_luminance_cache()

void build_utf8_luminance_cache	(	const char *	ascii_chars,
		utf8_char_t	cache[256]
	)

#include <common.h>

Build UTF-8 luminance cache.

Parameters

ascii_chars	Character palette string
cache	Output cache array (256 entries)

Definition at line 410 of file video/simd/common.c.

                                                                                 {
  if (!ascii_chars || !cache)
    return;
 
  // Parse characters
  typedef struct {
    const char *start;
    int byte_len;
  } char_info_t;
 
  char_info_t char_infos[256];
  int char_count = 0;
  const char *p = ascii_chars;
 
  while (*p && char_count < 255) {
    char_infos[char_count].start = p;
 
    if ((*p & 0xE0) == 0xC0) {
      char_infos[char_count].byte_len = 2;
      p += 2;
    } else if ((*p & 0xF0) == 0xE0) {
      char_infos[char_count].byte_len = 3;
      p += 3;
    } else if ((*p & 0xF8) == 0xF0) {
      char_infos[char_count].byte_len = 4;
      p += 4;
    } else {
      // ASCII characters (0x00-0x7F) and invalid sequences: treat as single byte
      char_infos[char_count].byte_len = 1;
      p++;
    }
    char_count++;
  }
 
  // Handle empty string case
  if (char_count == 0)
    return;
 
  // Build 256-entry cache
  for (int i = 0; i < 256; i++) {
    int char_idx = char_count > 1 ? (i * (char_count - 1) + 127) / 255 : 0;
    if (char_idx >= char_count)
      char_idx = char_count - 1;
 
    cache[i].byte_len = char_infos[char_idx].byte_len;
    memcpy(cache[i].utf8_bytes, char_infos[char_idx].start, char_infos[char_idx].byte_len);
    if (cache[i].byte_len < 4) {
      cache[i].utf8_bytes[cache[i].byte_len] = '\0';
    }
  }
}

References utf8_char_t::byte_len, and utf8_char_t::utf8_bytes.

build_utf8_ramp64_cache()

void build_utf8_ramp64_cache	(	const char *	ascii_chars,
		utf8_char_t	cache64[64],
		uint8_t	char_index_ramp[64]
	)

#include <common.h>

Build UTF-8 ramp64 cache.

Parameters

ascii_chars	Character palette string
cache64	Output cache array (64 entries)
char_index_ramp	Output character index ramp (64 entries)

Definition at line 463 of file video/simd/common.c.

                                                                                                            {
  if (!ascii_chars || !cache64 || !char_index_ramp)
    return;
 
  // Reuse the luminance cache building logic but for 64 entries
  // (Same UTF-8 parsing as above, but map to 64 entries instead of 256)
 
  // Parse characters (same as above)
  typedef struct {
    const char *start;
    int byte_len;
  } char_info_t;
 
  char_info_t char_infos[256];
  int char_count = 0;
  const char *p = ascii_chars;
 
  while (*p && char_count < 255) {
    char_infos[char_count].start = p;
 
    if ((*p & 0xE0) == 0xC0) {
      char_infos[char_count].byte_len = 2;
      p += 2;
    } else if ((*p & 0xF0) == 0xE0) {
      char_infos[char_count].byte_len = 3;
      p += 3;
    } else if ((*p & 0xF8) == 0xF0) {
      char_infos[char_count].byte_len = 4;
      p += 4;
    } else {
      // ASCII characters (0x00-0x7F) and invalid sequences: treat as single byte
      char_infos[char_count].byte_len = 1;
      p++;
    }
    char_count++;
  }
 
  // Handle empty string case
  if (char_count == 0)
    return;
 
  // Build 64-entry cache and index ramp
  for (int i = 0; i < 64; i++) {
    int char_idx = char_count > 1 ? (i * (char_count - 1) + 31) / 63 : 0;
    if (char_idx >= char_count)
      char_idx = char_count - 1;
 
    // Store character index for SIMD lookup
    char_index_ramp[i] = (uint8_t)char_idx;
 
    // Cache UTF-8 character
    cache64[i].byte_len = char_infos[char_idx].byte_len;
    memcpy(cache64[i].utf8_bytes, char_infos[char_idx].start, char_infos[char_idx].byte_len);
    if (cache64[i].byte_len < 4) {
      cache64[i].utf8_bytes[cache64[i].byte_len] = '\0';
    }
  }
}

References utf8_char_t::byte_len, and utf8_char_t::utf8_bytes.

calculate_cache_eviction_score()

double calculate_cache_eviction_score	(	uint64_t	last_access_time,
		uint32_t	access_count,
		uint64_t	creation_time,
		uint64_t	current_time
	)

#include <common.h>

Calculate cache eviction score.

Parameters

last_access_time	Last access timestamp (nanoseconds)
access_count	Total access count
creation_time	Cache creation timestamp (nanoseconds)
current_time	Current timestamp (nanoseconds)

Returns

Eviction score (lower = more likely to evict)

Definition at line 87 of file video/simd/common.c.

                                                             {
  // Protect against unsigned underflow if times are inconsistent (clock adjustments, etc.)
  uint64_t age_ns = (current_time >= last_access_time) ? (current_time - last_access_time) : 0;
  uint64_t total_age_ns = (current_time >= creation_time) ? (current_time - creation_time) : 0;
 
  uint64_t age_seconds = age_ns / 1000000000ULL;
  uint64_t total_age_seconds = total_age_ns / 1000000000ULL;
 
  // Frequency factor: high-use palettes get protection (logarithmic scaling)
  double frequency_factor = 1.0 + log10(1.0 + access_count);
 
  // Aging factor: frequency bonus decays over time (5-minute half-life)
  double aging_factor = exp(-(double)age_seconds / CACHE_FREQUENCY_DECAY_TIME);
 
  // Recent access bonus: strong protection for recently used (1-minute protection)
  double recency_bonus = exp(-(double)age_seconds / CACHE_RECENCY_SCALE);
 
  // Cache lifetime penalty: prevent immortal caches (1-hour max lifetime)
  double lifetime_penalty = total_age_seconds > CACHE_MAX_LIFETIME ? 0.5 : 1.0;
 
  // Final score: higher = keep longer
  return (frequency_factor * aging_factor + recency_bonus) * lifetime_penalty;
}

References CACHE_FREQUENCY_DECAY_TIME, CACHE_MAX_LIFETIME, and CACHE_RECENCY_SCALE.

Referenced by __attribute__().

convert_pixels_scalar()

void convert_pixels_scalar	(	const rgb_pixel_t *	pixels,
		char *	ascii_chars,
		int	count,
		const char	luminance_palette[256]
	)

#include <ascii_simd.h>

Convert pixels to ASCII (scalar fallback)

Parameters

pixels	RGB pixel array
ascii_chars	Output buffer for ASCII characters
count	Number of pixels to convert
luminance_palette	Luminance-to-character mapping palette

Definition at line 167 of file ascii_simd.c.

                                                                                                                       {
  for (int i = 0; i < count; i++) {
    const rgb_pixel_t *p = &pixels[i];
 
    // Calculate luminance using integer arithmetic
    int luminance = (LUMA_RED * p->r + LUMA_GREEN * p->g + LUMA_BLUE * p->b) >> 8;
 
    // Clamp to [0, 255]
    if (luminance > 255)
      luminance = 255;
 
    ascii_chars[i] = luminance_palette[luminance];
  }
}

References LUMA_BLUE, LUMA_GREEN, and LUMA_RED.

convert_pixels_scalar_with_newlines()

char * convert_pixels_scalar_with_newlines	(	image_t *	image,
		const char	luminance_palette[256]
	)

#include <ascii_simd.h>

Convert image to ASCII with newlines (scalar fallback)

Parameters

image	Source image
luminance_palette	Luminance-to-character mapping palette

Returns

Allocated ASCII string (caller must free), or NULL on error

Definition at line 182 of file ascii_simd.c.

                                                                                             {
  const int h = image->h;
  const int w = image->w;
 
  // Get UTF-8 character cache for RLE emission
  // Note: We need to reverse-engineer the palette chars from luminance_palette
  // For now, use a simpler approach with direct luminance lookup
 
  // Use outbuf_t for efficient UTF-8 RLE emission (same as SIMD renderers)
  outbuf_t ob = {0};
  const size_t max_char_bytes = 4; // Max UTF-8 character size
  ob.cap = (size_t)h * ((size_t)w * max_char_bytes + 1);
  ob.buf = SAFE_MALLOC(ob.cap ? ob.cap : 1, char *);
  if (!ob.buf) {
    log_error("Failed to allocate output buffer for scalar rendering");
    return NULL;
  }
 
  // Process pixels with RLE optimization
  for (int y = 0; y < h; y++) {
    const rgb_pixel_t *row_pixels = (const rgb_pixel_t *)&image->pixels[y * w];
 
    for (int x = 0; x < w;) {
      const rgb_pixel_t *p = &row_pixels[x];
 
      // Calculate luminance using integer arithmetic
      int luminance = (LUMA_RED * p->r + LUMA_GREEN * p->g + LUMA_BLUE * p->b) >> 8;
      if (luminance > 255)
        luminance = 255;
 
      char current_char = luminance_palette[luminance];
 
      // Find run length for same character (RLE optimization)
      int j = x + 1;
      while (j < w) {
        const rgb_pixel_t *next_p = &row_pixels[j];
        int next_luminance = (LUMA_RED * next_p->r + LUMA_GREEN * next_p->g + LUMA_BLUE * next_p->b) >> 8;
        if (next_luminance > 255)
          next_luminance = 255;
        char next_char = luminance_palette[next_luminance];
        if (next_char != current_char)
          break;
        j++;
      }
      uint32_t run = (uint32_t)(j - x);
 
      // Emit character with RLE (same as SIMD)
      ob_putc(&ob, current_char);
      if (rep_is_profitable(run)) {
        emit_rep(&ob, run - 1);
      } else {
        for (uint32_t k = 1; k < run; k++) {
          ob_putc(&ob, current_char);
        }
      }
      x = j;
    }
 
    // Add newline (except for last row)
    if (y != h - 1) {
      ob_putc(&ob, '\n');
    }
  }
 
  ob_term(&ob);
  return ob.buf;
}

References outbuf_t::buf, outbuf_t::cap, emit_rep(), image_t::h, log_error, LUMA_BLUE, LUMA_GREEN, LUMA_RED, ob_putc(), ob_term(), image_t::pixels, rep_is_profitable(), SAFE_MALLOC, and image_t::w.

emit_rep()

void emit_rep	(	outbuf_t *	ob,
		uint32_t	extra
	)

#include <output_buffer.h>

Emit run-length encoded sequence.

Parameters

ob	Output buffer structure (must not be NULL)
extra	Additional characters to repeat (must be > 0)

Emits an ANSI run-length encoding sequence that repeats the last character in the buffer 'extra' times. Format: ESC[extram (where 'extra' is the repeat count and the last character is repeated).

Note

This function repeats the character at buffer[len-1].

Useful for compressing repeated characters (spaces, blocks, etc.).

Only profitable for runs exceeding threshold (see rep_is_profitable()).

Example

ob_putc(ob, ' ');  // Append space
if (rep_is_profitable(50)) {
    emit_rep(ob, 49);  // Repeat space 49 more times (total 50)
}

Definition at line 149 of file output_buffer.c.

                                            {
  if (!ob)
    return;
  // ESC [ extra b
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_u32(ob, extra);
  ob_putc(ob, 'b');
}

References ob_putc(), and ob_u32().

Referenced by ansi_compress_rle(), convert_pixels_scalar_with_newlines(), and image_print().

emit_reset()

void emit_reset

(

outbuf_t *

ob

)

#include <output_buffer.h>

Emit ANSI reset sequence.

Parameters

ob	Output buffer structure (must not be NULL)

Emits ANSI escape sequence to reset all terminal attributes to defaults. Format: ESC[0m or ESC[m. Resets colors, bold, underline, and other formatting attributes.

Note

This resets both foreground and background colors to default.

Sequence length: 3 bytes (ESC[0m).

Useful for resetting terminal state between frames.

Definition at line 131 of file output_buffer.c.

                              {
  if (!ob)
    return;
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_putc(ob, '0');
  ob_putc(ob, 'm');
}

References ob_putc().

emit_set_256_color_bg()

void emit_set_256_color_bg	(	outbuf_t *	ob,
		uint8_t	color_idx
	)

#include <output_buffer.h>

Emit 256-color background ANSI sequence.

Parameters

ob	Output buffer structure (must not be NULL)
color_idx	256-color palette index (0-255)

Emits ANSI escape sequence for 256-color background color. Format: ESC[48;5;idxm (where idx is palette index 0-255). Uses extended ANSI color palette for 256-color mode.

Note

Requires terminal 256-color support for proper display.

Sequence length: ~9 bytes (ESC[48;5;255m).

Palette indices 0-15 are standard ANSI colors.

Palette indices 16-255 are extended palette.

Definition at line 172 of file output_buffer.c.

                                                            {
  if (!ob)
    return;
  // ESC[48;5;Nm
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_write(ob, "48;5;", 5);
  ob_u8(ob, color_idx);
  ob_putc(ob, 'm');
}

References ob_putc(), ob_u8(), and ob_write().

emit_set_256_color_fg()

void emit_set_256_color_fg	(	outbuf_t *	ob,
		uint8_t	color_idx
	)

#include <output_buffer.h>

Emit 256-color foreground ANSI sequence.

Parameters

ob	Output buffer structure (must not be NULL)
color_idx	256-color palette index (0-255)

Emits ANSI escape sequence for 256-color foreground color. Format: ESC[38;5;idxm (where idx is palette index 0-255). Uses extended ANSI color palette for 256-color mode.

Note

Requires terminal 256-color support for proper display.

Sequence length: ~9 bytes (ESC[38;5;255m).

Palette indices 0-15 are standard ANSI colors.

Palette indices 16-255 are extended palette.

Definition at line 160 of file output_buffer.c.

                                                            {
  if (!ob)
    return;
  // ESC[38;5;Nm
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_write(ob, "38;5;", 5);
  ob_u8(ob, color_idx);
  ob_putc(ob, 'm');
}

References ob_putc(), ob_u8(), and ob_write().

emit_set_bg()

void emit_set_bg	(	outbuf_t *	ob,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <output_buffer.h>

Emit background color sequence (auto-select mode)

Parameters

ob	Output buffer structure (must not be NULL)
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Emits background color ANSI sequence using the optimal color mode based on terminal capabilities. Automatically selects:

• Truecolor mode (if supported): 24-bit RGB
• 256-color mode (if supported): Quantized to 256-color palette
• 16-color mode (fallback): Quantized to standard ANSI colors

Note

Color mode is selected based on terminal_capabilities_t configuration.

This function uses the best available color mode for the terminal.

Color quantization is applied when truecolor is not available.

Definition at line 198 of file output_buffer.c.

                                                                {
  if (!ob)
    return;
  // ESC[48;2;R;G;Bm
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_write(ob, "48;2;", 5);
  ob_u8(ob, r);
  ob_putc(ob, ';');
  ob_u8(ob, g);
  ob_putc(ob, ';');
  ob_u8(ob, b);
  ob_putc(ob, 'm');
}

References ob_putc(), ob_u8(), and ob_write().

emit_set_fg()

void emit_set_fg	(	outbuf_t *	ob,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <output_buffer.h>

Emit foreground color sequence (auto-select mode)

Parameters

ob	Output buffer structure (must not be NULL)
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Emits foreground color ANSI sequence using the optimal color mode based on terminal capabilities. Automatically selects:

• Truecolor mode (if supported): 24-bit RGB
• 256-color mode (if supported): Quantized to 256-color palette
• 16-color mode (fallback): Quantized to standard ANSI colors

Note

Color mode is selected based on terminal_capabilities_t configuration.

This function uses the best available color mode for the terminal.

Color quantization is applied when truecolor is not available.

Definition at line 183 of file output_buffer.c.

                                                                {
  if (!ob)
    return;
  // ESC[38;2;R;G;Bm
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_write(ob, "38;2;", 5);
  ob_u8(ob, r);
  ob_putc(ob, ';');
  ob_u8(ob, g);
  ob_putc(ob, ';');
  ob_u8(ob, b);
  ob_putc(ob, 'm');
}

References ob_putc(), ob_u8(), and ob_write().

emit_set_truecolor_bg()

void emit_set_truecolor_bg	(	outbuf_t *	ob,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <output_buffer.h>

Emit truecolor background ANSI sequence.

Parameters

ob	Output buffer structure (must not be NULL)
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Emits ANSI escape sequence for 24-bit truecolor background color. Format: ESC[48;2;r;g;bm (where r, g, b are RGB values). Uses 24-bit RGB color values for optimal color accuracy.

Note

Requires terminal truecolor support for proper display.

Sequence length: ~15 bytes (ESC[48;2;255;255;255m).

Definition at line 116 of file output_buffer.c.

                                                                          {
  if (!ob)
    return;
  // ESC[48;2;R;G;Bm
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_write(ob, "48;2;", 5);
  ob_u8(ob, r);
  ob_putc(ob, ';');
  ob_u8(ob, g);
  ob_putc(ob, ';');
  ob_u8(ob, b);
  ob_putc(ob, 'm');
}

References ob_putc(), ob_u8(), and ob_write().

emit_set_truecolor_fg()

void emit_set_truecolor_fg	(	outbuf_t *	ob,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <output_buffer.h>

Emit truecolor foreground ANSI sequence.

Parameters

ob	Output buffer structure (must not be NULL)
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Emits ANSI escape sequence for 24-bit truecolor foreground color. Format: ESC[38;2;r;g;bm (where r, g, b are RGB values). Uses 24-bit RGB color values for optimal color accuracy.

Note

Requires terminal truecolor support for proper display.

Sequence length: ~15 bytes (ESC[38;2;255;255;255m).

Definition at line 100 of file output_buffer.c.

                                                                          {
  if (!ob)
    return;
  // ESC[38;2;R;G;Bm
  ob_putc(ob, 0x1b);
  ob_putc(ob, '[');
  ob_write(ob, "38;2;", 5);
  ob_u8(ob, r);
  ob_putc(ob, ';');
  ob_u8(ob, g);
  ob_putc(ob, ';');
  ob_u8(ob, b);
  ob_putc(ob, 'm');
}

References ob_putc(), ob_u8(), and ob_write().

get_16color_rgb()

void get_16color_rgb	(	uint8_t	color_index,
		uint8_t *	r,
		uint8_t *	g,
		uint8_t *	b
	)

#include <ansi_fast.h>

Get the actual RGB values for a 16-color ANSI index.

Parameters

color_index	16-color ANSI index (0-15)
r	Output red component (0-255)
g	Output green component (0-255)
b	Output blue component (0-255)

Definition at line 320 of file ansi_fast.c.

                                                                              {
  // Same color table as rgb_to_16color()
  static const uint8_t ansi_colors[16][3] = {
      {0, 0, 0},       // 0: Black
      {128, 0, 0},     // 1: Dark Red
      {0, 128, 0},     // 2: Dark Green
      {128, 128, 0},   // 3: Dark Yellow (Brown)
      {0, 0, 128},     // 4: Dark Blue
      {128, 0, 128},   // 5: Dark Magenta
      {0, 128, 128},   // 6: Dark Cyan
      {192, 192, 192}, // 7: Light Gray
      {128, 128, 128}, // 8: Dark Gray
      {255, 0, 0},     // 9: Bright Red
      {0, 255, 0},     // 10: Bright Green
      {255, 255, 0},   // 11: Bright Yellow
      {0, 0, 255},     // 12: Bright Blue
      {255, 0, 255},   // 13: Bright Magenta
      {0, 255, 255},   // 14: Bright Cyan
      {255, 255, 255}  // 15: White
  };
 
  if (color_index >= 16) {
    color_index = 7; // Default to light gray
  }
 
  *r = ansi_colors[color_index][0];
  *g = ansi_colors[color_index][1];
  *b = ansi_colors[color_index][2];
}

Referenced by image_print_16color_dithered_with_background(), and rgb_to_16color_dithered().

get_256_color_fast_path()

bool get_256_color_fast_path

(

void

)

#include <ascii_simd.h>

Get 256-color fast path setting.

Returns

true if 256-color mode is enabled, false for truecolor

get_current_time_ns()

uint64_t get_current_time_ns

(

void

)

#include <common.h>

Get current time in nanoseconds.

Returns

Current timestamp in nanoseconds since epoch

Definition at line 81 of file video/simd/common.c.

                                   {
  struct timespec now;
  (void)clock_gettime(CLOCK_MONOTONIC, &now);
  return now.tv_sec * 1000000000ULL + now.tv_nsec;
}

Referenced by __attribute__().

get_lum_palette()

char * get_lum_palette

(

void

)

#include <ascii.h>

Get luminance palette for character mapping.

Returns

Pointer to luminance palette array (256 elements, do not free)

Returns the default luminance-to-character mapping palette. The palette contains 256 characters ordered by luminance (dark to light) for mapping pixel brightness values (0-255) to ASCII characters.

Note

Returns pointer to static array (do not free).

Palette has 256 elements (one for each luminance level).

Palette is used for monochrome ASCII conversion.

get_sgr256_fg_bg_string()

char * get_sgr256_fg_bg_string	(	uint8_t	fg,
		uint8_t	bg,
		uint8_t *	len_out
	)

#include <ascii_simd.h>

Get 256-color foreground/background ANSI sequence string.

Parameters

fg	Foreground palette index (0-255)
bg	Background palette index (0-255)
len_out	Output parameter for sequence length

Returns

Pointer to ANSI sequence string (cached)

Definition at line 102 of file ascii_simd_color.c.

                                                                        {
  static __thread char buf[32]; // Thread-local buffer
  return build_sgr256_fgbg(buf, fg, bg, len_out);
}

get_sgr256_fg_string()

char * get_sgr256_fg_string	(	uint8_t	fg,
		uint8_t *	len_out
	)

#include <ascii_simd.h>

Get 256-color foreground ANSI sequence string.

Parameters

fg	256-color palette index (0-255)
len_out	Output parameter for sequence length

Returns

Pointer to ANSI sequence string (cached)

Definition at line 97 of file ascii_simd_color.c.

                                                         {
  static __thread char buf[16]; // Thread-local buffer
  return build_sgr256_fg(buf, fg, len_out);
}

get_utf8_palette_cache()

utf8_palette_cache_t * get_utf8_palette_cache

(

const char *

ascii_chars

)

#include <common.h>

Get or create UTF-8 palette cache.

Parameters

ascii_chars

Character palette string

Returns

Cache pointer (may be shared, do not free)

Thread-safe cache lookup with automatic creation and eviction.

Referenced by image_print(), image_print_16color(), image_print_16color_dithered(), image_print_16color_dithered_with_background(), and image_print_color().

has_avx2_support()

bool has_avx2_support

(

void

)

#include <common.h>

Check if AVX2 is supported.

Returns

true if AVX2 is available, false otherwise

has_neon_support()

bool has_neon_support

(

void

)

#include <common.h>

Check if NEON is supported.

Returns

true if NEON is available, false otherwise

has_sse2_support()

bool has_sse2_support

(

void

)

#include <common.h>

Check if SSE2 is supported.

Returns

true if SSE2 is available, false otherwise

has_ssse3_support()

bool has_ssse3_support

(

void

)

#include <common.h>

Check if SSSE3 is supported.

Returns

true if SSSE3 is available, false otherwise

has_sve_support()

bool has_sve_support

(

void

)

#include <common.h>

Check if SVE is supported.

Returns

true if SVE is available, false otherwise

image_clear()

void image_clear

(

image_t *

p

)

#include <image.h>

Clear image (set all pixels to black)

Parameters

p	Image to clear (must not be NULL)

Sets all pixels in the image to black (RGB = 0, 0, 0). Useful for resetting image state before filling with new data.

Note

Image dimensions are not modified (only pixel data is cleared).

This is equivalent to memset() of pixels array to zero.

Definition at line 203 of file video/image.c.

                             {
  if (!p || !p->pixels) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_clear: p or p->pixels is NULL");
    return;
  }
  // CRITICAL: Check for integer overflow before multiplication
  unsigned long w_ul = (unsigned long)p->w;
  unsigned long h_ul = (unsigned long)p->h;
  if (w_ul > 0 && h_ul > ULONG_MAX / w_ul) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_clear: dimensions overflow: %d x %d", p->w, p->h);
    return;
  }
  unsigned long pixel_count = w_ul * h_ul;
  if (pixel_count > ULONG_MAX / sizeof(rgb_pixel_t)) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_clear: buffer size overflow");
    return;
  }
  size_t clear_size = pixel_count * sizeof(rgb_pixel_t);
  SAFE_MEMSET(p->pixels, clear_size, 0, clear_size);
}

References ERROR_INVALID_PARAM, image_t::h, image_t::pixels, SAFE_MEMSET, SET_ERRNO, and image_t::w.

Referenced by ascii_convert(), and ascii_convert_with_capabilities().

image_destroy()

void image_destroy

(

image_t *

p

)

#include <image.h>

Destroy an image allocated with image_new()

Parameters

p	Image to destroy (can be NULL, no-op if NULL)

Frees an image structure and its associated pixel data array allocated by image_new(). Frees both the image structure and the pixels array.

Note

Safe to call with NULL pointer (no-op).

Must NOT be used for images allocated with image_new_from_pool().

Use image_destroy_to_pool() for pool-allocated images.

Definition at line 85 of file video/image.c.

                               {
  if (!p) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_destroy: p is NULL");
    return;
  }
 
  // Check allocation method and deallocate appropriately
  if (p->alloc_method == IMAGE_ALLOC_POOL) {
    // Pool-allocated images: free entire contiguous buffer (image + pixels)
    // Validate dimensions before calculating size (guard against corruption)
    if (p->w <= 0 || p->h <= 0) {
      SET_ERRNO(ERROR_INVALID_PARAM, "image_destroy: invalid dimensions %dx%d (pool-allocated)", p->w, p->h);
      return;
    }
 
    // Calculate original allocation size for proper buffer pool free
    size_t w = (size_t)p->w;
    size_t h = (size_t)p->h;
    size_t pixels_size;
    if (checked_size_mul3(w, h, sizeof(rgb_pixel_t), &pixels_size) != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_INVALID_STATE, "image_destroy: dimensions would overflow: %dx%d", p->w, p->h);
      return;
    }
    size_t total_size;
    if (checked_size_add(sizeof(image_t), pixels_size, &total_size) != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_INVALID_STATE, "image_destroy: total size would overflow: %dx%d", p->w, p->h);
      return;
    }
 
    // Free the entire contiguous buffer back to pool
    buffer_pool_free(NULL, p, total_size);
  } else {
    // SIMD-allocated images: free pixels and structure separately
    // SAFE_MALLOC_SIMD allocates with aligned allocation (posix_memalign on macOS, aligned_alloc on Linux)
    // These can be freed with standard free() / SAFE_FREE()
    SAFE_FREE(p->pixels);
    SAFE_FREE(p);
  }
}

References image_t::alloc_method, ASCIICHAT_OK, buffer_pool_free(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, image_t::h, IMAGE_ALLOC_POOL, image_t::pixels, SAFE_FREE, SET_ERRNO, and image_t::w.

Referenced by ascii_convert(), ascii_convert_with_capabilities(), benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), benchmark_simd_conversion_with_source(), and mirror_main().

image_destroy_to_pool()

void image_destroy_to_pool

(

image_t *

image

)

#include <image.h>

Destroy an image allocated from buffer pool.

Parameters

image

Image to destroy (can be NULL, no-op if NULL)

Returns an image structure and its pixel data to the buffer pool for reuse. This is faster than standard free() because buffers are reused instead of being deallocated.

Note

Safe to call with NULL pointer (no-op).

Must NOT be used for images allocated with image_new().

Use image_destroy() for standard-allocated images.

Definition at line 171 of file video/image.c.

                                           {
  if (!image) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_destroy_to_pool: image is NULL");
    return;
  }
 
  // Validate dimensions before calculating size (guard against corruption)
  if (image->w <= 0 || image->h <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_destroy_to_pool: invalid dimensions %dx%d", image->w, image->h);
    return;
  }
 
  // Calculate original allocation size for proper buffer pool free
  // Check for overflow (defensive - should match original allocation)
  size_t w = (size_t)image->w;
  size_t h = (size_t)image->h;
  size_t pixels_size;
  if (checked_size_mul3(w, h, sizeof(rgb_pixel_t), &pixels_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_STATE, "image_destroy_to_pool: dimensions would overflow: %dx%d", image->w, image->h);
    return;
  }
  size_t total_size;
  if (checked_size_add(sizeof(image_t), pixels_size, &total_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_STATE, "image_destroy_to_pool: total size would overflow: %dx%d", image->w, image->h);
    return;
  }
 
  // Free the entire contiguous buffer back to pool
  buffer_pool_free(NULL, image, total_size);
  // Note: Don't set image = NULL here since caller owns the pointer
}

References ASCIICHAT_OK, buffer_pool_free(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, image_t::h, SET_ERRNO, and image_t::w.

Referenced by create_mixed_ascii_frame_for_client().

image_new()

image_t * image_new	(	size_t	width,
		size_t	height
	)

#include <image.h>

Create a new image with standard allocation.

Parameters

width	Image width in pixels (must be > 0 and <= IMAGE_MAX_WIDTH)
height	Image height in pixels (must be > 0 and <= IMAGE_MAX_HEIGHT)

Returns

Allocated image structure, or NULL on error

Allocates a new image structure and pixel data array using standard malloc() allocation. Image is initialized with specified dimensions and all pixels set to black (0, 0, 0).

Note

Caller must free with image_destroy() when done.

Returns NULL on error (invalid dimensions, memory allocation failure).

Pixel data is allocated separately and freed automatically on destroy.

Example

image_t *img = image_new(1920, 1080);
if (img) {
    // Use image...
    image_destroy(img);
}

Definition at line 36 of file video/image.c.

                                                {
  image_t *p;
 
  p = SAFE_MALLOC(sizeof(image_t), image_t *);
 
  // Validate dimensions are non-zero and within bounds
  if (image_validate_dimensions(width, height) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Image dimensions invalid or too large: %zu x %zu", width, height);
    SAFE_FREE(p);
    return NULL;
  }
 
  // Calculate pixel count with overflow checking
  size_t total_pixels;
  if (checked_size_mul(width, height, &total_pixels) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Image dimensions would cause overflow: %zu x %zu", width, height);
    SAFE_FREE(p);
    return NULL;
  }
 
  // Calculate total pixel buffer size with overflow checking
  size_t pixels_size;
  if (checked_size_mul(total_pixels, sizeof(rgb_pixel_t), &pixels_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Image pixel buffer size would cause overflow");
    SAFE_FREE(p);
    return NULL;
  }
 
  if (pixels_size > IMAGE_MAX_PIXELS_SIZE) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Image size exceeds maximum allowed: %zu x %zu (%zu bytes)", width, height,
              pixels_size);
    SAFE_FREE(p);
    return NULL;
  }
 
  // Use SIMD-aligned allocation for optimal NEON/AVX performance with vld3q_u8
  p->pixels = SAFE_MALLOC_SIMD(pixels_size, rgb_pixel_t *);
  if (!p->pixels) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate image pixels: %zu bytes", pixels_size);
    SAFE_FREE(p);
    return NULL;
  }
 
  p->w = (int)width;
  p->h = (int)height;
  p->alloc_method = IMAGE_ALLOC_SIMD; // Track allocation method for correct deallocation
  return p;
}

References image_t::alloc_method, ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_MEMORY, image_t::h, IMAGE_ALLOC_SIMD, IMAGE_MAX_PIXELS_SIZE, image_validate_dimensions(), image_t::pixels, SAFE_FREE, SAFE_MALLOC, SAFE_MALLOC_SIMD, SET_ERRNO, and image_t::w.

Referenced by ascii_convert(), ascii_convert_with_capabilities(), benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), benchmark_simd_conversion_with_source(), and webcam_read().

image_new_from_pool()

image_t * image_new_from_pool	(	size_t	width,
		size_t	height
	)

#include <image.h>

Create a new image from buffer pool.

Parameters

width	Image width in pixels (must be > 0 and <= IMAGE_MAX_WIDTH)
height	Image height in pixels (must be > 0 and <= IMAGE_MAX_HEIGHT)

Returns

Allocated image structure from pool, or NULL on error

Allocates a new image structure and pixel data from the buffer pool for efficient memory management in video pipeline. Buffer pool reduces allocation overhead and improves performance for high-frequency operations (video frame capture/processing).

Note

Caller must free with image_destroy_to_pool() when done.

Returns NULL on error (invalid dimensions, pool exhaustion).

Buffer pool allocation is faster than standard malloc().

Example

image_t *img = image_new_from_pool(1920, 1080);
if (img) {
    // Process video frame...
    image_destroy_to_pool(img);
}

Definition at line 126 of file video/image.c.

                                                          {
  if (width == 0 || height == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_new_from_pool: invalid dimensions %zux%zu", width, height);
    return NULL;
  }
 
  if (width > IMAGE_MAX_WIDTH || height > IMAGE_MAX_HEIGHT) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_new_from_pool: dimensions %zux%zu exceed maximum %ux%u", width, height,
              IMAGE_MAX_WIDTH, IMAGE_MAX_HEIGHT);
    return NULL;
  }
 
  // Calculate total allocation size (structure + pixel data in single buffer)
  // Check for integer overflow before multiplication
  size_t pixels_size;
  if (checked_size_mul3(width, height, sizeof(rgb_pixel_t), &pixels_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_new_from_pool: dimensions would overflow: %zux%zu", width, height);
    return NULL;
  }
 
  size_t total_size;
  if (checked_size_add(sizeof(image_t), pixels_size, &total_size) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_new_from_pool: total size would overflow");
    return NULL;
  }
 
  // Allocate from buffer pool as single contiguous block
  void *buffer = buffer_pool_alloc(NULL, total_size);
  if (!buffer) {
    SET_ERRNO(ERROR_MEMORY, "image_new_from_pool: buffer pool allocation failed for %zu bytes (%zux%zu)", total_size,
              width, height);
    return NULL;
  }
 
  // Set up image structure at start of buffer
  image_t *image = (image_t *)buffer;
  image->w = (int)width;
  image->h = (int)height;
  // Pixel data immediately follows the image structure
  image->pixels = (rgb_pixel_t *)((uint8_t *)buffer + sizeof(image_t));
  image->alloc_method = IMAGE_ALLOC_POOL; // Track allocation method for correct deallocation
 
  return image;
}

References image_t::alloc_method, ASCIICHAT_OK, buffer_pool_alloc(), ERROR_INVALID_PARAM, ERROR_MEMORY, image_t::h, IMAGE_ALLOC_POOL, IMAGE_MAX_HEIGHT, IMAGE_MAX_WIDTH, image_t::pixels, SET_ERRNO, and image_t::w.

image_print()

char * image_print	(	const image_t *	p,
		const char *	palette
	)

#include <image.h>

Print image as ASCII art (monochrome)

Parameters

p	Image to print (must not be NULL)
palette	Character palette to use (or NULL for default ASCII palette)

Returns

Allocated ASCII string (caller must free), or NULL on error

Converts an image to ASCII art without color output. Uses character palette to map pixel luminance to ASCII characters. Returns a null-terminated string containing the ASCII art frame.

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Character palette is used to map luminance to characters.

ASCII output has width*height characters (one character per pixel).

Definition at line 349 of file video/image.c.

                                                         {
  if (!p || !palette) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_print: p=%p or palette=%p is NULL", p, palette);
    return NULL;
  }
  if (!p->pixels) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_print: p->pixels is NULL");
    return NULL;
  }
 
  const int h = p->h;
  const int w = p->w;
 
  if (h <= 0 || w <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_print: invalid dimensions h=%d, w=%d", h, w);
    return NULL;
  }
 
  // Get UTF-8 character cache for proper multi-byte character support
  utf8_palette_cache_t *utf8_cache = get_utf8_palette_cache(palette);
  if (!utf8_cache) {
    SET_ERRNO(ERROR_INVALID_STATE, "Failed to get UTF-8 palette cache for scalar rendering");
    return NULL;
  }
 
  // Character index ramp is now part of UTF-8 cache - no separate cache needed
 
  // Need space for h rows with UTF-8 characters, plus h-1 newlines, plus null terminator
  const size_t max_char_bytes = 4; // Max UTF-8 character size
 
  const rgb_pixel_t *pix = p->pixels;
 
  // Use outbuf_t for efficient UTF-8 RLE emission (same as SIMD renderers)
  outbuf_t ob = {0};
 
  // Calculate buffer size with overflow checking
  size_t w_times_bytes;
  if (checked_size_mul((size_t)w, max_char_bytes, &w_times_bytes) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Buffer size overflow: width too large for UTF-8 encoding");
    return NULL;
  }
 
  size_t w_times_bytes_plus_one;
  if (checked_size_add(w_times_bytes, 1, &w_times_bytes_plus_one) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Buffer size overflow: width * bytes + 1 overflow");
    return NULL;
  }
 
  if (checked_size_mul((size_t)h, w_times_bytes_plus_one, &ob.cap) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Buffer size overflow: height * (width * bytes + 1) overflow");
    return NULL;
  }
 
  ob.buf = SAFE_MALLOC(ob.cap ? ob.cap : 1, char *);
  if (!ob.buf) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate output buffer for scalar rendering");
    return NULL;
  }
 
  // Process pixels with UTF-8 RLE emission (same approach as SIMD)
  for (int y = 0; y < h; y++) {
    const int row_offset = y * w;
 
    for (int x = 0; x < w;) {
      const rgb_pixel_t pixel = pix[row_offset + x];
      // Use same luminance formula as SIMD: ITU-R BT.601 with rounding
      const int luminance = (77 * pixel.r + 150 * pixel.g + 29 * pixel.b + 128) >> 8;
 
      // Use same 6-bit precision as SIMD: map luminance (0-255) to bucket (0-63) then to character
      uint8_t safe_luminance = clamp_rgb(luminance);
      uint8_t luma_idx = (uint8_t)(safe_luminance >> 2);        // 0-63 index (same as SIMD)
      uint8_t char_idx = utf8_cache->char_index_ramp[luma_idx]; // Map to character index (same as SIMD)
 
      // Use same 64-entry cache as SIMD for consistency
      const utf8_char_t *char_info = &utf8_cache->cache64[luma_idx];
 
      // Find run length for same character (RLE optimization)
      int j = x + 1;
      while (j < w) {
        const rgb_pixel_t next_pixel = pix[row_offset + j];
        const int next_luminance = (77 * next_pixel.r + 150 * next_pixel.g + 29 * next_pixel.b + 128) >> 8;
        uint8_t next_safe_luminance = clamp_rgb(next_luminance);
        uint8_t next_luma_idx = (uint8_t)(next_safe_luminance >> 2);        // 0-63 index (same as SIMD)
        uint8_t next_char_idx = utf8_cache->char_index_ramp[next_luma_idx]; // Map to character index (same as SIMD)
        if (next_char_idx != char_idx)
          break;
        j++;
      }
      uint32_t run = (uint32_t)(j - x);
 
      // Emit UTF-8 character with RLE (same as SIMD)
      ob_write(&ob, char_info->utf8_bytes, char_info->byte_len);
      if (rep_is_profitable(run)) {
        emit_rep(&ob, run - 1);
      } else {
        for (uint32_t k = 1; k < run; k++) {
          ob_write(&ob, char_info->utf8_bytes, char_info->byte_len);
        }
      }
      x = j;
    }
 
    // Add newline between rows (except last row)
    if (y != h - 1) {
      ob_putc(&ob, '\n');
    }
  }
 
  ob_term(&ob);
  return ob.buf;
}

References ASCIICHAT_OK, outbuf_t::buf, utf8_char_t::byte_len, utf8_palette_cache_s::cache64, outbuf_t::cap, utf8_palette_cache_s::char_index_ramp, emit_rep(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, get_utf8_palette_cache(), image_t::h, ob_putc(), ob_term(), ob_write(), image_t::pixels, rep_is_profitable(), SAFE_MALLOC, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

Referenced by ascii_convert(), benchmark_simd_conversion(), image_print_simd(), and image_print_with_capabilities().

image_print_16color()

char * image_print_16color	(	const image_t *	image,
		const char *	palette
	)

#include <image.h>

Print image using 16-color ANSI mode.

Parameters

image	Image to print (must not be NULL)
palette	Character palette to use (or NULL for default ASCII palette)

Returns

Allocated ASCII string with 16-color ANSI codes (caller must free), or NULL on error

Converts an image to ASCII art using 16-color ANSI mode. Uses standard ANSI color palette (0-15) for color output. Colors are quantized to 16-color palette.

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Requires terminal 16-color support for proper display.

Colors are quantized to 16-color palette automatically.

Definition at line 739 of file video/image.c.

                                                                     {
  if (!image || !image->pixels || !palette) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image=%p or image->pixels=%p or palette=%p is NULL", image, image->pixels, palette);
    return NULL;
  }
 
  int h = image->h;
  int w = image->w;
 
  if (h <= 0 || w <= 0) {
    SET_ERRNO(ERROR_INVALID_STATE, "image_print_16color: invalid dimensions h=%d, w=%d", h, w);
    return NULL;
  }
 
  // Initialize 16-color lookup table
  ansi_fast_init_16color();
 
  // Calculate buffer size (smaller than 256-color due to shorter ANSI sequences)
  // Space for ANSI codes + newlines
  // Calculate with overflow checking
  size_t h_times_w;
  if (checked_size_mul((size_t)h, (size_t)w, &h_times_w) != ASCIICHAT_OK) {
    return NULL;
  }
 
  size_t h_times_w_times_12;
  if (checked_size_mul(h_times_w, 12u, &h_times_w_times_12) != ASCIICHAT_OK) {
    return NULL;
  }
 
  size_t buffer_size;
  if (checked_size_add(h_times_w_times_12, (size_t)h, &buffer_size) != ASCIICHAT_OK) {
    return NULL;
  }
 
  char *buffer;
  buffer = SAFE_MALLOC(buffer_size, char *);
 
  char *ptr = buffer;
  const char *reset_code = "\033[0m";
 
  for (int y = 0; y < h; y++) {
    for (int x = 0; x < w; x++) {
      rgb_pixel_t pixel = image->pixels[y * w + x];
 
      // Convert RGB to 16-color index and generate ANSI sequence
      uint8_t color_index = rgb_to_16color(pixel.r, pixel.g, pixel.b);
      ptr = append_16color_fg(ptr, color_index);
 
      // Use same luminance formula as SIMD: ITU-R BT.601 with rounding
      int luminance = (77 * pixel.r + 150 * pixel.g + 29 * pixel.b + 128) >> 8;
 
      // Use UTF-8 cache which contains character index ramp
      utf8_palette_cache_t *utf8_cache = get_utf8_palette_cache(palette);
      if (!utf8_cache) {
        SET_ERRNO(ERROR_INVALID_STATE, "Failed to get UTF-8 cache");
        return NULL;
      }
 
      // Use same 6-bit precision as SIMD: map luminance (0-255) to bucket (0-63) then to character
      uint8_t safe_luminance = clamp_rgb(luminance);
      uint8_t luma_idx = (uint8_t)(safe_luminance >> 2);        // 0-63 index (same as SIMD)
      uint8_t char_idx = utf8_cache->char_index_ramp[luma_idx]; // Map to character index (same as SIMD)
 
      // Use direct palette character lookup (same as SIMD would do)
      char ascii_char = palette[char_idx];
      const utf8_char_t *char_info = &utf8_cache->cache[(unsigned char)ascii_char];
 
      if (char_info) {
        // Copy UTF-8 character bytes
        for (int byte_idx = 0; byte_idx < char_info->byte_len; byte_idx++) {
          *ptr++ = char_info->utf8_bytes[byte_idx];
        }
      } else {
        // Fallback to simple ASCII if UTF-8 cache fails
        size_t palette_len = strlen(palette);
        int palette_index = (luminance * ((int)palette_len - 1) + 127) / 255;
        *ptr++ = palette[palette_index];
      }
    }
 
    // Add reset and newline at end of each row
    SAFE_STRNCPY(ptr, reset_code, 5);
    ptr += strlen(reset_code);
    if (y < h - 1) {
      *ptr++ = '\n';
    }
  }
 
  *ptr = '\0';
  return buffer;
}

References ansi_fast_init_16color(), append_16color_fg(), ASCIICHAT_OK, utf8_char_t::byte_len, utf8_palette_cache_s::cache, utf8_palette_cache_s::char_index_ramp, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, get_utf8_palette_cache(), image_t::h, image_t::pixels, rgb_to_16color(), SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

image_print_16color_dithered()

char * image_print_16color_dithered	(	const image_t *	image,
		const char *	palette
	)

#include <image.h>

Print image using 16-color ANSI mode with dithering.

Parameters

image	Image to print (must not be NULL)
palette	Character palette to use (or NULL for default ASCII palette)

Returns

Allocated ASCII string with dithered 16-color ANSI codes (caller must free), or NULL on error

Converts an image to ASCII art using 16-color ANSI mode with Floyd-Steinberg dithering. Dithering improves color accuracy by distributing quantization errors across neighboring pixels.

DITHERING:

• Floyd-Steinberg error diffusion algorithm
• Distributes quantization errors to adjacent pixels
• Improves perceived color accuracy in 16-color mode
• Slight performance overhead compared to non-dithered mode

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Dithering improves color accuracy but may add noise.

Requires terminal 16-color support for proper display.

Definition at line 833 of file video/image.c.

                                                                              {
  if (!image || !image->pixels || !palette) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image=%p or image->pixels=%p or palette=%p is NULL", image, image->pixels, palette);
    return NULL;
  }
 
  int h = image->h;
  int w = image->w;
 
  if (h <= 0 || w <= 0) {
    SET_ERRNO(ERROR_INVALID_STATE, "image_print_16color_dithered: invalid dimensions h=%d, w=%d", h, w);
    return NULL;
  }
 
  // Initialize 16-color lookup table
  ansi_fast_init_16color();
 
  // Allocate error buffer for Floyd-Steinberg dithering
  size_t pixel_count = (size_t)h * (size_t)w;
  rgb_error_t *error_buffer;
  error_buffer = SAFE_CALLOC(pixel_count, sizeof(rgb_error_t), rgb_error_t *);
 
  // Calculate buffer size (same as non-dithered version)
  // Space for ANSI codes + newlines
  // Calculate with overflow checking
  size_t h_times_w2;
  if (checked_size_mul((size_t)h, (size_t)w, &h_times_w2) != ASCIICHAT_OK) {
    SAFE_FREE(error_buffer);
    return NULL;
  }
 
  size_t h_times_w2_times_12;
  if (checked_size_mul(h_times_w2, 12u, &h_times_w2_times_12) != ASCIICHAT_OK) {
    SAFE_FREE(error_buffer);
    return NULL;
  }
 
  size_t buffer_size;
  if (checked_size_add(h_times_w2_times_12, (size_t)h, &buffer_size) != ASCIICHAT_OK) {
    SAFE_FREE(error_buffer);
    return NULL;
  }
 
  char *buffer;
  buffer = SAFE_MALLOC(buffer_size, char *);
 
  char *ptr = buffer;
  const char *reset_code = "\033[0m";
 
  for (int y = 0; y < h; y++) {
    for (int x = 0; x < w; x++) {
      rgb_pixel_t pixel = image->pixels[y * w + x];
 
      // Convert RGB to 16-color index using dithering
      uint8_t color_index = rgb_to_16color_dithered(pixel.r, pixel.g, pixel.b, x, y, w, h, error_buffer);
      ptr = append_16color_fg(ptr, color_index);
 
      // Use same luminance formula as SIMD: ITU-R BT.601 with rounding
      int luminance = (77 * pixel.r + 150 * pixel.g + 29 * pixel.b + 128) >> 8;
 
      // Use UTF-8 cache which contains character index ramp
      utf8_palette_cache_t *utf8_cache = get_utf8_palette_cache(palette);
      if (!utf8_cache) {
        SET_ERRNO(ERROR_INVALID_STATE, "Failed to get UTF-8 cache");
        return NULL;
      }
 
      // Use same 6-bit precision as SIMD: map luminance (0-255) to bucket (0-63) then to character
      uint8_t safe_luminance = clamp_rgb(luminance);
      uint8_t luma_idx = (uint8_t)(safe_luminance >> 2);        // 0-63 index (same as SIMD)
      uint8_t char_idx = utf8_cache->char_index_ramp[luma_idx]; // Map to character index (same as SIMD)
 
      // Use direct palette character lookup (same as SIMD would do)
      char ascii_char = palette[char_idx];
      const utf8_char_t *char_info = &utf8_cache->cache[(unsigned char)ascii_char];
 
      if (char_info) {
        // Copy UTF-8 character bytes
        for (int byte_idx = 0; byte_idx < char_info->byte_len; byte_idx++) {
          *ptr++ = char_info->utf8_bytes[byte_idx];
        }
      } else {
        // Fallback to simple ASCII if UTF-8 cache fails
        size_t palette_len = strlen(palette);
        int palette_index = (luminance * ((int)palette_len - 1) + 127) / 255;
        *ptr++ = palette[palette_index];
      }
    }
 
    // Add reset and newline at end of each row
    SAFE_STRNCPY(ptr, reset_code, 5);
    ptr += strlen(reset_code);
    if (y < h - 1) {
      *ptr++ = '\n';
    }
  }
 
  *ptr = '\0';
  SAFE_FREE(error_buffer); // Clean up error buffer
  return buffer;
}

References ansi_fast_init_16color(), append_16color_fg(), ASCIICHAT_OK, utf8_char_t::byte_len, utf8_palette_cache_s::cache, utf8_palette_cache_s::char_index_ramp, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, get_utf8_palette_cache(), image_t::h, image_t::pixels, rgb_to_16color_dithered(), SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

image_print_16color_dithered_with_background()

char * image_print_16color_dithered_with_background	(	const image_t *	image,
		bool	use_background,
		const char *	palette
	)

#include <image.h>

Print image using 16-color ANSI mode with dithering and background colors.

Parameters

image	Image to print (must not be NULL)
use_background	Whether to use background colors (true) or foreground colors only (false)
palette	Character palette to use (or NULL for default ASCII palette)

Returns

Allocated ASCII string with dithered 16-color ANSI codes (caller must free), or NULL on error

Converts an image to ASCII art using 16-color ANSI mode with Floyd-Steinberg dithering and optional background color support. Background colors provide better color coverage for block-style rendering.

RENDERING MODES:

• Foreground colors: Character color is set (text color)
• Background colors: Character background is set (block color)
• Background mode provides better color coverage for block characters

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Background colors require terminal background color support.

Dithering improves color accuracy but may add noise.

Definition at line 936 of file video/image.c.

                                                                                                                   {
  if (!image || !image->pixels || !palette) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image=%p or image->pixels=%p or palette=%p is NULL", image, image->pixels, palette);
    return NULL;
  }
 
  int h = image->h;
  int w = image->w;
 
  if (h <= 0 || w <= 0) {
    SET_ERRNO(ERROR_INVALID_STATE, "image_print_16color_dithered_with_background: invalid dimensions h=%d, w=%d", h, w);
    return NULL;
  }
 
  // Initialize 16-color lookup table
  ansi_fast_init_16color();
 
  // Allocate error buffer for Floyd-Steinberg dithering
  size_t pixel_count = (size_t)h * (size_t)w;
  rgb_error_t *error_buffer;
  error_buffer = SAFE_CALLOC(pixel_count, sizeof(rgb_error_t), rgb_error_t *);
 
  // Calculate buffer size (larger for background mode due to more ANSI sequences)
  size_t buffer_size =
      (size_t)h * (size_t)w * (use_background ? 24 : 12) + (size_t)h; // Space for ANSI codes + newlines
  char *buffer;
  buffer = SAFE_MALLOC(buffer_size, char *);
 
  char *ptr = buffer;
  const char *reset_code = "\033[0m";
 
  for (int y = 0; y < h; y++) {
    for (int x = 0; x < w; x++) {
      rgb_pixel_t pixel = image->pixels[y * w + x];
 
      // Convert RGB to 16-color index using dithering
      uint8_t color_index = rgb_to_16color_dithered(pixel.r, pixel.g, pixel.b, x, y, w, h, error_buffer);
 
      if (use_background) {
        // Background mode: use contrasting foreground on background color
        uint8_t bg_r, bg_g, bg_b;
        get_16color_rgb(color_index, &bg_r, &bg_g, &bg_b);
 
        // Calculate luminance to choose contrasting foreground
        int bg_luminance = (bg_r * 77 + bg_g * 150 + bg_b * 29) / 256;
        uint8_t fg_color = (bg_luminance < 127) ? 15 : 0; // White on dark, black on bright
 
        ptr = append_16color_bg(ptr, color_index); // Set background to pixel color
        ptr = append_16color_fg(ptr, fg_color);    // Set contrasting foreground
      } else {
        // Foreground mode: set foreground to pixel color
        ptr = append_16color_fg(ptr, color_index);
      }
 
      // Use same luminance formula as SIMD: ITU-R BT.601 with rounding
      int luminance = (77 * pixel.r + 150 * pixel.g + 29 * pixel.b + 128) >> 8;
 
      // Use UTF-8 cache which contains character index ramp
      utf8_palette_cache_t *utf8_cache = get_utf8_palette_cache(palette);
      if (!utf8_cache) {
        SET_ERRNO(ERROR_INVALID_STATE, "Failed to get UTF-8 cache");
        return NULL;
      }
 
      // Use same 6-bit precision as SIMD: map luminance (0-255) to bucket (0-63) then to character
      uint8_t safe_luminance = clamp_rgb(luminance);
      uint8_t luma_idx = (uint8_t)(safe_luminance >> 2);        // 0-63 index (same as SIMD)
      uint8_t char_idx = utf8_cache->char_index_ramp[luma_idx]; // Map to character index (same as SIMD)
 
      // Use direct palette character lookup (same as SIMD would do)
      char ascii_char = palette[char_idx];
      const utf8_char_t *char_info = &utf8_cache->cache[(unsigned char)ascii_char];
 
      if (char_info) {
        // Copy UTF-8 character bytes
        for (int byte_idx = 0; byte_idx < char_info->byte_len; byte_idx++) {
          *ptr++ = char_info->utf8_bytes[byte_idx];
        }
      } else {
        // Fallback to simple ASCII if UTF-8 cache fails
        size_t palette_len = strlen(palette);
        int palette_index = (luminance * ((int)palette_len - 1) + 127) / 255;
        *ptr++ = palette[palette_index];
      }
    }
 
    // Add reset and newline at end of each row
    SAFE_STRNCPY(ptr, reset_code, 5);
    ptr += strlen(reset_code);
    if (y < h - 1) {
      *ptr++ = '\n';
    }
  }
 
  *ptr = '\0';
  SAFE_FREE(error_buffer); // Clean up error buffer
  return buffer;
}

References ansi_fast_init_16color(), append_16color_bg(), append_16color_fg(), utf8_char_t::byte_len, utf8_palette_cache_s::cache, utf8_palette_cache_s::char_index_ramp, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, get_16color_rgb(), get_utf8_palette_cache(), image_t::h, image_t::pixels, rgb_to_16color_dithered(), SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

Referenced by image_print_with_capabilities().

image_print_256color()

char * image_print_256color	(	const image_t *	image,
		const char *	palette
	)

#include <image.h>

Print image using 256-color ANSI mode.

Parameters

image	Image to print (must not be NULL)
palette	Character palette to use (or NULL for default ASCII palette)

Returns

Allocated ASCII string with 256-color ANSI codes (caller must free), or NULL on error

Converts an image to ASCII art using 256-color ANSI mode. Uses extended ANSI color palette (0-255) for color output. Colors are quantized to 256-color palette.

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Requires terminal 256-color support for proper display.

Colors are quantized to 256-color palette automatically.

Definition at line 722 of file video/image.c.

                                                                      {
  if (!image || !image->pixels || !palette) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image=%p or image->pixels=%p or palette=%p is NULL", image, image->pixels, palette);
    return NULL;
  }
 
  // Use the existing optimized SIMD colored printing (no background for 256-color mode)
#ifdef SIMD_SUPPORT
  char *result = image_print_color_simd((image_t *)image, false, true, palette);
#else
  char *result = image_print_color(image, palette);
#endif
 
  return result;
}

References ERROR_INVALID_PARAM, image_print_color(), image_print_color_simd(), image_t::pixels, and SET_ERRNO.

Referenced by image_print_with_capabilities().

image_print_color()

char * image_print_color	(	const image_t *	p,
		const char *	palette
	)

#include <image.h>

Print image as ASCII art with color.

Parameters

p	Image to print (must not be NULL)
palette	Character palette to use (or NULL for default ASCII palette)

Returns

Allocated ASCII string with ANSI color codes (caller must free), or NULL on error

Converts an image to ASCII art with color output. Uses character palette for character mapping and ANSI color codes for color output. Returns a null-terminated string containing the ASCII art frame with embedded ANSI escape sequences.

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

ANSI color codes are embedded in the output string.

Color output requires terminal color support for proper display.

Converts an image to colored ASCII art with ANSI escape codes.

This function generates a string representation of an image where each pixel is converted to an ASCII character with ANSI color codes. The character is chosen based on luminance, and colors are applied using 24-bit RGB ANSI escape sequences.

Buffer allocation is precisely calculated to avoid waste and prevent overflows:

• Each pixel: 1 ASCII char + foreground ANSI code (19 bytes max)
• Background mode: adds background ANSI code (19 bytes max per pixel)
• Each row: reset sequence (\033[0m = 4 bytes) + newline (except last row)
• At the end: null terminator (1 byte)

Color modes:

• Foreground only (default): ASCII characters with colored foreground
• Background mode (opt_background_color): colored background with contrasting foreground (black on bright backgrounds, white on dark backgrounds)

ANSI escape code format:

• Foreground: \033[38;2;R;G;Bm (11-19 bytes depending on RGB values)
• Background: \033[48;2;R;G;Bm (11-19 bytes depending on RGB values)
• Reset: \033[0m (4 bytes)

Parameters

p	Pointer to image_t structure containing pixel data

Returns

Dynamically allocated string containing colored ASCII art, or NULL on error. Caller is responsible for freeing the returned string.

Note

The function performs overflow checks to prevent integer overflow when calculating buffer sizes for very large images.

Uses global opt_background_color to determine color mode.

Exits with ERROR_BUFFER if buffer overflow is detected during string construction (should never happen with correct calculation).

Definition at line 513 of file video/image.c.

                                                               {
  if (!p || !palette) {
    SET_ERRNO(ERROR_INVALID_PARAM, "p=%p or palette=%p is NULL", p, palette);
    return NULL;
  }
  if (!p->pixels) {
    SET_ERRNO(ERROR_INVALID_PARAM, "p->pixels is NULL");
    return NULL;
  }
 
  // Get UTF-8 character cache for proper multi-byte character support
  utf8_palette_cache_t *utf8_cache = get_utf8_palette_cache(palette);
  if (!utf8_cache) {
    SET_ERRNO(ERROR_INVALID_STATE, "Failed to get UTF-8 palette cache for scalar color rendering");
    return NULL;
  }
 
  const int h = p->h;
  const int w = p->w;
 
  // Constants for ANSI escape codes (using exact sizes from ansi_fast.c)
  const size_t max_fg_ansi = 19; // \033[38;2;255;255;255m
  const size_t max_bg_ansi = 19; // \033[48;2;255;255;255m
  const size_t reset_len = 4;    // \033[0m
 
  const size_t h_sz = (size_t)h;
  const size_t w_sz = (size_t)w;
 
  // Ensure h * w won't overflow
  if (h_sz > 0 && w_sz > SIZE_MAX / h_sz) {
    SET_ERRNO(ERROR_INVALID_STATE, "Image dimensions too large: %d x %d", h, w);
    return NULL;
  }
 
  const size_t total_pixels = h_sz * w_sz;
  const size_t bytes_per_pixel = 1 + max_fg_ansi + max_bg_ansi; // Conservative estimate for max possible
 
  // Ensure total_pixels * bytes_per_pixel won't overflow
  if (total_pixels > SIZE_MAX / bytes_per_pixel) {
    SET_ERRNO(ERROR_INVALID_STATE, "Pixel data too large for buffer: %d x %d", h, w);
    return NULL;
  }
 
  const size_t pixel_bytes = total_pixels * bytes_per_pixel;
 
  // Per row: reset sequence + newline (except last row)
  const size_t total_resets = h_sz * reset_len;
  const size_t total_newlines = (h_sz > 0) ? (h_sz - 1) : 0;
 
  // Final buffer size: pixel bytes + per-row extras + null terminator
  const size_t extra_bytes = total_resets + total_newlines + 1;
 
  if (pixel_bytes > SIZE_MAX - extra_bytes) {
    SET_ERRNO(ERROR_INVALID_STATE, "Final buffer size would overflow: %d x %d", h, w);
    return NULL;
  }
 
  const size_t lines_size = pixel_bytes + extra_bytes;
  char *lines;
  lines = SAFE_MALLOC(lines_size, char *);
 
  const rgb_pixel_t *pix = p->pixels;
  // char *current_pos = lines;
  // const char *buffer_end = lines + lines_size - 1; // reserve space for '\0'
 
  // Initialize the optimized RLE context for color sequence caching
  // Note: This function should be called via image_print_with_capabilities() for proper per-client rendering
  ansi_rle_context_t rle_ctx;
  ansi_color_mode_t color_mode = ANSI_MODE_FOREGROUND; // Default to foreground-only for legacy usage
  ansi_rle_init(&rle_ctx, lines, lines_size, color_mode);
 
  // Process each pixel using the optimized RLE context
  for (int y = 0; y < h; y++) {
    const int row_offset = y * w;
 
    for (int x = 0; x < w; x++) {
      const rgb_pixel_t pixel = pix[row_offset + x];
      int r = pixel.r, g = pixel.g, b = pixel.b;
      // Standard ITU-R BT.601 luminance calculation
      const int luminance = (77 * r + 150 * g + 29 * b + 128) >> 8;
 
      // Use UTF-8 character cache for proper character selection
      uint8_t safe_luminance = clamp_rgb(luminance);
      const utf8_char_t *char_info = &utf8_cache->cache[safe_luminance];
 
      // For RLE, we need to pass the first byte of the UTF-8 character
      // Note: RLE system may need updates for full UTF-8 support
      const char ascii_char = char_info->utf8_bytes[0];
 
      ansi_rle_add_pixel(&rle_ctx, (uint8_t)r, (uint8_t)g, (uint8_t)b, ascii_char);
    }
 
    // Add newline between rows (except last row)
    if (y != h - 1 && rle_ctx.length < rle_ctx.capacity - 1) {
      rle_ctx.buffer[rle_ctx.length++] = '\n';
    }
  }
 
  ansi_rle_finish(&rle_ctx);
  return lines;
}

References ANSI_MODE_FOREGROUND, ansi_rle_add_pixel(), ansi_rle_finish(), ansi_rle_init(), ansi_rle_context_t::buffer, utf8_palette_cache_s::cache, ansi_rle_context_t::capacity, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, get_utf8_palette_cache(), image_t::h, ansi_rle_context_t::length, image_t::pixels, SAFE_MALLOC, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

Referenced by ascii_convert(), benchmark_simd_color_conversion(), benchmark_simd_conversion_with_source(), image_print_256color(), image_print_color_simd(), and image_print_with_capabilities().

image_print_color_simd()

char * image_print_color_simd	(	image_t *	image,
		bool	use_background_mode,
		bool	use_256color,
		const char *	ascii_chars
	)

#include <ascii_simd.h>

Print image as ASCII with color using SIMD.

Parameters

image	Source image
use_background_mode	Use background colors
use_256color	Use 256-color mode (vs truecolor)
ascii_chars	Character palette

Returns

Allocated ASCII string with ANSI codes (caller must free), or NULL on error

Definition at line 375 of file ascii_simd_color.c.

                                                                                                                   {
  (void)use_256color; // Suppress unused parameter warning when SIMD not available
 
#if SIMD_SUPPORT_AVX2
  (void)use_background_mode; // Suppress unused parameter warning when SIMD not available
  // FIXME: my AVX2 implementation is dim and has vertical stripe artifacts. Use scalar until we fix it.
  return image_print_color(image, ascii_chars);
  // return render_ascii_avx2_unified_optimized(image, use_background_mode, use_256color, ascii_chars);
#elif SIMD_SUPPORT_SSSE3
  return render_ascii_ssse3_unified_optimized(image, use_background_mode, use_256color, ascii_chars);
#elif SIMD_SUPPORT_SSE2
  return render_ascii_sse2_unified_optimized(image, use_background_mode, use_256color, ascii_chars);
#elif SIMD_SUPPORT_NEON
  return render_ascii_neon_unified_optimized(image, use_background_mode, use_256color, ascii_chars);
#else
  // Fallback implementation for non-NEON platforms
  // Use scalar image function for fallback path - no SIMD allocation needed
  (void)use_background_mode; // Suppress unused parameter warning
  return image_print_color(image, ascii_chars);
#endif
}

References image_print_color().

Referenced by ascii_convert(), image_print_256color(), and image_print_with_capabilities().

image_print_simd()

char * image_print_simd	(	image_t *	image,
		const char *	ascii_chars
	)

#include <ascii_simd.h>

Print image as ASCII using SIMD (monochrome)

Parameters

image	Source image
ascii_chars	Character palette

Returns

Allocated ASCII string (caller must free), or NULL on error

Definition at line 252 of file ascii_simd.c.

                                                                {
#if SIMD_SUPPORT_AVX2
  return render_ascii_image_monochrome_avx2(image, ascii_chars);
#elif SIMD_SUPPORT_SSSE3
  return render_ascii_image_monochrome_ssse3(image, ascii_chars);
#elif SIMD_SUPPORT_SSE2
  return render_ascii_image_monochrome_sse2(image, ascii_chars);
#elif SIMD_SUPPORT_NEON
  return render_ascii_image_monochrome_neon(image, ascii_chars);
#else
  // Fallback to scalar implementation - use image_print which properly handles
  // the palette string (convert_pixels_scalar_with_newlines expects a 256-element
  // luminance lookup table, not the raw palette string)
  return image_print(image, ascii_chars);
#endif
}

References image_print().

Referenced by ascii_convert(), and image_print_with_capabilities().

image_print_with_capabilities()

char * image_print_with_capabilities	(	const image_t *	image,
		const terminal_capabilities_t *	caps,
		const char *	palette,
		const char	luminance_palette[256]
	)

#include <image.h>

Print image with terminal capability awareness.

Parameters

image	Image to print (must not be NULL)
caps	Terminal capabilities structure (must not be NULL)
palette	Character palette to use (or NULL for default ASCII palette)
luminance_palette	Luminance-to-character mapping palette (must not be NULL, 256 elements)

Returns

Allocated ASCII string (caller must free), or NULL on error

Converts an image to ASCII art with automatic color mode selection based on terminal capabilities. Automatically chooses the best color mode (16-color, 256-color, or truecolor) for the terminal.

COLOR MODE SELECTION:

• Truecolor: If terminal supports 24-bit RGB colors
• 256-color: If terminal supports extended ANSI palette
• 16-color: Fallback to standard ANSI colors
• Monochrome: If terminal has no color support

Note

Returns NULL on error (invalid image, memory allocation failure).

ASCII string must be freed by caller using free().

Color mode is selected automatically based on terminal capabilities.

This is the recommended function for capability-aware ASCII conversion.

image_resize()

void image_resize	(	const image_t *	source,
		image_t *	dest
	)

#include <image.h>

Resize image using nearest-neighbor interpolation.

Parameters

source	Source image (must not be NULL)
dest	Destination image (must be allocated and have valid dimensions)

Resizes an image using nearest-neighbor interpolation. Fast but may produce aliasing artifacts. Source pixels are sampled to nearest destination pixel positions.

NEAREST-NEIGHBOR INTERPOLATION:

• Fast algorithm (no interpolation calculations)
• May produce aliasing artifacts
• Pixel values are copied directly (no averaging)
• Suitable for integer scaling (2x, 3x, etc.)

Note

Destination image dimensions must be set before calling.

Source and destination images must be valid (not NULL).

Fast algorithm suitable for real-time resizing.

Definition at line 232 of file video/image.c.

                                                {
  if (!s || !d) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_resize: s or d is NULL");
    return;
  }
 
  image_resize_interpolation(s, d);
}

References ERROR_INVALID_PARAM, image_resize_interpolation(), and SET_ERRNO.

Referenced by ascii_convert(), and ascii_convert_with_capabilities().

image_resize_interpolation()

void image_resize_interpolation	(	const image_t *	source,
		image_t *	dest
	)

#include <image.h>

Resize image using bilinear interpolation.

Parameters

source	Source image (must not be NULL)
dest	Destination image (must be allocated and have valid dimensions)

Resizes an image using bilinear interpolation. Produces smoother results than nearest-neighbor but slower. Pixel values are interpolated from four nearest source pixels.

BILINEAR INTERPOLATION:

• Slower algorithm (interpolation calculations required)
• Produces smoother results (reduced aliasing)
• Pixel values are interpolated from 4 nearest neighbors
• Suitable for fractional scaling (1.5x, 2.3x, etc.)

Note

Destination image dimensions must be set before calling.

Source and destination images must be valid (not NULL).

Slower algorithm but produces better quality.

Definition at line 243 of file video/image.c.

                                                                      {
  if (!source || !dest || !source->pixels || !dest->pixels) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to image_resize_interpolation");
    return;
  }
 
  const int src_w = source->w;
  const int src_h = source->h;
  const int dst_w = dest->w;
  const int dst_h = dest->h;
 
  // Handle edge cases
  if (src_w <= 0 || src_h <= 0 || dst_w <= 0 || dst_h <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid image dimensions for resize");
    return;
  }
 
  // Use fixed-point arithmetic for better performance
  const uint32_t x_ratio = (((uint32_t)(unsigned int)src_w << 16) / (uint32_t)(unsigned int)dst_w) + 1;
  const uint32_t y_ratio = (((uint32_t)(unsigned int)src_h << 16) / (uint32_t)(unsigned int)dst_h) + 1;
 
  const rgb_pixel_t *src_pixels = source->pixels;
  rgb_pixel_t *dst_pixels = dest->pixels;
 
  for (int y = 0; y < dst_h; y++) {
    const uint32_t src_y = ((uint32_t)(unsigned int)y * y_ratio) >> 16;
    const uint32_t safe_src_y = (src_y >= (uint32_t)(unsigned int)src_h) ? (uint32_t)(src_h - 1) : src_y;
    const rgb_pixel_t *src_row = src_pixels + (safe_src_y * (size_t)src_w);
 
    rgb_pixel_t *dst_row = dst_pixels + ((size_t)y * (size_t)dst_w);
 
    for (int x = 0; x < dst_w; x++) {
      const uint32_t src_x = ((uint32_t)(unsigned int)x * x_ratio) >> 16;
      const uint32_t safe_src_x = (src_x >= (uint32_t)(unsigned int)src_w) ? (uint32_t)(src_w - 1) : src_x;
      dst_row[x] = src_row[safe_src_x];
    }
  }
}

References ERROR_INVALID_PARAM, image_t::h, image_t::pixels, SET_ERRNO, and image_t::w.

Referenced by image_resize().

init_dec3()

void init_dec3

(

void

)

#include <ascii_simd.h>

Initialize decimal lookup table.

Must be called before using any SIMD conversion functions.

Definition at line 58 of file ascii_simd.c.

                     {
  if (g_dec3_cache.dec3_initialized)
    return;
  for (int v = 0; v < 256; ++v) {
    int d2 = v / 100;     // 0..2
    int r = v - d2 * 100; // 0..99
    int d1 = r / 10;      // 0..9
    int d0 = r - d1 * 10; // 0..9
 
    if (d2) {
      g_dec3_cache.dec3_table[v].len = 3;
      g_dec3_cache.dec3_table[v].s[0] = '0' + d2;
      g_dec3_cache.dec3_table[v].s[1] = '0' + d1;
      g_dec3_cache.dec3_table[v].s[2] = '0' + d0;
    } else if (d1) {
      g_dec3_cache.dec3_table[v].len = 2;
      g_dec3_cache.dec3_table[v].s[0] = '0' + d1;
      g_dec3_cache.dec3_table[v].s[1] = '0' + d0;
    } else {
      g_dec3_cache.dec3_table[v].len = 1;
      g_dec3_cache.dec3_table[v].s[0] = '0' + d0;
    }
  }
  g_dec3_cache.dec3_initialized = true;
}

References global_dec3_cache_t::dec3_initialized, global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, and dec3_t::s.

Referenced by ascii_simd_init().

init_default_luminance_palette()

void init_default_luminance_palette

(

void

)

#include <ascii_simd.h>

Initialize default luminance palette.

Definition at line 37 of file ascii_simd.c.

                                          {
  if (g_default_palette_initialized)
    return;
 
  // Build default luminance mapping using standard palette
  const size_t len = DEFAULT_ASCII_PALETTE_LEN;
  for (int i = 0; i < 256; i++) {
    size_t palette_index = (i * (len - 1) + 127) / 255;
    if (palette_index >= len) {
      palette_index = len - 1;
    }
    g_default_luminance_palette[i] = DEFAULT_ASCII_PALETTE[palette_index];
  }
  g_default_palette_initialized = true;
}

References DEFAULT_ASCII_PALETTE, DEFAULT_ASCII_PALETTE_LEN, and g_default_luminance_palette.

Referenced by ascii_simd_init().

ob_putc()

void ob_putc	(	outbuf_t *	ob,
		char	c
	)

#include <output_buffer.h>

Append a character to buffer.

Parameters

ob	Output buffer structure (must not be NULL)
c	Character to append

Appends a single character to the output buffer. Automatically expands the buffer if necessary. Buffer remains null-terminated after append.

Note

Buffer is automatically expanded if needed.

Length is incremented by 1 after append.

Null terminator is updated automatically.

Definition at line 42 of file output_buffer.c.

                                   {
  if (!ob)
    return;
  ob_reserve(ob, 1);
  ob->buf[ob->len++] = c;
}

References outbuf_t::buf, outbuf_t::len, and ob_reserve().

Referenced by ansi_compress_rle(), ansi_strip_escapes(), convert_pixels_scalar_with_newlines(), emit_rep(), emit_reset(), emit_set_256_color_bg(), emit_set_256_color_fg(), emit_set_bg(), emit_set_fg(), emit_set_truecolor_bg(), emit_set_truecolor_fg(), image_print(), ob_term(), and ob_u8().

ob_reserve()

void ob_reserve	(	outbuf_t *	ob,
		size_t	need
	)

#include <output_buffer.h>

Reserve buffer space for upcoming writes.

Parameters

ob	Output buffer structure (must not be NULL)
need	Minimum bytes needed (must be > 0)

Ensures the buffer has at least 'need' bytes of available space. Automatically expands the buffer if necessary. Buffer grows exponentially (doubles in size) to minimize reallocation overhead.

Note

Buffer is automatically allocated on first reservation.

Buffer doubles in size when capacity is exceeded.

This function does not modify buffer length (only capacity).

Definition at line 21 of file output_buffer.c.

                                           {
  if (!ob)
    return;
  if (ob->cap == 0) {
    // Always allocate at least default capacity on first call
    size_t ncap = 4096;
    while (ncap < ob->len + need)
      ncap = (ncap * 3) / 2;
    // SAFE_REALLOC handles NULL ptr as malloc - this is safe
    ob->buf = SAFE_REALLOC(ob->buf, ncap, char *);
    ob->cap = ncap;
  } else if (ob->len + need > ob->cap) {
    // Expand existing buffer
    size_t ncap = ob->cap;
    while (ncap < ob->len + need)
      ncap = (ncap * 3) / 2;
    ob->buf = SAFE_REALLOC(ob->buf, ncap, char *);
    ob->cap = ncap;
  }
}

References outbuf_t::buf, outbuf_t::cap, outbuf_t::len, and SAFE_REALLOC.

Referenced by ansi_compress_rle(), ansi_expand_rle(), ansi_strip_escapes(), ob_putc(), ob_u32(), and ob_write().

ob_term()

void ob_term

(

outbuf_t *

ob

)

#include <output_buffer.h>

Append null terminator to buffer.

Parameters

ob	Output buffer structure (must not be NULL)

Ensures the buffer is null-terminated by appending a null character. Does not increment length counter (null terminator is not counted). Useful for ensuring buffer is a valid C string.

Note

This function ensures buffer[len] == '\0'.

Length counter is not modified (null terminator excluded from length).

Definition at line 57 of file output_buffer.c.

                           {
  if (!ob)
    return;
  ob_putc(ob, '\0');
}

References ob_putc().

Referenced by ansi_compress_rle(), ansi_expand_rle(), ansi_strip_escapes(), convert_pixels_scalar_with_newlines(), and image_print().

ob_u32()

void ob_u32	(	outbuf_t *	ob,
		uint32_t	v
	)

#include <output_buffer.h>

Append unsigned 32-bit integer as decimal string.

Parameters

ob	Output buffer structure (must not be NULL)
v	Value to append (0 to 4294967295)

Converts an unsigned 32-bit integer to decimal string representation and appends it to the buffer. Useful for formatting numeric values (dimensions, counts, timestamps, etc.).

Note

Buffer is automatically expanded if needed.

String representation is appended (1-10 characters for 0-4294967295).

Definition at line 85 of file output_buffer.c.

                                      {
  if (!ob)
    return;
  char tmp[10];
  int i = 0;
  do {
    tmp[i++] = '0' + (v % 10u);
    v /= 10u;
  } while (v);
  ob_reserve(ob, (size_t)i);
  while (i--)
    ob->buf[ob->len++] = tmp[i];
}

References outbuf_t::buf, outbuf_t::len, and ob_reserve().

Referenced by emit_rep().

ob_u8()

void ob_u8	(	outbuf_t *	ob,
		uint8_t	v
	)

#include <output_buffer.h>

Append unsigned 8-bit integer as decimal string.

Parameters

ob	Output buffer structure (must not be NULL)
v	Value to append (0-255)

Converts an unsigned 8-bit integer to decimal string representation and appends it to the buffer. Useful for formatting small numeric values (color indices, counts, etc.).

Note

Buffer is automatically expanded if needed.

String representation is appended (1-3 characters for 0-255).

Definition at line 64 of file output_buffer.c.

                                    {
  if (!ob)
    return;
  if (v >= 100) {
    uint8_t d0 = v / 100;
    uint8_t r = v % 100;
    uint8_t d1 = r / 10;
    uint8_t d2 = r % 10;
    ob_putc(ob, '0' + d0);
    ob_putc(ob, '0' + d1);
    ob_putc(ob, '0' + d2);
  } else if (v >= 10) {
    uint8_t d1 = v / 10;
    uint8_t d2 = v % 10;
    ob_putc(ob, '0' + d1);
    ob_putc(ob, '0' + d2);
  } else {
    ob_putc(ob, '0' + v);
  }
}

References ob_putc().

Referenced by emit_set_256_color_bg(), emit_set_256_color_fg(), emit_set_bg(), emit_set_fg(), emit_set_truecolor_bg(), and emit_set_truecolor_fg().

ob_write()

void ob_write	(	outbuf_t *	ob,
		const char *	s,
		size_t	n
	)

#include <output_buffer.h>

Append a string to buffer.

Parameters

ob	Output buffer structure (must not be NULL)
s	String to append (must not be NULL)
n	Number of bytes to append (must be > 0)

Appends n bytes from string s to the output buffer. Automatically expands the buffer if necessary. Buffer remains null-terminated after append.

Note

Buffer is automatically expanded if needed.

Length is incremented by n after append.

Null terminator is updated automatically.

This function copies n bytes (may include embedded nulls).

Definition at line 49 of file output_buffer.c.

                                                     {
  if (!ob || n == 0)
    return;
  ob_reserve(ob, n);
  SAFE_MEMCPY(ob->buf + ob->len, ob->cap - ob->len, s, n);
  ob->len += n;
}

References outbuf_t::buf, outbuf_t::cap, outbuf_t::len, ob_reserve(), and SAFE_MEMCPY.

Referenced by ansi_compress_rle(), ansi_expand_rle(), emit_set_256_color_bg(), emit_set_256_color_fg(), emit_set_bg(), emit_set_fg(), emit_set_truecolor_bg(), emit_set_truecolor_fg(), and image_print().

precalc_rgb_palettes()

void precalc_rgb_palettes	(	const float	red,
		const float	green,
		const float	blue
	)

#include <image.h>

Precalculate RGB palettes with color adjustment.

Parameters

red	Red adjustment factor (1.0 = no adjustment, >1.0 = increase, <1.0 = decrease)
green	Green adjustment factor (1.0 = no adjustment, >1.0 = increase, <1.0 = decrease)
blue	Blue adjustment factor (1.0 = no adjustment, >1.0 = increase, <1.0 = decrease)

Precalculates RGB color palettes with color adjustment factors. Color adjustment allows brightness, contrast, and color balance adjustments to be applied efficiently during ASCII conversion.

COLOR ADJUSTMENT:

• Adjustment factors are multiplied with color components
• Factors > 1.0 increase color intensity
• Factors < 1.0 decrease color intensity
• Precalculated palettes improve conversion performance

Note

Precalculated palettes are cached for efficient conversion.

Color adjustment is applied during ASCII conversion.

Useful for brightness/contrast control.

Definition at line 284 of file video/image.c.

                                                                                {
  // Validate input parameters to prevent overflow
  // Luminance weights should typically be in range 0.0-1.0
  // But allow slightly larger values for brightness adjustment
  const float max_weight = 255.0f;  // Maximum value that won't overflow when multiplied by 255
  const float min_weight = -255.0f; // Allow negative for color correction
 
  // Note: isfinite() checks are skipped in Release builds due to -ffinite-math-only flag
  // which disables NaN/infinity support for performance. Range checks below are sufficient.
#if !defined(NDEBUG) && !defined(__FAST_MATH__)
  if (!isfinite(red) || !isfinite(green) || !isfinite(blue)) {
    log_error("Invalid weight values (non-finite): red=%f, green=%f, blue=%f", red, green, blue);
    SET_ERRNO(ERROR_INVALID_PARAM, "precalc_rgb_palettes: non-finite weight values");
    return;
  }
#endif
 
  if (red < min_weight || red > max_weight || green < min_weight || green > max_weight || blue < min_weight ||
      blue > max_weight) {
    log_warn(
        "precalc_rgb_palettes: Weight values out of expected range: red=%f, green=%f, blue=%f (clamping to safe range)",
        red, green, blue);
  }
 
  // Clamp weights to safe range to prevent overflow
  const float safe_red = (red < min_weight) ? min_weight : ((red > max_weight) ? max_weight : red);
  const float safe_green = (green < min_weight) ? min_weight : ((green > max_weight) ? max_weight : green);
  const float safe_blue = (blue < min_weight) ? min_weight : ((blue > max_weight) ? max_weight : blue);
 
  const unsigned short max_ushort = 65535;
  const unsigned short min_ushort = 0;
 
  for (int n = 0; n < ASCII_LUMINANCE_LEVELS; ++n) {
    // Compute with float, then clamp to unsigned short range
    float red_val = (float)n * safe_red;
    float green_val = (float)n * safe_green;
    float blue_val = (float)n * safe_blue;
 
    // Clamp to unsigned short range before assignment
    if (red_val < (float)min_ushort) {
      red_val = (float)min_ushort;
    } else if (red_val > (float)max_ushort) {
      red_val = (float)max_ushort;
    }
 
    if (green_val < (float)min_ushort) {
      green_val = (float)min_ushort;
    } else if (green_val > (float)max_ushort) {
      green_val = (float)max_ushort;
    }
 
    if (blue_val < (float)min_ushort) {
      blue_val = (float)min_ushort;
    } else if (blue_val > (float)max_ushort) {
      blue_val = (float)max_ushort;
    }
 
    RED[n] = (unsigned short)red_val;
    GREEN[n] = (unsigned short)green_val;
    BLUE[n] = (unsigned short)blue_val;
    GRAY[n] = (unsigned short)n;
  }
}

References ASCII_LUMINANCE_LEVELS, BLUE, ERROR_INVALID_PARAM, GRAY, GREEN, log_error, log_warn, RED, and SET_ERRNO.

Referenced by server_main().

prewarm_sgr256_cache()

void prewarm_sgr256_cache

(

void

)

#include <ascii_simd.h>

Prewarm 256-color foreground/background cache for benchmarks.

Prevents first-frame performance penalty in benchmarks.

Definition at line 92 of file ascii_simd_color.c.

                                {
  // No-op: cache removed
}

Referenced by benchmark_simd_color_conversion_with_source().

prewarm_sgr256_fg_cache()

void prewarm_sgr256_fg_cache

(

void

)

#include <ascii_simd.h>

Prewarm 256-color foreground cache for benchmarks.

Prevents first-frame performance penalty in benchmarks.

Definition at line 88 of file ascii_simd_color.c.

                                   {
  // No-op: cache removed
}

Referenced by benchmark_simd_color_conversion_with_source().

print_simd_capabilities()

void print_simd_capabilities

(

void

)

#include <ascii_simd.h>

Print detected SIMD capabilities.

Prints available SIMD instruction sets to stdout.

Definition at line 276 of file ascii_simd.c.

                                   {
  printf("SIMD Support:\n");
#if SIMD_SUPPORT_AVX2
  printf("  ✓ AVX2 (32 pixels/cycle)\n");
#endif
#if SIMD_SUPPORT_NEON
  printf("  ✓ ARM NEON (16 pixels/cycle)\n");
#endif
#if SIMD_SUPPORT_SVE
  printf("  ✓ ARM SVE (scalable pixels/cycle)\n");
#endif
#if SIMD_SUPPORT_SSSE3
  printf("  ✓ SSSE3 (16 pixels/cycle)\n");
#endif
#if SIMD_SUPPORT_SSE2
  printf("  ✓ SSE2 (16 pixels/cycle)\n");
#endif
  printf("  ✓ Scalar fallback (1 pixel/cycle)\n");
}

quantize_color()

void quantize_color	(	int *	r,
		int *	g,
		int *	b,
		int	levels
	)

#include <image.h>

Quantize color to specified number of levels.

Parameters

r	Red component (input/output, must not be NULL, range 0-255)
g	Green component (input/output, must not be NULL, range 0-255)
b	Blue component (input/output, must not be NULL, range 0-255)
levels	Number of quantization levels (must be > 0)

Quantizes RGB color components to a specified number of levels. Reduces color precision for color palette mapping. Input colors are modified in-place to quantized values.

QUANTIZATION:

• Divides color range (0-255) into 'levels' bins
• Maps each component to nearest bin center
• Reduces color precision for palette mapping
• Used for 16-color and 256-color mode conversion

Note

Input/output parameters are modified in-place.

Quantization reduces color accuracy but enables palette mapping.

Typical values: 2 levels for 16-color, 6 levels for 256-color.

Definition at line 462 of file video/image.c.

                                                        {
  if (!r || !g || !b) {
    SET_ERRNO(ERROR_INVALID_PARAM, "quantize_color: r, g, or b is NULL");
    return;
  }
 
  if (levels <= 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "quantize_color: levels must be positive, got %d", levels);
    return;
  }
 
  int step = 256 / levels;
  *r = (*r / step) * step;
  *g = (*g / step) * step;
  *b = (*b / step) * step;
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

rep_is_profitable()

bool rep_is_profitable

(

uint32_t

runlen

)

#include <output_buffer.h>

Check if run-length encoding is profitable.

Parameters

runlen

Run length to check (number of repeated characters)

Returns

true if RLE is profitable, false otherwise

Determines whether run-length encoding (RLE) would reduce output size compared to emitting individual characters. RLE is profitable when the overhead of the repeat sequence is less than the characters it replaces.

RLE PROFITABILITY:

• RLE uses format: ESC[runs (e.g., ESC[100X repeats 'X' 100 times)
• Overhead: ~6-8 bytes for repeat sequence
• Profit: runlen - overhead bytes saved
• Profitable when runlen > ~10-15 characters

Note

Returns true if runlen exceeds RLE overhead threshold.

Threshold is tuned for typical ASCII art character runs.

Definition at line 141 of file output_buffer.c.

                                        {
  if (runlen <= 2)
    return false;
  uint32_t k = runlen - 1;                           // Extra repetitions beyond the first character
  uint32_t rep_cost = (uint32_t)(digits_u32(k) + 3); // ESC [ digits b
  return k > rep_cost;                               // Manual repetition cost vs REP cost
}

Referenced by ansi_compress_rle(), convert_pixels_scalar_with_newlines(), and image_print().

rgb_to_16color()

uint8_t rgb_to_16color	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <ansi_fast.h>

Convert RGB to 16-color ANSI index.

Parameters

r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

16-color ANSI index (0-15)

Definition at line 277 of file ansi_fast.c.

                                                        {
  // Convert RGB to the closest 16-color ANSI color
  // This uses a simple distance-based approach
 
  // Define the 16 ANSI colors in RGB
  static const uint8_t ansi_colors[16][3] = {
      {0, 0, 0},       // 0: Black
      {128, 0, 0},     // 1: Dark Red
      {0, 128, 0},     // 2: Dark Green
      {128, 128, 0},   // 3: Dark Yellow (Brown)
      {0, 0, 128},     // 4: Dark Blue
      {128, 0, 128},   // 5: Dark Magenta
      {0, 128, 128},   // 6: Dark Cyan
      {192, 192, 192}, // 7: Light Gray
      {128, 128, 128}, // 8: Dark Gray
      {255, 0, 0},     // 9: Bright Red
      {0, 255, 0},     // 10: Bright Green
      {255, 255, 0},   // 11: Bright Yellow
      {0, 0, 255},     // 12: Bright Blue
      {255, 0, 255},   // 13: Bright Magenta
      {0, 255, 255},   // 14: Bright Cyan
      {255, 255, 255}  // 15: White
  };
 
  uint8_t best_match = 0;
  int min_distance = INT_MAX;
 
  for (int i = 0; i < 16; i++) {
    int dr = (int)r - (int)ansi_colors[i][0];
    int dg = (int)g - (int)ansi_colors[i][1];
    int db = (int)b - (int)ansi_colors[i][2];
    int distance = dr * dr + dg * dg + db * db;
 
    if (distance < min_distance) {
      min_distance = distance;
      best_match = i;
    }
  }
 
  return best_match;
}

Referenced by append_color_fg_for_mode(), image_print_16color(), and rgb_to_16color_dithered().

rgb_to_16color_dithered()

uint8_t rgb_to_16color_dithered	(	int	r,
		int	g,
		int	b,
		int	x,
		int	y,
		int	width,
		int	height,
		rgb_error_t *	error_buffer
	)

#include <ansi_fast.h>

Convert RGB to 16-color with Floyd-Steinberg dithering.

Parameters

r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)
x	Pixel X coordinate
y	Pixel Y coordinate
width	Image width
height	Image height
error_buffer	Error diffusion buffer

Returns

16-color ANSI index (0-15)

Uses Floyd-Steinberg dithering algorithm for improved color approximation.

Definition at line 351 of file ansi_fast.c.

                                                                                                                     {
  // Add accumulated error from previous pixels
  if (error_buffer) {
    // Use size_t for index calculation to prevent integer overflow on large images
    size_t error_idx = (size_t)y * (size_t)width + (size_t)x;
    r += error_buffer[error_idx].r;
    g += error_buffer[error_idx].g;
    b += error_buffer[error_idx].b;
 
    // Reset error for this pixel
    error_buffer[error_idx].r = 0;
    error_buffer[error_idx].g = 0;
    error_buffer[error_idx].b = 0;
  }
 
  // Clamp values to [0, 255]
  uint8_t r_clamped = clamp_rgb((int)r);
  uint8_t g_clamped = clamp_rgb((int)g);
  uint8_t b_clamped = clamp_rgb((int)b);
 
  // Find the closest 16-color match
  uint8_t closest_color = rgb_to_16color(r_clamped, g_clamped, b_clamped);
 
  // Calculate quantization error if dithering is enabled
  if (error_buffer) {
    uint8_t actual_r, actual_g, actual_b;
    get_16color_rgb(closest_color, &actual_r, &actual_g, &actual_b);
 
    int error_r = r - (int)actual_r;
    int error_g = g - (int)actual_g;
    int error_b = b - (int)actual_b;
 
    // Distribute error using Floyd-Steinberg weights:
    //     * 7/16
    // 3/16 5/16 1/16
 
    // Error to right pixel (x+1, y)
    // Use size_t for all index calculations to prevent integer overflow
    if (x + 1 < width) {
      size_t right_idx = (size_t)y * (size_t)width + (size_t)(x + 1);
      error_buffer[right_idx].r += (error_r * 7) / 16;
      error_buffer[right_idx].g += (error_g * 7) / 16;
      error_buffer[right_idx].b += (error_b * 7) / 16;
    }
 
    // Error to pixels on next row (y+1)
    if (y + 1 < height) {
      // Bottom-left pixel (x-1, y+1)
      if (x - 1 >= 0) {
        size_t bl_idx = (size_t)(y + 1) * (size_t)width + (size_t)(x - 1);
        error_buffer[bl_idx].r += (error_r * 3) / 16;
        error_buffer[bl_idx].g += (error_g * 3) / 16;
        error_buffer[bl_idx].b += (error_b * 3) / 16;
      }
 
      // Bottom pixel (x, y+1)
      size_t bottom_idx = (size_t)(y + 1) * (size_t)width + (size_t)x;
      error_buffer[bottom_idx].r += (error_r * 5) / 16;
      error_buffer[bottom_idx].g += (error_g * 5) / 16;
      error_buffer[bottom_idx].b += (error_b * 5) / 16;
 
      // Bottom-right pixel (x+1, y+1)
      if (x + 1 < width) {
        size_t br_idx = (size_t)(y + 1) * (size_t)width + (size_t)(x + 1);
        error_buffer[br_idx].r += (error_r * 1) / 16;
        error_buffer[br_idx].g += (error_g * 1) / 16;
        error_buffer[br_idx].b += (error_b * 1) / 16;
      }
    }
  }
 
  return closest_color;
}

References rgb_error_t::b, rgb_error_t::g, get_16color_rgb(), rgb_error_t::r, and rgb_to_16color().

Referenced by image_print_16color_dithered(), and image_print_16color_dithered_with_background().

rgb_to_256color()

uint8_t rgb_to_256color	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <ansi_fast.h>

Convert RGB to 256-color palette index.

Parameters

r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

256-color palette index (0-255)

Definition at line 199 of file ansi_fast.c.

                                                         {
  // Map to 6x6x6 color cube (216 colors) + grayscale ramp
 
  // Check if it's close to grayscale
  int avg = (r + g + b) / 3;
  int gray_diff = abs(r - avg) + abs(g - avg) + abs(b - avg);
 
  if (gray_diff < 30) {
    // Use grayscale ramp (colors 232-255)
    int gray_level = (avg * 23) / 255;
    return (uint8_t)(232 + gray_level);
  }
 
  // Use 6x6x6 color cube (colors 16-231)
  int r6 = (r * 5) / 255;
  int g6 = (g * 5) / 255;
  int b6 = (b * 5) / 255;
 
  return (uint8_t)(16 + (r6 * 36) + (g6 * 6) + b6);
}

Referenced by append_color_fg_for_mode().

rgb_to_ansi_8bit()

void rgb_to_ansi_8bit	(	int	r,
		int	g,
		int	b,
		int *	fg_code,
		int *	bg_code
	)

#include <image.h>

Convert RGB to 8-bit ANSI color codes.

Parameters

r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)
fg_code	Output foreground color code (must not be NULL, range 0-255)
bg_code	Output background color code (must not be NULL, range 0-255)

Converts RGB color values to 8-bit ANSI color codes (256-color palette). Quantizes RGB colors to 256-color palette indices for foreground and background colors. Output codes are indices into 256-color ANSI palette.

COLOR QUANTIZATION:

• RGB colors are quantized to 256-color palette
• Quantization uses standard 6x6x6 color cube
• Output codes are palette indices (0-255)
• Foreground and background codes may differ

Note

Output parameters are modified to contain palette indices.

Color codes are indices into 256-color ANSI palette.

Quantization reduces color accuracy but enables 256-color mode.

Definition at line 628 of file video/image.c.

                                                                       {
  if (!fg_code || !bg_code) {
    SET_ERRNO(ERROR_INVALID_PARAM, "rgb_to_ansi_8bit: fg_code or bg_code is NULL");
    return;
  }
 
  // Convert RGB to 8-bit color code (216 color cube + 24 grayscale)
  if (r == g && g == b) {
    // Grayscale
    if (r < 8) {
      *fg_code = 16;
    } else if (r > 248) {
      *fg_code = 231;
    } else {
      *fg_code = 232 + (r - 8) / 10;
    }
  } else {
    // Color cube: 16 + 36*r + 6*g + b where r,g,b are 0-5
    int r_level = (r * 5) / 255;
    int g_level = (g * 5) / 255;
    int b_level = (b * 5) / 255;
    *fg_code = 16 + 36 * r_level + 6 * g_level + b_level;
  }
  *bg_code = *fg_code; // Same logic for background
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

rgb_to_ansi_bg()

char * rgb_to_ansi_bg	(	int	r,
		int	g,
		int	b
	)

#include <image.h>

Convert RGB to ANSI background color code.

Parameters

r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

Allocated ANSI color code string (caller must free), or NULL on error

Converts RGB color values to ANSI background color escape sequence. Returns a string containing the ANSI escape sequence for background color (e.g., "\033[48;2;255;0;0m" for red background).

Note

Returns NULL on error (memory allocation failure).

ANSI string must be freed by caller using free().

ANSI sequence format: ESC[48;2;r;g;bm (truecolor mode).

Color components are clamped to 0-255 range automatically.

Definition at line 622 of file video/image.c.

                                          {
  _Thread_local static char color_code[20]; // \033[48;2;255;255;255m + \0 = 20 bytes max
  SAFE_SNPRINTF(color_code, sizeof(color_code), "\033[48;2;%d;%d;%dm", r, g, b);
  return color_code;
}

References SAFE_SNPRINTF.

rgb_to_ansi_fg()

char * rgb_to_ansi_fg	(	int	r,
		int	g,
		int	b
	)

#include <image.h>

Convert RGB to ANSI foreground color code.

Parameters

r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns

Allocated ANSI color code string (caller must free), or NULL on error

Converts RGB color values to ANSI foreground color escape sequence. Returns a string containing the ANSI escape sequence for foreground color (e.g., "\033[38;2;255;0;0m" for red).

Note

Returns NULL on error (memory allocation failure).

ANSI string must be freed by caller using free().

ANSI sequence format: ESC[38;2;r;g;bm (truecolor mode).

Color components are clamped to 0-255 range automatically.

Definition at line 616 of file video/image.c.

                                          {
  _Thread_local static char color_code[20]; // \033[38;2;255;255;255m + \0 = 20 bytes max
  SAFE_SNPRINTF(color_code, sizeof(color_code), "\033[38;2;%d;%d;%dm", r, g, b);
  return color_code;
}

References SAFE_SNPRINTF.

set_color_quality_mode()

void set_color_quality_mode

(

bool

high_quality

)

#include <ascii_simd.h>

Set color quality mode.

Parameters

high_quality

true for 24-bit truecolor, false for 256-color

Controls tradeoff between color fidelity and rendering speed.

simd_caches_destroy_all()

void simd_caches_destroy_all

(

void

)

#include <common.h>

Destroy all SIMD caches.

Cleans up all caches and frees associated memory.

Referenced by server_main().

str_append_bytes()

void str_append_bytes	(	Str *	s,
		const void *	src,
		size_t	n
	)

#include <ascii_simd.h>

Append bytes to string buffer.

Parameters

s	String buffer structure
src	Source data
n	Number of bytes to append

Definition at line 130 of file ascii_simd.c.

                                                         {
  str_reserve(s, s->len + n);
  memcpy(s->data + s->len, src, n);
  s->len += n;
}

References Str::data, Str::len, and str_reserve().

Referenced by str_printf().

str_append_c()

void str_append_c	(	Str *	s,
		char	c
	)

#include <ascii_simd.h>

Append character to string buffer.

Parameters

s	String buffer structure
c	Character to append

Definition at line 136 of file ascii_simd.c.

                                  {
  str_reserve(s, s->len + 1);
  s->data[s->len++] = c;
}

References Str::data, Str::len, and str_reserve().

str_free()

void str_free

(

Str *

s

)

#include <ascii_simd.h>

Free string buffer.

Parameters

s	String buffer structure

Definition at line 114 of file ascii_simd.c.

                      {
  SAFE_FREE(s->data);
  s->data = NULL;
  s->len = s->cap = 0;
}

References Str::cap, Str::data, Str::len, and SAFE_FREE.

str_init()

void str_init

(

Str *

s

)

#include <ascii_simd.h>

Initialize string buffer.

Parameters

s	String buffer structure

Definition at line 108 of file ascii_simd.c.

                      {
  s->data = NULL;
  s->len = 0;
  s->cap = 0;
}

References Str::cap, Str::data, and Str::len.

str_printf()

void str_printf	(	Str *	s,
		const char *	fmt,
			...
	)

#include <ascii_simd.h>

Append formatted string to buffer.

Parameters

s	String buffer structure
fmt	Format string
...	Variable arguments

Definition at line 141 of file ascii_simd.c.

                                              {
  va_list ap;
  va_start(ap, fmt);
  char stackbuf[256];
  int n = vsnprintf(stackbuf, sizeof(stackbuf), fmt, ap);
  va_end(ap);
  if (n < 0)
    return;
  if ((size_t)n < sizeof(stackbuf)) {
    str_append_bytes(s, stackbuf, (size_t)n);
    return;
  }
  char *heap;
  heap = SAFE_MALLOC((size_t)n + 1, char *);
  va_start(ap, fmt);
  (void)vsnprintf(heap, (size_t)n + 1, fmt, ap);
  va_end(ap);
  str_append_bytes(s, heap, (size_t)n);
  SAFE_FREE(heap);
}

References SAFE_FREE, SAFE_MALLOC, and str_append_bytes().

str_reserve()

void str_reserve	(	Str *	s,
		size_t	need
	)

#include <ascii_simd.h>

Reserve space in string buffer.

Parameters

s	String buffer structure
need	Minimum bytes needed

Definition at line 120 of file ascii_simd.c.

                                      {
  if (need <= s->cap)
    return;
  size_t ncap = s->cap ? s->cap : 4096;
  while (ncap < need)
    ncap = (ncap * 3) / 2 + 64;
  s->data = SAFE_REALLOC(s->data, ncap, char *);
  s->cap = ncap;
}

References Str::cap, Str::data, and SAFE_REALLOC.

Referenced by str_append_bytes(), and str_append_c().

write_rgb_triplet()

size_t write_rgb_triplet	(	uint8_t	value,
		char *	dst
	)

#include <common.h>

Write decimal RGB triplet using dec3 cache.

Parameters

value	RGB component value (0-255)
dst	Destination buffer pointer

Returns

Number of bytes written

Note

Defined in ascii_simd.c to avoid circular dependencies.

Definition at line 26 of file ascii_simd.c.

                                                   {
  const dec3_t *d = &g_dec3_cache.dec3_table[value];
  memcpy(dst, d->s, d->len);
  return d->len;
}

References global_dec3_cache_t::dec3_table, g_dec3_cache, dec3_t::len, and dec3_t::s.

write_row_rep_from_arrays_enhanced()

size_t write_row_rep_from_arrays_enhanced	(	const uint8_t *	fg_r,
		const uint8_t *	fg_g,
		const uint8_t *	fg_b,
		const uint8_t *	bg_r,
		const uint8_t *	bg_g,
		const uint8_t *	bg_b,
		const uint8_t *	fg_idx,
		const uint8_t *	bg_idx,
		const char *	ascii_chars,
		int	width,
		char *	dst,
		size_t	cap,
		bool	is_truecolor
	)

#include <ascii_simd.h>

Enhanced REP compression writer.

Parameters

fg_r	Foreground red array
fg_g	Foreground green array
fg_b	Foreground blue array
bg_r	Background red array
bg_g	Background green array
bg_b	Background blue array
fg_idx	Foreground color indices
bg_idx	Background color indices
ascii_chars	Character palette
width	Image width in pixels
dst	Output buffer
cap	Output buffer capacity
is_truecolor	Use truecolor mode

Returns

Number of bytes written

Used by scalar fallbacks and declared in NEON implementation.

Variable Documentation

access_count

_Atomic uint32_t utf8_palette_cache_s::access_count

Total access count (atomic)

Definition at line 111 of file video/simd/common.h.

Referenced by __attribute__().

ascii_palette

char ascii_palette[]

extern

#include <ascii.h>

Default ASCII palette characters.

Default character palette for ASCII art conversion. Contains characters ordered by luminance (dark to light) for mapping pixel brightness to ASCII characters.

Note

External variable (defined in ascii.c).

Default palette: " .:-=+*#%@$" (common ASCII art palette).

avx2_time

double simd_benchmark_t::avx2_time

AVX2 implementation time (seconds)

Definition at line 275 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

best_method

const char* simd_benchmark_t::best_method

Name of fastest method

Definition at line 279 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

byte_len

uint8_t utf8_char_t::byte_len

Actual byte length (1-4)

Definition at line 91 of file video/simd/common.h.

Referenced by build_utf8_luminance_cache(), build_utf8_ramp64_cache(), image_print(), image_print_16color(), image_print_16color_dithered(), and image_print_16color_dithered_with_background().

cache

utf8_char_t utf8_palette_cache_s::cache[256]

256-entry cache for direct luminance lookup (monochrome)

Definition at line 103 of file video/simd/common.h.

Referenced by image_print_16color(), image_print_16color_dithered(), image_print_16color_dithered_with_background(), and image_print_color().

cache64

utf8_char_t utf8_palette_cache_s::cache64[64]

64-entry cache for SIMD color lookup

Definition at line 104 of file video/simd/common.h.

Referenced by image_print().

cached_score

double utf8_palette_cache_s::cached_score

Last calculated eviction score

Definition at line 116 of file video/simd/common.h.

cap

size_t Str::cap

Total bytes allocated

Definition at line 147 of file ascii_simd.h.

Referenced by str_free(), str_init(), and str_reserve().

cBB

int RLEState::cBB

Current background RGB

Definition at line 213 of file ascii_simd.h.

cBG

int RLEState::cBG

Definition at line 213 of file ascii_simd.h.

cBR

int RLEState::cBR

Definition at line 213 of file ascii_simd.h.

cFB

int RLEState::cFB

Current foreground RGB

Definition at line 212 of file ascii_simd.h.

cFG

int RLEState::cFG

Definition at line 212 of file ascii_simd.h.

cFR

int RLEState::cFR

Definition at line 212 of file ascii_simd.h.

char_index_ramp

uint8_t utf8_palette_cache_s::char_index_ramp[64]

Character indices for vqtbl4q_u8 lookup

Definition at line 105 of file video/simd/common.h.

Referenced by image_print(), image_print_16color(), image_print_16color_dithered(), and image_print_16color_dithered_with_background().

creation_time

uint64_t utf8_palette_cache_s::creation_time

When cache was created (immutable)

Definition at line 112 of file video/simd/common.h.

data

char* Str::data

Pointer to allocated buffer

Definition at line 145 of file ascii_simd.h.

Referenced by str_append_bytes(), str_append_c(), str_free(), str_init(), and str_reserve().

dec3

dec3_t dec3[256]

extern

#include <ansi_fast.h>

Access to internal decimal lookup table for testing.

dec3_initialized

bool global_dec3_cache_t::dec3_initialized

Whether cache is initialized

Definition at line 99 of file ascii_simd.h.

Referenced by init_dec3().

dec3_table

dec3_t global_dec3_cache_t::dec3_table[256]

Lookup table for 0-255

Definition at line 98 of file ascii_simd.h.

Referenced by append_sgr_truecolor_bg(), append_sgr_truecolor_fg(), append_sgr_truecolor_fg_bg(), append_truecolor_bg(), append_truecolor_fg(), append_truecolor_fg_bg(), init_dec3(), and write_rgb_triplet().

g_dec3_cache

global_dec3_cache_t g_dec3_cache

extern

#include <ascii_simd.h>

Global decimal cache instance.

Definition at line 23 of file ascii_simd.c.

{.dec3_initialized = false};

Referenced by append_sgr_truecolor_bg(), append_sgr_truecolor_fg(), append_sgr_truecolor_fg_bg(), append_truecolor_bg(), append_truecolor_fg(), append_truecolor_fg_bg(), init_dec3(), and write_rgb_triplet().

g_default_luminance_palette

char g_default_luminance_palette[256]

extern

#include <ascii_simd.h>

Default luminance palette (256 characters)

Definition at line 33 of file ascii_simd.c.

Referenced by benchmark_simd_color_conversion_with_source(), and init_default_luminance_palette().

h

int ImageRGB::h

Image height in pixels

Definition at line 227 of file ascii_simd.h.

Referenced by alloc_image().

heap_index

size_t utf8_palette_cache_s::heap_index

Min-heap eviction management (protected by write lock) Position in min-heap (for O(log n) updates)

Definition at line 115 of file video/simd/common.h.

hh

UT_hash_handle utf8_palette_cache_s::hh

uthash handle (required for hash table operations)

Definition at line 119 of file video/simd/common.h.

is_valid

bool utf8_palette_cache_s::is_valid

Whether cache is valid

Definition at line 107 of file video/simd/common.h.

key

uint32_t utf8_palette_cache_s::key

Hash key for uthash lookup

Definition at line 102 of file video/simd/common.h.

Referenced by __attribute__().

last_access_time

_Atomic uint64_t utf8_palette_cache_s::last_access_time

Thread-safe eviction tracking Nanoseconds since epoch (atomic)

Definition at line 110 of file video/simd/common.h.

Referenced by __attribute__().

len [1/2]

uint8_t dec3_t::len

Number of digits (1-3)

Definition at line 88 of file ascii_simd.h.

Referenced by append_sgr_truecolor_bg(), append_sgr_truecolor_fg(), append_sgr_truecolor_fg_bg(), append_truecolor_bg(), append_truecolor_fg(), append_truecolor_fg_bg(), init_dec3(), and write_rgb_triplet().

len [2/2]

size_t Str::len

Number of bytes currently used

Definition at line 146 of file ascii_simd.h.

Referenced by str_append_bytes(), str_append_c(), str_free(), and str_init().

neon_time

double simd_benchmark_t::neon_time

NEON implementation time (seconds)

Definition at line 276 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

palette_hash

char utf8_palette_cache_s::palette_hash[64]

Hash of palette for cache validation

Definition at line 106 of file video/simd/common.h.

pixels

uint8_t* ImageRGB::pixels

RGB data: w * h * 3 bytes

Definition at line 228 of file ascii_simd.h.

Referenced by alloc_image().

runLen

int RLEState::runLen

Current run length

Definition at line 214 of file ascii_simd.h.

s

char dec3_t::s[3]

Digit string (no null terminator)

Definition at line 89 of file ascii_simd.h.

Referenced by append_sgr_truecolor_bg(), append_sgr_truecolor_fg(), append_sgr_truecolor_fg_bg(), append_truecolor_bg(), append_truecolor_fg(), append_truecolor_fg_bg(), init_dec3(), and write_rgb_triplet().

scalar_time

double simd_benchmark_t::scalar_time

Scalar implementation time (seconds)

Definition at line 272 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

seeded

int RLEState::seeded

Whether state is initialized

Definition at line 215 of file ascii_simd.h.

speedup_best

double simd_benchmark_t::speedup_best

Best speedup ratio

Definition at line 278 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

sse2_time

double simd_benchmark_t::sse2_time

SSE2 implementation time (seconds)

Definition at line 273 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

ssse3_time

double simd_benchmark_t::ssse3_time

SSSE3 implementation time (seconds)

Definition at line 274 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion(), benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

sve_time

double simd_benchmark_t::sve_time

SVE implementation time (seconds)

Definition at line 277 of file ascii_simd.h.

Referenced by benchmark_simd_color_conversion_with_source(), benchmark_simd_conversion(), and benchmark_simd_conversion_with_source().

utf8_bytes

char utf8_char_t::utf8_bytes[4]

UTF-8 character bytes (up to 4)

Definition at line 90 of file video/simd/common.h.

Referenced by build_utf8_luminance_cache(), build_utf8_ramp64_cache(), image_print(), image_print_16color(), image_print_16color_dithered(), image_print_16color_dithered_with_background(), and image_print_color().

w

int ImageRGB::w

Image width in pixels

Definition at line 226 of file ascii_simd.h.

Referenced by alloc_image().