Skip to content

Commit 5d100dc

Browse files
Support more webcam resolutions
1 parent 52a4fcc commit 5d100dc

File tree

3 files changed

+352
-53
lines changed

3 files changed

+352
-53
lines changed

CLAUDE.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)