Implement movie surface stop-time queries

engine/Age.Engine/Hosting/IHost.cs

@@ -15,6 +15,8 @@ public readonly record struct SurfaceRectFill(
 
 public interface IHost
 {
+    /// <summary>Report a recoverable runtime discrepancy while allowing script execution to continue.</summary>
+    void ReportWarning(string message) => System.Console.Error.WriteLine(message);
     // Script-local resource ids resolve against the currently executing frame's SYS4INI section.
     // Interactive hosts track this stack; headless hosts may keep the no-op/default identity behavior.
     void EnterScriptContext(string scriptName) { }
@@ -111,7 +113,10 @@ public interface IHost
     void FadeBgm(int targetPercent, long durationMs) { }
     // Native op 0x236 binds a DirectShow movie decoder to an existing retained texture surface.
     // Playback is non-modal: the VM advances to the following instruction while the host publishes frames.
-    void PlayMovieToSurface(long resourceId, int surfaceSlot, long movieFlags, long syncMask) { }
+    /// <returns>The initialized movie graph's stop position in truncated integer milliseconds, or null
+    /// when the host could not obtain usable timing metadata. Native op 0x23f queries this state
+    /// immediately after 0x236 returns.</returns>
+    long? PlayMovieToSurface(long resourceId, int surfaceSlot, long movieFlags, long syncMask) => null;
     // Native op 0x20f uses a universal raw-catalog id and parks script execution until the movie
     // reaches EOF or the player cancels it. The decoder remains asynchronous; the interactive host
     // owns the modal wait so its render loop can continue publishing frames.

engine/Age.Engine/Model/GfxState.cs

@@ -299,6 +299,7 @@ public sealed class GfxState
             _objects.Clear();
             _fieldTable.Clear();
             _surfaces.Clear();
+            _movieStopTimesMs.Clear();
             _surfaceTransitions.Clear();
             CurrentObject = 0;
             CurrentRenderTargetSlot = -1;
@@ -314,8 +315,32 @@ public sealed class GfxState
 
     // ---- surfaces (image buffers per slot): ctx+0x52bd4[slot], from create/set-texture ----
     private readonly Dictionary<int, (long ResId, long ColorKey)> _surfaces = new();
+    // A separate entry models the native CMovieToTexture object attached to a surface. A null value means
+    // the movie object exists but its host decoder supplied no usable IMediaPosition stop time.
+    private readonly Dictionary<int, long?> _movieStopTimesMs = new();
     private readonly Dictionary<int, SurfaceTransition> _surfaceTransitions = new();
-    public void SetSurface(int slot, long resId, long colorKey) { lock (_lock) { _surfaces[slot] = (resId, colorKey); } }
+    public void SetSurface(int slot, long resId, long colorKey)
+    {
+        lock (_lock)
+        {
+            _surfaces[slot] = (resId, colorKey);
+            _movieStopTimesMs.Remove(slot);
+        }
+    }
+
+    /// <summary>Op 0x236 handoff: retain the initialized movie graph's IMediaPosition stop time. Null
+    /// deliberately distinguishes a movie surface with unavailable metadata from an empty movie slot.</summary>
+    public void SetMovieStopTime(int slot, long? stopTimeMs)
+    {
+        lock (_lock) _movieStopTimesMs[slot] = stopTimeMs;
+    }
+
+    /// <summary>Op 0x23f query. False means no movie object occupies the slot; true with a null value
+    /// means the movie exists but its stop-time query failed or returned unusable metadata.</summary>
+    public bool TryGetMovieStopTime(int slot, out long? stopTimeMs)
+    {
+        lock (_lock) return _movieStopTimesMs.TryGetValue(slot, out stopTimeMs);
+    }
 
     /// <summary>Op 0x20d: select a surface as the D3D render target; values at or above 1000 restore the
     /// device backbuffer in the native engine.</summary>
@@ -333,6 +358,7 @@ public sealed class GfxState
             for (int slot = firstSlot; slot < end; slot++)
             {
                 _surfaces.Remove(slot);
+                _movieStopTimesMs.Remove(slot);
                 _surfaceTransitions.Remove(slot);
             }
             if (CurrentRenderTargetSlot >= firstSlot && CurrentRenderTargetSlot < end)
@@ -429,7 +455,14 @@ public sealed class GfxState
             o.ColorAnim = true;
         }
     }
-    public void ClearSurface(int slot) { lock (_lock) { _surfaces[slot] = (0, 0); } }   // create-texture (blank)
+    public void ClearSurface(int slot)
+    {
+        lock (_lock)
+        {
+            _surfaces[slot] = (0, 0); // create-texture (blank)
+            _movieStopTimesMs.Remove(slot);
+        }
+    }
 
     /// <summary>Op 0x223: queue a type-0 timed alpha transition into a target surface slot.</summary>
     public void QueueSurfaceAlphaTransition(long commandKey, int targetSlot,

engine/Age.Engine/Vm/VirtualMachine.cs

@@ -1425,7 +1425,8 @@ public sealed class VirtualMachine
                 // The native CMovieToTexture renderer replaces the pixels of the already-created surface.
                 // Retain the same resource binding so the compositor resolves live movie frames for its objects.
                 Gfx.SetSurface(surfaceSlot, resourceId, 0);
-                _host.PlayMovieToSurface(resourceId, surfaceSlot, Read(a[2]), Read(a[3]));
+                long? stopTimeMs = _host.PlayMovieToSurface(resourceId, surfaceSlot, Read(a[2]), Read(a[3]));
+                Gfx.SetMovieStopTime(surfaceSlot, stopTimeMs);
                 return pc + 1; // native cmd size 9 resumes at the next instruction; playback is asynchronous
             }
             // ---- gfx command-buffer ops (VM-internal GfxState; docs/engine-re.md op-contract table) ----
@@ -1490,8 +1491,26 @@ public sealed class VirtualMachine
                 else Write(a[0], 1);   // native missing-object path leaves output operands untouched
                 return pc + 1;
             }
-            case "u00422930":   // 0x23f query-object: (out)(handle) <- 0 if the object exists, else -1
-                Write(a[0], Gfx.TryGet(Read(a[1])) != null ? 0 : -1); return pc + 1;
+            case "u00422930":                    // pre-reference compatibility
+            case "query-surface-stop-time-ms":   // 0x23f (out_stop_time_ms)(surface_slot)
+            {
+                int surfaceSlot = (int)Read(a[1]);
+                if (!Gfx.TryGetMovieStopTime(surfaceSlot, out long? stopTimeMs))
+                {
+                    Write(a[0], -1); // native null CMovieToTexture slot
+                    return pc + 1;
+                }
+                if (!stopTimeMs.HasValue)
+                {
+                    _host.ReportWarning(
+                        $"movie stop-time unavailable {_cur.Script.Name}@0x{ins.Offset:x} " +
+                        $"surface={surfaceSlot}; returning -1");
+                    Write(a[0], -1);
+                    return pc + 1;
+                }
+                Write(a[0], stopTimeMs.Value);
+                return pc + 1;
+            }
             case "set-gfx-geom3-c":     // 0x1ff: set current translation matrix
                 Gfx.SetCurrentTranslation(Read(a[0]), (Read(a[1]), Read(a[2]), Read(a[3]))); return pc + 1;
             case "u00420620":             // upstream ABI label