erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions

fix(ui): Campaign LA gate round 2 — character-select screen media resolution

Browse source 
Root cause: the LA8 character-select screen's root background RenderSurface
(0x06007576, LayoutDesc 0x21000004 element 0x1000039A) is PFID_CUSTOM_RAW_JPEG
— a complete JFIF byte stream (confirmed live: 414,230 bytes, FFD8...FFD9,
Width=0/Height=0 on disk) that SurfaceDecoder.DecodeRenderSurface had no case
for, so it fell through the switch's `_ => DecodedTexture.Magenta` default arm
with nothing logged. Retail's RenderSurface::CreateFromSourceData
(named-retail decomp @0x004440a0) hands this exact byte stream to the Intel
JPEG Library (`_ijlInit`/`_ijlRead`/`_ijlFree`) at runtime and reads the real
pixel dimensions from the JPEG's own SOF header rather than this
RenderSurface's Width/Height fields, which are legitimately 0 for this
format — the same reason the decoder's generic non-positive-Width/Height
guard was also wrong to apply here.

A per-id media sweep of the installed DAT (new EveryDeclaredMediaId_
ResolvesToADecodableTexture test) showed this was the ONLY unresolved id
among the screen's 25 distinct media ids — the listbox (0x1000039D) and every
button face resolve fine. The listbox interior and the ENTER button's
circular fill are both transparent regions layered on top of the root, so
the one broken root background bled through everywhere nothing opaque
covered it, producing all three symptoms (full-screen background, listbox
interior, ENTER circle) from one cause.

Fix: SurfaceDecoder now special-cases PFID_CUSTOM_RAW_JPEG before the
Width/Height guard and decodes it with StbImageSharp (dual Unlicense/MIT,
pure managed, no native dependency — works on the Linux headless/graphical
targets Slice K/L commit to). JPEG is ITU T.81-standardized, so any
conforming decoder reproduces the pixels IJL would; round-tripped a
synthetic fixture through the real decode path to confirm. Verified against
the live DAT: 0x06007576 now decodes to 800x600, exactly the screen's
LayoutDesc-authored size.

Guard: per claude-memory/feedback_ui_resolve_zero_magenta.md, an unresolved
id reaching the draw path should be loud. That memory's existing guard
("guard on the id, not the handle") only covers a DIFFERENT trap — a
zero/absent id — and could not have caught this one, which has a real,
non-zero, DAT-resolved id. No guard existed for "id resolves but can't
decode" or "id doesn't exist in either dat" before this change, so both were
silent. SurfaceDecoder now logs once per surface id on every magenta-return
path (null data, JPEG decode failure, unsupported format, no-palette
paletted format, decode exception); TextureCache.GetOrUploadRenderSurface
logs once per id when a RenderSurface isn't found in Portal or HighRes at
all.

Tests: CharacterManagementLiveDatTests.EveryDeclaredMediaId_
ResolvesToADecodableTexture (installed-DAT gate, ACDREAM_PROBE_LIVE_MOUNT=1)
sweeps every StateMedia id in the char-select root + listbox row template
and asserts none decode to the magenta placeholder — this class of gap now
fails the gate instead of shipping silently. SurfaceDecoderTests adds
PFID_CUSTOM_RAW_JPEG coverage (real decode via a synthetic from-scratch
JPEG fixture — not retail art, generated with StbImageWriteSharp and
round-tripped before being pasted in as a literal; corrupt-data and
null-SourceData magenta paths) plus PFID_P8/PFID_INDEX16 no-palette cases
that now flow through the same logged path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-08-15 09:12:10 +02:00
parent 6e1c0967cb
commit 9ce7292570
5 changed files with 353 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

89
src/AcDream.Core/Textures/SurfaceDecoder.cs
View file

@ -1,8 +1,10 @@
using System.Collections.Concurrent;
using AcDream.Core.Rendering.Wb;
using BCnEncoder.Decoder;
using BCnEncoder.Shared;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Enums;
using StbImageSharp;
namespace AcDream.Core.Textures;
@ -10,6 +12,34 @@ public static class SurfaceDecoder
{
private static readonly BcDecoder BcDecoder = new();
/// <summary>
/// Campaign LA gate round 2 (character-select screen): a real, DAT-resolved,
/// non-zero-id RenderSurface can still hit the magenta fallback below (unsupported
/// PixelFormat, a paletted format with no palette, or corrupt/undersized
/// SourceData). That is a DIFFERENT trap than the zero-id footgun documented in
/// <c>claude-memory/feedback_ui_resolve_zero_magenta.md</c> ("guard on the id, not
/// the handle") — this one has a real id and a real handle, so that guard cannot
/// catch it. Both traps produce the identical silent 1x1 magenta texture, so this
/// one needs the same "loud, not silent" treatment: log once per surface id so an
/// undecodable asset fails LOUD in diagnostics instead of shipping as a silent
/// magenta wash (this is exactly how LA8's character-select background,
/// RenderSurface 0x06007576/PFID_CUSTOM_RAW_JPEG, went unnoticed — nothing logged
/// when its decode fell through to the unsupported-format arm).
/// </summary>
private static readonly ConcurrentDictionary<uint, byte> LoggedMagentaIds = new();
private static DecodedTexture LogMagentaOnce(RenderSurface rs, string reason)
{
if (LoggedMagentaIds.TryAdd(rs.Id, 0))
{
Console.WriteLine(
$"[UI] SurfaceDecoder: RenderSurface 0x{rs.Id:X8} decoded to the 1x1 "
+ $"magenta placeholder ({reason}; format={rs.Format} "
+ $"{rs.Width}x{rs.Height}).");
}
return DecodedTexture.Magenta;
}
/// <summary>
/// Decode a RenderSurface's pixel bytes into RGBA8. Returns <see cref="DecodedTexture.Magenta"/>
/// for unsupported formats, null data, or corrupt sizing. This overload does NOT
@ -31,8 +61,35 @@ public static class SurfaceDecoder
/// </summary>
public static DecodedTexture DecodeRenderSurface(RenderSurface rs, Palette? palette, bool isClipMap = false, bool isAdditive = false)
{
if (rs.SourceData is null || rs.Width <= 0 || rs.Height <= 0)
return DecodedTexture.Magenta;
if (rs.SourceData is null)
return LogMagentaOnce(rs, "null SourceData");
// PFID_CUSTOM_RAW_JPEG carries a complete JFIF-encoded image verbatim in
// SourceData. Retail's RenderSurface::CreateFromSourceData (named-retail
// decomp @0x004440a0) hands this exact byte stream to the Intel JPEG Library
// (`_ijlInit`/`_ijlRead`/`_ijlFree`) at RUNTIME, and the real pixel dimensions
// come from the JPEG's own SOF header — NOT from this RenderSurface's
// Width/Height fields, which are legitimately 0 on disk for this format
// (confirmed against the installed DAT: 0x06007576, the LA8 character-select
// screen's root background, carries Width=0/Height=0 with a 414,230-byte
// FFD8...FFD9 JFIF stream that decodes to 800x600 — exactly the screen's
// LayoutDesc-authored size). Handle it before the generic Width/Height guard
// below, which does not apply to this format and previously made every
// PFID_CUSTOM_RAW_JPEG surface fall straight to magenta.
if (rs.Format == PixelFormat.PFID_CUSTOM_RAW_JPEG)
{
try
{
return DecodeCustomRawJpeg(rs);
}
catch (Exception ex)
{
return LogMagentaOnce(rs, $"JPEG decode failed: {ex.Message}");
}
}
if (rs.Width <= 0 || rs.Height <= 0)
return LogMagentaOnce(rs, "non-positive Width/Height");
try
{
@ -46,18 +103,40 @@ public static class SurfaceDecoder
PixelFormat.PFID_DXT5 => DecodeBc(rs, CompressionFormat.Bc3, isClipMap),
PixelFormat.PFID_A8 or PixelFormat.PFID_CUSTOM_LSCAPE_ALPHA => DecodeA8(rs, isAdditive),
PixelFormat.PFID_P8 when palette is not null => DecodeP8(rs, palette, isClipMap),
PixelFormat.PFID_P8 => LogMagentaOnce(rs, "PFID_P8 with no palette"),
PixelFormat.PFID_INDEX16 when palette is not null => DecodeIndex16(rs, palette, isClipMap),
PixelFormat.PFID_INDEX16 => LogMagentaOnce(rs, "PFID_INDEX16 with no palette"),
PixelFormat.PFID_R5G6B5 => DecodeR5G6B5(rs),
PixelFormat.PFID_A4R4G4B4 => DecodeA4R4G4B4(rs),
_ => DecodedTexture.Magenta,
_ => LogMagentaOnce(rs, $"unsupported PixelFormat {rs.Format}"),
};
}
catch
catch (Exception ex)
{
return DecodedTexture.Magenta;
return LogMagentaOnce(rs, $"decode threw: {ex.Message}");
}
}
/// <summary>
/// Decode PFID_CUSTOM_RAW_JPEG: see the doc comment on the
/// <see cref="PixelFormat.PFID_CUSTOM_RAW_JPEG"/> branch in
/// <see cref="DecodeRenderSurface(RenderSurface, Palette?, bool, bool)"/> for the
/// retail mechanism this replaces. JPEG is a standardized (ITU T.81) format, so any
/// conforming decoder reproduces the same pixels the Intel JPEG Library would.
/// StbImageSharp (dual Unlicense/MIT, pure managed, no native dependency) is
/// acdream's decoder so the same code path works on the Linux headless/graphical
/// targets Slice K/L commit to. Throws on any failure; the caller converts that
/// into the logged magenta placeholder — this method never returns Magenta itself.
/// </summary>
private static DecodedTexture DecodeCustomRawJpeg(RenderSurface rs)
{
ImageResult image = ImageResult.FromMemory(rs.SourceData!, ColorComponents.RedGreenBlueAlpha);
if (image.Width <= 0 || image.Height <= 0)
throw new InvalidDataException(
$"JPEG surface 0x{rs.Id:X8} decoded to {image.Width}x{image.Height}.");
return new DecodedTexture(image.Data, image.Width, image.Height);
}
private static DecodedTexture DecodeIndex16(RenderSurface rs, Palette palette, bool isClipMap)
{
int expectedBytes = rs.Width * rs.Height * 2;