Files
Triforce-Source/docs/presentation-source-crop.md
ruckus7382sfgsgdf 34b3683441 Triforce v0.2.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:32:48 -06:00

26 lines
1.6 KiB
Markdown

# Presentation source crops
Direct presentation, capture, scaling and interpolation must sample the same valid
source region. `present_source_rect` is the common contract, independent of Vulkan:
- A null crop, or either nonpositive crop extent, selects the entire image, preserving
the existing convention even when the unused origin fields are negative.
- An active crop with a negative or out-of-image origin is empty.
- Positive extents are clipped to the remaining source area by subtraction before
addition. `x + width` in guest input must not overflow a signed integer.
- Empty sources and dimensions beyond signed 32-bit image offsets are rejected.
The content-aspect calculation uses the same clipped region. Direct/capture blits
clear their destination to opaque black for an empty source region instead of issuing
an invalid Vulkan blit or copying undefined pixels. Zero destination extent records
nothing. Scaling/interpolation decline an invalid crop before setup or allocation;
ordinary presentation supplies the black fallback. Valid crops retain their offsets,
filter and destination rectangle.
`tests/test_present_source_crop.py` executes the production blit, capture wrapper and
complete interpolation recorder with CPU API spies. It checks the command offsets,
interpolation copy push constants, clipped allocation size, invalid-input clear/skip,
full-image convention and thousands of deterministic edge-crossing crops. It needs
Vulkan headers and a C++20 compiler, but no GPU or game data. The independent scaler
fixture separately executes the production scaling function.