chore: simplify UI copy and repo text

This commit is contained in:
xXJsonDeruloXx committed 2026-09-23 08:22:11 -04:00
1 parent af796545f6
commit 751f8ca114
96 files changed
+705 -1436

No files matched your search

+1 -1
View File
@@ -96,7 +96,7 @@ endif()
add_library(wayland-server SHARED IMPORTED)
set_target_properties(wayland-server PROPERTIES IMPORTED_LOCATION
${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/lib/libwayland-server.so)
# Vulkan is loaded at runtime via adrenotools (Turnip), not linked directly — so the
# Vulkan is loaded at runtime via adrenotools (Turnip), not linked directly - so the
# compositor uses Turnip's driver, which supports dmabuf import (drm_format_modifier).
target_link_libraries(bannerwayland
wayland-server
+73 -73
View File
@@ -1,6 +1,6 @@
# HDR on the Wayland backend — reconnaissance
# HDR on the Wayland backend - reconnaissance
> **2026-09-14: round 1 of Phase A is built** (branch `feat/wayland-hdr`, opt-in, testing only) —
> **2026-09-14: round 1 of Phase A is built** (branch `feat/wayland-hdr`, opt-in, testing only) -
> see **§10** at the end for what was built, how it is gated and how a tester's log proves it.
> The recon below is kept as written.
@@ -24,7 +24,7 @@ carries `dxgi.enableHDR` / `DXVK_HDR` and the `VK_COLOR_SPACE_HDR10_ST2084_EXT`
information. **Everything that is missing is in our compositor**, which advertises no colour
protocol, offers only four 8-bit DRM formats over `zwp_linux_dmabuf_v1`, takes
`surfaceFormats[0]` for its own swapchain, runs an 8-bit scene/effects chain, and never calls
`ASurfaceTransaction_setBufferDataSpace`. The work is therefore **app-side only** — the memory
`ASurfaceTransaction_setBufferDataSpace`. The work is therefore **app-side only** - the memory
note in `project_bannerlator_wayland_phase4` that HDR "does need a new wcp" is **wrong for the
HDR10 (10-bit PQ) path**; a new wcp is only needed for scRGB/FP16 zero-copy. Estimated
**4–6 engineer-days** to a plumbed, log-verifiable HDR10 path. But the Pocket FIT's panel
@@ -35,7 +35,7 @@ in §8: **not now.**
---
## 1. Game side — how far an HDR request gets today
## 1. Game side - how far an HDR request gets today
### 1.1 What a Windows game does
@@ -62,7 +62,7 @@ Swapchain formats DXVK will accept per colour space (`Presenter::pickFormat`,
* `EXTENDED_SRGB_LINEAR` (scRGB) → **`R16G16B16A16_SFLOAT` only**
`VK_EXT_hdr_metadata` is optional in both DXVK and vkd3d-proton. `VK_EXT_swapchain_colorspace`
is *not* requested as an instance extension by DXVK's win32 WSI — it simply trusts the driver to
is *not* requested as an instance extension by DXVK's win32 WSI - it simply trusts the driver to
report the extra `VkColorSpaceKHR` values from `vkGetPhysicalDeviceSurfaceFormatsKHR`. Mesa's
Wayland WSI does exactly that (§2.3), so this is not a problem for us.
@@ -82,7 +82,7 @@ DXGI enumeration for D3D12 titles is still DXVK's `dxgi.dll`, so `DXVK_HDR` stil
contains `VK_EXT_hdr_metadata`. Nothing needs rebuilding on the D3D side.
Proton-level gating: GE's `proton` script maps `PROTON_ENABLE_HDR` / `PROTON_USE_HDR` to
`DXVK_HDR=1` and nothing else. For us that is one container env var — no launcher work.
`DXVK_HDR=1` and nothing else. For us that is one container env var - no launcher work.
### 1.2 The failure mode today, exactly
@@ -90,19 +90,19 @@ DXVK's `DXGI_OUTPUT_DESC1` will claim HDR10 as soon as `DXVK_HDR=1`, regardless
`SetColorSpace1` then fails with `E_INVALIDARG` because our compositor advertises no colour
management, so Mesa lists only `SRGB_NONLINEAR` + `PASS_THROUGH` (§2.3). Well-behaved games fall
back to SDR. Games that trust `GetDesc1` without checking `CheckColorSpaceSupport` can render an
HDR-authored image into an SDR swapchain (washed out) — this is a pre-existing foot-gun, not
HDR-authored image into an SDR swapchain (washed out) - this is a pre-existing foot-gun, not
something we introduce. **Recommendation regardless of whether we do HDR: do not expose a
`DXVK_HDR` container toggle until the compositor answers truthfully**, or we invite exactly that
bug class.
### 1.3 `winewayland.drv` — carries nothing for colour, and blocks nothing
### 1.3 `winewayland.drv` - carries nothing for colour, and blocks nothing
`/home/claude-user/proton-wine-wayland2-wt/dlls/winewayland.drv/vulkan.c` is 121 lines:
`wayland_vulkan_surface_create` wraps the `wl_surface` in a `VkSurfaceKHR`,
`wayland_map_instance_extensions` aliases `VK_KHR_win32_surface` ⇄ `VK_KHR_wayland_surface`.
There is **no surface-format or colour-space filtering**, so whatever Mesa advertises reaches
DXVK unmodified. A grep for `color|colour|hdr|st2084|bt2020|gamut|10.?bit` across the whole
driver returns only GDI colour-bitmap helpers — nothing colorimetric.
driver returns only GDI colour-bitmap helpers - nothing colorimetric.
One real consequence: `wayland_output.c` publishes no EDID, and nothing in the tree writes the
`EDID` registry value `win32u/sysparams.c:815-818` reads. DXVK's
@@ -111,7 +111,7 @@ HDR luminances (`wsi_edid.h:38-56`: min 0.01 / max 1499 / maxFullFrame 799 nits)
size its tonemapper for a 1499-nit display. Correctable later by synthesising an EDID in
`winewayland.drv` (that *would* need a new wcp), but not a blocker.
### 1.4 Our bundled Turnip already speaks colour management — verified on the device
### 1.4 Our bundled Turnip already speaks colour management - verified on the device
```
$ strings .../Proton/11.0-2.1-arm64ec-6/lib/libvulkan_freedreno_wayland.so
@@ -125,11 +125,11 @@ VK_EXT_hdr_metadata PRESENT
The plain adrenotools driver the compositor itself loads
(`contents/adrenotools/Mesa Turnip v26.3.0-7cda785 (Android + Wayland)/libvulkan_freedreno.so`)
has the same colour-management symbols. Our own WSI patch is already aware of the protocol —
has the same colour-management symbols. Our own WSI patch is already aware of the protocol -
`patches/wayland/banner_ahb_wsi.py` anchors one of its edits on Mesa's
`if (display->color_manager) wp_color_manager_v1_destroy(...)` teardown line.
**And the zero-copy patch already maps 10-bit to gralloc** — `banner_ahb_wsi.py:99-100, 225-237`:
**And the zero-copy patch already maps 10-bit to gralloc** - `banner_ahb_wsi.py:99-100, 225-237`:
```c
#define BANNER_AHB_FORMAT_R8G8B8A8_UNORM 1u
@@ -140,10 +140,10 @@ case VK_FORMAT_A2B10G10R10_UNORM_PACK32: return BANNER_AHB_FORMAT_R10G10B10A2_U
So a 10-bit HDR10 swapchain can already be gralloc-backed and go onto the display layer with the
**shipped** wcp. `VK_FORMAT_R16G16B16A16_SFLOAT` is *not* mapped, so `banner_ahb_skip_format`
(:239-242, applied at `:606-617`) hides FP16 surface formats whenever zero-copy is on — scRGB
(:239-242, applied at `:606-617`) hides FP16 surface formats whenever zero-copy is on - scRGB
zero-copy is the one thing that needs a driver change (one enum: `AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16`).
### 1.5 X11 has no path — confirmed
### 1.5 X11 has no path - confirmed
`app/src/main/cpp/winlator/VulkanRendererContext.cpp:439` hardcodes
`swapchainFmt = VK_FORMAT_R8G8B8A8_UNORM` and `:492` hardcodes
@@ -170,7 +170,7 @@ Implementers: KWin (reference impl, most mature), Mutter (merged 2025-02-25 but
advertise enough features for automatic HDR), wlroots 0.20 / Sway 1.12 (HDR10 on the Vulkan
renderer), gamescope (v1 semantics + frog), Weston (experimental, no tone mapping).
Proton-CachyOS's changelog notes that its `winewayland.drv` `windows_bt2100` path needs protocol
**v3** and that *"no compositor supports it yet"* — everybody is converged on **v1**.
**v3** and that *"no compositor supports it yet"* - everybody is converged on **v1**.
**We only need v1.** That is what Mesa binds.
@@ -178,7 +178,7 @@ Proton-CachyOS's changelog notes that its `winewayland.drv` `windows_bt2100` pat
At bind, on the `wp_color_manager_v1` global, send one event per supported item then `done`:
* `supported_intent`: `perceptual` (mandatory anyway — it is all Mesa ever asks for)
* `supported_intent`: `perceptual` (mandatory anyway - it is all Mesa ever asks for)
* `supported_feature`: `parametric` (gates `create_parametric_creator`); optionally
`set_mastering_display_primaries`, and `extended_target_volume` **only if** we want scRGB
* `supported_primaries_named`: `bt2020` (HDR10), `srgb` (needed for scRGB and for Mesa's
@@ -195,9 +195,9 @@ Then implement: `create_parametric_creator` → `wp_image_description_creator_pa
**Not needed:** ICC creator, `wp_color_management_surface_feedback_v1`,
`wp_image_description_info_v1`, output image descriptions, v2/v3 requests. Mesa uses none of them.
### 2.3 What Mesa's WSI does — read from the exact commit we build
### 2.3 What Mesa's WSI does - read from the exact commit we build
Read from `src/vulkan/wsi/wsi_common_wayland.c` at Mesa `7cda7850` (4121 lines — the commit
Read from `src/vulkan/wsi/wsi_common_wayland.c` at Mesa `7cda7850` (4121 lines - the commit
recorded in `banners-turnip-wayland/mesa_hash.txt`). Landed upstream as MR !32038 (Xaver Hugl,
merged 2025-02-25, Mesa 25.1).
@@ -227,7 +227,7 @@ merged 2025-02-25, Mesa 25.1).
Consequence: if we advertise BT.2020 + PQ but keep only 8-bit DRM formats, Mesa will happily
offer `R8G8B8A8_UNORM` + `HDR10_ST2084` and DXVK will **not** take it (`pickFormat`'s HDR10 list
is 10-bit/16-bit only) — so there is no accidental 8-bit-PQ trap, but there is also no HDR
is 10-bit/16-bit only) - so there is no accidental 8-bit-PQ trap, but there is also no HDR
unless we also advertise a 10-bit DRM format.
* **Apply:** `wsi_wl_swapchain_update_colorspace` (`:1323-1455`) builds the parametric creator,
blocks on `ready`/`failed` (it dispatches the queue in a loop), sets mastering primaries /
@@ -248,7 +248,7 @@ Globals (`compositor.c:2527-2538`, plus `ahb_swapchain.c:406`,
`zwp_linux_dmabuf_v1` **v3**, `wl_seat` v5, `banner_desktop_v1`, `wp_presentation` v2,
pointer constraints, relative pointer, `banner_ahb_v1` v2, data device/control, text input,
toplevel icon. **No `wp_color_manager_v1`.** `protocols/` has no colour-management XML, and
protocol C glue is pre-generated into `generated/` (no `wayland-scanner` at app build time —
protocol C glue is pre-generated into `generated/` (no `wayland-scanner` at app build time -
`CMakeLists.txt:1-4`), so adding a protocol means generating and committing the files offline.
The dmabuf format table is 8-bit only (`compositor.c:1323-1326`):
@@ -267,14 +267,14 @@ Good news: the machinery around it is already format-agnostic.
`FOURCC` defines next to `compositor.c:415-421`.
The compositor's own output swapchain is oblivious (`vk_present.c:301-311, 437-466`): two instance
extensions (`VK_KHR_surface`, `VK_KHR_android_surface` — **no `VK_EXT_swapchain_colorspace`**),
and `VkSurfaceFormatKHR chosen = fmts[0];` (`:441`) — the first format the Android WSI happens to
extensions (`VK_KHR_surface`, `VK_KHR_android_surface` - **no `VK_EXT_swapchain_colorspace`**),
and `VkSurfaceFormatKHR chosen = fmts[0];` (`:441`) - the first format the Android WSI happens to
return, with whatever colour space rides along. The scene image and the whole 13-pass effects
chain are 8-bit (`vk_present.c:54` `SCENE_FMT = VK_FORMAT_R8G8B8A8_UNORM`; `effects_chain.c:29`
`FX_FORMAT = VK_FORMAT_R8G8B8A8_UNORM`).
> **Naming collision, flag it in any UI work.** The drawer already has an "HDR" effect. It is
> `effects_chain.c:197` `P_HDR` / `app/src/main/cpp/winlator/hdr.frag` — a dual-radius bloom +
> `effects_chain.c:197` `P_HDR` / `app/src/main/cpp/winlator/hdr.frag` - a dual-radius bloom +
> contrast lift ported from `HDREffect.java`, `HDRPower = 1.30`, entirely SDR and entirely fake.
> Real HDR must be named something else ("HDR output", "HDR10") or users will conflate them.
@@ -283,7 +283,7 @@ chain are 8-bit (`vk_present.c:54` `SCENE_FMT = VK_FORMAT_R8G8B8A8_UNORM`; `effe
No. A `DRM_FORMAT_ABGR2101010` buffer is equally valid as SDR BT.709 or as PQ BT.2020; the format
and modifier describe byte layout, not colorimetry. That ambiguity is precisely why
`wp_color_management_v1` exists. We *could* add a `set_dataspace` request to our own
`banner_ahb_v1` and skip the standard protocol — but Mesa would never call it, so that would need
`banner_ahb_v1` and skip the standard protocol - but Mesa would never call it, so that would need
a driver patch (new wcp) to buy something Mesa already gives us for free. **Implement
`wp_color_manager_v1` v1 server-side; it is strictly cheaper.**
@@ -301,16 +301,16 @@ a driver patch (new wcp) to buy something Mesa already gives us for free. **Impl
| `ASurfaceTransaction_setHdrMetadata_smpte2086(tx, sc, AHdrMetadata_smpte2086*)` | **29** | **PRESENT** |
| `ASurfaceTransaction_setHdrMetadata_cta861_3(tx, sc, AHdrMetadata_cta861_3*)` | **29** | **PRESENT** |
| `ASurfaceTransaction_setExtendedRangeBrightness(tx, sc, float cur, float desired)` | **34** | **PRESENT** |
| `ASurfaceTransaction_setDesiredHdrHeadroom(tx, sc, float)` | **35** | absent (expected — device is 34) |
| `ASurfaceTransaction_setDesiredHdrHeadroom(tx, sc, float)` | **35** | absent (expected - device is 34) |
| `ASurfaceTransaction_setLuts` | 36 | n/a |
| `ASurfaceTransaction_setColorSpace` | **does not exist** | — |
| `ASurfaceTransaction_setLuma` | **does not exist** | — |
| `ASurfaceTransaction_setColorSpace` | **does not exist** | - |
| `ASurfaceTransaction_setLuma` | **does not exist** | - |
(Checked with `strings` on the device's own `libandroid.so`; `setEnableBackPressure` and
`setFrameRateWithChangeStrategy` confirmed present alongside, matching what `sc_layer.c` already
dlsyms.)
Our dlsym table is `sc_layer.c:82-97` — 15 entries, **none of them colorimetric**. The additions
Our dlsym table is `sc_layer.c:82-97` - 15 entries, **none of them colorimetric**. The additions
needed are `setBufferDataSpace` (the only mandatory one), plus optionally
`setHdrMetadata_smpte2086` / `_cta861_3` and `setExtendedRangeBrightness`. All four are API ≤ 34,
i.e. inside the range `sc_layer.c` already targets, so the existing "missing symbol → path
@@ -333,10 +333,10 @@ Every layer on the device right now reports `dataspace=UNKNOWN (0)`, which SF tr
### 3.3 Buffer formats
`AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b` (API 26) ↔ `VK_FORMAT_A2B10G10R10_UNORM_PACK32`
— the normal 10-bit scanout format on Adreno DPUs. QTI gralloc on this device knows it:
- the normal 10-bit scanout format on Adreno DPUs. QTI gralloc on this device knows it:
`strings /vendor/lib64/libqdMetaData.so` lists `RGBA_1010102`, `RGBX_1010102`, `BGRA_1010102`,
`BGRX_1010102`. `AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16` (API 26) exists but is a
compositing intermediate, not normally a scanout format — it was **not** found in the vendor
compositing intermediate, not normally a scanout format - it was **not** found in the vendor
gralloc strings, so treat FP16 gralloc allocation on this SoC as unproven.
`AHardwareBuffer_isSupported()` (API 29) is the correct runtime probe, and we should use it rather
than assume.
@@ -345,7 +345,7 @@ The compositor's own AHB pool is hardcoded 8-bit (`sc_layer.c:302`
`.format = AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM`) and the imported view is built with
`DRM_ABGR8888` (`sc_layer.c:326`). That is the *copy* path; the zero-copy path
(`sc_layer_present_ahb`, `sc_layer.c:430`) takes the game's own buffer and so already carries
whatever format the game allocated — it just never labels it.
whatever format the game allocated - it just never labels it.
### 3.4 What SurfaceFlinger does with an HDR layer on an SDR panel
@@ -353,7 +353,7 @@ From `services/surfaceflinger/CompositionEngine/src/Output.cpp`, `getBestDataspa
`pickColorProfile()`:
* A `BT2020_PQ` layer sets `outHdrDataSpace = BT2020_PQ` but the output only *adopts* it when
`DisplayColorProfile::hasLegacyHdrSupport(BT2020_PQ)` is true — i.e. when the Composer HAL
`DisplayColorProfile::hasLegacyHdrSupport(BT2020_PQ)` is true - i.e. when the Composer HAL
reported HDR types for that display. Otherwise the output dataspace stays `DISPLAY_P3` with
`COLORIMETRIC` intent, and the layer is **tone-mapped, not rejected**.
* Because the HWC for an SDR-only display cannot consume a PQ buffer, the standard
@@ -364,7 +364,7 @@ From `services/surfaceflinger/CompositionEngine/src/Output.cpp`, `getBestDataspa
* **This is the trap for us.** Our whole zero-copy win is that `banner_wayland_game` composites
DEVICE (proven 2026-09-13: DEVICE with ROT_90 + 1.5× scale at 144 Hz, −4 pts GPU busy, −3 %
power). Tagging that layer `BT2020_PQ` on a panel with no HDR types is very likely to drop it to
CLIENT — i.e. HDR would **buy a washed-out tone-map and pay for it with the zero-copy saving**.
CLIENT - i.e. HDR would **buy a washed-out tone-map and pay for it with the zero-copy saving**.
Any implementation must gate the dataspace on the *display's* reported HDR types, not on the
game's request.
* `setExtendedRangeBrightness` is a different mechanism: it applies only to `RANGE_EXTENDED`
@@ -373,7 +373,7 @@ From `services/surfaceflinger/CompositionEngine/src/Output.cpp`, `getBestDataspa
reads brighter by simultaneous contrast without exceeding the panel ceiling.
**It needs the display to expose an HDR/SDR ratio.** This panel does not (§4).
* `setDesiredHdrHeadroom` (API 35) is the PQ/HLG equivalent and overrides/`is overridden by`
`setExtendedRangeBrightness` — last call wins. Not available on the test device at all.
`setExtendedRangeBrightness` - last call wins. Not available on the test device at all.
### 3.5 `has_HDR_display` vs `getHdrCapabilities()`
@@ -382,7 +382,7 @@ that the device *has* a wide-gamut, high-luminance panel; it gates SF-internal c
machinery. `Display.getHdrCapabilities().getSupportedHdrTypes()` is the **runtime, per-display**
answer, built from the Composer HAL's `getHdrCapabilities()` for that connector, itself derived
from the EDID CTA-861.3 Static Metadata Data Block. **They can disagree, and on this device they
do.** An empty list does not mean rejection — it means "tone-map it."
do.** An empty list does not mean rejection - it means "tone-map it."
### 3.6 External display
@@ -390,7 +390,7 @@ On hotplug, the framework queries `getDisplayConfigs`, `getColorModes`, `getHdrC
`getDisplayCapabilities` for the new display handle exactly as for the internal panel, so
`Display.getHdrCapabilities()` on an external `Display` *is* architecturally wired to reflect the
monitor's EDID. Whether it actually does is a vendor-HWC question; empty lists for genuinely
HDR10 USB-C monitors are a commonly reported Snapdragon gap. **Unproven for the Pocket FIT — the
HDR10 USB-C monitors are a commonly reported Snapdragon gap. **Unproven for the Pocket FIT - the
only way to know is to plug one in.**
---
@@ -441,7 +441,7 @@ Reading:
* `hdrSdrRatio not_available` / `NaN` and `displayBrightnessNits = -1` mean
`Display.isHdrSdrRatioAvailable()` is false → **`setExtendedRangeBrightness` has nothing to act
on here.** The "brighten highlights on an SDR panel" trick is unavailable on this device.
* `supportedColorModes=[0]` also means **Display-P3 wide gamut is not available either** — not
* `supportedColorModes=[0]` also means **Display-P3 wide gamut is not available either** - not
just HDR. A P3-tagged layer would be colour-converted into the panel's native gamut, i.e. into
whatever the panel natively is, with no way for us to know what that is.
* 500 nits max luminance is below the ~540-nit bar AOSP's own `has_HDR_display` doc cites, and
@@ -456,13 +456,13 @@ Vulkan-side, for completeness (device `strings`):
| Library | `VK_EXT_swapchain_colorspace` | `VK_EXT_hdr_metadata` |
|---|---|---|
| `/system/lib64/libvulkan.so` (platform loader — implements the Android swapchain) | **PRESENT** | **PRESENT** |
| `/system/lib64/libvulkan.so` (platform loader - implements the Android swapchain) | **PRESENT** | **PRESENT** |
| `/vendor/lib64/hw/vulkan.adreno.so` (Qualcomm blob) | absent | absent |
| `/vendor/lib64/hw/vulkan.turnip.so` (vendor-shipped Turnip) | **PRESENT** | **PRESENT** |
| wcp v6 `libvulkan_freedreno_wayland.so` (game driver) | **PRESENT** | **PRESENT** |
The platform loader contains the string `native_window_set_buffers_data_space(%d) failed: %s (%d)`
— i.e. Android's own swapchain implementation is what turns a `VkColorSpaceKHR` into a surface
- i.e. Android's own swapchain implementation is what turns a `VkColorSpaceKHR` into a surface
dataspace. So for the **copy path**, the compositor's output HDR is genuinely just "enable
`VK_EXT_swapchain_colorspace` at instance creation and pick a better surface format than
`fmts[0]`". No driver work.
@@ -474,11 +474,11 @@ dataspace. So for the **copy path**, the compositor's output HDR is genuinely ju
Sizes are engineer-days for someone who already knows this code. "Prove" = device-visible in logs
or `dumpsys`, not by eye. **App-only unless marked.**
### Phase A — make the truth reachable (no user-visible HDR yet)
### Phase A - make the truth reachable (no user-visible HDR yet)
| # | Repo | Work | Size |
|---|---|---|---|
| A1 | app | **Advertise 10-bit DRM formats over `zwp_linux_dmabuf_v1`.** Add `AB30`/`XB30` (and optionally `AR30`/`XR30`, `AB4H`/`XB4H`) to `compositor.c:1323-1326` + `FOURCC` defines near `:415-421`. `vkp_dmabuf_modifiers` and `drm_to_vk` already handle them, so this is a table edit + a log line. Risk: a client picking a 10-bit format while the scene/effects chain stays 8-bit — the import works (`drm_to_vk`), the blit downconverts. Gate behind a flag until A4. | **0.5 d** |
| A1 | app | **Advertise 10-bit DRM formats over `zwp_linux_dmabuf_v1`.** Add `AB30`/`XB30` (and optionally `AR30`/`XR30`, `AB4H`/`XB4H`) to `compositor.c:1323-1326` + `FOURCC` defines near `:415-421`. `vkp_dmabuf_modifiers` and `drm_to_vk` already handle them, so this is a table edit + a log line. Risk: a client picking a 10-bit format while the scene/effects chain stays 8-bit - the import works (`drm_to_vk`), the blit downconverts. Gate behind a flag until A4. | **0.5 d** |
| A2 | app | **Generate + commit `color-management-v1` protocol glue.** Fetch `staging/color-management/color-management-v1.xml` from wayland-protocols ≥ 1.41, run `wayland-scanner` offline, commit XML + `generated/color-management-v1-{protocol.c,server-protocol.h}`, add to `CMakeLists.txt`. Mechanical. | **0.5 d** |
| A3 | app | **Implement `wp_color_manager_v1` v1 server-side** (new `wl_color_mgmt.c`, ~400–500 lines): the global + bind-time feature/intent/primaries/tf events; the parametric creator with `set_primaries_named`/`set_tf_named`/`set_max_cll`/`set_max_fall`/`set_mastering_*`; image-description objects with `ready`/`failed`; `get_surface` → `wp_color_management_surface_v1` and `set_image_description` stored double-buffered on our `struct surface`. **Watch the blocking loop:** Mesa dispatches its queue waiting for `ready`, so we must send `ready` from the request handler's own flush, not defer it to the next frame, or a game stalls at swapchain creation. Advertise only what the *current output* can actually honour (see A5). | **2 d** |
| A4 | app | **Carry the image description onto the Android layer.** dlsym `ASurfaceTransaction_setBufferDataSpace` (+ `setHdrMetadata_smpte2086` / `_cta861_3`) in `sc_layer.c:82-97`; map surface image description → `ADataSpace` + `AHdrMetadata_*`; apply in `sc_layer_present_ahb` (`sc_layer.c:430-470`, next to the existing `setBuffer`). Plumb the per-surface description from `compositor.c` through `ahb_swapchain.c:219`. Also set an explicit `ADATASPACE_SRGB` on the existing 8-bit path so we stop relying on `UNKNOWN`. | **1 d** |
@@ -488,7 +488,7 @@ or `dumpsys`, not by eye. **App-only unless marked.**
genuinely HDR display gets an HDR10 swapchain, its buffer reaches an `ASurfaceControl` layer
tagged `BT2020_PQ` with real mastering metadata, and `dumpsys SurfaceFlinger` proves it.
### Phase B — the copy path and the effects chain (only if A is kept)
### Phase B - the copy path and the effects chain (only if A is kept)
| # | Repo | Work | Size |
|---|---|---|---|
@@ -498,7 +498,7 @@ tagged `BT2020_PQ` with real mastering metadata, and `dumpsys SurfaceFlinger` pr
**Phase B total: ~3 days. App-only. No new wcp.**
### Phase C — scRGB, and the one thing that needs a wcp
### Phase C - scRGB, and the one thing that needs a wcp
| # | Repo | Work | Size |
|---|---|---|---|
@@ -508,17 +508,17 @@ tagged `BT2020_PQ` with real mastering metadata, and `dumpsys SurfaceFlinger` pr
---
## 6. Cheap partial wins — and which are visible on a 500-nit panel
## 6. Cheap partial wins - and which are visible on a 500-nit panel
| Idea | Verdict on the Pocket FIT | Notes |
|---|---|---|
| **10-bit output (banding)** | **Visible, and the best value here.** | This is the one real win. B1 alone (0.5 d) gets a 10-bit output swapchain; A1 (0.5 d) lets the *game* render 10-bit. Adreno 750 + the DPU handle `RGBA_1010102` natively, and `vendor.display.enable_hdr10_gpu_target=1` says the GPU target path expects it. Pairs with the existing debanding pass — arguably makes it unnecessary for 10-bit-capable games, which saves a full-screen pass. Visible on gradients (skyboxes, fog, dark interiors) where our deband pass currently earns its keep. |
| **Display-P3 wide gamut on SDR** | **Not visible. Do not build.** | `supportedColorModes=[0]` / `ColorMode::NATIVE` — the HWC exposes no P3 mode. `persist.sys.sf.color_mode=9` asks for P3 and is ignored. Tagging a layer `ADATASPACE_DISPLAY_P3` would make SF convert P3 → the panel's native gamut, which on a NATIVE-mode display is an unknown-to-us transform. Net effect on this device: at best nothing, at worst a colour shift. |
| **10-bit output (banding)** | **Visible, and the best value here.** | This is the one real win. B1 alone (0.5 d) gets a 10-bit output swapchain; A1 (0.5 d) lets the *game* render 10-bit. Adreno 750 + the DPU handle `RGBA_1010102` natively, and `vendor.display.enable_hdr10_gpu_target=1` says the GPU target path expects it. Pairs with the existing debanding pass - arguably makes it unnecessary for 10-bit-capable games, which saves a full-screen pass. Visible on gradients (skyboxes, fog, dark interiors) where our deband pass currently earns its keep. |
| **Display-P3 wide gamut on SDR** | **Not visible. Do not build.** | `supportedColorModes=[0]` / `ColorMode::NATIVE` - the HWC exposes no P3 mode. `persist.sys.sf.color_mode=9` asks for P3 and is ignored. Tagging a layer `ADATASPACE_DISPLAY_P3` would make SF convert P3 → the panel's native gamut, which on a NATIVE-mode display is an unknown-to-us transform. Net effect on this device: at best nothing, at worst a colour shift. |
| **`setExtendedRangeBrightness` to lift highlights** | **Not available.** | `hdrSdrRatio not_available` / `NaN`, `displayBrightnessNits=-1`, `sdrWhitePointNits=-1`. `Display.isHdrSdrRatioAvailable()` is false, so there is no headroom to claim and SF has no nits data to dim the other layers against. |
| **`setDesiredHdrHeadroom`** | **Not available.** | API 35; device is API 34. Absent from `libandroid.so`. |
| **Set `ADATASPACE_SRGB` explicitly on our layers** | **Invisible but worth doing anyway (part of A4, ~0 extra cost).** | Every layer currently reports `dataspace=UNKNOWN (0)`. It works today because SF treats UNKNOWN as sRGB, but it is an accident we are relying on, and it will become wrong the moment any colour management is enabled. |
**So: of the three "cheap wins" in the brief, exactly one — 10-bit — is real on this hardware,
**So: of the three "cheap wins" in the brief, exactly one - 10-bit - is real on this hardware,
and it is worth about 1 engineer-day (A1 + B1) on its own, independent of HDR.**
---
@@ -535,13 +535,13 @@ candidates, easiest first:
*Mass Effect Legendary Edition*. RE Engine titles are the usual smoke test on Linux because they
call `SetColorSpace1` early and unconditionally when DXGI reports HDR.
* **D3D12 + HDR10:** *Cyberpunk 2077*, *Forza Horizon 5*, *Horizon Zero Dawn*. These go through
vkd3d-proton's stricter path (§1.1) — good for catching a half-done implementation, since a
vkd3d-proton's stricter path (§1.1) - good for catching a half-done implementation, since a
wrong answer **stalls presentation** instead of degrading.
* **Sanity harness, no game needed:** anything that calls `vkGetPhysicalDeviceSurfaceFormatsKHR`
under the layer. `vulkaninfo` is not available in the prefix, but a tiny Win32 Vulkan probe
built against the layer's headers, or simply DXVK's own `VK_INSTANCE_LAYERS`-free log with
`DXVK_LOG_LEVEL=info` and `DXVK_HDR=1`, will say whether the colour space was accepted. **Start
here** — it is the cheapest signal and needs no HDR display at all.
here** - it is the cheapest signal and needs no HDR display at all.
### 7.2 Platform-side verification (not by eye)
@@ -553,11 +553,11 @@ Order of proof, each step gating the next:
2. **Guest log.** `DXVK_HDR=1` + `DXVK_LOG_LEVEL=info` → DXVK prints the chosen colour space and
format at swapchain creation. If `SetColorSpace1` was refused, DXVK says so. Mesa's WSI prints
`Not using HDR metadata to avoid protocol errors` when `is_hdr_metadata_legal` rejects metadata
— catching that string is a direct test of A3's metadata plumbing.
- catching that string is a direct test of A3's metadata plumbing.
3. **`dumpsys SurfaceFlinger | grep banner_wayland_game`.** Today it prints
`dataspace=UNKNOWN (0) hdr metadata types=0`. Success = `dataspace:0x9c60000` (`BT2020_PQ`, 163971072 =
`STANDARD_BT2020|TRANSFER_ST2084|RANGE_FULL`) and `hdr metadata types=` non-zero. **Also record `composition:` on the same line**
— if it flips DEVICE → CLIENT, HDR cost us the zero-copy win (§3.4) and that is a failure, not a
- if it flips DEVICE → CLIENT, HDR cost us the zero-copy win (§3.4) and that is a failure, not a
success.
4. **`dumpsys display`.** On whatever display is in use: `supportedHdrTypes=[...]` non-empty,
`colorMode` ≠ 0, `hdrSdrRatio` ≠ `not_available`. This is the gate for steps 5–6; on the Pocket
@@ -567,14 +567,14 @@ Order of proof, each step gating the next:
`UNKNOWN (0)`.
6. **Only then, by eye.**
### 7.3 Getting a display that can actually show it — three options, ranked
### 7.3 Getting a display that can actually show it - three options, ranked
1. **External HDR display over USB-C (recommended, cheapest).** The app already reparents the game
into a `Presentation` on a secondary display —
into a `Presentation` on a secondary display -
`app/src/main/java/com/winlator/star/display/ExternalDisplayController.java`,
`findPresentationDisplay()` picks a `DISPLAY_CATEGORY_PRESENTATION` display that is not the
activity's own. In the Wayland session the compositor's `SurfaceView` is the reparented view, so
`sc_layer.c`'s `ASurfaceControl_createFromWindow(vkp_window(), ...)` follows it automatically —
`sc_layer.c`'s `ASurfaceControl_createFromWindow(vkp_window(), ...)` follows it automatically -
**no new plumbing to test on an external panel.** Risk: `Display.getHdrCapabilities()` for a
DP-alt-mode display depends on the vendor HWC reading the external EDID, and empty lists for
genuinely HDR10 monitors are a common Snapdragon gap (§3.6). **Step zero is a five-minute,
@@ -587,7 +587,7 @@ Order of proof, each step gating the next:
"Other GPUs… the Galaxy Fold (A840) logs are still outstanding"). Chasing HDR there before
plain Wayland is proven there inverts the priority order.
3. **Plumbing-only verification on SDR.** Everything in §7.2 steps 1–3 works on the Pocket FIT.
This proves the code is *correct* but proves nothing about whether it *looks right* — and
This proves the code is *correct* but proves nothing about whether it *looks right* - and
tone-mapping quality is the entire user-visible payload of HDR. **Do not ship on this evidence
alone.**
@@ -600,7 +600,7 @@ Order of proof, each step gating the next:
The reasoning, plainly:
* **The effort is genuinely small and smaller than we thought.** ~4.5 days to a plumbed HDR10
path, **app-only, no new wcp** — because Mesa's colour-management client is already inside the
path, **app-only, no new wcp** - because Mesa's colour-management client is already inside the
shipped wcp v6 driver and our zero-copy WSI patch already maps 10-bit to gralloc. The phase-4
memory note saying HDR "does need a new wcp" should be corrected: only scRGB/FP16 zero-copy (C1)
does, and that is optional.
@@ -616,7 +616,7 @@ The reasoning, plainly:
a feature nobody can exercise.
* **It is also out of order.** The pre-4 checkpoint's ranked list puts "other GPUs" and "prove
zero-copy where it can win, then make it the default" first, with multi-layer presentation in
flight. HDR competes with those for the same `sc_layer.c` surface area — and multi-layer will
flight. HDR competes with those for the same `sc_layer.c` surface area - and multi-layer will
rewrite exactly the code A4 touches. Landing HDR into `sc_layer.c` now means merging it twice.
**What the user would actually see for the effort, honestly:**
@@ -626,16 +626,16 @@ The reasoning, plainly:
* **Today, Pocket FIT, the 10-bit slice only (A1 + B1, ~1 day):** *slightly* smoother gradients in
dark scenes and skyboxes for games that offer a 10-bit swapchain, and a plausible route to
retiring the debanding pass (one fewer fullscreen pass) for those games. Small, real, and it is
the foundation Phase A sits on anyway — so it is not wasted work if HDR later goes ahead.
the foundation Phase A sits on anyway - so it is not wasted work if HDR later goes ahead.
* **Later, on an HDR display (external monitor or the Fold), full Phase A:** genuinely brighter
highlights and a wider gamut in the ~15 PC titles that implement HDR properly, on the one Android
emulator that can do it. That is a real headline feature and a real differentiator — but only
emulator that can do it. That is a real headline feature and a real differentiator - but only
once there is a panel to show it on.
**Recommended sequence:**
1. **Five minutes, zero code:** plug an HDR monitor into the Pocket FIT's USB-C and run
`dumpsys display | grep -A2 hdrCapabilities`. This single reading decides everything —
`dumpsys display | grep -A2 hdrCapabilities`. This single reading decides everything -
it is the difference between "we can develop and prove HDR today on hardware we own" and
"HDR is blocked on the Fold."
2. **~1 day, independent of HDR:** the 10-bit slice (A1 + B1), gated and A/B'd for banding and
@@ -656,7 +656,7 @@ The reasoning, plainly:
No external display was connected and I did not connect one. This is the single highest-value
unknown in the whole report (§8, step 1).
* **Whether an HDR-tagged layer really drops DEVICE → CLIENT on this HWC.** The AOSP code path is
clear (§3.4) but it is vendor-HWC behaviour and I did not test it — testing it would mean
clear (§3.4) but it is vendor-HWC behaviour and I did not test it - testing it would mean
launching a game, which was out of scope.
* **What the Galaxy Fold (Adreno 840, Android version unknown to me) reports.** Not connected.
Its `getHdrCapabilities()` and `isHdrSdrRatioAvailable()` are the other decisive readings.
@@ -674,7 +674,7 @@ The reasoning, plainly:
---
## 10. Round 1 — as built (2026-09-14, `feat/wayland-hdr`)
## 10. Round 1 - as built (2026-09-14, `feat/wayland-hdr`)
Phase A (A1–A5) for HDR10, opt-in, proven by the app's own logs because the first HDR panel in the
loop is a tester's non-rooted Galaxy Fold (Adreno 840, Android API 37: HDR10/HLG/HDR10+, 1351 nits,
@@ -691,7 +691,7 @@ Open only when ALL hold when the compositor starts:
| display layers with dataspace control | `sc_layer_can_tag_hdr()` = SurfaceControl API + `ASurfaceTransaction_setBufferDataSpace` |
| the zero-copy global | `ahb_swapchain_advertised()` |
`BANNER_WAYLAND_HDR=force` skips the display row only (testing the negotiation on an SDR panel —
`BANNER_WAYLAND_HDR=force` skips the display row only (testing the negotiation on an SDR panel -
SurfaceFlinger then tone-maps the layer). A **closed** gate advertises nothing (no
`wp_color_manager_v1` global, no 10-bit dma-buf rows), writes `color … HDR gate CLOSED: <why>` and
`HDR on screen: no, because <why>`, and the session is otherwise byte-for-byte the old one. With the
@@ -706,13 +706,13 @@ only right on the game's own layer) and exports `BANNER_WSI_AHB=1` to match.
primaries `bt2020`; transfer `st2084_pq`. Not advertised: `srgb` (so Mesa creates no colour surface for
SDR swapchains at all), HLG (no DXGI swapchain uses it), `ext_linear`/`extended_target_volume` (scRGB =
Phase C, needs FP16 gralloc + a layer change), ICC, `windows_scrgb`. `zwp_linux_dmabuf_v1` gains
`AB30`/`XB30` (A2B10G10R10 — Mesa lists a VkFormat only when both the alpha and opaque fourcc are there),
`AB30`/`XB30` (A2B10G10R10 - Mesa lists a VkFormat only when both the alpha and opaque fourcc are there),
appended after the four 8-bit rows. Protocol glue generated from wayland-protocols **1.41** with
wayland-scanner 1.24.0 (`protocols/color-management-v1.xml`).
Strictness: protocol errors only where a conforming client can never hit them (un-advertised
feature/intent/primaries/tf, a property set twice, an incomplete set, a not-ready description).
Everything a conforming client can produce on a bad day is logged and absorbed instead — out-of-range
Everything a conforming client can produce on a bad day is logged and absorbed instead - out-of-range
HDR metadata is dropped from what Android gets (and `max_cll`/`max_fall` of 0 = "unknown", which Mesa
sends as-is), a second colour surface for the same `wl_surface` replaces the first, requests on inert
objects are ignored. `ready` is sent from inside `create` (Mesa blocks its swapchain on it).
@@ -727,7 +727,7 @@ puts it back to `UNKNOWN` and clears the metadata. The zero-copy frame gets the
description; the 8-bit pool copy of an HDR frame keeps the PQ tag (colours right, 8-bit precision,
logged once); the effects pass and the overlay layer are always untagged.
### 10.4 When an HDR frame cannot be zero-copy — round 1's decision
### 10.4 When an HDR frame cannot be zero-copy - round 1's decision
No tone-mapping anywhere (the copy path is `vkCmdBlitImage` into an 8-bit sRGB swapchain; a PQ→SDR
shader pass is its own project). Instead:
@@ -741,7 +741,7 @@ shader pass is its own project). Instead:
unavailable:** the scene goes through the copy path and the HDR frames are shown **untone-mapped
(washed out)**; every such scene is counted and the reason logged.
### 10.5 Proof without root — what a tester's logs say
### 10.5 Proof without root - what a tester's logs say
`Download/Wayland-logs/wayland-*.log`, tag `color` (plus the existing `display` capability line):
@@ -754,14 +754,14 @@ shader pass is its own project). Instead:
| `<window> presents WxH buffers in XB30 (10-bit A2B10G10R10) …, gralloc RGBA1010102 (10-bit)` | the 10-bit swapchain really arrived |
| `banner_wayland_game: dataspace BT2020_PQ (0x9c60000) set on the display layer …` | the tag + metadata SurfaceFlinger received |
| `HDR last 10 s: N frames on the display layer tagged BT2020_PQ …` | steady state |
| `display HDR/SDR ratio X (was Y; HDR frames on screen: yes …)` | `Display.getHdrSdrRatio()` — rises above 1.00 only when Android grants HDR headroom |
| `display HDR/SDR ratio X (was Y; HDR frames on screen: yes …)` | `Display.getHdrSdrRatio()` - rises above 1.00 only when Android grants HDR headroom |
| `HDR on screen: yes / tagged but NOT confirmed / no, because …` | the verdict (written on changes, at game exit and at session end; the last one counts) |
DXVK's own `<exe>_dxgi.log` / `<exe>_d3d11.log` add `Color space: VK_COLOR_SPACE_HDR10_ST2084_EXT` and
the 10-bit format at swapchain creation; Mesa's `Not using HDR metadata to avoid protocol errors`
(stderr → `wine_debug.log`) means the game's metadata failed Mesa's own legality check.
## 11. Round 2 — as built (2026-09-14, `feat/wayland-hdr`; CI only, not device-proven yet)
## 11. Round 2 - as built (2026-09-14, `feat/wayland-hdr`; CI only, not device-proven yet)
Round 1 is proven on the tester's Fold (God of War, DXVK v3.1: 10-bit zero-copy, `BT2020_PQ` on the
layer, HDR/SDR ratio 1.00 → 2.51, `HDR on screen: yes`). Round 2 makes it a setting and removes
@@ -771,7 +771,7 @@ The gate itself is unchanged (§10.1) apart from its first input.
### 11.1 The setting, and what the launch does with it
- `Container.isWaylandHdr()` (extraData `waylandHdr`) and the shortcut extra `waylandHdr` (`1`/`0`/unset
= the container's) — one resolver, `display/WaylandHdr.effective()`, used by the three editors
= the container's) - one resolver, `display/WaylandHdr.effective()`, used by the three editors
(container, game shortcut, XMB game settings) and the launch path. `BANNER_WAYLAND_HDR` in the
environment still overrides it (`1` / `0` / `force`). Editors grey the row with the reason when the
built-in screen does not list HDR10 (`WaylandHdr.unavailableReason`), and say it applies from the
@@ -780,14 +780,14 @@ The gate itself is unchanged (§10.1) apart from its first input.
after the user's env merge unless the user set `DXVK_HDR` themselves.
- Every Wayland session whose display lists **HDR10** exports `BANNER_WAYLAND_HDR_MAX_NITS`,
`…_MAX_AVG_NITS`, `…_MIN_NITS` (decimal nits from `Display.getHdrCapabilities()`; unknown values and
a max of 0 are left out) — the contract the Wayland layer from versionCode 10 turns into EDID HDR
a max of 0 are left out) - the contract the Wayland layer from versionCode 10 turns into EDID HDR
metadata for DXGI (checked by the Wine side against DXVK's own EDID parser: the Fold's 1351/1351/0 →
DXGI max 1345.43, max full-frame 1345.43, min 0.01). Never on an SDR display, whose EDID would then
claim PQ support. One `session environment:` line logs them. Android has no live absolute nits; the
live evidence stays the HDR/SDR ratio.
- A "DXVK before 3.0 needs layer v10" warning was built and then **removed**: its premise was wrong
(Wine already exposes `VK_EXT_swapchain_colorspace` at instance level; DXVK ≥ 2.1 looks for it in the
device list, logs 0 on every Mesa system — the working v3.1 run logs 0 too — and never uses it for the
device list, logs 0 on every Mesa system - the working v3.1 run logs 0 too - and never uses it for the
HDR decision). Why God of War offered no HDR option on DXVK 2.4.1 is open (Fold A/B).
### 11.2 HDR-aware composition (`hdr_compose.c`, `hdr_encode.frag`, compositor.c `hdr_plan`)
@@ -907,4 +907,4 @@ hot, not recording, brightness 8-223 manual - and the HDR/SDR ratio at **1.00 th
perceptual SDR-like data. If interpolation artefacts show only in HDR, that is the next thing to try.
- Colour effects (brightness/contrast/saturation/gamma, the "HDR" bloom) operate on the PQ signal in
route 1 and look stronger than in SDR; sharpening/AA/CRT/upscalers are perceptually fine.
- scRGB (FP16) swapchains (Phase C) — unchanged: needs FP16 gralloc and a layer change.
- scRGB (FP16) swapchains (Phase C) - unchanged: needs FP16 gralloc and a layer change.
+33 -33
View File
@@ -3,23 +3,23 @@
Experimental **parallel** display runtime: run/launch games through Wine's
`winewayland.drv` talking to our own embedded Wayland compositor, instead of the
X11 path (pure-Java X11 server + `libwinlator.so`). The X11 runtime stays the
default and is untouched — this is a separate flavor/branch.
default and is untouched - this is a separate flavor/branch.
## What's already proven (spike repo `bannerlator-wayland`, device-tested on Adreno 750)
- Minimal libwayland-server compositor: globals + xdg-shell handshake + buffer commit.
- **Turnip's Vulkan WSI exports real zero-copy dmabufs to our external compositor**
(same Mesa path winewayland.drv uses for DXVK/VKD3D) — risk #1 retired.
(same Mesa path winewayland.drv uses for DXVK/VKD3D) - risk #1 retired.
- Compositor imports that dmabuf into its own Turnip VkImage (`vk_import.c`).
The staged `src/` here is that proven code, to grow into the app-embedded compositor.
## Dependencies
1. **A Proton 11 arm64ec wcp that ships `winewayland.drv`** — built on branch
1. **A Proton 11 arm64ec wcp that ships `winewayland.drv`** - built on branch
`The412Banner/proton-wine:feat/winewayland` (task #1). Nothing runs end-to-end
without it.
2. **Wayland runtime libs in the imagefs** so `winewayland.so` (unixlib) loads:
`libwayland-client.so`, `libwayland-egl.so`, `libxkbcommon.so`, `libxkbregistry.so`
(bionic aarch64). The wcp bundles them in its `lib/` as a fallback; the clean home
is the imagefs — add via `ImageFsInstaller` (new `installWaylandLibs()`), same
is the imagefs - add via `ImageFsInstaller` (new `installWaylandLibs()`), same
pattern as `installFFmpeg8()`.
## Integration plan (M4)
@@ -36,13 +36,13 @@ The staged `src/` here is that proven code, to grow into the app-embedded compos
and point the container at the winewayland wcp.
## Status
- ✅ **Native lib foundation done + compile-verified.** Compositor + vk_import + pre-generated
- **Native lib foundation done + compile-verified.** Compositor + vk_import + pre-generated
protocol glue build as `libbannerwayland.so` (CMake target added), linking the vendored
bionic `libwayland-server`. Verified: compiles/links clean as an aarch64 bionic `.so`,
exports `banner_wayland_run`, NEEDED = libwayland-server + libvulkan. JNI entry
(`waylandcomp_jni.c`) + `WaylandCompositor.java` bring it up on a thread. Compositor-process
runtime deps (libwayland-server/libffi/libandroid-support) staged in `jniLibs/arm64-v8a`.
- ⏭️ **Next phase (gated on the winewayland wcp landing green):** `WaylandDisplayActivity`
- **Next phase (gated on the winewayland wcp landing green):** `WaylandDisplayActivity`
(SurfaceView) + JNI `ANativeWindow`→Vulkan swapchain + blit the imported game VkImage to the
window (last un-proven render step) + input + launch wiring (start compositor, `WAYLAND_DISPLAY`,
per-prefix `Drivers\Graphics=winewayland`) + `ImageFsInstaller.installWaylandLibs()` (client/egl/xkb
@@ -126,7 +126,7 @@ small interface in `src/banner_ext.h` (compositor.c only gained hook calls + acc
control calls `ImmSetCompositionWindow`; the app (`WaylandTextInput`) shows the soft keyboard only
then (and with no hardware keyboard), hides it on disable unless the user's own toggle opened it.
Typed text: `SurfaceInputView`'s `InputConnection` → `commit_string` / `preedit_string` + `done`.
Deletions become Backspace/Delete key presses — winewayland's `delete_surrounding_text` handler is
Deletions become Backspace/Delete key presses - winewayland's `delete_surrounding_text` handler is
empty. Log tag `text-input`.
- **Window icons** (`src/wl_toplevel_icon.c`): `xdg_toplevel_icon_manager_v1` **v1**, accepts and
drops icons (`done` at bind, no sizes).
@@ -166,15 +166,15 @@ small interface in `src/banner_ext.h` (compositor.c only gained hook calls + acc
- Caveat: both sides must agree on the UBWC encoding for the GPU. The game runs the wcp's Wayland
Turnip, the compositor the user's adrenotools Turnip; the layout code (`fdl6`) is the same, but a
very different Mesa version on one side is the first suspect if a compressed frame imports fine
yet looks scrambled — `=0` is the workaround, and the `gpu` line names both the GPU and the
yet looks scrambled - `=0` is the workaround, and the `gpu` line names both the GPU and the
compositor's driver.
## Phones with no DRM node (OpenGL) — `BANNER_WAYLAND_NO_RENDER_NODE=1`
## Phones with no DRM node (OpenGL) - `BANNER_WAYLAND_NO_RENDER_NODE=1`
- The feedback's `main_device` is the first of `/dev/dri/renderD128`, `renderD129`, `card0` the app
can `stat`; retail phones (Adreno 830/840 reports, 2026-09-14) expose none, so it is `0:0`.
Vulkan games do not care. Mesa's EGL did: its Wayland DRM initialiser failed the display in
`dri2_setup_device()` without a render node and fell back to a software path that has no
rasteriser in these layers — native OpenGL black, sound playing. Wayland layer versionCode 9
rasteriser in these layers - native OpenGL black, sound playing. Wayland layer versionCode 9
(Banners-Turnip `patches/wayland/egl_wayland_no_drm_node.py`) runs zink + kopper on the Vulkan
device without a node instead; nothing app-side is needed for that.
- `BANNER_WAYLAND_NO_RENDER_NODE=1` (container or shortcut env) makes the compositor advertise
@@ -240,7 +240,7 @@ again on every flip. The compositor owns the state:
early-outs), which DXVK, vkd3d-proton and Zink all answer by rebuilding the swapchain. The mode
event is read with a non-blocking dispatch of the display queue on each acquire/present, because
in MAILBOX that queue is otherwise only dispatched when the acquire loop runs out of images.
- **Compatibility, both directions.** The registry bind clamps to `MIN(advertised, 2)` — binding
- **Compatibility, both directions.** The registry bind clamps to `MIN(advertised, 2)` - binding
above the advertised version is a fatal `wl_display` error, and a Bannerlator from before the live
switch advertises version 1. On version 1, and on version 2 before the first `mode` event arrives,
the driver keeps the original contract exactly: gralloc images iff `BANNER_WSI_AHB=1`, decided per
@@ -248,8 +248,8 @@ again on every flip. The compositor owns the state:
forces it on (the app exports that on every zero-copy launch, which would freeze the switch);
`BANNER_WSI_AHB=0` still forces the whole feature off.
- **No black frame, either way.** Switching OFF does not tear down anything: the old gralloc chain's
frames keep being shown — on the layer when this renderer could not import them, through the copy
path when it could — until the game has rebuilt, and only then does `sc_layer_hide()` run. Buffers
frames keep being shown - on the layer when this renderer could not import them, through the copy
path when it could - until the game has rebuilt, and only then does `sc_layer_hide()` run. Buffers
already on the layer keep their deferred release (`ahb_swapchain_defer_release` is no longer gated
on `g_zero_copy`, or the display would be handed a buffer it is still scanning out). Switching ON,
the layer path resumes as soon as the first `attach` of the new chain lands.
@@ -289,7 +289,7 @@ app window ....... Compose UI, the in-game drawer, the perf HUD, the on-screen c
runtime). The SurfaceControls are children of the SurfaceView's surface, created on first use and
retired together when the output window changes or goes away.
- **What can be on the game layer**, cheapest first: the game's own gralloc buffer (zero-copy, no
copy anywhere — `ahb_swapchain.c`); one blit of the game's frame into a compositor buffer
copy anywhere - `ahb_swapchain.c`); one blit of the game's frame into a compositor buffer
(`sc_layer_present`); or, with screen effects on, the compositor pass's **result** blitted into
such a buffer (`sc_layer_present_pass` → `vkp_pass_begin` / `vkp_pass_copy_to`). The last one is
what keeps a Look from dropping the session back to the app's swapchain: the scene → output
@@ -298,29 +298,29 @@ app window ....... Compose UI, the in-game drawer, the perf HUD, the on-screen c
- **Present order matters, and it was measured.** The layers go up first; the base surface's black
frame is presented *after* the layer transaction, and the effects chain runs in its own submit
with **no swapchain image acquired**. A present holds an acquired image and the acquire semaphore
is a vblank gate: folding the chain into that submit (one command buffer, one present — the
is a vblank gate: folding the chain into that submit (one command buffer, one present - the
shape that looks cheaper) put the whole 13-pass chain behind a vblank and measured **72 fps**
against **111 fps** for the split shape, on HL2 + Retro CRT at 1920x1080 on the Pocket FIT (the
copy path is 129 fps on the same scene). Anyone tempted to "optimise" this into one submit should
read this paragraph first.
- **What goes on the overlay layer**: exactly one draw above the game — a second Wayland toplevel
- **What goes on the overlay layer**: exactly one draw above the game - a second Wayland toplevel
(a launcher or settings window, a message box), copied 1:1 into the overlay pool and then
*cropped and placed* by the display through the same `vkp_map_draw` mapping the copy path uses.
The point is what does **not** happen: the game's frames are no longer copied through the
compositor's swapchain just because something small sits on top of them.
- **Transparency.** The compositor composes with blits, which overwrite — it never alpha-blends,
on either path — so every layer is marked `ASC_TRANSPARENCY_OPAQUE` and the overlay layer is
- **Transparency.** The compositor composes with blits, which overwrite - it never alpha-blends,
on either path - so every layer is marked `ASC_TRANSPARENCY_OPAQUE` and the overlay layer is
cropped to the window it carries. There is no blending to get wrong: no black box over the game,
no double-darkening, and the picture is the copy path's, pixel for pixel.
- **Input is untouched.** An `ASurfaceControl` has no input channel, so neither layer can take a
touch: everything still reaches the app's `SurfaceView` (and the views above it) exactly as
before, and the scene mapping touch goes through (`vkp_output_to_scene` / `ViewTransformation`)
is the same one the layers are placed with, so the cursor still lands where it is pointing. The
SurfaceView is not Z-on-top, so its whole subtree — both layers included — stays under the
SurfaceView is not Z-on-top, so its whole subtree - both layers included - stays under the
activity's own window: the drawer, the HUD and every Compose dialog draw above them.
- **What cannot be layered, and why.**
- *Frame generation*: each generated frame needs a present of its own on consecutive vblanks, and
a display layer latches one buffer per refresh — pacing that is the swapchain's job. While an
a display layer latches one buffer per refresh - pacing that is the swapchain's job. While an
engine is armed the whole scene takes the copy path (unchanged).
- *Effects with a window above the game*: the chain has to see the whole scene to look the way it
does on the copy path (and on X11), and the game layer only carries the game. Copy path.
@@ -332,37 +332,37 @@ app window ....... Compose UI, the in-game drawer, the perf HUD, the on-screen c
every layer down (scene no longer a fullscreen game, zero-copy switched off live, session end),
`sc_layer_hide_overlay()` is used when only the window above the game closed, and
`sc_layer_window_gone()` retires both SurfaceControls and drains both pools on a surface loss /
HOME / resume. **The overlay layer is always RETIRED, never merely hidden** (both paths) — see
HOME / resume. **The overlay layer is always RETIRED, never merely hidden** (both paths) - see
the HWC note below: a live second SurfaceControl keeps SurfaceFlinger composing on the GPU even
when it is invisible. The game layer keeps its SurfaceControl through a hide, because it goes up
and down with every effects / frame-generation toggle.
- **The display frame-rate vote belongs to one layer.** The refresh-rate stream's
`sc_layer_set_frame_rate()` (the game's cadence, the same value the app votes on its own surface)
is carried **only** by the layer the game presents on — the game layer. The overlay layer is
is carried **only** by the layer the game presents on - the game layer. The overlay layer is
explicitly voted `0`, so a window that redraws once a second can never hold the panel at the
game's cadence, nor drag the game's cadence down to its own. Each layer remembers what its live
SurfaceControl carries (`fps_applied`) and re-applies on the next transaction, and a retired
SurfaceControl resets it so a re-created layer is re-voted from scratch. Log: `display frame-rate
vote on banner_wayland_game: 60.00 Hz`.
- **Stats.** The 10 s `stats` line now ends with `| N zero-copy frames` (the game's own buffers) and
`| N layer frames` (frames the compositor put on a layer through one of its own buffers — the
`| N layer frames` (frames the compositor put on a layer through one of its own buffers - the
plain layer blit or the effects result). Both are hardware-composed; only the first is copy-free.
- **Measured on the Pocket FIT (Adreno 750, portrait panel, landscape session → every layer is
ROT_90 + scaled), `dumpsys android.hardware.graphics.composer3.IComposer/default`:** one layer is
`composition: DEVICE/DEVICE` (game's own gralloc buffer scanned out by the DPU), with effects on
the layer it stays `DEVICE/DEVICE`, but **two** layers flip the whole frame to `DEVICE/CLIENT` —
SurfaceFlinger composes it on the GPU — **and it does not come back when the overlay goes away**:
the layer it stays `DEVICE/DEVICE`, but **two** layers flip the whole frame to `DEVICE/CLIENT` -
SurfaceFlinger composes it on the GPU - **and it does not come back when the overlay goes away**:
retiring the overlay's SurfaceControl (which the compositor now does rather than merely hiding
it) leaves the frame in client composition; only re-creating the *game* layer's SurfaceControl
clears it (HOME + resume does, reproduced twice). Retiring is still right — one fewer live layer,
and it leaves the HWC list — it is just not the whole cure; the open follow-up is to retire and
clears it (HOME + resume does, reproduced twice). Retiring is still right - one fewer live layer,
and it leaves the HWC list - it is just not the whole cure; the open follow-up is to retire and
immediately re-create the game layer when the overlay goes, which would cost one black frame
unless the new SurfaceControl is shown before the old one is dropped. The likely mechanism is the
DPU's rotator budget (one rotated+scaled layer), not the layer count as such, so a device or
orientation that needs no rotation may well take both on the DPU. Even in client composition the
overlay layer is not a loss (SurfaceFlinger does the one blit the compositor would have done), but
the hardware-composition win is only real for the single-layer cases. Note `VRI[ScreenDecorHwcOverlay]`
is always `DISPLAY_DECORATION/CLIENT` (the system's rounded corners) — that is why SurfaceFlinger's
is always `DISPLAY_DECORATION/CLIENT` (the system's rounded corners) - that is why SurfaceFlinger's
`clientCompositionFrames` counter reads 100 % on this device in every state and is useless here.
- **Not done yet:** a second toplevel that is itself rendering into gralloc buffers could go on the
overlay layer zero-copy too (the token machinery in `ahb_swapchain.c` is already per-buffer, not
@@ -371,7 +371,7 @@ app window ....... Compose UI, the in-game drawer, the perf HUD, the on-screen c
## Screen effects (feat/wayland-effects, `src/effects_chain.c`)
The X11 renderer's screen-effect chain, run by the compositor between the composited scene and the
output. Same SPIR-V as the X11 Vulkan renderer (`winlator/*_frag.h`, made by `winlator/gen_shaders.sh`
and committed — the NDK build compiles no GLSL, so there is no build-time shader tooling), same
and committed - the NDK build compiles no GLSL, so there is no build-time shader tooling), same
push-constant layouts, uniform ranges and pass order, so a saved preset looks the same on both backends.
**Present-pass hook order (`vk_present.c`, `vkp_render`):**
@@ -384,7 +384,7 @@ scene (every draw blitted 1:1 into a scene-sized R8G8B8A8 image; compositor pas
-> present generated frames first, the real frame last, FIFO
```
The compositor pass runs when either stage needs it (`vkp_effects_active() || vkp_framegen_active()`).
Effects operate on the scene; the mapping operates on the output — the chain's result stands for
Effects operate on the scene; the mapping operates on the output - the chain's result stands for
the whole scene and goes through the same `draw_to_blit` as a plain frame. With everything off the
frame takes the old path unchanged (draws blitted straight through the mapping); only the blit filter
follows the scaling mode (Nearest = `VK_FILTER_NEAREST`).
@@ -409,12 +409,12 @@ them logs an `error` and effects stay off for the session). The app wires the dr
post-chain block (`XServerDialogState.on*Apply`) to these in `XServerDisplayActivity.initWaylandEffects`
and remembers the same per-game keys as the Vulkan path (#382).
**Zero-copy interplay:** the chain's result no longer has to land in the app's swapchain — with a
**Zero-copy interplay:** the chain's result no longer has to land in the app's swapchain - with a
fullscreen game alone on screen it is copied into the game layer's own gralloc buffer and the game
**stays on its display layer** while a Look is applied (see "Multi-layer presentation" below). It
still takes the copy path when a window is drawn above the game (the chain has to see the whole
scene to look as it does on X11) — `effects zero-copy paused: a window above the game needs the
compositor pass for the whole scene` — and always while frame generation is armed
scene to look as it does on X11) - `effects zero-copy paused: a window above the game needs the
compositor pass for the whole scene` - and always while frame generation is armed
(`framegen zero-copy paused: frame generation needs the compositor pass`); the layer comes back with
`effects zero-copy resumed: the game is back on its own display layer`. A frame this renderer could
not import (layer-only candidate) still goes on the layer, effects/frame generation skipped, said once.
+30 -30
View File
@@ -1,4 +1,4 @@
# Zero-copy window layers on Wayland — research spike + host-side prototype
# Zero-copy window layers on Wayland - research spike + host-side prototype
Branch `spike/wayland-zero-copy-layers` (on `feat/wayland-phase2`). Written 2026-09-13.
@@ -14,21 +14,21 @@ adrenotools Turnip.
**Answer in one paragraph.** A raw dma-buf can never become an `AHardwareBuffer` (option b is
closed: no public API, and the game's buffers are `/dev/dma_heap/system` allocations, not
gralloc buffers). The interop must go the other way: the buffer is a **gralloc `AHardwareBuffer`
first**, and its dma-buf fd (`native_handle->data[0]`) is what the Vulkan drivers import — which is
first**, and its dma-buf fd (`native_handle->data[0]`) is what the Vulkan drivers import - which is
exactly how Turnip already imports every gralloc buffer on Android (`vk_android.c`). Both Turnips
in play already have every extension needed; nothing is missing in the drivers. What is missing is
a **WSI hook**: Mesa's Wayland WSI always allocates its own dma-bufs and has no way to receive or
allocate compositor-visible buffers, so **option (a) or (c) each need a ~300-line patch to
`wsi_common_wayland.c` in our own Wayland Turnip build** (banners-turnip-wayland
`build_turnip_wayland_wsi.sh`, Mesa `7cda7850`) plus a small private Wayland protocol. Nothing in
the app can remove the copy on its own. Recommended: **option (a′) — the game's WSI allocates its
the app can remove the copy on its own. Recommended: **option (a′) - the game's WSI allocates its
swapchain images as `AHardwareBuffer`s (gralloc-native, UBWC), imports them through the AHB path
Turnip already has, and hands the compositor the AHB over a Unix socket (`AHardwareBuffer_send/
recvHandleFromUnixSocket`, the same mechanism the X11 renderer already uses for `GPUImage`) plus
the dma-buf fd through `zwp_linux_dmabuf_v1` as today (so the blit path stays as the fallback).**
The host half — one `ASurfaceControl` layer per fullscreen window, geometry from the fullscreen
The host half - one `ASurfaceControl` layer per fullscreen window, geometry from the fullscreen
mode, release fences from `ASurfaceTransaction_setOnComplete`, black base surface, HUD/pointer as
Android views above — is implemented in this branch as a gated prototype (`sc_layer.c`,
Android views above - is implemented in this branch as a gated prototype (`sc_layer.c`,
`BANNER_WAYLAND_ZERO_COPY=1`) with a compositor-owned AHB pool and one blit, so the
SurfaceFlinger side can be measured on the device before the driver work starts.
@@ -47,7 +47,7 @@ Facts the options rest on (Mesa `7cda7850`, the commit both Turnips are built fr
- **Dma-buf import works on both Turnips**: `VK_KHR_external_memory_fd`,
`VK_EXT_external_memory_dma_buf`, `VK_EXT_image_drm_format_modifier` are unconditional
(`tu_device.cc:253, 354, 369`); the compositor proves it every frame. Only
`VK_EXT_physical_device_drm` is off on KGSL (`:385`) — relevant to dmabuf-v4 feedback (§2).
`VK_EXT_physical_device_drm` is off on KGSL (`:385`) - relevant to dmabuf-v4 feedback (§2).
- **AHB import in Turnip is dma-buf import.** `VK_ANDROID_external_memory_android_hardware_buffer`
is exposed whenever a u_gralloc backend exists (`tu_device.cc:219, 428`), and the fallback backend
always exists. `vkGetAndroidHardwareBufferPropertiesANDROID` does
@@ -59,7 +59,7 @@ Facts the options rest on (Mesa `7cda7850`, the commit both Turnips are built fr
int) the UBWC flag `0x08000000` in the next int selects `DRM_FORMAT_MOD_QCOM_COMPRESSED`, else
`DRM_FORMAT_MOD_LINEAR`; pitch = `pixel_stride × bpp`, offset 0. The qcom backend
(`u_gralloc_qcom.c`, `hw_get_module`) cannot load the vendor gralloc from an app process, so the
fallback is the one in use — the local KGSL build imports exactly `AHardwareBuffer_allocate /
fallback is the one in use - the local KGSL build imports exactly `AHardwareBuffer_allocate /
describe / getNativeHandle / acquire / release / isSupported` and `hw_get_module`, NEEDED
`libnativewindow.so` + `libhardware.so` (readelf on `turnip608/stg/libvulkan_freedreno.so`).
So **the Wine process already loads `libnativewindow.so`** (as a dependency of the ICD), and
@@ -69,7 +69,7 @@ Facts the options rest on (Mesa `7cda7850`, the commit both Turnips are built fr
### (a) Game side: `AHardwareBuffer_allocate` in the guest, exported as a dma-buf
Feasible with the current drivers, **but only through a WSI patch** — the app cannot do it.
Feasible with the current drivers, **but only through a WSI patch** - the app cannot do it.
Mesa's Wayland WSI creates every native swapchain image with `wsi_create_native_image_mem`
(`wsi_common_drm.c:760-850`): `vkAllocateMemory` with `VkExportMemoryAllocateInfo{DMA_BUF}` →
`vkGetMemoryFdKHR` → `zwp_linux_buffer_params_v1.add(fd, …)` + `create_immed`
@@ -80,7 +80,7 @@ The patch (in our Wayland Turnip build): a new `create_mem` for the Wayland chai
compositor advertises a private global `banner_layer_buffer_v1`:
1. `AHardwareBuffer_allocate(w, h, R8G8B8A8, GPU_COLOR_OUTPUT | GPU_SAMPLED_IMAGE)`;
`vkGetAndroidHardwareBufferPropertiesANDROID` → `vkAllocateMemory` with
`VkImportAndroidHardwareBufferInfoANDROID` (Turnip: `tu_device.cc:3828`), bind — the image was
`VkImportAndroidHardwareBufferInfoANDROID` (Turnip: `tu_device.cc:3828`), bind - the image was
created with the modifier/pitch gralloc reports, i.e. UBWC on Adreno gralloc (§2).
2. `wsi_image.dma_buf_fd = dup(native_handle->data[0])`, `drm_modifier` / `row_pitches[0]` from
the same layout → the existing `zwp_linux_dmabuf_v1` path stays untouched: the compositor keeps
@@ -88,17 +88,17 @@ compositor advertises a private global `banner_layer_buffer_v1`:
3. `banner_layer_buffer_v1.attach(wl_buffer, socket_fd)`: the WSI creates a `socketpair`, sends one
end in the request, and calls `AHardwareBuffer_sendHandleToUnixSocket(ahb, other_end)`; the
compositor's request handler does `AHardwareBuffer_recvHandleFromUnixSocket` and stores the AHB
on `struct dmabuf_buffer`. Per swapchain image, once — not per frame.
on `struct dmabuf_buffer`. Per swapchain image, once - not per frame.
Extensions used by the game: `VK_ANDROID_external_memory_android_hardware_buffer` only (the
dma-buf/modifier extensions are used internally by the same driver). Note winevulkan does not
expose the AHB extension to PE code — irrelevant here, the WSI is unix-side inside the ICD.
expose the AHB extension to PE code - irrelevant here, the WSI is unix-side inside the ICD.
Effort: 2–3 days WSI + protocol + wcp rebuild (wine-compat-engineer for the packaging).
### (b) Import the game's existing dma-buf as an `AHardwareBuffer`
**No.** There is no public API: `AHardwareBuffer_createFromHandle` exists only in
`vndk/hardware_buffer.h` (exported by `libnativewindow.so`, so `dlsym` finds it), but it takes a
gralloc `native_handle_t` that the vendor mapper (`IMapper::importBuffer`) validates — on QTI a
gralloc `native_handle_t` that the vendor mapper (`IMapper::importBuffer`) validates - on QTI a
`private_handle_t` with the `'gmsm'` magic, a metadata dma-buf, and vendor-specific ints. The game's
buffers are bare DMA-heap fds. Fabricating a vendor handle around a foreign fd is unversioned
private ABI (differs across gralloc4 releases/OEMs) and is exactly the kind of thing that
@@ -115,8 +115,8 @@ before the swapchain image is created, plus reallocation on `vkCreateSwapchainKH
plus fence plumbing in both directions. `zwp_linux_dmabuf_v1` v4 feedback cannot express this (it
only steers format/modifier/device; the client still allocates), and on KGSL v4 is a trap anyway:
the driver has no DRM `dev_t`, so `same_gpu` stays false (`wsi_common_wayland.c:1660-1686`) and
Mesa takes the prime-blit path (one extra copy per frame). The one advantage over (a) — the
compositor decides linear vs UBWC — is moot because gralloc's decision is the right one for the DPU.
Mesa takes the prime-blit path (one extra copy per frame). The one advantage over (a) - the
compositor decides linear vs UBWC - is moot because gralloc's decision is the right one for the DPU.
Effort: 3–4 days; strictly more moving parts than (a). Not recommended.
**Recommendation: (a).** It reuses two proven mechanisms (Turnip's AHB import, the X11 path's
@@ -135,7 +135,7 @@ to our own Mesa build plus one small protocol.
- The compositor advertises `LINEAR` and `INVALID` only (`compositor.c: bind_dmabuf`,
`uint64_t mods[] = {MOD_LINEAR, MOD_INVALID}`); `INVALID` is dropped by the WSI
(`wsi_common_wayland.c:449-451`), so every game swapchain is linear today. DXVK/VKD3D render to
their own tiled/UBWC targets and copy into the linear swapchain image at present — a full-frame
their own tiled/UBWC targets and copy into the linear swapchain image at present - a full-frame
linear write per frame on the game side, on top of the compositor's blit. This is a real part of
the 20 %.
- Advertising `QCOM_COMPRESSED` as well: one line in `bind_dmabuf`. The WSI intersects the
@@ -149,23 +149,23 @@ to our own Mesa build plus one small protocol.
`GPU_COLOR_OUTPUT` RGBA8 unless a CPU usage bit is set (the prototype exploits exactly that:
`sc_layer.c: alloc_slot` retries with `CPU_READ_RARELY` when a UBWC import fails). The DPU
scans out UBWC RGBA natively; a prior device experiment (GL native rendering, 2026-06-29)
found the SDE pipes accepted both UBWC and linear layers — rotation+scale was the blocker, not
found the SDE pipes accepted both UBWC and linear layers - rotation+scale was the blocker, not
UBWC.
## 3. Per-layer composition (design; the prototype implements the single-layer subset)
- **wl_surface → SurfaceControl.** One `ASurfaceControl_createFromWindow(surfaceView_window,
name)` child per mapped toplevel (and per subsurface tree flattened per toplevel); the desktop
surface is the base layer at z 0 (or, with `g_hide_shell`, a black base — the SurfaceView's own
surface is the base layer at z 0 (or, with `g_hide_shell`, a black base - the SurfaceView's own
buffer); toplevels get `setZOrder` from the `g_toplevels` order (`apply_zorder`), with
`INT_MAX` reserved for the app's cursor/HUD if they ever move native. Position/scale:
`ASurfaceTransaction_setGeometry(src = buffer rect, dst = output rect, transform 0)`, with the
output rect produced by the same `update_map()` / `draw_to_blit()` arithmetic the blit path uses
(`vk_present.c: vkp_map_draw`) — letterbox/FILL crop/TOP-BOTTOM half all come out identical, so
(`vk_present.c: vkp_map_draw`) - letterbox/FILL crop/TOP-BOTTOM half all come out identical, so
**input stays consistent by construction**: the app maps touch through `ViewTransformation`
with the same inputs (see `WAYLAND_RUNTIME.md` "Fullscreen mode"), and the compositor's own
`vkp_output_to_scene` keeps working because the map is still updated every frame.
`setBufferTransparency(OPAQUE)` for XR24/XB24; `setBufferTransform` stays 0 — the DPU refuses
`setBufferTransparency(OPAQUE)` for XR24/XB24; `setBufferTransform` stays 0 - the DPU refuses
rotation+scale on one pipe (prior experiment), so a rotated panel must be handled by the
activity's orientation, not the layer.
- **HUD.** Already a separate layer: `PerfHudView`/`FrameRating`/cursor are Android views in
@@ -177,7 +177,7 @@ to our own Mesa build plus one small protocol.
fires `wl_callback.done` for those surfaces (as today, `fire_all_frames`). `wp_presentation`
feedback moves from "after our present" to the transaction's `ASurfaceTransaction_setOnComplete`
→ `ASurfaceTransactionStats_getLatchTime` / `getPresentFenceFd` (API 29) give the real on-glass
time — better than today's `now_ns()`; `setFrameTimeline` (API 33) can be added later for
time - better than today's `now_ns()`; `setFrameTimeline` (API 33) can be added later for
`VK_GOOGLE_display_timing` work. Without a window, `pace_without_output` stays as is.
- **`wl_buffer.release` timing.** Today a replaced buffer is released on the limiter's cadence,
which is safe because the blit was waited for. With layers the buffer is on the display until
@@ -185,14 +185,14 @@ to our own Mesa build plus one small protocol.
transaction that **replaced** it delivers `ASurfaceTransactionStats_getPreviousReleaseFenceFd`
(this is what `ASurfaceRendererContext::transactionCompleteCallback` does), wait that fence on
the compositor thread (or, better, hand it to the game: with option (a) the WSI can import it as
the `WSI_ES_RELEASE` point — Turnip/KGSL implements `vk_sync.import_sync_file`,
the `WSI_ES_RELEASE` point - Turnip/KGSL implements `vk_sync.import_sync_file`,
`tu_knl_kgsl.cc:1261-1303`), then `wl_buffer_send_release`. The FPS limiter keeps working: it only
delays the release further. Android 16's `setBufferWithRelease` is not available on 14.
- **Acquire fence.** Two sources: (1) if the kernel supports `DMA_BUF_IOCTL_EXPORT_SYNC_FILE`
(6.x GKI), the WSI already attaches its present semaphore to the dma-buf as a sync_file
(`wsi_drm_init_swapchain_implicit_sync`, `wsi_common_drm.c:368-395`, gated on the driver
exporting `SYNC_FD` semaphores — KGSL does, `:1278-1303`), and the compositor can
`EXPORT_SYNC_FILE(READ)` it and pass the fd to `setBuffer` — the prototype probes this on the
exporting `SYNC_FD` semaphores - KGSL does, `:1278-1303`), and the compositor can
`EXPORT_SYNC_FILE(READ)` it and pass the fd to `setBuffer` - the prototype probes this on the
first frame and logs the answer; (2) otherwise the option-(a) protocol carries a sync_fd per
present (`vkGetSemaphoreFdKHR`), which is what the X11 wrapper does. Never `-1` for a real
zero-copy frame.
@@ -210,11 +210,11 @@ to our own Mesa build plus one small protocol.
src == dst was DEVICE on every layer, GPU_TARGET empty. So: no SurfaceControl rotation ever; on
a landscape-native panel (handheld) the identity-transform game layer with a DPU scale should
promote; on a portrait phone in landscape it will not, and the base swapchain path is the better
one there — decide per device by measurement, not by assumption. Measure with
one there - decide per device by measurement, not by assumption. Measure with
`dumpsys SurfaceFlinger` (layer `composition: DEVICE/DEVICE` vs `DEVICE/CLIENT`, and the SDE pipe
table `GPU_TARGET` line) with the app foreground and the drawer closed.
- **Layer count.** The DPU has a handful of pipes (4–8 usable RGB pipes on SDM/SM8xxx); 2–3 game
layers + base + HUD + cursor is fine, a desktop with 10 windows is not — SurfaceFlinger then
layers + base + HUD + cursor is fine, a desktop with 10 windows is not - SurfaceFlinger then
composites the overflow on the GPU (still correct, just no gain). Policy: layers only for
fullscreen/topmost windows, everything else stays in the base swapchain (the prototype's rule).
- **Buffer ownership across processes.** The game's `AHardwareBuffer` is alive in the guest; the
@@ -226,7 +226,7 @@ to our own Mesa build plus one small protocol.
real thing (the prototype waits on the CPU instead, which is safe).
- **Background / rotation / device lost.** Covered by the window-request serialisation; a device
loss in the compositor's Turnip does not affect layers already on screen (SurfaceFlinger owns
them) — the old path's `device_lost` message stays.
them) - the old path's `device_lost` message stays.
- **Non-Adreno / old SoCs.** Everything here is NDK API 29 + gralloc-allocated buffers; the only
vendor-specific piece is the `'gmsm'` handle sniff, which degrades to "linear with a CPU bit".
Same risk class as the X11 ASR renderer; keep it opt-in until proven on a second SoC.
@@ -248,7 +248,7 @@ D3D12 tabs) as the workload, session log in `Download/Wayland-logs/`.
variables, launch the AIO fullscreen. Expected log lines (tag `layer`):
`SurfaceControl "banner_wayland_game" created as a child of the screen surface`,
`pool buffer 1920x1080 UBWC (QCOM_COMPRESSED), stride 1920 px (gralloc handle 2 fds / N ints)`
(or `linear` after `import of a UBWC … failed` — also a result: it tells whether the compositor
(or `linear` after `import of a UBWC … failed` - also a result: it tells whether the compositor
Turnip accepts gralloc's UBWC pitch), `geometry: buffer 0,0-1920,1080 -> screen …`,
`presenting 1920x1080 game frames on their own SurfaceControl layer (UBWC pool, 3 buffers)`,
and the probe line `kernel exports sync_file fences from the game's dma-buf …` or
@@ -293,7 +293,7 @@ hides the layer and draws the old way; the layer is retired when the SurfaceView
Everything else (frame callbacks, presentation feedback, FPS limiter, HUD counting, input) is
unchanged. Off by default: with the variable unset no new code runs.
Not zero-copy yet — it is the receive side. The copy disappears when step 5 lands and
Not zero-copy yet - it is the receive side. The copy disappears when step 5 lands and
`sc_layer_present` is handed the game's own `AHardwareBuffer` instead of a pool slot.
## 7. Step 5 implemented (feat/wayland-zero-copy-wsi + banners-turnip-wayland `banner_ahb_wsi.py`)
@@ -302,8 +302,8 @@ Option (a′) as recommended, with one deviation forced by the build: the Waylan
`platforms=wayland` build with Android detection off, so `VK_ANDROID_external_memory_android_hardware_buffer`
/ `vk_android.c` do not exist in it. The WSI therefore allocates the `AHardwareBuffer` itself
(`libnativewindow.so` dlopen'd), sniffs the gralloc handle for UBWC exactly like `u_gralloc_fallback.c`,
and imports `native_handle->data[0]` as a dma-buf with an explicit modifier + pitch — the same path
this compositor's pool uses (`vkp_image_import_dmabuf`) — after a test `vkCreateImage` proves the
and imports `native_handle->data[0]` as a dma-buf with an explicit modifier + pitch - the same path
this compositor's pool uses (`vkp_image_import_dmabuf`) - after a test `vkCreateImage` proves the
driver accepts that layout (linear retry otherwise). Fences: implicit via the dma-buf in both
directions (§3's option 1, proven by the probe; the compositor imports SurfaceFlinger's release
fence back into the dma-buf before `wl_buffer.release`). Details in `WAYLAND_RUNTIME.md`.
@@ -1,7 +1,7 @@
#ifndef BANNER_COLOR_H
#define BANNER_COLOR_H
/*
* HDR10 output on the Wayland backend (opt-in) — the compositor half of HDR_RECON.md Phase A (round 1)
* HDR10 output on the Wayland backend (opt-in) - the compositor half of HDR_RECON.md Phase A (round 1)
* plus HDR-aware composition (round 2, hdr_compose.h), implemented in wl_color_mgmt.c. The game half
* already ships: Mesa's Wayland WSI in our Turnip is a wp_color_manager_v1 client and exposes
* VK_COLOR_SPACE_HDR10_ST2084_EXT as soon as a compositor advertises BT.2020 + ST 2084; DXVK takes it
@@ -11,13 +11,13 @@
* - the container's / game's "HDR output" setting is on, or BANNER_WAYLAND_HDR=1 in their
* environment (which overrides the setting either way);
* - the display the game is on lists HDR10 among its supported HDR types (read by the app from
* android.view.Display — a property of the connector, not of the device);
* android.view.Display - a property of the connector, not of the device);
* - display layers with dataspace control (ASurfaceTransaction_setBufferDataSpace, Android 10+)
* and the zero-copy global (banner_ahb_v1): the HDR frame (or the composed HDR picture) is shown
* on the game's own display layer, tagged BT2020_PQ.
* In game, the drawer's HDR output switch (banner_color_set_output) flips between that and the same
* frames tone-mapped to SDR, live; the gate itself never changes during a session.
* A closed gate advertises nothing — no colour-management global, no 10-bit dma-buf formats — so the
* A closed gate advertises nothing - no colour-management global, no 10-bit dma-buf formats - so the
* session is byte-for-byte what it was before this file existed, and the session log says why.
* BANNER_WAYLAND_HDR=force skips the display check only (testing the negotiation on an SDR panel;
* SurfaceFlinger then tone-maps the layer, and says so in its composition type).
@@ -83,7 +83,7 @@ int banner_color_hdr_state(void);
/* Nits SDR content is placed at inside an HDR picture (default 203, BT.2408); any thread. */
void banner_color_set_sdr_white(float nits);
float banner_color_sdr_white(void);
/* The HDR session was asked for (BANNER_WAYLAND_HDR / the setting resolved on or force) — known before
/* The HDR session was asked for (BANNER_WAYLAND_HDR / the setting resolved on or force) - known before
* the compositor starts, so the Vulkan instance can enable VK_EXT_swapchain_colorspace for it. */
int banner_color_requested(void);
/* The drawer's live "HDR output" switch, per session, starting ON. On = HDR frames go to the display as
@@ -3,7 +3,7 @@
*
* The app's threads (UI thread, clipboard listener) hand text to the compositor through
* banner_host_* ; the messages are queued under a mutex and a pipe byte wakes the wl event
* loop, which drains them on the compositor thread — the only thread that may touch
* loop, which drains them on the compositor thread - the only thread that may touch
* wl_resources.
*/
#define _GNU_SOURCE 1
@@ -1,5 +1,5 @@
/*
* bannerlator-wayland — the embedded compositor of the Wayland display path.
* bannerlator-wayland - the embedded compositor of the Wayland display path.
*
* Clients are the Wine processes of a container (winewayland.drv) and, through them,
* Mesa's Vulkan WSI. Each process is its own client, so a Windows virtual desktop is
@@ -65,7 +65,7 @@
static FILE *g_log;
/* Lines logged before the session file exists are kept here and written into it, in order, the
* moment it opens — the compositor runs on its own thread, so anything the app reports as that
* moment it opens - the compositor runs on its own thread, so anything the app reports as that
* thread starts (the display's HDR capability, for one) would otherwise only reach logcat. The
* lock also serialises the file writes, which now come from the app's threads too. */
#define PRELOG_MAX 32
@@ -432,7 +432,7 @@ static int on_release_timer(int fd, uint32_t mask, void *data) {
* Each release takes the next slot of a per-surface cadence (one slot per interval), so a game
* gets one buffer back per interval however fast it commits. The schedule is kept honest at both
* ends: a slot in the past is brought to now (the game was slower than the cap, no catch-up burst
* is owed), and it never runs further ahead than the releases actually queued — with p releases
* is owed), and it never runs further ahead than the releases actually queued - with p releases
* still pending the new one lands at most (p + 1) intervals out, nothing pending means at most
* one interval. Without that bound the schedule kept slots that were consumed but never
* delivered (a swapchain rebuild destroys buffers with queued releases) or that a coarser earlier
@@ -1,4 +1,4 @@
/* Screen-effect chain — see effects_chain.h. Compositor thread unless noted. */
/* Screen-effect chain - see effects_chain.h. Compositor thread unless noted. */
#define _POSIX_C_SOURCE 200809L
#include "effects_chain.h"
#include "vk_loader.h"
@@ -309,7 +309,7 @@ static VkShaderModule shader(const uint32_t *code, size_t size) {
}
/* One full-quad post pipeline: upscale.vert + the effect's fragment shader, opaque, dynamic
* viewport/scissor — the X11 renderer's createPostPipeline. */
* viewport/scissor - the X11 renderer's createPostPipeline. */
static VkPipeline post_pipeline(VkShaderModule vert, const uint32_t *frag_code, size_t frag_size, const char *name) {
VkShaderModule frag = shader(frag_code, frag_size);
if (!frag) { banner_log("error", "effects: %s: vkCreateShaderModule failed", name); return VK_NULL_HANDLE; }
+15 -15
View File
@@ -1,4 +1,4 @@
/* Layer mode: the scene on a small set of ASurfaceControl layers — see sc_layer.h and
/* Layer mode: the scene on a small set of ASurfaceControl layers - see sc_layer.h and
* ZERO_COPY_SPIKE.md. The ASurfaceControl/ASurfaceTransaction API is dlsym'd from libandroid.so
* (API 29+), the same way the X11 renderers' scanout code does it, so the library still loads on
* older devices and the prototype stays off every other path. */
@@ -572,7 +572,7 @@ static int layer_geometry(int w, int h, int scene_w, int scene_h, int r[8]) {
/* The GAME layer's last placement, kept across SurfaceControl retires and swaps (l->geo_valid is
* per-SurfaceControl and is cleared by both). This is the src -> dst the display actually works
* with, and it is what decides whether a second layer is affordable — see overlay_affordable(). */
* with, and it is what decides whether a second layer is affordable - see overlay_affordable(). */
static ARect g_game_src, g_game_dst;
static int g_game_geo_known;
@@ -610,8 +610,8 @@ static void apply_frame_rate(ASurfaceTransaction *tx, struct layer *l) {
}
/* ---- colour (HDR, banner_color.h) -------------------------------------------------------------
* The layer is told what its buffer's pixels MEAN — the dataspace (BT2020_PQ for an HDR10 frame) and
* the game's mastering / content-light metadata — in the same transaction as the buffer, so the
* The layer is told what its buffer's pixels MEAN - the dataspace (BT2020_PQ for an HDR10 frame) and
* the game's mastering / content-light metadata - in the same transaction as the buffer, so the
* display never shows an HDR frame decoded as sRGB or the other way round. A layer that has never been
* tagged is never touched: sessions without an HDR description make no colour call at all. */
/* How much of the screen the layer's picture covers ("covers 80% of the screen (1920x1080 of 2400x1080)"):
@@ -722,19 +722,19 @@ static void log_layer_count(void) {
* marked for a swap and the swap rides the NEXT frame: a fresh SurfaceControl is created here, the
* frame is put on it, and the old one is hidden and unparented IN THE SAME TRANSACTION. Because
* SurfaceFlinger applies a transaction atomically there is never a composited frame with neither
* layer on it — no black frame, and no dropped frame beyond the one layer creation. The outgoing
* layer on it - no black frame, and no dropped frame beyond the one layer creation. The outgoing
* buffer is released through the OLD SurfaceControl's callback, which also releases it.
*
* ⚠️ MEASURED 2026-09-14, and the news is bad: on the Pocket FIT this does NOT bring hardware
* MEASURED 2026-09-14, and the news is bad: on the Pocket FIT this does NOT bring hardware
* composition back. The swap fires 6 ms after the overlay goes, SurfaceFlinger really does hand out
* a new layer (its id changes), the game never drops a frame — and the composer still reports
* a new layer (its id changes), the game never drops a frame - and the composer still reports
* `DEVICE/CLIENT` 24 s later. Neither does dropping the layer path entirely and re-creating the
* SurfaceControl after a gap. The ONE thing that clears it is HOME + resume, which re-creates the
* app's whole window and SurfaceView (`VRI[XServerDisplayActivity]#0` becomes `#4`) — so the sticky
* app's whole window and SurfaceView (`VRI[XServerDisplayActivity]#0` becomes `#4`) - so the sticky
* client-composition state belongs to the PARENT surface (or the display), not to this child layer.
* The phase-4 note that "only re-creating the GAME layer's SurfaceControl clears it" was inferred
* from HOME + resume and is wrong; see sc_layer.h. The swap is kept because it is free and correct
* and the mechanism may differ on hardware that does not rotate every layer — but do not claim it
* and the mechanism may differ on hardware that does not rotate every layer - but do not claim it
* restores DEVICE composition, and do not log as if it did.
*
* Returns the old SurfaceControl (the caller must add retire_ops for it to the same transaction and
@@ -753,7 +753,7 @@ static ASurfaceControl *swap_sc_begin(struct layer *l) {
ASurfaceControl *old = l->sc;
l->sc = fresh;
/* These describe the SurfaceControl, not the layer: the new one carries none of them yet.
* cur_slot / cur_token are deliberately NOT cleared — they name the buffer still on the OLD
* cur_slot / cur_token are deliberately NOT cleared - they name the buffer still on the OLD
* SurfaceControl, which is what the caller passes to add_complete_on as the one being replaced. */
l->shown = 0;
l->geo_valid = 0;
@@ -848,7 +848,7 @@ int sc_layer_present_ahb(AHardwareBuffer *ahb, int w, int h, int acquire_fd, voi
apply_colour(tx, l, color);
if (!l->shown) api.setVisibility(tx, l->sc, ASC_VISIBILITY_SHOW);
if (old) retire_ops(tx, old);
/* Same buffer, new SurfaceControl: it is NOT free, so no release is reported for it — the swap
/* Same buffer, new SurfaceControl: it is NOT free, so no release is reported for it - the swap
* moved it rather than taking it off screen. */
if (add_complete_on(tx, l, old ? old : l->sc, l->cur_slot,
l->cur_token == token ? NULL : l->cur_token, old ? 1 : 0) != 0) {
@@ -977,19 +977,19 @@ int sc_layer_present_hdr_scene(const struct vkp_draw *draws, int n, const struct
/* ---- is a SECOND display layer affordable on this display? -----------------------------------
* MEASURED on the Pocket FIT (2026-09-14, three times): while a second layer is up, this hardware
* composer hands the WHOLE frame back to the GPU (`DEVICE/CLIENT`), and nothing short of re-creating
* the app's window brings it back — so on this display the overlay layer costs more than it saves,
* the app's window brings it back - so on this display the overlay layer costs more than it saves,
* every time, for the rest of the session. Where it costs nothing it is still the better path (the
* game keeps copy-free frames with a window on top), so this is a GATE, not a removal.
*
* The gate is read from what the layer path actually knows, never from a device or panel list:
* - rotation: vkp_surface_rotation_degrees(), i.e. VkSurfaceCapabilitiesKHR::currentTransform —
* - rotation: vkp_surface_rotation_degrees(), i.e. VkSurfaceCapabilitiesKHR::currentTransform -
* what the presentation engine says it does to every layer we hand it;
* - scale: the GAME layer's own src -> dst rectangles, the ones passed to setGeometry.
* Rotated AND scaled is the combination that was measured to cost composition (the DPU's rotator
* has to take a scaled source); either alone, or neither, is left as it was.
*
* Why not just measure the composition type after raising the layer and back out if it comes back
* CLIENT — which would beat predicting? Because no app can read it. The composition type lives in
* CLIENT - which would beat predicting? Because no app can read it. The composition type lives in
* the Composer HAL; ASurfaceTransactionStats exposes latch time and fences and nothing else, and
* the only place the value is published is `dumpsys android.hardware.graphics.composer3.IComposer`,
* which needs android.permission.DUMP and string-parsing. It would also arrive at least a frame
@@ -1006,7 +1006,7 @@ static int overlay_affordable(int *deg, int sw[2], int dw[2]) {
}
/* -1 = not decided yet, 0 = raising the overlay, 1 = declining it. Logged on every change, so a
* tester's log says why they are seeing the copy path instead of two layers — and says it again if
* tester's log says why they are seeing the copy path instead of two layers - and says it again if
* the placement changes the answer (e.g. a fullscreen mode that stops scaling the game). */
static int g_overlay_declined = -1;
+14 -14
View File
@@ -2,8 +2,8 @@
#define SC_LAYER_H
/*
* Layer mode (BANNER_WAYLAND_ZERO_COPY=1): the scene is handed to SurfaceFlinger as a small,
* deliberately ordered SET of Android display layers — ASurfaceControl children of the
* compositor's SurfaceView — instead of being blitted into the compositor's own swapchain.
* deliberately ordered SET of Android display layers - ASurfaceControl children of the
* compositor's SurfaceView - instead of being blitted into the compositor's own swapchain.
*
* app window ......... Compose UI, the in-game drawer, the HUD, the on-screen controls and
* the pointer arrow: ordinary Android views, ALWAYS above everything
@@ -21,21 +21,21 @@
*
* MEASURED on the Pocket FIT (Adreno 750, portrait panel + landscape session, so every layer is
* ROT_90 + scaled), `dumpsys android.hardware.graphics.composer3.IComposer/default`: one layer is
* `composition: DEVICE/DEVICE`, effects on the layer keep it DEVICE/DEVICE — but a SECOND layer
* `composition: DEVICE/DEVICE`, effects on the layer keep it DEVICE/DEVICE - but a SECOND layer
* flips the whole frame to `DEVICE/CLIENT`. It does not come back when the overlay goes away.
* The overlay layer is retired rather than hidden for that reason, but the fallback outlives it.
* The likely mechanism is the DPU's rotator budget (one rotated+scaled layer), not the layer count
* as such, so a device or orientation needing no rotation may well take both on the DPU. Even in
* client composition the overlay layer is not a loss — SurfaceFlinger does the one blit the
* compositor would have done — but the hardware-composition win is only real for one layer.
* client composition the overlay layer is not a loss - SurfaceFlinger does the one blit the
* compositor would have done - but the hardware-composition win is only real for one layer.
*
* COMPOSITION RECOVERY (sc_layer.c, swap_sc_begin): retiring the overlay arms the game layer, and
* the NEXT frame is presented on a brand-new SurfaceControl while the old one is hidden and
* unparented in the SAME transaction. SurfaceFlinger applies a transaction atomically, so no
* composited frame is ever missing the game — no black frame, no dropped frame beyond the layer
* composited frame is ever missing the game - no black frame, no dropped frame beyond the layer
* creation itself. One `layer` line is written when it happens.
*
* ⚠️ It does NOT restore hardware composition on this panel, and that was measured, not assumed
* It does NOT restore hardware composition on this panel, and that was measured, not assumed
* (2026-09-14, Wizardry on the game layer + Wine's Task Manager on the overlay, reproduced twice):
* - two layers -> DEVICE/CLIENT
* - overlay retired + fresh game SurfaceControl -> still DEVICE/CLIENT, 24 s later too
@@ -43,12 +43,12 @@
* - drawer opened and closed, no second window -> DEVICE/DEVICE (control: the drawer is not the cause)
* - HOME + resume -> DEVICE/DEVICE
* HOME + resume re-creates the app's whole window and SurfaceView (`VRI[XServerDisplayActivity]#0`
* becomes `#4`), not just this child layer — so the sticky state belongs to the parent surface or
* becomes `#4`), not just this child layer - so the sticky state belongs to the parent surface or
* the display. Re-creating the parent would cost a real black frame and a swapchain rebuild, which
* is worse than the few percent of GPU that client composition costs. The cure that actually keeps
* the win is PREVENTION, and it IS implemented: sc_layer_overlay_affordable() declines the second
* layer when the game layer is both rotated and scaled, and the window above the game goes down the
* copy path instead (what the pre-phase-4 code did) — one blit SurfaceFlinger would have done
* copy path instead (what the pre-phase-4 code did) - one blit SurfaceFlinger would have done
* anyway, and the session keeps DEVICE composition throughout. Where a second layer costs nothing,
* nothing changes.
*
@@ -56,7 +56,7 @@
* - the game's own gralloc buffer (ahb_swapchain.c, true zero-copy: no copy anywhere);
* - one blit of the game's frame into a compositor-allocated AHardwareBuffer (sc_layer_present);
* - with screen effects on, the compositor pass's result blitted into such a buffer
* (sc_layer_present_pass) — the game STAYS on its layer while a Look is applied, and the
* (sc_layer_present_pass) - the game STAYS on its layer while a Look is applied, and the
* scene -> output mapping is done by the display (setGeometry) instead of a second GPU blit.
* The compositor never alpha-blends (it composes with blits, which overwrite), so every layer is
* marked OPAQUE and the overlay layer is cropped to the window it carries: the picture is the
@@ -141,9 +141,9 @@ void sc_layer_set_frame_rate(float fps);
* layer, not after: on a display where the answer is no, the whole scene must go down the copy path
* from the start, or the game layer would be shown and hidden again on every frame.
*
* The answer is computed from what the layer path knows — the rotation the presentation engine
* The answer is computed from what the layer path knows - the rotation the presentation engine
* applies to everything we hand it (VkSurfaceCapabilitiesKHR::currentTransform) and the game
* layer's own src -> dst rectangles — and never from a device or panel allowlist. ROTATED AND
* layer's own src -> dst rectangles - and never from a device or panel allowlist. ROTATED AND
* SCALED is the combination measured to cost hardware composition (below); either alone is fine.
* The reason is written to the session log once, and again if the answer changes. */
int sc_layer_overlay_affordable(void);
@@ -156,7 +156,7 @@ int sc_layer_present_overlay(struct vkp_image *src, const int geo[8]);
/* The scene is not a single fullscreen window this frame: hide every layer that is up. */
void sc_layer_hide(void);
/* Only the overlay layer: nothing is above the game any more. The game keeps its layer, but its
* SurfaceControl is swapped for a fresh one on the next frame (composition recovery, above — which
* SurfaceControl is swapped for a fresh one on the next frame (composition recovery, above - which
* on this panel does not in fact win hardware composition back; see the measurement there). */
void sc_layer_hide_overlay(void);
@@ -164,7 +164,7 @@ void sc_layer_hide_overlay(void);
void sc_layer_window_gone(void);
/* Frames the compositor put on a layer through one of its own buffers (a blit or the effects
* pass) since the last call — the zero-copy frames ahb_swapchain.c counts are NOT included.
* pass) since the last call - the zero-copy frames ahb_swapchain.c counts are NOT included.
* For the 10 s summary. */
unsigned sc_layer_frames_take(void);
/* Frames dropped since the last call because every layer buffer was still held by the display (the
+1 -1
View File
@@ -2,7 +2,7 @@
#define VK_LOADER_H
/*
* Loads Turnip via adrenotools (the same path the app uses for the guest renderer)
* and resolves every Vulkan entry point through its vkGetInstanceProcAddr — NOT the
* and resolves every Vulkan entry point through its vkGetInstanceProcAddr - NOT the
* process-default system Adreno driver, which lacks VK_EXT_image_drm_format_modifier /
* dmabuf import. All compositor Vulkan calls go through g_vk.* .
*/
@@ -1,4 +1,4 @@
/* Android-surface render backend — see vk_present.h. Uses Turnip via vk_loader
/* Android-surface render backend - see vk_present.h. Uses Turnip via vk_loader
* (g_vk.*), not the process-default system Adreno driver. */
#define _POSIX_C_SOURCE 200809L
#include "vk_present.h"
@@ -118,7 +118,7 @@ static VkResult timed_wait(VkFence fence, uint64_t timeout) {
}
/* The scene image (effects path only): every draw composited 1:1 at scene size, the input of the
* screen-effect chain (effects_chain.c) — and of frame generation once that lands. Recreated on a
* screen-effect chain (effects_chain.c) - and of frame generation once that lands. Recreated on a
* scene size change; frames are fenced, so never while the GPU reads it. */
static struct { VkImage img; VkDeviceMemory mem; int w, h; } g_scene;
@@ -175,7 +175,7 @@ static struct {
static int64_t g_swap_retry_at_ns;
static int g_swap_fail_logged;
/* Implemented in waylandcomp_jni.c — notifies Java (dismiss launch overlay). */
/* Implemented in waylandcomp_jni.c - notifies Java (dismiss launch overlay). */
extern void banner_on_first_frame(void);
static char g_gpu_name[VK_MAX_PHYSICAL_DEVICE_NAME_SIZE];
@@ -311,7 +311,7 @@ static const char *align_name(int a) {
}
}
/* Mirror of ViewTransformation.update(outer = output, inner = scene, mode, alignment) — keep the
/* Mirror of ViewTransformation.update(outer = output, inner = scene, mode, alignment) - keep the
* arithmetic identical: the app maps touch input through that class with the same inputs, so any
* difference here puts the pointer beside what it is pointing at. OFF and FIT are both an
* aspect-preserving letterbox (OFF only differs in the app's fullscreen gates); TOP/BOTTOM confine
@@ -379,7 +379,7 @@ static int has_ext(VkExtensionProperties *e, uint32_t n, const char *name) {
static int dev_init(void) {
if (g_dev_state != 0) return g_dev_state == 1 ? 0 : -1;
/* Load Turnip (adrenotools) and its entry points — NOT the system driver. */
/* Load Turnip (adrenotools) and its entry points - NOT the system driver. */
if (vk_loader_open(g_driver_path, g_library_name, g_native_lib_dir) != 0) {
LOGE("present: vk_loader_open failed"); g_dev_state = -1; return -1;
}
@@ -656,7 +656,7 @@ static int swap_init_locked(void) {
/* Remembered for the layer path: currentTransform is the rotation the presentation engine (and
* therefore SurfaceFlinger and the DPU) applies to everything we put on this display. Anything
* but IDENTITY means every display layer we hand over is a ROTATED layer. sc_layer.c needs that
* to decide whether a second layer is affordable — see sc_layer_present_overlay(). */
* to decide whether a second layer is affordable - see sc_layer_present_overlay(). */
g_surface_transform = caps.currentTransform;
g_surface_transform_known = 1;
g_caps_extent = caps.currentExtent; /* check_surface_changed() compares against this */
@@ -724,7 +724,7 @@ static int swap_init_locked(void) {
/* Use IDENTITY preTransform when the surface supports it. Setting preTransform =
* currentTransform tells the presentation engine our content is ALREADY pre-rotated by
* that amount — but our blit doesn't rotate, so on a device whose surface reports a 90°
* that amount - but our blit doesn't rotate, so on a device whose surface reports a 90°
* currentTransform the display then rotates our upright frame 90° (game shows sideways).
* IDENTITY = "don't rotate what I present", which is what we want. */
VkSurfaceTransformFlagBitsKHR pretrans =
@@ -874,7 +874,7 @@ const char *vkp_modifier_name(uint64_t modifier) {
}
/* Can the driver create the image vkp_image_import_dmabuf() creates for this format+modifier
* (2D, DRM_FORMAT_MODIFIER tiling, TRANSFER_SRC, dma-buf memory) — and import it? */
* (2D, DRM_FORMAT_MODIFIER tiling, TRANSFER_SRC, dma-buf memory) - and import it? */
static int modifier_importable(VkFormat fmt, uint64_t modifier) {
if (!g_vk.GetPhysicalDeviceImageFormatProperties2) return 1; /* can't ask; the create will tell */
VkPhysicalDeviceExternalImageFormatInfo ext = {
@@ -7,12 +7,12 @@
* Owns a Turnip VkDevice + a swapchain on the SurfaceView's ANativeWindow. Each
* client buffer becomes an image (a dmabuf from winewayland's Vulkan WSI is
* imported zero-copy; a wl_shm buffer is copied into a host-visible image), and
* every frame blits the whole scene — desktop, windows, subsurfaces — in order.
* every frame blits the whole scene - desktop, windows, subsurfaces - in order.
*/
// Set the Turnip driver to load (adrenotools). Call before the first frame.
// NULL args -> the backend falls back to the system libvulkan (dmabuf import will
// likely fail — Adreno lacks drm_format_modifier). driver_path ends with '/'.
// likely fail - Adreno lacks drm_format_modifier). driver_path ends with '/'.
void vk_present_set_driver(const char *driver_path, const char *library_name,
const char *native_lib_dir);
@@ -157,7 +157,7 @@ int vkp_map_rect(int img_w, int img_h, int scene_w, int scene_h, int out[8]);
/* The output window frames go to (NULL = none); compositor thread. */
/* Degrees the display rotates every layer we present by (0/90/180/270), -1 before the swapchain
* exists. From VkSurfaceCapabilitiesKHR::currentTransform, i.e. what the presentation engine says
* it does — never a device allowlist. The layer path uses it to decide whether a SECOND display
* it does - never a device allowlist. The layer path uses it to decide whether a SECOND display
* layer is affordable on this display (sc_layer_present_overlay). */
int vkp_surface_rotation_degrees(void);
@@ -147,7 +147,7 @@ void banner_on_pointer_lock(int locked, int x, int y) {
if ((*env)->ExceptionCheck(env)) (*env)->ExceptionClear(env);
}
/* A program copied text (UTF-8, not NUL-terminated for the app's sake — a byte[] so emoji and
/* A program copied text (UTF-8, not NUL-terminated for the app's sake - a byte[] so emoji and
* NULs survive JNI). Compositor thread. */
void banner_on_clipboard_text(const char *utf8, int len) {
JNIEnv *env;
@@ -227,7 +227,7 @@ Java_com_steamdeck_launcher_wayland_WaylandCompositor_nativeCompositorTid(JNIEnv
return (jint)g_comp_tid;
}
/* Headless start (no output window) — used for bring-up tests. */
/* Headless start (no output window) - used for bring-up tests. */
JNIEXPORT void JNICALL
Java_com_steamdeck_launcher_wayland_WaylandCompositor_nativeStart(JNIEnv *env, jclass clazz,
jstring xdgRuntimeDir) {
@@ -412,7 +412,7 @@ Java_com_steamdeck_launcher_wayland_WaylandCompositor_nativeSetDeband(JNIEnv *en
}
/* Colour grade (slider units: brightness/contrast -100..100, gamma 0.5..3, saturation 0..200 %) and the
* FXAA / Toon / CRT / NTSC toggles — VulkanRenderer.setScreenEffects. */
* FXAA / Toon / CRT / NTSC toggles - VulkanRenderer.setScreenEffects. */
JNIEXPORT void JNICALL
Java_com_steamdeck_launcher_wayland_WaylandCompositor_nativeSetScreenEffects(JNIEnv *env, jclass clazz, jfloat brightness,
jfloat contrast, jfloat gamma, jfloat saturation, jboolean fxaa, jboolean toon, jboolean crt, jboolean ntsc) {
@@ -573,7 +573,7 @@ Java_com_steamdeck_launcher_wayland_WaylandCompositor_nativeHdrToneMappedOnScree
return banner_color_tonemapped_on_screen() ? JNI_TRUE : JNI_FALSE;
}
/* The Look the controls currently match (null = Custom) — only named in the session log. */
/* The Look the controls currently match (null = Custom) - only named in the session log. */
JNIEXPORT void JNICALL
Java_com_steamdeck_launcher_wayland_WaylandCompositor_nativeSetLookName(JNIEnv *env, jclass clazz, jstring name) {
char *s = dup_jstr(env, name);
@@ -1,6 +1,6 @@
/*
* Clipboard: wl_data_device_manager (core, v3) and zwlr_data_control_manager_v1 (v1), selection
* only — drag and drop is refused. Both protocols share one selection:
* only - drag and drop is refused. Both protocols share one selection:
*
* owner CLIENT a program's wl_data_source / zwlr_data_control_source_v1 (its mime list)
* owner HOST text the app pushed from Android's clipboard (offered under the text mimes)
@@ -1,6 +1,6 @@
/*
* wp_color_manager_v1 (wayland-protocols staging color-management-v1, version 1) — the subset Mesa's
* Wayland WSI binds — plus the HDR gate, the per-surface image descriptions and the session log's
* wp_color_manager_v1 (wayland-protocols staging color-management-v1, version 1) - the subset Mesa's
* Wayland WSI binds - plus the HDR gate, the per-surface image descriptions and the session log's
* HDR evidence. See banner_color.h for the design and HDR_RECON.md for why it is shaped this way.
*
* Strictness policy. A protocol error disconnects the client, and the client here is a GAME, so
@@ -3,7 +3,7 @@
* bridge winewayland.drv uses for IME text (our soft keyboard).
*
* Focus model. winewayland enables its text input as soon as our `enter` names a surface and
* routes every IME update to that surface's window — inside that window's process (the update
* routes every IME update to that surface's window - inside that window's process (the update
* list is per process). Keyboard focus in this compositor sits on the desktop surface (the
* desktop owner's process), so text input can't follow it; it follows banner_ime_target():
* the program window last clicked, else the topmost program window. Clicking into notepad