🖼️ 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	digital_rain.c
	Matrix-style digital rain effect implementation.

file	common.c
	ARM NEON-accelerated ASCII rendering utilities.

file	halfblock.c
	ARM NEON-accelerated ASCII half-block rendering.

file	background.c
	Scalar ASCII background color rendering (truecolor)

file	ansi.c
	ANSI escape sequence utilities and fast color code generation with SIMD-accelerated terminal output.

file	digital_rain.h
	Matrix-style digital rain effect for ASCII frames.

file	avx2.h
	AVX2-optimized ASCII rendering functions.

file	common.h
	SIMD-optimized ASCII conversion interface.

file	neon.h
	NEON-optimized ASCII rendering functions.

file	common.h
	ARM NEON-accelerated ASCII rendering utilities (declarations)

file	sgr.h
	ANSI SGR (Select Graphic Rendition) color sequence generation.

file	sse2.h
	SSE2-optimized ASCII rendering functions.

file	ssse3.h
	SSSE3-optimized ASCII rendering functions.

file	sve.h
	SVE-optimized ASCII rendering functions.

file	ansi.h
	ANSI escape sequence utilities and fast color code generation.

Data Structures
struct	digital_rain_column_t
	Digital rain column state. More...

struct	digital_rain_t
	Digital rain effect context. More...

struct	ascii_frame_source_t
	Frame source structure for grid layout. 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

struct	utf8_palette_cache

struct	outbuf_t
	Dynamic output buffer (auto-expanding) More...

struct	color_filter_def_t
	Color filter metadata structure. More...

struct	rgb_pixel_t
	RGB pixel structure. More...

struct	rgb_pixel_simd_t
	SIMD-aligned RGB pixel structure for optimal NEON/AVX performance. More...

struct	image_t
	Image structure. More...

Macros
#define	DIGITAL_RAIN_DEFAULT_FALL_SPEED 3.0f
	Default fall speed for raindrops.

#define	DIGITAL_RAIN_DEFAULT_RAINDROP_LENGTH 12.0f
	Default raindrop length.

#define	DIGITAL_RAIN_DEFAULT_BRIGHTNESS_DECAY 0.1f
	Default brightness decay factor.

#define	DIGITAL_RAIN_DEFAULT_ANIMATION_SPEED 1.0f
	Default animation speed multiplier.

#define	DIGITAL_RAIN_DEFAULT_COLOR_R 0
	Default Matrix green color (R, G, B)

#define	DIGITAL_RAIN_DEFAULT_COLOR_G 255

#define	DIGITAL_RAIN_DEFAULT_COLOR_B 80

#define	DIGITAL_RAIN_DEFAULT_CURSOR_BRIGHTNESS 2.0f
	Cursor brightness multiplier.

#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	ascii_zzz() time_sleep_ns(ASCII_SLEEP_NS)
	Sleep for frame rate limiting.

#define	RAMP64_SIZE 64
	UTF-8 character palette cache.

#define	CACHE_FREQUENCY_DECAY_TIME 10000

#define	CACHE_RECENCY_SCALE 100

#define	CACHE_MAX_LIFETIME 3600

#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.

Typedefs
typedef struct utf8_palette_cache	utf8_palette_cache_t

Enumerations
enum	image_alloc_method_t { IMAGE_ALLOC_SIMD = 0 , IMAGE_ALLOC_POOL = 1 }
	Pixel allocation method tracking. More...

Functions
digital_rain_t *	digital_rain_init (int num_columns, int num_rows)
	Initialize digital rain effect context.

void	digital_rain_destroy (digital_rain_t *rain)
	Destroy digital rain effect context.

char *	digital_rain_apply (digital_rain_t rain, const char frame, float delta_time)
	Apply digital rain effect to ASCII frame.

void	digital_rain_reset (digital_rain_t *rain)
	Reset digital rain effect state.

void	digital_rain_set_fall_speed (digital_rain_t *rain, float speed)
	Set digital rain fall speed.

void	digital_rain_set_raindrop_length (digital_rain_t *rain, float length)
	Set digital rain raindrop length.

void	digital_rain_set_color (digital_rain_t *rain, uint8_t r, uint8_t g, uint8_t b)
	Set digital rain color.

void	digital_rain_set_color_from_filter (digital_rain_t *rain, color_filter_t filter)
	Set digital rain color from color filter.

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)
	Convert image to ASCII art with terminal capability awareness.

char *	image_print_with_capabilities (const image_t image, const terminal_capabilities_t caps, const char *palette)
	Convert image to ASCII art with terminal capabilities.

asciichat_error_t	ascii_write (const char *frame)
	Write ASCII frame to terminal.

void	ascii_write_destroy (int fd, bool reset_terminal)
	Destroy ASCII write subsystem.

char *	ascii_pad_frame_width (const char *frame, size_t pad)
	Add leading spaces (left-padding) to each line of a frame.

char *	ascii_pad_frame_height (const char *frame, size_t pad_top)
	Add blank lines (vertical padding) to center a frame vertically.

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.

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_destroy (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_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_bg_string (uint8_t bg, uint8_t *len_out)
	Get 256-color background 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_utf8_luminance_cache (const char *ascii_chars, utf8_char_t cache[256])
	Build UTF-8 luminance cache for all 256 levels.

void	build_utf8_ramp64_cache (const char *ascii_chars, utf8_char_t cache64[64], uint8_t char_index_ramp[256])
	Build UTF-8 ramp64 cache and character index ramp.

utf8_palette_cache_t *	get_utf8_palette_cache (const char *ascii_chars)
	Get UTF-8 palette cache for a character set.

void	simd_caches_destroy_all (void)
	Destroy all SIMD caches (palette and other caches)

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.

char *	rgb_to_truecolor_halfblocks_scalar (const uint8_t *rgb, int width, int height, int stride_bytes)
	Convert RGB to truecolor half-blocks using scalar code.

char *	rgb_to_halfblocks_scalar (const uint8_t rgb, int width, int height, int stride_bytes, const char palette)
	Convert RGB to monochrome (grayscale) half-blocks using scalar code.

char *	rgb_to_16color_halfblocks_scalar (const uint8_t rgb, int width, int height, int stride_bytes, const char palette)
	Convert RGB to 16-color half-blocks using scalar code.

char *	rgb_to_256color_halfblocks_scalar (const uint8_t rgb, int width, int height, int stride_bytes, const char palette)
	Convert RGB to 256-color half-blocks using scalar code.

const color_filter_def_t *	color_filter_get_metadata (color_filter_t filter)
	Get color filter metadata by enum value.

color_filter_t	color_filter_from_cli_name (const char *cli_name)
	Convert color filter CLI name to enum value.

void	color_filter_calculate_rainbow (float time, uint8_t r, uint8_t g, uint8_t *b)
	Calculate rainbow color from time (3.5s cycle)

char *	rainbow_replace_ansi_colors (const char *ansi_string, float time_seconds)
	Replace all RGB ANSI codes with rainbow color.

int	apply_color_filter (uint8_t *pixels, uint32_t width, uint32_t height, uint32_t stride, color_filter_t filter, float time)
	Apply color filter to entire image in-place.

asciichat_error_t	image_render_test_pattern (image_t image, unsigned int frame_counter)
	Render animated color bars and grid lines into an existing image.

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)

image_t *	image_new_copy (const image_t *source)
	Create a copy of an existing image.

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_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.

Variables
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

uint8_t	utf8_char_t::width

uint8_t	utf8_char_t::utf8_bytes [4]

uint8_t	utf8_char_t::byte_len

uint8_t	utf8_char_t::_pad

utf8_char_t	utf8_palette_cache::cache [256]

utf8_char_t	utf8_palette_cache::cache64 [64]

uint8_t	utf8_palette_cache::char_index_ramp [256]

atomic_t	utf8_palette_cache::last_access_time

atomic_t	utf8_palette_cache::access_count

uint32_t	utf8_palette_cache::total_age_seconds

uint64_t	utf8_palette_cache::creation_time

double	utf8_palette_cache::cached_score

size_t	utf8_palette_cache::heap_index

uint32_t	utf8_palette_cache::key

char	utf8_palette_cache::palette_hash [256]

bool	utf8_palette_cache::initialized

bool	utf8_palette_cache::is_valid

UT_hash_handle	utf8_palette_cache::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.

Detailed Description

🖼️ Everything necessary to turn pixels into text art

Implements a Matrix-inspired digital rain effect that can be applied to ASCII frames as a post-processing step. The effect creates the illusion of "falling" characters by modulating brightness in a sawtooth wave pattern.

ALGORITHM OVERVIEW:

The digital rain effect is based on the observation that Matrix code rain isn't actually falling characters - it's stationary characters whose brightness changes to create the illusion of rain. Key concepts:

Sawtooth Wave: Each column has a brightness wave that repeats, creating multiple "raindrops" falling at different speeds.
Cursor/Tracer: The bright leading character is detected where brightness increases (where the wave rises).
Organic Variation: Random timing offsets and wobble functions prevent mechanical-looking patterns.

IMPLEMENTATION:

Per-column state tracking (timing, speed, phase)
Brightness calculation using fractional time wrapping
ANSI color code injection for brightness modulation
Cursor highlighting with increased brightness
Smooth brightness transitions via decay blending

Note: This effect is applied AFTER ASCII conversion; Works with both color and monochrome ASCII frames; Minimal performance impact (O(frame_size) single pass)

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

Date: February 2026

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 AVX2 (Advanced Vector Extensions 2) optimized functions for converting images to ASCII art on modern x86-64 CPUs.

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

Date: September 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 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 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 scalar (non-SIMD) halfblock rendering functions for converting RGB images to ANSI-escaped halfblock characters with truecolor foreground and background colors.

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

Date: February 2026

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

This module provides color filtering capabilities to apply monochromatic color tints to grayscale video feeds. The server processes color filters; clients see each user in their chosen filter color.

FEATURES:

11 built-in color filters (matrix green, cyan, magenta, etc.)
ITU-R BT.601 grayscale conversion formula
Two colorization modes: "color on white" and "white on color"
Per-pixel colorization for maximum quality
Protocol integration via CLIENT_CAPABILITIES packet

COLOR FILTERS:

0. none (no filtering)

black (dark content on white background)
white (white content on black background)
green (#00FF41)
magenta (#FF00FF)
fuchsia (#FF00AA)
orange (#FF8800)
teal (#00DDDD)
cyan (#00FFFF)
pastel-pink (#FFB6C1)
error-red (#FF3333)
yellow (#FFEB99)

ARCHITECTURE:

color_filter_registry[]: Metadata for all 11 filters (name, CLI name, RGB values, mode)
rgb_to_grayscale(): ITU-R BT.601 conversion (efficient fixed-point math)
colorize_grayscale_pixel(): Single pixel colorization (inline for performance)
apply_color_filter(): Image-wide colorization (in-place operation)

USAGE:

// Convert image to grayscale and apply filter
if (filter != COLOR_FILTER_NONE) {
    apply_color_filter(image, width, height, filter);
}

PROTOCOL INTEGRATION:

The color_filter field is included in the CLIENT_CAPABILITIES packet:

Client sends chosen filter to server during connection
Server applies filter to client's video before ASCII conversion
All clients see the filtered output

Note: All filter colors are applied using ITU-R BT.601 grayscale conversion; Filters automatically set –color-mode mono (monochromatic display); "--color-filter foo --color-mode 256" is an error

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

Date: February 2026

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

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:

Capturing RGB frames from webcam (1920x1080 or configured resolution)
Scaling frames to terminal dimensions (typically 80x24 to 200x60)
Converting RGB pixels to grayscale luminance
Mapping luminance values to ASCII characters from a palette
Optionally preserving color information via ANSI escape sequences
Generating optimized ANSI output for terminal rendering
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 vs Scalar Implementations

ascii-chat provides both scalar (non-SIMD) and SIMD implementations of video conversion, with automatic runtime selection based on CPU capabilities.

Scalar (Non-SIMD) Implementation

Purpose: Fallback for processors without SIMD support, reference implementation

File: lib/video/scalar/halfblock.c

Algorithm:

Processes one source pixel at a time
No vector instructions - standard integer arithmetic
Suitable for embedded systems and older CPUs

Performance Characteristics:

Single-threaded throughput: ~15 FPS for 1920x1080 → 160x45
Latency: 66 ms per frame (16.7 ms target for 60 FPS)
CPU usage: ~25% on single core (limited by core speed)
Memory bandwidth: Not optimized (scalar loads dominate)
Cache efficiency: Moderate (sequential memory access)

When to Use:

Baseline architecture where SIMD unavailable
Testing and validation (reference implementation)
Debugging (easier to trace scalar logic)
Embedded systems with no vector support

Trade-offs:

Advantage: Maximal portability, simpler code
Disadvantage: ~4-8x slower than SIMD, unsuitable for real-time video

SIMD vs Scalar Implementations

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);

Optimization Strategy

ascii-chat uses a multi-layered optimization approach to achieve real-time video conversion:

Architecture-Level Optimization

SIMD Instruction Selection:

Single implementation compiled per target (not runtime branches within loops)
Avoids branch prediction penalties in hot loops
CMake selects highest available SIMD level at build time

Build-Time vs Runtime Selection:

Build Time:    CMake detects target CPU → Selects SIMD level → Compiles one variant
Runtime:       CPU detection validates assumptions → Falls back if needed
Result:        Optimal code without runtime dispatch overhead

Algorithm-Level Optimization

Parallel Data Processing:

SSE2/NEON: Process 16 bytes per instruction (16 RGB values or 4 RGBA pixels)
AVX2: Process 32 bytes per instruction (32 luminance values)
Reduces loop iterations by 4-8x vs scalar

Color Caching:

UTF-8 palette cache: 256 entries for monochrome, 64 for color
Eviction algorithm: LRU with frequency/recency scoring
~5-10 MB cache to avoid repeated string lookups

ANSI Escape Sequence Optimization:

Stateful color tracking: Only emit color change when needed
Run-length encoding: Combine consecutive identical characters
Pre-allocated buffers avoid malloc per frame

Memory Hierarchy Optimization

Cache Line Awareness:

Process data in 64-byte chunks (typical L1 cache line)
Bilinear scaling: Process 2x2 pixel blocks with temporal locality
Luminance conversion: Sequential access patterns

Zero-Copy Techniques:

Webcam frames returned as direct memory pointers
Output buffers pre-allocated in buffer pool
Avoid malloc/memcpy in hot loops

SIMD Register Utilization:

Use all available vector registers (XMM0-15 for SSE2, YMM0-15 for AVX2)
Instruction-level parallelism: Multiple independent operations per cycle
Minimize register spills to stack

Spatial Locality

Bilinear Scaling: Process pixels in raster order

Sequential reads from source image
Sequential writes to scaled output
Prefetcher-friendly access patterns

Luminance Conversion: Stream processing

Read RGB triplets sequentially
Compute Y value immediately
Write Y value to output
Cache misses minimized by streaming pattern

Performance Benchmarks

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

Implementation	FPS	Latency	CPU %	Speedup vs Scalar
Scalar	15	66 ms	25%	1x (baseline)
SSE2	60	16 ms	6%	4x
SSSE3	75	13 ms	5%	5x
AVX2	90	11 ms	4%	6x

Measured on Apple M1 (ARM NEON):

NEON: 120 FPS, 8 ms latency, 5% CPU (8x speedup vs scalar)

Performance Analysis:

Scalar implementation bottlenecked by memory bandwidth (~25% CPU from single core)
SSE2 achieves 4x speedup with 16-byte parallel processing
AVX2 approaches 6x speedup limited by memory system (not ALU bound)
60 FPS target achievable on all SIMD targets with <10% single-core 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

Performance Trade-offs Analysis

Scalar vs SIMD Trade-offs

Scalar Advantages:

Universal portability (any CPU)
Small binary size (<50 KB)
No CPU detection overhead
Easier to debug (serial execution model)

**Scalar Disadvantages**:

4-8x slower than SIMD on typical CPUs
~25% single-core CPU at 15 FPS (unsustainable for real-time)
Memory bandwidth underutilized
Not suitable for production video chat

**Decision Rationale**:

ascii-chat targets modern CPUs (post-2005) where SIMD is standard
Scalar kept as fallback for: testing, validation, exotic platforms
Production paths use SIMD to meet real-time requirements

SIMD Level Trade-offs

Level	Year	Speedup vs SSE2	Availability	Recommendation
Scalar	N/A	0.25x	100%	Fallback only
SSE2	2001	1x (baseline)	99%	x86_64 default
SSSE3	2006	1.25x	95%	Nice-to-have
AVX2	2013	1.5x	80%	Best for x86
NEON	2007	1.3-2x	100% ARM	ARM default
SVE	2017	2-4x	5%	Future use

Architecture Selection Logic:

At build time, CMake checks:
1. Target architecture (x86_64, ARM, ARM64, PowerPC)
2. Compiler support for intrinsics
3. Optional: Runtime detection preference
 
Best-fit selection:
- x86_64: Default SSE2 (baseline), enable AVX2 if compiler supports
- ARM: NEON (baseline for 32-bit), SVE if available
- Fallback: Always provide scalar for maximum compatibility

Compilation Strategy:

Single SIMD variant compiled per build (no runtime dispatch)
Avoids branch prediction penalty in hot loops
Smaller binary: Only one code path compiled
Cleaner CPU-specific code paths

Latency vs Throughput

64 FPS at 1920x1080:

Target latency: ~16 ms per frame (16.7 ms budget)
Scalar: 66 ms (4x over budget - unsuitable)
SSE2: 16 ms (meets target)
AVX2: 11 ms (headroom for other processing)

Strategy:

SIMD essential to stay within real-time deadline
Headroom (11 ms on AVX2) allows for:
- Webcam capture (~1-2 ms)
- Network transmission (~5-10 ms)
- Terminal rendering (~2-3 ms)

Power Efficiency

Energy Per Frame:

Implementation	Frames/sec	Power	Energy/Frame	Relative
Scalar	15 FPS	25W	1.67 J	1.0x
SSE2	60 FPS	6W	0.10 J	0.06x
AVX2	90 FPS	4W	0.04 J	0.03x

Analysis:

SIMD dramatically reduces energy/frame (16-25x improvement)
Enables battery operation on mobile devices
Reduces thermal load and cooling requirements

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 454 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 468 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 441 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 529 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 410 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 423 of file ascii.h.

◆ ascii_zzz

#define ascii_zzz ( ) time_sleep_ns(ASCII_SLEEP_NS)

#include <ascii.h>

Sleep for frame rate limiting.

Sleeps for a short duration (50 microseconds) to limit frame rate and prevent excessive terminal I/O. Uses time_sleep_ns() for precise nanosecond-precision timing control with the unified timing API.

Note: Sleep duration: 50000 nanoseconds (50 microseconds); Used between frame outputs for rate limiting.

Definition at line 548 of file ascii.h.

◆ CACHE_FREQUENCY_DECAY_TIME

#define CACHE_FREQUENCY_DECAY_TIME 10000

#include <common.h>

Definition at line 463 of file video/ascii/common.h.

◆ CACHE_MAX_LIFETIME

#define CACHE_MAX_LIFETIME 3600

#include <common.h>

Definition at line 465 of file video/ascii/common.h.

◆ CACHE_RECENCY_SCALE

#define CACHE_RECENCY_SCALE 100

#include <common.h>

Definition at line 464 of file video/ascii/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 507 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 518 of file ascii.h.

◆ DIGITAL_RAIN_DEFAULT_ANIMATION_SPEED

#define DIGITAL_RAIN_DEFAULT_ANIMATION_SPEED 1.0f

#include <digital_rain.h>

Default animation speed multiplier.

Overall animation speed. 1.0 = normal speed.

Definition at line 128 of file digital_rain.h.

◆ DIGITAL_RAIN_DEFAULT_BRIGHTNESS_DECAY

#define DIGITAL_RAIN_DEFAULT_BRIGHTNESS_DECAY 0.1f

#include <digital_rain.h>

Default brightness decay factor.

Controls how quickly brightness transitions occur (0-1). Higher values = more immediate transitions, lower = smoother.

Definition at line 121 of file digital_rain.h.

◆ DIGITAL_RAIN_DEFAULT_COLOR_B

#define DIGITAL_RAIN_DEFAULT_COLOR_B 80

#include <digital_rain.h>

Definition at line 137 of file digital_rain.h.

◆ DIGITAL_RAIN_DEFAULT_COLOR_G

#define DIGITAL_RAIN_DEFAULT_COLOR_G 255

#include <digital_rain.h>

Definition at line 136 of file digital_rain.h.

◆ DIGITAL_RAIN_DEFAULT_COLOR_R

#define DIGITAL_RAIN_DEFAULT_COLOR_R 0

#include <digital_rain.h>

Default Matrix green color (R, G, B)

Classic Matrix green: (0, 255, 80)

Definition at line 135 of file digital_rain.h.

◆ DIGITAL_RAIN_DEFAULT_CURSOR_BRIGHTNESS

#define DIGITAL_RAIN_DEFAULT_CURSOR_BRIGHTNESS 2.0f

#include <digital_rain.h>

Cursor brightness multiplier.

How much brighter the cursor should be compared to regular characters.

Definition at line 144 of file digital_rain.h.

◆ DIGITAL_RAIN_DEFAULT_FALL_SPEED

#define DIGITAL_RAIN_DEFAULT_FALL_SPEED 3.0f

#include <digital_rain.h>

Default fall speed for raindrops.

Controls how fast the brightness wave moves down each column. Higher values = faster falling rain.

Definition at line 105 of file digital_rain.h.

◆ DIGITAL_RAIN_DEFAULT_RAINDROP_LENGTH

#define DIGITAL_RAIN_DEFAULT_RAINDROP_LENGTH 12.0f

#include <digital_rain.h>

Default raindrop length.

Controls the length of each raindrop in grid cells. Smaller values = shorter, more frequent raindrops.

Definition at line 113 of file digital_rain.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 179 of file video/rgba/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 193 of file video/rgba/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 166 of file video/rgba/image.h.

◆ LUMA_BLUE

#define LUMA_BLUE 29

#include <common.h>

Luminance blue coefficient (0.114 * 256 = 29)

Definition at line 84 of file video/ascii/common.h.

◆ LUMA_GREEN

#define LUMA_GREEN 150

#include <common.h>

Luminance green coefficient (0.587 * 256 = 150)

Definition at line 82 of file video/ascii/common.h.

◆ LUMA_RED

#define LUMA_RED 77

#include <common.h>

Luminance red coefficient (0.299 * 256 = 77)

Definition at line 80 of file video/ascii/common.h.

◆ LUMA_THRESHOLD

#define LUMA_THRESHOLD 128

#include <common.h>

Luminance threshold for rounding.

Definition at line 86 of file video/ascii/common.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 488 of file ascii.h.

◆ RAMP64_SIZE

#define RAMP64_SIZE 64

#include <common.h>

UTF-8 character palette cache.

Definition at line 462 of file video/ascii/common.h.

Typedef Documentation

◆ utf8_palette_cache_t

typedef struct utf8_palette_cache utf8_palette_cache_t

#include <common.h>

Enumeration Type Documentation

◆ 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 118 of file video/rgba/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 <common.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.

◆ 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);

ansi_compress_rle
char * ansi_compress_rle(const char *input, size_t input_len)
Compress repeated characters using RLE escape sequences.
Definition rle.c:98

frame
int frame
Definition splash.c:99

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);

ansi_expand_rle
char * ansi_expand_rle(const char *input, size_t input_len)
Expand RLE escape sequences in a string.
Definition rle.c:13

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.

◆ apply_color_filter()

int apply_color_filter	(	uint8_t *	pixels,
		uint32_t	width,
		uint32_t	height,
		uint32_t	stride,
		color_filter_t	filter,
		float	time
	)

#include <color_filter.h>

Apply color filter to entire image in-place.

Parameters

pixels	Image pixel buffer (modified in-place)
width	Image width in pixels
height	Image height in pixels
stride	Bytes per row (typically width * 3 for RGB24)
filter	Color filter to apply (COLOR_FILTER_NONE = no-op)
time	Current time in seconds (used for COLOR_FILTER_RAINBOW animation)

Returns: 0 on success, -1 on error (invalid parameters)

Applies the specified color filter to an RGB image. The operation:

Converts each RGB pixel to grayscale (ITU-R BT.601)
Scales grayscale by the filter's RGB color values
Modifies pixels in-place

For "color on white" mode (black-on-white only): Dark pixels get full color, light pixels become white

For "white on color" mode (all other filters): Grayscale value scales the color intensity

For COLOR_FILTER_RAINBOW: Uses time parameter to cycle through RGB spectrum (3.5s period)

Note: This function modifies the image in-place; If filter == COLOR_FILTER_NONE, this is a no-op; Expected stride is typically width * 3 for RGB24 format

Definition at line 274 of file color_filter.c.

                                   {
  if (!pixels || width == 0 || height == 0 || stride == 0) {
    return -1;
  }
 
  if (filter == COLOR_FILTER_NONE) {
    return 0; // No-op for none filter
  }
 
  // Special handling for rainbow filter
  if (filter == COLOR_FILTER_RAINBOW) {
    uint8_t rainbow_r, rainbow_g, rainbow_b;
    color_filter_calculate_rainbow(time, &rainbow_r, &rainbow_g, &rainbow_b);
 
    // Create temporary filter def with current rainbow color
    color_filter_def_t rainbow_filter = {
        .name = "rainbow",
        .cli_name = "rainbow",
        .r = rainbow_r,
        .g = rainbow_g,
        .b = rainbow_b,
        .foreground_on_bg = false,
    };
 
    // Process each pixel with minimum brightness to prevent black
    // Minimum brightness is 70% to ensure rainbow colors stay vibrant even for dark input
    const uint8_t min_brightness = 179; // 70% of 255
 
    for (uint32_t y = 0; y < height; y++) {
      uint8_t *row = pixels + y * stride;
      for (uint32_t x = 0; x < width; x++) {
        uint8_t *pixel = row + x * 3;
        uint8_t r = pixel[0];
        uint8_t g = pixel[1];
        uint8_t b = pixel[2];
        uint8_t gray = rgb_to_grayscale(r, g, b);
 
        // Boost grayscale to maintain minimum brightness for rainbow
        // Formula: adjusted = min + gray * (1 - min/255)
        // This ensures: black pixels -> min_brightness, white pixels -> 255
        uint8_t adjusted_gray = min_brightness + (uint8_t)((gray * (255U - min_brightness)) / 255U);
 
        colorize_grayscale_pixel(adjusted_gray, &rainbow_filter, &pixel[0], &pixel[1], &pixel[2]);
      }
    }
    return 0;
  }
 
  const color_filter_def_t *filter_def = color_filter_get_metadata(filter);
  if (!filter_def) {
    return -1; // Invalid filter
  }
 
  // Process each pixel in the image
  for (uint32_t y = 0; y < height; y++) {
    uint8_t *row = pixels + y * stride;
    for (uint32_t x = 0; x < width; x++) {
      uint8_t *pixel = row + x * 3; // Assume RGB24 (3 bytes per pixel)
      uint8_t r = pixel[0];
      uint8_t g = pixel[1];
      uint8_t b = pixel[2];
 
      // Convert RGB to grayscale using ITU-R BT.601
      uint8_t gray = rgb_to_grayscale(r, g, b);
 
      // Colorize the grayscale value
      colorize_grayscale_pixel(gray, filter_def, &pixel[0], &pixel[1], &pixel[2]);
    }
  }
 
  return 0;
}

References color_filter_calculate_rainbow(), color_filter_get_metadata(), COLOR_FILTER_NONE, COLOR_FILTER_RAINBOW, and color_filter_def_t::name.

Referenced by ascii_convert_with_capabilities(), mirror_convert_frame(), and session_display_convert_to_ascii().

◆ 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 111 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
    if (GET_OPTION(render_mode) == RENDER_MODE_HALF_BLOCK) {
      const uint8_t *rgb_data = (const uint8_t *)resized->pixels;
#if SIMD_SUPPORT_NEON
      // Use NEON half-block renderer (optimized SIMD path)
      log_dev("Using NEON halfblock renderer");
      ascii = rgb_to_truecolor_halfblocks_neon(rgb_data, resized->w, resized->h, 0);
#else
      // Fallback to scalar halfblock renderer (works on all platforms)
      log_dev("Using scalar halfblock renderer (NEON not available)");
      ascii = rgb_to_truecolor_halfblocks_scalar(rgb_data, resized->w, resized->h, 0);
#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
      if (GET_OPTION(render_mode) == RENDER_MODE_BACKGROUND) {
        ascii = image_print_color_background(resized, palette_chars);
      } else {
        ascii = image_print_color_utf8(resized, palette_chars);
      }
#endif
    }
  } else {
    // Use grayscale/monochrome conversion with client's palette
    ascii = image_print(resized, palette_chars);
  }
 
  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_background(), image_print_color_simd(), image_print_color_utf8(), image_resize(), log_dev, log_error, image_t::pixels, RENDER_MODE_BACKGROUND, RENDER_MODE_HALF_BLOCK, rgb_to_truecolor_halfblocks_scalar(), SAFE_FREE, and image_t::w.

◆ 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
	)

#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 233 of file ascii.c.

                                                                                     {
 
  if (original == NULL || caps == NULL) {
    log_error("Invalid parameters for ascii_convert_with_capabilities");
    return NULL;
  }
 
  // Validate original image dimensions to detect corruption
  if (original->w <= 0 || original->w > 10000 || original->h <= 0 || original->h > 10000) {
    log_error("Invalid original image dimensions detected: w=%d, h=%d (likely corrupted)", original->w, original->h);
    return NULL;
  }
 
  if (original->pixels == NULL) {
    log_error("Original image pixels pointer is NULL");
    return NULL;
  }
 
  // Start with the target dimensions requested by the user.
  ssize_t resized_width = width;
  ssize_t resized_height = height;
 
  // Preserve aspect ratio by cropping the source to cover the viewport. The
  // destination dimensions remain the full requested viewport dimensions.
 
  // Half-block mode doubles height for 2x vertical resolution (AFTER aspect ratio)
  if (caps->render_mode == RENDER_MODE_HALF_BLOCK) {
    resized_height = resized_height * 2;
  }
 
  // Cover rendering fills the viewport, so no aspect-ratio padding is needed.
  size_t pad_width = 0;
  size_t pad_height = 0;
 
  // Resize the captured frame to the aspect-correct dimensions
  if (resized_width <= 0 || resized_height <= 0) {
    log_error("Invalid dimensions for resize: width=%zd, height=%zd", resized_width, resized_height);
    return NULL;
  }
 
  // Validate dimensions fit in image_t's int fields before casting
  if (resized_width > INT_MAX || resized_height > INT_MAX) {
    log_error("Dimensions exceed INT_MAX: width=%zd, height=%zd", resized_width, resized_height);
    return NULL;
  }
 
  // PROFILING: Time image allocation and resize
  START_TIMER("image_alloc");
  uint64_t prof_alloc_start_ns = time_get_ns();
 
  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);
 
  uint64_t prof_alloc_end_ns = time_get_ns();
  STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 5 * NS_PER_MS_INT, "image_alloc",
                           "IMAGE_ALLOC: Alloc+clear complete (%.2f ms)");
 
  START_TIMER("image_resize");
  uint64_t prof_resize_start_ns = prof_alloc_end_ns;
 
  if (use_aspect_ratio && !stretch) {
    image_resize_cover(original, resized, resized_width, resized_height);
  } else {
    image_resize(original, resized);
  }
 
  uint64_t prof_resize_end_ns = time_get_ns();
  STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 5 * NS_PER_MS_INT, "image_resize",
                           "IMAGE_RESIZE: Resize complete (%.2f ms)");
 
  // Check original image before resize (validate dimensions to prevent integer overflow)
  int orig_black = 0, orig_total = 0;
  if (original->w > 0 && original->w <= 10000 && original->h > 0 && original->h <= 10000) {
    int64_t total_pixels = (int64_t)original->w * original->h;
    int sample_size = (total_pixels < 1000) ? (int)total_pixels : 1000;
    for (int i = 0; i < sample_size; i++) {
      rgb_pixel_t p = original->pixels[i];
      orig_total++;
      if (p.r == 0 && p.g == 0 && p.b == 0)
        orig_black++;
    }
    log_debug_every(5 * NS_PER_SEC_INT,
                    ">>> ORIGINAL image: %d/%d pixels are black (%.1f%%), first pixel=RGB(%d,%d,%d)\n", orig_black,
                    orig_total, orig_total > 0 ? 100.0 * orig_black / orig_total : 0, original->pixels[0].r,
                    original->pixels[0].g, original->pixels[0].b);
  } else {
    log_warn("Skipping debug check: corrupted image dimensions (w=%d, h=%d)", original->w, original->h);
  }
 
  // PROFILING: Time ASCII print
  uint64_t prof_print_start_ns = prof_resize_end_ns;
 
  // DEBUG: Log dimensions going to renderer
  log_debug_every(10 * US_PER_SEC_INT,
                  "ascii_convert: original=%dx%d, requested=%zdx%zd, resized=%dx%d, pad=%zux%zu (mode=%d)", original->w,
                  original->h, width, height, resized->w, resized->h, pad_width, pad_height, caps->render_mode);
 
  // Check if image is all black
  int black_pixels = 0, total_pixels = 0;
  for (int i = 0; i < resized->w * resized->h && i < 1000; i++) {
    rgb_pixel_t p = resized->pixels[i];
    total_pixels++;
    if (p.r == 0 && p.g == 0 && p.b == 0)
      black_pixels++;
  }
  log_debug_every(5 * NS_PER_SEC_INT,
                  ">>> Resized image check: %d/%d pixels are black (%.1f%%), first pixel=RGB(%d,%d,%d)\n", black_pixels,
                  total_pixels, total_pixels > 0 ? 100.0 * black_pixels / total_pixels : 0, resized->pixels[0].r,
                  resized->pixels[0].g, resized->pixels[0].b);
 
  // Apply the target client's filter after resizing, so it is scoped to this
  // client and never mutates the shared source frame.
  if (caps->color_filter != COLOR_FILTER_NONE) {
    const float time_seconds = (float)time_get_ns() / (float)NS_PER_SEC_INT;
    if (apply_color_filter((uint8_t *)resized->pixels, (uint32_t)resized->w, (uint32_t)resized->h,
                           (uint32_t)(resized->w * sizeof(rgb_pixel_t)), caps->color_filter, time_seconds) != 0) {
      log_warn("Failed to apply client color filter %d", caps->color_filter);
    }
  }
 
  // Use the capability-aware image printing function with client's palette
  START_TIMER("image_print_with_capabilities");
  char *ascii = image_print_with_capabilities(resized, caps, palette_chars);
 
  uint64_t prof_print_end_ns = time_get_ns();
  STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 5 * NS_PER_MS_INT, "image_print_with_capabilities",
                           "IMAGE_PRINT: Print complete (%.2f ms)");
 
  uint64_t alloc_time_us = time_ns_to_us(time_elapsed_ns(prof_alloc_start_ns, prof_alloc_end_ns));
  uint64_t resize_time_us = time_ns_to_us(time_elapsed_ns(prof_resize_start_ns, prof_resize_end_ns));
  uint64_t print_time_us = time_ns_to_us(time_elapsed_ns(prof_print_start_ns, prof_print_end_ns));
 
  // PROFILING: Time padding
  START_TIMER("ascii_padding");
  uint64_t prof_pad_start_ns = time_get_ns();
 
  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);
 
  uint64_t prof_pad_end_ns = time_get_ns();
  STOP_TIMER_AND_LOG_EVERY(dev, 3 * NS_PER_SEC_INT, 2 * NS_PER_MS_INT, "ascii_padding",
                           "ASCII_PADDING: Padding complete (%.2f ms)");
 
  uint64_t pad_time_ns = time_elapsed_ns(prof_pad_start_ns, prof_pad_end_ns);
  char alloc_str[32], resize_str[32], print_str[32], pad_str[32], total_str[32];
  time_pretty(alloc_time_us * 1000, -1, alloc_str, sizeof(alloc_str));
  time_pretty(resize_time_us * 1000, -1, resize_str, sizeof(resize_str));
  time_pretty(print_time_us * 1000, -1, print_str, sizeof(print_str));
  time_pretty(pad_time_ns, -1, pad_str, sizeof(pad_str));
  uint64_t total_time_ns = (alloc_time_us + resize_time_us + print_time_us) * 1000 + pad_time_ns;
  time_pretty(total_time_ns, -1, total_str, sizeof(total_str));
  log_dev("ASCII_BREAKDOWN: alloc=%s, resize=%s, print=%s, pad=%s (total=%s)", alloc_str, resize_str, print_str,
          pad_str, total_str);
 
  image_destroy(resized);
 
  return ascii_padded;
}

References apply_color_filter(), ascii_pad_frame_height(), ascii_pad_frame_width(), rgb_pixel_t::b, terminal_capabilities_t::color_filter, COLOR_FILTER_NONE, rgb_pixel_t::g, image_t::h, image_clear(), image_destroy(), image_new(), image_print_with_capabilities(), image_resize(), log_debug_every, log_dev, log_error, log_warn, NS_PER_MS_INT, NS_PER_SEC_INT, image_t::pixels, rgb_pixel_t::r, terminal_capabilities_t::render_mode, RENDER_MODE_HALF_BLOCK, SAFE_FREE, START_TIMER, STOP_TIMER_AND_LOG_EVERY, time_elapsed_ns(), time_get_ns(), time_pretty(), US_PER_SEC_INT, and image_t::w.

Referenced by mirror_convert_frame(), and session_display_convert_to_ascii().

◆ 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);

}

ascii_write
asciichat_error_t ascii_write(const char *frame)
Write ASCII frame to terminal.
Definition ascii.c:420

ascii_create_grid
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.
Definition ascii.c:625

ascii_frame_source_t
Frame source structure for grid layout.
Definition ascii.h:325

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 625 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 visual width of the line (excluding ANSI escape sequences)
      int visual_line_width = ansi_visual_width(&src_data[line_start], line_len);
 
      // Calculate horizontal padding to center the line based on visual width
      int h_padding = (width - visual_line_width) / 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 max_visual_width = width - h_padding;
      // Truncate to visual width while preserving complete ANSI sequences
      int copy_len = ansi_truncate_to_visual_width(&src_data[line_start], line_len, max_visual_width);
 
      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)
      // Truncate to visual cell width while preserving complete ANSI sequences
      int copy_len = ansi_truncate_to_visual_width(src_data + line_start, line_len, cell_width);
      // Check that visual width of truncated line fits
      int truncated_visual_width = ansi_visual_width(src_data + line_start, copy_len);
      if (copy_len > 0 && start_col + truncated_visual_width <= 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.

NOTE: Uses plain newlines instead of ANSI escape sequences to support both TTY and piped/redirected output. TTY flicker prevention is handled by the display layer (e.g., display.c) when appropriate.

Definition at line 925 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
  // Each padding row needs: 1 newline character per padding row
  size_t frame_len = strlen(frame);
  size_t top_padding_len = pad_top; // 1 newline per padding row
  size_t total_len = top_padding_len + frame_len;
 
  char *buffer;
  buffer = SAFE_MALLOC(total_len + 1, char *);
 
  char *position = buffer;
 
  // Add top padding with plain newlines
  // Use plain newlines instead of ANSI escape sequences so the output works
  // when redirected to pipes or files, not just TTY
  for (size_t i = 0; i < pad_top; i++) {
    *position++ = '\n';
  }
 
  // Copy the original frame
  size_t remaining = frame_len + 1;
  SAFE_MEMCPY(position, remaining, frame, frame_len);
  position += frame_len;
  *position = '\0';
 
  return buffer;
}

References frame, 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 480 of file ascii.c.

                                                                {
  if (!frame) {
    SET_ERRNO(ERROR_INVALID_PARAM, "ascii_pad_frame_width: frame is NULL");
    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 ERROR_INVALID_PARAM, frame, SAFE_MALLOC, SAFE_MEMCPY, SAFE_MEMSET, and SET_ERRNO.

Referenced by ascii_convert(), and ascii_convert_with_capabilities().

◆ ascii_simd_init()

void ascii_simd_init ( void )

#include <common.h>

Initialize SIMD subsystem.

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

Definition at line 601 of file video/ascii/common.c.

                           {
  init_dec3();
  init_default_luminance_palette();
}

References init_dec3(), and init_default_luminance_palette().

Referenced by ansi_fast_init(), server_main(), and session_host_start_render().

◆ 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 420 of file ascii.c.

                                                 {
  if (frame == NULL) {
    log_warn("Attempted to write NULL frame");
    return ERROR_INVALID_PARAM;
  }
 
  // Only reset cursor if output is connected to a TTY (not piped/redirected)
  if (terminal_should_use_control_sequences(STDOUT_FILENO)) {
    cursor_reset(STDOUT_FILENO);
  }
 
  size_t frame_len = strlen(frame);
  // Write all frame data with automatic retry on transient errors
  platform_write_all(STDOUT_FILENO, frame, frame_len);
 
  // Flush C stdio buffer and terminal to ensure piped output is written immediately
  (void)fflush(stdout);
  terminal_flush(STDOUT_FILENO);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, cursor_reset, ERROR_INVALID_PARAM, frame, log_warn, platform_write_all(), terminal_flush(), and terminal_should_use_control_sequences().

◆ 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 442 of file ascii.c.

                                                      {
#if PLATFORM_WINDOWS
  (void)fd; // Unused on Windows - terminal operations use stdout directly
#endif
  // console_clear(fd);
  // cursor_reset(fd);
  // Only restore terminal state if:
  // 1. reset_terminal is true (caller wants terminal restore)
  // 2. terminal_should_use_control_sequences() confirms it's safe (TTY, not snapshot, not testing)
  if (reset_terminal && terminal_should_use_control_sequences(fd)) {
    // Show cursor using platform abstraction
    if (terminal_cursor_show() != 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 log_debug, log_warn, terminal_cursor_show(), terminal_set_echo(), and terminal_should_use_control_sequences().

Referenced by session_display_destroy().

◆ 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 83 of file ascii.c.

                                                                {
  // Validate file descriptor
  if (fd < 0) {
    log_error("Invalid file descriptor %d", fd);
    return ERROR_INVALID_PARAM;
  }
 
  // Only apply terminal control sequences if:
  // 1. reset_terminal is true (caller wants terminal reset)
  // 2. terminal_should_use_control_sequences() confirms it's safe (TTY, not snapshot, not testing)
  if (reset_terminal && terminal_should_use_control_sequences(fd)) {
    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_cursor_hide() != 0) {
      log_warn("Failed to hide cursor");
    }
  }
  log_dev("ASCII writer initialized");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, console_clear, cursor_reset, ERROR_INVALID_PARAM, ERROR_TERMINAL, log_dev, log_error, log_warn, terminal_cursor_hide(), terminal_set_echo(), and terminal_should_use_control_sequences().

Referenced by session_display_create().

◆ benchmark_simd_color_conversion()

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

#include <common.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

◆ 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 <common.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 <common.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 <common.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

◆ 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 for all 256 levels.

Definition at line 380 of file video/ascii/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.

Referenced by get_utf8_palette_cache().

◆ build_utf8_ramp64_cache()

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

#include <common.h>

Build UTF-8 ramp64 cache and character index ramp.

Definition at line 433 of file video/ascii/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.

Referenced by get_utf8_palette_cache().

◆ color_filter_calculate_rainbow()

void color_filter_calculate_rainbow	(	float	time,
		uint8_t *	r,
		uint8_t *	g,
		uint8_t *	b
	)

#include <color_filter.h>

Calculate rainbow color from time (3.5s cycle)

Parameters

time	Current time in seconds
r	Output red component (0-255)
g	Output green component (0-255)
b	Output blue component (0-255)

Centralized rainbow color calculation used by both –matrix and –color-filter rainbow. Cycles through full RGB spectrum over 3.5 seconds.

Calculate rainbow color from time Cycles through full spectrum over 3.5 seconds This is the centralized rainbow implementation used by both matrix and color filter

Definition at line 169 of file color_filter.c.

                                                                                    {
  // Cycle period: 3.5 seconds
  const float cycle_period = 3.5f;
 
  // Normalize time to [0, 1] range within cycle
  float phase = fmodf(time, cycle_period) / cycle_period;
 
  // Convert to hue angle [0, 360)
  float hue = phase * 360.0f;
 
  // HSV to RGB conversion (S=1, V=1 for full saturation and brightness)
  // Hue divided into 6 segments
  float h = hue / 60.0f;
  int i = (int)floorf(h);
  float f = h - (float)i;
 
  // Calculate RGB based on hue segment
  float q = 1.0f - f;
  float t = f;
 
  switch (i % 6) {
  case 0:
    *r = 255;
    *g = (uint8_t)(t * 255.0f + 0.5f);
    *b = 0;
    break; // Red to Yellow
  case 1:
    *r = (uint8_t)(q * 255.0f + 0.5f);
    *g = 255;
    *b = 0;
    break; // Yellow to Green
  case 2:
    *r = 0;
    *g = 255;
    *b = (uint8_t)(t * 255.0f + 0.5f);
    break; // Green to Cyan
  case 3:
    *r = 0;
    *g = (uint8_t)(q * 255.0f + 0.5f);
    *b = 255;
    break; // Cyan to Blue
  case 4:
    *r = (uint8_t)(t * 255.0f + 0.5f);
    *g = 0;
    *b = 255;
    break; // Blue to Magenta
  case 5:
    *r = 255;
    *g = 0;
    *b = (uint8_t)(q * 255.0f + 0.5f);
    break; // Magenta to Red
  default:
    *r = 255;
    *g = 0;
    *b = 0;
    break; // Fallback to red
  }
 
  // Ensure minimum perceived brightness by boosting luminance
  // Pure blue (0,0,255) has luminance ~18, which appears very dark
  // We need minimum luminance of ~120 for bright, vibrant colors
  const float min_luminance = 120.0f;
 
  // Calculate current luminance using ITU-R BT.709 coefficients
  float luminance = 0.2126f * *r + 0.7152f * *g + 0.0722f * *b;
 
  if (luminance < min_luminance) {
    // Boost luminance by adding white (increasing all channels proportionally)
    // This desaturates the color but makes it much brighter
    float boost = (min_luminance - luminance) / 3.0f;
    *r = (uint8_t)fminf(255.0f, *r + boost);
    *g = (uint8_t)fminf(255.0f, *g + boost);
    *b = (uint8_t)fminf(255.0f, *b + boost);
  }
}

Referenced by apply_color_filter(), digital_rain_apply(), and rainbow_replace_ansi_colors().

◆ color_filter_from_cli_name()

color_filter_t color_filter_from_cli_name ( const char * cli_name )

#include <color_filter.h>

Convert color filter CLI name to enum value.

Parameters

cli_name CLI argument name (e.g., "matrix-green")

Returns: Filter enum value, or COLOR_FILTER_NONE if not found

Converts a CLI argument name (like "matrix-green") to the corresponding color_filter_t enum value.

Note: CLI names are case-insensitive; Returns COLOR_FILTER_NONE for unknown filter names

Definition at line 150 of file color_filter.c.

                                                                {
  if (!cli_name) {
    return COLOR_FILTER_NONE;
  }
 
  for (int i = 0; i < COLOR_FILTER_COUNT; i++) {
    if (platform_strcasecmp(color_filter_registry[i].cli_name, cli_name) == 0) {
      return (color_filter_t)i;
    }
  }
 
  return COLOR_FILTER_NONE;
}

References COLOR_FILTER_COUNT, COLOR_FILTER_NONE, and platform_strcasecmp().

Referenced by parse_color_filter().

◆ color_filter_get_metadata()

const color_filter_def_t * color_filter_get_metadata ( color_filter_t filter )

#include <color_filter.h>

Get color filter metadata by enum value.

Parameters

filter Filter enum value (color_filter_t)

Returns: Pointer to filter metadata, or NULL if invalid filter

Returns the metadata definition for a color filter including its name, RGB values, and rendering mode.

Note: The returned pointer is statically allocated and valid for program lifetime; Returns NULL for COLOR_FILTER_NONE

Definition at line 143 of file color_filter.c.

                                                                           {
  if (filter <= COLOR_FILTER_NONE || filter >= COLOR_FILTER_COUNT) {
    return NULL;
  }
  return &color_filter_registry[filter];
}

References COLOR_FILTER_COUNT.

Referenced by apply_color_filter(), and digital_rain_set_color_from_filter().

◆ convert_pixels_scalar()

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

#include <common.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

◆ convert_pixels_scalar_with_newlines()

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

#include <common.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

◆ digital_rain_apply()

char * digital_rain_apply	(	digital_rain_t *	rain,
		const char *	frame,
		float	delta_time
	)

#include <digital_rain.h>

Apply digital rain effect to ASCII frame.

Parameters

rain	Digital rain context (must not be NULL)
frame	Input ASCII frame (must not be NULL, must be null-terminated)
delta_time	Time elapsed since last frame in seconds

Returns: Allocated frame with digital rain effect applied, or NULL on error

Applies the digital rain effect to an ASCII frame by analyzing character positions and injecting ANSI color codes to modulate brightness. The effect:

Parses the frame to identify grid positions
Calculates per-cell brightness using sawtooth wave pattern
Detects cursor positions (brightness increases)
Injects ANSI color codes to darken/brighten characters
Returns new frame with effect applied

FRAME FORMAT:

Input can be plain ASCII or contain existing ANSI codes
Output contains ANSI color codes for brightness modulation
Frame dimensions must match num_columns x num_rows
Newlines are preserved in output

Note: Caller must free returned frame string; Input frame is not modified; Works with both color and monochrome frames; Preserves existing ANSI codes (may override colors)

Definition at line 369 of file digital_rain.c.

                                                                                    {
  if (!rain || !frame) {
    log_error("digital_rain_apply: NULL parameter");
    return NULL;
  }
 
  // Update time
  rain->time += delta_time * rain->animation_speed;
  float sim_time = rain->time;
 
  // Update rainbow color if rainbow mode is enabled
  if (rain->rainbow_mode) {
    color_filter_calculate_rainbow(sim_time, &rain->color_r, &rain->color_g, &rain->color_b);
  }
 
  // Allocate output buffer (input size + overhead for ANSI codes)
  // Estimate: each character might need up to 20 bytes for ANSI codes
  size_t input_len = strlen(frame);
  size_t output_capacity = input_len * 20 + 1024;
  char *output = SAFE_MALLOC(output_capacity, char *);
  if (!output) {
    log_error("digital_rain_apply: failed to allocate output buffer");
    return NULL;
  }
 
  const char *src = frame;
  char *dst = output;
  size_t remaining = output_capacity;
 
  int col = 0;
  int row = 0;
 
  while (*src && remaining > 100) {
    // Try to parse and modify ANSI color sequences
    if (*src == '\033') {
      int r, g, b;
      bool is_foreground;
      const char *after = parse_ansi_color(src, &r, &g, &b, &is_foreground);
 
      if (after) {
        // Found a color sequence - calculate brightness for this position
        float brightness = get_rain_brightness(rain, col, row, sim_time);
        float brightness_below = get_rain_brightness(rain, col, row + 1, sim_time);
        bool is_cursor = brightness > brightness_below;
 
        // Blend with previous brightness for smooth transitions
        if (!rain->first_frame && row < rain->num_rows && col < rain->num_columns) {
          size_t idx = (size_t)row * (size_t)rain->num_columns + (size_t)col;
          float prev_brightness = rain->previous_brightness[idx];
          brightness = prev_brightness + (brightness - prev_brightness) * rain->brightness_decay;
          rain->previous_brightness[idx] = brightness;
        } else if (row < rain->num_rows && col < rain->num_columns) {
          size_t idx = (size_t)row * (size_t)rain->num_columns + (size_t)col;
          rain->previous_brightness[idx] = brightness;
        }
 
        // Generate modulated color
        char ansi_buf[32];
        int ansi_len =
            generate_modulated_color(ansi_buf, sizeof(ansi_buf), r, g, b, brightness, is_foreground, is_cursor);
 
        if ((size_t)ansi_len < remaining) {
          memcpy(dst, ansi_buf, (size_t)ansi_len);
          dst += ansi_len;
          remaining -= (size_t)ansi_len;
        }
 
        src = after;
        continue;
      } else {
        // Not a color sequence - copy as-is
        const char *after_skip = skip_ansi_sequence(src);
        size_t ansi_len = (size_t)(after_skip - src);
        if (ansi_len < remaining) {
          memcpy(dst, src, ansi_len);
          dst += ansi_len;
          remaining -= ansi_len;
          src = after_skip;
        } else {
          break;
        }
        continue;
      }
    }
 
    // Handle newline
    if (*src == '\n') {
      *dst++ = *src++;
      remaining--;
      row++;
      col = 0;
      continue;
    }
 
    // Copy regular characters - inject color for non-colored characters
    if (remaining > 0) {
      // Calculate brightness for this position
      float brightness = get_rain_brightness(rain, col, row, sim_time);
      float brightness_below = get_rain_brightness(rain, col, row + 1, sim_time);
      bool is_cursor = brightness > brightness_below;
 
      // Blend with previous brightness
      if (!rain->first_frame && row < rain->num_rows && col < rain->num_columns) {
        size_t idx = (size_t)row * (size_t)rain->num_columns + (size_t)col;
        float prev_brightness = rain->previous_brightness[idx];
        brightness = prev_brightness + (brightness - prev_brightness) * rain->brightness_decay;
        rain->previous_brightness[idx] = brightness;
      } else if (row < rain->num_rows && col < rain->num_columns) {
        size_t idx = (size_t)row * (size_t)rain->num_columns + (size_t)col;
        rain->previous_brightness[idx] = brightness;
      }
 
      // For characters without explicit color codes, use the rain's default color
      char ansi_buf[32];
      int ansi_len = generate_modulated_color(ansi_buf, sizeof(ansi_buf), rain->color_r, rain->color_g, rain->color_b,
                                              brightness, true, is_cursor);
 
      if ((size_t)ansi_len < remaining) {
        memcpy(dst, ansi_buf, (size_t)ansi_len);
        dst += ansi_len;
        remaining -= (size_t)ansi_len;
      }
 
      // Decode UTF-8 character to get byte length
      uint32_t codepoint;
      int utf8_len = utf8_decode((const uint8_t *)src, &codepoint);
      if (utf8_len < 0) {
        // Invalid UTF-8, treat as single byte
        utf8_len = 1;
      }
 
      // Copy all bytes of the UTF-8 character
      for (int i = 0; i < utf8_len && *src && remaining > 0; i++) {
        *dst++ = *src++;
        remaining--;
      }
 
      // Only increment column once per character (not per byte)
      col++;
    } else {
      break;
    }
  }
 
  // Null-terminate
  if (remaining > 0) {
    *dst = '\0';
  } else {
    output[output_capacity - 1] = '\0';
  }
 
  rain->first_frame = false;
  return output;
}

References digital_rain_t::animation_speed, digital_rain_t::brightness_decay, digital_rain_t::color_b, color_filter_calculate_rainbow(), digital_rain_t::color_g, digital_rain_t::color_r, digital_rain_t::first_frame, frame, log_error, digital_rain_t::num_columns, digital_rain_t::previous_brightness, digital_rain_t::rainbow_mode, SAFE_MALLOC, digital_rain_t::time, and utf8_decode().

Referenced by mirror_convert_frame(), session_display_convert_to_ascii(), and session_display_write_ascii().

◆ digital_rain_destroy()

void digital_rain_destroy ( digital_rain_t * rain )

#include <digital_rain.h>

Destroy digital rain effect context.

Parameters

rain	Digital rain context to destroy (can be NULL)

Frees all resources associated with the digital rain context. Safe to call with NULL pointer.

Definition at line 154 of file digital_rain.c.

                                                {
  if (!rain) {
    return;
  }
 
  SAFE_FREE(rain->columns);
  SAFE_FREE(rain->previous_brightness);
  SAFE_FREE(rain);
}

References digital_rain_t::columns, digital_rain_t::previous_brightness, and SAFE_FREE.

Referenced by cleanup_client_media_buffers(), mirror_cleanup(), mirror_convert_frame(), session_display_convert_to_ascii(), and session_display_destroy().

◆ digital_rain_init()

digital_rain_t * digital_rain_init	(	int	num_columns,
		int	num_rows
	)

#include <digital_rain.h>

Initialize digital rain effect context.

Parameters

num_columns	Number of columns in the ASCII grid
num_rows	Number of rows in the ASCII grid

Returns: Allocated digital rain context, or NULL on error

Creates and initializes a digital rain effect context for the specified grid dimensions. Allocates per-column state and initializes random offsets.

Note: Caller must call digital_rain_destroy() to free resources; Returns NULL on memory allocation failure

Definition at line 96 of file digital_rain.c.

                                                                 {
  if (num_columns <= 0 || num_rows <= 0) {
    log_error("digital_rain_init: invalid dimensions %dx%d", num_columns, num_rows);
    return NULL;
  }
 
  digital_rain_t *rain = SAFE_CALLOC(1, sizeof(digital_rain_t), digital_rain_t *);
  if (!rain) {
    log_error("digital_rain_init: failed to allocate context");
    return NULL;
  }
 
  rain->num_columns = num_columns;
  rain->num_rows = num_rows;
 
  // Allocate column state array
  rain->columns = SAFE_CALLOC((size_t)num_columns, sizeof(digital_rain_column_t), digital_rain_column_t *);
  if (!rain->columns) {
    log_error("digital_rain_init: failed to allocate column array");
    SAFE_FREE(rain);
    return NULL;
  }
 
  // Allocate previous brightness array
  size_t grid_size = (size_t)num_columns * (size_t)num_rows;
  rain->previous_brightness = SAFE_CALLOC(grid_size, sizeof(float), float *);
  if (!rain->previous_brightness) {
    log_error("digital_rain_init: failed to allocate brightness array");
    SAFE_FREE(rain->columns);
    SAFE_FREE(rain);
    return NULL;
  }
 
  // Initialize per-column random offsets
  for (int col = 0; col < num_columns; col++) {
    digital_rain_column_t *column = &rain->columns[col];
    column->time_offset = random_float((float)col, 0.0f) * 1000.0f;
    column->speed_multiplier = random_float((float)col + 0.1f, 0.0f) * 0.5f + 0.5f;
    column->phase_offset = random_float((float)col + 0.2f, 0.0f) * (float)M_PI * 2.0f;
  }
 
  // Set default parameters
  rain->fall_speed = DIGITAL_RAIN_DEFAULT_FALL_SPEED;
  rain->raindrop_length = DIGITAL_RAIN_DEFAULT_RAINDROP_LENGTH;
  rain->brightness_decay = DIGITAL_RAIN_DEFAULT_BRIGHTNESS_DECAY;
  rain->animation_speed = DIGITAL_RAIN_DEFAULT_ANIMATION_SPEED;
  rain->color_r = DIGITAL_RAIN_DEFAULT_COLOR_R;
  rain->color_g = DIGITAL_RAIN_DEFAULT_COLOR_G;
  rain->color_b = DIGITAL_RAIN_DEFAULT_COLOR_B;
  rain->cursor_brightness = DIGITAL_RAIN_DEFAULT_CURSOR_BRIGHTNESS;
  rain->rainbow_mode = false;
  rain->first_frame = true;
  rain->time = 0.0f;
 
  log_info("Digital rain initialized: %dx%d grid", num_columns, num_rows);
  return rain;
}

Referenced by mirror_convert_frame(), session_display_convert_to_ascii(), and session_display_create().

◆ digital_rain_reset()

void digital_rain_reset ( digital_rain_t * rain )

#include <digital_rain.h>

Reset digital rain effect state.

Parameters

rain	Digital rain context (must not be NULL)

Resets the digital rain effect to its initial state, clearing all timing and brightness history. Useful when switching frames or restarting the effect.

Definition at line 164 of file digital_rain.c.

                                              {
  if (!rain) {
    return;
  }
 
  rain->time = 0.0f;
  rain->first_frame = true;
 
  // Clear previous brightness
  size_t grid_size = (size_t)rain->num_columns * (size_t)rain->num_rows;
  memset(rain->previous_brightness, 0, grid_size * sizeof(float));
}

References digital_rain_t::first_frame, digital_rain_t::num_columns, digital_rain_t::num_rows, digital_rain_t::previous_brightness, and digital_rain_t::time.

◆ digital_rain_set_color()

void digital_rain_set_color	(	digital_rain_t *	rain,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

#include <digital_rain.h>

Set digital rain color.

Parameters

rain	Digital rain context (must not be NULL)
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Definition at line 193 of file digital_rain.c.

                                                                                   {
  if (rain) {
    rain->color_r = r;
    rain->color_g = g;
    rain->color_b = b;
  }
}

References digital_rain_t::color_b, digital_rain_t::color_g, and digital_rain_t::color_r.

Referenced by digital_rain_set_color_from_filter().

◆ digital_rain_set_color_from_filter()

void digital_rain_set_color_from_filter	(	digital_rain_t *	rain,
		color_filter_t	filter
	)

#include <digital_rain.h>

Set digital rain color from color filter.

Parameters

rain	Digital rain context (must not be NULL)
filter	Color filter to use for rain color

Automatically sets the rain color based on the active color filter. If filter is COLOR_FILTER_NONE, uses default Matrix green.

Definition at line 201 of file digital_rain.c.

                                                                                     {
  if (!rain) {
    return;
  }
 
  // If no filter is set, use default Matrix green
  if (filter == COLOR_FILTER_NONE) {
    rain->rainbow_mode = false;
    digital_rain_set_color(rain, DIGITAL_RAIN_DEFAULT_COLOR_R, DIGITAL_RAIN_DEFAULT_COLOR_G,
                           DIGITAL_RAIN_DEFAULT_COLOR_B);
    return;
  }
 
  // Rainbow mode: enable dynamic color cycling
  if (filter == COLOR_FILTER_RAINBOW) {
    rain->rainbow_mode = true;
    // Set initial color to red (will be overridden during rendering)
    digital_rain_set_color(rain, 255, 0, 0);
    return;
  }
 
  // Get color from filter metadata
  rain->rainbow_mode = false;
  const color_filter_def_t *filter_def = color_filter_get_metadata(filter);
  if (filter_def) {
    digital_rain_set_color(rain, filter_def->r, filter_def->g, filter_def->b);
  }
}

References color_filter_def_t::b, color_filter_get_metadata(), COLOR_FILTER_NONE, COLOR_FILTER_RAINBOW, DIGITAL_RAIN_DEFAULT_COLOR_B, DIGITAL_RAIN_DEFAULT_COLOR_G, DIGITAL_RAIN_DEFAULT_COLOR_R, digital_rain_set_color(), color_filter_def_t::g, color_filter_def_t::r, and digital_rain_t::rainbow_mode.

Referenced by mirror_convert_frame(), session_display_convert_to_ascii(), session_display_create(), and session_display_write_ascii().

◆ digital_rain_set_fall_speed()

void digital_rain_set_fall_speed	(	digital_rain_t *	rain,
		float	speed
	)

#include <digital_rain.h>

Set digital rain fall speed.

Parameters

rain	Digital rain context (must not be NULL)
speed	Fall speed multiplier (suggested range: 0.1 to 5.0)

Definition at line 181 of file digital_rain.c.

                                                                    {
  if (rain) {
    rain->fall_speed = speed;
  }
}

References digital_rain_t::fall_speed.

◆ digital_rain_set_raindrop_length()

void digital_rain_set_raindrop_length	(	digital_rain_t *	rain,
		float	length
	)

#include <digital_rain.h>

Set digital rain raindrop length.

Parameters

rain	Digital rain context (must not be NULL)
length	Raindrop length in cells (suggested range: 5.0 to 50.0)

Definition at line 187 of file digital_rain.c.

                                                                          {
  if (rain) {
    rain->raindrop_length = length;
  }
}

References digital_rain_t::raindrop_length.

◆ 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 156 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(), image_print(), rgb_to_16color_halfblocks_scalar(), rgb_to_256color_halfblocks_scalar(), rgb_to_halfblocks_scalar(), and rgb_to_truecolor_halfblocks_scalar().

◆ 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 138 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().

Referenced by rgb_to_16color_halfblocks_scalar(), rgb_to_256color_halfblocks_scalar(), and rgb_to_truecolor_halfblocks_scalar().

◆ 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 177 of file output_buffer.c.

                                                            {
  if (!ob)
    return;
  // Use pre-cached color sequence instead of building on-demand
  uint8_t seq_len;
  const char *seq = get_sgr256_bg_string(color_idx, &seq_len);
  ob_write(ob, seq, seq_len);
}

References get_sgr256_bg_string(), 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 167 of file output_buffer.c.

                                                            {
  if (!ob)
    return;
  // Use pre-cached color sequence instead of building on-demand
  uint8_t seq_len;
  const char *seq = get_sgr256_fg_string(color_idx, &seq_len);
  ob_write(ob, seq, seq_len);
}

References get_sgr256_fg_string(), 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 201 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().

Referenced by rgb_to_truecolor_halfblocks_scalar().

◆ 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 186 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().

Referenced by rgb_to_truecolor_halfblocks_scalar().

◆ 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 123 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 107 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_256_color_fast_path()

bool get_256_color_fast_path ( void )

#include <common.h>

Get 256-color fast path setting.

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

◆ 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_bg_string()

char * get_sgr256_bg_string	(	uint8_t	bg,
		uint8_t *	len_out
	)

#include <common.h>

Get 256-color background ANSI sequence string.

Parameters

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

Returns: Pointer to ANSI sequence string (cached)

Definition at line 142 of file sgr.c.

                                                         {
  if (!sgr256_cache_initialized) {
    init_sgr256_cache();
  }
  *len_out = sgr256_bg_cache[bg].len;
  return sgr256_bg_cache[bg].seq;
}

◆ get_sgr256_fg_bg_string()

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

#include <common.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 150 of file sgr.c.

                                                                        {
  // For FG+BG, still build on-demand since we'd need 256*256 cache
  static __thread char buf[32];
  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 <common.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 134 of file sgr.c.

                                                         {
  if (!sgr256_cache_initialized) {
    init_sgr256_cache();
  }
  *len_out = sgr256_fg_cache[fg].len;
  return sgr256_fg_cache[fg].seq;
}

◆ get_utf8_palette_cache()

utf8_palette_cache_t * get_utf8_palette_cache ( const char * ascii_chars )

#include <common.h>

Get UTF-8 palette cache for a character set.

Definition at line 270 of file video/ascii/common.c.

                                                                      {
  if (!ascii_chars)
    return NULL;
 
  // Check for empty string
  if (ascii_chars[0] == '\0')
    return NULL;
 
  // Create hash of palette for cache key
  uint32_t palette_hash = hash_palette_string(ascii_chars);
 
  // Ensure the cache system is initialized
  init_utf8_cache_system();
 
  // First try: read lock for cache lookup (allows multiple concurrent readers)
  rwlock_rdlock(&g_utf8_cache_rwlock);
 
  // Check if cache exists
  utf8_palette_cache_t *cache = NULL;
  HASH_FIND_INT(g_utf8_cache_table, &palette_hash, cache);
  if (cache) {
    // Cache hit: Update access tracking (atomics are thread-safe under rdlock)
    uint64_t current_time = time_get_ns();
    atomic_store_u64(&cache->last_access_time, current_time);
    uint32_t new_access_count = atomic_fetch_add_u64(&cache->access_count, 1) + 1;
 
    // Every 10th access: Update heap position (requires write lock)
    if (new_access_count % 10 == 0) {
      // Save the key before releasing read lock
      uint32_t saved_key = cache->key;
 
      // Release read lock and upgrade to write lock
      rwlock_rdunlock(&g_utf8_cache_rwlock);
      rwlock_wrlock(&g_utf8_cache_rwlock);
 
      // Re-lookup cache entry after lock upgrade
      // Another thread could have evicted this entry while we were upgrading locks
      utf8_palette_cache_t *cache_relookup = NULL;
      HASH_FIND_INT(g_utf8_cache_table, &saved_key, cache_relookup);
      if (cache_relookup) {
        // Cache entry still exists - safe to update heap position
        uint64_t last_access = atomic_load_u64(&cache_relookup->last_access_time);
        uint32_t access_count = atomic_load_u64(&cache_relookup->access_count);
        double new_score =
            calculate_cache_eviction_score(last_access, access_count, cache_relookup->creation_time, current_time);
        utf8_heap_update_score(cache_relookup, new_score);
      }
      // If cache_relookup is NULL, entry was evicted - skip update (not an error)
 
      rwlock_wrunlock(&g_utf8_cache_rwlock);
    } else {
      rwlock_rdunlock(&g_utf8_cache_rwlock);
    }
 
    return cache;
  }
 
  // Cache miss: Need to create new entry
  // Release read lock and acquire write lock
  rwlock_rdunlock(&g_utf8_cache_rwlock);
  rwlock_wrlock(&g_utf8_cache_rwlock);
 
  // Double-check: another thread might have created it while we upgraded locks
  cache = NULL;
  HASH_FIND_INT(g_utf8_cache_table, &palette_hash, cache);
  if (cache) {
    // Found it! Just update access tracking and return
    uint64_t current_time = time_get_ns();
    atomic_store_u64(&cache->last_access_time, current_time);
    atomic_fetch_add_u64(&cache->access_count, 1);
    rwlock_wrunlock(&g_utf8_cache_rwlock);
    return cache;
  }
 
  // Create new cache entry (holding write lock)
  cache = SAFE_MALLOC(sizeof(utf8_palette_cache_t), utf8_palette_cache_t *);
  if (!cache) {
    rwlock_wrunlock(&g_utf8_cache_rwlock);
    return NULL;
  }
  memset(cache, 0, sizeof(utf8_palette_cache_t));
 
  // Set the key for uthash
  cache->key = palette_hash;
 
  // Build both cache types
  build_utf8_luminance_cache(ascii_chars, cache->cache);
  build_utf8_ramp64_cache(ascii_chars, cache->cache64, cache->char_index_ramp);
 
  // Store palette hash for validation
  SAFE_STRNCPY(cache->palette_hash, ascii_chars, sizeof(cache->palette_hash));
  cache->is_valid = true;
 
  // Initialize eviction tracking
  uint64_t current_time = time_get_ns();
  atomic_store_u64(&cache->last_access_time, current_time);
  atomic_store_u64(&cache->access_count, 1); // First access
  cache->creation_time = current_time;
 
  // Store in hash table with guaranteed eviction support
  try_insert_with_eviction_utf8(palette_hash, cache);
 
  // WASM: Skip debug log to avoid blocking render loop on main thread
  // log_debug("UTF8_CACHE: Created new cache for palette='%s' (hash=0x%x)", ascii_chars, palette_hash);
 
  rwlock_wrunlock(&g_utf8_cache_rwlock);
  return cache;
}

Referenced by image_print(), image_print_16color(), image_print_16color_dithered(), image_print_16color_dithered_with_background(), image_print_256color(), image_print_color(), image_print_color_background(), image_print_color_utf8(), and session_display_create().

◆ 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 258 of file video/rgba/image.c.

                             {
  if (!p || !p->pixels) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_clear: p or p->pixels is NULL");
    return;
  }
  // 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 140 of file video/rgba/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(), create_mixed_ascii_frame_for_client(), ffmpeg_decoder_destroy(), media_source_destroy(), session_display_convert_to_ascii(), session_host_add_client(), session_host_add_memory_participant(), session_host_destroy(), session_host_inject_frame(), and session_host_remove_client().

◆ 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 226 of file video/rgba/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 91 of file video/rgba/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(), ffmpeg_decoder_create(), ffmpeg_decoder_create_stdin(), image_new_copy(), session_capture_process_for_transmission(), session_display_convert_to_ascii(), session_host_add_client(), session_host_add_memory_participant(), and session_host_inject_frame().

◆ image_new_copy()

image_t * image_new_copy ( const image_t * source )

#include <image.h>

Create a copy of an existing image.

Parameters

source Source image to copy (must not be NULL)

Returns: Newly allocated copy of the image, or NULL on error

Creates a deep copy of an image, allocating new memory for the copy. The source and destination images are completely independent - modifying one does not affect the other. Useful for creating snapshots to prevent concurrent modification issues.

Note: Returns NULL on error (invalid image, memory allocation failure).; Caller must free the returned image with image_destroy().; Copy is allocated with standard malloc() allocation.; Pixels are fully copied (not shared with source).

Definition at line 279 of file video/rgba/image.c.

                                               {
  if (!source) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_new_copy: source is NULL");
    return NULL;
  }
 
  // Create new image with same dimensions
  image_t *copy = image_new((size_t)source->w, (size_t)source->h);
  if (!copy) {
    return NULL;
  }
 
  // Copy pixel data from source to copy
  if (source->pixels && copy->pixels) {
    size_t pixel_count = (size_t)source->w * (size_t)source->h;
    size_t pixels_size = pixel_count * sizeof(rgb_pixel_t);
    memcpy(copy->pixels, source->pixels, pixels_size);
  }
 
  return copy;
}

References ERROR_INVALID_PARAM, image_t::h, image_new(), image_t::pixels, SET_ERRNO, and image_t::w.

Referenced by create_mixed_ascii_frame_for_client().

◆ 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);

}

image_destroy_to_pool
void image_destroy_to_pool(image_t *image)
Destroy an image allocated from buffer pool.
Definition video/rgba/image.c:226

image_new_from_pool
image_t * image_new_from_pool(size_t width, size_t height)
Create a new image from buffer pool.
Definition video/rgba/image.c:181

Definition at line 181 of file video/rgba/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 27 of file foreground.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)
 
      // cache64 is indexed by luminance bucket; char_idx is only for run matching.
      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, (const char *)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, (const char *)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, rgb_pixel_t::b, outbuf_t::buf, utf8_char_t::byte_len, utf8_palette_cache::cache64, outbuf_t::cap, utf8_palette_cache::char_index_ramp, emit_rep(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, rgb_pixel_t::g, get_utf8_palette_cache(), image_t::h, ob_putc(), ob_term(), ob_write(), image_t::pixels, rgb_pixel_t::r, rep_is_profitable(), SAFE_MALLOC, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

Referenced by ascii_convert(), 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 533 of file foreground.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";
 
  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 for 16-color rendering");
    SAFE_FREE(buffer);
    return NULL;
  }
 
  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 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)
      const utf8_char_t *char_info = &utf8_cache->cache64[luma_idx];
 
      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, rgb_pixel_t::b, buffer_size, utf8_char_t::byte_len, utf8_palette_cache::cache64, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, rgb_pixel_t::g, get_utf8_palette_cache(), image_t::h, image_t::pixels, rgb_pixel_t::r, rgb_to_16color(), 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_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 646 of file foreground.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";
 
  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 for 16-color dithered rendering");
    SAFE_FREE(buffer);
    SAFE_FREE(error_buffer);
    return NULL;
  }
 
  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 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)
      const utf8_char_t *char_info = &utf8_cache->cache64[luma_idx];
 
      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, rgb_pixel_t::b, buffer_size, utf8_char_t::byte_len, utf8_palette_cache::cache64, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, rgb_pixel_t::g, get_utf8_palette_cache(), image_t::h, image_t::pixels, rgb_pixel_t::r, 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 746 of file foreground.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";
 
  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 for 16-color dithered bg rendering");
    SAFE_FREE(buffer);
    SAFE_FREE(error_buffer);
    return NULL;
  }
 
  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 same 6-bit precision as SIMD: map luminance (0-255) to bucket (0-63) then to character
      uint8_t safe_luminance = clamp_rgb(luminance);
 
      const utf8_char_t *char_info = &utf8_cache->cache[safe_luminance];
 
      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(), rgb_pixel_t::b, buffer_size, utf8_char_t::byte_len, utf8_palette_cache::cache, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, rgb_pixel_t::g, get_16color_rgb(), get_utf8_palette_cache(), image_t::h, image_t::pixels, rgb_pixel_t::r, 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_color_simd().

◆ 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 431 of file foreground.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_256color: invalid dimensions h=%d, w=%d", h, w);
    return NULL;
  }
 
  ansi_fast_init_256color();
 
  // Buffer size: 256-color ANSI codes are "\033[38;5;NNNm" (max 13 bytes) + char + reset + newline
  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_18;
  if (checked_size_mul(h_times_w, 18u, &h_times_w_times_18) != ASCIICHAT_OK) {
    return NULL;
  }
 
  size_t buffer_size;
  if (checked_size_add(h_times_w_times_18, (size_t)h, &buffer_size) != ASCIICHAT_OK) {
    return NULL;
  }
 
  char *buffer = SAFE_MALLOC(buffer_size, char *);
  char *ptr = buffer;
  const char *reset_code = "\033[0m";
 
  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 for 256-color rendering");
    SAFE_FREE(buffer);
    return NULL;
  }
 
  for (int y = 0; y < h; y++) {
    for (int x = 0; x < w; x++) {
      rgb_pixel_t pixel = image->pixels[y * w + x];
 
      uint8_t color_index = rgb_to_256color(pixel.r, pixel.g, pixel.b);
      ptr = append_256color_fg(ptr, color_index);
 
      int luminance = (77 * pixel.r + 150 * pixel.g + 29 * pixel.b + 128) >> 8;
 
      uint8_t safe_luminance = clamp_rgb(luminance);
 
      const utf8_char_t *char_info = &utf8_cache->cache[safe_luminance];
 
      if (char_info && char_info->byte_len > 0) {
        for (int byte_idx = 0; byte_idx < char_info->byte_len; byte_idx++) {
          *ptr++ = char_info->utf8_bytes[byte_idx];
        }
      } else {
        size_t palette_len = strlen(palette);
        int palette_index = (luminance * ((int)palette_len - 1) + 127) / 255;
        *ptr++ = palette[palette_index];
      }
    }
 
    SAFE_STRNCPY(ptr, reset_code, 5);
    ptr += strlen(reset_code);
    if (y < h - 1) {
      *ptr++ = '\n';
    }
  }
 
  *ptr = '\0';
  return buffer;
}

References ansi_fast_init_256color(), append_256color_fg(), ASCIICHAT_OK, rgb_pixel_t::b, buffer_size, utf8_char_t::byte_len, utf8_palette_cache::cache, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, rgb_pixel_t::g, get_utf8_palette_cache(), image_t::h, image_t::pixels, rgb_pixel_t::r, rgb_to_256color(), SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

Referenced by image_print_color_simd(), and 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 194 of file foreground.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: newline (except last row)
  // Final reset added once by ansi_rle_finish()
  const size_t total_newlines = (h_sz > 0) ? (h_sz - 1) : 0;
  const size_t final_reset = reset_len; // One reset at end (from ansi_rle_finish)
 
  // Final buffer size: pixel bytes + per-row newlines + final reset + null terminator
  const size_t extra_bytes = total_newlines + final_reset + 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 (uses original values for accuracy)
      const int luminance = (77 * pixel.r + 150 * pixel.g + 29 * pixel.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 single-byte ASCII, use RLE optimization; for multi-byte UTF-8, write directly
      if (char_info->byte_len == 1 && (unsigned char)char_info->utf8_bytes[0] < 128) {
        // ASCII character - use RLE optimization
        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);
      } else {
        // Multi-byte UTF-8 character - write color code and full UTF-8 bytes directly
        int written = SAFE_SNPRINTF((char *)&rle_ctx.buffer[rle_ctx.length], rle_ctx.capacity - rle_ctx.length,
                                    "\033[38;2;%d;%d;%dm", r, g, b);
        rle_ctx.length += written;
        // Write UTF-8 bytes
        for (int i = 0; i < char_info->byte_len && rle_ctx.length < rle_ctx.capacity; i++) {
          rle_ctx.buffer[rle_ctx.length++] = char_info->utf8_bytes[i];
        }
      }
    }
 
    // Add newline after each row (except the 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(), rgb_pixel_t::b, ansi_rle_context_t::buffer, utf8_char_t::byte_len, utf8_palette_cache::cache, ansi_rle_context_t::capacity, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, rgb_pixel_t::g, get_utf8_palette_cache(), image_t::h, ansi_rle_context_t::length, image_t::pixels, rgb_pixel_t::r, SAFE_MALLOC, SAFE_SNPRINTF, SET_ERRNO, utf8_char_t::utf8_bytes, and image_t::w.

Referenced by image_print_color_simd().

◆ image_print_color_simd()

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

#include <common.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 413 of file sgr.c.

                                                                                                                   {
  if (!image || !ascii_chars) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image_print_color_simd: image or ascii_chars is NULL");
    return NULL;
  }
 
  log_dev_every(4500 * US_PER_MS_INT, "image_print_color_simd called: width=%d, height=%d, use_256color=%d", image->w,
                image->h, use_256color);
 
#if SIMD_SUPPORT_AVX2
  log_debug_every(10 * US_PER_SEC_INT, "Taking AVX2 path: width=%d, height=%d", image->w, image->h);
  // AVX2 implementation would go here
  // For now, fall through to scalar implementation
#endif
 
  // Fallback to scalar implementation
  if (use_background_mode) {
    return image_print_16color_dithered_with_background(image, use_background_mode, ascii_chars);
  } else if (use_256color) {
    return image_print_256color(image, ascii_chars);
  } else {
    return image_print_color(image, ascii_chars);
  }
}

References ERROR_INVALID_PARAM, image_t::h, image_print_16color_dithered_with_background(), image_print_256color(), image_print_color(), log_debug_every, log_dev_every, SET_ERRNO, US_PER_MS_INT, US_PER_SEC_INT, and image_t::w.

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
	)

#include <ascii.h>

Convert image to ASCII art with terminal capabilities.

Print image with terminal capability awareness.

Parameters

image	Image to convert (must not be NULL)
caps	Terminal capabilities structure
palette	Palette characters to use for conversion

Returns: ASCII art string, or NULL on error

Converts an image to ASCII art using the provided terminal capabilities. Automatically selects the best rendering method based on terminal capabilities.

Note: Returns dynamically allocated string that must be freed by caller.

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.

Definition at line 978 of file ascii.c.

                                                                                                                    {
  if (!image || !caps || !palette) {
    return NULL;
  }
 
  terminal_color_mode_t color_level = caps->color_level;
  render_mode_t render_mode = caps->render_mode;
 
  // Half-block mode: dispatch to halfblock renderers by color depth
  if (render_mode == RENDER_MODE_HALF_BLOCK) {
    const uint8_t *rgb_data = (const uint8_t *)image->pixels;
    switch (color_level) {
    case TERM_COLOR_TRUECOLOR:
      return rgb_to_truecolor_halfblocks_scalar(rgb_data, image->w, image->h, 0);
    case TERM_COLOR_256:
      return rgb_to_256color_halfblocks_scalar(rgb_data, image->w, image->h, 0, palette);
    case TERM_COLOR_16:
      return rgb_to_16color_halfblocks_scalar(rgb_data, image->w, image->h, 0, palette);
    case TERM_COLOR_NONE:
    case TERM_COLOR_AUTO:
    default:
      return rgb_to_halfblocks_scalar(rgb_data, image->w, image->h, 0, palette);
    }
  }
 
  // Foreground/background modes: dispatch by color depth
  switch (color_level) {
  case TERM_COLOR_TRUECOLOR: {
    bool use_background = (render_mode == RENDER_MODE_BACKGROUND);
#ifdef SIMD_SUPPORT
    return image_print_color_simd((image_t *)image, use_background, false, palette);
#else
    if (use_background) {
      return image_print_color_background(image, palette);
    }
    return image_print_color_utf8(image, palette);
#endif
  }
  case TERM_COLOR_256:
    return image_print_256color(image, palette);
  case TERM_COLOR_16:
    return image_print_16color(image, palette);
  case TERM_COLOR_NONE:
  case TERM_COLOR_AUTO:
  default:
    return image_print(image, palette);
  }
}

References terminal_capabilities_t::color_level, image_t::h, image_print(), image_print_16color(), image_print_256color(), image_print_color_background(), image_print_color_simd(), image_print_color_utf8(), image_t::pixels, terminal_capabilities_t::render_mode, RENDER_MODE_BACKGROUND, RENDER_MODE_HALF_BLOCK, rgb_to_16color_halfblocks_scalar(), rgb_to_256color_halfblocks_scalar(), rgb_to_halfblocks_scalar(), rgb_to_truecolor_halfblocks_scalar(), TERM_COLOR_16, TERM_COLOR_256, TERM_COLOR_AUTO, TERM_COLOR_NONE, TERM_COLOR_TRUECOLOR, and image_t::w.

Referenced by ascii_convert_with_capabilities().

◆ image_render_test_pattern()

asciichat_error_t image_render_test_pattern	(	image_t *	image,
		unsigned int *	frame_counter
	)

#include <image.h>

Render animated color bars and grid lines into an existing image.

Parameters

image	Destination image; its allocation remains owned by the caller.
frame_counter	Per-source animation counter, advanced after each frame.

Returns: ASCIICHAT_OK on success, or ERROR_INVALID_PARAM for invalid arguments.

Definition at line 38 of file video/rgba/image.c.

                                                                                         {
  if (!image || !image->pixels || image->w <= 0 || image->h <= 0 || !frame_counter) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Test pattern requires a valid image and frame counter");
  }
 
  // Advance every generated frame. Discovery's FPS indicator measures visual
  // changes, so holding each test pattern phase for two frames makes a 60 Hz
  // source appear to run at only 30 FPS.
  unsigned int animation_phase = *frame_counter;
  *frame_counter += 5; // Speed up animation by a factor of five.
 
  for (int y = 0; y < image->h; y++) {
    for (int x = 0; x < image->w; x++) {
      rgb_pixel_t *pixel = &image->pixels[y * image->w + x];
 
      // Animated color bars that shift based on frame counter
      int animated_x = (x + animation_phase) % image->w;
      int grid_x = animated_x / 40;
 
      // Base pattern: color bars that animate horizontally
      switch (grid_x % 3) {
      case 0: // Red
        pixel->r = 255;
        pixel->g = 0;
        pixel->b = 0;
        break;
      case 1: // Green
        pixel->r = 0;
        pixel->g = 255;
        pixel->b = 0;
        break;
      case 2: // Blue
      default:
        pixel->r = 0;
        pixel->g = 0;
        pixel->b = 255;
        break;
      }
 
      // Add animated grid lines. The phase alternates the cell pattern each
      // generated frame so a downsampled terminal client still has a visible
      // frame-to-frame change when --test-pattern is used for cadence tests.
      if (animated_x % 40 == 0 || y % 30 == 0 || (((x / 10) + (y / 10) + animation_phase) & 1) == 0) {
        pixel->r = 0;
        pixel->g = 0;
        pixel->b = 0;
      }
    }
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, rgb_pixel_t::b, ERROR_INVALID_PARAM, rgb_pixel_t::g, image_t::h, image_t::pixels, rgb_pixel_t::r, SET_ERRNO, and image_t::w.

◆ 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 309 of file video/rgba/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(), ascii_convert_with_capabilities(), and session_capture_process_for_transmission().

◆ 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 320 of file video/rgba/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: src=%dx%d dst=%dx%d", src_w, src_h, dst_w,
              dst_h);
    return;
  }
 
  // Defensive checks to prevent invalid shift (UBSan protection)
  if (src_w < 1 || src_h < 1 || dst_w < 1 || dst_h < 1) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid dimensions detected after first check");
    return;
  }
 
  // Use fixed-point arithmetic for better performance
  // Use uint64_t intermediate to prevent overflow when shifting large dimensions
  const uint32_t x_ratio = (uint32_t)((((uint64_t)src_w << 16) / (uint64_t)dst_w) + 1);
  const uint32_t y_ratio = (uint32_t)((((uint64_t)src_h << 16) / (uint64_t)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;
    // Explicitly clamp to valid range [0, src_h-1]
    const uint32_t safe_src_y = src_y >= (uint32_t)(unsigned int)src_h ? (uint32_t)(src_h - 1) : src_y;
 
    // Bounds check: ensure safe_src_y is valid
    if (safe_src_y >= (uint32_t)(unsigned int)src_h) {
      SET_ERRNO(ERROR_INVALID_PARAM, "safe_src_y out of bounds: %u >= %d", safe_src_y, src_h);
      return;
    }
 
    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;
      // Explicitly clamp to valid range [0, src_w-1]
      const uint32_t safe_src_x = src_x >= (uint32_t)(unsigned int)src_w ? (uint32_t)(src_w - 1) : src_x;
 
      // Bounds check: ensure safe_src_x is valid
      if (safe_src_x >= (uint32_t)(unsigned int)src_w) {
        SET_ERRNO(ERROR_INVALID_PARAM, "safe_src_x out of bounds: %u >= %d", safe_src_x, src_w);
        return;
      }
 
      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 <common.h>

Initialize decimal lookup table.

Must be called before using any SIMD conversion functions.

Initialize decimal lookup table.

Pre-builds a cache of ASCII representations for all byte values. Used by color code generation to avoid repeated int-to-string conversions.

Definition at line 546 of file video/ascii/common.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 append_truecolor_bg(), append_truecolor_fg(), append_truecolor_fg_bg(), and ascii_simd_init().

◆ init_default_luminance_palette()

void init_default_luminance_palette ( void )

#include <common.h>

Initialize default luminance palette.

Definition at line 589 of file video/ascii/common.c.

                                          {
  if (!lifecycle_init(&g_default_palette_lc, "default_palette")) {
    return; // Already initialized
  }
  do_init_default_luminance_palette();
}

References lifecycle_init().

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 43 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(), emit_rep(), emit_reset(), emit_set_bg(), emit_set_fg(), emit_set_truecolor_bg(), emit_set_truecolor_fg(), image_print(), ob_u8(), rgb_to_16color_halfblocks_scalar(), rgb_to_256color_halfblocks_scalar(), rgb_to_halfblocks_scalar(), and rgb_to_truecolor_halfblocks_scalar().

◆ 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 22 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(), ob_putc(), ob_term(), 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 58 of file output_buffer.c.

                           {
  if (!ob)
    return;
  // Reserve space for null terminator if needed
  if (ob->len >= ob->cap) {
    ob_reserve(ob, 1);
  }
  // Append null terminator WITHOUT incrementing length
  // (null terminator is not part of the string length)
  ob->buf[ob->len] = '\0';
}

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

Referenced by ansi_compress_rle(), ansi_expand_rle(), image_print(), rgb_to_16color_halfblocks_scalar(), rgb_to_256color_halfblocks_scalar(), rgb_to_halfblocks_scalar(), and rgb_to_truecolor_halfblocks_scalar().

◆ 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 92 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 71 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_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 50 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(), image_print(), rgb_to_16color_halfblocks_scalar(), rgb_to_256color_halfblocks_scalar(), rgb_to_halfblocks_scalar(), and rgb_to_truecolor_halfblocks_scalar().

◆ 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 385 of file video/rgba/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 <common.h>

Prewarm 256-color foreground/background cache for benchmarks.

Prevents first-frame performance penalty in benchmarks.

Definition at line 129 of file sgr.c.

                                {
  init_sgr256_cache();
}

◆ prewarm_sgr256_fg_cache()

void prewarm_sgr256_fg_cache ( void )

#include <common.h>

Prewarm 256-color foreground cache for benchmarks.

Prevents first-frame performance penalty in benchmarks.

Definition at line 125 of file sgr.c.

                                   {
  init_sgr256_cache();
}

◆ print_simd_capabilities()

void print_simd_capabilities ( void )

#include <common.h>

Print detected SIMD capabilities.

Prints available SIMD instruction sets to stdout.

◆ 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 140 of file foreground.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.

◆ rainbow_replace_ansi_colors()

char * rainbow_replace_ansi_colors	(	const char *	ansi_string,
		float	time_seconds
	)

#include <color_filter.h>

Replace all RGB ANSI codes with rainbow color.

Parameters

ansi_string	Input string with ANSI escape sequences
time_seconds	Current time in seconds (for rainbow animation)

Returns: New string with rainbow colors, or NULL if no changes needed

Replaces all RGB foreground color codes (\x1b[38;2;R;G;Bm) in the input string with a single rainbow color calculated from the current time. This preserves ASCII character selection while applying rainbow colors.

The function:

Calculates rainbow color from time using color_filter_calculate_rainbow()
Builds replacement ANSI code string
Scans input for \x1b[38;2; sequences
Replaces each RGB code with rainbow code
Returns new string (caller must SAFE_FREE)

Note: Returns NULL if no ANSI codes found (use original string); Caller must free returned string with SAFE_FREE(); Input string is not modified; Usable in both terminal apps (lib/session) and WASM apps (src/web)

Definition at line 348 of file color_filter.c.

                                                                               {
  if (!ansi_string) {
    return NULL;
  }
 
  // Calculate rainbow color once for this frame
  uint8_t rainbow_r = 0, rainbow_g = 0, rainbow_b = 0;
  color_filter_calculate_rainbow(time_seconds, &rainbow_r, &rainbow_g, &rainbow_b);
 
  // Build the replacement ANSI code string once
  char rainbow_code[32];
  snprintf(rainbow_code, sizeof(rainbow_code), "\x1b[38;2;%d;%d;%dm", rainbow_r, rainbow_g, rainbow_b);
  size_t rainbow_code_len = strlen(rainbow_code);
 
  // Check if there are any ANSI codes to replace
  if (!strstr(ansi_string, "\x1b[38;2;")) {
    return NULL; // No ANSI codes found, no replacement needed
  }
 
  // Allocate buffer for result (2x size for safety with many replacements)
  size_t input_len = strlen(ansi_string);
  char *new_result = SAFE_MALLOC(input_len * 2, char *);
  if (!new_result) {
    return NULL;
  }
 
  // Replace all RGB color codes with rainbow color
  const char *src = ansi_string;
  char *dst = new_result;
 
  while (*src) {
    const char *ansi_start = strstr(src, "\x1b[38;2;");
    if (ansi_start) {
      // Copy everything before this ANSI code
      size_t before_len = (size_t)(ansi_start - src);
      memcpy(dst, src, before_len);
      dst += before_len;
 
      // Skip the old ANSI code (find the 'm' that ends it)
      const char *ansi_end = strchr(ansi_start + 7, 'm');
      if (ansi_end) {
        // Copy the rainbow replacement code
        // NOLINTNEXTLINE(bugprone-not-null-terminated-result) - binary data
        memcpy(dst, rainbow_code, rainbow_code_len);
        dst += rainbow_code_len;
 
        // Move source past the old code
        src = ansi_end + 1;
      } else {
        // Malformed ANSI code, just copy it
        *dst++ = *src++;
      }
    } else {
      // No more ANSI codes, copy the rest
      memcpy(dst, src, strlen(src) + 1);
      break;
    }
  }
 
  return new_result;
}

References color_filter_calculate_rainbow(), and SAFE_MALLOC.

Referenced by mirror_convert_frame(), and session_display_convert_to_ascii().

◆ 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 148 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(), image_print(), rgb_to_16color_halfblocks_scalar(), rgb_to_256color_halfblocks_scalar(), rgb_to_halfblocks_scalar(), and rgb_to_truecolor_halfblocks_scalar().

◆ rgb_to_16color_halfblocks_scalar()

char * rgb_to_16color_halfblocks_scalar	(	const uint8_t *	rgb,
		int	width,
		int	height,
		int	stride_bytes,
		const char *	palette
	)

#include <halfblock.h>

Convert RGB to 16-color half-blocks using scalar code.

Parameters

rgb	RGB pixel data (RGB24 format, 3 bytes per pixel)
width	Image width in pixels
height	Image height in pixels
stride_bytes	Row stride in bytes (if 0, calculated as width * 3)
palette	Character palette (unused, for API consistency)
pad_height	Top padding height (number of newlines to output before frame)

Returns: Allocated ASCII string with half-block characters (caller must free), or NULL on error

Renders an RGB image using halfblock characters with 16-color ANSI codes. Processes 2 rows of source pixels per 1 output line with foreground and background color selection from 16-color palette.

Note: Caller must free the returned buffer with free().

Convert RGB to 16-color half-blocks using scalar code.

Definition at line 297 of file scalar/halfblock.c.

                                                            {
  (void)palette; // Unused for 16-color mode
  if (width <= 0 || height <= 0)
    return platform_strdup("");
  if (stride_bytes <= 0)
    stride_bytes = width * 3;
 
  // Initialize 16-color lookup table
  ansi_fast_init_16color();
 
  outbuf_t ob = {0};
  // Estimate: per cell ~ 12 bytes (16-color codes); half the rows + newlines + resets
  size_t est_cells = (size_t)width * ((size_t)(height + 1) / 2);
  ob.cap = est_cells * 12u + (size_t)((height + 1) / 2) * 8u + 64u;
  ob.buf = SAFE_MALLOC(ob.cap ? ob.cap : 1, char *);
  if (!ob.buf)
    return NULL;
 
  // Track 16-color state
  int cur_fg = -1, cur_bg = -1;
  static const char HB[3] = {(char)0xE2, (char)0x96, (char)0x80};
 
  for (int y = 0; y < height; y += 2) {
    const uint8_t *rowT = rgb + (size_t)y * (size_t)stride_bytes;
    const uint8_t *rowB = (y + 1 < height) ? rowT + (size_t)stride_bytes : NULL;
 
    int x = 0;
    while (x < width) {
      const uint8_t *pT = rowT + (size_t)x * 3u;
      uint8_t rT = pT[0], gT = pT[1], bT = pT[2];
      uint8_t color_fg = rgb_to_16color(rT, gT, bT);
 
      uint8_t rB = rT, gB = gT, bB = bT;
      if (rowB) {
        const uint8_t *pB = rowB + (size_t)x * 3u;
        rB = pB[0];
        gB = pB[1];
        bB = pB[2];
      }
      uint8_t color_bg = rgb_to_16color(rB, gB, bB);
 
      // Extend run while colors match
      int j = x + 1;
      for (; j < width; ++j) {
        const uint8_t *qT = rowT + (size_t)j * 3u;
        uint8_t color_fg2 = rgb_to_16color(qT[0], qT[1], qT[2]);
 
        uint8_t color_bg2 = color_fg2;
        if (rowB) {
          const uint8_t *qB = rowB + (size_t)j * 3u;
          color_bg2 = rgb_to_16color(qB[0], qB[1], qB[2]);
        }
 
        if (color_fg2 != color_fg || color_bg2 != color_bg)
          break;
      }
      uint32_t run = (uint32_t)(j - x);
 
      // Check if transparent
      bool is_transparent = (rT == 0 && gT == 0 && bT == 0 && rB == 0 && gB == 0 && bB == 0);
 
      if (is_transparent) {
        if (cur_fg != -1 || cur_bg != -1) {
          emit_reset(&ob);
          cur_fg = cur_bg = -1;
        }
        // Emit spaces for transparent area (no RLE for padding)
        for (uint32_t k = 0; k < run; ++k) {
          ob_write(&ob, " ", 1);
        }
      } else {
        // Emit 16-color codes if changed
        if (cur_fg != color_fg) {
          char buf[16];
          char *ptr = append_16color_fg(buf, color_fg);
          ob_write(&ob, buf, (size_t)(ptr - buf));
          cur_fg = color_fg;
        }
        if (cur_bg != color_bg) {
          char buf[16];
          char *ptr = append_16color_bg(buf, color_bg);
          ob_write(&ob, buf, (size_t)(ptr - buf));
          cur_bg = color_bg;
        }
 
        ob_write(&ob, HB, 3);
        if (rep_is_profitable(run)) {
          emit_rep(&ob, run - 1);
        } else {
          for (uint32_t k = 1; k < run; ++k) {
            ob_write(&ob, HB, 3);
          }
        }
      }
 
      x = j;
    }
 
    emit_reset(&ob);
    if (y + 2 < height) {
      ob_putc(&ob, '\n');
    }
    cur_fg = cur_bg = -1;
  }
 
  ob_term(&ob);
  return ob.buf;
}

References ansi_fast_init_16color(), append_16color_bg(), append_16color_fg(), outbuf_t::buf, outbuf_t::cap, emit_rep(), emit_reset(), ob_putc(), ob_term(), ob_write(), platform_strdup(), rep_is_profitable(), rgb_to_16color(), and SAFE_MALLOC.

Referenced by image_print_with_capabilities().

◆ rgb_to_256color_halfblocks_scalar()

char * rgb_to_256color_halfblocks_scalar	(	const uint8_t *	rgb,
		int	width,
		int	height,
		int	stride_bytes,
		const char *	palette
	)

#include <halfblock.h>

Convert RGB to 256-color half-blocks using scalar code.

Parameters

rgb	RGB pixel data (RGB24 format, 3 bytes per pixel)
width	Image width in pixels
height	Image height in pixels
stride_bytes	Row stride in bytes (if 0, calculated as width * 3)
palette	Character palette (unused, for API consistency)
pad_height	Top padding height (number of newlines to output before frame)

Returns: Allocated ASCII string with half-block characters (caller must free), or NULL on error

Renders an RGB image using halfblock characters with 256-color ANSI codes. Processes 2 rows of source pixels per 1 output line with foreground and background color selection from 256-color palette.

Note: Caller must free the returned buffer with free().

Convert RGB to 256-color half-blocks using scalar code.

Definition at line 416 of file scalar/halfblock.c.

                                                             {
  (void)palette; // Unused for 256-color mode
  if (width <= 0 || height <= 0)
    return platform_strdup("");
  if (stride_bytes <= 0)
    stride_bytes = width * 3;
 
  // Initialize 256-color lookup table
  ansi_fast_init_256color();
 
  outbuf_t ob = {0};
  // Estimate: per cell ~ 14 bytes (256-color codes); half the rows + newlines + resets
  size_t est_cells = (size_t)width * ((size_t)(height + 1) / 2);
  ob.cap = est_cells * 14u + (size_t)((height + 1) / 2) * 8u + 64u;
  ob.buf = SAFE_MALLOC(ob.cap ? ob.cap : 1, char *);
  if (!ob.buf)
    return NULL;
 
  // Track 256-color state
  int cur_fg = -1, cur_bg = -1;
  static const char HB[3] = {(char)0xE2, (char)0x96, (char)0x80};
 
  for (int y = 0; y < height; y += 2) {
    const uint8_t *rowT = rgb + (size_t)y * (size_t)stride_bytes;
    const uint8_t *rowB = (y + 1 < height) ? rowT + (size_t)stride_bytes : NULL;
 
    int x = 0;
    while (x < width) {
      const uint8_t *pT = rowT + (size_t)x * 3u;
      uint8_t rT = pT[0], gT = pT[1], bT = pT[2];
      uint8_t color_fg = rgb_to_256color(rT, gT, bT);
 
      uint8_t rB = rT, gB = gT, bB = bT;
      if (rowB) {
        const uint8_t *pB = rowB + (size_t)x * 3u;
        rB = pB[0];
        gB = pB[1];
        bB = pB[2];
      }
      uint8_t color_bg = rgb_to_256color(rB, gB, bB);
 
      // Extend run while colors match
      int j = x + 1;
      for (; j < width; ++j) {
        const uint8_t *qT = rowT + (size_t)j * 3u;
        uint8_t color_fg2 = rgb_to_256color(qT[0], qT[1], qT[2]);
 
        uint8_t color_bg2 = color_fg2;
        if (rowB) {
          const uint8_t *qB = rowB + (size_t)j * 3u;
          color_bg2 = rgb_to_256color(qB[0], qB[1], qB[2]);
        }
 
        if (color_fg2 != color_fg || color_bg2 != color_bg)
          break;
      }
      uint32_t run = (uint32_t)(j - x);
 
      // Check if transparent
      bool is_transparent = (rT == 0 && gT == 0 && bT == 0 && rB == 0 && gB == 0 && bB == 0);
 
      if (is_transparent) {
        if (cur_fg != -1 || cur_bg != -1) {
          emit_reset(&ob);
          cur_fg = cur_bg = -1;
        }
        // Emit spaces for transparent area (no RLE for padding)
        for (uint32_t k = 0; k < run; ++k) {
          ob_write(&ob, " ", 1);
        }
      } else {
        // Emit 256-color codes if changed
        if (cur_fg != color_fg) {
          char buf[16];
          char *ptr = append_256color_fg(buf, color_fg);
          ob_write(&ob, buf, (size_t)(ptr - buf));
          cur_fg = color_fg;
        }
        if (cur_bg != color_bg) {
          char buf[16];
          char *ptr = append_256color_bg(buf, color_bg);
          ob_write(&ob, buf, (size_t)(ptr - buf));
          cur_bg = color_bg;
        }
 
        ob_write(&ob, HB, 3);
        if (rep_is_profitable(run)) {
          emit_rep(&ob, run - 1);
        } else {
          for (uint32_t k = 1; k < run; ++k) {
            ob_write(&ob, HB, 3);
          }
        }
      }
 
      x = j;
    }
 
    emit_reset(&ob);
    if (y + 2 < height) {
      ob_putc(&ob, '\n');
    }
    cur_fg = cur_bg = -1;
  }
 
  ob_term(&ob);
  return ob.buf;
}

References ansi_fast_init_256color(), append_256color_bg(), append_256color_fg(), outbuf_t::buf, outbuf_t::cap, emit_rep(), emit_reset(), ob_putc(), ob_term(), ob_write(), platform_strdup(), rep_is_profitable(), rgb_to_256color(), and SAFE_MALLOC.

Referenced by image_print_with_capabilities().

◆ 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 381 of file foreground.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 375 of file foreground.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 369 of file foreground.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.

◆ rgb_to_halfblocks_scalar()

char * rgb_to_halfblocks_scalar	(	const uint8_t *	rgb,
		int	width,
		int	height,
		int	stride_bytes,
		const char *	palette
	)

#include <halfblock.h>

Convert RGB to monochrome (grayscale) half-blocks using scalar code.

Parameters

rgb	RGB pixel data (RGB24 format, 3 bytes per pixel)
width	Image width in pixels
height	Image height in pixels
stride_bytes	Row stride in bytes (if 0, calculated as width * 3)
palette	Character palette for luminance mapping

Returns: Allocated ASCII string with half-block characters (caller must free), or NULL on error

Renders an RGB image using halfblock characters without color codes. Uses ITU-R BT.601 luminance formula for grayscale conversion.

Note: Caller must free the returned buffer with free().

Convert RGB to monochrome (grayscale) half-blocks using scalar code.

Parameters

rgb	Input RGB image data (RGB24, 3 bytes per pixel)
width	Image width in pixels
height	Image height in pixels
stride_bytes	Bytes per row (if 0, calculated as width * 3)
palette	Character palette (unused, for API consistency)

Returns: Malloc'd NUL-terminated ASCII string (caller must free)

Renders an RGB image using halfblock characters with no color codes. Simple monochrome rendering without any ANSI escape sequences.

Definition at line 184 of file scalar/halfblock.c.

                                                                                                                 {
  (void)palette; // Unused for monochrome mode
  if (width <= 0 || height <= 0)
    return platform_strdup("");
  if (stride_bytes <= 0)
    stride_bytes = width * 3;
 
  outbuf_t ob = {0};
  // Estimate: per cell ~ 3 bytes (UTF-8 block shade); half the rows + newlines
  size_t est_cells = (size_t)width * ((size_t)(height + 1) / 2);
  ob.cap = est_cells * 3u + (size_t)((height + 1) / 2) * 2u + 64u;
  ob.buf = SAFE_MALLOC(ob.cap ? ob.cap : 1, char *);
  if (!ob.buf)
    return NULL;
 
  // Process 2 source rows per output line
  for (int y = 0; y < height; y += 2) {
    const uint8_t *rowT = rgb + (size_t)y * (size_t)stride_bytes;
    const uint8_t *rowB = (y + 1 < height) ? rowT + (size_t)stride_bytes : NULL;
 
    int x = 0;
    while (x < width) {
      // Read top pixel
      const uint8_t *pT = rowT + (size_t)x * 3u;
      uint8_t rT = pT[0], gT = pT[1], bT = pT[2];
 
      // Read bottom pixel (or duplicate top if no bottom row)
      uint8_t rB = rT, gB = gT, bB = bT;
      if (rowB) {
        const uint8_t *pB = rowB + (size_t)x * 3u;
        rB = pB[0];
        gB = pB[1];
        bB = pB[2];
      }
 
      // Extend run while colors match exactly (treating as monochrome)
      int j = x + 1;
      for (; j < width; ++j) {
        const uint8_t *qT = rowT + (size_t)j * 3u;
        uint8_t rT2 = qT[0], gT2 = qT[1], bT2 = qT[2];
 
        uint8_t rB2 = rT2, gB2 = gT2, bB2 = bT2;
        if (rowB) {
          const uint8_t *qB = rowB + (size_t)j * 3u;
          rB2 = qB[0];
          gB2 = qB[1];
          bB2 = qB[2];
        }
 
        if (!((rT2 == rT && gT2 == gT && bT2 == bT) && (rB2 == rB && gB2 == gB && bB2 == bB)))
          break;
      }
      uint32_t run = (uint32_t)(j - x);
 
      // Convert to luminance for monochrome shading
      uint8_t lum_top = (rT * 76 + gT * 150 + bT * 29) >> 8; // ITU-R BT.601
      uint8_t lum_bot = (rB * 76 + gB * 150 + bB * 29) >> 8;
 
      // Check if transparent (both pixels very dark)
      bool is_transparent = (lum_top < 16 && lum_bot < 16);
 
      if (is_transparent) {
        // Emit spaces for transparent area (no RLE for padding)
        for (uint32_t k = 0; k < run; ++k) {
          ob_write(&ob, " ", 1);
        }
      } else {
        // Use block characters based on luminance levels
        // Map luminance (0-255) to block shade characters
        uint8_t shade_top = (lum_top >> 6); // Map 0-255 to 0-3
 
        static const char shades[4][3] = {
            {(char)0xE2, (char)0x96, (char)0x91}, // ░ light shade
            {(char)0xE2, (char)0x96, (char)0x92}, // ▒ medium shade
            {(char)0xE2, (char)0x96, (char)0x93}, // ▓ dark shade
            {(char)0xE2, (char)0x96, (char)0x88}  // █ full block
        };
 
        // Emit the appropriate shade character
        const char *shade_char = shades[shade_top];
        ob_write(&ob, shade_char, 3);
        if (rep_is_profitable(run)) {
          emit_rep(&ob, run - 1);
        } else {
          for (uint32_t k = 1; k < run; ++k) {
            ob_write(&ob, shade_char, 3);
          }
        }
      }
 
      x = j;
    }
 
    // End of line: reset and newline (except for last output line)
    // Note: even monochrome calls reset for structural consistency
    if (y + 2 < height) {
      ob_putc(&ob, '\n');
    }
  }
 
  ob_term(&ob);
  return ob.buf;
}

References outbuf_t::buf, outbuf_t::cap, emit_rep(), ob_putc(), ob_term(), ob_write(), platform_strdup(), rep_is_profitable(), and SAFE_MALLOC.

Referenced by image_print_with_capabilities().

◆ rgb_to_truecolor_halfblocks_scalar()

char * rgb_to_truecolor_halfblocks_scalar	(	const uint8_t *	rgb,
		int	width,
		int	height,
		int	stride_bytes
	)

#include <halfblock.h>

Convert RGB to truecolor half-blocks using scalar code.

Parameters

rgb	RGB pixel data (RGB24 format, 3 bytes per pixel)
width	Image width in pixels
height	Image height in pixels
stride_bytes	Row stride in bytes (if 0, calculated as width * 3)

Returns: Allocated ASCII string with half-block characters (caller must free), or NULL on error

Renders an RGB image using halfblock characters (▀) with truecolor foreground and background colors. Processes 2 rows of source pixels per 1 output line:

Top pixel: foreground color for halfblock
Bottom pixel: background color for halfblock
Last row (odd height): duplicates top row as bottom

Features:

Run-length encoding (RLE) for repeated halfblocks
Transparent area detection (fully black pixels)
Color state tracking to minimize ANSI sequences
Proper vertical resolution (height / 2 output rows)

Note: Caller must free the returned buffer with free().; Returns empty string for invalid dimensions (width <= 0 or height <= 0).; Stride of 0 defaults to width * 3 (tightly packed RGB24).

Convert RGB to truecolor half-blocks using scalar code.

Parameters

rgb	Input RGB image data (RGB24, 3 bytes per pixel)
width	Image width in pixels
height	Image height in pixels
stride_bytes	Bytes per row (if 0, calculated as width * 3)

Returns: Malloc'd NUL-terminated ANSI escape string (caller must free)

Renders an RGB image using halfblock characters with truecolor foreground and background colors. Processes 2 source rows per output line:

Top pixel: foreground color for halfblock
Bottom pixel: background color for halfblock
Last row (odd height): duplicates top row as bottom

Uses RLE optimization for repeated halfblocks and detects transparent areas (fully black pixels) which are rendered as spaces instead of halfblocks.

Definition at line 48 of file scalar/halfblock.c.

                                                                                                      {
 
  if (width <= 0 || height <= 0)
    return platform_strdup("");
  if (stride_bytes <= 0)
    stride_bytes = width * 3;
 
  outbuf_t ob = {0};
  // Estimate: per cell ~ 10-14 bytes (ANSI sequences); half the rows + newlines
  size_t est_cells = (size_t)width * ((size_t)(height + 1) / 2);
  ob.cap = est_cells * 14u + (size_t)((height + 1) / 2) * 8u + 64u;
  ob.buf = SAFE_MALLOC(ob.cap ? ob.cap : 1, char *);
  if (!ob.buf)
    return NULL;
 
  // Track SGR state (use -1 to indicate "not set")
  int cur_fr = -1, cur_fg = -1, cur_fb = -1;
  int cur_br = -1, cur_bg = -1, cur_bb = -1;
 
  // Upper half-block character: U+2580 = UTF-8 0xE2 0x96 0x80
  static const char HB[3] = {(char)0xE2, (char)0x96, (char)0x80};
 
  // Process 2 source rows per output line
  for (int y = 0; y < height; y += 2) {
    const uint8_t *rowT = rgb + (size_t)y * (size_t)stride_bytes;
    const uint8_t *rowB = (y + 1 < height) ? rowT + (size_t)stride_bytes : NULL;
 
    int x = 0;
    while (x < width) {
      // Read top pixel
      const uint8_t *pT = rowT + (size_t)x * 3u;
      uint8_t rT = pT[0], gT = pT[1], bT = pT[2];
 
      // Read bottom pixel (or duplicate top if no bottom row)
      uint8_t rB = rT, gB = gT, bB = bT;
      if (rowB) {
        const uint8_t *pB = rowB + (size_t)x * 3u;
        rB = pB[0];
        gB = pB[1];
        bB = pB[2];
      }
 
      // Extend run while top and bottom colors match exactly
      int j = x + 1;
      for (; j < width; ++j) {
        const uint8_t *qT = rowT + (size_t)j * 3u;
        uint8_t rT2 = qT[0], gT2 = qT[1], bT2 = qT[2];
 
        uint8_t rB2 = rT2, gB2 = gT2, bB2 = bT2;
        if (rowB) {
          const uint8_t *qB = rowB + (size_t)j * 3u;
          rB2 = qB[0];
          gB2 = qB[1];
          bB2 = qB[2];
        }
 
        // Check if colors match
        if (!((rT2 == rT && gT2 == gT && bT2 == bT) && (rB2 == rB && gB2 == gB && bB2 == bB)))
          break;
      }
      uint32_t run = (uint32_t)(j - x);
 
      // Check if transparent (all black = padding)
      bool is_transparent = (rT == 0 && gT == 0 && bT == 0 && rB == 0 && gB == 0 && bB == 0);
 
      if (is_transparent) {
        // Reset colors before transparent areas to prevent color bleeding
        if (cur_fr != -1 || cur_fg != -1 || cur_fb != -1 || cur_br != -1 || cur_bg != -1 || cur_bb != -1) {
          emit_reset(&ob);
          cur_fr = cur_fg = cur_fb = -1;
          cur_br = cur_bg = cur_bb = -1;
        }
        // Emit spaces for transparent area (no RLE for padding)
        for (uint32_t k = 0; k < run; ++k) {
          ob_write(&ob, " ", 1);
        }
      } else {
        // Normal colored halfblocks - set fg to TOP, bg to BOTTOM if changed
        if (cur_fr != rT || cur_fg != gT || cur_fb != bT) {
          emit_set_fg(&ob, rT, gT, bT);
          cur_fr = rT;
          cur_fg = gT;
          cur_fb = bT;
        }
        if (cur_br != rB || cur_bg != gB || cur_bb != bB) {
          emit_set_bg(&ob, rB, gB, bB);
          cur_br = rB;
          cur_bg = gB;
          cur_bb = bB;
        }
 
        // Emit halfblock once, then RLE or literals
        ob_write(&ob, HB, 3);
        if (rep_is_profitable(run)) {
          emit_rep(&ob, run - 1);
        } else {
          for (uint32_t k = 1; k < run; ++k) {
            ob_write(&ob, HB, 3);
          }
        }
      }
 
      x = j;
    }
 
    // End of line: reset and newline (except for last output line)
    emit_reset(&ob);
    if (y + 2 < height) {
      ob_putc(&ob, '\n');
    }
    cur_fr = cur_fg = cur_fb = -1;
    cur_br = cur_bg = cur_bb = -1;
  }
 
  // Ensure null terminator
  ob_term(&ob);
  return ob.buf;
}

References outbuf_t::buf, outbuf_t::cap, emit_rep(), emit_reset(), emit_set_bg(), emit_set_fg(), ob_putc(), ob_term(), ob_write(), platform_strdup(), rep_is_profitable(), and SAFE_MALLOC.

Referenced by ascii_convert(), and image_print_with_capabilities().

◆ set_color_quality_mode()

void set_color_quality_mode ( bool high_quality )

#include <common.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 (palette and other caches)

Called during shutdown to clean up resources.

Definition at line 497 of file video/ascii/common.c.

                                   {
  log_dev("SIMD_CACHE: Starting cleanup of all SIMD caches");
 
  // Only destroy caches if they were ever initialized
  if (lifecycle_is_initialized(&g_utf8_cache_lc)) {
    // Destroy shared UTF-8 palette cache (write lock for cleanup)
    rwlock_wrlock(&g_utf8_cache_rwlock);
    if (g_utf8_cache_table) {
      // Free all UTF-8 cache entries using HASH_ITER
      utf8_palette_cache_t *cache, *tmp;
      HASH_ITER(hh, g_utf8_cache_table, cache, tmp) {
        HASH_DEL(g_utf8_cache_table, cache);
        SAFE_FREE(cache);
      }
      g_utf8_cache_table = NULL;
      // WASM: Skip debug log to avoid blocking
      // log_debug("UTF8_CACHE: Destroyed shared UTF-8 palette cache");
    }
    // Clean up heap arrays
    if (g_utf8_heap) {
      SAFE_FREE(g_utf8_heap);
      g_utf8_heap = NULL;
      g_utf8_heap_size = 0;
    }
    rwlock_wrunlock(&g_utf8_cache_rwlock);
    // Shutdown lifecycle and destroy rwlock together
    lifecycle_shutdown(&g_utf8_cache_lc);
  }
 
  // Call architecture-specific cache cleanup functions
  // Note: Only ONE SIMD implementation is compiled based on highest available instruction set
  // Higher instruction sets (AVX2, SSSE3) handle cleanup for lower ones (SSE2)
#if SIMD_SUPPORT_SSSE3
  ssse3_caches_destroy();
#elif SIMD_SUPPORT_SSE2
  sse2_caches_destroy();
#elif SIMD_SUPPORT_SVE
  sve_caches_destroy();
#endif
 
  log_dev("SIMD_CACHE: All SIMD caches destroyed");
}

References lifecycle_is_initialized(), lifecycle_shutdown(), log_dev, rwlock_wrlock, rwlock_wrunlock, and SAFE_FREE.

Referenced by asciichat_shared_destroy().

◆ str_append_bytes()

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

#include <common.h>

Append bytes to string buffer.

Parameters

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

◆ str_append_c()

void str_append_c	(	Str *	s,
		char	c
	)

#include <common.h>

Append character to string buffer.

Parameters

s	String buffer structure
c	Character to append

◆ str_destroy()

void str_destroy ( Str * s )

#include <common.h>

Free string buffer.

Parameters

s	String buffer structure

◆ str_init()

void str_init ( Str * s )

#include <common.h>

Initialize string buffer.

Parameters

s	String buffer structure

◆ str_printf()

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

#include <common.h>

Append formatted string to buffer.

Parameters

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

◆ str_reserve()

void str_reserve	(	Str *	s,
		size_t	need
	)

#include <common.h>

Reserve space in string buffer.

Parameters

s	String buffer structure
need	Minimum bytes needed

◆ 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 <common.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

◆ _pad

uint8_t utf8_char_t::_pad

Padding for alignment

Definition at line 471 of file video/ascii/common.h.

◆ access_count

atomic_t utf8_palette_cache::access_count

Total access count

Definition at line 479 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache().

◆ 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 282 of file video/ascii/common.h.

◆ best_method

const char* simd_benchmark_t::best_method

Name of fastest method

Definition at line 286 of file video/ascii/common.h.

◆ byte_len

uint8_t utf8_char_t::byte_len

Number of bytes used

Definition at line 470 of file video/ascii/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(), image_print_256color(), image_print_color(), image_print_color_background(), and image_print_color_utf8().

◆ cache

utf8_char_t utf8_palette_cache::cache[256]

Cache of all 256 luminance levels

Definition at line 475 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache(), image_print_16color_dithered_with_background(), image_print_256color(), image_print_color(), image_print_color_background(), and image_print_color_utf8().

◆ cache64

utf8_char_t utf8_palette_cache::cache64[64]

Cache of 64 most common characters

Definition at line 476 of file video/ascii/common.h.

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

◆ cached_score

double utf8_palette_cache::cached_score

Eviction score (higher = keep longer)

Definition at line 482 of file video/ascii/common.h.

◆ cap

size_t Str::cap

Total bytes allocated

Definition at line 154 of file video/ascii/common.h.

◆ cBB

int RLEState::cBB

Current background RGB

Definition at line 220 of file video/ascii/common.h.

◆ cBG

int RLEState::cBG

Definition at line 220 of file video/ascii/common.h.

◆ cBR

int RLEState::cBR

Definition at line 220 of file video/ascii/common.h.

◆ cFB

int RLEState::cFB

Current foreground RGB

Definition at line 219 of file video/ascii/common.h.

◆ cFG

int RLEState::cFG

Definition at line 219 of file video/ascii/common.h.

◆ cFR

int RLEState::cFR

Definition at line 219 of file video/ascii/common.h.

◆ char_index_ramp

uint8_t utf8_palette_cache::char_index_ramp[256]

Luminance to character index mapping

Definition at line 477 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache(), and image_print().

◆ creation_time

uint64_t utf8_palette_cache::creation_time

When this cache was created

Definition at line 481 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache().

◆ data

char* Str::data

Pointer to allocated buffer

Definition at line 152 of file video/ascii/common.h.

◆ dec3_initialized

bool global_dec3_cache_t::dec3_initialized

Whether cache is initialized

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

Referenced by append_truecolor_bg(), append_truecolor_fg(), append_truecolor_fg_bg(), and init_dec3().

◆ dec3_table

dec3_t global_dec3_cache_t::dec3_table[256]

Lookup table for 0-255

Definition at line 106 of file video/ascii/common.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(), and init_dec3().

◆ g_dec3_cache

global_dec3_cache_t g_dec3_cache

extern

#include <common.h>

Global decimal cache instance.

Definition at line 37 of file video/ascii/common.c.

37{0};

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(), and init_dec3().

◆ g_default_luminance_palette

char g_default_luminance_palette[256]

extern

#include <common.h>

Default luminance palette (256 characters)

Definition at line 38 of file video/ascii/common.c.

38{0};

◆ h

int ImageRGB::h

Image height in pixels

Definition at line 234 of file video/ascii/common.h.

◆ heap_index

size_t utf8_palette_cache::heap_index

Index in the eviction min-heap

Definition at line 483 of file video/ascii/common.h.

◆ hh

UT_hash_handle utf8_palette_cache::hh

uthash handle

Definition at line 490 of file video/ascii/common.h.

◆ initialized

bool utf8_palette_cache::initialized

Whether cache is initialized

Definition at line 486 of file video/ascii/common.h.

◆ is_valid

bool utf8_palette_cache::is_valid

Whether cache has valid data

Definition at line 487 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache().

◆ key

uint32_t utf8_palette_cache::key

Palette string hash (uthash key)

Definition at line 484 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache().

◆ last_access_time

atomic_t utf8_palette_cache::last_access_time

Last access timestamp

Definition at line 478 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache().

◆ len [1/2]

uint8_t dec3_t::len

Number of digits (1-3)

Definition at line 96 of file video/ascii/common.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(), and init_dec3().

◆ len [2/2]

size_t Str::len

Number of bytes currently used

Definition at line 153 of file video/ascii/common.h.

◆ neon_time

double simd_benchmark_t::neon_time

NEON implementation time (seconds)

Definition at line 283 of file video/ascii/common.h.

◆ palette_hash

char utf8_palette_cache::palette_hash[256]

Original palette string for validation

Definition at line 485 of file video/ascii/common.h.

Referenced by get_utf8_palette_cache().

◆ pixels

uint8_t* ImageRGB::pixels

RGB data: w * h * 3 bytes

Definition at line 235 of file video/ascii/common.h.

◆ runLen

int RLEState::runLen

Current run length

Definition at line 221 of file video/ascii/common.h.

◆ s

char dec3_t::s[3]

Digit string (no null terminator)

Definition at line 97 of file video/ascii/common.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(), and init_dec3().

◆ scalar_time

double simd_benchmark_t::scalar_time

Scalar implementation time (seconds)

Definition at line 279 of file video/ascii/common.h.

◆ seeded

int RLEState::seeded

Whether state is initialized

Definition at line 222 of file video/ascii/common.h.

◆ speedup_best

double simd_benchmark_t::speedup_best

Best speedup ratio

Definition at line 285 of file video/ascii/common.h.

◆ sse2_time

double simd_benchmark_t::sse2_time

SSE2 implementation time (seconds)

Definition at line 280 of file video/ascii/common.h.

◆ ssse3_time

double simd_benchmark_t::ssse3_time

SSSE3 implementation time (seconds)

Definition at line 281 of file video/ascii/common.h.

◆ sve_time

double simd_benchmark_t::sve_time

SVE implementation time (seconds)

Definition at line 284 of file video/ascii/common.h.

◆ total_age_seconds

uint32_t utf8_palette_cache::total_age_seconds

Total age in seconds

Definition at line 480 of file video/ascii/common.h.

◆ utf8_bytes

uint8_t utf8_char_t::utf8_bytes[4]

UTF-8 bytes (0-3)

Definition at line 469 of file video/ascii/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(), image_print_256color(), image_print_color(), image_print_color_background(), and image_print_color_utf8().

◆ w

int ImageRGB::w

Image width in pixels

Definition at line 233 of file video/ascii/common.h.

◆ width

uint8_t utf8_char_t::width

Character display width (1 or 2)

Definition at line 468 of file video/ascii/common.h.

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Luminance Calculation Constants

Detailed Description

ALGORITHM OVERVIEW:

IMPLEMENTATION:

CORE FEATURES:

CONVERSION MODES:

FRAME MANAGEMENT:

CORE FEATURES:

BUFFER MANAGEMENT:

ANSI ESCAPE SEQUENCES:

COLOR MODE AUTO-SELECTION:

RLE FORMAT:

USE CASES:

FEATURES:

COLOR FILTERS:

ARCHITECTURE:

USAGE:

PROTOCOL INTEGRATION:

CORE FEATURES:

IMAGE FORMATS:

COLOR MODES:

video README

Overview

Features

Rendering Pipeline

1. Image Scaling

2. Brightness Calculation

3. Palette Mapping

4. ANSI Escape Sequence Generation

5. Terminal Output

SIMD vs Scalar Implementations

Scalar (Non-SIMD) Implementation

SIMD vs Scalar Implementations

SSE2 (x86_64 Baseline)

SSSE3 (Supplemental SSE3)

AVX2 (Advanced Vector Extensions 2)

NEON (ARM)

SVE (ARM Scalable Vector Extension)

Runtime CPU Detection

Usage Examples

Basic Conversion

Half-Block Mode

Multi-Client Grid

Optimization Strategy

Architecture-Level Optimization

Algorithm-Level Optimization

Memory Hierarchy Optimization

Spatial Locality

Performance Benchmarks

Performance Trade-offs Analysis

Scalar vs SIMD Trade-offs

SIMD Level Trade-offs

Latency vs Throughput

Power Efficiency

Terminal Compatibility

Macro Definition Documentation

◆ ANSI_BG_PREFIX

◆ ANSI_COLOR_SUFFIX

◆ ANSI_FG_PREFIX

◆ ascii_clear_screen

◆ ASCII_LUMINANCE_LEVELS

◆ ASCII_SLEEP_NS

◆ ascii_zzz

◆ CACHE_FREQUENCY_DECAY_TIME

◆ CACHE_MAX_LIFETIME

◆ CACHE_RECENCY_SCALE

◆ console_clear

◆ cursor_reset

◆ DIGITAL_RAIN_DEFAULT_ANIMATION_SPEED

◆ DIGITAL_RAIN_DEFAULT_BRIGHTNESS_DECAY

◆ DIGITAL_RAIN_DEFAULT_COLOR_B

◆ DIGITAL_RAIN_DEFAULT_COLOR_G