mirror of
https://git.triforceproject.com/triforce/source
synced 2026-11-19 16:20:01 -04:00
Triforce v0.2.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
35
docs/capture-readback.md
Normal file
35
docs/capture-readback.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Capture copies and CPU visibility
|
||||
|
||||
Normal screenshots, generated-frame screenshots and binary frame-log slots are
|
||||
GPU-written mapped staging buffers. Their contents reach CPU consumers through
|
||||
three distinct requirements:
|
||||
|
||||
1. Record a copy-write to host-read dependency for the copied buffer range.
|
||||
2. Wait for its owning GPU submission or presentation-slot fence.
|
||||
3. Invalidate that allocation range before reading a non-coherent host cache.
|
||||
|
||||
`capture_host_read_barrier` uses COPY/TRANSFER_WRITE to HOST/HOST_READ, offset0
|
||||
and the complete copied byte count, with no queue ownership transfer. Each
|
||||
capture producer records it immediately after its copy. Existing timeline/fence
|
||||
waits remain in place. `invalidate_mapped` delegates cache atom alignment and
|
||||
coherent-memory handling to VMA.
|
||||
|
||||
`shot_pixels` owns normal screenshot bytes after the timeline wait. A pending
|
||||
screenshot already copied to CPU memory keeps using that snapshot if its parity
|
||||
slot is reused; it must not invalidate or reread the reused GPU slot. Generated
|
||||
screenshots invalidate their own allocation after the same completed value.
|
||||
Frame-log collection invalidates only a used slot after its fence wait and
|
||||
preserves timestamp, sequence and kind metadata.
|
||||
|
||||
The source-sliced regression executes the actual three copy/dependency tails
|
||||
and the CPU consumers against authored device bytes, host-domain availability
|
||||
and coherent/non-coherent caches. Four phases (normal, owned snapshot, made,
|
||||
binary log), two cache modes and two host-visibility modes give16 scenarios.
|
||||
Permissive host visibility remains a positive control; explicit visibility
|
||||
detects a missing producer dependency even on coherent memory. These models
|
||||
verify protocol and ownership, not physical non-coherent GPU memory or driver
|
||||
behavior. PNG encoding and generic device-loss/wait-error handling are outside
|
||||
this test; no performance or intended visual change is claimed.
|
||||
|
||||
References: [Khronos host readback](https://docs.vulkan.org/guide/latest/synchronization_examples.html#cpu-read-back-of-data-written-by-a-compute-shader)
|
||||
and [VMA cache management](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/memory_mapping.html).
|
||||
Reference in New Issue
Block a user