capture.c File Reference

📹 Client webcam capture: dedicated capture thread with frame rate limiting and network transmission More...

Go to the source code of this file.

Macros
#define	MAX_FRAME_WIDTH   480
#define	MAX_FRAME_HEIGHT   270

Functions
	__attribute__ ((unused))
	Webcam capture thread handle.
int	capture_init ()
	Initialize capture subsystem.
int	capture_start_thread ()
	Start capture thread.
void	capture_stop_thread ()
	Stop capture thread.
bool	capture_thread_exited ()
	Check if capture thread has exited.
void	capture_cleanup ()
	Cleanup capture subsystem.

Detailed Description

📹 Client webcam capture: dedicated capture thread with frame rate limiting and network transmission

The capture system follows a producer-consumer pattern:

• Producer: Webcam capture thread reads frames from camera
• Processing: Frame resizing and format conversion pipeline
• Consumer: Network transmission thread sends processed frames
• Rate Limiting: Frame rate control to prevent bandwidth overload

Threading Model

Capture operations run in a dedicated thread:

• Main Thread: Manages thread lifecycle and coordination
• Capture Thread: Continuous frame capture and processing loop
• Synchronization: Atomic flags coordinate thread shutdown
• Resource Management: Clean webcam and memory resource cleanup

Frame Processing Pipeline

Raw webcam frames undergo comprehensive processing:

1. Capture: Read raw frame from webcam device
2. Validation: Check frame validity and dimensions
3. Aspect Ratio: Calculate optimal resize dimensions
4. Resizing: Scale frame to network-optimal size (800x600 max)
5. Serialization: Pack frame data into network packet format
6. Transmission: Send via IMAGE_FRAME packet to server

Frame Rate Management

Implements intelligent frame rate limiting:

• Capture Rate: 144 FPS to support high-refresh displays (~6.9ms intervals)
• Timing Control: Monotonic clock for accurate frame intervals
• Adaptive Delays: Dynamic sleep adjustment for consistent timing
• Display Support: High capture rate enables smooth playback on promotion displays

Image Resizing Strategy

Optimizes frame size for network efficiency:

• Maximum Dimensions: 800x600 pixels for reasonable bandwidth
• Aspect Ratio Preservation: Maintain original camera aspect ratio
• Intelligent Scaling: Fit-to-bounds algorithm for optimal sizing
• Quality Balance: Large enough for server flexibility, small enough for efficiency

Packet Format and Transmission

Frame data serialized for network transmission:

• Header: Width and height as 32-bit network byte order integers
• Payload: RGB pixel data as continuous byte array
• Size Limits: Enforce maximum packet size for protocol compliance
• Error Handling: Graceful handling of oversized frames

Platform Compatibility

Uses webcam abstraction layer for cross-platform support:

• Linux: Video4Linux2 (V4L2) webcam interface
• macOS: AVFoundation framework integration
• Windows: DirectShow API wrapper (stub implementation)
• Fallback: Test pattern generation when webcam unavailable

Integration Points

• main.c: Capture subsystem lifecycle management
• server.c: Network packet transmission and connection monitoring
• webcam.c: Low-level webcam device interface and frame reading
• image.c: Image processing and memory management functions

Error Handling

Capture errors handled with appropriate recovery:

• Device Errors: Webcam unavailable or device busy (continue with warnings)
• Memory Errors: Frame allocation failures (skip frame, continue)
• Network Errors: Transmission failures (trigger connection loss detection)
• Processing Errors: Invalid frames or resize failures (skip and retry)

Resource Management

Careful resource lifecycle management:

• Webcam Device: Proper initialization and cleanup
• Frame Buffers: Automatic memory management with leak prevention
• Thread Resources: Clean thread termination and resource release
• Network Buffers: Efficient packet buffer allocation and cleanup

Author

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

Date

2025

Definition in file capture.c.

Macro Definition Documentation

MAX_FRAME_HEIGHT

#define MAX_FRAME_HEIGHT   270

MAX_FRAME_WIDTH

#define MAX_FRAME_WIDTH   480