diff --git a/docs/PROJECT-STRUCTURE.md b/docs/PROJECT-STRUCTURE.md index fbd4b23..cb91103 100644 --- a/docs/PROJECT-STRUCTURE.md +++ b/docs/PROJECT-STRUCTURE.md @@ -167,8 +167,11 @@ timed-deadline waiting, frame yield, and scene reset. `engine/Age.Engine/Hosting SFX, fade, volume, and route-control contracts, including the compatibility overload/default chains used by simple hosts. `engine/Age.Engine/Hosting/IMovieHost.cs` owns ordinary, positioned, mask-transition, activity-query, and modal movie playback contracts. `IHost` inherits all four focused contracts; their required and default -behavior is unchanged. The neutral `engine/Age.Engine/Model/MovieMaskTransitionRequest.cs` record carries movie -mask work between the VM, host, and retained graphics without making `Model` depend on `Hosting`. +behavior is unchanged. `engine/Age.Engine/Hosting/IGraphicsHost.cs` owns mutable surfaces, retained-range/frame +presentation, transitions, texture lifecycle, pixel capture/replace, draw, and size contracts; `IHost` also +inherits this focused surface without changing existing hosts. The neutral +`engine/Age.Engine/Model/MovieMaskTransitionRequest.cs` record carries movie mask work between the VM, host, and +retained graphics without making `Model` depend on `Hosting`. `engine/Age.Engine/Model/RgbaImage.cs` owns the format-independent packed RGBA image transported between SYS4 decoders, host surfaces, renderers, persistence, and tests; consumers do not depend on `Sys4` merely to exchange decoded pixels. diff --git a/docs/remake-architecture-and-roadmap.md b/docs/remake-architecture-and-roadmap.md index 979be4e..f041321 100644 --- a/docs/remake-architecture-and-roadmap.md +++ b/docs/remake-architecture-and-roadmap.md @@ -786,6 +786,13 @@ do not mix mechanical moves with semantic changes. the neutral image contract; image-only format imports were removed while genuine SYS4 consumers retained theirs. Decoder and image behavior remain unchanged, and runtime validation remains green. + The sixth bounded contract slice introduced `IGraphicsHost` for mutable surface fill/copy, retained-range and + frame presentation, transition waits/fades, texture lifecycle, pixel capture/replace, drawing, and size + queries. `IHost` inherits the focused contract; all seventeen members, required implementations, default + fallbacks, and existing host classes remain behaviorally unchanged. Surface request records and the fade + direction remain in their prior locations pending a separate transport cleanup. Runtime validation remains + green. + 4. **Make the build graph express source ownership.** Stop linking production `.cs` files from `godot/` and `tools/movie-corpus-gate/` into `Age.Engine.Tests`. Extract the platform-neutral frontend/movie/diagnostic code into a small production project referenced by Godot, tests, and the corpus gate. Retain both existing @@ -1146,8 +1153,8 @@ layer's rendering diverges from ADV; save layout. ## 8. Immediate next step Continue step 3 of the **codebase consolidation** maintenance slice: clarify runtime contracts without changing behavior or the aggregate host accepted by the VM. With diagnostic, lifecycle, audio, and movie contracts -established beneath `IHost` and shared movie/image transport now neutral, introduce the graphics host contract -next. Preserve its surface, retained-range presentation, transition, texture, capture/replace, and headless-default -behavior while leaving the remaining surface request records in place for a separate transport cleanup. +established beneath `IHost`, shared movie/image transport neutral, and the graphics contract now separated, move +the unchanged `SurfaceRectFill`, `SurfaceRectCopy`, and `SurfaceBlackFadeDirection` contracts from `Hosting` to +`Model` next. Preserve all consumers and graphics behavior before separating the remaining ADV/input domains. Concrete playthrough blockers may still preempt this bounded maintenance work; the consolidation effort does not replace Phase B gameplay validation or the open cross-platform gates. diff --git a/engine/Age.Engine/Hosting/IGraphicsHost.cs b/engine/Age.Engine/Hosting/IGraphicsHost.cs new file mode 100644 index 0000000..b3edc8c --- /dev/null +++ b/engine/Age.Engine/Hosting/IGraphicsHost.cs @@ -0,0 +1,48 @@ +using Age.Engine.Model; + +namespace Age.Engine.Hosting; + +public interface IGraphicsHost +{ + void FillSurfaceRect(SurfaceRectFill fill) { } + void CopySurfaceRect(SurfaceRectCopy copy) { } + void PresentObjectRange(GfxState gfx, long firstHandle, long count) { } + + // Normal playback reaches op 0x21c and parks until a queued 0x223 transition completes. The + // read/message-skip branch reaches op 0x20c and presents the completed endpoint immediately. + void WaitForForegroundTransition(GfxState gfx) { } + void PresentFrame(GfxState gfx) { } + + // Legacy SYS4 screen-transition family (ops 0x21, 0x22, and 0x25): scripts render complete + // frames into numbered surfaces, then block while the engine alpha-composites an endpoint. + // Native bypasses the timed service when ADV fast-forward is already active at opcode dispatch. + void FadeSurfaceWithBlack( + GfxState gfx, int surface, long intervalArgument, SurfaceBlackFadeDirection direction, + bool forceEndpoint = false) { } + void CrossfadeSurfaces( + GfxState gfx, int sourceSurface, int targetSurface, long intervalArgument, + bool forceEndpoint = false) { } + + void CreateTexture(int slot, int width, int height); + + /// Return a stable RGBA snapshot of one numbered surface, or null when unavailable. + RgbaImage? CaptureSurfacePixels(int slot) => null; + + /// Replace one numbered surface from decoded RGBA pixels. False means unsupported. + bool ReplaceSurfacePixels(int slot, RgbaImage image) => false; + + void SetTexture(long resourceId, int slot); + void SetTexture(long resourceId, int slot, long colorKey) => SetTexture(resourceId, slot); + void ReleaseSurface(int slot) { } + + /// Clear the selected target's pixels; -1 denotes the main backbuffer. + void ClearRenderTarget(int surfaceSlot) { } + + void ReleaseSurfaceRange(int firstSlot, int count) + { + for (int slot = firstSlot; slot < firstSlot + count; slot++) ReleaseSurface(slot); + } + + void DrawTexture(int slot, int srcX, int srcY, int width, int height, int dstX, int dstY); + (int Width, int Height) GetTextureSize(int slot); +} diff --git a/engine/Age.Engine/Hosting/IHost.cs b/engine/Age.Engine/Hosting/IHost.cs index 55f2fd1..5ebee13 100644 --- a/engine/Age.Engine/Hosting/IHost.cs +++ b/engine/Age.Engine/Hosting/IHost.cs @@ -40,7 +40,7 @@ public enum SurfaceBlackFadeDirection ToBlack, } -public interface IHost : IDiagnosticHost, ILifecycleHost, IAudioHost, IMovieHost +public interface IHost : IDiagnosticHost, ILifecycleHost, IAudioHost, IMovieHost, IGraphicsHost { /// Present AGERc's modal full-width editor. Cancel preserves CurrentText. FullwidthTextEditResult EditFullwidthString(FullwidthTextEditRequest request) @@ -84,9 +84,6 @@ public interface IHost : IDiagnosticHost, ILifecycleHost, IAudioHost, IMovieHost void EndTextHistoryPresentation(GfxState gfx) => EndTextHistoryPresentation(); int MessageWindowAlphaSetting => 0; void SetMessageWindowAlphaSetting(int value) { } - void FillSurfaceRect(SurfaceRectFill fill) { } - void CopySurfaceRect(SurfaceRectCopy copy) { } - void PresentObjectRange(GfxState gfx, long firstHandle, long count) { } void ConfigureAdvWaitIndicator(AdvWaitIndicatorConfig config) { } // Op 0x212 supplies the ordinary retained handle used to publish the configured atlas cell. void BindAdvWaitIndicator( @@ -134,33 +131,4 @@ public interface IHost : IDiagnosticHost, ILifecycleHost, IAudioHost, IMovieHost // Optional diagnostic override. Native ReadTextDB state is VM/profile-owned; interactive hosts // normally leave this false. bool IsAdvReadSkipActive => false; - // Normal playback reaches op 0x21c and parks until a queued 0x223 transition completes. The - // read/message-skip branch reaches op 0x20c and presents the completed endpoint immediately. - void WaitForForegroundTransition(GfxState gfx) { } - void PresentFrame(GfxState gfx) { } - // Legacy SYS4 screen-transition family (ops 0x21, 0x22, and 0x25): scripts render complete - // frames into numbered surfaces, then block while the engine alpha-composites an endpoint. - // Native bypasses the timed service when ADV fast-forward is already active at opcode dispatch. - void FadeSurfaceWithBlack( - GfxState gfx, int surface, long intervalArgument, SurfaceBlackFadeDirection direction, - bool forceEndpoint = false) { } - void CrossfadeSurfaces( - GfxState gfx, int sourceSurface, int targetSurface, long intervalArgument, - bool forceEndpoint = false) { } - void CreateTexture(int slot, int width, int height); - /// Return a stable RGBA snapshot of one numbered surface, or null when unavailable. - RgbaImage? CaptureSurfacePixels(int slot) => null; - /// Replace one numbered surface from decoded RGBA pixels. False means unsupported. - bool ReplaceSurfacePixels(int slot, RgbaImage image) => false; - void SetTexture(long resourceId, int slot); - void SetTexture(long resourceId, int slot, long colorKey) => SetTexture(resourceId, slot); - void ReleaseSurface(int slot) { } - /// Clear the selected target's pixels; -1 denotes the main backbuffer. - void ClearRenderTarget(int surfaceSlot) { } - void ReleaseSurfaceRange(int firstSlot, int count) - { - for (int slot = firstSlot; slot < firstSlot + count; slot++) ReleaseSurface(slot); - } - void DrawTexture(int slot, int srcX, int srcY, int width, int height, int dstX, int dstY); - (int Width, int Height) GetTextureSize(int slot); }