conco/OpenMaidEngine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

engine: materialize live ADV glyphs

Browse Source
This commit is contained in:
gamer147
2026-07-30 19:04:22 -04:00
parent eec99c2c7c
commit e5b4db5eff
15 changed files with 758 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
engine/Age.Engine.Tests/AdvTextOpsTests.cs
View File

@@ -216,6 +216,48 @@ public class AdvTextOpsTests
host.LiveTextRuns.Select(emitted => emitted.Run.Text));
}
[Fact]
public void RetainedGlyphMetricsAdvanceCanonicalCursorBetweenRuns()
{
var table = OpcodeTableJson.Load(Paths.OpcodesJson);
static Operand I(long value) => new(0, value);
static Operand S(int index) => new(2, index);
var script = ScriptAssembler.Assemble(table, "RETAINED_CURSOR",
new List<(int, Operand[])>
{
(0x70, new[] { I(1), I(100), I(50), I(10), I(20) }),
(0x79, new[] { I(1), I(2), I(3) }),
(0x71, new[] { I(1) }),
(0x213, new[] { I(1), I(100), I(10) }),
(0x6e, new[] { I(0), S(0) }),
(0x6e, new[] { I(0), S(1) }),
(0x2, Array.Empty<Operand>()),
},
new[] { "A", "BC" });
var host = new RecordingHost
{
OnRetainedText = run => new AdvRetainedTextRunResult(
run.Layout.Slot,
FirstGlyphIndex: 0,
GlyphCount: run.Text.Length,
CursorX: run.Layout.CursorX + run.Text.Length * 4,
CursorY: run.Layout.CursorY),
};
var vm = new VirtualMachine(script, table, host);
vm.Run();
Assert.Equal(new[] { (2, 3), (6, 3) },
host.LiveTextRuns.Select(run =>
(run.Run.Layout.CursorX, run.Run.Layout.CursorY)));
Assert.Equal(new[] { (2, 3), (6, 3) },
vm.TextHistory.Records.Select(record =>
(record.Layout.CursorX, record.Layout.CursorY)));
Assert.Equal((14, 3),
(vm.TextHistory.GetLayoutSnapshot(1).CursorX,
vm.TextHistory.GetLayoutSnapshot(1).CursorY));
}
[Fact]
public void RealMamesResearchDescriptionUsesImmediateRetainedTextPath()
{

2
engine/Age.Engine.Tests/NativeNumberedSaveCodecTests.cs
View File

@@ -116,7 +116,7 @@ public class NativeNumberedSaveCodecTests
new AdvTextLayoutSnapshot(3, 320, 90, 20, 400, 0, 0, 300, 80),
liveHistory.GetLayoutSnapshot(3));
Assert.Equal(
new AdvTextLayoutPresentationBinding(3, 0x17, 0x2000, 500, 0x1234),
new AdvTextLayoutPresentationBinding(3, 0x17, 0x2000, 500, 0x1234, 45, 42),
liveHistory.GetPresentationBinding(3));
}

116
engine/Age.Engine.Tests/RetainedAdvTextLayoutPresentationTests.cs Normal file
View File

@@ -0,0 +1,116 @@
using Age.Engine.Model;
using Age.Engine.Text;
public class RetainedAdvTextLayoutPresentationTests
{
[Fact]
public void PublishesNativeRectsInHandleOrderAndStopsAtCapacity()
{
var binding = new AdvTextLayoutPresentationBinding(
1, 21, 100, 2, 900, 10, 20);
var presentation = new RetainedAdvTextLayoutPresentation(binding);
presentation.Append(
[
new AdvRetainedGlyphRecord(0, 1, 2, 5, 8),
new AdvRetainedGlyphRecord(0, 5, 2, 9, 8),
],
layoutOriginX: 30,
layoutOriginY: 40);
presentation.Append(
[new AdvRetainedGlyphRecord(0, 10, 3, 14, 9)],
layoutOriginX: 50,
layoutOriginY: 60);
var gfx = new GfxState();
gfx.CreateSurface(21);
Assert.Equal(2, presentation.PublishThrough(gfx, 3));
Assert.Collection(
gfx.SnapshotVisibleObjects(),
first => Assert.Equal(
(100L, 1, 2, 4, 6, 31, 42),
(first.Handle, first.SrcX, first.SrcY, first.W, first.H,
first.DstX, first.DstY)),
second => Assert.Equal(
(101L, 5, 2, 4, 6, 35, 42),
(second.Handle, second.SrcX, second.SrcY, second.W, second.H,
second.DstX, second.DstY)));
Assert.Null(gfx.TryGet(102));
}
[Fact]
public void RepublishRestoresPartialEraseWithoutAdvancingReveal()
{
var presentation = Presentation(capacity: 4);
var gfx = new GfxState();
gfx.CreateSurface(21);
presentation.PublishThrough(gfx, 2);
gfx.EraseRange(101, 1);
Assert.Single(gfx.SnapshotVisibleObjects());
Assert.Equal(2, presentation.Republish(gfx));
Assert.Equal(new long[] { 100, 101 },
gfx.SnapshotVisibleObjects().Select(item => item.Handle));
presentation.ErasePublished(gfx);
Assert.Empty(gfx.SnapshotVisibleObjects());
Assert.Equal(2, presentation.PublishedGlyphCount);
}
[Fact]
public void ConsecutiveRunsRetainTheirOwnLayoutOrigins()
{
var binding = new AdvTextLayoutPresentationBinding(
7, 27, 200, 10, -1, 53, 10);
var presentation = new RetainedAdvTextLayoutPresentation(binding);
presentation.Append(
[new AdvRetainedGlyphRecord(0, 3, 4, 7, 10)],
275, 90);
presentation.Append(
[new AdvRetainedGlyphRecord(0, 7, 4, 11, 10)],
275, 135);
var gfx = new GfxState();
gfx.CreateSurface(27);
presentation.PublishThrough(gfx, 2);
Assert.Equal(
new[] { (278, 94), (282, 139) },
gfx.SnapshotVisibleObjects().Select(item => (item.DstX, item.DstY)));
}
[Fact]
public void SavedFrameStyleReconstructionRebuildsTheSameBindings()
{
RetainedAdvTextLayoutPresentation before = Presentation(capacity: 4);
var gfx = new GfxState();
gfx.CreateSurface(21);
before.PublishThrough(gfx, 3);
RenderObject[] expected = gfx.SnapshotVisibleObjects().ToArray();
gfx.EraseRange(
before.Binding.FirstObjectHandle,
before.Binding.ObjectCapacity);
RetainedAdvTextLayoutPresentation reconstructed =
Presentation(capacity: 4);
reconstructed.PublishThrough(gfx, 3);
Assert.Equal(expected, gfx.SnapshotVisibleObjects());
}
private static RetainedAdvTextLayoutPresentation Presentation(int capacity)
{
var presentation = new RetainedAdvTextLayoutPresentation(
new AdvTextLayoutPresentationBinding(
1, 21, 100, capacity, -1, 10, 20));
presentation.Append(
[
new AdvRetainedGlyphRecord(0, 1, 2, 5, 8),
new AdvRetainedGlyphRecord(0, 5, 2, 9, 8),
new AdvRetainedGlyphRecord(0, 9, 2, 13, 8),
],
30,
40);
return presentation;
}
}

10
engine/Age.Engine.Tests/TestSupport.cs
View File

@@ -95,6 +95,16 @@ internal class RecordingHost : IHost
Lines.Add((run.SourceOffset, run.Text));
LiveTextRuns.Add((run, glyphDelayMilliseconds));
}
public Func<AdvLiveTextRun, AdvRetainedTextRunResult?>? OnRetainedText;
public virtual AdvRetainedTextRunResult? ShowText(
GfxState gfx,
AdvTextLayoutPresentationBinding binding,
AdvLiveTextRun run,
int glyphDelayMilliseconds)
{
ShowText(run, glyphDelayMilliseconds);
return OnRetainedText?.Invoke(run);
}
public void SetMessageGlyphDelayMilliseconds(int milliseconds)
=> MessageGlyphDelayMilliseconds = milliseconds;
public RgbaImage? CaptureSurfacePixels(int slot)

17
engine/Age.Engine/Hosting/IHost.cs
View File

@@ -64,6 +64,15 @@ public interface IHost
void ShowText(int offset, string text);
void ShowText(AdvLiveTextRun run, int glyphDelayMilliseconds)
=> ShowText(run.SourceOffset, run.Text);
AdvRetainedTextRunResult? ShowText(
GfxState gfx,
AdvTextLayoutPresentationBinding binding,
AdvLiveTextRun run,
int glyphDelayMilliseconds)
{
ShowText(run, glyphDelayMilliseconds);
return null;
}
int MessageGlyphDelayMilliseconds => 50;
void SetMessageGlyphDelayMilliseconds(int milliseconds) { }
// Native ADV text subsystem: op 0x7a updates the selected layout's last 20-byte cursor record;
@@ -73,6 +82,9 @@ public interface IHost
void DrawStringToSurface(int surfaceSlot, int x, int y, string text, AdvTextStyle style)
=> DrawStringToSurface(surfaceSlot, x, y, text);
void ClearRenderedAdvTextLayout(int layoutSlot) { }
void ResetRenderedAdvTextLayout(
GfxState gfx, AdvTextLayoutPresentationBinding binding)
=> ClearRenderedAdvTextLayout(binding.LayoutSlot);
void RenderTextHistory(AdvTextHistoryRenderBatch batch) { }
// History render batches are transient bindings, unlike the retained backlog itself. HISTORY.BIN's
// recording re-enable at exit ends that presentation and drops every bound target layout.
@@ -87,10 +99,15 @@ public interface IHost
void SetAdvWaitIndicatorEnabled(bool enabled) { }
// Op 0x20a republishes one retained ADV text layout and includes the current marker frame when active.
void PublishAdvTextLayout(int layoutSlot) { }
void PublishAdvTextLayout(
GfxState gfx, AdvTextLayoutPresentationBinding binding)
=> PublishAdvTextLayout(binding.LayoutSlot);
// Op 0x199 temporarily yields the active ADV page into its registered hide-window coroutine.
// The retained scene continues to render, but the text layout and its wait marker are suspended
// until op 0x7c restores the saved page PC.
void SetAdvPagePresentationSuspended(bool suspended) { }
void SetAdvPagePresentationSuspended(GfxState gfx, bool suspended)
=> SetAdvPagePresentationSuspended(suspended);
void WaitForInput();
void WaitForInput(int layoutSlot) => WaitForInput();
// Interactive hosts service script callbacks on the VM thread while the enclosing ADV page remains

16
engine/Age.Engine/Model/AdvRetainedTextContract.cs
View File

@@ -30,7 +30,21 @@ public readonly record struct AdvTextLayoutPresentationBinding(
int SourceSurfaceSlot,
long FirstObjectHandle,
long ObjectCapacity,
long WaitIndicatorObjectHandle);
long WaitIndicatorObjectHandle,
int ResetCursorX,
int ResetCursorY);
public readonly record struct AdvRetainedGlyphPlacement(
AdvRetainedGlyphRecord Record,
int LayoutOriginX,
int LayoutOriginY);
public readonly record struct AdvRetainedTextRunResult(
int LayoutSlot,
int FirstGlyphIndex,
int GlyphCount,
int CursorX,
int CursorY);
/// <summary>Platform-neutral rules established from AGE's native retained-glyph workers.</summary>
public static class AdvRetainedTextContract

3
engine/Age.Engine/Model/AdvTextHistory.cs
View File

@@ -201,7 +201,8 @@ public sealed class AdvTextHistory
var layout = GetOrCreateLayout(slot);
return new AdvTextLayoutPresentationBinding(
slot, checked(slot + 0x14), layout.TextObjectRangeFirst,
layout.TextObjectRangeCount, layout.WaitIndicatorObjectHandle);
layout.TextObjectRangeCount, layout.WaitIndicatorObjectHandle,
layout.ResetCursorX, layout.ResetCursorY);
}
/// <summary>

86
engine/Age.Engine/Text/RetainedAdvTextLayoutPresentation.cs Normal file
View File

@@ -0,0 +1,86 @@
using Age.Engine.Model;
namespace Age.Engine.Text;
/// <summary>
/// Transient live-layout presentation state. History persistence owns neither this list nor its Gfx
/// bindings; saved-frame script reconstruction rebuilds both.
/// </summary>
public sealed class RetainedAdvTextLayoutPresentation
{
private readonly List<AdvRetainedGlyphPlacement> _glyphs = new();
public RetainedAdvTextLayoutPresentation(AdvTextLayoutPresentationBinding binding)
{
if (binding.LayoutSlot <= 0)
throw new ArgumentOutOfRangeException(nameof(binding));
if (binding.SourceSurfaceSlot < 0)
throw new ArgumentOutOfRangeException(nameof(binding));
if (binding.FirstObjectHandle < 0 || binding.ObjectCapacity <= 0)
throw new ArgumentException(
"A retained ADV layout requires a nonnegative first handle and positive capacity.",
nameof(binding));
Binding = binding;
}
public AdvTextLayoutPresentationBinding Binding { get; }
public IReadOnlyList<AdvRetainedGlyphPlacement> Glyphs => _glyphs;
public int PublishedGlyphCount { get; private set; }
public int PublishableGlyphCount
=> (int)Math.Min(_glyphs.Count, Binding.ObjectCapacity);
public int Append(
IReadOnlyList<AdvRetainedGlyphRecord> records,
int layoutOriginX,
int layoutOriginY)
{
ArgumentNullException.ThrowIfNull(records);
int first = _glyphs.Count;
foreach (AdvRetainedGlyphRecord record in records)
_glyphs.Add(new AdvRetainedGlyphPlacement(
record, layoutOriginX, layoutOriginY));
return first;
}
/// <summary>Publish newly revealed glyphs through a layout-global target count.</summary>
public int PublishThrough(GfxState gfx, int targetGlyphCount)
{
ArgumentNullException.ThrowIfNull(gfx);
int target = Math.Clamp(targetGlyphCount, 0, PublishableGlyphCount);
for (int index = PublishedGlyphCount; index < target; index++)
Bind(gfx, index);
PublishedGlyphCount = Math.Max(PublishedGlyphCount, target);
return PublishedGlyphCount;
}
/// <summary>Recreate every currently revealed binding after op 0x20a or temporary suspension.</summary>
public int Republish(GfxState gfx)
{
ArgumentNullException.ThrowIfNull(gfx);
for (int index = 0; index < PublishedGlyphCount; index++)
Bind(gfx, index);
return PublishedGlyphCount;
}
public void ErasePublished(GfxState gfx)
{
ArgumentNullException.ThrowIfNull(gfx);
gfx.EraseRange(Binding.FirstObjectHandle, Binding.ObjectCapacity);
}
private void Bind(GfxState gfx, int index)
{
AdvRetainedGlyphPlacement placement = _glyphs[index];
AdvRetainedGlyphRecord record = placement.Record;
if (record.Width <= 0 || record.Height <= 0) return;
gfx.BindDraw(
checked(Binding.FirstObjectHandle + index),
Binding.SourceSurfaceSlot,
record.Left,
record.Top,
record.Width,
record.Height,
checked(placement.LayoutOriginX + record.Left),
checked(placement.LayoutOriginY + record.Top));
}
}

25
engine/Age.Engine/Vm/VirtualMachine.cs
View File

@@ -1809,7 +1809,7 @@ public sealed class VirtualMachine
{
_cur.CoroutineResumePc = pc + 1;
_cur.CoroutineYieldActive = true;
_host.SetAdvPagePresentationSuspended(true);
_host.SetAdvPagePresentationSuspended(Gfx, true);
targetOffset = _cur.CoroutineYieldHandlerA;
}
else targetOffset = _cur.CoroutineYieldHandlerB;
@@ -1824,7 +1824,7 @@ public sealed class VirtualMachine
{
_cur.CoroutineResumePc = null;
_cur.CoroutineYieldActive = false;
_host.SetAdvPagePresentationSuspended(false);
_host.SetAdvPagePresentationSuspended(Gfx, false);
return resumePc;
}
return pc + 1; // cold bounded scene-entry path
@@ -1991,7 +1991,13 @@ public sealed class VirtualMachine
var liveRun = new AdvLiveTextRun(
off, TextHistory.GetLayoutSnapshot(layoutSlot), _advTextStyle, text, scriptStack);
TextHistory.AppendText(layoutSlot, off, text, _advTextStyle);
_host.ShowText(liveRun, _messageGlyphDelayMilliseconds);
AdvTextLayoutPresentationBinding binding =
TextHistory.GetPresentationBinding(liveRun.Layout.Slot);
AdvRetainedTextRunResult? retained = _host.ShowText(
Gfx, binding, liveRun, _messageGlyphDelayMilliseconds);
if (retained is { } result)
TextHistory.SetCursor(
result.LayoutSlot, result.CursorX, result.CursorY);
}
return pc + 1;
case "define-adv-text-layout": // 0x70: configure layout and begin a logical retained group
@@ -2003,8 +2009,12 @@ public sealed class VirtualMachine
int requestedSlot = (int)Read(a[0]);
TextHistory.ResetLayout(requestedSlot);
var layout = TextHistory.GetLayoutSnapshot(requestedSlot);
AdvTextLayoutPresentationBinding binding =
TextHistory.GetPresentationBinding(layout.Slot);
if (binding.FirstObjectHandle >= 0 && binding.ObjectCapacity > 0)
Gfx.EraseRange(binding.FirstObjectHandle, binding.ObjectCapacity);
_host.SetAdvTextCursor(layout.Slot, layout.CursorX, layout.CursorY);
_host.ClearRenderedAdvTextLayout(layout.Slot);
_host.ResetRenderedAdvTextLayout(Gfx, binding);
_cur.ReadMessageOffset = ins.Offset;
_sharedProfile.ReadText.CommitPending();
RefreshAdvReadSkipState();
@@ -2031,8 +2041,13 @@ public sealed class VirtualMachine
return pc + 1;
case "u00420CE0":
case "publish-adv-text-layout": // 0x20a: publish layout and current marker frame if active
_host.PublishAdvTextLayout((int)Read(a[0]));
{
int requestedSlot = (int)Read(a[0]);
AdvTextLayoutPresentationBinding binding =
TextHistory.GetPresentationBinding(requestedSlot);
_host.PublishAdvTextLayout(Gfx, binding);
return pc + 1;
}
case "draw-string": // 0x204 (surface slot, x, y, string)
_host.DrawStringToSurface((int)Read(a[0]), (int)Read(a[1]), (int)Read(a[2]), ReadStr(a[3]),
_advTextStyle);