display.c File Reference

💻 Client terminal display: TTY detection, frame rendering, and interactive/stdout output routing More...

Go to the source code of this file.

Functions
int	display_init ()
	Initialize what is necessary to display ascii frames.
bool	display_has_tty ()
	Check if display has TTY capability.
void	display_full_reset ()
	Perform full display reset.
void	display_reset_for_new_connection ()
	Reset display state for new connection.
void	display_disable_logging_for_first_frame ()
	Disable terminal logging for first frame.
void	display_render_frame (const char *frame_data, bool is_snapshot_frame)
	Render ASCII frame to display.
void	display_cleanup ()
	Cleanup display subsystem.

Variables
tty_info_t	g_tty_info = {-1, NULL, false}
	Global TTY information structure.

Detailed Description

💻 Client terminal display: TTY detection, frame rendering, and interactive/stdout output routing

The display system supports dual output modes:

• Interactive TTY Mode: Direct terminal control with cursor positioning
• Redirect Mode: Plain text output for pipes and file redirection
• Snapshot Mode: Single frame capture with minimal terminal control

TTY Detection and Management

Implements robust TTY detection across platforms:

1. Environment Variables: Check $TTY for explicit terminal path
2. Standard Streams: Test stdin/stdout/stderr for TTY status
3. Controlling Terminal: Fall back to /dev/tty (Unix) or CON (Windows)
4. Validation: Verify TTY path accessibility and permissions

Terminal Control Sequences

Uses platform abstraction layer for terminal operations:

• Initialization: Set terminal to optimal display mode
• Cursor Management: Hide cursor and position for frame updates
• Screen Control: Clear screen and scrollback buffer
• Reset Operations: Restore terminal to original state

Frame Rendering Pipeline

Frame display follows a structured pipeline:

1. Mode Detection: Determine output mode (TTY vs redirect)
2. Cursor Positioning: Position cursor for frame update (TTY mode)
3. Data Writing: Write frame data to appropriate file descriptor
4. Synchronization: Ensure data reaches terminal (fsync for redirect)
5. State Updates: Track frame dimensions and display state

Snapshot Mode Support

Special handling for single-frame capture:

• Timing Control: Coordinate with protocol for snapshot timing
• Output Routing: Final frame written to both TTY and stdout
• Format Control: Skip terminal control sequences in snapshot output
• Cleanup: Add newline terminator for proper file formatting

Platform Compatibility

Cross-platform terminal support:

• Unix/Linux: Uses /dev/tty and POSIX terminal I/O
• macOS: Enhanced TTY detection with $TTY environment variable
• Windows: CON device for console output with Windows Console API
• Error Handling: Graceful fallback for unsupported operations

Integration Points

• main.c: Display subsystem initialization and lifecycle management
• protocol.c: Frame data reception and rendering requests
• server.c: Terminal capability reporting and resize handling
• options.c: Display mode configuration from command line

Error Handling

Display errors handled with graceful degradation:

• TTY Access Errors: Fall back to stdout redirection mode
• Write Errors: Log errors but continue processing
• Terminal Control Errors: Skip control sequences, continue with data
• Permission Errors: Try alternative TTY paths before failing

Author

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

Date

September 2025

Version

2.0

Definition in file display.c.