Fix : XR thread resubmits the last valid frame during stall + Eager Frame Heartbeat option

runtime/include/runtime_config.h

@@ -57,6 +57,7 @@ struct RuntimeUserConfig {
     std::optional<bool> vrStopAtDisplayCopy;
     std::optional<bool> vrSkipCopyClears;
     std::optional<std::string> vrMirrorView;
+    std::optional<bool> vrEagerFrameHeartbeat;
     std::optional<bool> vrFirstPerson;
     std::optional<float> vrFirstPersonUnitsPerMeter;
     std::optional<float> vrFirstPersonHeadUpMeters;
@@ -375,6 +376,8 @@ inline void EnsureConfigFile() {
               "# \"right\" mirror the headset's eyes, and \"none\" blacks the window\n"
               "# out. Changeable live from the F10 menu.\n"
               "mirror_view = \"normal\"\n"
+              "# Repeat at headset cadence (true), or only during stalls (false). Live.\n"
+              "eager_frame_heartbeat = false\n"
               "render_scale = 1.0\n"
               "world_units_per_meter = 500.0\n"
               "hud_distance_meters = 2.0\n"
@@ -635,6 +638,7 @@ inline RuntimeUserConfig ParseConfigDocument(const toml::value& document) {
         value && IsSupportedVrMirrorView(*value)) {
         config.vrMirrorView = *value;
     }
+    config.vrEagerFrameHeartbeat = FindConfigValue<bool>(document, "vr", "eager_frame_heartbeat");
     if (auto value = FindConfigInt(document, "vr", "first_person_hidden_model");
         value && *value >= -1 && *value <= 31) {
         config.vrFirstPersonHiddenModel = static_cast<int32_t>(*value);
@@ -936,6 +940,11 @@ inline bool SetVrMirrorView(std::string value) {
     return WriteSetting("vr", "mirror_view", FormatString(value));
 }
 
+inline bool SetVrEagerFrameHeartbeat(bool value) {
+    Mutable().vrEagerFrameHeartbeat = value;
+    return WriteSetting("vr", "eager_frame_heartbeat", value ? "true" : "false");
+}
+
 inline bool SetVrFirstPersonRotation(std::string value) {
     if (!IsSupportedVrFirstPersonRotation(value)) {
         return false;
@@ -1268,6 +1277,10 @@ inline std::string VrMirrorView(std::string fallback = kVrMirrorViewDefault) {
     return value && IsSupportedVrMirrorView(*value) ? *value : std::move(fallback);
 }
 
+inline bool VrEagerFrameHeartbeat() {
+    return Get().vrEagerFrameHeartbeat.value_or(false);
+}
+
 inline std::string VrFirstPersonRotation(std::string fallback = kVrFirstPersonRotationDefault) {
     const auto& value = Get().vrFirstPersonRotation;
     return value && IsSupportedVrFirstPersonRotation(*value) ? *value : std::move(fallback);

runtime/include/vr/openxr_d3d12.h

@@ -92,7 +92,7 @@ public:
 
     // timeout_ms == UINT32_MAX waits until Aurora publishes this token or
     // Shutdown() interrupts the wait. A timeout does not release XR images;
-    // the caller must first drain/cancel Aurora, then FinishFrame(false).
+    // the caller may keep pacing with RepeatFrame while Aurora still owns them.
     OpenXRD3D12SubmissionStatus WaitForSubmission(const OpenXRD3D12Frame& frame,
                                                   uint32_t timeout_ms = UINT32_MAX);
 
@@ -101,11 +101,17 @@ public:
     // is required to release them and close the compositor frame.
     bool TryCancelPendingFrame(OpenXRD3D12Frame& frame);
 
+    // Ends the current compositor cycle with the last completed layer and starts
+    // another, without releasing or changing Aurora's pending images/render token.
+    // The original render poses remain attached to the pending and retained images.
+    bool RepeatFrame(const OpenXRD3D12Frame& frame);
+
     // Releases acquired images and calls xrEndFrame. submit_layer must only be
     // true after WaitForSubmission returned Success. Immersive frames submit
     // XrCompositionLayerProjection; virtual-screen frames submit an
     // XrCompositionLayerQuad using the single mono target, placed as the
-    // presentation's quad_anchored/quad_pose describe.
+    // presentation's quad_anchored/quad_pose describe. If no new usable layer is
+    // available, resubmits the retained layer using the current display time.
     bool FinishFrame(OpenXRD3D12Frame& frame, bool submit_layer);
 
     // Call on the XR owner thread after Aurora's worker is idle and before

runtime/include/vr/openxr_integration.h

@@ -53,4 +53,8 @@ void OpenXRRequestRecenter() noexcept;
 // once per published frame.
 void OpenXRSetLeanBackDegrees(float degrees) noexcept;
 
+// Live pacing choice. Disabled: submit fresh frames promptly and repeat during
+// stalls. Enabled: repeat at each headset display deadline while waiting.
+void OpenXRSetEagerFrameHeartbeat(bool enabled) noexcept;
+
 } // namespace mkw::vr