feat(linux): HDR video on a native Wayland plane

Video on Linux went through a Flutter texture: 8-bit sRGB, which cannot carry
HDR at all, and which forced a whole-window Flutter recomposite for every video
frame. This moves it onto a wl_subsurface stacked below the Flutter surface, with
mpv rendering into an EGL window surface on it through the libmpv render API. The
subsurface is desynchronized, so video and UI now present independently.

With the plane in place HDR follows: the surface is described to the compositor
through wp_color_manager_v1 as the source's own curve and gamut - PQ or HLG,
BT.2020 - carrying whatever HDR10 static metadata the stream actually declares.
The description and the buffer it describes land on the same commit, staged and
validated before mpv is switched, so a PQ frame is never presented labelled sRGB.
A five-second watchdog bounds the one wait a compositor could otherwise leave
hanging. A session that cannot host the plane - X11, or a compositor without
wl_subcompositor - fails initialize with VIDEO_PLANE_UNSUPPORTED naming the
reason: the texture path is gone, and refusing by name beats degrading to
something the user cannot see. An SDR output, a missing capability or an 8-bit
config keep the plane and simply leave it undescribed.

The output's colour state is trusted only when it has been earned. Every landed
property step records itself as it lands; a reset or sequence that cannot
finish downgrades its result to unknown and marks the applied-output cache
untrusted until a clean apply earns it back. A plane whose output state cannot
be named is quarantined - hidden, its description withdrawn - and the
quarantine is recorded state: an unrelated visibility change cannot put a
mislabelled plane back on screen, and only a commit that resolves to a nameable
outcome lifts it. A rect collapsing to zero detaches the buffer exactly as
hiding does, a refused setVideoRect drops the Dart-side sent-rect cache so the
next layout pass retries for free, and a refused tone-mapping pick tells the
user instead of dying in a log.

NVIDIA's Wayland EGL (through at least 610.xx) offers no 10-bit unorm window
configs, so the plane takes half-float as the tier between 10-bit unorm and
8-bit, declares the whole surface opaque so the compositor never reads the
alpha those configs carry, and states GL_RGBA16F rather than a 10-bit lie.
Whether the output is in HDR is read from luminance headroom above its own
reference white rather than from the preferred transfer function, which current
KWin no longer answers PQ for; the margin is half a stop, because KWin reports
an undimmed maximum over a software-dimmed SDR white. Validated on an RTX 4090
(driver 610.57.04) under KWin 6.7.4 with locked-exposure photographs.

Who tone-maps is a user choice. The default is the compositor: photographed on a
400-nit HDR output against a PQ chart it keeps 400 -> 1000 nits monotonic and
separated where the player leg flattens them, because the player path drives
mpv's legacy vo_gpu, whose own standalone output scores the same. The gap is the
renderer, not the wiring.

The decision itself - what the source carries, what the output supports, what to
tell mpv and what to tell the compositor - lives in hdr_metadata.h, free of
Wayland and GTK so its luminance validation can be tested without a display
server. Sending an incoherent luminance set is a protocol error that disconnects
the client, so the rules are worth a unit test.

The deb, rpm and pacman packages now declare wayland-client, wayland-egl and EGL:
the plane links them directly and bundle-libs.sh deliberately never bundles them,
since they are coupled to the running compositor and GPU driver.

lib/dev/harness_main.dart is a second entrypoint for measuring this on hardware -
it drives one clip with scripted mpv properties and reports the colour state mpv
actually settled on. Nothing imports it, so it is tree-shaken out of the app.

Verified on a Steam Deck against an external 400-nit HDR display: the compositor
reports PQ / BT.2020, the connector carries HDR_OUTPUT_METADATA, and against mpv
vo=gpu-next on the same frame the shipped build sits 4.90 counts away overall -
closer to the reference HDR player than to its own SDR fallback.
This commit is contained in:
edde746
2026-08-10 08:48:13 +02:00
parent c27dc0a1a7
commit bcd6fe9906
76 changed files with 8025 additions and 1833 deletions
+366 -46
View File
@@ -1,18 +1,25 @@
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:material_symbols_icons/symbols.dart';
import 'package:plezy/i18n/strings.g.dart';
import 'package:plezy/mpv/models.dart';
import 'package:plezy/mpv/player/player.dart';
import 'package:plezy/mpv/player/player_native.dart';
import 'package:plezy/mpv/player/player_state.dart';
import 'package:plezy/mpv/player/player_streams.dart';
import 'package:plezy/screens/settings/subtitle_styling_screen.dart';
import 'package:plezy/services/sleep_timer_service.dart';
import 'package:plezy/services/base_shared_preferences_service.dart';
import 'package:plezy/services/settings_service.dart';
import 'package:plezy/services/sleep_timer_service.dart';
import 'package:plezy/widgets/overlay_sheet.dart';
import 'package:plezy/widgets/video_controls/models/track_controls_state.dart';
import 'package:plezy/widgets/video_controls/sheets/video_settings_sheet.dart';
import 'package:shared_preferences_platform_interface/in_memory_shared_preferences_async.dart';
import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';
import 'package:shared_preferences_platform_interface/types.dart';
import '../test_helpers/prefs.dart';
import '../test_helpers/theme.dart';
@@ -77,7 +84,7 @@ void main() {
appliedRates.add(rate);
},
);
await _pumpHostedSheet(tester, player);
await _pumpSheetViaOverlayRoute(tester, player);
await tester.tap(find.text('Playback Speed'));
await tester.pumpAndSettle();
@@ -116,10 +123,10 @@ void main() {
testWidgets('failed HDR write restores the toggle without persisting', (tester) async {
final propertyWrite = Completer<void>();
var writeCount = 0;
final writes = <(String, String)>[];
final player = _FakeSettingsPlayer(
onSetProperty: (_, _) {
writeCount++;
onSetProperty: (name, value) {
writes.add((name, value));
return propertyWrite.future;
},
);
@@ -143,14 +150,20 @@ void main() {
expect(tester.takeException(), isNull);
expect(tester.widget<Switch>(toggle).value, isTrue);
expect(SettingsService.instance.read(SettingsService.enableHDR), isTrue);
expect(writeCount, 1);
// The name carries as much weight as the count: the plane intercepts this
// exact property, and any other name falls through to mpv as a real write.
expect(writes, [('hdr-enabled', 'no')]);
});
testWidgets('accepted HDR write persists once', (tester) async {
var writeCount = 0;
// The switch springing back on its own reads as a lost tap. This message is
// what tells the user the surface itself cannot carry HDR and no retry will
// change that, so it has to survive any rework of the write path.
testWidgets('a plane that can never carry HDR says so', (tester) async {
final writes = <(String, String)>[];
final player = _FakeSettingsPlayer(
onSetProperty: (_, _) async {
writeCount++;
onSetProperty: (name, value) async {
writes.add((name, value));
throw PlatformException(code: 'HDR_UNSUPPORTED', message: 'no colour-management protocol');
},
);
await _pumpSheet(tester, player: player, supportsHdrControl: true);
@@ -162,38 +175,291 @@ void main() {
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
expect(writeCount, 1);
expect(find.text(t.videoSettings.hdrUnsupported), findsOneWidget);
// Once. A refusal is not something to compensate for: nothing was recorded,
// so there is nothing to put back and no second write to explain.
expect(writes, [('hdr-enabled', 'no')]);
expect(tester.widget<Switch>(toggle).value, isTrue);
expect(SettingsService.instance.read(SettingsService.enableHDR), isTrue);
});
testWidgets('an accepted HDR write pushes one hdr-enabled write per toggle', (tester) async {
final writes = <(String, String)>[];
final player = _FakeSettingsPlayer(onSetProperty: (name, value) async => writes.add((name, value)));
await _pumpSheet(tester, player: player, supportsHdrControl: true);
await tester.scrollUntilVisible(find.text('HDR'), 500, scrollable: find.byType(Scrollable).first);
final tile = find.ancestor(of: find.text('HDR'), matching: find.byType(ListTile)).first;
final toggle = find.descendant(of: tile, matching: find.byType(Switch));
await tester.tap(toggle);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
expect(writes, [('hdr-enabled', 'no')]);
expect(tester.widget<Switch>(toggle).value, isFalse);
expect(SettingsService.instance.read(SettingsService.enableHDR), isFalse);
// Toggled back so the expectation cannot be met by a sheet that sends 'no'
// whichever way the switch went.
await tester.tap(toggle);
await tester.pumpAndSettle();
expect(writes, [('hdr-enabled', 'no'), ('hdr-enabled', 'yes')]);
expect(tester.widget<Switch>(toggle).value, isTrue);
expect(SettingsService.instance.read(SettingsService.enableHDR), isTrue);
});
testWidgets('hides the HDR controls when the host declares the surface cannot carry HDR', (tester) async {
await _pumpSheet(tester);
// Scroll past where the HDR rows would sit. Without a following anchor the
// absence would also be satisfied by the ListView simply not having built
// that far yet, which is not the contract under test.
await tester.scrollUntilVisible(find.text('Auto-Play Next'), 500, scrollable: find.byType(Scrollable).first);
expect(find.text('HDR'), findsNothing);
expect(find.text('HDR Tone Mapping'), findsNothing);
});
// The sheet resolves both the capability probe and the tone-mapping row through
// PlayerNative.usesLinuxVideoPlane, so setting the documented override puts the
// plane's behaviour under test on any host.
group('on the Linux video plane', () {
setUp(() {
PlayerNative.debugUseLinuxVideoPlane = true;
});
tearDown(() {
PlayerNative.debugUseLinuxVideoPlane = null;
});
// supportsHdrControl left null so the sheet asks the player, which is the path
// that ships on Linux. The cases above inject the answer and so cover only the
// gate, not the probe behind it.
testWidgets('hides the HDR controls when the capability probe answers no', (tester) async {
final player = _FakeSettingsPlayer(hdrOutputSupported: false);
await _pumpSheet(tester, player: player, supportsHdrControl: null, height: 4000);
expect(find.text('Auto-Play Next'), findsOneWidget, reason: 'the list should be fully built');
expect(find.text('HDR'), findsNothing);
expect(find.text('HDR Tone Mapping'), findsNothing);
});
testWidgets('a player reporting an HDR output reveals the controls', (tester) async {
final player = _FakeSettingsPlayer(hdrOutputSupported: true);
await _pumpSheet(tester, player: player, supportsHdrControl: null, height: 4000);
expect(find.text('HDR'), findsOneWidget);
expect(find.text('HDR Tone Mapping'), findsOneWidget);
});
// Dragging the window onto an HDR monitor raises no lifecycle event on
// Wayland, so this stream is the sheet's only notice that the probe now
// answers differently.
testWidgets('an HDR output arriving under the window reveals the controls', (tester) async {
final player = _FakeSettingsPlayer(hdrOutputSupported: false);
await _pumpSheet(tester, player: player, supportsHdrControl: null, height: 4000);
expect(find.text('HDR'), findsNothing);
player.hdrOutputSupported = true;
player.hdrOutputChanged.add(null);
await tester.pumpAndSettle();
expect(find.text('HDR'), findsOneWidget);
expect(find.text('HDR Tone Mapping'), findsOneWidget);
});
testWidgets('losing the HDR output takes the controls away again', (tester) async {
final player = _FakeSettingsPlayer(hdrOutputSupported: true);
await _pumpSheet(tester, player: player, supportsHdrControl: null, height: 4000);
expect(find.text('HDR'), findsOneWidget);
player.hdrOutputSupported = false;
player.hdrOutputChanged.add(null);
await tester.pumpAndSettle();
expect(find.text('Auto-Play Next'), findsOneWidget, reason: 'the list should be fully built');
expect(find.text('HDR'), findsNothing);
expect(find.text('HDR Tone Mapping'), findsNothing);
});
testWidgets('the output-changed subscription does not outlive the sheet', (tester) async {
final player = _FakeSettingsPlayer(hdrOutputSupported: false);
await _pumpSheet(tester, player: player, supportsHdrControl: null, height: 4000);
final probesWhileMounted = player.probeCount;
await tester.pumpWidget(const MaterialApp(home: SizedBox.shrink()));
await tester.pumpAndSettle();
player.hdrOutputSupported = true;
player.hdrOutputChanged.add(null);
await tester.pumpAndSettle();
// The plane outlives any one sheet, so a subscription left behind keeps
// probing - and setState()s - on a disposed State.
expect(player.hdrOutputChanged.hasListener, isFalse);
expect(player.probeCount, probesWhileMounted);
expect(tester.takeException(), isNull);
});
testWidgets('selecting a tone-mapping mode pushes it to mpv and persists it', (tester) async {
final writes = <(String, String)>[];
final player = _FakeSettingsPlayer(onSetProperty: (name, value) async => writes.add((name, value)));
await _pumpSheet(tester, player: player, supportsHdrControl: true, withSheetHost: true);
await tester.scrollUntilVisible(find.text('HDR Tone Mapping'), 500, scrollable: find.byType(Scrollable).first);
await tester.tap(find.text('HDR Tone Mapping'));
await tester.pumpAndSettle();
await tester.tap(find.text('Player'));
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
expect(writes, [('hdr-tone-mapping', 'player')]);
expect(SettingsService.instance.read(SettingsService.hdrToneMapping), HdrToneMapping.player);
});
testWidgets('a refused tone-mapping write leaves the stored mode alone', (tester) async {
final writes = <(String, String)>[];
final player = _FakeSettingsPlayer(
onSetProperty: (name, value) async {
writes.add((name, value));
throw StateError('rejected');
},
);
await _pumpSheet(tester, player: player, supportsHdrControl: true, withSheetHost: true);
await tester.scrollUntilVisible(find.text('HDR Tone Mapping'), 500, scrollable: find.byType(Scrollable).first);
await tester.tap(find.text('HDR Tone Mapping'));
await tester.pumpAndSettle();
await tester.tap(find.text('Player'));
await tester.pumpAndSettle();
// mpv is asked before the setting is written, precisely so a refusal
// cannot leave the stored mode claiming one the player never entered.
expect(tester.takeException(), isNull);
expect(writes, [('hdr-tone-mapping', 'player')]);
expect(SettingsService.instance.read(SettingsService.hdrToneMapping), HdrToneMapping.compositor);
});
});
// The refusals covered above all come from the player. This is the other half:
// the player takes the value and the store loses it, which is the case that
// used to leave the plane carrying a policy neither the sheet nor the stored
// preference named for the rest of the session.
group('when the preference store refuses the write', () {
late _RejectingPrefsStore store;
setUp(() async {
// The tone-mapping row is gated on the plane. Installing the store belongs
// out here too: SharedPreferencesWithCache binds the platform when it is
// created, and creating it reads the store off disk, which a testWidgets
// body cannot await.
PlayerNative.debugUseLinuxVideoPlane = true;
store = _RejectingPrefsStore(
// Seeded with the values both controls start on, so a rejected write is
// a rejected *overwrite* and the surviving value is an explicit one
// rather than the absence of a key.
initial: {SettingsService.enableHDR.key: true, SettingsService.hdrToneMapping.key: 'compositor'},
refused: {SettingsService.enableHDR.key, SettingsService.hdrToneMapping.key},
);
SharedPreferencesAsyncPlatform.instance = store;
// resetSharedPreferencesForTest already registered the teardown that puts
// the previous platform back.
BaseSharedPreferencesService.resetForTesting();
SettingsService.resetForTesting();
await SettingsService.getInstance();
});
tearDown(() {
PlayerNative.debugUseLinuxVideoPlane = null;
});
testWidgets('a lost HDR preference write puts the plane back on the stored policy', (tester) async {
final writes = <(String, String)>[];
final player = _FakeSettingsPlayer(onSetProperty: (name, value) async => writes.add((name, value)));
await _pumpSheet(tester, player: player, supportsHdrControl: true);
await tester.scrollUntilVisible(find.text('HDR'), 500, scrollable: find.byType(Scrollable).first);
final tile = find.ancestor(of: find.text('HDR'), matching: find.byType(ListTile)).first;
final toggle = find.descendant(of: tile, matching: find.byType(Switch));
expect(tester.widget<Switch>(toggle).value, isTrue);
await tester.tap(toggle);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
// The plane accepted 'no' and the store then lost it, so the plane has to
// be told 'yes' again. Leaving it at 'no' is the divergence.
expect(writes, [('hdr-enabled', 'no'), ('hdr-enabled', 'yes')]);
expect(tester.widget<Switch>(toggle).value, isTrue);
expect(SettingsService.instance.read(SettingsService.enableHDR), isTrue);
expect(await store.durable(SettingsService.enableHDR.key), isTrue);
});
testWidgets('a lost tone-mapping preference write puts the plane back on the stored mode', (tester) async {
final writes = <(String, String)>[];
final player = _FakeSettingsPlayer(onSetProperty: (name, value) async => writes.add((name, value)));
await _pumpSheet(tester, player: player, supportsHdrControl: true, withSheetHost: true);
await tester.scrollUntilVisible(find.text('HDR Tone Mapping'), 500, scrollable: find.byType(Scrollable).first);
await tester.tap(find.text('HDR Tone Mapping'));
await tester.pumpAndSettle();
await tester.tap(find.text('Player'));
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
expect(writes, [('hdr-tone-mapping', 'player'), ('hdr-tone-mapping', 'compositor')]);
expect(SettingsService.instance.read(SettingsService.hdrToneMapping), HdrToneMapping.compositor);
expect(await store.durable(SettingsService.hdrToneMapping.key), 'compositor');
// The pick did not take, so the picker stays open with the tick where it
// was. A tick on 'Player' would mean the sheet is showing a mode the
// stored preference does not name.
expect(_tickOn('Compositor'), findsOneWidget);
expect(_tickOn('Player'), findsNothing);
});
});
}
/// The tick marking the selected option in one of the sheet's picker views.
Finder _tickOn(String label) => find.descendant(
of: find.ancestor(of: find.text(label), matching: find.byType(ListTile)).first,
matching: find.byIcon(Symbols.check_rounded),
);
Future<void> _pumpSheet(
WidgetTester tester, {
bool canControl = false,
Player? player,
bool supportsHdrControl = false,
// Explicitly false by default so the sheet does not consult the platform.
// Pass null to exercise the capability probe instead.
bool? supportsHdrControl = false,
// Option views that dismiss themselves on selection reach
// OverlaySheetController.of(), which asserts without a host above it.
bool withSheetHost = false,
// The default is short enough that the ListView is lazy: callers that need a
// row present without dragging to it pass a taller sheet, which builds all of
// them.
double height = 700,
}) async {
final sheet = SizedBox(
width: 900,
height: height,
child: VideoSettingsSheet(
player: player ?? _FakeSettingsPlayer(),
supportsHdrControl: supportsHdrControl,
trackControlsState: TrackControlsState(canControl: canControl),
),
);
await tester.pumpWidget(
MaterialApp(
theme: ThemeData(extensions: const [testMonoTokensAnimated]),
home: Scaffold(
body: SizedBox(
width: 900,
height: 700,
child: VideoSettingsSheet(
player: player ?? _FakeSettingsPlayer(),
supportsHdrControl: supportsHdrControl,
trackControlsState: TrackControlsState(canControl: canControl),
),
),
),
home: Scaffold(body: withSheetHost ? OverlaySheetHost(child: sheet) : sheet),
),
);
await tester.pumpAndSettle();
}
Future<void> _pumpHostedSheet(WidgetTester tester, Player player) async {
Future<void> _pumpSheetViaOverlayRoute(WidgetTester tester, Player player) async {
await tester.pumpWidget(
MaterialApp(
theme: ThemeData(extensions: const [testMonoTokensAnimated]),
@@ -221,31 +487,51 @@ Future<void> _pumpHostedSheet(WidgetTester tester, Player player) async {
}
class _FakeSettingsPlayer implements Player {
_FakeSettingsPlayer({this.onSetProperty, this.onSetRate})
: _streams = PlayerStreams(
playing: const Stream<bool>.empty(),
completed: const Stream<bool>.empty(),
buffering: const Stream<bool>.empty(),
position: const Stream<Duration>.empty(),
duration: const Stream<Duration>.empty(),
seekable: const Stream<bool>.empty(),
buffer: const Stream<Duration>.empty(),
volume: const Stream<double>.empty(),
rate: const Stream<double>.empty(),
tracks: const Stream<Tracks>.empty(),
track: const Stream<TrackSelection>.empty(),
log: const Stream<PlayerLog>.empty(),
error: const Stream<PlayerError>.empty(),
audioDevice: const Stream<AudioDevice>.empty(),
audioDevices: const Stream<List<AudioDevice>>.empty(),
bufferRanges: const Stream<List<BufferRange>>.empty(),
playbackRestart: const Stream<void>.empty(),
backendSwitched: const Stream<void>.empty(),
);
_FakeSettingsPlayer({this.onSetProperty, this.onSetRate, this.hdrOutputSupported = false});
/// The plane's notice that the output under the window changed, which is the
/// only thing that moves [isHdrOutputSupported]'s answer while a sheet is up.
/// Closed by [dispose], which the tests that emit on it call through
/// `addTearDown`.
final hdrOutputChanged = StreamController<void>.broadcast();
@override
Future<void> dispose({bool preserveDisplayMode = false}) async {
await hdrOutputChanged.close();
}
late final PlayerStreams _streams = PlayerStreams(
playing: const Stream<bool>.empty(),
completed: const Stream<bool>.empty(),
buffering: const Stream<bool>.empty(),
position: const Stream<Duration>.empty(),
duration: const Stream<Duration>.empty(),
seekable: const Stream<bool>.empty(),
buffer: const Stream<Duration>.empty(),
volume: const Stream<double>.empty(),
rate: const Stream<double>.empty(),
tracks: const Stream<Tracks>.empty(),
track: const Stream<TrackSelection>.empty(),
log: const Stream<PlayerLog>.empty(),
error: const Stream<PlayerError>.empty(),
audioDevice: const Stream<AudioDevice>.empty(),
audioDevices: const Stream<List<AudioDevice>>.empty(),
bufferRanges: const Stream<List<BufferRange>>.empty(),
playbackRestart: const Stream<void>.empty(),
backendSwitched: const Stream<void>.empty(),
hdrOutputChanged: hdrOutputChanged.stream,
);
final PlayerStreams _streams;
final Future<void> Function(String name, String value)? onSetProperty;
final Future<void> Function(double rate)? onSetRate;
bool hdrOutputSupported;
int probeCount = 0;
@override
Future<bool> isHdrOutputSupported() async {
probeCount++;
return hdrOutputSupported;
}
@override
PlayerState get state => const PlayerState();
@@ -272,3 +558,37 @@ class _FakeSettingsPlayer implements Player {
@override
dynamic noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation);
}
/// A preference store that loses the durable half of a write.
///
/// Substituting the platform is how this suite supplies a store at all (see
/// [resetSharedPreferencesForTest]), and it is the only layer that can be lost:
/// `SharedPreferencesWithCache` sits above it and is not subclassable.
final class _RejectingPrefsStore extends InMemorySharedPreferencesAsync {
_RejectingPrefsStore({required Map<String, Object> initial, required this.refused}) : super.withData(initial);
/// Only these keys. Creating the cache runs the legacy-to-async migration,
/// which stores its own completion marker and must be allowed to.
final Set<String> refused;
/// What survived, which is what the next launch reads. Not
/// `SettingsService.read`: that answers from the in-process copy, which a
/// refused write moves before the platform call it then fails.
Future<Object?> durable(String key) async {
final stored = await getPreferences(
GetPreferencesParameters(filter: PreferencesFilters(allowList: {key})),
const SharedPreferencesOptions(),
);
return stored[key];
}
Future<bool> _refuse(String key) async => throw StateError('the preference store refused "$key"');
@override
Future<bool> setBool(String key, bool value, SharedPreferencesOptions options) =>
refused.contains(key) ? _refuse(key) : super.setBool(key, value, options);
@override
Future<bool> setString(String key, String value, SharedPreferencesOptions options) =>
refused.contains(key) ? _refuse(key) : super.setString(key, value, options);
}