Syplheed-Reborn/docs/re/structures/ui-prm-primitives.md

# `.prm` elements are untextured full-screen quads, and `kind` bit `0x10` says so

**Status:** ✅ `CONFIRMED` statically across all 965 screen builds on the disc.
🔴 **Drawing them at `Element::rest()` is refuted** — it would black out the
title screen. ❔ the resting rule for a fade group is unsolved, and that is the
blocker on actually compositing them.

## What they are

Every composite the port produces is missing its `.prm` elements: they resolve to
no sprite, so `compose` skips them. 369 of them exist. Swept over the disc:

| | |
|---|---|
| `.prm` elements in screen builds | **369** |
| …with a RATC child of their own name (a payload) | **0** |
| …with `kind & 0x10` set | **369** |
| non-`.prm` elements with `kind & 0x10` set | **0** |
| …with `pivot × 2 == 1280×720` (the design space) | **361** |
| …resting at scale 100 %, position (0,0) | 361 / 356 |

Three things follow, none of them inferred:

1. **They carry no texture.** Not one has a payload child; there is nothing in
   the bundle for them to draw. `.prm` is a primitive, not a sprite.
2. **The format marks them.** `kind & 0x10` and the `.prm` extension agree with
   **zero exceptions in either direction**. A port can classify an element as a
   primitive from the declaration table alone, without parsing filenames — which
   is what a decoded field is for.
3. **They are screen-sized colour fills.** 361 of 369 are exactly the design
   space at 1:1 in the corner. The 8 that are not are small coloured quads
   (844×600 at (291,60), and two degenerate 0×720).

## Where the colour is

The keyframe's `fade` word, ARGB — the field named for the alpha ramp it drives
on a sprite. On a `.prm` there is no sprite to modulate, so it *is* the fill.
Resting values across the disc:

```
 189  0x00000000   (transparent — nothing on screen)
 102  0xff000000   (opaque black)
  32  0x7f000000     6  0x60ff0000 (red)     6  0x0000ffd4 (cyan)
  20  other blacks   6  0x008000ff (violet)  2  0xf0ffffff (near-white flash)
```

Overwhelmingly **black at some alpha**: these are the screen's fade-to-black,
dim-behind-a-menu and flash layers. That matches the standing note on
`ComposeOptions::backdrop`, which describes the compositor's dim slate as a
stand-in for "the PRMD dim-quad" — this is that quad, and it is in the file.

## Drawing them (2026-08-19)

`fill_quad` composites a primitive as a solid rectangle of the keyframe's `fade`
colour, `pivot × 2` in size, placed and scaled exactly as a sprite is. It is
behind `ComposeOptions::include_primitives` / `screen render --primitives`, and
**off by default** — for a reason that is itself the result of this iteration.

On the title screen, whose paint order is ground truth, it is measurably right:

| composite | mean luminance | vs capture | mean abs diff |
|---|---|---|---|
| primitives off | 76.30 | **+18 %** | 16.07 |
| primitives on | **63.72** | **−1.3 %** | **13.08** |

(capture mean 64.58). The composite was ~40 % too bright in the background
regions; `pteff02.prm`, a 25 % black dim, is what was missing. The wordmark is
*not* dimmed by it — the measured order paints that quad at slot 4, beneath the
logo — and the fraction of wordmark pixels above 200 moves 29.9 % → 28.2 %
against the capture's 26.8 %.
[The composite](../captures/ui-layout/title-composited-with-primitives.png).

Edge correlation goes 0.9538 → 0.9480, which sounds like a loss and is not
informative: a uniform dim scales gradients uniformly, so a normalised edge
correlation barely sees it. Brightness is the metric that discriminates here, and
it moves 20 percentage points toward the capture.

## Refuted twice, and the second one is the blocker

**Refuted: you cannot draw them at `Element::rest()`** — as the old longest-dwell
rule computed it. The title's `pteff00.prm` runs opaque → transparent →
transparent → opaque, a screen transition whose resting pose is the transparent
plateau, and it paints **last**; the old rule picked the opaque endpoint, i.e.
the whole screen. That is fixed — [`ui-resting-pose.md`](ui-resting-pose.md).

**Refuted: the derived paint order does not place them.** This is what keeps the
flag off. A primitive has no `T8aD` header, so it has **no layer key**, and
`derived_paint_order` sorts the keyless to the very end. `GP_DIALOG`'s
`pzeff00.prm` is a *single* keyframe of opaque black at full screen; painted last
it wipes the build. Measured: of the 125 builds that draw a visible primitive,
**36 come out more than 99 % one colour** with the derived order.

And no simple default fixes it, because the two screens read off the running game
disagree with each other:

* the developer-logo splash paints `palogo_eff0.prm` **first** — it is the black
  backdrop the logos sit on;
* the title paints `pteff02.prm` at slot **4**, beneath the wordmark, and
  `pteff00.prm` **last**, as the fade-out.

So a primitive's position is real, per-element, and not derivable from anything
decoded so far. "Primitives first" would break the title's fade-out; "primitives
last" wipes 36 builds; "keep declaration position" was checked against the title
and fails there too — `pteff00.prm` is element 8, declared among the wordmarks,
and the game paints it 23rd.

A disc test measures the damage (36 / 125 / 0-by-default) rather than asserting
the feature works, so the number stays honest and changes when the ordering is
solved.

Worth seeing anyway: the DIFFICULTY dialog
([capture](../captures/ui-layout/dialog-difficulty-with-primitives.png)) renders
legibly with its 50 % dim — an early false alarm said 36 `GP_DIALOG` builds went
"100 % black", which was a crude near-black pixel threshold, not a black screen.
The genuinely wiped ones are a different set, wiped by an *opaque* quad.

## What is not settled

## Where a primitive paints — refuted in the file, measured in the game (2026-08-19)

**🔴 Refuted: the key is not in the bundle.** Two places were checked and both
are empty:

* the **declaration entry**'s four unread words are constant across every
  element of all three measured screens — `+28` = 0, `+36` = `0xffffffff`,
  `+56` = 0, and `+44` is a button ordinal (1…5 on the menu's five buttons,
  `0xffffffff` everywhere else). No key there.
* the **bundle carries no data at all** for a primitive. The menu build declares
  `pteff00.prm`, `pteff02.prm` and `pteff05.t32` and has **zero** RATC children
  for any of them — its 34 children are 21 `T8aD` sprites and 13 `.rat` records,
  none of them named for a primitive.

So the layer a primitive draws on comes from the game's own code, not the file.

**✅ But it is consistent, which makes a per-name table honest.** Bracketing each
unkeyed element between its measured neighbours' keys:

| element | title screen | main menu | splash |
|---|---|---|---|
| `pteff05.t32` | — | (0x8010, 0x8040) | — |
| `pteff04.t32` | (0x8010, 0x8040) | — | — |
| `pteff02.prm` | **(0x8010, 0x8040)** | **(0x8010, 0x8040)** | — |
| `pteff00.prm` | (0x8100, end) | (0x8110, end) | — |
| `palogo_eff0.prm` | — | — | (start, 0xa100) |

`pteff02.prm` falls in the **same interval on both** screens it appears on, the
fade quad is past the maximum on both, and the splash backdrop is below the
minimum. `ui_layout::implied_layer_key` records exactly these, and nothing more —
an unlisted primitive keeps `u32::MAX` and still sorts last.

With it, `derived_paint_order` produces **the same layer-key sequence as the
order read off the running game on all three measured screens**, primitives
included, and matches element-for-element on four of the five bundle instances
(the fifth is the title, which differs only inside its tied groups — a separate
open question). Pinned by
`the_derived_order_puts_every_element_in_the_right_layer_group`.

This does **not** make `include_primitives` safe by default: the 36 builds that
come out one colour are wiped by `pzeff00.prm` and `pceff00.prm`, whose positions
have never been measured, so they are not in the table.

## What is not settled

* ❔ **Where an *unmeasured* primitive paints.** The blocker, unchanged for the
  ones not in the table. It has no layer
  key and the two measured screens rule out every constant default. The cheapest
  next step is a third measured order from a screen that carries a primitive —
  the `GP_DIALOG` DIFFICULTY box is reachable from the main menu and has exactly
  one, so a runtime child-list read there would say whether its dim is first or
  last.
* ❔ **Blend mode.** A dim quad at `0x7f000000` is presumably straight alpha over
  what is beneath, but the flash (`0xf0ffffff`) and the coloured ones
  (`0x60ff0000`) may well be additive. Nothing measured.
* ❔ **The 8 non-full-screen ones**, including two with a zero dimension.
* 🟡 `kind = 0x3010` (38 elements) is `0x10` plus `0x3000`, the button-record
  bits — a primitive that is part of a button. Unexamined.

---

## ✅ Measured on the splash: the `.prm` paints FIRST, full-screen, opaque black

**2026-08-29.** This page recorded that where a `.prm` paints "on a screen
without a measured order is unsolved". For the developer splash it is now
measured, from the 235-frame draw capture.

Every frame begins with two full-screen draws before any sprite:

```
f120: [1280x720]  [1280x720]  [499x241] …
        ^clear      ^this one
```

The second is **untextured** in all **212** frames, with a constant vertex colour
of **`FF000000`** — opaque black. That matches `palogo_eff0.prm`'s declaration
exactly:

| declared | observed |
|---|---|
| `kind = 0x10` (the primitive marker) | untextured draw |
| pivot (640,360) → **1280×720** | 1280×720 quad |
| **one** keyframe, `a = 255` | constant across 212 frames |
| — | vertex colour `FF000000` |

So the splash's backdrop is an **opaque black full-screen quad from the bundle
itself**, painted behind every sprite — not a clear colour, which is why our
splash renders need `--black` to match.

⚠️ **Not a general rule.** The measured *main menu* order puts `pteff02.prm` at
position 4 and `pteff00.prm` **last** — that one is the screen-transition fade.
A `.prm` paints where its screen's order says; the splash's happens to be first.

## ⚠️ And the splash's "measured paint order" is a SEQUENCE, not a depth order

`measured_paint_order` returns `[0, 2, 4, 6, 1, 3, 5]` for the splash, commented
*"the full-screen `.prm`, then all three glows, then the three logos"*.

The draw capture shows the glows and the logos **never appear in the same frame**
— 0 overlapping frames in 235 ([group start time](ui-group-start-time.md)). Two
elements that never co-occur have **no observable relative depth**. What that
vector records between its glow half and its logo half is the *temporal* order
they were seen in, not a front-to-back relationship.

🟡 This does not make the render wrong — compositing them in that order is
harmless, and the ✅ for element 0 (the `.prm` first) *is* a real depth
observation, since it co-occurs with everything. But the type of the claim
matters for a consumer: **treating the vector as depth invites compositing all
seven elements at once, which is exactly what does not reproduce the screen.**