bug(debug-ui): frame-time and FPS graph use render-only total #1077

Closed
opened 2026-11-07 03:28:22 +00:00 by SakulFlee · 0 comments
Owner

Summary

total is measured from t_realize_start, which happens after the update phase and after surface lock/acquire/view. The actual frame period is therefore approximately:

frame ≈ update + surface_acq + total

But TOTAL_STAGE_INDEX is documented as "the whole-frame duration", the debug graph labels it "frame time", and fps_values() computes 1000.0 / total.

Evidence

  • Windows capture: update 0.336 + surface 1.998 + total 4.018 = 6.35 ms, versus cdt 6.46 ms. The graph would report ~249 FPS from 4.02 ms, while the real FPS is ~155.
  • Linux 55-row capture: update 0.262 + surface 10.488 + total 2.579 = 13.33 ms, versus cdt 13.37 ms. The graph would report ~388 FPS, while the real FPS is ~75.
  • Android phone capture: update 13.62 + surface 0.61 + total 106.47 = 120.70 ms, versus cdt 120.38 ms. The graph would report ~9.4 FPS, while the real FPS is ~8.
  • The CSV's fps column is correct; the graph is not.

Fix direction

  • Add an explicit frame_total (update + surface_acq + total plus event-loop overhead) and keep render_total if needed.
  • Or include update and surface acquisition in total and add separate update/render-only stages.
  • Use the real timer FPS for the FPS graph instead of deriving FPS from render total.
  • Update the CSV schema, debug labels, docs, and tests together.

Acceptance criteria

  • The "frame time" graph matches the actual frame period within timer resolution.
  • The "FPS" graph matches the CSV fps column.
  • update, surface_acq, and total are no longer double-counted or mislabeled.
## Summary `total` is measured from `t_realize_start`, which happens after the update phase and after surface lock/acquire/view. The actual frame period is therefore approximately: ```text frame ≈ update + surface_acq + total ``` But `TOTAL_STAGE_INDEX` is documented as "the whole-frame duration", the debug graph labels it "frame time", and `fps_values()` computes `1000.0 / total`. ## Evidence - Windows capture: update 0.336 + surface 1.998 + total 4.018 = 6.35 ms, versus cdt 6.46 ms. The graph would report ~249 FPS from 4.02 ms, while the real FPS is ~155. - Linux 55-row capture: update 0.262 + surface 10.488 + total 2.579 = 13.33 ms, versus cdt 13.37 ms. The graph would report ~388 FPS, while the real FPS is ~75. - Android phone capture: update 13.62 + surface 0.61 + total 106.47 = 120.70 ms, versus cdt 120.38 ms. The graph would report ~9.4 FPS, while the real FPS is ~8. - The CSV's `fps` column is correct; the graph is not. ## Fix direction - Add an explicit `frame_total` (`update + surface_acq + total` plus event-loop overhead) and keep `render_total` if needed. - Or include update and surface acquisition in `total` and add separate update/render-only stages. - Use the real timer FPS for the FPS graph instead of deriving FPS from render total. - Update the CSV schema, debug labels, docs, and tests together. ## Acceptance criteria - The "frame time" graph matches the actual frame period within timer resolution. - The "FPS" graph matches the CSV `fps` column. - `update`, `surface_acq`, and `total` are no longer double-counted or mislabeled.
SakulFlee changed title from bug(debug-ui): frame-time and FPS graph exclude surface acquisition to bug(debug-ui): frame-time and FPS graph use render-only total 2026-11-07 03:43:57 +00:00
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
SakulFlee/Orbital#1077
No description provided.