feat(render): add optional two-step precise sync

entry/src/main/ets/model/StreamConfig.ets

@@ -91,6 +91,7 @@ export interface StreamConfig {
   enableSyncDecode: boolean;  // 同步解码模式（API 20+，主动轮询 + 仅渲染最新输出帧，低延迟优先）
   enableVrr: boolean;         // VRR 可变刷新率模式（动态调整屏幕刷新率，可能丢帧）
   enableVsync: boolean;       // VSync 渲染模式（按时间戳精确呈现，更平滑但可能增加延迟）
+  enableTwoStepPreciseSync: boolean; // 二步精确同步（host 节奏去抖 + 本地 VSync 对齐）
   enablePostProcess: boolean; // 后处理滤镜（HDR 暗区抖动补偿，适用于 OLED 面板）
   upscaleMode: number;        // 超分辨率模式 (0=OFF, 1=XENGINE, 2=FSR1, 3=AUTO)
   upscaleSharpness: number;   // 超分锐度 (0.0 - 1.0)
@@ -277,6 +278,7 @@ export function getDefaultStreamConfig(): StreamConfig {
     enableSyncDecode: false, // 默认禁用同步解码（需要 API 20+；启用后低延迟优先）
     enableVrr: false,       // 默认禁用 VRR（可能丢帧）
     enableVsync: false,     // 默认关闭（低延迟优先；开启后更平滑但可能增加 1 帧左右延迟）
+    enableTwoStepPreciseSync: false, // 默认关闭，便于与原 VSync 路径做 A/B 对比
     enablePostProcess: false, // 默认禁用后处理滤镜
     upscaleMode: 0,           // 默认不超分
     upscaleSharpness: 0.5,    // 默认锐度 50%

entry/src/main/ets/pages/SettingsPageV2.ets

@@ -238,6 +238,7 @@ struct SettingsPageV2 {
   @State enableSyncDecode: boolean = false;  // 同步解码模式，默认禁用
   @State enableVrr: boolean = false;  // VRR 可变刷新率，默认禁用
   @State enableVsync: boolean = false;
+  @State enableTwoStepPreciseSync: boolean = false;
   @State enablePostProcess: boolean = false;  // 后处理滤镜（暗区抖动补偿）
   @State upscaleMode: number = 0;             // 超分辨率模式
   @State upscaleSharpness: number = 50;       // 超分锐度 (0-100)
@@ -589,6 +590,7 @@ struct SettingsPageV2 {
       this.enableSyncDecode = await this.loadBoolean(SettingsKeys.ENABLE_SYNC_DECODE, false);  // 默认禁用
       this.enableVrr = await this.loadBoolean(SettingsKeys.ENABLE_VRR, false);  // VRR 默认禁用
       this.enableVsync = await this.loadBoolean(SettingsKeys.ENABLE_VSYNC, false);
+      this.enableTwoStepPreciseSync = await this.loadBoolean(SettingsKeys.ENABLE_TWO_STEP_PRECISE_SYNC, false);
       this.enablePostProcess = await this.loadBoolean(SettingsKeys.ENABLE_POST_PROCESS, false);
       this.upscaleMode = await PreferencesUtil.get<number>(SettingsKeys.UPSCALE_MODE, 0);
       this.upscaleSharpness = await PreferencesUtil.get<number>(SettingsKeys.UPSCALE_SHARPNESS, 50);
@@ -2110,6 +2112,16 @@ struct SettingsPageV2 {
                   this.saveSetting(SettingsKeys.ENABLE_VSYNC, this.enableVsync);
                 }
               },
+              {
+                title: '二步精确同步 (实验性)',
+                subtitle: '先跟随主机出帧节奏，再对齐本地屏幕刷新',
+                type: 'toggle',
+                value: this.enableTwoStepPreciseSync,
+                action: () => {
+                  this.enableTwoStepPreciseSync = !this.enableTwoStepPreciseSync;
+                  this.saveSetting(SettingsKeys.ENABLE_TWO_STEP_PRECISE_SYNC, this.enableTwoStepPreciseSync);
+                }
+              },
               {
                 title: '性能模式',
                 subtitle: '优化线程优先级和系统资源调度',

entry/src/main/ets/service/SettingsService.ets

@@ -134,6 +134,7 @@ export class SettingsKeys {
   static readonly ENABLE_SYNC_DECODE: string = 'settings_enable_sync_decode';  // 同步解码模式
   static readonly ENABLE_VRR: string = 'settings_enable_vrr';  // VRR 可变刷新率模式
   static readonly ENABLE_VSYNC: string = 'settings_enable_vsync';
+  static readonly ENABLE_TWO_STEP_PRECISE_SYNC: string = 'settings_enable_two_step_precise_sync';
   static readonly ADAPTIVE_BITRATE: string = 'settings_adaptive_bitrate';  // 智能码率调节
   static readonly ABR_MODE: string = 'settings_abr_mode';  // ABR 模式: balanced | quality | lowLatency
   static readonly ENABLE_POST_PROCESS: string = 'settings_enable_post_process';  // 后处理滤镜
@@ -639,6 +640,7 @@ export class SettingsService {
     const enableSyncDecode = await this.getBoolean(SettingsKeys.ENABLE_SYNC_DECODE, false);  // 默认禁用
     const enableVrr = await this.getBoolean(SettingsKeys.ENABLE_VRR, false);  // VRR 默认禁用
     const enableVsync = await this.getBoolean(SettingsKeys.ENABLE_VSYNC, false);
+    const enableTwoStepPreciseSync = await this.getBoolean(SettingsKeys.ENABLE_TWO_STEP_PRECISE_SYNC, false);
     const enablePostProcess = await this.getBoolean(SettingsKeys.ENABLE_POST_PROCESS, false);
     const upscaleMode = await this.getNumber(SettingsKeys.UPSCALE_MODE, 0);
     const upscaleSharpness = await this.getNumber(SettingsKeys.UPSCALE_SHARPNESS, 50) / 100.0;
@@ -729,6 +731,7 @@ export class SettingsService {
       enableSyncDecode: enableSyncDecode,
       enableVrr: enableVrr,
       enableVsync: enableVsync,
+      enableTwoStepPreciseSync: enableTwoStepPreciseSync,
       enablePostProcess: enablePostProcess,
       sdrToHdrMode: sdrToHdrMode,
       sdrToHdr: sdrToHdr,

entry/src/main/ets/service/streaming/StreamingSession.ets

@@ -136,6 +136,7 @@ interface NativeModule {
   isDecoderSyncMode(): boolean;
   setVsyncEnabled(enabled: boolean): void;
   isVsyncEnabled(): boolean;
+  setTwoStepPreciseSyncEnabled(enabled: boolean): void;
   setVrrEnabled(enabled: boolean): void;
   setPostProcessEnabled(enabled: boolean): void;
   setUpscaleMode(mode: number, sharpness: number): void;
@@ -1283,6 +1284,7 @@ export class StreamingSession {
     this.nativeModule.setDecoderBufferCount(this.config.decoderBufferCount);
     this.nativeModule.setDecoderSyncMode(this.config.enableSyncDecode);
     this.nativeModule.setVsyncEnabled(this.config.enableVsync);
+    this.nativeModule.setTwoStepPreciseSyncEnabled(this.config.enableTwoStepPreciseSync ?? false);
     this.nativeModule.setVrrEnabled(this.config.enableVrr);
     this.nativeModule.setPostProcessEnabled(this.config.enablePostProcess ?? false);
     this.nativeModule.setUpscaleMode(this.config.upscaleMode ?? 0, this.config.upscaleSharpness ?? 0.5);
@@ -1293,7 +1295,8 @@ export class StreamingSession {
     }
 
     console.info(`解码器: buffers=${this.config.decoderBufferCount}, sync=${this.config.enableSyncDecode}, ` +
-      `vsync=${this.config.enableVsync}, vrr=${this.config.enableVrr}`);
+      `vsync=${this.config.enableVsync}, twoStep=${this.config.enableTwoStepPreciseSync ?? false}, ` +
+      `vrr=${this.config.enableVrr}`);
 
     const callStart = async (): Promise<number> => {
       this.isStartingConnection = true;

nativelib/src/main/cpp/callbacks.cpp

@@ -702,7 +702,8 @@ int BridgeDrSubmitDecodeUnit(void* decodeUnitPtr) {
         totalSize,
         decodeUnit->frameNumber, 
         decodeUnit->frameType,
-        decodeUnit->frameHostProcessingLatency
+        decodeUnit->frameHostProcessingLatency,
+        static_cast<int64_t>(decodeUnit->presentationTimeUs)
     );
 
     if (heapAllocated) {

nativelib/src/main/cpp/moonlight_bridge.cpp

@@ -1998,6 +1998,25 @@ napi_value MoonBridge_IsVsyncEnabled(napi_env env, napi_callback_info info) {
     return result;
 }
 
+napi_value MoonBridge_SetTwoStepPreciseSyncEnabled(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value args[1];
+    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
+
+    bool enabled = false;
+    if (argc >= 1) {
+        napi_get_value_bool(env, args[0], &enabled);
+    }
+
+    NativeRender::GetInstance()->SetTwoStepPreciseSyncEnabled(enabled);
+    OH_LOG_INFO(LOG_APP, "MoonBridge_SetTwoStepPreciseSyncEnabled: %{public}s",
+                enabled ? "true" : "false");
+
+    napi_value result;
+    napi_get_undefined(env, &result);
+    return result;
+}
+
 // =============================================================================
 // 音频设置
 // =============================================================================

nativelib/src/main/cpp/moonlight_bridge.h

@@ -272,6 +272,12 @@ napi_value MoonBridge_SetVsyncEnabled(napi_env env, napi_callback_info info);
  */
 napi_value MoonBridge_IsVsyncEnabled(napi_env env, napi_callback_info info);
 
+/**
+ * 设置是否启用二步精确同步（内部自行使用 VSync）。
+ * @param enabled boolean
+ */
+napi_value MoonBridge_SetTwoStepPreciseSyncEnabled(napi_env env, napi_callback_info info);
+
 // =============================================================================
 // 音频设置
 // =============================================================================

nativelib/src/main/cpp/napi_init.cpp

@@ -130,6 +130,7 @@ static napi_value Init(napi_env env, napi_value exports) {
         { "isDecoderSyncMode", nullptr, MoonBridge_IsDecoderSyncMode, nullptr, nullptr, nullptr, napi_default, nullptr },
         { "setVsyncEnabled", nullptr, MoonBridge_SetVsyncEnabled, nullptr, nullptr, nullptr, napi_default, nullptr },
         { "isVsyncEnabled", nullptr, MoonBridge_IsVsyncEnabled, nullptr, nullptr, nullptr, napi_default, nullptr },
+        { "setTwoStepPreciseSyncEnabled", nullptr, MoonBridge_SetTwoStepPreciseSyncEnabled, nullptr, nullptr, nullptr, napi_default, nullptr },
         { "setVrrEnabled", nullptr, MoonBridge_SetVrrEnabled, nullptr, nullptr, nullptr, napi_default, nullptr },
         { "setPostProcessEnabled", nullptr, MoonBridge_SetPostProcessEnabled, nullptr, nullptr, nullptr, napi_default, nullptr },
         { "setUpscaleMode", nullptr, MoonBridge_SetUpscaleMode, nullptr, nullptr, nullptr, napi_default, nullptr },