84 lines
5.1 KiB
Markdown
84 lines
5.1 KiB
Markdown
# Gadget material opacity and blending
|
|
|
|
Implemented 2026-10-27. Scope: Vulkan support needed by the recovered shrink-ray
|
|
effect. This is a renderer capability, not a claim of complete original material
|
|
or fixed-function rendering fidelity.
|
|
|
|
## Recovered facts
|
|
|
|
[Shrink-ray investigation](shrink-ray.md) records the underlying REA evidence.
|
|
Original EXE SHA256:
|
|
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
|
|
Original engine DLL SHA256:
|
|
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
|
|
|
|
| Original location | Fact and dependency |
|
|
| --- | --- |
|
|
| EXE VA40E4A0 / raw0E4A0, complete-object virtual offset114 | Positive opacity walks shape polygons and nonnull materials; writes material RGB1, alpha=parameter at +4C..58, source blend enum6 at +30, destination enum7 or1 at +34, and sets flag38 bit0. It does not multiply a previous alpha or scale geometry. |
|
|
| EXE VA440000 / raw40000, Init; VA440180 / raw40180, update | Effect initialization and texture changes invoke that setter with0.5. The material opacity applies to all three animated ray textures. |
|
|
| EXE global509A13; store VA476BBE / raw76BBE | False selects destination enum1; true selects enum7. Store comes from graphics setup. Complete hardware/settings fallback semantics remain unresolved. |
|
|
| DLL VA10036AB0 / raw36AB0; table VA1013667C / raw13667C | Adapter maps blend enums to Direct3D states19/20. Enum6→SRC_ALPHA, enum1→ONE, enum7→INV_SRC_ALPHA. False global therefore means additive SrcAlpha/One; true means conventional SrcAlpha/OneMinusSrcAlpha. |
|
|
|
|
The DLL REA evidence is
|
|
`ev_f5a914ee9eae593b02a04149b6651b2d783151df046bbb417624bf94f23bb96c`,
|
|
closed/exported in `artifacts/shrink-ray/rea-blend/00.json`. The parent report
|
|
links retained EXE evidence and byte-guard utility. No originals were modified
|
|
or executed for this implementation.
|
|
|
|
## Implementation and explicit policies
|
|
|
|
`MeshDraw.Opacity` defaults to1; `MeshDraw.Blend` defaults to `MeshBlend.Opaque`.
|
|
The other modes are `Alpha` and `Additive`, using exactly the source/destination
|
|
factors above for both RGB and alpha. The caller chooses the mode; opacity alone
|
|
does not enable blending. The source effect should use opacity0.5 with its chosen
|
|
graphics branch. Texture alpha is not pre-halved.
|
|
|
|
The fragment shader retains the existing texture-alpha cutout test (<0.5) and
|
|
then multiplies texture alpha by material opacity. Keeping this test and threshold
|
|
is existing port behavior; source alpha-test interaction is still unverified.
|
|
The push constant is float opacity at byte64 after the existing64-byte transform;
|
|
the68-byte range covers vertex and fragment stages. The vertex shader is
|
|
unchanged. Opaque world and opaque UI blend/depth pipeline states are unchanged.
|
|
|
|
Blended world draws test opaque depth without writing depth. This is an explicit
|
|
modern implementation policy: original shrink-ray depth-write state has not been
|
|
recovered in this bounded investigation. Rendering order is opaque world,
|
|
blended world, then UI; each pass preserves mesh draw order. There is no distance
|
|
sorting. UI modes use the same blend factors with depth testing/writing disabled
|
|
and the existing identity transform. This supports opacity without disturbing
|
|
ordinary HUD composition; it is not a recovered universal original UI contract.
|
|
|
|
All explicit draw opacities must be finite within0..1 and blend modes must be
|
|
valid, including invisible draws. Scene creation/replacement and every render
|
|
validate these properties. Per-frame validation runs before swapchain acquisition
|
|
or command-buffer recording so a rejected mutable material leaves rendering
|
|
usable after correction. All six pipelines are destroyed before their layout.
|
|
|
|
## Verification
|
|
|
|
`scripts/compile-shaders.sh` compiled both shaders for Vulkan1.3 and validated
|
|
both SPIR-V modules. Vertex SPIR-V remained unchanged. The isolated source-linked
|
|
test project builds without compiling the main runtime:
|
|
|
|
```sh
|
|
source scripts/env.sh
|
|
dotnet restore tests/GamePort.BlendTests/GamePort.BlendTests.csproj --ignore-failed-sources --source .nuget/packages
|
|
dotnet build tests/GamePort.BlendTests/GamePort.BlendTests.csproj --no-restore
|
|
dotnet tests/GamePort.BlendTests/bin/Debug/net10.0/GamePort.BlendTests.dll artifacts/gadget-blending/final-frame.ppm
|
|
```
|
|
|
|
Build: zero warnings/errors. Linux headless Vulkan runtime: llvmpipe
|
|
(LLVM20.1.2,256bits), Khronos validation enabled, **17 checks passed, zero
|
|
validation errors**. GPU RGBA readback checks exercise default opaque color,
|
|
half-opacity alpha/additive RGB equations, opaque occlusion, disabled blended
|
|
depth writes, UI ordering and depth bypass for both blend modes, zero opacity,
|
|
unchanged texture cutout, invalid opacity/enum rejection, and successful rendering
|
|
after correction. Numeric color tolerance is2/255 for attachment quantization.
|
|
Logs and a final opaque reference frame remain in `artifacts/gadget-blending/`.
|
|
|
|
These are real port GPU checks, not original-game comparisons. Windows runtime,
|
|
the selected graphics-option branch, original depth-write behavior, mixed
|
|
transparent scene ordering, and original alpha-test policy remain unverified.
|
|
Main-runtime integration and gameplay visual comparison belong to the primary
|
|
agent's integration checks.
|