Settings > Player > External Monitor > HDR Preview Window

Author: ddennedy

src/CMakeLists.txt

@@ -146,6 +146,7 @@ add_executable(shotcut WIN32 MACOSX_BUNDLE
   transportcontrol.h
   util.cpp util.h
   videowidget.cpp videowidget.h
+  hdrpreviewwindow.cpp hdrpreviewwindow.h
   widgets/alsawidget.cpp widgets/alsawidget.h
   widgets/alsawidget.ui
   widgets/audiometerwidget.cpp widgets/audiometerwidget.h
@@ -266,12 +267,29 @@ add_custom_target(OTHER_FILES
   ../scripts/staple.sh
 )
 
+# Compile HDR gain shader (used by HdrPreview.qml ShaderEffect)
+find_program(QSB_EXECUTABLE qsb HINTS
+  "${Qt6_DIR}/../../../bin" "${Qt6Core_DIR}/../../../bin")
+if(QSB_EXECUTABLE)
+  set(HDR_GAIN_FRAG ${CMAKE_CURRENT_SOURCE_DIR}/qml/views/hdr_gain.frag)
+  set(HDR_GAIN_QSB ${CMAKE_CURRENT_SOURCE_DIR}/qml/views/hdr_gain.frag.qsb)
+  add_custom_command(
+    OUTPUT ${HDR_GAIN_QSB}
+    COMMAND ${QSB_EXECUTABLE} --glsl "100 es,120,150" --hlsl 50 --msl 12 -o ${HDR_GAIN_QSB} ${HDR_GAIN_FRAG}
+    DEPENDS ${HDR_GAIN_FRAG}
+    COMMENT "Compiling HDR gain shader"
+  )
+  add_custom_target(hdr_shaders ALL DEPENDS ${HDR_GAIN_QSB})
+  add_dependencies(shotcut hdr_shaders)
+endif()
+
 target_link_libraries(shotcut
   PRIVATE
   CuteLogger
   PkgConfig::mlt++
   PkgConfig::FFTW
   Qt6::Charts
+  Qt6::GuiPrivate
   Qt6::Multimedia
   Qt6::Network
   Qt6::OpenGL

src/hdrpreviewwindow.cpp

@@ -0,0 +1,169 @@
+/*
+ * Copyright (c) 2026 Meltytech, LLC
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "hdrpreviewwindow.h"
+
+#include "qmltypes/qmlutilities.h"
+
+#include <private/qrhi_p.h>
+#include <QDebug>
+#include <QDir>
+#include <QQmlContext>
+#include <QQmlEngine>
+#include <QQuickItem>
+
+#ifdef Q_OS_MACOS
+#include "macos.h"
+#endif
+
+// HLG OETF: scene-referred linear to HLG electrical signal.
+// See ITU-R BT.2100-2.
+static float hlgOetf(float linear)
+{
+    const float a = 0.17883277f;
+    const float b = 0.28466892f;
+    const float c = 0.55991073f;
+    if (linear < 1.0f / 12.0f)
+        return sqrtf(3.0f * linear);
+    return a * logf(12.0f * linear - b) + c;
+}
+
+HdrPreviewWindow::HdrPreviewWindow(QWindow *parent)
+    : QQuickView(QmlUtilities::sharedEngine(), parent)
+{
+    setTitle(tr("HDR Preview"));
+    setResizeMode(QQuickView::SizeRootObjectToView);
+    setColor(Qt::black);
+
+    // Request HDR swapchain via the internal Qt scene graph property.
+    // Qt's video fragment shaders only select the linear HDR output path
+    // (nv12_bt2020_hlg_linear.frag) for HDRExtendedSrgbLinear, not for
+    // HDRExtendedDisplayP3Linear. So we must use "scrgb" on all platforms.
+    setProperty("_qt_sg_hdr_format", QByteArrayLiteral("scrgb"));
+
+    rootContext()->setContextProperty("hdrWindow", this);
+
+    QDir qmlDir = QmlUtilities::qmlDir();
+    setSource(QUrl::fromLocalFile(qmlDir.filePath("views/HdrPreview.qml")));
+
+    resize(960, 540);
+
+#ifdef Q_OS_MACOS
+    // Override NSScreen.maximumExtendedDynamicRangeColorComponentValue so that
+    // Qt's video shader outputs > 1.0 values (HDR) on the first frame, which
+    // then causes macOS to allocate real EDR headroom.
+    macosOverrideEdrHeadroom(true);
+
+    // Monitor EDR headroom every second for the first 30 seconds.
+    connect(&m_edrTimer, &QTimer::timeout, this, &HdrPreviewWindow::checkEdrHeadroom);
+    m_edrTimer.start(1000);
+#endif
+}
+
+HdrPreviewWindow::~HdrPreviewWindow()
+{
+#ifdef Q_OS_MACOS
+    macosOverrideEdrHeadroom(false);
+#endif
+}
+
+void HdrPreviewWindow::setVideoSink(QVideoSink *sink)
+{
+    m_videoSink = sink;
+}
+
+void HdrPreviewWindow::pushFrame(const QVideoFrame &frame)
+{
+    if (m_videoSink && isVisible()) {
+        if (!m_loggedSwapChain) {
+            m_loggedSwapChain = true;
+            auto *sc = swapChain();
+            if (sc) {
+                qDebug() << "HDR Preview: swapChain format =" << sc->format()
+                         << "hdrInfo =" << sc->hdrInfo();
+            } else {
+                qDebug() << "HDR Preview: swapChain() returned nullptr!";
+            }
+            qDebug() << "HDR Preview frame: pixelFormat =" << frame.surfaceFormat().pixelFormat()
+                     << "colorTransfer =" << frame.surfaceFormat().colorTransfer()
+                     << "maxLuminance =" << frame.surfaceFormat().maxLuminance();
+#ifdef Q_OS_MACOS
+            auto wid = winId();
+            qDebug() << "HDR Preview EDR:"
+                     << "current =" << macosCurrentEdrHeadroom(wid)
+                     << "potential =" << macosPotentialEdrHeadroom(wid)
+                     << "reference =" << macosReferenceEdrHeadroom(wid);
+#endif
+        }
+        updateHdrGain();
+        m_videoSink->setVideoFrame(frame);
+    }
+}
+
+void HdrPreviewWindow::setHlg(bool isHlg)
+{
+    if (m_isHlg != isHlg) {
+        m_isHlg = isHlg;
+        if (!m_isHlg && !qFuzzyCompare(m_hdrGain, 1.0f)) {
+            m_hdrGain = 1.0f;
+            emit hdrGainChanged();
+        }
+    }
+}
+
+void HdrPreviewWindow::updateHdrGain()
+{
+    if (!m_isHlg)
+        return;
+
+    auto *sc = swapChain();
+    if (!sc || sc->format() != QRhiSwapChain::HDRExtendedSrgbLinear)
+        return;
+
+    auto info = sc->hdrInfo();
+    float headroom = 1.0f;
+    if (info.limitsType == QRhiSwapChainHdrInfo::ColorComponentValue)
+        headroom = info.limits.colorComponentValue.maxColorComponentValue;
+
+    if (headroom <= 1.0f)
+        return;
+
+    // Qt's HLG shader has a bug: maxLum is HLG-encoded but used as a linear
+    // multiplier in the OOTF.  Compensate by multiplying the rendered output
+    // by the ratio of the correct linear value to the HLG-encoded one.
+    float newGain = headroom / hlgOetf(headroom);
+    if (!qFuzzyCompare(newGain, m_hdrGain)) {
+        m_hdrGain = newGain;
+        qDebug() << "HDR Preview: gain =" << m_hdrGain << "(headroom =" << headroom << ")";
+        emit hdrGainChanged();
+    }
+}
+
+void HdrPreviewWindow::checkEdrHeadroom()
+{
+#ifdef Q_OS_MACOS
+    float headroom = macosCurrentEdrHeadroom(winId());
+    if (headroom != m_lastLoggedHeadroom) {
+        m_lastLoggedHeadroom = headroom;
+        auto *sc = swapChain();
+        qDebug() << "HDR Preview: EDR headroom =" << headroom
+                 << "(swapChain hdrInfo =" << (sc ? sc->hdrInfo() : QRhiSwapChainHdrInfo()) << ")";
+    }
+    if (++m_edrCheckCount >= 30)
+        m_edrTimer.stop();
+#endif
+}

src/hdrpreviewwindow.h

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2026 Meltytech, LLC
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef HDRPREVIEWWINDOW_H
+#define HDRPREVIEWWINDOW_H
+
+#include <QPointer>
+#include <QQuickView>
+#include <QTimer>
+#include <QVideoFrame>
+#include <QVideoSink>
+
+class HdrPreviewWindow : public QQuickView
+{
+    Q_OBJECT
+    Q_PROPERTY(float hdrGain READ hdrGain NOTIFY hdrGainChanged)
+
+public:
+    explicit HdrPreviewWindow(QWindow *parent = nullptr);
+    ~HdrPreviewWindow();
+
+    Q_INVOKABLE void setVideoSink(QVideoSink *sink);
+    float hdrGain() const { return m_hdrGain; }
+
+public slots:
+    void pushFrame(const QVideoFrame &frame);
+    void setHlg(bool isHlg);
+
+signals:
+    void hdrGainChanged();
+
+private slots:
+    void checkEdrHeadroom();
+
+private:
+    void updateHdrGain();
+
+    QPointer<QVideoSink> m_videoSink;
+    QTimer m_edrTimer;
+    bool m_loggedSwapChain{false};
+    bool m_isHlg{false};
+    float m_lastLoggedHeadroom{0.0f};
+    int m_edrCheckCount{0};
+    float m_hdrGain{1.0f};
+};
+
+#endif // HDRPREVIEWWINDOW_H

src/macos.h

@@ -17,8 +17,32 @@
 
 #pragma once
 
+#include <cstdint>
+
 void removeMacosTabBar();
 void macosSetDockProgress(int percent);
 void macosPauseDockProgress(int percent);
 void macosResetDockProgress();
 void macosFinishDockProgress(bool isSuccess, bool stopped);
+
+/// Override NSScreen.maximumExtendedDynamicRangeColorComponentValue to return
+/// the *potential* headroom.  This breaks the chicken-and-egg where Qt's shader
+/// won't output > 1.0 because headroom=1, and macOS won't allocate headroom
+/// because no content > 1.0 is being rendered.  Once the shader outputs HDR
+/// values, macOS allocates real headroom and the override becomes a no-op.
+/// Safe: only affects the HDR preview window's video shader (main window uses
+/// SDR swapchain format, so Qt's video node ignores hdrInfo for it).
+void macosOverrideEdrHeadroom(bool enable);
+
+/// Query the current EDR headroom for the screen hosting the given window.
+/// Returns NSScreen.maximumExtendedDynamicRangeColorComponentValue.
+/// @param windowId  QWindow::winId()
+float macosCurrentEdrHeadroom(uintptr_t windowId);
+
+/// Query the potential (maximum) EDR headroom.
+/// Returns NSScreen.maximumPotentialExtendedDynamicRangeColorComponentValue.
+float macosPotentialEdrHeadroom(uintptr_t windowId);
+
+/// Query the reference EDR headroom.
+/// Returns NSScreen.maximumReferenceExtendedDynamicRangeColorComponentValue.
+float macosReferenceEdrHeadroom(uintptr_t windowId);

src/macos.mm

@@ -20,8 +20,12 @@
 #import <AppKit/NSDockTile.h>
 #import <AppKit/NSImageView.h>
 #import <AppKit/NSProgressIndicator.h>
+#import <AppKit/NSScreen.h>
 #import <AppKit/NSView.h>
 #import <AppKit/NSWindow.h>
+#import <objc/runtime.h>
+
+#include <atomic>
 
 void removeMacosTabBar()
 {
@@ -96,3 +100,69 @@ void macosFinishDockProgress(bool isSuccess, bool stopped)
         [NSApp requestUserAttention:NSCriticalRequest];
     }
 }
+
+// ---------------------------------------------------------------------------
+// EDR headroom override via method swizzle on NSScreen
+// ---------------------------------------------------------------------------
+static std::atomic<bool> s_edrOverrideEnabled{false};
+static bool s_swizzled = false;
+
+// Category that holds the swizzled implementation.
+@interface NSScreen (ShotcutEdrOverride)
+- (CGFloat)shotcut_maximumExtendedDynamicRangeColorComponentValue;
+@end
+
+@implementation NSScreen (ShotcutEdrOverride)
+- (CGFloat)shotcut_maximumExtendedDynamicRangeColorComponentValue
+{
+    // After swizzling, calling the swizzled selector invokes the ORIGINAL impl.
+    CGFloat real = [self shotcut_maximumExtendedDynamicRangeColorComponentValue];
+    if (s_edrOverrideEnabled.load(std::memory_order_relaxed) && real < 2.0) {
+        return self.maximumPotentialExtendedDynamicRangeColorComponentValue;
+    }
+    return real;
+}
+@end
+
+void macosOverrideEdrHeadroom(bool enable)
+{
+    if (!s_swizzled) {
+        s_swizzled = true;
+        Method original = class_getInstanceMethod(
+            [NSScreen class],
+            @selector(maximumExtendedDynamicRangeColorComponentValue));
+        Method swizzled = class_getInstanceMethod(
+            [NSScreen class],
+            @selector(shotcut_maximumExtendedDynamicRangeColorComponentValue));
+        method_exchangeImplementations(original, swizzled);
+        NSLog(@"macosOverrideEdrHeadroom: swizzled NSScreen.maximumExtendedDynamicRangeColorComponentValue");
+    }
+    s_edrOverrideEnabled.store(enable, std::memory_order_relaxed);
+    NSLog(@"macosOverrideEdrHeadroom: %s", enable ? "enabled" : "disabled");
+}
+
+float macosCurrentEdrHeadroom(uintptr_t windowId)
+{
+    NSView *view = reinterpret_cast<NSView *>(windowId);
+    if (!view || !view.window || !view.window.screen)
+        return 1.0f;
+    return static_cast<float>(view.window.screen.maximumExtendedDynamicRangeColorComponentValue);
+}
+
+float macosPotentialEdrHeadroom(uintptr_t windowId)
+{
+    NSView *view = reinterpret_cast<NSView *>(windowId);
+    if (!view || !view.window || !view.window.screen)
+        return 1.0f;
+    return static_cast<float>(view.window.screen.maximumPotentialExtendedDynamicRangeColorComponentValue);
+}
+
+float macosReferenceEdrHeadroom(uintptr_t windowId)
+{
+    NSView *view = reinterpret_cast<NSView *>(windowId);
+    if (!view || !view.window || !view.window.screen)
+        return 1.0f;
+    if (@available(macOS 12.0, *))
+        return static_cast<float>(view.window.screen.maximumReferenceExtendedDynamicRangeColorComponentValue);
+    return 1.0f;
+}