Sylpheed/docs/re/structures/ui-forced-backdrop.md

# Where a keyless primitive paints, when the file forces it

**Classification: decoded.** Derived from the keyframes and the element's own
geometry, checked disc-wide, and validated against **both** primitives whose
position was measured in the running game — one it must reproduce, one it must
not disturb.

## The question

A `.prm` / `.tbm` primitive carries **no layer key**: the key is read from a
sprite's header, and a primitive has no sprite.
[`ui-prm-primitives.md`](ui-prm-primitives.md) established that the key is not in
the bundle either — the declaration entry's unread words are constant, and the
bundle has no RATC child for a primitive — so `implied_layer_key` is a **measured
per-name table**, and anything not in it keeps `u32::MAX` and sorts **last**.

"❔ Where an *unmeasured* primitive paints" has been that page's standing blocker.

The port hit it: `build_12` / `build_15` composited to solid black at every
instant of their declared life, because `pgloading_eff00.prm` — a full-screen
opaque quad — sorted on top.

## The rule

> **An element that covers the screen and is fully opaque at some instant cannot
> paint above anything visible at that instant.** Where the elements visible
> during its opaque span are *all* of them, its position is forced to first.

This is a constraint read off the file, not a preference, and it is not an
analogy to a neighbouring screen.

`pgloading_eff00.prm` is opaque for **39** instants, and **all 9** other elements
on the loading screen are visible inside that span. **Forced first**, 4/4
instances.

## The controls — the rule has to survive both, and it does

| primitive | measured in the game | opaque instants | forced below | rule says |
|---|---|---|---|---|
| `palogo_eff0.prm` (entry 11, developer) | **paints FIRST** | 211 | **6 of 6** | ✅ forced first |
| `palogo_eff0.prm` (entry 10/13, publisher) | **paints FIRST** | 256 | 2 of 2 | ✅ forced first |
| `pteff00.prm` (title) | **paints LAST** | 2 | 3 of 23 | ✅ permitted on top |
| `pteff00.prm` (menu) | **paints LAST** | 2 | 7 of 15 | ✅ permitted on top |

🔴 **The first row is the one that matters.** `palogo_eff0.prm` is named like an
overlay, and a rule keyed on the *name* would sort it last — against a measured
order. Occlusion gets it right. `pteff00.prm` is opaque only for two instants, at
its screen's entry and exit, so the constraint never binds it: it is the fade
cover, and it belongs on top.

## The span, and what it costs to get wrong

The rule quantifies over "every instant the primitive is opaque" and "every
element visible then", so it depends on where a screen's timeline ends and on what
an element does after its own last keyframe. The port asked, having got **256**
opaque instants for `palogo_eff0.prm` where this page said 211.

⚠️ **That pair was a bundle mismatch, not a definitional one** — `palogo_eff0.prm`
appears on both splashes, and the publisher (entries 10, 13) runs to t=255 while
the developer (11, 14) runs to t=210. 256 and 211 are both right, for their own
screen. The definitions already agreed.

**The definition:** the span is `0 ..= max keyframe time over every element in the
build`, and an element **holds its final pose** past its own last keyframe — which
is what `pose_at` does, and it is decoded rather than assumed: a group holds at its
last keyframe rather than looping
([`ui-keyframe-time-unit.md`](../ui-keyframe-time-unit.md)), and
[`ui-record-loop-length.md`](ui-record-loop-length.md) shows the declared length
never falls short of the last keyframe, the slack being exactly that hold.

**How much rests on it — 130 keyless full-screen primitives with an opaque
interval, and how many verdicts change:**

| alternative convention | verdicts changed |
|---|---|
| span = the bundle header's declared `+0x08` | **0** |
| span = the primitive's **own** last keyframe | 72 |
| elements counted **gone** after their last keyframe (no hold) | **72** |

🔴 **The hold decides 55 % of the verdicts, and dropping it is refuted by a
measured order.** `palogo_eff0.prm` is a *single* keyframe at t=0. Without the
hold it would be opaque for one instant, no other element would be up yet, and the
rule would call it **free** — against the order measured in the running game,
which paints it first. Pinned by
`the_hold_after_a_final_keyframe_is_required_by_a_measured_order`.

✅ **And the header length is interchangeable with the elements' maximum**: zero
disagreements disc-wide. Either may be used.

✅ **The verdicts that matter are convention-independent.**
`pgloading_eff00.prm` comes out **first** under all four conventions;
`pteff00.prm` comes out **free** under all four. Only `palogo_eff0.prm` moves, and
only under the convention its own measured order rules out.

## Disc-wide

Keyless **full-screen** primitives with an opaque interval:

| | count |
|---|---|
| position **forced first** | **80** |
| constrained below some, not all | 50 |
| occluding nothing | 0 |

The split falls almost exactly along the names — every `*base*` is forced, every
`*eff00*` is not — with three families crossing it: `palogo_eff0.prm`,
`pgloading_eff00.prm` and `pzeff00.prm` are named like overlays and are forced
first. **That is precisely why the name is not the rule.**

✅ **And it explains a symptom the corpus had recorded without a cause.**
`ui-prm-primitives.md` notes 36 builds that "come out one colour ... wiped by
`pzeff00.prm` and `pceff00.prm`, whose positions have never been measured".
`pzeff00.prm` is forced first in **32 of 32** instances. Those builds were wiped by
our own sort, not by the game.

## 🔴 The rule's real limit, found by its own test

An earlier version applied to any element. Its disc-wide test asserted that no
*keyed* element is ever forced — and that assertion failed, on **22** of them:
`pneff01.t32` (key `0xd850`, paints #8 of 13) and `pbfriendly.t32` (key `0x9230`,
#17 of 49).

Both are `.t32` **sprites**, and that is the flaw: a sprite's *element* alpha
being 255 says nothing about whether its **texture** covers the screen. Most of it
may be transparent. The disagreements were the rule overreaching, not the keys
being wrong.

`forced_backdrop` is now restricted to elements with **no sprite** — untextured
primitives, which are solid quads and do occlude what they cover. That is also the
only case `derived_paint_order` consults it for.

## 🔴 Self-refutation: the argument is sound for only 42 of the 80

A disc-wide census of the *colour* these elements carry breaks the rule's premise
for nearly half its verdicts.

| the 80 forced-first instances | count | fade ARGB |
|---|---|---|
| `.prm` — untextured solid quads | **42** | pure black (`ff000000`, `7f000000`, `40000000`, …) |
| `.tbm` | **38** | **`ffffffff`** — white at full alpha |

**A solid white quad at alpha 255 painted first would make the screen white.** No
screen is white. So a `.tbm` is not a solid quad: `ffffffff` is a white
*modulation* on a texture, which is exactly what a background bitmap carries.

🔴 **And that means element alpha does not establish coverage for them** — the same
error the `.t32` guard already caught, one file extension further out. I fixed that
symptom (`el.sprite.is_some()`) rather than its cause: **an element's alpha is not
its texture's opacity, and only an untextured primitive makes the two the same
thing.**

**What this does and does not change:**

* ✅ The **42 `.prm`** verdicts stand as decoded. For a solid colour quad the fade
  *is* the pixel, so opacity and coverage are the same fact.
* ✅ **One of the 13 `.tbm` names is measured, not inferred.** `pfbase.tbm` is
  element 0 of the save/load frame, and the order read off the running game
  (`the_save_load_screens_match_what_the_running_game_paints`) starts `[0, 1, 2,
  …]` — the game paints it first. The other twelve names rest on the rule.
* 🟡 The **38 `.tbm`** verdicts are **not** decoded. They are almost certainly still
  right — every one is named `*base*`, is full-screen, and one of them
  (`pfbase.tbm`) has its first position **measured in the running game** — but that
  is a name-and-role argument, which this page elsewhere argues is the weaker kind.
* ⚠️ **The code is deliberately unchanged.** Restricting `forced_backdrop` to
  `.prm` would send `pcbase`, `pnbase`, `pqbase`, `pubase`, `pvbase`, `pjbgbase2`,
  `po_menu_base` and the four `px_*_base` back to `u32::MAX` — last — which is the
  blank-screen bug this rule was written to fix. Downgrading their *status* is
  honest; reverting their *position* would be wrong.

## ❔ Where a `.tbm`'s pixels live — looked, not found

If a `.tbm`'s texture could be decoded, its alpha coverage would settle the 38
directly. It cannot be located:

* **not in its bundle** — no RATC record and no sprite-table entry, for any of the
  13 names;
* **not a file** — there is no `.tbm` anywhere on the disc;
* **not a pak entry** — its own archive's hashed TOC contains none of `pfbase.tbm`,
  its uppercase form, its stem, `.t32`/`.tga`/`.xpr` variants, or `ui\`/`tex\`
  prefixes, across four archives;
* **not visible in our composite** — `compose` skips an element with no resolvable
  sprite, so our renderer draws **no pixels at all** for a `.tbm`, and no committed
  capture covers a screen that has one (`GP_SAVE_LOAD`, `GP_BUNK`,
  `GP_DEBRIEFING_PILOTLOG`), so nothing says whether the game draws any either.

⚠️ **So a second reading survives and is not excluded**: that a `.tbm` element
contributes no pixels, in which case its paint position is *inert* rather than
wrong. That would leave the 38 verdicts harmless instead of correct — a different
claim with the same consequence. Distinguishing them needs a capture of a screen
that carries one, which is behind the Ⓐ fault
([`ui-clock-freezes-at-settle.md`](ui-clock-freezes-at-settle.md)).

## 🔴 Stability is not necessity — 62 of the 80 are DECIDED by this rule (2026-08-30)

**Raised by the port agent, and it is right.** Every check this page has run — and
every re-check after a change elsewhere — measured whether a verdict *moved*. That
is the rule's **stability**. It never measured its **necessity**: an element whose
position is already fixed by a read `T8aD` key or an `implied_layer_key` is
*confirmed* by the rule, not *decided* by it, and on those screens removing the
rule entirely costs nothing.

So the question was asked directly. `derived_paint_order` was recomputed with the
`forced_backdrop` fallback removed and the two orders compared, over every
`dat/*.pak`:

| | instances |
|---|---|
| the rule **DECIDES** the order — it moves without it | **62** |
| the rule merely **AGREES** — order unchanged | 18 |
| **total forced** | **80** |

The 80 reproduces this page's own census exactly, which is the check that the probe
is looking at the same set. Data:
[`../data/forced-backdrop-necessity.txt`](../data/forced-backdrop-necessity.txt) ·
instrument: `crates/sylpheed-formats/examples/forced_backdrop_necessity.rs`.

**Every one of the 62 deciders is keyless — no keyed element is ever moved.** That
is the rule behaving as designed: it is a fallback, and it only ever fires where
nothing else can speak.

The 18 that merely agree split two ways, and the distinction matters:

* **14 have a key of their own** — `pfbase.tbm` (10) and `palogo_eff0.prm` (4). Here
  the sort already had the answer and the rule reproduces it. ⚠️ **This is the part
  that is not independent support.** `palogo_eff0.prm` being forced first agrees
  with its measured order, but its `implied_layer_key` is `0x00000000` and would
  have put it first anyway — so that agreement is the rule reproducing the crate,
  not the game confirming the rule.
* **4 are keyless but inert** — `po_menu_base.tbm`, twice in each of two 2-element
  builds. *Every* element on those screens is forced, so all keys collapse to the
  same value and the declaration-index tie-break gives the identical order either
  way.

### What actually holds the 62 up

Not a key — there is none — and not the `palogo_eff0.prm` control, which as above
is only decisive under a convention its own key already satisfies. **It is the
impossibility argument alone**: a full-screen quad that is opaque at some instant
cannot paint above everything visible then, or the screen is blank at that instant.
That argument is doing all the work on 62 instances, and its assumptions are
exactly the ones listed under *Reach* below — which is now a larger exposure than
this page previously implied.

By element, the 62:

| | count | kind |
|---|---|---|
| `pzeff00.prm` | 32 | `.prm`, colour census says pure black |
| `pgloading_eff00.prm` | 4 | `.prm` — 2 in `GP_TITLE` (entries 12/15), 2 in `GP_SAVE_LOAD` |
| `esrb_base.prm` | 2 | `.prm` |
| ten `*base*.tbm` families | 24 | `.tbm`, ❔ pixels never located |

⚠️ **24 of the 62 are `.tbm`**, and this page already records that a `.tbm`'s
pixels cannot be found anywhere on the disc. For those the two readings — "the rule
places it correctly" and "the element draws nothing, so its position is inert" —
remain indistinguishable, and both leave the composite right. The 38 `.prm`
deciders have no such escape: those are real quads with real colour, and the rule is
load-bearing on them in the full sense.

### For the port specifically

On the five menu screens the exposure is **two**: `GP_TITLE` entries **12 and 15**,
the dressed loading bundles, where `pgloading_eff00.prm` has neither a read nor an
implied key. Entries 10, 11, 13 and 14 — the four splashes — are unchanged with the
rule removed, exactly as the port measured on its own side. Two renderers, same
answer.

## Reach

⚠️ **Assumes straight alpha-over blending.** Blend mode is ❔ on
[`ui-prm-primitives.md`](ui-prm-primitives.md): an *additive* quad at alpha 255
would not occlude, and the rule would then be placing it wrongly. The
`palogo_eff0.prm` control is evidence the assumption holds at least there.

✅ **The colour census narrows this a long way.** Every full-screen `*eff00*`
primitive on the disc is **pure black** at its various alphas — `ff000000`,
`7f000000`, `40000000`, `b2000000`, `cc000000`, `d4000000`, `00000000`. Black at
alpha *a* over content is exactly what an alpha-over dim or fade looks like, and an
*additive* black quad would be a no-op, so a designer would not author one. The
single non-black primitive on the disc is **`pbafc.prm`**, RGB `00e8e0` (cyan) at
alphas up to `ff` — and it is **844×600, not full-screen**, so it is outside this
rule's geometry guard entirely. ❔ Whether *it* is additive is still open, and it is
now the only candidate.

✅ **Coverage is tested per instant, against the SCALED size, and two-sidedly.**
An earlier version rejected on the *declared* size (pivot doubled), which the port
pointed out replaces one error with its mirror: an element scaled **above** 100 %
could cover the screen from a smaller declared size. Checked across **921** keyless
elements: **0** do, so the mirror case does not occur on this disc — the per-instant
test is in because it does not need that to stay true. Verdicts before and after:
80, split 42 `.prm` / 38 `.tbm`, unchanged.

⚠️ **It gives a lower bound, not an ordering.** It settles the 80 instances where
occlusion forces the position, and says nothing about the 50 where the primitive
is opaque only part of the time — including `pteff00.prm`, whose place on top is
still a *measured* per-name entry, not a decoded one.

⚠️ **No new oracle measurement.** The two controls are orders measured previously;
nothing here was captured from a running game. A draw capture of a loading screen
would confirm it directly, and the loading screens are not reachable from the
title path.

## Reproducing

```bash
cargo run -p sylpheed-formats --example prm_forced_first
cargo run -p sylpheed-formats --example prm_occlusion_check
SYLPHEED_DISC=/disc cargo test -p sylpheed-formats --test ui_forced_backdrop_disc
```