output.cpp

#include "output/output.h"

#include "config/config.h"
#include "config/resolve.h"
#include "core/log.h"
#include "core/tracy.h"
#include "input/cursor.h"
#include "input/seat.h"
#include "layer/layer_surface.h"
#include "lock/session_lock.h"
#include "output/cursor_plane_pace.h"
#include "output/format_sequence.h"
#include "output/frame_schedule.h"
#include "output/gamma_transition.h"
#include "output/hdr_format.h"
#include "output/hdr_metadata.h"
#include "output/identity.h"
#include "output/mode_selection.h"
#include "output/rendered_state_commit.h"
#include "output/sdr_format.h"
#include "overview/overview.h"
#include "scene/cheatsheet.h"
#include "scene/config_banner.h"
#include "scene/node.h"
#include "scene/quit_confirm.h"
#include "server/color_manager.h"
#include "server/ipc.h"
#include "server/server.h"
#include "view/view.h"
#include "wlr.h"
#include "workspace/scratchpad.h"
#include "workspace/workspace.h"

extern "C" {
#include <umbrielfx/render/effect.h>
#include <wlr/util/transform.h>
}

#include <algorithm>
#include <cassert>
#include <cmath>
#include <cstdlib>
#include <ctime>
#include <drm_fourcc.h>
#include <format>

#ifdef TRACY_ENABLE
#include <set>
#endif

namespace umbriel {

  namespace {
    constexpr Logger kLog("output");
    constexpr int kFrameRetryDelayMs = 16;

    std::string_view directScanoutReason(wlr_scene_direct_scanout_status status) {
      switch (status) {
      case WLR_SCENE_DIRECT_SCANOUT_ACTIVE:
        return "";
      case WLR_SCENE_DIRECT_SCANOUT_DISABLED:
        return "disabled";
      case WLR_SCENE_DIRECT_SCANOUT_NO_CANDIDATE:
        return "no_candidate";
      case WLR_SCENE_DIRECT_SCANOUT_COMPOSITED:
        return "composited";
      case WLR_SCENE_DIRECT_SCANOUT_EFFECTS:
        return "effects";
      case WLR_SCENE_DIRECT_SCANOUT_COLOR:
        return "color_conversion";
      case WLR_SCENE_DIRECT_SCANOUT_CAPTURE:
        return "capture";
      case WLR_SCENE_DIRECT_SCANOUT_CROPPED:
        return "cropped";
      case WLR_SCENE_DIRECT_SCANOUT_TRANSFORM:
        return "transform";
      case WLR_SCENE_DIRECT_SCANOUT_MODESET:
        return "modeset";
      case WLR_SCENE_DIRECT_SCANOUT_RENDER_LOCKED:
        return "render_locked";
      case WLR_SCENE_DIRECT_SCANOUT_SOFTWARE_CURSOR:
        return "software_cursor";
      case WLR_SCENE_DIRECT_SCANOUT_REJECTED:
        return "rejected";
      case WLR_SCENE_DIRECT_SCANOUT_DEBUG_DAMAGE:
        return "debug_damage";
      }
      return "unknown";
    }

    struct OutputFrameScope {
      explicit OutputFrameScope(Server& owner) : server(owner) { server.beginOutputFrame(); }
      ~OutputFrameScope() { server.endOutputFrame(); }
      Server& server;
    };

    wlr_box
    pendingSceneBox(const wlr_output& output, const wlr_output_state& state, const wlr_scene_output& sceneOutput) {
      int width = output.width;
      int height = output.height;
      if ((state.committed & WLR_OUTPUT_STATE_MODE) != 0) {
        if (state.mode_type == WLR_OUTPUT_STATE_MODE_FIXED && state.mode != nullptr) {
          width = state.mode->width;
          height = state.mode->height;
        } else if (state.mode_type == WLR_OUTPUT_STATE_MODE_CUSTOM) {
          width = state.custom_mode.width;
          height = state.custom_mode.height;
        }
      }

      const wl_output_transform transform =
          (state.committed & WLR_OUTPUT_STATE_TRANSFORM) != 0 ? state.transform : output.transform;
      wlr_output_transform_coords(transform, &width, &height);
      const float scale = (state.committed & WLR_OUTPUT_STATE_SCALE) != 0 ? state.scale : output.scale;
      if (scale > 0.0F) {
        width = static_cast<int>(std::ceil(static_cast<double>(width) / scale));
        height = static_cast<int>(std::ceil(static_cast<double>(height) / scale));
      }
      return {.x = sceneOutput.x, .y = sceneOutput.y, .width = width, .height = height};
    }

    // Staging any mode, even the live one, makes wlroots request ALLOW_MODESET, which makes the display resync.
    wlr_output_mode* keepLiveModeOrStage(wlr_output_state& state, const wlr_output& output, wlr_output_mode* mode) {
      if (!liveModeMatches(output, mode)) {
        wlr_output_state_set_mode(&state, mode);
        return nullptr;
      }
      kLog.info("output '{}': keeping live mode {}x{}@{}mHz", output.name, mode->width, mode->height, mode->refresh);
      return mode;
    }

#ifdef TRACY_ENABLE
    // Tracy keeps a plot's name pointer and reads it while a capture runs, so
    // the per-output names live for the rest of the process.
    const char* tracyPlotName(std::string name) {
      static std::set<std::string> names;
      return names.insert(std::move(name)).first->c_str();
    }
#endif

  } // namespace

  OutputIdentity Output::identity() const {
    const auto text = [](const char* value) { return value != nullptr ? std::string_view(value) : std::string_view(); };
    return m_output != nullptr
        ? OutputIdentity{
              .connector = text(m_output->name),
              .make = text(m_output->make),
              .model = text(m_output->model),
              .serial = text(m_output->serial),
          }
        : OutputIdentity{};
  }

  Output::Output(Server& server, wlr_output* output)
      : m_server(&server), m_output(output), m_defaultScale(output->scale),
        m_hdrStaticMetadata(hdrStaticMetadataForOutput(output)) {
    m_output->data = this;
    wlr_output_init_render(m_output, m_server->allocator(), m_server->renderer());
    // Create the scene output before the initial configuration so startup and
    // resume modesets carry rendered content instead of wlroots' empty buffer.
    m_sceneOutput = wlr_scene_output_create(m_server->scene(), m_output);
    if (m_sceneOutput == nullptr) {
      kLog.error("output '{}': failed to create scene output", m_output->name);
      std::abort();
    }
    wlr_scene_output_set_direct_scanout_enabled(m_sceneOutput, configuredDirectScanoutEnabled());

    m_frame.notify = onFrame;
    wl_signal_add(&m_output->events.frame, &m_frame);

    m_requestState.notify = onRequestState;
    wl_signal_add(&m_output->events.request_state, &m_requestState);

    m_present.notify = onPresent;
    wl_signal_add(&m_output->events.present, &m_present);

    m_destroy.notify = onDestroy;
    wl_signal_add(&m_output->events.destroy, &m_destroy);

    m_frameRetryTimer =
        wl_event_loop_add_timer(wl_display_get_event_loop(m_server->display()), onFrameRetryTimer, this);
    m_directScanoutTimer =
        wl_event_loop_add_timer(wl_display_get_event_loop(m_server->display()), onDirectScanoutTimer, this);

    applyCursorConfig();
    m_desktopEnabled = m_server->initialOutputEnabled(*this);
    if (!applyConfiguredState()) {
      // Do not advertise a logical output whose initial backend enable failed.
      // Keeping it disabled lets a later output-enable action retry the commit.
      m_desktopEnabled = false;
    }
    updateSceneSdrWhite();
    if (desktopEnabled()) {
      wlr_output_layout_output* layoutOutput = addToLayout();
      wlr_scene_output_layout_add_output(m_server->sceneLayout(), layoutOutput, m_sceneOutput);
    }
    m_server->resolveOutputEffect(*this);
    applyOutputEffects();

    for (uint32_t layer = 0; layer < kLayerCount; ++layer) {
      m_layerTrees[layer] = wlr_scene_tree_create(m_server->shellLayerTree(layer));
      m_layerPopupTrees[layer] = wlr_scene_tree_create(m_server->shellLayerTree(layer));
    }
    m_backgroundUpdate.notify = onBackgroundUpdate;
    if (!wlr_scene_node_add_update_listener(
            &layerTree(ZWLR_LAYER_SHELL_V1_LAYER_BACKGROUND)->node, &m_backgroundUpdate
        )) {
      kLog.error("output '{}': failed to watch background scene updates", m_output->name);
      std::abort();
    }
    m_backgroundPopupUpdate.notify = onBackgroundPopupUpdate;
    if (!wlr_scene_node_add_update_listener(
            &layerPopupTree(ZWLR_LAYER_SHELL_V1_LAYER_BACKGROUND)->node, &m_backgroundPopupUpdate
        )) {
      kLog.error("output '{}': failed to watch background popup updates", m_output->name);
      std::abort();
    }
    m_viewRoot = wlr_scene_tree_create(m_server->xdgTree());
    m_fullscreenRoot = wlr_scene_tree_create(m_server->fullscreenTree());
    m_pinnedRoot = wlr_scene_tree_create(m_server->pinnedTree());
    arrangeLayers();
    m_workspaceGroup = std::make_unique<WorkspaceGroup>(*m_server, *this);
  }

  bool Output::configuredEnabled() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule != nullptr ? rule->enabled : outputCanAutoEnable(m_output);
  }

  void Output::scheduleEffectFrame() {
    if (m_handlingFrame) {
      return; // handleFrame arms the next effect frame after its tick
    }
    m_effectFrameDue = true;
    wlr_output_schedule_frame(m_output);
  }

  void Output::scheduleAudioFrame() {
    if (m_server->sessionLocked() || !outputFrameAllowed(m_server->stopping(), m_server->session())) {
      m_effectAudio = {};
      wlr_scene_output_set_effect_audio(m_sceneOutput, m_effectAudio.data());
      return;
    }
    if (!wlr_scene_output_audio_active(m_sceneOutput)) {
      return;
    }
    timespec now{};
    clock_gettime(CLOCK_MONOTONIC, &now);
    armEffectFrame(static_cast<uint64_t>(now.tv_sec) * 1000 + static_cast<uint64_t>(now.tv_nsec) / 1'000'000);
  }

  bool Output::audioPending() const {
    return m_effectAudio != m_server->effects().audio() && wlr_scene_output_audio_active(m_sceneOutput);
  }

  void Output::applyOutputEffects() {
    EffectRegistry& registry = m_server->effects();
    const Effects& settings = config().effects;
    // Nothing configured: touch nothing (no addon, no scene calls). The registry's counts are zero too; a bound
    // screen or cursor slot keeps a ledger instance, so it is still detached below.
    if (settings.presets.empty() && !registry.active() && !registry.persistentReferenced()) {
      return;
    }
    wlr_scene_output_set_effect_capture_policy(m_sceneOutput, settings.inCapture);
    const std::string_view screenName = m_screenEffectSlot.effectiveName();
    const std::string_view cursorName = m_server->cursorEffectSlot().effectiveName();
    const bool suspended = registry.ledger().suspended();
    fx_effect_shader* screen = suspended ? nullptr : registry.preset(screenName, EffectKind::Screen);
    const EffectPreset* screenPreset = screen != nullptr ? registry.presetConfig(screenName) : nullptr;
    fx_effect_shader* cursor = suspended ? nullptr : registry.preset(cursorName, EffectKind::Cursor);
    const EffectPreset* cursorPreset = cursor != nullptr ? registry.presetConfig(cursorName) : nullptr;
    bool advancing = true;
#ifdef UMBRIEL_HARNESS
    advancing = !m_server->animationClockFrozen();
#endif
    wlr_scene_output_set_effect_time(m_sceneOutput, m_server->animationClockMsec());
    m_outputEffectsTimed = false;
    // Register demand after the cursor program and motion history have been updated.
    const auto bind = [&](const void* owner, fx_effect_shader* shader, bool visible) {
      const bool motion = fx_effect_shader_reads(shader, "umbriel_pointer_history")
          || fx_effect_shader_reads(shader, "umbriel_pointer_path");
      const bool readsTime = fx_effect_shader_reads(shader, "umbriel_time")
          || (motion && wlr_scene_output_cursor_motion_active(m_sceneOutput));
      m_outputEffectsTimed = m_outputEffectsTimed || (readsTime && visible);
      registry.updateInstance(
          owner, {.output = this, .visible = visible, .readsTime = readsTime, .advancing = advancing}
      );
    };
    if (screenPreset != nullptr) {
      fx_animation_parameters parameters{};
      registry.fillTimeUniforms(parameters, m_effectSeconds, *screenPreset, screen);
      bind(this, screen, m_output->enabled);
      wlr_scene_output_set_screen_effect(m_sceneOutput, screen, &parameters);
    } else {
      wlr_scene_output_set_screen_effect(m_sceneOutput, nullptr, nullptr);
      registry.removeInstance(this);
    }
    const Cursor* pointer = m_server->cursor();
    if (cursorPreset != nullptr && pointer != nullptr) {
      const double lx = pointer->wlr()->x;
      const double ly = pointer->wlr()->y;
      const bool here = wlr_output_layout_output_at(m_server->outputLayout(), lx, ly) == m_output;
      fx_animation_parameters parameters{};
      registry.fillTimeUniforms(parameters, m_effectSeconds, *cursorPreset, cursor);
      wlr_scene_output_set_cursor_effect(m_sceneOutput, cursor, &parameters, cursorPreset->radius);
      // A newly set cursor program draws nothing until the pointer is pushed after it.
      wlr_scene_output_set_effect_time(m_sceneOutput, m_server->animationClockMsec());
      wlr_scene_output_set_effect_pointer(m_sceneOutput, lx, ly, pointer->visible());
      bind(&m_cursorEffectOwner, cursor, m_output->enabled && here && pointer->visible());
    } else {
      wlr_scene_output_set_cursor_effect(m_sceneOutput, nullptr, nullptr, 0);
      registry.removeInstance(&m_cursorEffectOwner);
    }
  }

  void Output::scheduleEffectCaptureRelease() {
    if (m_effectCaptureBuilt && outputFrameAllowed(m_server->stopping(), m_server->session())) {
      wlr_output_schedule_frame(m_output);
    }
  }

  int Output::externalRenderLocks() const { return m_output->attach_render_locks - (m_animationRenderLocked ? 1 : 0); }

  bool Output::effectCapturePending(int captureLocks) const {
    // Keyed on configuration, not instances: a close snapshot keeps its window slots after its instances leave.
    return captureLocks > 0 && !config().effects.inCapture && m_server->effects().inPlaceReferenced();
  }

  bool Output::captureExclusionPending(int captureLocks) const {
    return captureLocks > 0 && umbrielfx_scene_has_capture_exclusion(m_sceneOutput->scene);
  }

  unsigned Output::effectEligible() const { return m_server->effects().ledger().eligible(this); }

  wlr_box Output::layoutBox() const {
    wlr_box box{.x = m_arrangedLayoutX, .y = m_arrangedLayoutY, .width = 0, .height = 0};
    wlr_output_effective_resolution(m_output, &box.width, &box.height);
    if (const wlr_output_layout_output* layoutOutput = wlr_output_layout_get(m_server->outputLayout(), m_output)) {
      box.x = layoutOutput->x;
      box.y = layoutOutput->y;
    }
    return box;
  }

  wlr_box Output::usableArea() const {
    wlr_box area = m_localUsableArea;
    const wlr_box box = layoutBox();
    area.x += box.x;
    area.y += box.y;
    return area;
  }

  HdrMode Output::hdrMode() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule != nullptr ? rule->hdr : HdrMode::Off;
  }

  bool Output::hdrRequested() const {
    if (wlr_surface* surface = m_server->seat()->wlr()->keyboard_state.focused_surface) {
      if (View* view = View::fromSurface(surface); view != nullptr && view->mapped() && view->currentOutput() == this) {
        if (const std::optional<HdrMode> mode = view->resolvedRules().hdr) {
          const bool fullscreen = view->layoutFullscreen() || view->currentFullscreen();
          return hdrEnabled(*mode, fullscreen, autoHdrEligible(view));
        }
      }
    }
    const HdrMode mode = hdrMode();
    return hdrEnabled(mode, m_fullscreenHdrRequested, m_autoHdrOwner != nullptr);
  }

  bool Output::hdrActive() const { return m_output->image_description != nullptr; }

  bool Output::automaticHdrAvailable() const {
    if (!m_output->enabled || !m_desktopEnabled || !m_hdrAvailable) {
      return false;
    }
    HdrMode mode = hdrMode();
    if (wlr_surface* surface = m_server->seat()->wlr()->keyboard_state.focused_surface) {
      if (View* view = View::fromSurface(surface); view != nullptr && view->mapped() && view->currentOutput() == this) {
        mode = view->resolvedRules().hdr.value_or(mode);
      }
    }
    return mode == HdrMode::Auto;
  }

  void Output::updateHdrAvailability(bool activationRejected) {
    m_hdrAvailable = false;
    if (!m_output->enabled
        || !m_desktopEnabled
        || (m_output->supported_transfer_functions & WLR_COLOR_TRANSFER_FUNCTION_ST2084_PQ) == 0
        || (m_output->supported_primaries & WLR_COLOR_NAMED_PRIMARIES_BT2020) == 0
        || !m_server->renderer()->features.output_color_transform) {
      return;
    }
    if (hdrActive()) {
      m_hdrAvailable = true;
      return;
    }
    // A successful SDR fallback after a rejected HDR request is not evidence
    // that HDR became available. A later configuration retry can probe again.
    if (activationRejected) {
      return;
    }
    const wlr_drm_format_set* formats = wlr_output_get_primary_formats(m_output, m_server->allocator()->buffer_caps);
    wlr_output_state state{};
    wlr_output_state_init(&state);
    state.allow_reconfiguration = true;
    wlr_output_state_set_color_transform(&state, nullptr);
    const auto description = makeHdrOutputDescription(m_output->default_primaries, m_hdrStaticMetadata);
    if (wlr_output_state_set_image_description(&state, &description)) {
      m_hdrAvailable = selectHdrRenderFormat(m_output->render_format, [&](uint32_t format) {
                         if (formats != nullptr && wlr_drm_format_set_get(formats, format) == nullptr) {
                           return false;
                         }
                         wlr_output_state_set_render_format(&state, format);
                         if (wlr_output_test_state(m_output, &state)) {
                           return true;
                         }
                         // The real activation path can drop VRR when HDR needs it disabled.
                         if (m_output->adaptive_sync_supported
                             && m_output->adaptive_sync_status == WLR_OUTPUT_ADAPTIVE_SYNC_ENABLED) {
                           wlr_output_state_set_adaptive_sync_enabled(&state, false);
                           return wlr_output_test_state(m_output, &state);
                         }
                         return false;
                       }).has_value();
    }
    wlr_output_state_finish(&state);
    if (m_hdrAvailable && hdrRequested()) {
      // A mode change can make a previously rejected request usable. Retry at
      // the frame boundary instead of treating its old SDR fallback as final.
      m_hdrTransition.recordCommit(true, false, true);
      scheduleFullFrame();
    }
  }

  bool Output::bitDepthActive() const {
    return deriveTenBitSdrActive(m_output->enabled, hdrActive(), m_output->render_format);
  }

  float Output::configuredSdrWhite() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule != nullptr ? rule->sdrWhite : 203.0F;
  }

  float Output::sdrWhite() const { return m_runtimeSdrWhite.value_or(configuredSdrWhite()); }

  SdrTransfer Output::configuredSdrTransfer() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule != nullptr ? rule->sdrTransfer : SdrTransfer::Gamma22;
  }

  void Output::setRuntimeSdrWhite(float nits) {
    if (m_runtimeSdrWhite && *m_runtimeSdrWhite == nits) {
      return;
    }
    m_runtimeSdrWhite = nits;
    kLog.info("output '{}': live SDR white {} cd/m2", m_output->name, nits);
    updateSceneSdrWhite();
    markBlurBackgroundDirty();
    m_server->updateColorPreferences();
    wlr_output_schedule_frame(m_output);
  }

  int Output::configuredBitDepth() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule != nullptr ? rule->bitDepth : 8;
  }

  bool Output::configuredDirectScanoutEnabled() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule == nullptr || rule->directScanout;
  }

  bool Output::configuredTearingAllowed() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule != nullptr && rule->allowTearing;
  }

  bool Output::configuredCyclicWorkspaces() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    return rule != nullptr && rule->cyclicWorkspaces;
  }

  View* Output::tearingCandidate() const {
    const Workspace* workspace = m_workspaceGroup != nullptr ? m_workspaceGroup->active() : nullptr;
    if (workspace == nullptr) {
      return nullptr;
    }
    const auto eligible = [this](View* view) {
      return view != nullptr
          && view->mapped()
          && view->onActiveWorkspace()
          && view->currentOutput() == this
          && view->layoutFullscreen()
          && view->currentFullscreen();
    };
    if (View* focused = workspace->focusedView(); eligible(focused)) {
      return focused;
    }
    const auto& views = workspace->allViews();
    const auto candidate = std::ranges::find_if(views, eligible);
    return candidate != views.end() ? *candidate : nullptr;
  }

  bool Output::clientTearingHintAsync(const View* view) const {
    if (view == nullptr || m_server->tearingControlManager() == nullptr) {
      return false;
    }
    return wlr_tearing_control_manager_v1_surface_hint_from_surface(
               m_server->tearingControlManager(), view->rootSurface()
           )
        == WP_TEARING_CONTROL_V1_PRESENTATION_HINT_ASYNC;
  }

  bool Output::tearingEligible(View* view) const {
    if (view == nullptr || tearingCandidate() != view) {
      return false;
    }
    return tearingEnabled(configuredTearingAllowed(), view->resolvedRules().allowTearing, clientTearingHintAsync(view));
  }

  bool Output::tearingRequested() const { return tearingEligible(tearingCandidate()); }

  std::optional<bool> Output::lastPresentationVsync() const {
    if (!m_lastPresentationFlags || *m_lastPresentationFlags == 0) {
      return std::nullopt;
    }
    return (*m_lastPresentationFlags & WLR_OUTPUT_PRESENT_VSYNC) != 0;
  }

  void Output::resetTearingState() {
    m_tearingFallbackReason.clear();
    m_tearingRecovery.reset();
    wlr_output_schedule_frame(m_output);
  }

  void Output::applyDirectScanoutConfig() {
    wlr_scene_output_set_direct_scanout_enabled(m_sceneOutput, configuredDirectScanoutEnabled());
  }

  void Output::setHdrFallbackReason(std::string_view reason) {
    if (m_hdrFallbackReason == reason) {
      return;
    }
    m_hdrFallbackReason = reason;
    if (!reason.empty()) {
      kLog.warn("output '{}': HDR unavailable: {}", m_output->name, reason);
    }
  }

  void Output::setBitDepthFallbackReason(std::string_view reason) {
    if (m_bitDepthFallbackReason == reason) {
      return;
    }
    m_bitDepthFallbackReason = reason;
    if (!reason.empty()) {
      kLog.warn("output '{}': 10-bit SDR unavailable: {}", m_output->name, reason);
    }
  }

  void Output::updateSceneSdrWhite() {
    if (m_sceneOutput == nullptr) {
      return;
    }
    const float level = hdrActive() ? sdrWhite() : 0.0F;
    wlr_scene_output_set_sdr_white_level(m_sceneOutput, level);
    updateSceneHdrWhitePoint(wlr_gamma_control_manager_v1_get_control(m_server->gammaManager(), m_output));
  }

  void Output::updateSceneHdrWhitePoint(wlr_gamma_control_v1* control) {
    if (m_sceneOutput == nullptr) {
      return;
    }
    const auto white = hdrWhitePointFromGamma(
        control != nullptr ? control->table : nullptr, control != nullptr ? control->ramp_size : 0
    );
    wlr_scene_output_set_hdr_white_point(m_sceneOutput, white.data());
  }

  wlr_scene_rect* Output::createConfiguredFrameMask(const wlr_output_state& state) const {
    const wlr_box box = pendingSceneBox(*m_output, state, *m_sceneOutput);
    if (box.width <= 0 || box.height <= 0) {
      kLog.error("output '{}': configured frame has no secure logical extent", m_output->name);
      return nullptr;
    }
    auto color = config().colors.backdrop;
    color[3] = 1.0F;
    wlr_scene_rect* mask = wlr_scene_rect_create(&m_server->scene()->tree, box.width, box.height, color.data());
    if (mask == nullptr) {
      kLog.error("output '{}': failed to create secure mask for configured frame", m_output->name);
      return nullptr;
    }
    wlr_scene_node_set_position(&mask->node, box.x, box.y);
    wlr_scene_node_raise_to_top(&mask->node);
    return mask;
  }

  bool Output::applyConfiguredState(bool stageGeometry) {
    if (m_workspaceGroup != nullptr) {
      m_workspaceGroup->abandonReveal();
    }
    const OutputRule* rule = findOutputRule(config(), identity());
    const auto sdrTransfer = configuredSdrTransfer() == SdrTransfer::Srgb ? WLR_COLOR_TRANSFER_FUNCTION_SRGB
                                                                          : WLR_COLOR_TRANSFER_FUNCTION_GAMMA22;
    if (!wlr_scene_output_set_sdr_transfer_function(m_sceneOutput, sdrTransfer)) {
      kLog.error("output '{}': failed to apply SDR transfer function", m_output->name);
      return false;
    }
    const std::optional<double> configuredScale = rule != nullptr ? rule->scale : std::nullopt;
    const bool enabled = desktopEnabled() && !m_dpmsOff;
    wlr_output_state state{};
    wlr_output_state_init(&state);
    if (stageGeometry && outputEnableNeedsStaging(*m_output, enabled)) {
      wlr_output_state_set_enabled(&state, enabled);
    }

    const bool hdrWasActive = hdrActive();
    const bool hdrRequested = this->hdrRequested();

    // Stage geometry.
    bool scaleStaged = false;
    const OutputMode* configuredModeSpec = nullptr;
    wlr_output_mode* stagedMode = nullptr;
    wlr_output_mode* keptLiveMode = nullptr;
    if (enabled && stageGeometry) {
      if (rule != nullptr && rule->mode) {
        if (wlr_output_is_wl(m_output)) {
          kLog.info("output '{}': mode is ignored in nested sessions", m_output->name);
        } else {
          configuredModeSpec = &*rule->mode;
          stagedMode = selectOutputMode(m_output, *rule->mode);
          if (stagedMode != nullptr) {
            keptLiveMode = keepLiveModeOrStage(state, *m_output, stagedMode);
          } else {
            wlr_output_state_set_custom_mode(&state, rule->mode->width, rule->mode->height, rule->mode->refreshMHz);
          }
        }
      } else if (!wlr_output_is_wl(m_output)) {
        if (wlr_output_mode* mode = wlr_output_preferred_mode(m_output)) {
          keptLiveMode = keepLiveModeOrStage(state, *m_output, mode);
        }
      }

      if (configuredScale) {
        wlr_output_state_set_scale(&state, static_cast<float>(*configuredScale));
        scaleStaged = true;
      } else if (m_appliedConfiguredScale) {
        wlr_output_state_set_scale(&state, m_defaultScale);
        scaleStaged = true;
      }
      if (rule != nullptr && rule->transform) {
        wlr_output_state_set_transform(&state, static_cast<wl_output_transform>(*rule->transform));
      }
    }

    if (enabled && !stageGeometry) {
      // Image-description and max-bpc changes may require a modeset even
      // though the live mode and geometry stay unchanged.
      state.allow_reconfiguration = true;
    }

    // VRR variants. Try with VRR first (if requested and supported), then without.
    const bool vrrRequested = enabled && configuredVrrEnabled();
    const bool vrrSupported = m_output->adaptive_sync_supported;
    if (vrrRequested && !vrrSupported) {
      kLog.warn("output '{}': VRR requested but adaptive sync is not supported", m_output->name);
    }

    const bool tryVrrOn = vrrRequested && vrrSupported;

    // HDR pre-flight.
    std::string_view earlyHdrFail;
    bool imageDescAvailable = false;
    wlr_output_image_description hdrDescription{};
    if (enabled && hdrRequested) {
      if ((m_output->supported_transfer_functions & WLR_COLOR_TRANSFER_FUNCTION_ST2084_PQ) == 0) {
        earlyHdrFail = "display does not advertise PQ";
      } else if ((m_output->supported_primaries & WLR_COLOR_NAMED_PRIMARIES_BT2020) == 0) {
        earlyHdrFail = "display does not advertise BT.2020 primaries";
      } else if (!m_server->renderer()->features.output_color_transform) {
        earlyHdrFail = "renderer lacks FP16 output transform";
      } else {
        hdrDescription = makeHdrOutputDescription(m_output->default_primaries, m_hdrStaticMetadata);

        if (!wlr_output_state_set_image_description(&state, &hdrDescription)) {
          earlyHdrFail = "failed to stage HDR image description";
        } else {
          imageDescAvailable = true;
        }
      }
    }

    const wlr_drm_format_set* primaryFormats =
        enabled ? wlr_output_get_primary_formats(m_output, m_server->allocator()->buffer_caps) : nullptr;
    const int bitDepth = configuredBitDepth();

    const auto tenBitFormatName = [](uint32_t fmt) { return fmt == DRM_FORMAT_XRGB2101010 ? "XR30" : "XB30"; };

    const auto isPrimaryFormat = [&](uint32_t fmt) {
      return primaryFormats == nullptr || wlr_drm_format_set_get(primaryFormats, fmt) != nullptr;
    };
    const auto stageVrr = [&](bool vrr) {
      if (vrrSupported) {
        wlr_output_state_set_adaptive_sync_enabled(&state, vrr);
      }
    };
    const GammaTransitionOps gammaOps{
        .clear = [&] { wlr_output_state_set_color_transform(&state, nullptr); },
        .apply =
            [&] {
              wlr_gamma_control_v1* control =
                  wlr_gamma_control_manager_v1_get_control(m_server->gammaManager(), m_output);
              if (wlr_gamma_control_v1_apply(control, &state)) {
                return true;
              }
              if (control != nullptr) {
                wlr_gamma_control_v1_send_failed_and_destroy(control);
              }
              return false;
            },
    };

    // wlroots writes max bpc only in commits that allow a modeset, and the kernel may require one to change
    // colorspace or to switch HDR on or off.
    const auto allowModesetForColorChange = [&](uint32_t fmt, bool hdr) {
      if (colorChangeNeedsModeset(*m_output, fmt, hdr)) {
        state.allow_reconfiguration = true;
      }
    };

    const auto stageHdr = [&](uint32_t fmt, bool vrr) -> bool {
      if (!isPrimaryFormat(fmt)) {
        return false;
      }
      stageVrr(vrr);
      (void)stageGammaForOutputMode(GammaOutputMode::Hdr, gammaOps);
      wlr_output_state_set_image_description(&state, &hdrDescription);
      wlr_output_state_set_render_format(&state, fmt);
      allowModesetForColorChange(fmt, true);
      return true;
    };

    const auto stageSdr = [&](uint32_t fmt, bool vrr) -> bool {
      if (fmt != DRM_FORMAT_XRGB8888 && !isPrimaryFormat(fmt)) {
        return false;
      }
      stageVrr(vrr);
      (void)stageGammaForOutputMode(GammaOutputMode::Sdr, gammaOps);
      wlr_output_state_set_render_format(&state, fmt);
      allowModesetForColorChange(fmt, false);
      return true;
    };

    // Run the format sequence, retrying with the preferred mode on failure.
    bool anyCommitted = false;
    bool usedModeFallback = false;
    std::string_view pendingHdrFail = earlyHdrFail;
    std::string_view pendingSdr10Fail;
    bool hdrRejected = !earlyHdrFail.empty();

    if (enabled) {
      const FormatSequenceParams seqParams{
          .hdrRequested = hdrRequested,
          .imageDescAvailable = imageDescAvailable,
          .hdrWasActive = hdrWasActive,
          .currentRenderFormat = m_output->render_format,
          .bitDepth = bitDepth,
          .tryVrrOn = tryVrrOn,
          .configuredModeSpec = stageGeometry ? configuredModeSpec : nullptr,
          .preferredMode = stageGeometry ? preferredFallbackMode(m_output, stagedMode) : nullptr,
          .keptLiveMode = keptLiveMode,
          .modeFallbackAlreadyWarned = m_modeFallbackWarned,
          .vrrDroppedTier = m_vrrDroppedTier,
          .earlyHdrFail = earlyHdrFail,
      };

      const auto commitStagedState = [&] -> FormatCommitResult {
        const bool targetHdr = state.image_description != nullptr;
        wlr_scene_output_set_sdr_white_level(m_sceneOutput, targetHdr ? sdrWhite() : 0.0F);
        wlr_damage_ring_add_whole(&m_sceneOutput->damage_ring);
        // The cache may need a new size, format or SDR curve; re-render it in this frame.
        markBlurBackgroundDirty();

        wlr_output_state frameState{};
        wlr_output_state_init(&frameState);
        if (!wlr_output_state_copy(&frameState, &state)) {
          wlr_output_state_finish(&frameState);
          return FormatCommitResult::Retry;
        }

        wlr_scene_rect* secureMask = nullptr;
        const bool unbound = wlr_output_layout_get(m_server->outputLayout(), m_output) == nullptr;
        if (stageGeometry && (m_server->sessionLocked() || unbound)) {
          // An unbound scene output still samples the scene origin, and a
          // locked geometry change can outgrow the permanent blank until the
          // layout callback resizes it. Render this configured frame through
          // a temporary opaque mask so neither path exposes unrelated content.
          secureMask = createConfiguredFrameMask(frameState);
          if (secureMask == nullptr) {
            wlr_output_state_finish(&frameState);
            return FormatCommitResult::Retry;
          }
        }

        const int captureLocks = externalRenderLocks();
        wlr_scene_output_state_options sceneOptions{};
        sceneOptions.capture_sdr = targetHdr && captureLocks > 0;
        sceneOptions.effect_capture_pending = effectCapturePending(captureLocks);
        sceneOptions.capture_exclusion = captureExclusionPending(captureLocks);
        m_effectCaptureBuilt = sceneOptions.effect_capture_pending || sceneOptions.capture_exclusion;

        const RenderedStateCommitResult commitResult = commitRenderedState(
            frameState,
            [&](wlr_output_state& pending) {
              return wlr_scene_output_build_state(m_sceneOutput, &pending, &sceneOptions);
            },
            [&](const wlr_output_state& pending) {
              SceneCommit observation(*this, pending);
              return wlr_output_commit_state(m_output, &pending);
            }
        );
        if (secureMask != nullptr) {
          wlr_scene_node_destroy(&secureMask->node);
        }
        const bool commitAttempted = commitResult == RenderedStateCommitResult::Committed
            || commitResult == RenderedStateCommitResult::CommitFailed;
        const bool commitOk = commitResult == RenderedStateCommitResult::Committed;
        if (commitResult == RenderedStateCommitResult::MissingBuffer) {
          kLog.error("output '{}': configured scene state has no buffer", m_output->name);
        }
        const bool recoveringFromFailedCommit = m_tearingRecovery.regularCommitPending();
        if (commitAttempted) {
          m_tearingRecovery.recordCommit(false, commitOk);
        }
        if (commitOk) {
          m_lastCommitTearing = false;
          m_trackingPresentation = true;
          m_trackedPresentationCommitSeq = m_output->commit_seq;
          m_lastPresentationPresented.reset();
          m_lastPresentationFlags.reset();
          if (recoveringFromFailedCommit && !m_tearingRecovery.regularCommitPending()) {
            m_tearingFallbackReason = "recovered with regular page flip";
          }
          if (SessionLock* lock = m_server->sessionLock()) {
            lock->handleOutputCommit(*this, m_output->commit_seq);
          }
        }
        wlr_output_state_finish(&frameState);
        switch (commitResult) {
        case RenderedStateCommitResult::Committed:
          return FormatCommitResult::Committed;
        case RenderedStateCommitResult::CommitFailed:
          return FormatCommitResult::Rejected;
        case RenderedStateCommitResult::BuildFailed:
        case RenderedStateCommitResult::MissingBuffer:
          return FormatCommitResult::Retry;
        }
        return FormatCommitResult::Retry;
      };

      const FormatSequenceOps seqOps{
          .stageSdr = stageSdr,
          .stageHdr = stageHdr,
          .test =
              [&] {
                // A kept live mode leaves wlroots nothing to change, so it skips the KMS test unless a buffer is sent.
                if (keptLiveMode != nullptr
                    && !wlr_output_configure_primary_swapchain(m_output, &state, &m_output->swapchain)) {
                  return false;
                }
                return wlr_output_test_state(m_output, &state);
              },
          .commit = commitStagedState,
          .clearImageDescription = [&] { wlr_output_state_set_image_description(&state, nullptr); },
          .stageMode = [&](wlr_output_mode* mode) { wlr_output_state_set_mode(&state, mode); },
          .warnModeFallback =
              [&](std::string_view requested, const wlr_output_mode& fallback) {
                kLog.warn(
                    "output '{}': configured mode {} could not be applied, using preferred mode "
                    "{}x{}@{}mHz",
                    m_output->name, requested, fallback.width, fallback.height, fallback.refresh
                );
              },
          .warnVrrDropped =
              [&](FormatTier tier) {
                switch (tier) {
                case FormatTier::Hdr:
                  kLog.warn("output '{}': HDR is incompatible with VRR, keeping VRR disabled", m_output->name);
                  break;
                case FormatTier::Sdr10:
                  kLog.warn("output '{}': 10-bit SDR is incompatible with VRR, keeping VRR disabled", m_output->name);
                  break;
                case FormatTier::Sdr8:
                  kLog.warn(
                      "output '{}': configured state commit failed with VRR enabled, keeping VRR disabled",
                      m_output->name
                  );
                  break;
                }
              },
      };

      const FormatSequenceResult seq = runFormatSequence(seqParams, seqOps);
      anyCommitted = seq.committed;
      usedModeFallback = seq.usedModeFallback;
      if (seq.usedLiveModeRetry) {
        kLog.info(
            "output '{}': backend rejected keeping live mode {}x{}@{}mHz, retried with a modeset", m_output->name,
            keptLiveMode->width, keptLiveMode->height, keptLiveMode->refresh
        );
      }
      if (seq.modeFallbackWarnedNow) {
        m_modeFallbackWarned = true;
      }
      if (seq.committed) {
        m_vrrDroppedTier = seq.vrrDropped ? std::optional(seq.committedTier) : std::nullopt;
        if (seq.committedTier == FormatTier::Hdr) {
          kLog.info(
              "output '{}': selected HDR render format {}", m_output->name, tenBitFormatName(seq.committedFormat)
          );
        } else if (seq.committedTier == FormatTier::Sdr10) {
          kLog.info(
              "output '{}': selected 10-bit SDR render format {}", m_output->name, tenBitFormatName(seq.committedFormat)
          );
        }
      }
      pendingHdrFail = seq.hdrFail;
      pendingSdr10Fail = seq.sdr10Fail;
      hdrRejected = hdrRequested && !seq.retry && !seq.hdrFail.empty();
    } else {
      if (!hdrRequested && hdrWasActive) {
        wlr_output_state_set_image_description(&state, nullptr);
        wlr_output_state_set_render_format(&state, DRM_FORMAT_XRGB8888);
      }
      anyCommitted = wlr_output_commit_state(m_output, &state);
    }

    wlr_output_state_finish(&state);
    m_hdrTransition.recordCommit(enabled, hdrRequested, anyCommitted);
    if (hdrRejected) {
      m_hdrAvailable = false;
    }
    if (!anyCommitted) {
      // A failed candidate may have prepared the scene for the requested
      // transfer function. Keep the renderer aligned with the live output.
      updateSceneSdrWhite();
      markBlurBackgroundDirty();
      m_server->updateColorPreferences();
      kLog.error("output '{}': failed to commit configured state", m_output->name);
      return false;
    }
    if (stageGeometry && !usedModeFallback) {
      m_modeFallbackWarned = false;
    }
    if (enabled && scaleStaged) {
      m_appliedConfiguredScale = configuredScale.has_value();
    }
    if (enabled) {
      // Every successful enabled-state commit above staged either an HDR bypass
      // or the latest SDR gamma table.
      m_gammaDirty = false;
    }
    const bool hdrIsActive = hdrActive();
    if (hdrIsActive) {
      m_hdrAvailable = true;
      setHdrFallbackReason({});
    } else {
      if (!hdrRequested) {
        setHdrFallbackReason({});
      } else if (enabled) {
        if (!pendingHdrFail.empty()) {
          m_hdrAvailable = false;
        }
        setHdrFallbackReason(pendingHdrFail);
      }
    }
    if (!enabled || bitDepthActive() || hdrIsActive || bitDepth != 10) {
      setBitDepthFallbackReason({});
    } else {
      setBitDepthFallbackReason(pendingSdr10Fail);
    }
    updateSceneSdrWhite();
    m_server->updateIdleInhibit();
    if (enabled) {
      kLog.info(
          "output '{}': applied mode={}x{}@{}mHz scale={} transform={}", m_output->name, m_output->width,
          m_output->height, m_output->refresh, m_output->scale, static_cast<int>(m_output->transform)
      );
    } else if (!desktopEnabled()) {
      const OutputRule* rule = findOutputRule(config(), identity());
      if (rule == nullptr && !outputCanAutoEnable(m_output)) {
        kLog.info(
            "output '{}': not enabled automatically because it has no preferred mode or display identity",
            m_output->name
        );
      } else {
        kLog.info("output '{}': disabled by {}", m_output->name, configuredEnabled() ? "output management" : "config");
      }
    } else {
      kLog.info("output '{}': powered off", m_output->name);
    }
    if (stageGeometry) {
      updateHdrAvailability(hdrRejected);
    }
    m_server->updateColorPreferences();
    return true;
  }

  bool Output::configuredVrrEnabled() const {
    const OutputRule* rule = findOutputRule(config(), identity());
    const VrrMode outputMode = rule != nullptr ? rule->vrr : VrrMode::Disabled;
    const bool fullscreen = hasFullscreenView();

    std::optional<VrrMode> focusedMode;
    bool focusedFullscreen = false;
    if (wlr_surface* surface = m_server->seat()->wlr()->keyboard_state.focused_surface) {
      if (View* view = View::fromSurface(surface); view != nullptr && view->mapped() && view->currentOutput() == this) {
        focusedMode = view->resolvedRules().vrr;
        focusedFullscreen = view->currentFullscreen() || view->scheduledFullscreen();
      }
    }
    return effectiveVrrEnabled(outputMode, fullscreen, focusedMode, focusedFullscreen);
  }

  bool Output::hasFullscreenView(const View* ignored) const {
    const Workspace* workspace = m_workspaceGroup != nullptr ? m_workspaceGroup->active() : nullptr;
    return workspace != nullptr && std::ranges::any_of(workspace->allViews(), [ignored](const View* view) {
             return view != ignored && view->mapped() && (view->layoutFullscreen() || view->currentFullscreen());
           });
  }

  bool Output::fullscreenCoversOutput() const {
    const Workspace* workspace = m_workspaceGroup != nullptr ? m_workspaceGroup->active() : nullptr;
    const wlr_box box = layoutBox();
    return workspace != nullptr
        && box.width > 0
        && box.height > 0
        && std::ranges::any_of(workspace->allViews(), [&box](const View* view) {
             const wlr_box& fullscreen = view->presentedBox();
             return view->mapped()
                 && (view->layoutFullscreen() || view->currentFullscreen())
                 && view->presented()
                 && fullscreen.x <= box.x
                 && fullscreen.y <= box.y
                 && fullscreen.x + fullscreen.width >= box.x + box.width
                 && fullscreen.y + fullscreen.height >= box.y + box.height;
           });
  }

  bool Output::autoHdrEligible(const View* view) const {
    if (view == nullptr
        || !view->mapped()
        || !view->onActiveWorkspace()
        || view->currentOutput() != this
        || (!view->layoutFullscreen() && !view->currentFullscreen())) {
      return false;
    }
    return m_server->surfaceTreeHdrDescription(view->rootSurface()) != nullptr;
  }

  View* Output::findAutoHdrCandidate() const {
    const auto candidate =
        std::ranges::find_if(m_server->views(), [this](const auto& view) { return autoHdrEligible(view.get()); });
    return candidate != m_server->views().end() ? candidate->get() : nullptr;
  }

  void Output::updateHdr() {
    const HdrMode mode = hdrMode();
    if (mode == HdrMode::Fullscreen) {
      m_autoHdrOwner = nullptr;
      m_fullscreenHdrRequested = hasFullscreenView();
    } else if (mode == HdrMode::Auto) {
      m_fullscreenHdrRequested = false;
      if (!autoHdrEligible(m_autoHdrOwner)) {
        m_autoHdrOwner = findAutoHdrCandidate();
      }
    } else {
      m_fullscreenHdrRequested = false;
      m_autoHdrOwner = nullptr;
    }

    if (m_hdrTransition.pending(m_output->enabled, hdrRequested())) {
      scheduleFullFrame();
    }
    m_server->updateColorPreferences();
  }

  void Output::forgetHdrView(const View* view) {
    if (hdrMode() == HdrMode::Fullscreen && !hasFullscreenView(view)) {
      m_fullscreenHdrRequested = false;
    }
    if (m_autoHdrOwner == view) {
      m_autoHdrOwner = nullptr;
    }
    if (m_hdrTransition.pending(m_output->enabled, hdrRequested())) {
      scheduleFullFrame();
    }
    m_server->updateColorPreferences();
  }

  void Output::updateVrr() {
    // wlroots rejects adaptive-sync commits on disabled outputs; nothing to
    // update while the monitor is off.
    if (!m_output->adaptive_sync_supported || !m_output->enabled) {
      return;
    }
    const bool enabled = configuredVrrEnabled();
    const bool currentlyEnabled = m_output->adaptive_sync_status == WLR_OUTPUT_ADAPTIVE_SYNC_ENABLED;
    if (enabled == currentlyEnabled) {
      return;
    }

    wlr_output_state state{};
    wlr_output_state_init(&state);
    wlr_output_state_set_adaptive_sync_enabled(&state, enabled);
    if (!wlr_output_commit_state(m_output, &state)) {
      kLog.warn("output '{}': failed to {} VRR", m_output->name, enabled ? "enable" : "disable");
    } else {
      kLog.info("output '{}': VRR {}", m_output->name, enabled ? "enabled" : "disabled");
      m_server->updateOutputManagerConfig();
    }
    wlr_output_state_finish(&state);
  }

  wlr_output_layout_output* Output::addToLayout() {
    const OutputRule* rule = findOutputRule(config(), identity());
    if (rule != nullptr && rule->position) {
      return wlr_output_layout_add(m_server->outputLayout(), m_output, (*rule->position)[0], (*rule->position)[1]);
    }
    return wlr_output_layout_add_auto(m_server->outputLayout(), m_output);
  }

  bool Output::applyOutputState() {
    m_runtimeSdrWhite.reset();
    const bool previousDesktopEnabled = m_desktopEnabled;
    const bool previousDpmsOff = m_dpmsOff;
    m_desktopEnabled = configuredEnabled();
    if (m_desktopEnabled != previousDesktopEnabled) {
      // Logical disablement subsumes DPMS. A later logical enable must power
      // the connector on instead of reviving it in a stale DPMS-off state.
      m_dpmsOff = false;
    }
    const HdrMode nextHdrMode = hdrMode();
    if (nextHdrMode == HdrMode::Auto) {
      m_fullscreenHdrRequested = false;
      if (!autoHdrEligible(m_autoHdrOwner)) {
        m_autoHdrOwner = findAutoHdrCandidate();
      }
    } else if (nextHdrMode == HdrMode::Fullscreen) {
      m_autoHdrOwner = nullptr;
      m_fullscreenHdrRequested = hasFullscreenView();
    } else {
      m_autoHdrOwner = nullptr;
      m_fullscreenHdrRequested = false;
    }
    if (!applyConfiguredState()) {
      m_desktopEnabled = previousDesktopEnabled;
      m_dpmsOff = previousDpmsOff;
      return false;
    }
    if (desktopEnabled()) {
      wlr_output_layout_output* layoutOutput = addToLayout();
      // Re-bind the scene output after a disable removed it from the layout.
      // No-op while it is still bound.
      wlr_scene_output_layout_add_output(m_server->sceneLayout(), layoutOutput, m_sceneOutput);
    } else {
      wlr_output_layout_remove(m_server->outputLayout(), m_output);
    }
    applyOutputEffects();
    markDirty(Dirty::LayerArrange | Dirty::Banner);
    if (m_server->sessionLocked()) {
      m_server->updateLockBlank();
    }
    if (SessionLock* lock = m_server->sessionLock()) {
      lock->handleOutputStateChanged(*this);
    }
    wlr_output_schedule_frame(m_output);
    return true;
  }

  void Output::adoptOutputManagerEnabled(bool enabled) {
    const bool wasDesktopEnabled = m_desktopEnabled;
    m_desktopEnabled = enabled;
    if (!enabled || !wasDesktopEnabled) {
      // A logical disable is not a pending DPMS request. Re-enabling through
      // output management must therefore bring the connector up.
      m_dpmsOff = false;
    }
  }

  void Output::applyOutputManagerLayout(int x, int y) {
    if (desktopEnabled()) {
      wlr_output_layout_output* layoutOutput = wlr_output_layout_add(m_server->outputLayout(), m_output, x, y);
      wlr_scene_output_layout_add_output(m_server->sceneLayout(), layoutOutput, m_sceneOutput);
    } else {
      wlr_output_layout_remove(m_server->outputLayout(), m_output);
    }
    applyOutputEffects();
    handleExternalConfigChange();
    kLog.info(
        "output '{}': {} by output management, power {}", m_output->name, desktopEnabled() ? "enabled" : "disabled",
        m_output->enabled ? "on" : "off"
    );
    if (SessionLock* lock = m_server->sessionLock()) {
      lock->handleOutputStateChanged(*this);
    }
  }

  bool Output::setPowered(bool powered) {
    if (!desktopEnabled()) {
      return false;
    }
    const bool dpmsOff = !powered;
    if (m_dpmsOff == dpmsOff) {
      return true;
    }

    const bool previous = m_dpmsOff;
    m_dpmsOff = dpmsOff;
    if (!applyConfiguredState()) {
      m_dpmsOff = previous;
      return false;
    }
    applyOutputEffects();

    if (powered) {
      m_gammaDirty = true;
      markDirty(Dirty::LayerArrange | Dirty::Banner | Dirty::Backdrop);
      if (m_server->sessionLocked()) {
        m_server->updateLockBlank();
      }
      wlr_output_schedule_frame(m_output);
      m_server->scheduleDisplacedViewRestore();
    }
    if (SessionLock* lock = m_server->sessionLock()) {
      lock->handleOutputStateChanged(*this);
    }
    m_server->updateOutputManagerConfig();
    return true;
  }

#ifdef UMBRIEL_HARNESS
  void Output::setSyntheticPlaneCursorForTest(
      double x, double y, bool visible, std::uintptr_t image, int width, int height, int hotspotX, int hotspotY
  ) {
    m_syntheticPlaneCursor = CursorPlaneState{
        .valid = false,
        .enabled = true,
        .visible = visible,
        .x = x,
        .y = y,
        .width = width,
        .height = height,
        .hotspot_x = hotspotX,
        .hotspot_y = hotspotY,
        .image = reinterpret_cast<const void*>(image),
    };
  }
#endif

  bool Output::paceCursorPlaneTransition() {
    if (m_output == nullptr || m_sceneOutput == nullptr) {
      return false;
    }
    const wlr_output_cursor* plane = m_output->hardware_cursor;
    CursorPlaneState now{
        .valid = false,
        .enabled = plane != nullptr && plane->enabled,
        .visible = plane != nullptr && plane->visible,
        .x = plane != nullptr ? plane->x : 0,
        .y = plane != nullptr ? plane->y : 0,
        .width = plane != nullptr ? static_cast<int>(plane->width) : 0,
        .height = plane != nullptr ? static_cast<int>(plane->height) : 0,
        .hotspot_x = plane != nullptr ? plane->hotspot_x : 0,
        .hotspot_y = plane != nullptr ? plane->hotspot_y : 0,
        .image = plane != nullptr ? m_output->cursor_front_buffer : nullptr,
    };
#ifdef UMBRIEL_HARNESS
    if (m_syntheticPlaneCursor.has_value()) {
      now = *m_syntheticPlaneCursor;
    }
#endif
    // The snapshot advances on every sample, consumer or not: a client that
    // starts recording later must diff from where the cursor is now, not from
    // wherever it was when the last session ended.
    CursorPlaneState previous;
    if (!cursorPlaneAdvance(&m_lastCursorPlane, now, &previous)) {
      return false;
    }
    // Past this point the transition is real, so the sweep over live capture
    // sessions is worth its cost; on a stationary cursor it never runs.
    if (!needsCursorCapturePacing()) {
      return false;
    }
    const CursorPlaneDamage damage = cursorPlaneDamageFor(&previous, &now);
    if (damage.has_leave) {
      wlr_scene_output_damage_box(m_sceneOutput, &damage.leave_box);
    }
    if (damage.has_enter) {
      wlr_scene_output_damage_box(m_sceneOutput, &damage.enter_box);
    }
    return true;
  }

  bool Output::needsCursorCapturePacing() const {
    if (m_output == nullptr) {
      return false;
    }
    // Only an output whose capture source carries a live cursor-metadata
    // session is paced. The session bookkeeping and the source mapping live
    // in Server; screencopy never registers there.
    return m_server->hasCopyCaptureFor(m_output);
  }

  void Output::applyCursorConfig() {
    const bool lockSoftwareCursor = !config().input.cursor.hardwareCursor;
    if (lockSoftwareCursor == m_softwareCursorLocked) {
      return;
    }
    wlr_output_lock_software_cursors(m_output, lockSoftwareCursor);
    m_softwareCursorLocked = lockSoftwareCursor;
    // Locking drops the plane and unlocking brings it back wherever the cursor
    // happens to be; neither is a transition a recorder should see, so discard
    // the snapshot and let the next sample re-seed it.
    m_lastCursorPlane = {};
    wlr_output_schedule_frame(m_output);
  }

  void Output::handleExternalConfigChange() {
    // Mode changes can drop the DRM gamma LUT; re-apply on the next frame.
    m_gammaDirty = true;
    updateHdrAvailability();
    m_server->updateColorPreferences();
    markDirty(Dirty::LayerArrange);
    wlr_output_schedule_frame(m_output);
  }

  void Output::notifySurfaceScaleIter(wlr_surface* surface, int /*sx*/, int /*sy*/, void* data) {
    const auto* self = static_cast<Output*>(data);
    if (surface == nullptr || self == nullptr || self->m_output == nullptr) {
      return;
    }
    wlr_fractional_scale_v1_notify_scale(surface, self->m_output->scale);
    wlr_surface_set_preferred_buffer_scale(surface, static_cast<int32_t>(std::ceil(self->m_output->scale)));
  }

  Output::~Output() {
    if (m_backgroundPopupUpdate.link.next != nullptr) {
      wl_list_remove(&m_backgroundPopupUpdate.link);
      m_backgroundPopupUpdate.link.next = nullptr;
    }
    if (m_backgroundUpdate.link.next != nullptr) {
      wl_list_remove(&m_backgroundUpdate.link);
      m_backgroundUpdate.link.next = nullptr;
    }
    if (m_frameRetryTimer != nullptr) {
      wl_event_source_remove(m_frameRetryTimer);
      m_frameRetryTimer = nullptr;
    }
    if (m_effectFrameTimer != nullptr) {
      wl_event_source_remove(m_effectFrameTimer);
      m_effectFrameTimer = nullptr;
    }
    if (m_directScanoutTimer != nullptr) {
      wl_event_source_remove(m_directScanoutTimer);
      m_directScanoutTimer = nullptr;
    }
    if (m_animationRenderLocked) {
      wlr_output_lock_attach_render(m_output, false);
      m_animationRenderLocked = false;
    }
    if (m_softwareCursorLocked) {
      wlr_output_lock_software_cursors(m_output, false);
      m_softwareCursorLocked = false;
    }
    if (m_output != nullptr && m_output->data == this) {
      m_output->data = nullptr;
    }
    if (m_frame.link.next != nullptr) {
      wl_list_remove(&m_frame.link);
      wl_list_remove(&m_requestState.link);
      wl_list_remove(&m_present.link);
      wl_list_remove(&m_destroy.link);
    }
    // Workspace destructors reparent leftover views onto the server trees, so the group has to go before the roots it
    // hangs under.
    m_workspaceGroup.reset();
    for (wlr_scene_tree*& layerTree : m_layerTrees) {
      if (layerTree != nullptr) {
        wlr_scene_node_destroy(&layerTree->node);
        layerTree = nullptr;
      }
    }
    for (wlr_scene_tree*& popupTree : m_layerPopupTrees) {
      if (popupTree != nullptr) {
        wlr_scene_node_destroy(&popupTree->node);
        popupTree = nullptr;
      }
    }
    if (m_optimizedBlur != nullptr) {
      wlr_scene_node_destroy(&m_optimizedBlur->node);
      m_optimizedBlur = nullptr;
    }
    for (wlr_scene_tree* root : {m_viewRoot, m_fullscreenRoot, m_pinnedRoot}) {
      if (root != nullptr) {
        wlr_scene_node_destroy(&root->node);
      }
    }
    m_viewRoot = nullptr;
    m_fullscreenRoot = nullptr;
    m_pinnedRoot = nullptr;
  }

  wlr_scene_tree* Output::layerTree(uint32_t layer) const {
    if (layer >= kLayerCount) {
      return m_layerTrees[ZWLR_LAYER_SHELL_V1_LAYER_TOP];
    }
    return m_layerTrees[layer];
  }

  wlr_scene_tree* Output::layerPopupTree(uint32_t layer) const {
    assert(layer < kLayerCount);
    return m_layerPopupTrees[layer];
  }

  void Output::arrangeLayer(wlr_scene_tree* tree, const wlr_box* fullArea, wlr_box* usableArea, bool exclusive) {
    wlr_scene_node* node = nullptr;
    wl_list_for_each(node, &tree->children, link) {
      SceneNode* sceneNode = sceneNodeFrom(node->data);
      if (sceneNode == nullptr || sceneNode->kind != SceneNodeKind::LayerSurface) {
        continue;
      }
      auto* layerSurface = static_cast<LayerSurface*>(sceneNode);
      if (layerSurface->scene() == nullptr || layerSurface->arrangingOut()) {
        continue;
      }
      wlr_layer_surface_v1* surface = layerSurface->layerSurface();
      if (surface == nullptr || !surface->initialized) {
        continue;
      }
      // Only exclusive_zone > 0 participates in the exclusive pass.
      if ((surface->current.exclusive_zone > 0) != exclusive) {
        continue;
      }
      wlr_scene_layer_surface_v1_configure(layerSurface->scene(), fullArea, usableArea);
    }
  }

  void Output::arrangeLayers() {
    wlr_box outputArea{};
    wlr_output_effective_resolution(m_output, &outputArea.width, &outputArea.height);
    if (outputArea.width <= 0 || outputArea.height <= 0) {
      return;
    }

    int physicalWidth = 0;
    int physicalHeight = 0;
    wlr_output_transformed_resolution(m_output, &physicalWidth, &physicalHeight);
    const wlr_box layerArea = {
        .x = 0,
        .y = 0,
        .width = static_cast<int>(std::ceil(static_cast<double>(physicalWidth) / m_output->scale)),
        .height = static_cast<int>(std::ceil(static_cast<double>(physicalHeight) / m_output->scale)),
    };
    wlr_box usableArea = outputArea;

    // Exclusive first, overlay down to background so higher layers win the zone.
    static constexpr uint32_t kExclusiveOrder[] = {
        ZWLR_LAYER_SHELL_V1_LAYER_OVERLAY,
        ZWLR_LAYER_SHELL_V1_LAYER_TOP,
        ZWLR_LAYER_SHELL_V1_LAYER_BOTTOM,
        ZWLR_LAYER_SHELL_V1_LAYER_BACKGROUND,
    };
    for (uint32_t layer : kExclusiveOrder) {
      arrangeLayer(m_layerTrees[layer], &layerArea, &usableArea, true);
    }
    for (uint32_t layer : kExclusiveOrder) {
      arrangeLayer(m_layerTrees[layer], &layerArea, &usableArea, false);
    }
    updateOptimizedBlur(outputArea);

    // Layer trees are output-local; pin them to the scene-output origin.
    for (auto& m_layerTree : m_layerTrees) {
      wlr_scene_node_set_position(&m_layerTree->node, m_sceneOutput->x, m_sceneOutput->y);
    }
    for (auto* popupTree : m_layerPopupTrees) {
      wlr_scene_node_set_position(&popupTree->node, m_sceneOutput->x, m_sceneOutput->y);
    }

    // Content roots are clipped to this output's layout box, not repositioned: views are laid out in layout
    // coordinates. A disabled output never gets here (outputArea is empty above), and its workspaces have already been
    // evacuated, so the stale clip it keeps has nothing under it.
    const wlr_box outputBox = {
        .x = m_sceneOutput->x,
        .y = m_sceneOutput->y,
        .width = outputArea.width,
        .height = outputArea.height,
    };
    for (wlr_scene_tree* root : {m_viewRoot, m_fullscreenRoot, m_pinnedRoot}) {
      wlr_scene_tree_set_clip(root, &outputBox);
    }

    // Keep the usable area output-local so layout moves take effect immediately,
    // without waiting for the next layer arrangement.
    m_localUsableArea = usableArea;
    m_arrangedLayoutX = m_sceneOutput->x;
    m_arrangedLayoutY = m_sceneOutput->y;

    if (ScratchpadManager* scratchpad = m_server->scratchpadManager()) {
      scratchpad->refreshOutputGeometry(this);
    }

    // Layer geometry and the usable area settle here.
    m_server->scheduleIpcLayersEvent();
    m_server->scheduleIpcOutputsEvent();
    const wlr_box layoutUsableArea = this->usableArea();
    // Arrangement runs on every layer commit; only a changed result is worth a line.
    const wlr_box& logged = m_loggedUsableArea;
    if (layoutUsableArea.x != logged.x
        || layoutUsableArea.y != logged.y
        || layoutUsableArea.width != logged.width
        || layoutUsableArea.height != logged.height) {
      m_loggedUsableArea = layoutUsableArea;
      kLog.debug(
          "{} usable={}x{}+{}+{}", m_output->name, layoutUsableArea.width, layoutUsableArea.height, layoutUsableArea.x,
          layoutUsableArea.y
      );
    }
    if (m_workspaceGroup != nullptr && m_workspaceGroup->active() != nullptr) {
      m_workspaceGroup->active()->markArrange(false);
    }
  }

  void Output::updateOptimizedBlur(const wlr_box& fullArea) {
    const auto& blur = config().appearance.blur;
    if (!blur.enabled || !config().optimizedBlurNeeded()) {
      if (m_optimizedBlur != nullptr) {
        wlr_scene_node_destroy(&m_optimizedBlur->node);
        m_optimizedBlur = nullptr;
      }
      if (!blur.enabled) {
        fx_renderer_clear_output_effect_buffers(m_output);
      }
      return;
    }

    if (m_optimizedBlur == nullptr) {
      m_optimizedBlur = wlr_scene_optimized_blur_create(
          m_server->shellLayerTree(ZWLR_LAYER_SHELL_V1_LAYER_BACKGROUND), fullArea.width, fullArea.height
      );
      if (m_optimizedBlur == nullptr) {
        return;
      }
    }

    const bool changed = m_optimizedBlur->node.x != m_sceneOutput->x
        || m_optimizedBlur->node.y != m_sceneOutput->y
        || m_optimizedBlur->width != fullArea.width
        || m_optimizedBlur->height != fullArea.height;
    wlr_scene_node_set_enabled(&m_optimizedBlur->node, true);
    wlr_scene_node_set_position(&m_optimizedBlur->node, m_sceneOutput->x, m_sceneOutput->y);
    wlr_scene_optimized_blur_set_size(m_optimizedBlur, fullArea.width, fullArea.height);
    if (changed) {
      wlr_scene_optimized_blur_mark_dirty(m_optimizedBlur);
    }
  }

  void Output::markBlurBackgroundDirty() {
    if (m_optimizedBlur != nullptr && !m_optimizedBlur->dirty) {
      wlr_scene_optimized_blur_mark_dirty(m_optimizedBlur);
    }
  }

  void Output::onGammaChanged(wlr_gamma_control_v1* control) {
    updateSceneHdrWhitePoint(control);
    if (hdrActive()) {
      // The scene applies the requested white point before PQ encoding.
      // Keep the full table for SDR instead of applying it to PQ values.
      m_gammaDirty = false;
      return;
    }
    // DRM gamma LUT upload is expensive; apply once on change, not every frame.
    m_gammaDirty = true;
    wlr_output_schedule_frame(m_output);
  }

  void Output::onFrame(wl_listener* listener, void* /*data*/) {
    Output* self;
    self = wl_container_of(listener, self, m_frame);
    self->handleFrame();
  }

  void Output::onBackgroundUpdate(wl_listener* listener, void* /*data*/) {
    Output* self;
    self = wl_container_of(listener, self, m_backgroundUpdate);
    self->markBlurBackgroundDirty();
  }

  void Output::onBackgroundPopupUpdate(wl_listener* listener, void* /*data*/) {
    Output* self = wl_container_of(listener, self, m_backgroundPopupUpdate); // NOLINT(modernize-use-auto)
    self->markBlurBackgroundDirty();
  }

  void Output::onRequestState(wl_listener* listener, void* data) {
    Output* self;
    self = wl_container_of(listener, self, m_requestState);
    self->handleRequestState(data);
  }

  void Output::onPresent(wl_listener* listener, void* data) {
    Output* self;
    self = wl_container_of(listener, self, m_present);
    self->handlePresent(data);
  }

  void Output::onDestroy(wl_listener* listener, void* /*data*/) {
    Output* self;
    self = wl_container_of(listener, self, m_destroy);
    self->handleDestroy();
  }

  int Output::onFrameRetryTimer(void* data) {
    auto* self = static_cast<Output*>(data);
    if (outputFrameAllowed(self->m_server->stopping(), self->m_server->session())) {
      wlr_output_schedule_frame(self->m_output);
    }
    return 0;
  }

  Output::SceneCommit::SceneCommit(Output& output, const wlr_output_state& state) : m_output(output) {
    wl_list_init(&m_commit.link);
    if ((state.committed & WLR_OUTPUT_STATE_BUFFER) == 0 || state.buffer == nullptr) {
      return;
    }
    // The submitted state owns the buffer for this scope. Snapshot the decision before commit callbacks can change
    // the scene, and avoid attributing a later cursor or metadata commit to an earlier failed scene build.
    m_buffer = state.buffer;
    m_state = output.builtDirectScanout();
    m_commit.notify = onCommit;
    wl_signal_add(&output.m_output->events.commit, &m_commit);
  }

  Output::SceneCommit::~SceneCommit() { wl_list_remove(&m_commit.link); }

  void Output::SceneCommit::onCommit(wl_listener* listener, void* data) {
    SceneCommit* self;
    self = wl_container_of(listener, self, m_commit);
    const auto* event = static_cast<wlr_output_event_commit*>(data);
    if ((event->state->committed & WLR_OUTPUT_STATE_BUFFER) == 0 || event->state->buffer != self->m_buffer) {
      return;
    }
    self->m_output.recordDirectScanout(self->m_state, event->output->commit_seq);
    // A synchronous backend attempt can account for this built buffer only once.
    wl_list_remove(&self->m_commit.link);
    wl_list_init(&self->m_commit.link);
  }

  DirectScanoutState Output::builtDirectScanout() const {
    const wlr_scene_direct_scanout_status status = wlr_scene_output_direct_scanout_status(m_sceneOutput);
    DirectScanoutState state;
    state.active = status == WLR_SCENE_DIRECT_SCANOUT_ACTIVE;
    state.reason = directScanoutReason(status);
    if (wlr_scene_buffer* buffer = wlr_scene_output_direct_scanout_buffer(m_sceneOutput)) {
      wlr_scene_surface* sceneSurface = wlr_scene_surface_try_from_buffer(buffer);
      const View* view =
          sceneSurface != nullptr ? View::fromSurface(wlr_surface_get_root_surface(sceneSurface->surface)) : nullptr;
      if (view != nullptr) {
        state.windowId = view->extForeignIdentifier() != nullptr ? view->extForeignIdentifier() : "";
        state.appId = view->appId() != nullptr ? view->appId() : "";
        state.title = view->title() != nullptr ? view->title() : "";
      }
    }
    return state;
  }

  void Output::recordDirectScanout(const DirectScanoutState& state, uint32_t commitSeq) {
    // Restarting the wait on every change settles only a state that held for the whole interval.
    const DirectScanoutTracker::Observation observation = m_directScanout.recordCommit(state, commitSeq);
    if (observation != DirectScanoutTracker::Observation::Unchanged && m_directScanoutTimer != nullptr) {
      const bool pending = observation == DirectScanoutTracker::Observation::Pending;
      wl_event_source_timer_update(m_directScanoutTimer, pending ? DirectScanoutTracker::kSettleMs : 0);
    }
  }

  int Output::onDirectScanoutTimer(void* data) {
    auto* self = static_cast<Output*>(data);
    if (!self->m_directScanout.settle()) {
      return 0;
    }
    const DirectScanoutState& state = self->m_directScanout.settled();
    if (self->m_directScanout.settledChangeIsNotable()) {
      if (state.active) {
        kLog.info(
            "output '{}': direct scanout on ({} \"{}\")", self->m_output->name,
            state.appId.empty() ? "unknown" : state.appId, state.title
        );
      } else {
        kLog.info("output '{}': direct scanout off ({})", self->m_output->name, state.reason);
      }
    }
    self->m_server->scheduleIpcOutputsEvent();
    return 0;
  }

  void Output::armFrameRetry() {
    if (m_frameRetryTimer != nullptr && outputFrameAllowed(m_server->stopping(), m_server->session())) {
      wl_event_source_timer_update(m_frameRetryTimer, kFrameRetryDelayMs);
    }
  }

  int Output::onEffectFrameTimer(void* data) {
    auto* output = static_cast<Output*>(data);
    output->m_effectFrameArmed = false;
    output->m_effectFrameDue = true;
    wlr_output_schedule_frame(output->m_output);
    return 0;
  }

  void Output::armEffectFrame(uint64_t nowMsec) {
    const uint64_t delay = effectFrameDelayMs(config().effects.maxFps, nowMsec, m_lastEffectFrameMsec);
    if (delay == 0) {
      disarmEffectFrame();
      m_effectFrameDue = true;
      wlr_output_schedule_frame(m_output);
      return;
    }
    if (m_effectFrameArmed) {
      return;
    }
    if (m_effectFrameTimer == nullptr) {
      m_effectFrameTimer =
          wl_event_loop_add_timer(wl_display_get_event_loop(m_server->display()), onEffectFrameTimer, this);
    }
    wl_event_source_timer_update(m_effectFrameTimer, static_cast<int>(delay));
    m_effectFrameArmed = true;
  }

  void Output::disarmEffectFrame() {
    if (m_effectFrameArmed) {
      wl_event_source_timer_update(m_effectFrameTimer, 0);
      m_effectFrameArmed = false;
    }
  }

  void Output::applyMode(int width, int height, int refreshMHz) {
    if (width <= 0 || height <= 0) {
      return;
    }

    wlr_output_state state{};
    wlr_output_state_init(&state);
    wlr_output_state_set_custom_mode(&state, width, height, refreshMHz);
    if (!wlr_output_commit_state(m_output, &state)) {
      wlr_log(WLR_ERROR, "failed to commit output mode %dx%d for '%s'", width, height, m_output->name);
    } else {
      // Mode changes can drop the DRM gamma LUT; re-apply on the next frame.
      m_gammaDirty = true;
      updateHdrAvailability();
      m_server->updateColorPreferences();
    }
    wlr_output_state_finish(&state);
    markDirty(Dirty::LayerArrange | Dirty::Banner | Dirty::Backdrop);
    if (m_server->sessionLocked()) {
      m_server->updateLockBlank();
    }
    if (SessionLock* lock = m_server->sessionLock()) {
      lock->handleOutputStateChanged(*this);
    }
    wlr_output_schedule_frame(m_output);
  }

  void Output::scheduleFullFrame() {
    wlr_damage_ring_add_whole(&m_sceneOutput->damage_ring);
    wlr_output_schedule_frame(m_output);
  }

  void Output::markDirty(Dirty what) {
    m_dirty |= what;
    wlr_output_schedule_frame(m_output);
  }

  void Output::flushDirty() {
    UMBRIEL_ZONE("Output::flushDirty");
    // Server-wide chrome is recorded on the Server and flushed by whichever
    // output frames first; each of these is idempotent and cheap.
    Dirty pending = m_dirty | m_server->takeDirty();
    m_dirty = Dirty::None;
    // Order matters: exclusive zones define the usable area, the layout fills
    // it, and the chrome sits over the result.
    if (has(pending, Dirty::LayerArrange)) {
      arrangeLayers();
      // Changing the usable area makes the layout stale, so arrangeLayers marks it, after this set was taken. Take
      // again rather than let that wait a frame; the same holds for anything a later step records for a step further
      // down.
      pending |= m_dirty;
      m_dirty = Dirty::None;
    }
    if (has(pending, Dirty::Layout) && m_workspaceGroup != nullptr) {
      m_workspaceGroup->flushArrange();
    }
    if (has(pending, Dirty::Banner)) {
      m_server->relayoutBanner();
    }
    if (has(pending, Dirty::Backdrop)) {
      m_server->updateBackdrop();
    }
    if (has(pending, Dirty::Cheatsheet)) {
      m_server->relayoutCheatsheet();
    }
    if (has(pending, Dirty::QuitConfirm)) {
      m_server->relayoutQuitConfirm();
    }
  }

  void Output::updateFullscreenStack() {
    if (m_server->sessionLocked() || (m_server->overview() != nullptr && m_server->overview()->active())) {
      return;
    }
    const bool above = fullscreenCoversOutput();
    wlr_scene_tree* parent = above ? m_server->fullscreenTree() : m_server->xdgTree();
    if (m_fullscreenRoot->node.parent != parent) {
      wlr_scene_node_reparent(&m_fullscreenRoot->node, parent);
      if (!above) {
        wlr_scene_node_place_above(&m_fullscreenRoot->node, &m_viewRoot->node);
      }
    }
    if (above != m_fullscreenAboveTopLayer) {
      m_fullscreenAboveTopLayer = above;
      m_server->refreshLayerFocus(this);
    }
  }

  void Output::handleFrame() {
    UMBRIEL_ZONE("Output::handleFrame");
    // A failed DRM commit can immediately queue another frame after logind revokes device access. Stop before that
    // retry loop can keep the final event-loop dispatch alive. A null session belongs to a nested or headless backend
    // and remains renderable.
    if (!outputFrameAllowed(m_server->stopping(), m_server->session())) {
      return;
    }
    const OutputFrameScope frameScope(*m_server);
    if (m_frameRetryTimer != nullptr) {
      wl_event_source_timer_update(m_frameRetryTimer, 0);
    }
    m_handlingFrame = true;

    flushDirty();
    if (m_hasDeferredMode) {
      m_hasDeferredMode = false;
      applyMode(m_deferredWidth, m_deferredHeight, m_deferredRefresh);
    }
    timespec now{};
    clock_gettime(CLOCK_MONOTONIC, &now);
    const uint64_t nowMsec = static_cast<uint64_t>(now.tv_sec) * 1000 + static_cast<uint64_t>(now.tv_nsec) / 1'000'000;
    // A frame is an effect frame when one was asked for, or when an instance here is eligible or an audio change is
    // pending and the max_fps interval has elapsed (a delay of 1 ms is the helper's "due now"), whichever timeline
    // scheduled the frame. The output's own timer supplies the frames nothing else asks for.
    const bool effectFrame = m_effectFrameDue
        || (!m_server->sessionLocked()
            && (effectEligible() > 0 || audioPending())
            && effectFrameDelayMs(config().effects.maxFps, nowMsec, m_lastEffectFrameMsec) <= 1);
    m_effectFrameDue = false;
    if (effectFrame) {
      m_lastEffectFrameMsec = nowMsec;
      disarmEffectFrame();
    }
    // Effect time moves only on effect frames, which caps them at max_fps. It follows the clock while nothing here
    // needs frames of its own, so a new instance starts from now, and while the clock is frozen, so the first frozen
    // frame draws the frozen instant.
    const EffectRegistry& effects = m_server->effects();
    bool stampEffectTime =
        effectFrame || (effectEligible() == 0 && (effects.persistentReferenced() || effects.active()));
#ifdef UMBRIEL_HARNESS
    stampEffectTime = stampEffectTime || m_server->animationClockFrozen();
#endif
    if (stampEffectTime) {
      m_effectSeconds = effects.clockSeconds();
    }
    if (effectFrame) {
      m_effectAudio = effects.audio();
      wlr_scene_output_set_effect_audio(m_sceneOutput, m_effectAudio.data());
    }
    // Sample animations on this output's vblank cadence rather than when the frame event got dispatched, so event-loop
    // latency and other outputs' rendering do not make motion steps uneven.
    const uint64_t nowNs = static_cast<uint64_t>(now.tv_sec) * 1'000'000'000 + static_cast<uint64_t>(now.tv_nsec);
    const uint64_t vblankNs = latestVblankNs(nowNs, m_lastPresentNs, m_refreshNs);
    const uint64_t sampleNs = vblankNs != 0 ? vblankNs : nowNs;
    m_server->tickAnimations(m_server->animationFrameClockMsec(static_cast<double>(sampleNs) / 1e6));
    if (stampEffectTime && m_outputEffectsTimed) {
      applyOutputEffects();
    }

    if (m_workspaceGroup != nullptr) {
      m_workspaceGroup->refreshReveal();
    }
    updateFullscreenStack();
    // Refresh after arrangement and animation so stacking and output transfers are current.
    const auto dimsBehind = [](const auto& rule) { return rule.dimBehind.value_or(0.0) > 0.0; };
    if (std::ranges::any_of(config().windowRules, dimsBehind)) {
      for (const auto& view : m_server->views()) {
        view->updateDimBehind();
      }
    }
    if (std::ranges::any_of(config().layerRules, dimsBehind)) {
      for (const auto& layer : m_server->layerSurfaces()) {
        layer->updateDimBehind();
      }
    }

    // A direct-scanned fullscreen client may stop submitting as soon as it loses focus. On VRR outputs that can leave
    // the first workspace-switch frame waiting on the old client, so the compositor never gets a vblank to advance the
    // slide. Keep animated outputs on the render path until their final composed frame has settled.
    const bool animationsActive = m_server->animationsActiveFor(this);
    // Persistent effects reading time keep an output drawing on their own timer, never through the animation
    // registry: settle, tearing, and the render lock keep their meanings.
    const bool effectsEligible = !m_server->sessionLocked() && effectEligible() > 0;
    if (animationsActive != m_animationRenderLocked) {
      wlr_output_lock_attach_render(m_output, animationsActive);
      m_animationRenderLocked = animationsActive;
    }

    // Keep preferred color descriptions current as output membership and policy change.
    if (ColorManager* colorManager = m_server->colorManager()) {
      colorManager->updatePreferredDescriptions();
    }

    const int externalLocks = externalRenderLocks();
    const bool captureActive = externalLocks > 0;
    View* tearingView = tearingCandidate();
    const bool tearingPolicyRequested = tearingEligible(tearingView);

    bool tearingFrameEligible = tearingPolicyRequested;
    if (!configuredTearingAllowed()) {
      m_tearingFallbackReason.clear();
    } else if (tearingView == nullptr) {
      m_tearingFallbackReason.clear();
    } else if (const std::optional<bool> rule = tearingView->resolvedRules().allowTearing; rule && !*rule) {
      m_tearingFallbackReason.clear();
    } else if (!tearingView->resolvedRules().allowTearing && !clientTearingHintAsync(tearingView)) {
      m_tearingFallbackReason.clear();
    } else if (m_server->sessionLocked()) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "session locked";
    } else if (m_server->overview() != nullptr && m_server->overview()->active()) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "overview active";
    } else if (m_server->configBanner() != nullptr && m_server->configBanner()->visible()) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "configuration banner visible";
    } else if (m_server->cheatsheet() != nullptr && m_server->cheatsheet()->visible()) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "cheatsheet visible";
    } else if (m_server->quitConfirm() != nullptr && m_server->quitConfirm()->visible()) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "quit confirmation visible";
    } else if (animationsActive) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "output animation active";
    } else if (captureActive) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "output capture active";
    } else if (m_tearingRecovery.regularCommitPending()) {
      tearingFrameEligible = false;
      m_tearingFallbackReason = "recovering from failed async commit";
    } else {
      m_tearingFallbackReason.clear();
    }
    const bool requestTearing = m_tearingRecovery.requestTearing(tearingFrameEligible);

    if (m_output->width <= 0 || m_output->height <= 0) {
      // Output not configured yet; no clients can be presenting on it either.
      m_handlingFrame = false;
      return;
    }

    // Render + commit only if the scene actually changed or a gamma upload is pending. All exit paths below MUST reach
    // the unconditional wlr_scene_output_send_frame_done call at the bottom: mailbox/FIFO clients (games via DXVK,
    // video players) block on wl_surface.frame before submitting their next buffer. If we skip frame_done on the
    // "nothing to render" path, they never commit again, damage stays clean, and the output stops producing frames.
    bool commitFailed = false;
    // Sample the plane before the needs_frame test below: a cursor-only move
    // damages nothing else, so this frame is the only commit that can carry
    // the damage. wlroots clears needs_frame on commit, so every mutation
    // since the last commit is diffed here exactly once; the umbrielfx scene's
    // own needs_frame listener is what scheduled this frame for them.
    paceCursorPlaneTransition();
    const bool sceneChanged = wlr_scene_output_needs_frame(m_sceneOutput);
    if (sceneChanged) {
      // Scene motion under a stationary cursor must reach the client before its next press.
      if (Cursor* cursor = m_server->cursor()) {
        cursor->refreshPointerContents(this);
      }
    }
    const bool hdrTransitionPending = m_hdrTransition.pending(m_output->enabled, hdrRequested());
    if (hdrTransitionPending) {
      // Run at the frame boundary, after the previous page flip completed. The
      // configured-state commit builds the scene into the same state as the
      // image-description and render-format switch.
      m_inFrame = true;
      const bool committed = applyConfiguredState(false);
      m_inFrame = false;
      commitFailed = !committed;
      if (committed) {
        if (effectFrame) {
          ++m_effectFrames;
        }
        m_server->updateOutputManagerConfig();
      }
    }
    if (!hdrTransitionPending && (sceneChanged || m_gammaDirty)) {
      m_inFrame = true;
      if (effectFrame) {
        ++m_effectFrames;
      }
      UMBRIEL_ZONE("Output::render");

      wlr_output_state state{};
      wlr_output_state_init(&state);

      bool commitOk = false;
      const int captureLocks = externalLocks;
      wlr_scene_output_state_options sceneOptions{};
      sceneOptions.capture_sdr = hdrActive() && captureLocks > 0;
      sceneOptions.effect_capture_pending = effectCapturePending(captureLocks);
      sceneOptions.capture_exclusion = captureExclusionPending(captureLocks);
      m_effectCaptureBuilt = sceneOptions.effect_capture_pending || sceneOptions.capture_exclusion;
      sceneOptions.require_animation_success = m_workspaceGroup != nullptr && m_workspaceGroup->revealActive();
      if (sceneOptions.require_animation_success) {
        sceneOptions.workspace_from = m_workspaceGroup->revealRoot(false);
        sceneOptions.workspace_to = m_workspaceGroup->revealRoot(true);
      }
      bool built = false;
      {
        UMBRIEL_ZONE("Output::buildState");
        built = wlr_scene_output_build_state(m_sceneOutput, &state, &sceneOptions);
      }
      if (!built && sceneOptions.require_animation_success) {
        // Reject the incomplete frame and resume native slide at the same progress.
        m_workspaceGroup->abandonReveal();
      }
      if (built) {
        // Hardware gamma only (DRM). Nested Wayland has no gamma LUT; leave that alone.
        // Apply only when dirty: uploading the LUT every frame stalls the compositor.
        bool gammaPending = false;
        if (m_gammaDirty) {
          if (hdrActive()) {
            m_gammaDirty = false;
          } else if (wlr_output_get_gamma_size(m_output) > 0) {
            wlr_gamma_control_v1* control =
                wlr_gamma_control_manager_v1_get_control(m_server->gammaManager(), m_output);
            if (!wlr_gamma_control_v1_apply(control, &state)) {
              if (control != nullptr) {
                wlr_gamma_control_v1_send_failed_and_destroy(control);
              }
              m_gammaDirty = false;
            } else {
              gammaPending = true;
            }
          } else {
            m_gammaDirty = false;
          }
        }

        const bool hasBuffer = (state.committed & WLR_OUTPUT_STATE_BUFFER) != 0;
        bool commitTearing = requestTearing && hasBuffer;
        const bool recoveringFromFailedCommit = m_tearingRecovery.regularCommitPending();
        bool backendRejectedTearing = false;
        if (commitTearing) {
          state.tearing_page_flip = true;
          if (!wlr_output_test_state(m_output, &state)) {
            state.tearing_page_flip = false;
            commitTearing = false;
            backendRejectedTearing = true;
            m_tearingRecovery.forceRegularCommit();
            m_tearingFallbackReason = "backend rejected async page flip";
          }
        }

        {
          UMBRIEL_ZONE("Output::commitState");
          SceneCommit observation(*this, state);
          commitOk = wlr_output_commit_state(m_output, &state);
        }
        if (hasBuffer) {
          m_tearingRecovery.recordCommit(commitTearing, commitOk);
        }
        if (commitOk && gammaPending) {
          m_gammaDirty = false;
        }
        if (commitOk && hasBuffer) {
          m_lastCommitTearing = commitTearing;
          m_trackingPresentation = true;
          m_trackedPresentationCommitSeq = m_output->commit_seq;
          m_lastPresentationPresented.reset();
          m_lastPresentationFlags.reset();
          if (commitTearing) {
            m_tearingFallbackReason.clear();
          } else if (
              recoveringFromFailedCommit && !backendRejectedTearing && !m_tearingRecovery.regularCommitPending()
          ) {
            m_tearingFallbackReason = "recovered with regular page flip";
          }
          if (SessionLock* lock = m_server->sessionLock()) {
            lock->handleOutputCommit(*this, m_output->commit_seq);
          }
        } else if (commitTearing) {
          m_tearingFallbackReason = "async page flip commit failed";
        } else if (hasBuffer && m_tearingRecovery.regularCommitPending()) {
          m_tearingFallbackReason = "regular recovery commit failed";
        }
      }

      wlr_output_state_finish(&state);
      m_inFrame = false;
      commitFailed = !commitOk;
    }

    // Screencopy drops its lock inside the commit; image-copy sessions ask for the release frame when they end.
    if (m_effectCaptureBuilt
        && !(effectCapturePending(externalRenderLocks()) || captureExclusionPending(externalRenderLocks()))) {
      scheduleEffectCaptureRelease();
    }

    // A request_state that arrived mid-commit is applied now that we're out of it.
    if (m_hasDeferredMode) {
      m_hasDeferredMode = false;
      applyMode(m_deferredWidth, m_deferredHeight, m_deferredRefresh);
    }

    if (commitFailed && m_output->idle_frame != nullptr) {
      // Damage, animation, or deferred output work can schedule another idle frame while this frame callback is still
      // running. Remove it before arming the timer, otherwise the idle dispatcher can still recurse without returning
      // to signals.
      wl_event_source_remove(m_output->idle_frame);
      m_output->idle_frame = nullptr;
    }

    // A failed commit has no vblank to pace an immediate retry. Defer it so event-loop signal and session sources get
    // dispatched first. This also replaces animation scheduling for the failed frame, otherwise the animation path
    // would recreate the same immediate retry loop.
    switch (outputFrameFollowup(m_server->stopping(), m_server->session(), commitFailed, animationsActive)) {
    case OutputFrameFollowup::Schedule:
      wlr_output_schedule_frame(m_output);
      break;
    case OutputFrameFollowup::RetryDelayed:
      armFrameRetry();
      break;
    case OutputFrameFollowup::None:
      break;
    }

    if ((effectsEligible || audioPending()) && !commitFailed) {
      armEffectFrame(nowMsec);
    } else {
      disarmEffectFrame();
    }
    m_handlingFrame = false;

    if (Ipc* ipc = m_server->ipc()) {
      ipc->notifyOutputFrame(*this);
    }

    // Unconditional: see comment above. Never gate this on commit success.
    wlr_scene_output_send_frame_done(m_sceneOutput, &now);
  }

  void Output::handleRequestState(void* data) {
    auto* event = static_cast<wlr_output_event_request_state*>(data);

    // Parent configure can arrive while we are flushing a frame commit. Applying a
    // mode change mid-frame makes the wayland backend reject the primary buffer.
    if (m_inFrame
        && (event->state->committed & WLR_OUTPUT_STATE_MODE) != 0
        && event->state->mode_type == WLR_OUTPUT_STATE_MODE_CUSTOM) {
      m_deferredWidth = event->state->custom_mode.width;
      m_deferredHeight = event->state->custom_mode.height;
      m_deferredRefresh = event->state->custom_mode.refresh;
      m_hasDeferredMode = true;
      return;
    }

    if (!wlr_output_commit_state(m_output, event->state)) {
      wlr_log(WLR_ERROR, "failed to commit requested output state for '%s'", m_output->name);
      return;
    }
    if ((event->state->committed & (WLR_OUTPUT_STATE_MODE | WLR_OUTPUT_STATE_ENABLED)) != 0) {
      markDirty(Dirty::LayerArrange | Dirty::Banner | Dirty::Backdrop);
      m_gammaDirty = true;
      updateHdrAvailability();
      m_server->updateColorPreferences();
      if (SessionLock* lock = m_server->sessionLock()) {
        lock->handleOutputStateChanged(*this);
      }
    }
    wlr_output_schedule_frame(m_output);
  }

  void Output::handlePresent(void* data) {
    const auto* event = static_cast<const wlr_output_event_present*>(data);
#ifdef TRACY_ENABLE
    if (event->presented) {
      if (m_tracyIntervalPlot == nullptr) {
        m_tracyIntervalPlot = tracyPlotName(std::format("{} present interval ms", m_output->name));
        m_tracyVblankPlot = tracyPlotName(std::format("{} vblanks per present", m_output->name));
      }
      const int64_t whenNs = static_cast<int64_t>(event->when.tv_sec) * 1'000'000'000 + event->when.tv_nsec;
      if (m_tracyLastPresentNs != 0) {
        TracyPlot(m_tracyIntervalPlot, static_cast<double>(whenNs - m_tracyLastPresentNs) / 1e6);
      }
      // Above 1 while frames keep coming, the output repeated a vblank: a missed frame.
      if (event->seq != 0 && m_tracyLastPresentSeq != 0) {
        TracyPlot(m_tracyVblankPlot, static_cast<int64_t>(event->seq - m_tracyLastPresentSeq));
      }
      m_tracyLastPresentNs = whenNs;
      m_tracyLastPresentSeq = event->seq;
    }
#endif
    if (event->presented) {
      const bool fixedRefresh =
          event->refresh > 0 && m_output->adaptive_sync_status != WLR_OUTPUT_ADAPTIVE_SYNC_ENABLED;
      m_lastPresentNs = fixedRefresh
          ? static_cast<uint64_t>(event->when.tv_sec) * 1'000'000'000 + static_cast<uint64_t>(event->when.tv_nsec)
          : 0;
      m_refreshNs = fixedRefresh ? static_cast<uint64_t>(event->refresh) : 0;
    }
    if (SessionLock* lock = m_server->sessionLock()) {
      lock->handleOutputPresent(*this, event->commit_seq, event->presented);
    }
    if (!m_trackingPresentation || event->commit_seq != m_trackedPresentationCommitSeq) {
      return;
    }
    m_trackingPresentation = false;
    m_lastPresentationPresented = event->presented;
    if (event->presented) {
      m_lastPresentationFlags = event->flags;
    } else {
      m_lastPresentationFlags.reset();
      if (m_lastCommitTearing) {
        m_tearingRecovery.forceRegularCommit();
        m_tearingFallbackReason = "async page flip was not presented";
        wlr_damage_ring_add_whole(&m_sceneOutput->damage_ring);
        if (outputFrameAllowed(m_server->stopping(), m_server->session())) {
          wlr_output_schedule_frame(m_output);
        }
      }
    }
  }

  void Output::handleDestroy() {
    if (m_output->data == this) {
      m_output->data = nullptr;
    }
    wl_list_remove(&m_frame.link);
    wl_list_remove(&m_requestState.link);
    wl_list_remove(&m_present.link);
    wl_list_remove(&m_destroy.link);
    m_frame.link.next = nullptr;
    m_requestState.link.next = nullptr;
    m_present.link.next = nullptr;
    m_destroy.link.next = nullptr;
    if (m_optimizedBlur != nullptr && m_server->scene() != nullptr) {
      wlr_scene_node_destroy(&m_optimizedBlur->node);
    }
    m_optimizedBlur = nullptr;
    m_server->removeOutput(this);
  }

} // namespace umbriel