@@ -66,6 +66,52 @@ The OS supports:
6666- Platform detection via ` sys.platform ` ("esp32" vs others)
6767- Different boot files per hardware variant (boot_fri3d-2024.py, etc.)
6868
69+ ### Webcam Module (Desktop Only)
70+
71+ The ` c_mpos/src/webcam.c ` module provides webcam support for desktop builds using the V4L2 API.
72+
73+ ** Resolution Adaptation** :
74+ - Automatically queries supported YUYV resolutions from the webcam using V4L2 API
75+ - Supports all 23 ESP32 camera resolutions via intelligent cropping/padding
76+ - ** Center cropping** : When requesting smaller than available (e.g., 240x240 from 320x240)
77+ - ** Black border padding** : When requesting larger than maximum supported
78+ - Always returns exactly the requested dimensions for API consistency
79+
80+ ** Behavior** :
81+ - On first init, queries device for supported resolutions using ` VIDIOC_ENUM_FRAMESIZES `
82+ - Selects smallest capture resolution ≥ requested dimensions (minimizes memory/bandwidth)
83+ - Converts YUYV to RGB565 (color) or grayscale during capture
84+ - Caches supported resolutions to avoid re-querying device
85+
86+ ** Examples** :
87+
88+ * Cropping (common case)* :
89+ - Request: 240x240 (not natively supported)
90+ - Capture: 320x240 (nearest supported YUYV resolution)
91+ - Process: Extract center 240x240 region
92+ - Result: 240x240 frame with centered content
93+
94+ * Padding (rare case)* :
95+ - Request: 1920x1080
96+ - Capture: 1280x720 (webcam maximum)
97+ - Process: Center 1280x720 content in 1920x1080 buffer with black borders
98+ - Result: 1920x1080 frame (API contract maintained)
99+
100+ ** Performance** :
101+ - Exact matches use fast path (no cropping overhead)
102+ - Cropped resolutions add ~ 5-10% CPU overhead
103+ - Padded resolutions add ~ 3-5% CPU overhead (memset + center placement)
104+ - V4L2 buffers sized for capture resolution, conversion buffers sized for output
105+
106+ ** Implementation Details** :
107+ - YUYV format: 2 pixels per macropixel (4 bytes: Y0 U Y1 V)
108+ - Crop offsets must be even for proper YUYV alignment
109+ - Center crop formula: ` offset = (capture_dim - output_dim) / 2 ` , then align to even
110+ - Supported resolutions cached in ` supported_resolutions_t ` structure
111+ - Separate tracking of ` capture_width/height ` (from V4L2) vs ` output_width/height ` (user requested)
112+
113+ ** File Location** : ` c_mpos/src/webcam.c ` (C extension module)
114+
69115## Build System
70116
71117### Building Firmware
0 commit comments