From 6da3c2fc6ef71fea31c0a2b6efe9f8d31e0c34e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Sun, 12 Jul 2026 14:32:16 -0400
Subject: [PATCH 01/20] gfx: prefer EGL on xcb and force a desktop OpenGL
 context

Request the xcb EGL integration on X11 so that dma-buf import can stay
zero-copy, and pin a desktop-GL (not GLES) core-profile context with a
stencil buffer on the desktop code path.

(cherry picked from commit 38cd38d6ac5a18fcb88eb5323028bb7227375688)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/app/main.cpp | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/app/main.cpp b/src/app/main.cpp
index f8dc64c2ff..b824fb0c0d 100644
--- a/src/app/main.cpp
+++ b/src/app/main.cpp
@@ -273,6 +273,9 @@ static void setup_x11(int argc, char** argv)
 
         helper_dylibs.run_under_x11 = true;
         helper_dylibs.xwayland = wayland;
+
+        // EGL is the only way to get zero-copy with dma-buf import
+        qputenv("QT_XCB_GL_INTEGRATION", "xcb_egl");
       }
     }
   };
@@ -518,6 +521,7 @@ static void setup_opengl(bool& enable_opengl_ui)
 
 #ifndef QT_NO_OPENGL
 #if (defined(__arm__) || defined(__aarch64__)) && !defined(_WIN32) && !defined(__APPLE__)
+  // Raspberry Pi & such
   QSurfaceFormat fmt = QSurfaceFormat::defaultFormat();
   fmt.setRenderableType(QSurfaceFormat::OpenGLES);
   fmt.setSwapInterval(1);
@@ -533,6 +537,7 @@ static void setup_opengl(bool& enable_opengl_ui)
   fmt.setDefaultFormat(fmt);
 #else
   {
+    // Desktop GL
     std::vector<std::pair<int, int>> versions_to_test
         = {{4, 6}, {4, 5}, {4, 4}, {4, 3}, {4, 2}, {4, 1}, {4, 0},
            {3, 3}, {3, 2}, {3, 1}, {3, 0}, {2, 1}, {2, 0}};
@@ -571,7 +576,9 @@ static void setup_opengl(bool& enable_opengl_ui)
 
     QSurfaceFormat fmt = QSurfaceFormat::defaultFormat();
     fmt.setProfile(QSurfaceFormat::CoreProfile);
+    fmt.setRenderableType(QSurfaceFormat::OpenGL);
     fmt.setSwapInterval(1);
+    fmt.setStencilBufferSize(8);
     bool ok = false;
     for(auto [maj, min] : versions_to_test)
     {

From 680dccbd293f44551db12851407e80749d7b8d47 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Sun, 5 Jul 2026 17:28:29 -0400
Subject: [PATCH 02/20] gstreamer: classify appsinks from the pipeline string,
 follow the engine quantum

(cherry picked from commit cb5ca64ba99851dd83daecd7c5ccb79defd982b7)
---
 .../Gfx/GStreamer/GStreamerDevice.cpp         | 174 +++++++++++++++---
 1 file changed, 148 insertions(+), 26 deletions(-)

diff --git a/src/plugins/score-plugin-gfx/Gfx/GStreamer/GStreamerDevice.cpp b/src/plugins/score-plugin-gfx/Gfx/GStreamer/GStreamerDevice.cpp
index 81a74cd651..b0b24ddbef 100644
--- a/src/plugins/score-plugin-gfx/Gfx/GStreamer/GStreamerDevice.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/GStreamer/GStreamerDevice.cpp
@@ -35,8 +35,10 @@ extern "C" {
 #include <Gfx/GStreamer/GStreamerLoader.hpp>
 #include <Video/GStreamerCompatibility.hpp>
 
+#include <ossia/detail/parse_strict.hpp>
+
 #include <climits>
-#include <regex>
+#include <ctre.hpp>
 #include <thread>
 
 namespace Gfx::GStreamer
@@ -71,6 +73,11 @@ struct gstreamer_pipeline
 
     // Ring buffer per channel, written by GStreamer thread, read by audio engine
     static constexpr std::size_t ring_size = 65536;
+
+    // Max block the audio thread may resize the output storage to; the
+    // parameter reserves this up front so the per-tick resize never reallocates
+    // (a realloc would free a buffer the audio thread is reading through).
+    static constexpr std::size_t max_block = 1 << 15;
     std::vector<std::vector<float>> ring; // [channel][ring_size]
     std::atomic<std::size_t> write_pos{0};
     std::atomic<std::size_t> read_pos{0};
@@ -99,11 +106,38 @@ struct gstreamer_pipeline
       write_pos.store(wp + num_samples, std::memory_order_release);
     }
 
+    // Points at the parameter's audio spans so read_into_output can re-point
+    // them after a resize. A raw pointer (not a std::function) so that clearing
+    // or using it during teardown can never throw on the audio thread.
+    ossia::small_vector<std::span<float>, 8>* output_spans{};
+
     // Called by audio engine (indirectly): copy from ring into output spans
     void read_into_output(int block_size)
     {
       if(!output_data)
         return;
+
+      // The engine tick size can differ from the configured buffer size
+      // (e.g. PipeWire dynamic quantum); the storage follows it, but never
+      // beyond the capacity reserved at construction (so no reallocation).
+      if(block_size > (int)max_block)
+        block_size = max_block;
+      bool resized = false;
+      for(auto& v : *output_data)
+      {
+        if(std::ssize(v) != block_size)
+        {
+          v.resize(block_size);
+          resized = true;
+        }
+      }
+      if(resized && output_spans && output_data)
+      {
+        const std::size_t n = std::min(output_spans->size(), output_data->size());
+        for(std::size_t i = 0; i < n; i++)
+          (*output_spans)[i] = (*output_data)[i];
+      }
+
       auto rp = read_pos.load(std::memory_order_relaxed);
       auto wp = write_pos.load(std::memory_order_acquire);
 
@@ -236,12 +270,15 @@ struct gstreamer_pipeline
           }
           else
           {
-            // Caps not yet negotiated; default to video
-            info.is_video = true;
-            info.width = 640;
-            info.height = 480;
-            info.pixfmt = AV_PIX_FMT_RGBA;
-            video_count++;
+            // Caps not yet negotiated (e.g. live sources: v4l2src, webrtcsrc,
+            // audiotestsrc is-live=true don't preroll in PAUSED).
+            // Fall back to classifying from the pipeline description: the
+            // nearest audio/video token before this appsink wins.
+            classify_from_pipeline_string(pipeline_string, sink_name, info);
+            if(info.is_video)
+              video_count++;
+            else
+              audio_count++;
           }
           gst.object_unref(pad);
         }
@@ -346,17 +383,16 @@ struct gstreamer_pipeline
   }
 
 private:
+  static constexpr auto appsink_name_rexp
+      = ctll::fixed_string{R"(appsink\b[^!]*?\bname\s*=\s*([A-Za-z0-9_]+))"};
+  static constexpr auto elem_name_rexp
+      = ctll::fixed_string{R"(\bname\s*=\s*([A-Za-z0-9_]+))"};
+
   static std::vector<std::string> find_appsink_names(const std::string& pipeline)
   {
     std::vector<std::string> names;
-    // Match "appsink" optionally followed by properties including name=<identifier>
-    std::regex re(R"(appsink\b[^!]*?\bname\s*=\s*(\w+))");
-    auto begin = std::sregex_iterator(pipeline.begin(), pipeline.end(), re);
-    auto end = std::sregex_iterator();
-    for(auto it = begin; it != end; ++it)
-    {
-      names.push_back((*it)[1].str());
-    }
+    for(auto m : ctre::search_all<appsink_name_rexp>(pipeline))
+      names.push_back(m.get<1>().to_string());
     return names;
   }
 
@@ -365,14 +401,87 @@ struct gstreamer_pipeline
   static std::vector<std::string> find_all_named_elements(const std::string& pipeline)
   {
     std::vector<std::string> names;
-    std::regex re(R"(\bname\s*=\s*(\w+))");
-    auto begin = std::sregex_iterator(pipeline.begin(), pipeline.end(), re);
-    auto end = std::sregex_iterator();
-    for(auto it = begin; it != end; ++it)
+    for(auto m : ctre::search_all<elem_name_rexp>(pipeline))
+      names.push_back(m.get<1>().to_string());
+    return names;
+  }
+
+  static constexpr auto channels_rexp
+      = ctll::fixed_string{R"(channels=(?:\(int\))?\s*([0-9]+))"};
+  static constexpr auto rate_rexp
+      = ctll::fixed_string{R"(rate=(?:\(int\))?\s*([0-9]+))"};
+  static constexpr auto width_rexp
+      = ctll::fixed_string{R"(width=(?:\(int\))?\s*([0-9]+))"};
+  static constexpr auto height_rexp
+      = ctll::fixed_string{R"(height=(?:\(int\))?\s*([0-9]+))"};
+  static constexpr auto format_rexp
+      = ctll::fixed_string{R"(format=(?:\(string\))?\s*([A-Za-z0-9]+))"};
+
+  template <ctll::fixed_string Rexp>
+  static int last_int_of(std::string_view str, int fallback)
+  {
+    int ret = fallback;
+    for(auto m : ctre::search_all<Rexp>(str))
+      if(auto v = ossia::parse_strict<int>(m.template get<1>().to_view()))
+        ret = *v;
+    return ret;
+  }
+
+  // Guess an appsink's media type from the pipeline string when caps are
+  // not negotiated yet: look for the last audio/video-ish token occurring
+  // before "appsink ... name=<sink_name>".
+  static void classify_from_pipeline_string(
+      const std::string& pipeline, const std::string& sink_name, AppsinkInfo& info)
+  {
+    std::size_t sink_pos = std::string::npos;
+    for(auto m : ctre::search_all<appsink_name_rexp>(pipeline))
     {
-      names.push_back((*it)[1].str());
+      if(m.get<1>().to_view() == sink_name)
+      {
+        sink_pos = std::distance(pipeline.begin(), m.get<0>().begin());
+        break;
+      }
+    }
+    const std::string_view before
+        = std::string_view{pipeline}.substr(0, sink_pos);
+
+    static constexpr std::string_view audio_tokens[]
+        = {"audio/x-raw", "audioconvert", "audioresample", "audiotestsrc"};
+    static constexpr std::string_view video_tokens[]
+        = {"video/x-raw", "videoconvert", "videoscale", "videotestsrc", "videorate"};
+
+    std::size_t last_audio = std::string::npos, last_video = std::string::npos;
+    for(auto tok : audio_tokens)
+      if(auto p = before.rfind(tok); p != std::string::npos)
+        last_audio = (last_audio == std::string::npos) ? p : std::max(last_audio, p);
+    for(auto tok : video_tokens)
+      if(auto p = before.rfind(tok); p != std::string::npos)
+        last_video = (last_video == std::string::npos) ? p : std::max(last_video, p);
+
+    const bool is_audio = last_audio != std::string::npos
+                          && (last_video == std::string::npos || last_audio > last_video);
+    if(is_audio)
+    {
+      info.is_video = false;
+      info.channels = last_int_of<channels_rexp>(before, 2);
+      info.rate = last_int_of<rate_rexp>(before, 48000);
+    }
+    else
+    {
+      info.is_video = true;
+      info.width = last_int_of<width_rexp>(before, 640);
+      info.height = last_int_of<height_rexp>(before, 480);
+      info.pixfmt = AV_PIX_FMT_RGBA;
+      std::string format;
+      for(auto m : ctre::search_all<format_rexp>(before))
+        format = m.get<1>().to_string();
+      if(!format.empty())
+      {
+        auto& map = ::Video::gstreamerToLibav();
+        if(auto it = map.find(format); it != map.end())
+          info.pixfmt = it->second;
+      }
     }
-    return names;
   }
 
   static void parse_video_caps(
@@ -562,18 +671,29 @@ class gstreamer_audio_parameter final : public ossia::audio_parameter
       , m_audio_data(num_channels)
       , m_block_size{bs}
   {
-    // Set up owned buffers and point audio spans to them permanently
+    // Set up owned buffers and point audio spans to them permanently.
+    // Reserve a generous capacity up front so the per-tick resize() in
+    // read_into_output (block size follows the engine quantum) never
+    // reallocates — a realloc here would free a buffer the audio thread may
+    // still be reading through the spans, causing a double free.
     audio.resize(num_channels);
     for(int i = 0; i < num_channels; i++)
     {
+      m_audio_data[i].reserve(gstreamer_pipeline::AudioBuffer::max_block);
       m_audio_data[i].resize(bs, 0.f);
       audio[i] = m_audio_data[i];
     }
-    // Give the AudioBuffer a pointer so read_into_output can fill our buffers
+    // Give the AudioBuffer pointers so read_into_output can fill our buffers
+    // and re-point our spans after a resize.
     m_buffer.output_data = &m_audio_data;
+    m_buffer.output_spans = &audio;
   }
 
-  virtual ~gstreamer_audio_parameter() { m_buffer.output_data = nullptr; }
+  virtual ~gstreamer_audio_parameter()
+  {
+    m_buffer.output_data = nullptr;
+    m_buffer.output_spans = nullptr;
+  }
 
   // clone_value() (not virtual) reads from audio spans.
   // We use push_value(audio_port) as a hook — it's called by the audio engine
@@ -594,8 +714,10 @@ class gstreamer_audio_parameter final : public ossia::audio_parameter
 
   void refresh_from_ring()
   {
-    m_buffer.read_into_output(m_block_size);
-    // Re-point spans (in case vectors reallocated, though they shouldn't)
+    // Follow whatever block size the engine last requested in pre_tick
+    const int bs
+        = m_audio_data.empty() ? m_block_size : (int)m_audio_data[0].size();
+    m_buffer.read_into_output(bs);
     for(std::size_t i = 0; i < m_audio_data.size(); i++)
       audio[i] = m_audio_data[i];
   }

From 20626ba3af76410d9b5779d41b41a087f25398ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Mon, 27 Jul 2026 08:30:48 -0400
Subject: [PATCH 03/20] gfx: export ISFNode

The plugin builds with -fvisibility=hidden, so an un-exported class has no
externally linkable constructor. DecklinkRoundtrip uses ISFNode for its GPU
test-pattern path and failed to link against it; every other node the
harnesses construct already carries the export.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-gfx/Gfx/Graph/ISFNode.hpp | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/ISFNode.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/ISFNode.hpp
index bdb3f21189..60e2b5d3f5 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/ISFNode.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/ISFNode.hpp
@@ -5,6 +5,8 @@
 
 #include <isf.hpp>
 
+#include <score_plugin_gfx_export.h>
+
 #include <list>
 namespace score::gfx
 {

From c7e98e4c15b21661f68d71a75e3ff90e04962b2b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Sun, 12 Jul 2026 14:32:16 -0400
Subject: [PATCH 04/20] gfx: add a video pixel format vocabulary and libav
 bridge

A backend-neutral pixel-format description plus conversions to and from
ffmpeg's AVPixelFormat, shared by the video encoders, decoders and the
GPU interop strategies.

(cherry picked from commit c835069748dea74fb75bf6484b1c066b9eefdf68)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-gfx/CMakeLists.txt   |   4 +
 .../Gfx/Graph/interop/VideoPixelFormat.cpp    | 326 ++++++++++++++++++
 .../Gfx/Graph/interop/VideoPixelFormat.hpp    | 160 +++++++++
 .../Gfx/Graph/interop/VideoPixelFormatAV.cpp  | 103 ++++++
 .../Gfx/Graph/interop/VideoPixelFormatAV.hpp  |  56 +++
 5 files changed, 649 insertions(+)
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.hpp

diff --git a/src/plugins/score-plugin-gfx/CMakeLists.txt b/src/plugins/score-plugin-gfx/CMakeLists.txt
index 643785948c..c7327d1f2b 100644
--- a/src/plugins/score-plugin-gfx/CMakeLists.txt
+++ b/src/plugins/score-plugin-gfx/CMakeLists.txt
@@ -239,6 +239,10 @@ set(HDRS
     Gfx/Graph/encoders/UYVYCompute.hpp
     Gfx/Graph/encoders/BGRACompute.hpp
     Gfx/Graph/encoders/ComputeEncoder.hpp
+    Gfx/Graph/interop/VideoPixelFormatAV.hpp
+    Gfx/Graph/interop/VideoPixelFormatAV.cpp
+    Gfx/Graph/interop/VideoPixelFormat.hpp
+    Gfx/Graph/interop/VideoPixelFormat.cpp
 
     Gfx/Graph/decoders/GPUVideoDecoder.hpp
     Gfx/Graph/decoders/GPUVideoDecoderFactory.hpp
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
new file mode 100644
index 0000000000..cdc8f8dda9
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
@@ -0,0 +1,326 @@
+#include "VideoPixelFormat.hpp"
+
+namespace score::gfx::interop
+{
+
+namespace
+{
+
+constexpr VideoPixelFormatInfo kUnknown{
+    "unknown", 0, 1, 1, 1, false, false, 256};
+
+constexpr VideoPixelFormatInfo
+makeRgb(const char* name, uint8_t bpp, uint16_t align = 256) noexcept
+{
+  return VideoPixelFormatInfo{name, bpp, 1, 1, 1, false, false, align};
+}
+
+constexpr VideoPixelFormatInfo makeYuv422Packed(const char* name,
+                                                uint8_t bpp,
+                                                uint16_t align = 256) noexcept
+{
+  return VideoPixelFormatInfo{name, bpp, 1, 2, 1, true, false, align};
+}
+
+constexpr VideoPixelFormatInfo makeNv12(const char* name, uint8_t bpp) noexcept
+{
+  // 4:2:0 semi-planar. Primary-sample bytes = bpp / (8 + 16/(hs*vs)) =
+  // bpp/12 here: exact for NV12 (12→1) and P010 (24→2).
+  return VideoPixelFormatInfo{name, bpp, 2, 2, 2, true, true, 256,
+                              uint8_t(bpp / 12u)};
+}
+
+constexpr VideoPixelFormatInfo makeNv16(const char* name, uint8_t bpp) noexcept
+{
+  // 4:2:2 semi-planar. bpp/16: exact for P210 (32→2).
+  return VideoPixelFormatInfo{name, bpp, 2, 2, 1, true, true, 256,
+                              uint8_t(bpp / 16u)};
+}
+
+constexpr VideoPixelFormatInfo
+makePlanar(const char* name, uint8_t bpp, uint8_t hs, uint8_t vs) noexcept
+{
+  // Fully planar. Primary-sample bytes = bpp / (8 + 16/(hs*vs)); exact
+  // for all 4:2:0 / 4:2:2 / 4:4:4 8/10/12-bit variants.
+  return VideoPixelFormatInfo{name, bpp, 3, hs, vs, true, true, 256,
+                              uint8_t(bpp / (8u + 16u / (uint32_t(hs) * vs)))};
+}
+
+constexpr VideoPixelFormatInfo makeMono(const char* name, uint8_t bpp) noexcept
+{
+  return VideoPixelFormatInfo{name, bpp, 1, 1, 1, false, false, 64};
+}
+
+} // namespace
+
+const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept
+{
+  // The clang-friendly approach: declare each info in a switch and
+  // return a reference to a static-local. Keeps the data localized
+  // with each enum value.
+  switch(f)
+  {
+    case VideoPixelFormat::BGRA8:
+    {
+      static constexpr auto i = makeRgb("BGRA8", 32);
+      return i;
+    }
+    case VideoPixelFormat::RGBA8:
+    {
+      static constexpr auto i = makeRgb("RGBA8", 32);
+      return i;
+    }
+    case VideoPixelFormat::ARGB8:
+    {
+      static constexpr auto i = makeRgb("ARGB8", 32);
+      return i;
+    }
+    case VideoPixelFormat::ABGR8:
+    {
+      static constexpr auto i = makeRgb("ABGR8", 32);
+      return i;
+    }
+    case VideoPixelFormat::RGB24:
+    {
+      static constexpr auto i = makeRgb("RGB24", 24, 64);
+      return i;
+    }
+    case VideoPixelFormat::BGR24:
+    {
+      static constexpr auto i = makeRgb("BGR24", 24, 64);
+      return i;
+    }
+    case VideoPixelFormat::R210:
+    {
+      static constexpr auto i = makeRgb("R210", 32, 256);
+      return i;
+    }
+    case VideoPixelFormat::R12B:
+    {
+      static constexpr auto i = makeRgb("R12B", 36, 256);
+      return i;
+    }
+    case VideoPixelFormat::R12L:
+    {
+      static constexpr auto i = makeRgb("R12L", 36, 256);
+      return i;
+    }
+    case VideoPixelFormat::ARGB10:
+    {
+      // 4×10-bit channels packed into 5 bytes/pixel (see PackedRGB::argb10,
+      // 40 bits). Declaring 32 here under-sized the stride by 20% → the
+      // encoder's readback wrote past DMA/ring allocations sized from it.
+      static constexpr auto i = makeRgb("ARGB10", 40, 256);
+      return i;
+    }
+    case VideoPixelFormat::DPX10:
+    {
+      static constexpr auto i = makeRgb("DPX10", 32, 256);
+      return i;
+    }
+    case VideoPixelFormat::DPX10LE:
+    {
+      static constexpr auto i = makeRgb("DPX10LE", 32, 256);
+      return i;
+    }
+    case VideoPixelFormat::RGB12P:
+    {
+      static constexpr auto i = makeRgb("RGB12P", 36, 256);
+      return i;
+    }
+    case VideoPixelFormat::RGB48:
+    {
+      static constexpr auto i = makeRgb("RGB48", 48, 256);
+      return i;
+    }
+    case VideoPixelFormat::RGB10:
+    {
+      static constexpr auto i = makeRgb("RGB10", 32, 256);
+      return i;
+    }
+    case VideoPixelFormat::UYVY422:
+    {
+      static constexpr auto i = makeYuv422Packed("UYVY422", 16);
+      return i;
+    }
+    case VideoPixelFormat::YUYV422:
+    {
+      static constexpr auto i = makeYuv422Packed("YUYV422", 16);
+      return i;
+    }
+    case VideoPixelFormat::YVYU422:
+    {
+      static constexpr auto i = makeYuv422Packed("YVYU422", 16);
+      return i;
+    }
+    case VideoPixelFormat::VYUY422:
+    {
+      static constexpr auto i = makeYuv422Packed("VYUY422", 16);
+      return i;
+    }
+    case VideoPixelFormat::V210:
+    {
+      // V210 effective bits-per-pixel: 16 bytes / 6 pixels = 21.33 bpp.
+      // Round up to 22 for byte calc; the real stride formula is
+      // separate in defaultStride().
+      static constexpr auto i = makeYuv422Packed("V210", 22, 128);
+      return i;
+    }
+    case VideoPixelFormat::V216:
+    {
+      static constexpr auto i = makeYuv422Packed("V216", 32);
+      return i;
+    }
+    case VideoPixelFormat::NV12:
+    {
+      static constexpr auto i = makeNv12("NV12", 12);
+      return i;
+    }
+    case VideoPixelFormat::P010:
+    {
+      static constexpr auto i = makeNv12("P010", 24);
+      return i;
+    }
+    case VideoPixelFormat::P210:
+    {
+      static constexpr auto i = makeNv16("P210", 32);
+      return i;
+    }
+    case VideoPixelFormat::YUV420P:
+    {
+      static constexpr auto i = makePlanar("YUV420P", 12, 2, 2);
+      return i;
+    }
+    case VideoPixelFormat::YUV420P10:
+    {
+      static constexpr auto i = makePlanar("YUV420P10", 24, 2, 2);
+      return i;
+    }
+    case VideoPixelFormat::YUV422P:
+    {
+      static constexpr auto i = makePlanar("YUV422P", 16, 2, 1);
+      return i;
+    }
+    case VideoPixelFormat::YUV422P10:
+    {
+      static constexpr auto i = makePlanar("YUV422P10", 32, 2, 1);
+      return i;
+    }
+    case VideoPixelFormat::YUV444P:
+    {
+      static constexpr auto i = makePlanar("YUV444P", 24, 1, 1);
+      return i;
+    }
+    case VideoPixelFormat::YUV444P10:
+    {
+      static constexpr auto i = makePlanar("YUV444P10", 48, 1, 1);
+      return i;
+    }
+    case VideoPixelFormat::YUV444P12:
+    {
+      static constexpr auto i = makePlanar("YUV444P12", 48, 1, 1);
+      return i;
+    }
+    case VideoPixelFormat::RGBA16:
+    {
+      static constexpr auto i = makeRgb("RGBA16", 64);
+      return i;
+    }
+    case VideoPixelFormat::RGBA16F:
+    {
+      static constexpr auto i = makeRgb("RGBA16F", 64);
+      return i;
+    }
+    case VideoPixelFormat::RGBA32F:
+    {
+      static constexpr auto i = makeRgb("RGBA32F", 128);
+      return i;
+    }
+    case VideoPixelFormat::Mono8:
+    {
+      static constexpr auto i = makeMono("Mono8", 8);
+      return i;
+    }
+    case VideoPixelFormat::Mono10:
+    {
+      static constexpr auto i = makeMono("Mono10", 16);
+      return i;
+    }
+    case VideoPixelFormat::Mono12:
+    {
+      static constexpr auto i = makeMono("Mono12", 16);
+      return i;
+    }
+    case VideoPixelFormat::Mono16:
+    {
+      static constexpr auto i = makeMono("Mono16", 16);
+      return i;
+    }
+    case VideoPixelFormat::BayerRG8:
+    {
+      static constexpr auto i = makeMono("BayerRG8", 8);
+      return i;
+    }
+    case VideoPixelFormat::BayerRG12:
+    {
+      static constexpr auto i = makeMono("BayerRG12", 16);
+      return i;
+    }
+    case VideoPixelFormat::Unknown:
+      break;
+  }
+  return kUnknown;
+}
+
+const char* formatName(VideoPixelFormat f) noexcept
+{
+  return formatInfo(f).name;
+}
+
+std::size_t defaultStride(VideoPixelFormat f, uint32_t width) noexcept
+{
+  // V210 has a non-trivial stride formula per SMPTE 296M.
+  if(f == VideoPixelFormat::V210)
+    return alignUp(((std::size_t(width) + 47u) / 48u) * 128u, 128u);
+
+  const auto& info = formatInfo(f);
+  if(info.bitsPerPixel == 0)
+    return 0;
+  // Planar/semi-planar: the primary (luma) plane row is
+  // width * bytesPerPrimarySample — NOT width * average-bpp/8, which
+  // over-computes (NV12 1.5×, P010 3×). Packed formats have no separate
+  // primary plane, so they keep width * bitsPerPixel/8.
+  const std::size_t bytesPerRow
+      = (info.isPlanar && info.bytesPerPrimarySample > 0)
+            ? std::size_t(width) * info.bytesPerPrimarySample
+            : (std::size_t(width) * info.bitsPerPixel + 7u) / 8u;
+  return alignUp(bytesPerRow, info.defaultStrideAlignment);
+}
+
+std::size_t bytesPerFrame(
+    VideoPixelFormat f, uint32_t width, uint32_t height) noexcept
+{
+  const auto& info = formatInfo(f);
+  if(info.bitsPerPixel == 0 || width == 0 || height == 0)
+    return 0;
+
+  if(!info.isPlanar)
+    return defaultStride(f, width) * height;
+
+  // Multi-plane: primary plane = width × height; chroma planes scaled
+  // by subsampling factors. NV12-shape (semi-planar) gathers UV into a
+  // single interleaved plane of half height.
+  const std::size_t yBytes = defaultStride(f, width) * height;
+  const std::size_t cWidth = width / info.horizontalSubsampling;
+  const std::size_t cHeight = height / info.verticalSubsampling;
+  if(info.planeCount == 2)
+    return yBytes + defaultStride(f, uint32_t(cWidth * 2u)) * cHeight; // NV-style: interleaved UV
+  if(info.planeCount == 3)
+  {
+    const std::size_t cBytes = defaultStride(f, uint32_t(cWidth)) * cHeight;
+    return yBytes + 2u * cBytes;
+  }
+  return yBytes;
+}
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
new file mode 100644
index 0000000000..1d9655a97d
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -0,0 +1,160 @@
+#pragma once
+
+/**
+ * @file VideoPixelFormat.hpp
+ * @brief Vendor-neutral pixel format enum + descriptive metadata.
+ *
+ * Capture/output cards each have their own pixel-format enums:
+ * AJA `NTV2FrameBufferFormat`, DeckLink `BMDPixelFormat`, Magewell
+ * `MWFOURCC`, Rivermax SDP-derived sample types, Ximea `XI_IMG_FORMAT`.
+ * Strategies translate between vendor enums and score's internal
+ * representation; without a central enum every strategy reinvents the
+ * mapping table.
+ *
+ * This file provides:
+ *
+ *   - `VideoPixelFormat` — exhaustive enum of formats score handles
+ *     (packed RGB, packed YUV, planar YUV, 10/12-bit variants, etc).
+ *   - `VideoPixelFormatInfo` — descriptive struct with bytes-per-pixel
+ *     equivalent, plane count, subsampling, default stride alignment,
+ *     and a human-readable name.
+ *   - Helpers: `formatInfo()`, `defaultStride()`, `formatName()`,
+ *     `bytesPerFrame()`.
+ *
+ * Vendor-specific translation tables (e.g. `bmdFormatTo(...)`,
+ * `ntv2FormatTo(...)`) live in each vendor's addon to avoid pulling
+ * vendor headers into score-plugin-gfx.
+ *
+ * Eventually this header may move to a `score-lib-video` library when
+ * one exists; for now it lives under `score::gfx::interop` since
+ * score-plugin-gfx is the universal dependency.
+ */
+
+#include <score_plugin_gfx_export.h>
+
+#include <cstddef>
+#include <cstdint>
+
+namespace score::gfx::interop
+{
+
+/** Comprehensive pixel format enum covering every flavour score's
+ *  vendor strategies need. Values are stable; reorder only with
+ *  serialization migration. */
+enum class VideoPixelFormat : uint16_t
+{
+  Unknown = 0,
+
+  // -- Packed 8-bit RGB ------------------------------------------------
+  BGRA8 = 1,      /**< Most common; matches QRhi BGRA8 + DeckLink bmdFormat8BitBGRA. */
+  RGBA8 = 2,
+  ARGB8 = 3,
+  ABGR8 = 4,
+  RGB24 = 5,      /**< Packed 24-bit, byte order R,G,B (3 bpp). */
+  BGR24 = 6,      /**< Packed 24-bit, byte order B,G,R (3 bpp). */
+
+  // -- Packed 10/12-bit RGB --------------------------------------------
+  R210 = 10,      /**< DeckLink r210 / AV_CODEC_ID_R210: word
+                       (R<<20)|(G<<10)|B, 4 bytes/pixel, big-endian. */
+  R12B = 11,      /**< 12-bit RGB big-endian, AJA + DeckLink. */
+  R12L = 12,      /**< 12-bit RGB little-endian. */
+  ARGB10 = 13,    /**< A2R10G10B10 packed (AJA NTV2_FBF_10BIT_ARGB). */
+  DPX10 = 14,     /**< 10-bit RGB DPX/Cineon, big-endian (AJA NTV2_FBF_10BIT_DPX). */
+  DPX10LE = 15,   /**< 10-bit RGB DPX/Cineon, little-endian. */
+  RGB12P = 16,    /**< 12-bit RGB packed, 2px/9 bytes (AJA NTV2_FBF_12BIT_RGB_PACKED). */
+  RGB48 = 17,     /**< 16-bit-per-channel RGB, no alpha (AJA NTV2_FBF_48BIT_RGB). */
+  RGB10 = 18,     /**< AJA NTV2_FBF_10BIT_RGB: word (B<<20)|(G<<10)|R, LE.
+                       Distinct from R210 (DeckLink r210: R high, BE). */
+
+  // -- Packed 8-bit YUV 4:2:2 -----------------------------------------
+  UYVY422 = 20,   /**< Most common SDI; 16-bpp packed UYVY. */
+  YUYV422 = 21,
+  YVYU422 = 22,
+  VYUY422 = 23,
+
+  // -- Packed 10-bit YUV 4:2:2 ----------------------------------------
+  V210 = 30,      /**< SMPTE 296M; 6 pixels packed into 16 bytes. */
+  V216 = 31,      /**< 16-bit per channel; 4:2:2. */
+
+  // -- Planar 4:2:0 ----------------------------------------------------
+  NV12 = 40,      /**< Y plane + interleaved UV plane; HEVC standard. */
+  P010 = 41,      /**< NV12 with 10-bit upshifted to 16-bit lanes. */
+  YUV420P = 42,   /**< Three-plane 4:2:0; FFmpeg standard. */
+  YUV420P10 = 43, /**< Three-plane 4:2:0, 10-bit (AJA NTV2_FBF_10BIT_YCBCR_420PL3_LE). */
+
+  // -- Planar 4:2:2 ----------------------------------------------------
+  P210 = 50,      /**< NV12-shape with 4:2:2 sub-sampling at 10-bit. */
+  YUV422P = 51,
+  YUV422P10 = 52,
+
+  // -- Planar 4:4:4 ----------------------------------------------------
+  YUV444P = 60,
+  YUV444P10 = 61,
+  YUV444P12 = 62,
+
+  // -- High-precision RGB ----------------------------------------------
+  RGBA16 = 70,    /**< 16-bit per channel integer RGBA. */
+  RGBA16F = 71,   /**< 16-bit half-float per channel. */
+  RGBA32F = 72,   /**< 32-bit float per channel. */
+
+  // -- Raw / Bayer (industrial cameras) -------------------------------
+  Mono8 = 80,
+  Mono10 = 81,
+  Mono12 = 82,
+  Mono16 = 83,
+  BayerRG8 = 84,
+  BayerRG12 = 85,
+};
+
+/** Sample arrangement description. Three plane counts cover everything
+ *  the matrix vendors emit:
+ *   - 1: packed (BGRA8, UYVY, V210, R210, Mono*)
+ *   - 2: semi-planar (NV12, P010, P210)
+ *   - 3: fully planar (YUV420P, YUV422P, etc) */
+struct VideoPixelFormatInfo
+{
+  const char* name{"unknown"};
+  uint8_t bitsPerPixel{};       /**< Average; 12 for NV12, 16 for UYVY, 20 for V210 effective. */
+  uint8_t planeCount{1};
+  uint8_t horizontalSubsampling{1}; /**< Chroma subsampling: 1 for 4:4:4, 2 for 4:2:2, 2 for 4:2:0. */
+  uint8_t verticalSubsampling{1};   /**< 1 for 4:2:2, 2 for 4:2:0. */
+  bool isYuv{};
+  bool isPlanar{};
+  uint16_t defaultStrideAlignment{256}; /**< Bytes; vendors typically need 128 or 256. */
+  /**< Bytes of ONE primary-plane (luma) sample: 1 for 8-bit planar
+   *   (NV12, YUV420P), 2 for 10/16-bit planar (P010, P210, YUV420P10).
+   *   0 for packed formats, where the primary-plane stride is
+   *   width*bitsPerPixel/8. Using the average bitsPerPixel for a planar
+   *   primary plane over-computes its stride (NV12 1.5×, P010 3×). */
+  uint8_t bytesPerPrimarySample{0};
+};
+
+/** Round `v` up to the next multiple of `a` (`a` must be a power of two). */
+constexpr std::size_t alignUp(std::size_t v, std::size_t a) noexcept
+{
+  return (v + a - 1) & ~(a - 1);
+}
+
+/** Get the descriptive info for `f`. Returns a static reference; the
+ *  pointer is stable for the duration of the program. */
+SCORE_PLUGIN_GFX_EXPORT
+const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept;
+
+/** Human-readable short name, e.g. "UYVY422", "V210". */
+SCORE_PLUGIN_GFX_EXPORT
+const char* formatName(VideoPixelFormat f) noexcept;
+
+/** Compute the default row stride in bytes for `f` at the given
+ *  `width`. The result is rounded up to `formatInfo(f).defaultStrideAlignment`.
+ *  Vendor-specific stride rules (V210's `(width+47)/48*128`) are baked
+ *  into this function for the cases that need it. */
+SCORE_PLUGIN_GFX_EXPORT
+std::size_t defaultStride(VideoPixelFormat f, uint32_t width) noexcept;
+
+/** Total byte size of one frame at `width × height` in format `f`.
+ *  Accounts for plane count + subsampling. */
+SCORE_PLUGIN_GFX_EXPORT
+std::size_t bytesPerFrame(
+    VideoPixelFormat f, uint32_t width, uint32_t height) noexcept;
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
new file mode 100644
index 0000000000..c745dfa9ca
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
@@ -0,0 +1,103 @@
+#include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
+
+namespace score::gfx::interop
+{
+
+AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
+{
+  using V = VideoPixelFormat;
+  switch(f)
+  {
+    // -- packed 8-bit RGB --
+    case V::BGRA8:     return AV_PIX_FMT_BGRA;
+    case V::RGBA8:     return AV_PIX_FMT_RGBA;
+    case V::ARGB8:     return AV_PIX_FMT_ARGB;
+    case V::ABGR8:     return AV_PIX_FMT_ABGR;
+    case V::RGB24:     return AV_PIX_FMT_RGB24;
+    case V::BGR24:     return AV_PIX_FMT_BGR24;
+
+    // -- high-precision RGB --
+    case V::RGB48:     return AV_PIX_FMT_RGB48LE;  // AJA 48BIT_RGB is 16-bit LE
+    case V::RGBA16:    return AV_PIX_FMT_RGBA64LE;
+
+    // -- packed 8-bit YUV 4:2:2 --
+    case V::UYVY422:   return AV_PIX_FMT_UYVY422;
+    case V::YUYV422:   return AV_PIX_FMT_YUYV422;
+    case V::YVYU422:   return AV_PIX_FMT_YVYU422;
+
+    // -- planar / semi-planar YUV --
+    case V::NV12:      return AV_PIX_FMT_NV12;
+    case V::P010:      return AV_PIX_FMT_P010LE;
+    case V::P210:      return AV_PIX_FMT_P210LE;
+    case V::YUV420P:   return AV_PIX_FMT_YUV420P;
+    case V::YUV420P10: return AV_PIX_FMT_YUV420P10LE;
+    case V::YUV422P:   return AV_PIX_FMT_YUV422P;
+    case V::YUV422P10: return AV_PIX_FMT_YUV422P10LE;
+    case V::YUV444P:   return AV_PIX_FMT_YUV444P;
+    case V::YUV444P10: return AV_PIX_FMT_YUV444P10LE;
+    case V::YUV444P12: return AV_PIX_FMT_YUV444P12LE;
+
+    // -- grey --
+    case V::Mono8:     return AV_PIX_FMT_GRAY8;
+    case V::Mono10:    return AV_PIX_FMT_GRAY10LE;
+    case V::Mono12:    return AV_PIX_FMT_GRAY12LE;
+    case V::Mono16:    return AV_PIX_FMT_GRAY16LE;
+
+    // -- wire-only: no AVPixelFormat (FFmpeg models these as codecs) --
+    case V::V210:      // AV_CODEC_ID_V210
+    case V::V216:      // AV_CODEC_ID_V210X
+    case V::R210:      // AV_CODEC_ID_R210 (big-endian, R high)
+    case V::RGB10:     // AJA NTV2_FBF_10BIT_RGB (little-endian, B high)
+    case V::R12B:      // AV_CODEC_ID_DPX
+    case V::R12L:
+    case V::ARGB10:    // A2R10G10B10 packed
+    case V::DPX10:
+    case V::DPX10LE:
+    case V::RGB12P:
+    case V::VYUY422:   // no AV_PIX_FMT_VYUY
+    // -- no clean/unambiguous AVPixelFormat twin --
+    case V::RGBA16F:   // no packed half-float RGBA pixfmt
+    case V::RGBA32F:   // no packed float RGBA pixfmt (GBRPF32 is planar)
+    case V::BayerRG8:  // Bayer order differs per sensor; keep explicit
+    case V::BayerRG12:
+    case V::Unknown:
+      return AV_PIX_FMT_NONE;
+  }
+  return AV_PIX_FMT_NONE;
+}
+
+VideoPixelFormat fromAVPixelFormat(AVPixelFormat f) noexcept
+{
+  using V = VideoPixelFormat;
+  switch(f)
+  {
+    case AV_PIX_FMT_BGRA:        return V::BGRA8;
+    case AV_PIX_FMT_RGBA:        return V::RGBA8;
+    case AV_PIX_FMT_ARGB:        return V::ARGB8;
+    case AV_PIX_FMT_ABGR:        return V::ABGR8;
+    case AV_PIX_FMT_RGB24:       return V::RGB24;
+    case AV_PIX_FMT_BGR24:       return V::BGR24;
+    case AV_PIX_FMT_RGB48LE:     return V::RGB48;
+    case AV_PIX_FMT_RGBA64LE:    return V::RGBA16;
+    case AV_PIX_FMT_UYVY422:     return V::UYVY422;
+    case AV_PIX_FMT_YUYV422:     return V::YUYV422;
+    case AV_PIX_FMT_YVYU422:     return V::YVYU422;
+    case AV_PIX_FMT_NV12:        return V::NV12;
+    case AV_PIX_FMT_P010LE:      return V::P010;
+    case AV_PIX_FMT_P210LE:      return V::P210;
+    case AV_PIX_FMT_YUV420P:     return V::YUV420P;
+    case AV_PIX_FMT_YUV420P10LE: return V::YUV420P10;
+    case AV_PIX_FMT_YUV422P:     return V::YUV422P;
+    case AV_PIX_FMT_YUV422P10LE: return V::YUV422P10;
+    case AV_PIX_FMT_YUV444P:     return V::YUV444P;
+    case AV_PIX_FMT_YUV444P10LE: return V::YUV444P10;
+    case AV_PIX_FMT_YUV444P12LE: return V::YUV444P12;
+    case AV_PIX_FMT_GRAY8:       return V::Mono8;
+    case AV_PIX_FMT_GRAY10LE:    return V::Mono10;
+    case AV_PIX_FMT_GRAY12LE:    return V::Mono12;
+    case AV_PIX_FMT_GRAY16LE:    return V::Mono16;
+    default:                     return V::Unknown;
+  }
+}
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.hpp
new file mode 100644
index 0000000000..62259a383d
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.hpp
@@ -0,0 +1,56 @@
+#pragma once
+
+/**
+ * @file VideoPixelFormatAV.hpp
+ * @brief Bridge between the wire-format enum `VideoPixelFormat` and libav's
+ *        `AVPixelFormat`.
+ *
+ * Why two enums exist (and why we can't just use AVPixelFormat everywhere):
+ * the SDI/HDMI capture cards carry several *packed wire formats* that FFmpeg
+ * does NOT model as pixel formats — it models them as **codecs** that decode
+ * into a planar AVPixelFormat:
+ *
+ *   v210      -> AV_CODEC_ID_V210  (decodes to yuv422p10le) — no AV_PIX_FMT_V210
+ *   v216      -> AV_CODEC_ID_V210X (yuv422p16)              — no AV_PIX_FMT
+ *   r210/RGB10-> AV_CODEC_ID_R210/R10K (gbrp10/rgb48)       — no exact AV_PIX_FMT
+ *   DPX 10/12 -> AV_CODEC_ID_DPX                            — no AV_PIX_FMT
+ *   12-bit packed RGB, A2-ARGB10                            — no AV_PIX_FMT
+ *
+ * Those are exactly the formats capture cards put on the wire, so a wire-format
+ * enum is unavoidable. But the *buffer* formats (planar/semi-planar YUV, packed
+ * 8-bit RGB, 16-bit RGB, grey) all have AVPixelFormat twins; this bridge maps
+ * them so:
+ *   - the capture path can derive a `VideoPixelFormat` from the
+ *     `Video::ImageFormat::pixel_format` (an AVPixelFormat) it already carries;
+ *   - vendor format tables can interop with the libav-based decoder/encoder
+ *     paths for the representable subset, with a single source of truth for the
+ *     overlap instead of each site re-deriving it.
+ *
+ * `toAVPixelFormat` returns `AV_PIX_FMT_NONE` for the wire-only formats (the
+ * caller keeps using `VideoPixelFormat` for those). `fromAVPixelFormat` returns
+ * `VideoPixelFormat::Unknown` for AVPixelFormats with no wire-format equivalent.
+ */
+
+#include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+
+#include <score_plugin_gfx_export.h>
+
+extern "C" {
+#include <libavutil/pixfmt.h>
+}
+
+namespace score::gfx::interop
+{
+
+/// Map a wire format to its byte-identical AVPixelFormat, or AV_PIX_FMT_NONE if
+/// FFmpeg has no pixel-format for it (v210/v216/DPX/r210/12-bit-packed/A2-ARGB10
+/// — those are codecs in FFmpeg, not pixel formats).
+SCORE_PLUGIN_GFX_EXPORT
+AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept;
+
+/// Map an AVPixelFormat back to a wire format, or VideoPixelFormat::Unknown if
+/// it isn't one of the capture-card wire formats.
+SCORE_PLUGIN_GFX_EXPORT
+VideoPixelFormat fromAVPixelFormat(AVPixelFormat f) noexcept;
+
+} // namespace score::gfx::interop

From 6e454de3730727778cfcdbd6cb40e22a779ef962 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Wed, 29 Jul 2026 22:49:21 -0400
Subject: [PATCH 05/20] gfx: generate the pixel-format vocabulary from one
 declarative table

The enum, the descriptor table and the name lookup were three hand-maintained
lists of the same thing, so they could disagree - and did: a format could be
declared in the enum with no descriptor at all, leaving formatInfo() returning
the "unknown" sentinel and bytesPerFrame() returning 0 for it.

Generate all of them from a single X-macro table instead. Adding a row adds the
enum value, the descriptor and the entry allFormats() exposes at once, so
declaring a format without describing it is no longer expressible.

Two modelling changes come with it:

- Sizing is block-based (blockPixels/blockBytes) rather than an averaged
  bits-per-pixel. The average could not express v210 at all - 128 bytes per 48
  pixels is 21.33 bits, which was truncated into a uint8_t and then special
  cased in the stride function - and it over-computed planar strides, which is
  why a separate bytesPerPrimarySample field had to exist alongside it. One
  block spec covers packed, semi-planar and planar uniformly, and v210 s SMPTE
  stride now falls out of the general expression.

- bool isYuv becomes a ColorModel enum, because greyscale and Bayer are neither
  YUV nor RGB, and both are produced by the industrial-camera paths. hasAlpha
  and byteOrder become queryable instead of living in prose: "forced opaque" and
  the endianness of the 10/12-bit layouts were only recorded in comments.

defaultStrideAlignment is renamed preferredStrideAlignment and documented as a
fallback for callers with no constraint of their own: alignment is a property of
a device or allocator, not of a pixel format. alignedRowBytes() is the form
device paths should use, and rowBytes() gives the unpadded row.

Verified size-identical: a dump of stride at 64/720/1920/1921/3840/7680 and
frame size at 720p/1080p for all 40 formats is byte-for-byte unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 .../Gfx/Graph/interop/VideoPixelFormat.cpp    | 367 ++++--------------
 .../Gfx/Graph/interop/VideoPixelFormat.hpp    | 312 +++++++++------
 2 files changed, 282 insertions(+), 397 deletions(-)

diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
index cdc8f8dda9..a2f98392f7 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
@@ -1,4 +1,5 @@
 #include "VideoPixelFormat.hpp"
+#include <iterator>
 
 namespace score::gfx::interop
 {
@@ -6,321 +7,113 @@ namespace score::gfx::interop
 namespace
 {
 
-constexpr VideoPixelFormatInfo kUnknown{
-    "unknown", 0, 1, 1, 1, false, false, 256};
+constexpr VideoPixelFormatInfo kUnknown{};
+
+// The descriptor array, generated from the one declarative table. Adding a
+// format to the table adds it here, to the enum, and to what the unit test
+// sweeps, all at once -- there is no second list to forget.
+#define SCORE_VPF_INFO_ROW(                                                    \
+    Name, Value, Model, Planes, Hsub, Vsub, BlockPixels, BlockBytes, Alpha,    \
+    Order, Align)                                                              \
+  VideoPixelFormatInfo{                                                        \
+      #Name,                                                                   \
+      VideoPixelFormat::Name,                                                  \
+      ColorModel::Model,                                                       \
+      Planes,                                                                  \
+      Hsub,                                                                    \
+      Vsub,                                                                    \
+      BlockPixels,                                                             \
+      BlockBytes,                                                              \
+      Alpha,                                                                   \
+      ByteOrder::Order,                                                        \
+      Align},
+
+constexpr VideoPixelFormatInfo kFormats[]{
+    SCORE_VIDEO_PIXEL_FORMATS(SCORE_VPF_INFO_ROW)};
+
+#undef SCORE_VPF_INFO_ROW
+
+static_assert(
+    std::size(kFormats) == formatCount(),
+    "descriptor array and formatCount() must both come from the table");
 
-constexpr VideoPixelFormatInfo
-makeRgb(const char* name, uint8_t bpp, uint16_t align = 256) noexcept
-{
-  return VideoPixelFormatInfo{name, bpp, 1, 1, 1, false, false, align};
-}
-
-constexpr VideoPixelFormatInfo makeYuv422Packed(const char* name,
-                                                uint8_t bpp,
-                                                uint16_t align = 256) noexcept
-{
-  return VideoPixelFormatInfo{name, bpp, 1, 2, 1, true, false, align};
-}
-
-constexpr VideoPixelFormatInfo makeNv12(const char* name, uint8_t bpp) noexcept
-{
-  // 4:2:0 semi-planar. Primary-sample bytes = bpp / (8 + 16/(hs*vs)) =
-  // bpp/12 here: exact for NV12 (12→1) and P010 (24→2).
-  return VideoPixelFormatInfo{name, bpp, 2, 2, 2, true, true, 256,
-                              uint8_t(bpp / 12u)};
-}
+} // namespace
 
-constexpr VideoPixelFormatInfo makeNv16(const char* name, uint8_t bpp) noexcept
+const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept
 {
-  // 4:2:2 semi-planar. bpp/16: exact for P210 (32→2).
-  return VideoPixelFormatInfo{name, bpp, 2, 2, 1, true, true, 256,
-                              uint8_t(bpp / 16u)};
+  // Linear scan over a small constexpr array. The values are sparse (1..100 for
+  // ~70 formats) so a direct-indexed table would be mostly holes, and this runs
+  // at setup time, not per frame.
+  for(const auto& i : kFormats)
+    if(i.format == f)
+      return i;
+  return kUnknown;
 }
 
-constexpr VideoPixelFormatInfo
-makePlanar(const char* name, uint8_t bpp, uint8_t hs, uint8_t vs) noexcept
+const char* formatName(VideoPixelFormat f) noexcept
 {
-  // Fully planar. Primary-sample bytes = bpp / (8 + 16/(hs*vs)); exact
-  // for all 4:2:0 / 4:2:2 / 4:4:4 8/10/12-bit variants.
-  return VideoPixelFormatInfo{name, bpp, 3, hs, vs, true, true, 256,
-                              uint8_t(bpp / (8u + 16u / (uint32_t(hs) * vs)))};
+  return formatInfo(f).name;
 }
 
-constexpr VideoPixelFormatInfo makeMono(const char* name, uint8_t bpp) noexcept
+const VideoPixelFormatInfo* allFormats(std::size_t& count) noexcept
 {
-  return VideoPixelFormatInfo{name, bpp, 1, 1, 1, false, false, 64};
+  count = std::size(kFormats);
+  return kFormats;
 }
 
-} // namespace
-
-const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept
+std::size_t rowBytes(VideoPixelFormat f, uint32_t width) noexcept
 {
-  // The clang-friendly approach: declare each info in a switch and
-  // return a reference to a static-local. Keeps the data localized
-  // with each enum value.
-  switch(f)
-  {
-    case VideoPixelFormat::BGRA8:
-    {
-      static constexpr auto i = makeRgb("BGRA8", 32);
-      return i;
-    }
-    case VideoPixelFormat::RGBA8:
-    {
-      static constexpr auto i = makeRgb("RGBA8", 32);
-      return i;
-    }
-    case VideoPixelFormat::ARGB8:
-    {
-      static constexpr auto i = makeRgb("ARGB8", 32);
-      return i;
-    }
-    case VideoPixelFormat::ABGR8:
-    {
-      static constexpr auto i = makeRgb("ABGR8", 32);
-      return i;
-    }
-    case VideoPixelFormat::RGB24:
-    {
-      static constexpr auto i = makeRgb("RGB24", 24, 64);
-      return i;
-    }
-    case VideoPixelFormat::BGR24:
-    {
-      static constexpr auto i = makeRgb("BGR24", 24, 64);
-      return i;
-    }
-    case VideoPixelFormat::R210:
-    {
-      static constexpr auto i = makeRgb("R210", 32, 256);
-      return i;
-    }
-    case VideoPixelFormat::R12B:
-    {
-      static constexpr auto i = makeRgb("R12B", 36, 256);
-      return i;
-    }
-    case VideoPixelFormat::R12L:
-    {
-      static constexpr auto i = makeRgb("R12L", 36, 256);
-      return i;
-    }
-    case VideoPixelFormat::ARGB10:
-    {
-      // 4×10-bit channels packed into 5 bytes/pixel (see PackedRGB::argb10,
-      // 40 bits). Declaring 32 here under-sized the stride by 20% → the
-      // encoder's readback wrote past DMA/ring allocations sized from it.
-      static constexpr auto i = makeRgb("ARGB10", 40, 256);
-      return i;
-    }
-    case VideoPixelFormat::DPX10:
-    {
-      static constexpr auto i = makeRgb("DPX10", 32, 256);
-      return i;
-    }
-    case VideoPixelFormat::DPX10LE:
-    {
-      static constexpr auto i = makeRgb("DPX10LE", 32, 256);
-      return i;
-    }
-    case VideoPixelFormat::RGB12P:
-    {
-      static constexpr auto i = makeRgb("RGB12P", 36, 256);
-      return i;
-    }
-    case VideoPixelFormat::RGB48:
-    {
-      static constexpr auto i = makeRgb("RGB48", 48, 256);
-      return i;
-    }
-    case VideoPixelFormat::RGB10:
-    {
-      static constexpr auto i = makeRgb("RGB10", 32, 256);
-      return i;
-    }
-    case VideoPixelFormat::UYVY422:
-    {
-      static constexpr auto i = makeYuv422Packed("UYVY422", 16);
-      return i;
-    }
-    case VideoPixelFormat::YUYV422:
-    {
-      static constexpr auto i = makeYuv422Packed("YUYV422", 16);
-      return i;
-    }
-    case VideoPixelFormat::YVYU422:
-    {
-      static constexpr auto i = makeYuv422Packed("YVYU422", 16);
-      return i;
-    }
-    case VideoPixelFormat::VYUY422:
-    {
-      static constexpr auto i = makeYuv422Packed("VYUY422", 16);
-      return i;
-    }
-    case VideoPixelFormat::V210:
-    {
-      // V210 effective bits-per-pixel: 16 bytes / 6 pixels = 21.33 bpp.
-      // Round up to 22 for byte calc; the real stride formula is
-      // separate in defaultStride().
-      static constexpr auto i = makeYuv422Packed("V210", 22, 128);
-      return i;
-    }
-    case VideoPixelFormat::V216:
-    {
-      static constexpr auto i = makeYuv422Packed("V216", 32);
-      return i;
-    }
-    case VideoPixelFormat::NV12:
-    {
-      static constexpr auto i = makeNv12("NV12", 12);
-      return i;
-    }
-    case VideoPixelFormat::P010:
-    {
-      static constexpr auto i = makeNv12("P010", 24);
-      return i;
-    }
-    case VideoPixelFormat::P210:
-    {
-      static constexpr auto i = makeNv16("P210", 32);
-      return i;
-    }
-    case VideoPixelFormat::YUV420P:
-    {
-      static constexpr auto i = makePlanar("YUV420P", 12, 2, 2);
-      return i;
-    }
-    case VideoPixelFormat::YUV420P10:
-    {
-      static constexpr auto i = makePlanar("YUV420P10", 24, 2, 2);
-      return i;
-    }
-    case VideoPixelFormat::YUV422P:
-    {
-      static constexpr auto i = makePlanar("YUV422P", 16, 2, 1);
-      return i;
-    }
-    case VideoPixelFormat::YUV422P10:
-    {
-      static constexpr auto i = makePlanar("YUV422P10", 32, 2, 1);
-      return i;
-    }
-    case VideoPixelFormat::YUV444P:
-    {
-      static constexpr auto i = makePlanar("YUV444P", 24, 1, 1);
-      return i;
-    }
-    case VideoPixelFormat::YUV444P10:
-    {
-      static constexpr auto i = makePlanar("YUV444P10", 48, 1, 1);
-      return i;
-    }
-    case VideoPixelFormat::YUV444P12:
-    {
-      static constexpr auto i = makePlanar("YUV444P12", 48, 1, 1);
-      return i;
-    }
-    case VideoPixelFormat::RGBA16:
-    {
-      static constexpr auto i = makeRgb("RGBA16", 64);
-      return i;
-    }
-    case VideoPixelFormat::RGBA16F:
-    {
-      static constexpr auto i = makeRgb("RGBA16F", 64);
-      return i;
-    }
-    case VideoPixelFormat::RGBA32F:
-    {
-      static constexpr auto i = makeRgb("RGBA32F", 128);
-      return i;
-    }
-    case VideoPixelFormat::Mono8:
-    {
-      static constexpr auto i = makeMono("Mono8", 8);
-      return i;
-    }
-    case VideoPixelFormat::Mono10:
-    {
-      static constexpr auto i = makeMono("Mono10", 16);
-      return i;
-    }
-    case VideoPixelFormat::Mono12:
-    {
-      static constexpr auto i = makeMono("Mono12", 16);
-      return i;
-    }
-    case VideoPixelFormat::Mono16:
-    {
-      static constexpr auto i = makeMono("Mono16", 16);
-      return i;
-    }
-    case VideoPixelFormat::BayerRG8:
-    {
-      static constexpr auto i = makeMono("BayerRG8", 8);
-      return i;
-    }
-    case VideoPixelFormat::BayerRG12:
-    {
-      static constexpr auto i = makeMono("BayerRG12", 16);
-      return i;
-    }
-    case VideoPixelFormat::Unknown:
-      break;
-  }
-  return kUnknown;
+  const auto& info = formatInfo(f);
+  if(!info.valid() || width == 0)
+    return 0;
+  // Whole blocks only: a partial block still occupies its full width, which is
+  // what makes v210's SMPTE stride (48 pixels per 128 bytes) fall out of the
+  // same expression as everything else.
+  const std::size_t blocks
+      = (std::size_t(width) + info.blockPixels - 1u) / info.blockPixels;
+  return blocks * info.blockBytes;
 }
 
-const char* formatName(VideoPixelFormat f) noexcept
+std::size_t alignedRowBytes(
+    VideoPixelFormat f, uint32_t width, std::size_t alignment) noexcept
 {
-  return formatInfo(f).name;
+  return alignUp(rowBytes(f, width), alignment);
 }
 
 std::size_t defaultStride(VideoPixelFormat f, uint32_t width) noexcept
 {
-  // V210 has a non-trivial stride formula per SMPTE 296M.
-  if(f == VideoPixelFormat::V210)
-    return alignUp(((std::size_t(width) + 47u) / 48u) * 128u, 128u);
-
-  const auto& info = formatInfo(f);
-  if(info.bitsPerPixel == 0)
-    return 0;
-  // Planar/semi-planar: the primary (luma) plane row is
-  // width * bytesPerPrimarySample — NOT width * average-bpp/8, which
-  // over-computes (NV12 1.5×, P010 3×). Packed formats have no separate
-  // primary plane, so they keep width * bitsPerPixel/8.
-  const std::size_t bytesPerRow
-      = (info.isPlanar && info.bytesPerPrimarySample > 0)
-            ? std::size_t(width) * info.bytesPerPrimarySample
-            : (std::size_t(width) * info.bitsPerPixel + 7u) / 8u;
-  return alignUp(bytesPerRow, info.defaultStrideAlignment);
+  return alignedRowBytes(f, width, formatInfo(f).preferredStrideAlignment);
 }
 
-std::size_t bytesPerFrame(
-    VideoPixelFormat f, uint32_t width, uint32_t height) noexcept
+std::size_t
+bytesPerFrame(VideoPixelFormat f, uint32_t width, uint32_t height) noexcept
 {
   const auto& info = formatInfo(f);
-  if(info.bitsPerPixel == 0 || width == 0 || height == 0)
+  if(!info.valid() || width == 0 || height == 0)
     return 0;
 
-  if(!info.isPlanar)
-    return defaultStride(f, width) * height;
-
-  // Multi-plane: primary plane = width × height; chroma planes scaled
-  // by subsampling factors. NV12-shape (semi-planar) gathers UV into a
-  // single interleaved plane of half height.
   const std::size_t yBytes = defaultStride(f, width) * height;
-  const std::size_t cWidth = width / info.horizontalSubsampling;
-  const std::size_t cHeight = height / info.verticalSubsampling;
-  if(info.planeCount == 2)
-    return yBytes + defaultStride(f, uint32_t(cWidth * 2u)) * cHeight; // NV-style: interleaved UV
-  if(info.planeCount == 3)
+  if(!info.isPlanar())
+    return yBytes;
+
+  // Chroma planes are scaled by the subsampling factors and padded to the same
+  // preferred stride as luma. Semi-planar formats gather both chroma components
+  // into one plane of double width; fully planar ones use two separate planes,
+  // which comes to the same number of samples.
+  const auto cWidth = uint32_t(width / info.horizontalSubsampling);
+  const auto cHeight = std::size_t(height / info.verticalSubsampling);
+  switch(info.planeCount)
   {
-    const std::size_t cBytes = defaultStride(f, uint32_t(cWidth)) * cHeight;
-    return yBytes + 2u * cBytes;
+    case 2:
+      return yBytes + defaultStride(f, cWidth * 2u) * cHeight;
+    case 3:
+      return yBytes + 2u * (defaultStride(f, cWidth) * cHeight);
+    case 4:
+      // Planar with a full-resolution alpha plane.
+      return yBytes + 2u * (defaultStride(f, cWidth) * cHeight) + yBytes;
+    default:
+      return yBytes;
   }
-  return yBytes;
 }
 
 } // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
index 1d9655a97d..2918308869 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -2,32 +2,37 @@
 
 /**
  * @file VideoPixelFormat.hpp
- * @brief Vendor-neutral pixel format enum + descriptive metadata.
+ * @brief Vendor-neutral pixel format vocabulary + descriptive metadata.
  *
  * Capture/output cards each have their own pixel-format enums:
  * AJA `NTV2FrameBufferFormat`, DeckLink `BMDPixelFormat`, Magewell
- * `MWFOURCC`, Rivermax SDP-derived sample types, Ximea `XI_IMG_FORMAT`.
- * Strategies translate between vendor enums and score's internal
- * representation; without a central enum every strategy reinvents the
- * mapping table.
+ * `MWFOURCC`, V4L2 fourccs, DRM fourccs, PipeWire SPA formats, GStreamer
+ * format strings, Ximea `XI_IMG_FORMAT`. Strategies translate between those
+ * and score's internal representation; without a central vocabulary every
+ * strategy reinvents the mapping table, and they drift apart.
  *
- * This file provides:
+ * `AVPixelFormat` cannot serve as that vocabulary on its own: FFmpeg models
+ * several formats the SDI cards put on the wire as *codecs* rather than pixel
+ * formats (v210, v216, r210, DPX 10/12-bit, 12-bit packed RGB, A2-ARGB10), so
+ * they have no `AV_PIX_FMT_*` at all. `VideoPixelFormatAV.hpp` bridges the
+ * representable subset in both directions.
  *
- *   - `VideoPixelFormat` — exhaustive enum of formats score handles
- *     (packed RGB, packed YUV, planar YUV, 10/12-bit variants, etc).
- *   - `VideoPixelFormatInfo` — descriptive struct with bytes-per-pixel
- *     equivalent, plane count, subsampling, default stride alignment,
- *     and a human-readable name.
- *   - Helpers: `formatInfo()`, `defaultStride()`, `formatName()`,
- *     `bytesPerFrame()`.
+ * This vocabulary describes **sample layout only**. Colorimetry -- range,
+ * primaries, transfer characteristic, chroma siting, HDR metadata -- is a
+ * separate orthogonal axis, owned by `Video::ImageFormat`. Do not add colour
+ * fields here: a format says how bytes are arranged, not how to interpret the
+ * values in them.
  *
- * Vendor-specific translation tables (e.g. `bmdFormatTo(...)`,
- * `ntv2FormatTo(...)`) live in each vendor's addon to avoid pulling
- * vendor headers into score-plugin-gfx.
+ * Everything is generated from one declarative table,
+ * `SCORE_VIDEO_PIXEL_FORMATS`: the enum, the descriptor array, the name
+ * lookup, and the list the unit test sweeps. A format therefore cannot be
+ * declared without being described -- which is how 28 formats previously ended
+ * up declared with a zero-byte descriptor, so that `bytesPerFrame` silently
+ * returned 0 for them.
  *
- * Eventually this header may move to a `score-lib-video` library when
- * one exists; for now it lives under `score::gfx::interop` since
- * score-plugin-gfx is the universal dependency.
+ * Vendor-specific translation tables (e.g. `bmdFormatTo(...)`,
+ * `ntv2FormatTo(...)`) live in each vendor's addon to avoid pulling vendor
+ * headers into score-plugin-gfx.
  */
 
 #include <score_plugin_gfx_export.h>
@@ -38,105 +43,179 @@
 namespace score::gfx::interop
 {
 
-/** Comprehensive pixel format enum covering every flavour score's
- *  vendor strategies need. Values are stable; reorder only with
- *  serialization migration. */
-enum class VideoPixelFormat : uint16_t
+/** Which colour model the samples carry. A boolean "is YUV" cannot express
+ *  greyscale or Bayer, both of which the industrial-camera paths produce. */
+enum class ColorModel : uint8_t
 {
   Unknown = 0,
+  RGB,
+  YUV,
+  Grey,  /**< Single achromatic channel (Mono*). */
+  Bayer, /**< Undemosaiced colour-filter-array data (BayerRG*). */
+};
 
-  // -- Packed 8-bit RGB ------------------------------------------------
-  BGRA8 = 1,      /**< Most common; matches QRhi BGRA8 + DeckLink bmdFormat8BitBGRA. */
-  RGBA8 = 2,
-  ARGB8 = 3,
-  ABGR8 = 4,
-  RGB24 = 5,      /**< Packed 24-bit, byte order R,G,B (3 bpp). */
-  BGR24 = 6,      /**< Packed 24-bit, byte order B,G,R (3 bpp). */
-
-  // -- Packed 10/12-bit RGB --------------------------------------------
-  R210 = 10,      /**< DeckLink r210 / AV_CODEC_ID_R210: word
-                       (R<<20)|(G<<10)|B, 4 bytes/pixel, big-endian. */
-  R12B = 11,      /**< 12-bit RGB big-endian, AJA + DeckLink. */
-  R12L = 12,      /**< 12-bit RGB little-endian. */
-  ARGB10 = 13,    /**< A2R10G10B10 packed (AJA NTV2_FBF_10BIT_ARGB). */
-  DPX10 = 14,     /**< 10-bit RGB DPX/Cineon, big-endian (AJA NTV2_FBF_10BIT_DPX). */
-  DPX10LE = 15,   /**< 10-bit RGB DPX/Cineon, little-endian. */
-  RGB12P = 16,    /**< 12-bit RGB packed, 2px/9 bytes (AJA NTV2_FBF_12BIT_RGB_PACKED). */
-  RGB48 = 17,     /**< 16-bit-per-channel RGB, no alpha (AJA NTV2_FBF_48BIT_RGB). */
-  RGB10 = 18,     /**< AJA NTV2_FBF_10BIT_RGB: word (B<<20)|(G<<10)|R, LE.
-                       Distinct from R210 (DeckLink r210: R high, BE). */
-
-  // -- Packed 8-bit YUV 4:2:2 -----------------------------------------
-  UYVY422 = 20,   /**< Most common SDI; 16-bpp packed UYVY. */
-  YUYV422 = 21,
-  YVYU422 = 22,
-  VYUY422 = 23,
-
-  // -- Packed 10-bit YUV 4:2:2 ----------------------------------------
-  V210 = 30,      /**< SMPTE 296M; 6 pixels packed into 16 bytes. */
-  V216 = 31,      /**< 16-bit per channel; 4:2:2. */
-
-  // -- Planar 4:2:0 ----------------------------------------------------
-  NV12 = 40,      /**< Y plane + interleaved UV plane; HEVC standard. */
-  P010 = 41,      /**< NV12 with 10-bit upshifted to 16-bit lanes. */
-  YUV420P = 42,   /**< Three-plane 4:2:0; FFmpeg standard. */
-  YUV420P10 = 43, /**< Three-plane 4:2:0, 10-bit (AJA NTV2_FBF_10BIT_YCBCR_420PL3_LE). */
-
-  // -- Planar 4:2:2 ----------------------------------------------------
-  P210 = 50,      /**< NV12-shape with 4:2:2 sub-sampling at 10-bit. */
-  YUV422P = 51,
-  YUV422P10 = 52,
-
-  // -- Planar 4:4:4 ----------------------------------------------------
-  YUV444P = 60,
-  YUV444P10 = 61,
-  YUV444P12 = 62,
-
-  // -- High-precision RGB ----------------------------------------------
-  RGBA16 = 70,    /**< 16-bit per channel integer RGBA. */
-  RGBA16F = 71,   /**< 16-bit half-float per channel. */
-  RGBA32F = 72,   /**< 32-bit float per channel. */
-
-  // -- Raw / Bayer (industrial cameras) -------------------------------
-  Mono8 = 80,
-  Mono10 = 81,
-  Mono12 = 82,
-  Mono16 = 83,
-  BayerRG8 = 84,
-  BayerRG12 = 85,
+/** Byte order of multi-byte samples. `NA` means the format has no multi-byte
+ *  sample whose order could differ -- 8-bit packed layouts, and byte-addressed
+ *  ones like RGB24 where component order is part of the format identity. */
+enum class ByteOrder : uint8_t
+{
+  NA = 0,
+  Little,
+  Big,
 };
 
-/** Sample arrangement description. Three plane counts cover everything
- *  the matrix vendors emit:
- *   - 1: packed (BGRA8, UYVY, V210, R210, Mono*)
- *   - 2: semi-planar (NV12, P010, P210)
- *   - 3: fully planar (YUV420P, YUV422P, etc) */
+// ---------------------------------------------------------------------------
+// The single declarative table. One row per format; nothing else in this
+// vocabulary is maintained by hand.
+//
+//   X(Name, Value, Model, Planes, Hsub, Vsub, BlockPixels, BlockBytes,
+//     Alpha, Order, Align)
+//
+// `Value` is the serialized wire value and is FROZEN: rows may be reordered
+// freely, but a value must never change without a serialization migration.
+//
+// BlockPixels/BlockBytes describe the **primary plane**: a horizontal run of
+// BlockPixels pixels occupies exactly BlockBytes bytes. Packed formats put a
+// whole pixel group there (BGRA8 = 1px/4B, UYVY = 2px/4B, v210 = 48px/128B per
+// SMPTE ST 2110-20); planar formats put one luma sample there (NV12 = 1px/1B,
+// P010 = 1px/2B).
+//
+// That one mechanism replaces an averaged bits-per-pixel, which could not
+// express v210 at all (128 bytes / 48 pixels = 21.33 bits, truncated into an
+// integer field and then special-cased in the stride function) and which
+// over-computed planar strides (NV12 by 1.5x, P010 by 3x). A new packed layout
+// now needs a table row, not another branch.
+//
+// `Align` is a *preferred* stride alignment, used only by callers that have no
+// constraint of their own. It is not a property of the pixel format: a device
+// or allocator with a real requirement (D3D12's 256-byte row pitch, a DeckLink
+// rowBytes, a V4L2 `bytesperline`) must pass its own to `alignedRowBytes`.
+// ---------------------------------------------------------------------------
+#define SCORE_VIDEO_PIXEL_FORMATS(X)                                           \
+  /* -- Packed 8-bit RGB -------------------------------------------------- */ \
+  /* BGRA8 matches QRhi BGRA8 + DeckLink bmdFormat8BitBGRA. */ \
+  X(BGRA8, 1, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
+  X(RGBA8, 2, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
+  X(ARGB8, 3, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
+  X(ABGR8, 4, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
+  X(RGB24, 5, RGB, 1, 1, 1, 1, 3, false, NA, 64)                               \
+  X(BGR24, 6, RGB, 1, 1, 1, 1, 3, false, NA, 64)                               \
+  /* -- Packed 10/12-bit RGB ----------------------------------------------- */ \
+  /* R210 is DeckLink r210 / AV_CODEC_ID_R210: (R<<20)|(G<<10)|B, big-endian. */ \
+  /* RGB10 is AJA NTV2_FBF_10BIT_RGB: (B<<20)|(G<<10)|R, little-endian.       */ \
+  /* R12B/R12L pack 8 pixels into 36 bytes (12 bits per component).           */ \
+  X(R210, 10, RGB, 1, 1, 1, 1, 4, false, Big, 256)                             \
+  X(R12B, 11, RGB, 1, 1, 1, 8, 36, false, Big, 256)                            \
+  X(R12L, 12, RGB, 1, 1, 1, 8, 36, false, Little, 256)                         \
+  X(ARGB10, 13, RGB, 1, 1, 1, 1, 5, true, Little, 256)                         \
+  X(DPX10, 14, RGB, 1, 1, 1, 1, 4, false, Big, 256)                            \
+  X(DPX10LE, 15, RGB, 1, 1, 1, 1, 4, false, Little, 256)                       \
+  X(RGB12P, 16, RGB, 1, 1, 1, 2, 9, false, NA, 256)                            \
+  X(RGB48, 17, RGB, 1, 1, 1, 1, 6, false, Little, 256)                         \
+  X(RGB10, 18, RGB, 1, 1, 1, 1, 4, false, Little, 256)                         \
+  /* -- Packed 8-bit YUV 4:2:2 (two pixels share one chroma pair) ---------- */ \
+  X(UYVY422, 20, YUV, 1, 2, 1, 2, 4, false, NA, 256)                           \
+  X(YUYV422, 21, YUV, 1, 2, 1, 2, 4, false, NA, 256)                           \
+  X(YVYU422, 22, YUV, 1, 2, 1, 2, 4, false, NA, 256)                           \
+  X(VYUY422, 23, YUV, 1, 2, 1, 2, 4, false, NA, 256)                           \
+  /* -- Packed 10/16-bit YUV 4:2:2 ----------------------------------------- */ \
+  /* v210 packs 48 pixels into 128 bytes; that block IS the SMPTE stride     */ \
+  /* rule, so it needs no special case here.                                 */ \
+  X(V210, 30, YUV, 1, 2, 1, 48, 128, false, Little, 128)                       \
+  X(V216, 31, YUV, 1, 2, 1, 2, 8, false, Little, 256)                          \
+  /* -- Planar / semi-planar 4:2:0 ----------------------------------------- */ \
+  X(NV12, 40, YUV, 2, 2, 2, 1, 1, false, NA, 256)                              \
+  X(P010, 41, YUV, 2, 2, 2, 1, 2, false, Little, 256)                          \
+  X(YUV420P, 42, YUV, 3, 2, 2, 1, 1, false, NA, 256)                           \
+  X(YUV420P10, 43, YUV, 3, 2, 2, 1, 2, false, Little, 256)                     \
+  /* -- Planar / semi-planar 4:2:2 ----------------------------------------- */ \
+  X(P210, 50, YUV, 2, 2, 1, 1, 2, false, Little, 256)                          \
+  X(YUV422P, 51, YUV, 3, 2, 1, 1, 1, false, NA, 256)                           \
+  X(YUV422P10, 52, YUV, 3, 2, 1, 1, 2, false, Little, 256)                     \
+  /* -- Planar / semi-planar / packed 4:4:4 -------------------------------- */ \
+  X(YUV444P, 60, YUV, 3, 1, 1, 1, 1, false, NA, 256)                           \
+  X(YUV444P10, 61, YUV, 3, 1, 1, 1, 2, false, Little, 256)                     \
+  X(YUV444P12, 62, YUV, 3, 1, 1, 1, 2, false, Little, 256)                     \
+  /* -- High-precision RGB ------------------------------------------------- */ \
+  X(RGBA16, 70, RGB, 1, 1, 1, 1, 8, true, Little, 256)                         \
+  X(RGBA16F, 71, RGB, 1, 1, 1, 1, 8, true, Little, 256)                        \
+  X(RGBA32F, 72, RGB, 1, 1, 1, 1, 16, true, Little, 256)                       \
+  /* -- Greyscale / Bayer (industrial cameras) ----------------------------- */ \
+  X(Mono8, 80, Grey, 1, 1, 1, 1, 1, false, NA, 64)                             \
+  X(Mono10, 81, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
+  X(Mono12, 82, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
+  X(Mono16, 83, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
+  X(BayerRG8, 84, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                         \
+  X(BayerRG12, 85, Bayer, 1, 1, 1, 1, 2, false, Little, 64)
+
+/** Comprehensive pixel format enum, generated from the table above.
+ *  Values are stable; reorder only with serialization migration. */
+enum class VideoPixelFormat : uint16_t
+{
+  Unknown = 0,
+#define SCORE_VPF_ENUM_ROW(Name, Value, ...) Name = Value,
+  SCORE_VIDEO_PIXEL_FORMATS(SCORE_VPF_ENUM_ROW)
+#undef SCORE_VPF_ENUM_ROW
+};
+
+/** Number of described formats, excluding `Unknown`. */
+constexpr std::size_t formatCount() noexcept
+{
+#define SCORE_VPF_COUNT_ROW(...) +1
+  return std::size_t(0 SCORE_VIDEO_PIXEL_FORMATS(SCORE_VPF_COUNT_ROW));
+#undef SCORE_VPF_COUNT_ROW
+}
+
+/** Sample arrangement description.
+ *
+ * Plane counts cover everything the matrix vendors emit:
+ *   - 1: packed (BGRA8, UYVY, v210, R210, Mono*)
+ *   - 2: semi-planar, chroma interleaved into one plane (NV12, P010, P210)
+ *   - 3: fully planar (YUV420P, YUV422P, ...)
+ *   - 4: fully planar plus an alpha plane (none declared yet; sized correctly
+ *        by `bytesPerFrame` if one is added)
+ */
 struct VideoPixelFormatInfo
 {
   const char* name{"unknown"};
-  uint8_t bitsPerPixel{};       /**< Average; 12 for NV12, 16 for UYVY, 20 for V210 effective. */
+  VideoPixelFormat format{VideoPixelFormat::Unknown};
+  ColorModel colorModel{ColorModel::Unknown};
   uint8_t planeCount{1};
-  uint8_t horizontalSubsampling{1}; /**< Chroma subsampling: 1 for 4:4:4, 2 for 4:2:2, 2 for 4:2:0. */
+  uint8_t horizontalSubsampling{1}; /**< 1 for 4:4:4, 2 for 4:2:2 and 4:2:0. */
   uint8_t verticalSubsampling{1};   /**< 1 for 4:2:2, 2 for 4:2:0. */
-  bool isYuv{};
-  bool isPlanar{};
-  uint16_t defaultStrideAlignment{256}; /**< Bytes; vendors typically need 128 or 256. */
-  /**< Bytes of ONE primary-plane (luma) sample: 1 for 8-bit planar
-   *   (NV12, YUV420P), 2 for 10/16-bit planar (P010, P210, YUV420P10).
-   *   0 for packed formats, where the primary-plane stride is
-   *   width*bitsPerPixel/8. Using the average bitsPerPixel for a planar
-   *   primary plane over-computes its stride (NV12 1.5×, P010 3×). */
-  uint8_t bytesPerPrimarySample{0};
+  /** Primary-plane block geometry: `blockPixels` pixels occupy `blockBytes`
+   *  bytes. See the table header for why this replaces bits-per-pixel. */
+  uint16_t blockPixels{1};
+  uint16_t blockBytes{};
+  bool hasAlpha{};
+  ByteOrder byteOrder{ByteOrder::NA};
+  /** Preferred stride alignment for callers with no constraint of their own.
+   *  Devices with a real requirement must pass theirs to `alignedRowBytes`. */
+  uint16_t preferredStrideAlignment{256};
+
+  /** True when chroma lives in its own plane(s) rather than interleaved with
+   *  luma inside one packed buffer. */
+  constexpr bool isPlanar() const noexcept { return planeCount > 1; }
+  constexpr bool isYuv() const noexcept { return colorModel == ColorModel::YUV; }
+  constexpr bool isRgb() const noexcept { return colorModel == ColorModel::RGB; }
+  /** True when the format carries no chroma at all. */
+  constexpr bool isAchromatic() const noexcept
+  {
+    return colorModel == ColorModel::Grey || colorModel == ColorModel::Bayer;
+  }
+  /** False only for the `Unknown` sentinel. */
+  constexpr bool valid() const noexcept { return blockBytes != 0; }
 };
 
-/** Round `v` up to the next multiple of `a` (`a` must be a power of two). */
+/** Round `v` up to a multiple of `a`. `a <= 1` means no alignment; `a` need not
+ *  be a power of two (V210's 128 happens to be, a V4L2 `bytesperline` may not). */
 constexpr std::size_t alignUp(std::size_t v, std::size_t a) noexcept
 {
-  return (v + a - 1) & ~(a - 1);
+  return a <= 1 ? v : ((v + a - 1) / a) * a;
 }
 
-/** Get the descriptive info for `f`. Returns a static reference; the
- *  pointer is stable for the duration of the program. */
+/** Descriptive info for `f`. Returns a reference to storage with static
+ *  lifetime; the `Unknown` sentinel is returned for unrecognised values. */
 SCORE_PLUGIN_GFX_EXPORT
 const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept;
 
@@ -144,17 +223,30 @@ const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept;
 SCORE_PLUGIN_GFX_EXPORT
 const char* formatName(VideoPixelFormat f) noexcept;
 
-/** Compute the default row stride in bytes for `f` at the given
- *  `width`. The result is rounded up to `formatInfo(f).defaultStrideAlignment`.
- *  Vendor-specific stride rules (V210's `(width+47)/48*128`) are baked
- *  into this function for the cases that need it. */
+/** Every described format, in table order. Lets callers -- and the unit test --
+ *  enumerate the vocabulary without maintaining a second copy of the list. */
+SCORE_PLUGIN_GFX_EXPORT
+const VideoPixelFormatInfo* allFormats(std::size_t& count) noexcept;
+
+/** Tight primary-plane row size in bytes, with no padding at all. */
+SCORE_PLUGIN_GFX_EXPORT
+std::size_t rowBytes(VideoPixelFormat f, uint32_t width) noexcept;
+
+/** `rowBytes` rounded up to `alignment`. This is the form device paths should
+ *  use, passing the alignment their allocator actually requires. */
+SCORE_PLUGIN_GFX_EXPORT
+std::size_t
+alignedRowBytes(VideoPixelFormat f, uint32_t width, std::size_t alignment) noexcept;
+
+/** `alignedRowBytes` using the format's `preferredStrideAlignment`, for callers
+ *  that have no constraint of their own. */
 SCORE_PLUGIN_GFX_EXPORT
 std::size_t defaultStride(VideoPixelFormat f, uint32_t width) noexcept;
 
-/** Total byte size of one frame at `width × height` in format `f`.
- *  Accounts for plane count + subsampling. */
+/** Total byte size of one frame at `width × height`, summing every plane at the
+ *  format's preferred stride. */
 SCORE_PLUGIN_GFX_EXPORT
-std::size_t bytesPerFrame(
-    VideoPixelFormat f, uint32_t width, uint32_t height) noexcept;
+std::size_t
+bytesPerFrame(VideoPixelFormat f, uint32_t width, uint32_t height) noexcept;
 
 } // namespace score::gfx::interop

From 26663a78ee16778d51224c161999d2682b4407da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Wed, 29 Jul 2026 22:50:24 -0400
Subject: [PATCH 06/20] gfx: describe the 29 formats that were declared without
 a descriptor

The GPU-interop branch added 29 enum values for the V4L2 camera layouts (the
X-padded RGB variants, NV21/NV16/NV61/NV24/NV42, the packed 4:4:4 YUV orders,
the sub-byte RGB/YUV group, YVU420P, YUV422P12, Mono16BE) but only one
descriptor, so formatInfo() answered "unknown" for the other 28. rowBytes() and
bytesPerFrame() therefore returned 0 for formats the V4L2 capture path actively
produces -- 16 of the 28 are reachable from it today. Nothing crashed only
because the single consumer, HostPinnedRing, prefers the stride the device
reports and falls back to the computed one; a caller that omitted the stride
would have allocated a zero-byte ring.

Since a format can no longer be declared without being described, the values
move up here where the vocabulary lives, each with its block geometry, colour
model, alpha and byte order.

Also map to AVPixelFormat the ones FFmpeg can express exactly, taking the number
of twins from 26 to 42: the 0-prefixed/suffixed X-variants,
NV21/NV16/NV24/NV42, VUYA/VUYX, the RGB565/555/444 pairs, GRAY16BE and
yuv422p12le. The rest stay deliberately unmapped, each with its reason recorded,
and two of those reasons matter:

- YVU420P has no plane-swapped twin. FFmpeg spells YV12 as yuv420p with the U
  and V pointers exchanged, so returning yuv420p here would silently swap
  chroma, which is precisely the bug this bridge exists to prevent.
- AV_PIX_FMT_RGB8/BGR8 are 2:3:3, not the 3:3:2 that V4L2 calls RGB332.

The switch is now exhaustive over the enum, so -Wswitch makes a new format state
its FFmpeg relationship rather than silently defaulting to none.

Verified: 69 formats, no descriptor holes, no zero-size results, 42 AV twins
with no asymmetric round-trip, and plane count, subsampling, planarity, alpha
and RGB-ness all agree with the FFmpeg descriptor for every twin.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 .../Gfx/Graph/interop/VideoPixelFormat.hpp    | 35 +++++++++-
 .../Gfx/Graph/interop/VideoPixelFormatAV.cpp  | 68 +++++++++++++++++++
 2 files changed, 101 insertions(+), 2 deletions(-)

diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
index 2918308869..1cd78deace 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -93,13 +93,18 @@ enum class ByteOrder : uint8_t
 // ---------------------------------------------------------------------------
 #define SCORE_VIDEO_PIXEL_FORMATS(X)                                           \
   /* -- Packed 8-bit RGB -------------------------------------------------- */ \
-  /* BGRA8 matches QRhi BGRA8 + DeckLink bmdFormat8BitBGRA. */ \
+  /* BGRA8 matches QRhi BGRA8 + DeckLink bmdFormat8BitBGRA. The X-variants  */ \
+  /* are the same bytes with the 4th/1st channel undefined: forced opaque.  */ \
   X(BGRA8, 1, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
   X(RGBA8, 2, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
   X(ARGB8, 3, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
   X(ABGR8, 4, RGB, 1, 1, 1, 1, 4, true, NA, 256)                               \
   X(RGB24, 5, RGB, 1, 1, 1, 1, 3, false, NA, 64)                               \
   X(BGR24, 6, RGB, 1, 1, 1, 1, 3, false, NA, 64)                               \
+  X(BGRX8, 7, RGB, 1, 1, 1, 1, 4, false, NA, 256)                              \
+  X(RGBX8, 8, RGB, 1, 1, 1, 1, 4, false, NA, 256)                              \
+  X(XRGB8, 9, RGB, 1, 1, 1, 1, 4, false, NA, 256)                              \
+  X(XBGR8, 19, RGB, 1, 1, 1, 1, 4, false, NA, 256)                             \
   /* -- Packed 10/12-bit RGB ----------------------------------------------- */ \
   /* R210 is DeckLink r210 / AV_CODEC_ID_R210: (R<<20)|(G<<10)|B, big-endian. */ \
   /* RGB10 is AJA NTV2_FBF_10BIT_RGB: (B<<20)|(G<<10)|R, little-endian.       */ \
@@ -113,6 +118,18 @@ enum class ByteOrder : uint8_t
   X(RGB12P, 16, RGB, 1, 1, 1, 2, 9, false, NA, 256)                            \
   X(RGB48, 17, RGB, 1, 1, 1, 1, 6, false, Little, 256)                         \
   X(RGB10, 18, RGB, 1, 1, 1, 1, 4, false, Little, 256)                         \
+  /* -- Packed sub-byte RGB / YUV (legacy, embedded, V4L2 cameras) --------- */ \
+  X(RGB332, 90, RGB, 1, 1, 1, 1, 1, false, NA, 64)                             \
+  X(RGB565, 91, RGB, 1, 1, 1, 1, 2, false, Little, 64)                         \
+  X(RGB565BE, 92, RGB, 1, 1, 1, 1, 2, false, Big, 64)                          \
+  X(RGB555, 93, RGB, 1, 1, 1, 1, 2, false, Little, 64)                         \
+  X(RGB555BE, 94, RGB, 1, 1, 1, 1, 2, false, Big, 64)                          \
+  X(ARGB1555, 95, RGB, 1, 1, 1, 1, 2, true, Little, 64)                        \
+  X(RGB444, 96, RGB, 1, 1, 1, 1, 2, false, Little, 64)                         \
+  X(ARGB4444, 97, RGB, 1, 1, 1, 1, 2, true, Little, 64)                        \
+  X(AYUV4444, 98, YUV, 1, 1, 1, 1, 2, true, Little, 64)                        \
+  X(AYUV1555, 99, YUV, 1, 1, 1, 1, 2, true, Little, 64)                        \
+  X(YUV565, 100, YUV, 1, 1, 1, 1, 2, false, Little, 64)                        \
   /* -- Packed 8-bit YUV 4:2:2 (two pixels share one chroma pair) ---------- */ \
   X(UYVY422, 20, YUV, 1, 2, 1, 2, 4, false, NA, 256)                           \
   X(YUYV422, 21, YUV, 1, 2, 1, 2, 4, false, NA, 256)                           \
@@ -128,14 +145,27 @@ enum class ByteOrder : uint8_t
   X(P010, 41, YUV, 2, 2, 2, 1, 2, false, Little, 256)                          \
   X(YUV420P, 42, YUV, 3, 2, 2, 1, 1, false, NA, 256)                           \
   X(YUV420P10, 43, YUV, 3, 2, 2, 1, 2, false, Little, 256)                     \
+  X(NV21, 44, YUV, 2, 2, 2, 1, 1, false, NA, 256)                              \
+  X(YVU420P, 45, YUV, 3, 2, 2, 1, 1, false, NA, 256)                           \
   /* -- Planar / semi-planar 4:2:2 ----------------------------------------- */ \
   X(P210, 50, YUV, 2, 2, 1, 1, 2, false, Little, 256)                          \
   X(YUV422P, 51, YUV, 3, 2, 1, 1, 1, false, NA, 256)                           \
   X(YUV422P10, 52, YUV, 3, 2, 1, 1, 2, false, Little, 256)                     \
+  X(NV16, 53, YUV, 2, 2, 1, 1, 1, false, NA, 256)                              \
+  X(NV61, 54, YUV, 2, 2, 1, 1, 1, false, NA, 256)                              \
+  X(YUV422P12, 55, YUV, 3, 2, 1, 1, 2, false, Little, 256)                     \
   /* -- Planar / semi-planar / packed 4:4:4 -------------------------------- */ \
   X(YUV444P, 60, YUV, 3, 1, 1, 1, 1, false, NA, 256)                           \
   X(YUV444P10, 61, YUV, 3, 1, 1, 1, 2, false, Little, 256)                     \
   X(YUV444P12, 62, YUV, 3, 1, 1, 1, 2, false, Little, 256)                     \
+  X(NV24, 63, YUV, 2, 1, 1, 1, 1, false, NA, 256)                              \
+  X(NV42, 64, YUV, 2, 1, 1, 1, 1, false, NA, 256)                              \
+  X(VUYA, 65, YUV, 1, 1, 1, 1, 4, true, NA, 256)                               \
+  X(VUYX, 66, YUV, 1, 1, 1, 1, 4, false, NA, 256)                              \
+  X(AYUV, 67, YUV, 1, 1, 1, 1, 4, true, NA, 256)                               \
+  X(XYUV, 68, YUV, 1, 1, 1, 1, 4, false, NA, 256)                              \
+  X(YUVA, 69, YUV, 1, 1, 1, 1, 4, true, NA, 256)                               \
+  X(YUVX, 73, YUV, 1, 1, 1, 1, 4, false, NA, 256)                              \
   /* -- High-precision RGB ------------------------------------------------- */ \
   X(RGBA16, 70, RGB, 1, 1, 1, 1, 8, true, Little, 256)                         \
   X(RGBA16F, 71, RGB, 1, 1, 1, 1, 8, true, Little, 256)                        \
@@ -146,7 +176,8 @@ enum class ByteOrder : uint8_t
   X(Mono12, 82, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
   X(Mono16, 83, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
   X(BayerRG8, 84, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                         \
-  X(BayerRG12, 85, Bayer, 1, 1, 1, 1, 2, false, Little, 64)
+  X(BayerRG12, 85, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                    \
+  X(Mono16BE, 86, Grey, 1, 1, 1, 1, 2, false, Big, 64)
 
 /** Comprehensive pixel format enum, generated from the table above.
  *  Values are stable; reorder only with serialization migration. */
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
index c745dfa9ca..289bbd1282 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
@@ -15,6 +15,20 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     case V::ABGR8:     return AV_PIX_FMT_ABGR;
     case V::RGB24:     return AV_PIX_FMT_RGB24;
     case V::BGR24:     return AV_PIX_FMT_BGR24;
+    // The X-variants are the same bytes with the spare channel undefined;
+    // FFmpeg spells those out as its 0-prefixed/suffixed forms, so they map
+    // exactly rather than aliasing onto the alpha-bearing format.
+    case V::BGRX8:     return AV_PIX_FMT_BGR0;
+    case V::RGBX8:     return AV_PIX_FMT_RGB0;
+    case V::XRGB8:     return AV_PIX_FMT_0RGB;
+    case V::XBGR8:     return AV_PIX_FMT_0BGR;
+
+    // -- packed sub-byte RGB --
+    case V::RGB565:    return AV_PIX_FMT_RGB565LE;
+    case V::RGB565BE:  return AV_PIX_FMT_RGB565BE;
+    case V::RGB555:    return AV_PIX_FMT_RGB555LE;
+    case V::RGB555BE:  return AV_PIX_FMT_RGB555BE;
+    case V::RGB444:    return AV_PIX_FMT_RGB444LE;
 
     // -- high-precision RGB --
     case V::RGB48:     return AV_PIX_FMT_RGB48LE;  // AJA 48BIT_RGB is 16-bit LE
@@ -27,21 +41,37 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
 
     // -- planar / semi-planar YUV --
     case V::NV12:      return AV_PIX_FMT_NV12;
+    case V::NV21:      return AV_PIX_FMT_NV21;
+    case V::NV16:      return AV_PIX_FMT_NV16;
+    case V::NV24:      return AV_PIX_FMT_NV24;
+    case V::NV42:      return AV_PIX_FMT_NV42;
     case V::P010:      return AV_PIX_FMT_P010LE;
     case V::P210:      return AV_PIX_FMT_P210LE;
     case V::YUV420P:   return AV_PIX_FMT_YUV420P;
     case V::YUV420P10: return AV_PIX_FMT_YUV420P10LE;
     case V::YUV422P:   return AV_PIX_FMT_YUV422P;
     case V::YUV422P10: return AV_PIX_FMT_YUV422P10LE;
+    case V::YUV422P12: return AV_PIX_FMT_YUV422P12LE;
     case V::YUV444P:   return AV_PIX_FMT_YUV444P;
     case V::YUV444P10: return AV_PIX_FMT_YUV444P10LE;
     case V::YUV444P12: return AV_PIX_FMT_YUV444P12LE;
 
+    // -- packed 4:4:4 YUV with/without alpha --
+#if LIBAVUTIL_VERSION_INT >= AV_VERSION_INT(57, 36, 100)
+    case V::VUYA:      return AV_PIX_FMT_VUYA;
+    case V::VUYX:      return AV_PIX_FMT_VUYX;
+#else
+    case V::VUYA:
+    case V::VUYX:
+      return AV_PIX_FMT_NONE;
+#endif
+
     // -- grey --
     case V::Mono8:     return AV_PIX_FMT_GRAY8;
     case V::Mono10:    return AV_PIX_FMT_GRAY10LE;
     case V::Mono12:    return AV_PIX_FMT_GRAY12LE;
     case V::Mono16:    return AV_PIX_FMT_GRAY16LE;
+    case V::Mono16BE:  return AV_PIX_FMT_GRAY16BE;
 
     // -- wire-only: no AVPixelFormat (FFmpeg models these as codecs) --
     case V::V210:      // AV_CODEC_ID_V210
@@ -60,6 +90,25 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     case V::RGBA32F:   // no packed float RGBA pixfmt (GBRPF32 is planar)
     case V::BayerRG8:  // Bayer order differs per sensor; keep explicit
     case V::BayerRG12:
+    // FFmpeg has no plane-swapped planar twin: YV12 is expressed as yuv420p
+    // with the U and V pointers exchanged, so returning yuv420p here would
+    // silently swap chroma -- the exact bug this bridge exists to avoid.
+    case V::YVU420P:
+    case V::NV61:      // no AV_PIX_FMT_NV61 (NV16 with the pair exchanged)
+    // Packed 4:4:4 orders FFmpeg does not spell: it has VUYA/VUYX/UYVA only.
+    case V::AYUV:
+    case V::XYUV:
+    case V::YUVA:
+    case V::YUVX:
+    // AV_PIX_FMT_RGB8/BGR8 are 2:3:3, not the 3:3:2 of V4L2's RGB332.
+    case V::RGB332:
+    // 16-bit containers whose spare bit(s) FFmpeg treats as padding rather
+    // than alpha, so the alpha-bearing variants have no exact twin.
+    case V::ARGB1555:
+    case V::ARGB4444:
+    case V::AYUV4444:
+    case V::AYUV1555:
+    case V::YUV565:
     case V::Unknown:
       return AV_PIX_FMT_NONE;
   }
@@ -77,25 +126,44 @@ VideoPixelFormat fromAVPixelFormat(AVPixelFormat f) noexcept
     case AV_PIX_FMT_ABGR:        return V::ABGR8;
     case AV_PIX_FMT_RGB24:       return V::RGB24;
     case AV_PIX_FMT_BGR24:       return V::BGR24;
+    case AV_PIX_FMT_BGR0:        return V::BGRX8;
+    case AV_PIX_FMT_RGB0:        return V::RGBX8;
+    case AV_PIX_FMT_0RGB:        return V::XRGB8;
+    case AV_PIX_FMT_0BGR:        return V::XBGR8;
+    case AV_PIX_FMT_RGB565LE:    return V::RGB565;
+    case AV_PIX_FMT_RGB565BE:    return V::RGB565BE;
+    case AV_PIX_FMT_RGB555LE:    return V::RGB555;
+    case AV_PIX_FMT_RGB555BE:    return V::RGB555BE;
+    case AV_PIX_FMT_RGB444LE:    return V::RGB444;
     case AV_PIX_FMT_RGB48LE:     return V::RGB48;
     case AV_PIX_FMT_RGBA64LE:    return V::RGBA16;
     case AV_PIX_FMT_UYVY422:     return V::UYVY422;
     case AV_PIX_FMT_YUYV422:     return V::YUYV422;
     case AV_PIX_FMT_YVYU422:     return V::YVYU422;
     case AV_PIX_FMT_NV12:        return V::NV12;
+    case AV_PIX_FMT_NV21:        return V::NV21;
+    case AV_PIX_FMT_NV16:        return V::NV16;
+    case AV_PIX_FMT_NV24:        return V::NV24;
+    case AV_PIX_FMT_NV42:        return V::NV42;
     case AV_PIX_FMT_P010LE:      return V::P010;
     case AV_PIX_FMT_P210LE:      return V::P210;
     case AV_PIX_FMT_YUV420P:     return V::YUV420P;
     case AV_PIX_FMT_YUV420P10LE: return V::YUV420P10;
     case AV_PIX_FMT_YUV422P:     return V::YUV422P;
     case AV_PIX_FMT_YUV422P10LE: return V::YUV422P10;
+    case AV_PIX_FMT_YUV422P12LE: return V::YUV422P12;
     case AV_PIX_FMT_YUV444P:     return V::YUV444P;
     case AV_PIX_FMT_YUV444P10LE: return V::YUV444P10;
     case AV_PIX_FMT_YUV444P12LE: return V::YUV444P12;
+#if LIBAVUTIL_VERSION_INT >= AV_VERSION_INT(57, 36, 100)
+    case AV_PIX_FMT_VUYA:        return V::VUYA;
+    case AV_PIX_FMT_VUYX:        return V::VUYX;
+#endif
     case AV_PIX_FMT_GRAY8:       return V::Mono8;
     case AV_PIX_FMT_GRAY10LE:    return V::Mono10;
     case AV_PIX_FMT_GRAY12LE:    return V::Mono12;
     case AV_PIX_FMT_GRAY16LE:    return V::Mono16;
+    case AV_PIX_FMT_GRAY16BE:    return V::Mono16BE;
     default:                     return V::Unknown;
   }
 }

From 649d291dadfbe4b94e09a690b2323e7c460d4108 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Wed, 29 Jul 2026 22:52:35 -0400
Subject: [PATCH 07/20] media: fix A444_10LE mapping to a big-endian
 AVPixelFormat

The GStreamer format map had A444_10BE and A444_10LE both resolving to
AV_PIX_FMT_YUVA444P10BE, so a little-endian 10-bit 4:4:4-with-alpha stream was
decoded as big-endian: every 10-bit sample byte-swapped. This reaches the
GStreamer, Sh4lt and Shmdata inputs, which all resolve caps through this map.

An audit of the whole table for key/value endianness agreement found this as the
only live mismatch; the GBR/GBRA rows that also look inconsistent are commented
out.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-media/Video/GStreamerCompatibility.hpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/plugins/score-plugin-media/Video/GStreamerCompatibility.hpp b/src/plugins/score-plugin-media/Video/GStreamerCompatibility.hpp
index 9ed65069ad..bf1c54ddde 100644
--- a/src/plugins/score-plugin-media/Video/GStreamerCompatibility.hpp
+++ b/src/plugins/score-plugin-media/Video/GStreamerCompatibility.hpp
@@ -131,7 +131,7 @@ inline const ossia::hash_map<std::string, AVPixelFormat>& gstreamerToLibav()
     format_map["A422_10BE"] = AV_PIX_FMT_YUVA422P10BE;
     format_map["A422_10LE"] = AV_PIX_FMT_YUVA422P10LE;
     format_map["A444_10BE"] = AV_PIX_FMT_YUVA444P10BE;
-    format_map["A444_10LE"] = AV_PIX_FMT_YUVA444P10BE;
+    format_map["A444_10LE"] = AV_PIX_FMT_YUVA444P10LE;
     format_map["ABGR"] = AV_PIX_FMT_ABGR;
     // format_map["ABGR64_BE"] = AV_PIX_FMT_ABGR64BE;
     // format_map["ABGR64_LE"] = AV_PIX_FMT_ABGR64LE;

From ef99cc572c7413b70ae75c2c5c642cf72a897eb6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Wed, 29 Jul 2026 22:57:05 -0400
Subject: [PATCH 08/20] tests: move the pixel-format suite next to the
 vocabulary and sweep the table

The suite lived on the GPU-interop branch, three PRs downstream of the header it
guards, so the PR that introduces a format never ran it. Move it here.

It also could not have caught the descriptor holes it was written to prevent: it
kept its own 41-entry allKnownFormats[] list and asserted that each entry had a
descriptor, which is a tautology with respect to the table. A format declared in
the enum but present in neither list -- the state 28 formats were in -- was
invisible to it.

Every sweep now iterates allFormats(), the same table the vocabulary is
generated from, so a format is covered the moment it is declared.

New invariants beyond the previous coverage:
  - values as well as names are unique, and none reuses the 0 sentinel
  - colour-model classification: exactly one of RGB / YUV / achromatic holds,
    and neither RGB nor greyscale claims chroma subsampling
  - alignedRowBytes pads without ever losing data and never wastes a whole
    alignment unit, for 13 widths x 6 alignments x every format
  - rowBytes is exactly the block count and is monotonic in width
  - byte order is declared wherever a sample spans more than one byte
  - the FFmpeg cross-check now also compares alpha, RGB-ness and endianness,
    which the old bool isYuv/bitsPerPixel model could not express

Verified by injection: wrongly setting YUV420P to 2 planes, and dropping a
blockBytes to 0, each fail the suite; the correct table passes 19078 assertions
across 17 cases.

One assertion from the old suite was itself wrong and is corrected here: 10-bit
planar is exactly double its 8-bit twin only for tight rows. Alignment padding
is not linear in the sample size -- at 1920 the 8-bit luma row pads 1920 -> 2048
while the 10-bit row is already 256-aligned at 3840 -- so the padded sizes are
merely ordered, and the doubling is asserted on tight rows instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 tests/unit/CMakeLists.txt           |   7 +
 tests/unit/VideoPixelFormatTest.cpp | 450 ++++++++++++++++++++++++++++
 2 files changed, 457 insertions(+)
 create mode 100644 tests/unit/VideoPixelFormatTest.cpp

diff --git a/tests/unit/CMakeLists.txt b/tests/unit/CMakeLists.txt
index a280bb0a99..86063a98a2 100644
--- a/tests/unit/CMakeLists.txt
+++ b/tests/unit/CMakeLists.txt
@@ -290,3 +290,10 @@ if(TARGET pipewire::pipewire)
     target_include_directories(test_unit_pipewire_protocol_quantum SYSTEM PRIVATE ${_pw_includes})
   endif()
 endif()
+# The video pixel-format vocabulary and its libav bridge. Lives with the
+# vocabulary rather than with its consumers, so the PR that introduces a format
+# is the one whose CI proves it is described and sized correctly.
+score_add_test(test_unit_video_pixel_format
+  SOURCES VideoPixelFormatTest.cpp
+  PLUGINS score_plugin_gfx
+  LIBS avutil)
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
new file mode 100644
index 0000000000..f7e5379174
--- /dev/null
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -0,0 +1,450 @@
+// Unit tests for the video pixel-format vocabulary
+// (Gfx/Graph/interop/VideoPixelFormat.{hpp,cpp}) and its libav bridge
+// (VideoPixelFormatAV.{hpp,cpp}). Pure mapping logic, no app context.
+//
+// Every sweep here iterates allFormats(), i.e. the same declarative table the
+// vocabulary itself is generated from. That matters: the previous version of
+// this file kept its own 41-entry list of formats and then asserted that each
+// had a descriptor, which is a tautology -- a format declared in the enum but
+// absent from both lists was invisible to it, and 28 formats were in exactly
+// that state. Deriving from the table means a new format is swept the moment it
+// is declared, and there is no second list to forget to update.
+//
+// Covered for EVERY format in the vocabulary:
+//   - descriptor invariants: block geometry, plane count vs planarity,
+//     subsampling factors, colour model, name
+//   - sizing: tight rowBytes, alignment behaviour, hand-computed values
+//     including odd widths and the v210 48-pixel/128-byte SMPTE rule
+//   - bytesPerFrame against per-plane hand computation
+//   - AV bridge round-trips both ways, wire-only formats mapping to
+//     AV_PIX_FMT_NONE, unknown AV formats mapping to Unknown
+//   - cross-validation of every mapped format against FFmpeg's own
+//     av_pix_fmt_desc_get(): plane count, chroma subsampling, planarity,
+//     alpha and RGB-ness. A mismatch there is a real bug, not a test artifact.
+
+#include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+#include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
+
+extern "C" {
+#include <libavutil/pixdesc.h>
+}
+
+#include <catch2/catch_test_macros.hpp>
+
+#include <set>
+#include <string>
+#include <vector>
+
+namespace vpf = score::gfx::interop;
+using V = vpf::VideoPixelFormat;
+using vpf::ColorModel;
+
+namespace
+{
+// The vocabulary, straight from the table that generates it.
+std::vector<const vpf::VideoPixelFormatInfo*> described()
+{
+  std::size_t n = 0;
+  const auto* all = vpf::allFormats(n);
+  std::vector<const vpf::VideoPixelFormatInfo*> out;
+  out.reserve(n);
+  for(std::size_t i = 0; i < n; ++i)
+    out.push_back(all + i);
+  return out;
+}
+
+// A few widths that between them exercise exact blocks, partial blocks, odd
+// values and the 8K rasters the SDI paths actually run.
+constexpr uint32_t kWidths[] = {1, 2, 6, 63, 64, 65, 720, 1919, 1920, 1921, 3840, 7680, 8192};
+} // namespace
+
+// The values are serialized, so freezing a representative spread here makes an
+// accidental renumbering break the build rather than silently invalidate saved
+// documents.
+static_assert(uint16_t(V::Unknown) == 0);
+static_assert(uint16_t(V::BGRA8) == 1);
+static_assert(uint16_t(V::BGRX8) == 7);
+static_assert(uint16_t(V::XBGR8) == 19);
+static_assert(uint16_t(V::UYVY422) == 20);
+static_assert(uint16_t(V::V210) == 30);
+static_assert(uint16_t(V::NV12) == 40);
+static_assert(uint16_t(V::YVU420P) == 45);
+static_assert(uint16_t(V::YUV422P12) == 55);
+static_assert(uint16_t(V::YUV444P) == 60);
+static_assert(uint16_t(V::YUVX) == 73);
+static_assert(uint16_t(V::Mono8) == 80);
+static_assert(uint16_t(V::Mono16BE) == 86);
+static_assert(uint16_t(V::YUV565) == 100);
+
+TEST_CASE("the vocabulary is non-trivial and self-consistent", "[gfx][pixfmt]")
+{
+  const auto all = described();
+  REQUIRE(all.size() == vpf::formatCount());
+  // Guards against the table being accidentally emptied or halved.
+  CHECK(all.size() >= 69);
+
+  for(const auto* i : all)
+  {
+    INFO("format " << i->name);
+    // Every described format must be usable: the whole point of generating the
+    // enum from the table is that this can no longer fail.
+    CHECK(i->valid());
+    CHECK(i->blockBytes > 0);
+    CHECK(i->blockPixels >= 1);
+    CHECK(i->name != nullptr);
+    CHECK(std::string(i->name) != "unknown");
+    CHECK(i->colorModel != ColorModel::Unknown);
+    CHECK(i->planeCount >= 1);
+    CHECK(i->planeCount <= 4);
+    CHECK(i->isPlanar() == (i->planeCount > 1));
+    // Subsampling is only meaningful in the two documented axes.
+    CHECK((i->horizontalSubsampling == 1 || i->horizontalSubsampling == 2
+           || i->horizontalSubsampling == 4));
+    CHECK((i->verticalSubsampling == 1 || i->verticalSubsampling == 2));
+    // formatInfo() must resolve the value back to this very row.
+    CHECK(&vpf::formatInfo(i->format) == i);
+    CHECK(std::string(vpf::formatName(i->format)) == i->name);
+  }
+}
+
+TEST_CASE("names and values are unique across the vocabulary", "[gfx][pixfmt]")
+{
+  std::set<std::string> names;
+  std::set<uint16_t> values;
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    CHECK(names.insert(i->name).second);
+    CHECK(values.insert(uint16_t(i->format)).second);
+    // Zero is the sentinel and must not be reused by a real format.
+    CHECK(uint16_t(i->format) != 0);
+  }
+}
+
+TEST_CASE("achromatic and chroma-bearing formats are classified", "[gfx][pixfmt]")
+{
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    // Grey and Bayer carry no chroma, so they cannot be subsampled.
+    if(i->isAchromatic())
+    {
+      CHECK(i->horizontalSubsampling == 1);
+      CHECK(i->verticalSubsampling == 1);
+      CHECK(i->planeCount == 1);
+      CHECK_FALSE(i->isYuv());
+      CHECK_FALSE(i->isRgb());
+    }
+    // RGB is never subsampled either.
+    if(i->isRgb())
+    {
+      CHECK(i->horizontalSubsampling == 1);
+      CHECK(i->verticalSubsampling == 1);
+    }
+    // Exactly one of the model predicates may hold.
+    const int n = int(i->isRgb()) + int(i->isYuv()) + int(i->isAchromatic());
+    CHECK(n == 1);
+  }
+}
+
+TEST_CASE("multi-byte samples declare a byte order", "[gfx][pixfmt]")
+{
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    // A format whose primary block is one byte per pixel has no order to state.
+    if(i->blockPixels == 1 && i->blockBytes == 1)
+      CHECK(i->byteOrder == vpf::ByteOrder::NA);
+  }
+}
+
+TEST_CASE("unknown / out-of-range formats return the sentinel", "[gfx][pixfmt]")
+{
+  for(auto f : {V::Unknown, V(1234), V(65535), V(101)})
+  {
+    const auto& u = vpf::formatInfo(f);
+    CHECK(std::string(u.name) == "unknown");
+    CHECK_FALSE(u.valid());
+    CHECK(vpf::rowBytes(f, 1920) == 0);
+    CHECK(vpf::defaultStride(f, 1920) == 0);
+    CHECK(vpf::bytesPerFrame(f, 1920, 1080) == 0);
+  }
+}
+
+TEST_CASE("degenerate sizes yield zero, never garbage", "[gfx][pixfmt]")
+{
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    CHECK(vpf::rowBytes(i->format, 0) == 0);
+    CHECK(vpf::bytesPerFrame(i->format, 0, 1080) == 0);
+    CHECK(vpf::bytesPerFrame(i->format, 1920, 0) == 0);
+  }
+}
+
+TEST_CASE("rowBytes is the exact block count, and monotonic", "[gfx][pixfmt]")
+{
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    std::size_t prev = 0;
+    for(auto w : kWidths)
+    {
+      const auto blocks = (std::size_t(w) + i->blockPixels - 1) / i->blockPixels;
+      const auto expect = blocks * i->blockBytes;
+      CHECK(vpf::rowBytes(i->format, w) == expect);
+      // Never narrower as the raster widens.
+      CHECK(vpf::rowBytes(i->format, w) >= prev);
+      prev = vpf::rowBytes(i->format, w);
+    }
+  }
+}
+
+TEST_CASE("alignedRowBytes pads without ever losing data", "[gfx][pixfmt]")
+{
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    for(auto w : kWidths)
+    {
+      const auto tight = vpf::rowBytes(i->format, w);
+      for(std::size_t a : {std::size_t(0), std::size_t(1), std::size_t(64),
+                           std::size_t(128), std::size_t(256), std::size_t(512)})
+      {
+        const auto padded = vpf::alignedRowBytes(i->format, w, a);
+        CHECK(padded >= tight);
+        if(a > 1)
+        {
+          CHECK(padded % a == 0);
+          // Padding never wastes a whole alignment unit.
+          CHECK(padded - tight < a);
+        }
+        else
+        {
+          CHECK(padded == tight);
+        }
+      }
+      // The convenience form must agree with the explicit one.
+      CHECK(vpf::defaultStride(i->format, w)
+            == vpf::alignedRowBytes(i->format, w, i->preferredStrideAlignment));
+    }
+  }
+}
+
+TEST_CASE("hand-computed strides: packed formats", "[gfx][pixfmt]")
+{
+  // 4 bytes per pixel, 256-aligned.
+  CHECK(vpf::rowBytes(V::BGRA8, 1920) == 7680);
+  CHECK(vpf::defaultStride(V::BGRA8, 1920) == 7680);
+  CHECK(vpf::rowBytes(V::BGRA8, 1921) == 7684);
+  CHECK(vpf::defaultStride(V::BGRA8, 1921) == 7936);
+  // The X-padded variants are byte-identical to their alpha-bearing twins.
+  CHECK(vpf::rowBytes(V::BGRX8, 1920) == vpf::rowBytes(V::BGRA8, 1920));
+  CHECK(vpf::rowBytes(V::XRGB8, 1920) == vpf::rowBytes(V::ARGB8, 1920));
+  // 3 bytes per pixel, 64-aligned.
+  CHECK(vpf::rowBytes(V::RGB24, 1920) == 5760);
+  CHECK(vpf::defaultStride(V::RGB24, 1920) == 5760);
+  // 4:2:2 packed: two pixels per 4 bytes.
+  CHECK(vpf::rowBytes(V::UYVY422, 1920) == 3840);
+  CHECK(vpf::rowBytes(V::UYVY422, 2) == 4);
+  // An odd width still occupies the whole trailing block.
+  CHECK(vpf::rowBytes(V::UYVY422, 3) == 8);
+  // 12-bit RGB: 8 pixels per 36 bytes.
+  CHECK(vpf::rowBytes(V::R12B, 8) == 36);
+  CHECK(vpf::rowBytes(V::R12B, 9) == 72);
+  CHECK(vpf::rowBytes(V::R12B, 1920) == 8640);
+  // 12-bit packed RGB: 2 pixels per 9 bytes.
+  CHECK(vpf::rowBytes(V::RGB12P, 1920) == 8640);
+  // 16-bit and float RGB.
+  CHECK(vpf::rowBytes(V::RGB48, 1920) == 11520);
+  CHECK(vpf::rowBytes(V::RGBA16, 1920) == 15360);
+  CHECK(vpf::rowBytes(V::RGBA32F, 1920) == 30720);
+  // Greyscale.
+  CHECK(vpf::rowBytes(V::Mono8, 1920) == 1920);
+  CHECK(vpf::rowBytes(V::Mono16, 1920) == 3840);
+  CHECK(vpf::rowBytes(V::Mono16BE, 1920) == 3840);
+  // Sub-byte RGB.
+  CHECK(vpf::rowBytes(V::RGB332, 1920) == 1920);
+  CHECK(vpf::rowBytes(V::RGB565, 1920) == 3840);
+}
+
+TEST_CASE("hand-computed strides: the v210 width rule", "[gfx][pixfmt][v210]")
+{
+  // SMPTE packs 48 pixels into 128 bytes; a partial group still costs 128.
+  // Expressing that as the block geometry means no special case in the code.
+  CHECK(vpf::rowBytes(V::V210, 48) == 128);
+  CHECK(vpf::rowBytes(V::V210, 49) == 256);
+  CHECK(vpf::rowBytes(V::V210, 96) == 256);
+  CHECK(vpf::rowBytes(V::V210, 1920) == 5120);  // 1920 = 40 groups exactly
+  CHECK(vpf::rowBytes(V::V210, 1921) == 5248);  // 41 groups
+  CHECK(vpf::rowBytes(V::V210, 3840) == 10240);
+  CHECK(vpf::rowBytes(V::V210, 7680) == 20480);
+  CHECK(vpf::rowBytes(V::V210, 8192) == 21888); // 8192/48 = 170.67 -> 171
+  // 1280 is the classic non-multiple: 1280/48 = 26.67 -> 27 groups.
+  CHECK(vpf::rowBytes(V::V210, 1280) == 27 * 128);
+  // Already 128-aligned, so the preferred alignment changes nothing.
+  for(auto w : {48u, 49u, 1280u, 1920u, 1921u})
+    CHECK(vpf::defaultStride(V::V210, w) == vpf::rowBytes(V::V210, w));
+}
+
+TEST_CASE("hand-computed frame sizes: packed", "[gfx][pixfmt]")
+{
+  CHECK(vpf::bytesPerFrame(V::BGRA8, 1920, 1080) == 7680u * 1080u);
+  CHECK(vpf::bytesPerFrame(V::UYVY422, 1920, 1080) == 3840u * 1080u);
+  CHECK(vpf::bytesPerFrame(V::V210, 1920, 1080) == 5120u * 1080u);
+  CHECK(vpf::bytesPerFrame(V::Mono8, 1920, 1080) == 1920u * 1080u);
+}
+
+TEST_CASE("hand-computed frame sizes: planar and semi-planar", "[gfx][pixfmt]")
+{
+  // NV12: luma plane + one interleaved chroma plane at half height.
+  {
+    const auto y = vpf::defaultStride(V::NV12, 1920) * 1080u;
+    const auto uv = vpf::defaultStride(V::NV12, 1920) * 540u;
+    CHECK(vpf::bytesPerFrame(V::NV12, 1920, 1080) == y + uv);
+  }
+  // NV21 is NV12 with the chroma pair exchanged: identical footprint.
+  CHECK(vpf::bytesPerFrame(V::NV21, 1920, 1080)
+        == vpf::bytesPerFrame(V::NV12, 1920, 1080));
+  // YUV420P: luma + two quarter-size planes.
+  {
+    const auto y = vpf::defaultStride(V::YUV420P, 1920) * 1080u;
+    const auto c = vpf::defaultStride(V::YUV420P, 960) * 540u;
+    CHECK(vpf::bytesPerFrame(V::YUV420P, 1920, 1080) == y + 2 * c);
+  }
+  // YVU420P swaps the planes only: identical footprint.
+  CHECK(vpf::bytesPerFrame(V::YVU420P, 1920, 1080)
+        == vpf::bytesPerFrame(V::YUV420P, 1920, 1080));
+  // 10-bit planar uses 2-byte lanes, so the *tight* footprint is exactly double
+  // the 8-bit one. It is only exact untight: alignment padding is not linear in
+  // the sample size (at 1920, 8-bit luma pads 1920 -> 2048 while 10-bit luma is
+  // already 256-aligned at 3840), so the padded sizes are merely ordered.
+  const auto tightFrame = [](V f, uint32_t w, uint32_t h) -> std::size_t {
+    const auto& i = vpf::formatInfo(f);
+    const auto y = vpf::rowBytes(f, w) * std::size_t(h);
+    if(!i.isPlanar())
+      return y;
+    const auto cw = w / i.horizontalSubsampling;
+    const auto ch = std::size_t(h / i.verticalSubsampling);
+    if(i.planeCount == 2)
+      return y + vpf::rowBytes(f, cw * 2) * ch;
+    return y + 2 * (vpf::rowBytes(f, cw) * ch);
+  };
+  CHECK(tightFrame(V::YUV420P10, 1920, 1080) == 2 * tightFrame(V::YUV420P, 1920, 1080));
+  CHECK(tightFrame(V::P010, 1920, 1080) == 2 * tightFrame(V::NV12, 1920, 1080));
+  CHECK(vpf::bytesPerFrame(V::YUV420P10, 1920, 1080)
+        > vpf::bytesPerFrame(V::YUV420P, 1920, 1080));
+  CHECK(vpf::bytesPerFrame(V::P010, 1920, 1080)
+        > vpf::bytesPerFrame(V::NV12, 1920, 1080));
+  // 4:2:2 planar has full-height chroma, 4:4:4 full-size chroma.
+  CHECK(vpf::bytesPerFrame(V::YUV422P, 1920, 1080)
+        > vpf::bytesPerFrame(V::YUV420P, 1920, 1080));
+  CHECK(vpf::bytesPerFrame(V::YUV444P, 1920, 1080)
+        > vpf::bytesPerFrame(V::YUV422P, 1920, 1080));
+  // 12-bit shares the 16-bit lane with 10-bit, so the footprints match.
+  CHECK(vpf::bytesPerFrame(V::YUV422P12, 1920, 1080)
+        == vpf::bytesPerFrame(V::YUV422P10, 1920, 1080));
+}
+
+TEST_CASE("every planar format sums its planes", "[gfx][pixfmt]")
+{
+  for(const auto* i : described())
+  {
+    if(!i->isPlanar())
+      continue;
+    INFO("format " << i->name);
+    const uint32_t w = 1920, h = 1080;
+    const auto y = vpf::defaultStride(i->format, w) * std::size_t(h);
+    const auto cw = w / i->horizontalSubsampling;
+    const auto ch = std::size_t(h / i->verticalSubsampling);
+    std::size_t expect = y;
+    if(i->planeCount == 2)
+      expect += vpf::defaultStride(i->format, cw * 2) * ch;
+    else if(i->planeCount == 3)
+      expect += 2 * (vpf::defaultStride(i->format, cw) * ch);
+    else if(i->planeCount == 4)
+      expect += 2 * (vpf::defaultStride(i->format, cw) * ch) + y;
+    CHECK(vpf::bytesPerFrame(i->format, w, h) == expect);
+    // A planar frame is always at least as big as its luma plane.
+    CHECK(vpf::bytesPerFrame(i->format, w, h) >= y);
+  }
+}
+
+TEST_CASE("AV bridge: score -> AV -> score round-trip", "[gfx][pixfmt][av]")
+{
+  int twins = 0;
+  for(const auto* i : described())
+  {
+    const auto av = vpf::toAVPixelFormat(i->format);
+    if(av == AV_PIX_FMT_NONE)
+      continue;
+    ++twins;
+    INFO("format " << i->name << " -> " << av_get_pix_fmt_name(av));
+    CHECK(vpf::fromAVPixelFormat(av) == i->format);
+  }
+  // The bridge is meant to cover most of the vocabulary; a collapse to a
+  // handful would mean the switch lost its cases.
+  CHECK(twins >= 40);
+}
+
+TEST_CASE("AV bridge: AV -> score -> AV round-trip", "[gfx][pixfmt][av]")
+{
+  for(const AVPixFmtDescriptor* d = av_pix_fmt_desc_next(nullptr); d;
+      d = av_pix_fmt_desc_next(d))
+  {
+    const auto av = av_pix_fmt_desc_get_id(d);
+    const auto f = vpf::fromAVPixelFormat(av);
+    if(f == V::Unknown)
+      continue;
+    INFO("AV " << av_get_pix_fmt_name(av) << " -> " << vpf::formatName(f));
+    CHECK(vpf::toAVPixelFormat(f) == av);
+  }
+}
+
+TEST_CASE("AV bridge: unmapped inputs return the sentinel", "[gfx][pixfmt][av]")
+{
+  CHECK(vpf::fromAVPixelFormat(AV_PIX_FMT_NONE) == V::Unknown);
+  // Hardware-surface and paletted formats have no place in this vocabulary.
+  CHECK(vpf::fromAVPixelFormat(AV_PIX_FMT_VAAPI) == V::Unknown);
+  CHECK(vpf::fromAVPixelFormat(AV_PIX_FMT_CUDA) == V::Unknown);
+  CHECK(vpf::fromAVPixelFormat(AV_PIX_FMT_DRM_PRIME) == V::Unknown);
+  CHECK(vpf::fromAVPixelFormat(AV_PIX_FMT_PAL8) == V::Unknown);
+  CHECK(vpf::toAVPixelFormat(V::Unknown) == AV_PIX_FMT_NONE);
+  // The wire-only formats are the reason this vocabulary exists: FFmpeg models
+  // them as codecs, so they must not claim a pixel-format twin.
+  for(auto f : {V::V210, V::V216, V::R210, V::RGB10, V::R12B, V::R12L, V::ARGB10,
+                V::DPX10, V::DPX10LE, V::RGB12P})
+  {
+    INFO("wire-only format " << vpf::formatName(f));
+    CHECK(vpf::toAVPixelFormat(f) == AV_PIX_FMT_NONE);
+  }
+  // YVU420P must not alias onto yuv420p: FFmpeg expresses YV12 by swapping the
+  // U and V pointers, so claiming a twin here would silently swap chroma.
+  CHECK(vpf::toAVPixelFormat(V::YVU420P) == AV_PIX_FMT_NONE);
+  CHECK(vpf::fromAVPixelFormat(AV_PIX_FMT_YUV420P) == V::YUV420P);
+}
+
+TEST_CASE("descriptors agree with FFmpeg for every mapped format",
+          "[gfx][pixfmt][av]")
+{
+  for(const auto* i : described())
+  {
+    const auto av = vpf::toAVPixelFormat(i->format);
+    if(av == AV_PIX_FMT_NONE)
+      continue;
+    const AVPixFmtDescriptor* d = av_pix_fmt_desc_get(av);
+    REQUIRE(d != nullptr);
+    INFO("format " << i->name << " vs FFmpeg " << av_get_pix_fmt_name(av));
+
+    CHECK(i->planeCount == av_pix_fmt_count_planes(av));
+    CHECK(i->horizontalSubsampling == (1 << d->log2_chroma_w));
+    CHECK(i->verticalSubsampling == (1 << d->log2_chroma_h));
+    CHECK(i->isPlanar() == ((d->flags & AV_PIX_FMT_FLAG_PLANAR) != 0));
+    CHECK(i->hasAlpha == ((d->flags & AV_PIX_FMT_FLAG_ALPHA) != 0));
+    CHECK(i->isRgb() == ((d->flags & AV_PIX_FMT_FLAG_RGB) != 0));
+    // FFmpeg marks big-endian layouts explicitly; little-endian and
+    // order-agnostic ones must not carry the flag.
+    const bool avBigEndian = (d->flags & AV_PIX_FMT_FLAG_BE) != 0;
+    CHECK((i->byteOrder == vpf::ByteOrder::Big) == avBigEndian);
+  }
+}

From cf78174eeb875ee72b4f3bba1832d8182f5c7b29 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 07:44:29 -0400
Subject: [PATCH 09/20] gfx: cover the 4:1:1, 4:1:0 and 16-bit layouts the
 camera backends need

Auditing the three camera backends against the vocabulary turned up formats none
of them could describe:

  V4L2    YUV411P, YUV410P, YVU410
  Win32   YV16 (YVU422P), Y210, Y216, P216, Y410 (XV30), Y416 (AYUV64),
          Y41P (UYYVYY411)
  AVF     422YpCbCr16 (YUV422P16), 4444YpCbCrA8 (YUVA444P)

Add all thirteen, plus P416 to complete the semi-planar 16-bit set. Ten have an
exact AVPixelFormat and are bridged; three do not and say why:

  YVU410P, YVU422P  plane-swapped, and FFmpeg expresses those by exchanging the
                    U and V pointers rather than with a distinct pixel format
  Y216              no AV_PIX_FMT_Y216 exists in any libav we support

YUVA444P is the first four-plane format in the table, which exercises the alpha
plane arm of bytesPerFrame that until now had no format reaching it. YUV410P is
the first with vertical subsampling 4; the suite asserted 1 or 2, so it would
have rejected a correct 4:1:0 descriptor.

XV30 deliberately reports no alpha: its top two bits are padding, not an alpha
channel, and FFmpeg agrees - the cross-check against AV_PIX_FMT_FLAG_ALPHA
passes only because of that distinction.

82 formats, no descriptor holes, no zero-size results, 52 AV twins with no
asymmetric round-trip, and no disagreement with the FFmpeg descriptor for any
twin. 22670 assertions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 .../Gfx/Graph/interop/VideoPixelFormat.hpp    | 18 ++++++++++++++
 .../Gfx/Graph/interop/VideoPixelFormatAV.cpp  | 24 +++++++++++++++++++
 tests/unit/VideoPixelFormatTest.cpp           |  5 ++--
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
index 1cd78deace..7b81c2eecc 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -140,6 +140,10 @@ enum class ByteOrder : uint8_t
   /* rule, so it needs no special case here.                                 */ \
   X(V210, 30, YUV, 1, 2, 1, 48, 128, false, Little, 128)                       \
   X(V216, 31, YUV, 1, 2, 1, 2, 8, false, Little, 256)                          \
+  /* Y210/Y216 carry YUYV component order in 16-bit lanes (Y210 uses the high  */ \
+  /* 10 bits); V216 differs from Y216 only in that order.                      */ \
+  X(Y210, 106, YUV, 1, 2, 1, 2, 8, false, Little, 256)                         \
+  X(Y216, 107, YUV, 1, 2, 1, 2, 8, false, Little, 256)                         \
   /* -- Planar / semi-planar 4:2:0 ----------------------------------------- */ \
   X(NV12, 40, YUV, 2, 2, 2, 1, 1, false, NA, 256)                              \
   X(P010, 41, YUV, 2, 2, 2, 1, 2, false, Little, 256)                          \
@@ -154,6 +158,14 @@ enum class ByteOrder : uint8_t
   X(NV16, 53, YUV, 2, 2, 1, 1, 1, false, NA, 256)                              \
   X(NV61, 54, YUV, 2, 2, 1, 1, 1, false, NA, 256)                              \
   X(YUV422P12, 55, YUV, 3, 2, 1, 1, 2, false, Little, 256)                     \
+  X(YUV422P16, 110, YUV, 3, 2, 1, 1, 2, false, Little, 256)                    \
+  X(YVU422P, 104, YUV, 3, 2, 1, 1, 1, false, NA, 256)                          \
+  X(P216, 108, YUV, 2, 2, 1, 1, 2, false, Little, 256)                         \
+  /* -- Planar 4:1:1 and 4:1:0 (webcams, legacy capture) ------------------- */ \
+  X(YUV411P, 101, YUV, 3, 4, 1, 1, 1, false, NA, 256)                          \
+  X(YUV410P, 102, YUV, 3, 4, 4, 1, 1, false, NA, 256)                          \
+  X(YVU410P, 103, YUV, 3, 4, 4, 1, 1, false, NA, 256)                          \
+  X(UYYVYY411, 105, YUV, 1, 4, 1, 4, 6, false, NA, 256)                        \
   /* -- Planar / semi-planar / packed 4:4:4 -------------------------------- */ \
   X(YUV444P, 60, YUV, 3, 1, 1, 1, 1, false, NA, 256)                           \
   X(YUV444P10, 61, YUV, 3, 1, 1, 1, 2, false, Little, 256)                     \
@@ -166,6 +178,12 @@ enum class ByteOrder : uint8_t
   X(XYUV, 68, YUV, 1, 1, 1, 1, 4, false, NA, 256)                              \
   X(YUVA, 69, YUV, 1, 1, 1, 1, 4, true, NA, 256)                               \
   X(YUVX, 73, YUV, 1, 1, 1, 1, 4, false, NA, 256)                              \
+  X(YUVA444P, 111, YUV, 4, 1, 1, 1, 1, true, NA, 256)                          \
+  X(P416, 109, YUV, 2, 1, 1, 1, 2, false, Little, 256)                         \
+  /* XV30 packs 2 padding bits + three 10-bit components into 32 bits; the pad */ \
+  /* is not alpha. AYUV64 is the same geometry at 16 bits with real alpha.     */ \
+  X(XV30, 112, YUV, 1, 1, 1, 1, 4, false, Little, 256)                         \
+  X(AYUV64, 113, YUV, 1, 1, 1, 1, 8, true, Little, 256)                        \
   /* -- High-precision RGB ------------------------------------------------- */ \
   X(RGBA16, 70, RGB, 1, 1, 1, 1, 8, true, Little, 256)                         \
   X(RGBA16F, 71, RGB, 1, 1, 1, 1, 8, true, Little, 256)                        \
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
index 289bbd1282..e98fe24b73 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
@@ -52,6 +52,14 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     case V::YUV422P:   return AV_PIX_FMT_YUV422P;
     case V::YUV422P10: return AV_PIX_FMT_YUV422P10LE;
     case V::YUV422P12: return AV_PIX_FMT_YUV422P12LE;
+    case V::YUV422P16: return AV_PIX_FMT_YUV422P16LE;
+    case V::YUV411P:   return AV_PIX_FMT_YUV411P;
+    case V::YUV410P:   return AV_PIX_FMT_YUV410P;
+    case V::UYYVYY411: return AV_PIX_FMT_UYYVYY411;
+    case V::P216:      return AV_PIX_FMT_P216LE;
+    case V::P416:      return AV_PIX_FMT_P416LE;
+    case V::Y210:      return AV_PIX_FMT_Y210LE;
+    case V::YUVA444P:  return AV_PIX_FMT_YUVA444P;
     case V::YUV444P:   return AV_PIX_FMT_YUV444P;
     case V::YUV444P10: return AV_PIX_FMT_YUV444P10LE;
     case V::YUV444P12: return AV_PIX_FMT_YUV444P12LE;
@@ -60,11 +68,14 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
 #if LIBAVUTIL_VERSION_INT >= AV_VERSION_INT(57, 36, 100)
     case V::VUYA:      return AV_PIX_FMT_VUYA;
     case V::VUYX:      return AV_PIX_FMT_VUYX;
+    case V::XV30:      return AV_PIX_FMT_XV30LE;
 #else
     case V::VUYA:
     case V::VUYX:
+    case V::XV30:
       return AV_PIX_FMT_NONE;
 #endif
+    case V::AYUV64:    return AV_PIX_FMT_AYUV64LE;
 
     // -- grey --
     case V::Mono8:     return AV_PIX_FMT_GRAY8;
@@ -94,7 +105,10 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     // with the U and V pointers exchanged, so returning yuv420p here would
     // silently swap chroma -- the exact bug this bridge exists to avoid.
     case V::YVU420P:
+    case V::YVU410P:
+    case V::YVU422P:
     case V::NV61:      // no AV_PIX_FMT_NV61 (NV16 with the pair exchanged)
+    case V::Y216:      // no AV_PIX_FMT_Y216 in any supported libav
     // Packed 4:4:4 orders FFmpeg does not spell: it has VUYA/VUYX/UYVA only.
     case V::AYUV:
     case V::XYUV:
@@ -152,13 +166,23 @@ VideoPixelFormat fromAVPixelFormat(AVPixelFormat f) noexcept
     case AV_PIX_FMT_YUV422P:     return V::YUV422P;
     case AV_PIX_FMT_YUV422P10LE: return V::YUV422P10;
     case AV_PIX_FMT_YUV422P12LE: return V::YUV422P12;
+    case AV_PIX_FMT_YUV422P16LE: return V::YUV422P16;
+    case AV_PIX_FMT_YUV411P:     return V::YUV411P;
+    case AV_PIX_FMT_YUV410P:     return V::YUV410P;
+    case AV_PIX_FMT_UYYVYY411:   return V::UYYVYY411;
+    case AV_PIX_FMT_P216LE:      return V::P216;
+    case AV_PIX_FMT_P416LE:      return V::P416;
+    case AV_PIX_FMT_Y210LE:      return V::Y210;
+    case AV_PIX_FMT_YUVA444P:    return V::YUVA444P;
     case AV_PIX_FMT_YUV444P:     return V::YUV444P;
     case AV_PIX_FMT_YUV444P10LE: return V::YUV444P10;
     case AV_PIX_FMT_YUV444P12LE: return V::YUV444P12;
 #if LIBAVUTIL_VERSION_INT >= AV_VERSION_INT(57, 36, 100)
     case AV_PIX_FMT_VUYA:        return V::VUYA;
     case AV_PIX_FMT_VUYX:        return V::VUYX;
+    case AV_PIX_FMT_XV30LE:      return V::XV30;
 #endif
+    case AV_PIX_FMT_AYUV64LE:    return V::AYUV64;
     case AV_PIX_FMT_GRAY8:       return V::Mono8;
     case AV_PIX_FMT_GRAY10LE:    return V::Mono10;
     case AV_PIX_FMT_GRAY12LE:    return V::Mono12;
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index f7e5379174..69bc9afd77 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -100,7 +100,8 @@ TEST_CASE("the vocabulary is non-trivial and self-consistent", "[gfx][pixfmt]")
     // Subsampling is only meaningful in the two documented axes.
     CHECK((i->horizontalSubsampling == 1 || i->horizontalSubsampling == 2
            || i->horizontalSubsampling == 4));
-    CHECK((i->verticalSubsampling == 1 || i->verticalSubsampling == 2));
+    CHECK((i->verticalSubsampling == 1 || i->verticalSubsampling == 2
+           || i->verticalSubsampling == 4));
     // formatInfo() must resolve the value back to this very row.
     CHECK(&vpf::formatInfo(i->format) == i);
     CHECK(std::string(vpf::formatName(i->format)) == i->name);
@@ -160,7 +161,7 @@ TEST_CASE("multi-byte samples declare a byte order", "[gfx][pixfmt]")
 
 TEST_CASE("unknown / out-of-range formats return the sentinel", "[gfx][pixfmt]")
 {
-  for(auto f : {V::Unknown, V(1234), V(65535), V(101)})
+  for(auto f : {V::Unknown, V(1234), V(65535), V(200)})
   {
     const auto& u = vpf::formatInfo(f);
     CHECK(std::string(u.name) == "unknown");

From 0dcb0fea836e31687f19a24b66d4cd3a08c3c033 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 08:10:09 -0400
Subject: [PATCH 10/20] gfx: make the Bayer colour-filter-array order part of
 the format

BayerRG8/BayerRG12 named a generic mosaic, but the CFA order decides which
sensor cell a demosaic reads as red: interpreting BGGR data as RGGB swaps red
and blue. V4L2 exposes the four 8-bit orders as distinct fourccs and FFmpeg has
a pixel format for each, so a single generic Bayer format cannot describe what
the camera is actually sending.

Add the four 8-bit orders plus the two 16-bit ones FFmpeg carries, all bridged.
BayerRG8/BayerRG12 stay for the Ximea path, which reports its order out of band.

The FFmpeg cross-check needed a real relationship rather than an equality here:
FFmpeg sets AV_PIX_FMT_FLAG_RGB on Bayer, because a mosaic is made of R/G/B
filters, while we keep Bayer as its own colour model because a demosaic has to
run before the samples are RGB in any usable sense. The suite now asserts
"RGB-like", which is what the flag actually means, instead of silently disagreeing.

88 formats, 58 AV twins, no descriptor holes, no asymmetric round-trip, no
disagreement with the FFmpeg descriptor. 24366 assertions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 .../Gfx/Graph/interop/VideoPixelFormat.hpp         |  8 ++++++++
 .../Gfx/Graph/interop/VideoPixelFormatAV.cpp       | 14 ++++++++++++++
 tests/unit/VideoPixelFormatTest.cpp                |  7 ++++++-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
index 7b81c2eecc..694f87b793 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -195,6 +195,14 @@ enum class ByteOrder : uint8_t
   X(Mono16, 83, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
   X(BayerRG8, 84, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                         \
   X(BayerRG12, 85, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                    \
+  /* The CFA order decides how a demosaic reads the mosaic, so the four 8-bit  */ \
+  /* orders are distinct formats rather than one generic Bayer.                */ \
+  X(BayerBGGR8, 114, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                      \
+  X(BayerGBRG8, 115, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                      \
+  X(BayerGRBG8, 116, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                      \
+  X(BayerRGGB8, 117, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                      \
+  X(BayerBGGR16, 118, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                 \
+  X(BayerRGGB16, 119, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                 \
   X(Mono16BE, 86, Grey, 1, 1, 1, 1, 2, false, Big, 64)
 
 /** Comprehensive pixel format enum, generated from the table above.
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
index e98fe24b73..cf093b4d9d 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
@@ -84,6 +84,14 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     case V::Mono16:    return AV_PIX_FMT_GRAY16LE;
     case V::Mono16BE:  return AV_PIX_FMT_GRAY16BE;
 
+    // -- Bayer: the CFA order is part of the format identity --
+    case V::BayerBGGR8:  return AV_PIX_FMT_BAYER_BGGR8;
+    case V::BayerGBRG8:  return AV_PIX_FMT_BAYER_GBRG8;
+    case V::BayerGRBG8:  return AV_PIX_FMT_BAYER_GRBG8;
+    case V::BayerRGGB8:  return AV_PIX_FMT_BAYER_RGGB8;
+    case V::BayerBGGR16: return AV_PIX_FMT_BAYER_BGGR16LE;
+    case V::BayerRGGB16: return AV_PIX_FMT_BAYER_RGGB16LE;
+
     // -- wire-only: no AVPixelFormat (FFmpeg models these as codecs) --
     case V::V210:      // AV_CODEC_ID_V210
     case V::V216:      // AV_CODEC_ID_V210X
@@ -188,6 +196,12 @@ VideoPixelFormat fromAVPixelFormat(AVPixelFormat f) noexcept
     case AV_PIX_FMT_GRAY12LE:    return V::Mono12;
     case AV_PIX_FMT_GRAY16LE:    return V::Mono16;
     case AV_PIX_FMT_GRAY16BE:    return V::Mono16BE;
+    case AV_PIX_FMT_BAYER_BGGR8:    return V::BayerBGGR8;
+    case AV_PIX_FMT_BAYER_GBRG8:    return V::BayerGBRG8;
+    case AV_PIX_FMT_BAYER_GRBG8:    return V::BayerGRBG8;
+    case AV_PIX_FMT_BAYER_RGGB8:    return V::BayerRGGB8;
+    case AV_PIX_FMT_BAYER_BGGR16LE: return V::BayerBGGR16;
+    case AV_PIX_FMT_BAYER_RGGB16LE: return V::BayerRGGB16;
     default:                     return V::Unknown;
   }
 }
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 69bc9afd77..3426b4b608 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -442,7 +442,12 @@ TEST_CASE("descriptors agree with FFmpeg for every mapped format",
     CHECK(i->verticalSubsampling == (1 << d->log2_chroma_h));
     CHECK(i->isPlanar() == ((d->flags & AV_PIX_FMT_FLAG_PLANAR) != 0));
     CHECK(i->hasAlpha == ((d->flags & AV_PIX_FMT_FLAG_ALPHA) != 0));
-    CHECK(i->isRgb() == ((d->flags & AV_PIX_FMT_FLAG_RGB) != 0));
+    // FFmpeg's RGB flag means "components are R/G/B rather than luma+chroma",
+    // which is true of a Bayer mosaic too. We keep Bayer as its own colour model
+    // because a demosaic has to run before the samples are RGB in any usable
+    // sense, so the two agree on everything except that naming.
+    CHECK((i->isRgb() || i->colorModel == ColorModel::Bayer)
+          == ((d->flags & AV_PIX_FMT_FLAG_RGB) != 0));
     // FFmpeg marks big-endian layouts explicitly; little-endian and
     // order-agnostic ones must not carry the flag.
     const bool avBigEndian = (d->flags & AV_PIX_FMT_FLAG_BE) != 0;

From 357bcb1f3fe91833d17e4c2f349f781acc5b6dd8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 08:14:55 -0400
Subject: [PATCH 11/20] gfx: one V4L2 fourcc table instead of two that
 disagreed

The V4L2 fourcc mapping existed twice: a table vendored from libavdevice in the
camera enumeration, and a second one in the DMA capture backend. They had
already drifted -- the deprecated V4L2_PIX_FMT_RGB32 resolved to XRGB in one and
RGBX in the other, which is a red/blue swap for whichever caller was wrong.

Put the layouts in interop/V4L2PixelFormat, shared by both, and derive the
AVPixelFormat through the existing bridge rather than maintaining a second
opinion about it. The deprecated RGB32/BGR32 pair resolves the way libavdevice
has long assumed, which is also what the kernel documents.

The compressed fourccs stay in the camera enumeration as a five-entry table,
because MJPEG, H.264, MPEG-4 and CPIA are codecs, not pixel formats. Mixing the
two axes in one table is what made the old one describe a raw layout and a
compressed stream with the same row shape.

Also adds chromaSwappedTwin(). The V-before-U layouts (YV12, YV16, YVU9) have no
AVPixelFormat of their own, so before this the enumeration named their U-first
twin and forgot, which silently exchanges red and blue. Naming the twin
*and* recording the relationship is strictly more information: the enumeration
keeps offering those cameras exactly as before, and a consumer that wants
correct chroma now has something to ask.

Verified non-regressing by construction: all 28 raw entries of the vendored
table produce the same AVPixelFormat through the new path, checked
programmatically rather than by reading. New guardrails assert that every
V4L2-mapped format round-trips, that compressed fourccs resolve to no layout,
and that a swapped layout and its twin agree on every geometric field and on
frame size. 24477 assertions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-gfx/CMakeLists.txt   |   2 +
 .../Gfx/CameraDevice.v4l2.cpp                 | 110 ++++-------
 .../Gfx/Graph/interop/V4L2PixelFormat.cpp     | 178 ++++++++++++++++++
 .../Gfx/Graph/interop/V4L2PixelFormat.hpp     |  37 ++++
 .../Gfx/Graph/interop/VideoPixelFormat.cpp    |  14 ++
 .../Gfx/Graph/interop/VideoPixelFormat.hpp    |  11 ++
 tests/unit/VideoPixelFormatTest.cpp           |  58 ++++++
 7 files changed, 337 insertions(+), 73 deletions(-)
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.cpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.hpp

diff --git a/src/plugins/score-plugin-gfx/CMakeLists.txt b/src/plugins/score-plugin-gfx/CMakeLists.txt
index c7327d1f2b..0e81b30f43 100644
--- a/src/plugins/score-plugin-gfx/CMakeLists.txt
+++ b/src/plugins/score-plugin-gfx/CMakeLists.txt
@@ -242,7 +242,9 @@ set(HDRS
     Gfx/Graph/interop/VideoPixelFormatAV.hpp
     Gfx/Graph/interop/VideoPixelFormatAV.cpp
     Gfx/Graph/interop/VideoPixelFormat.hpp
+    Gfx/Graph/interop/V4L2PixelFormat.hpp
     Gfx/Graph/interop/VideoPixelFormat.cpp
+    Gfx/Graph/interop/V4L2PixelFormat.cpp
 
     Gfx/Graph/decoders/GPUVideoDecoder.hpp
     Gfx/Graph/decoders/GPUVideoDecoderFactory.hpp
diff --git a/src/plugins/score-plugin-gfx/Gfx/CameraDevice.v4l2.cpp b/src/plugins/score-plugin-gfx/Gfx/CameraDevice.v4l2.cpp
index 9690c37aa6..6881622d80 100644
--- a/src/plugins/score-plugin-gfx/Gfx/CameraDevice.v4l2.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/CameraDevice.v4l2.cpp
@@ -30,99 +30,63 @@ void *v4l2_mmap(void *start, size_t length, int prot, int flags,
 int v4l2_munmap(void *_start, size_t length);
 }
 
+#include <Gfx/Graph/interop/V4L2PixelFormat.hpp>
+#include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
+
 namespace Gfx
 {
 namespace
 {
-// Imported from ffmpeg source code
-struct fmt_map
+// V4L2 exposes two kinds of fourcc: raw buffer layouts, and compressed
+// streams. The layouts are described once, in interop/V4L2PixelFormat, shared
+// with the DMA capture path -- this file used to carry a second, independently
+// maintained copy of that mapping. Only the codec side stays here, because a
+// codec is not a pixel format.
+struct compressed_fmt
 {
-  enum AVPixelFormat ff_fmt;
-  enum AVCodecID codec_id;
   uint32_t v4l2_fmt;
+  AVCodecID codec_id;
 };
 
-const struct fmt_map ff_fmt_conversion_table[] = {
-    //ff_fmt              codec_id              v4l2_fmt
-    {AV_PIX_FMT_YUV420P, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_YUV420},
-    {AV_PIX_FMT_YUV420P, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_YVU420},
-    {AV_PIX_FMT_YUV422P, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_YUV422P},
-    {AV_PIX_FMT_YUYV422, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_YUYV},
-    {AV_PIX_FMT_UYVY422, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_UYVY},
-    {AV_PIX_FMT_YUV411P, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_YUV411P},
-    {AV_PIX_FMT_YUV410P, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_YUV410},
-    {AV_PIX_FMT_YUV410P, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_YVU410},
-    {AV_PIX_FMT_RGB555LE, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_RGB555},
-    {AV_PIX_FMT_RGB555BE, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_RGB555X},
-    {AV_PIX_FMT_RGB565LE, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_RGB565},
-    {AV_PIX_FMT_RGB565BE, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_RGB565X},
-    {AV_PIX_FMT_BGR24, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_BGR24},
-    {AV_PIX_FMT_RGB24, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_RGB24},
-#ifdef V4L2_PIX_FMT_XBGR32
-    {AV_PIX_FMT_BGR0, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_XBGR32},
-    {AV_PIX_FMT_0RGB, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_XRGB32},
-    {AV_PIX_FMT_BGRA, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_ABGR32},
-    {AV_PIX_FMT_ARGB, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_ARGB32},
-#endif
-    {AV_PIX_FMT_BGR0, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_BGR32},
-    {AV_PIX_FMT_0RGB, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_RGB32},
-    {AV_PIX_FMT_GRAY8, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_GREY},
-#ifdef V4L2_PIX_FMT_Y16
-    {AV_PIX_FMT_GRAY16LE, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_Y16},
-#endif
-#ifdef V4L2_PIX_FMT_Z16
-    {AV_PIX_FMT_GRAY16LE, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_Z16},
-#endif
-    {AV_PIX_FMT_NV12, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_NV12},
-    {AV_PIX_FMT_NONE, AV_CODEC_ID_MJPEG, V4L2_PIX_FMT_MJPEG},
-    {AV_PIX_FMT_NONE, AV_CODEC_ID_MJPEG, V4L2_PIX_FMT_JPEG},
+const compressed_fmt compressed_formats[] = {
+    {V4L2_PIX_FMT_MJPEG, AV_CODEC_ID_MJPEG},
+    {V4L2_PIX_FMT_JPEG, AV_CODEC_ID_MJPEG},
 #ifdef V4L2_PIX_FMT_H264
-    {AV_PIX_FMT_NONE, AV_CODEC_ID_H264, V4L2_PIX_FMT_H264},
+    {V4L2_PIX_FMT_H264, AV_CODEC_ID_H264},
 #endif
 #ifdef V4L2_PIX_FMT_MPEG4
-    {AV_PIX_FMT_NONE, AV_CODEC_ID_MPEG4, V4L2_PIX_FMT_MPEG4},
+    {V4L2_PIX_FMT_MPEG4, AV_CODEC_ID_MPEG4},
 #endif
 #ifdef V4L2_PIX_FMT_CPIA1
-    {AV_PIX_FMT_NONE, AV_CODEC_ID_CPIA, V4L2_PIX_FMT_CPIA1},
-#endif
-#ifdef V4L2_PIX_FMT_SRGGB8
-    {AV_PIX_FMT_BAYER_BGGR8, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_SBGGR8},
-    {AV_PIX_FMT_BAYER_GBRG8, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_SGBRG8},
-    {AV_PIX_FMT_BAYER_GRBG8, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_SGRBG8},
-    {AV_PIX_FMT_BAYER_RGGB8, AV_CODEC_ID_RAWVIDEO, V4L2_PIX_FMT_SRGGB8},
+    {V4L2_PIX_FMT_CPIA1, AV_CODEC_ID_CPIA},
 #endif
-    {AV_PIX_FMT_NONE, AV_CODEC_ID_NONE, 0},
 };
 
-enum AVPixelFormat ff_fmt_v4l2ff(uint32_t v4l2_fmt, enum AVCodecID codec_id)
+AVCodecID ff_fmt_v4l2codec(uint32_t v4l2_fmt)
 {
-  int i;
-
-  for(i = 0; ff_fmt_conversion_table[i].codec_id != AV_CODEC_ID_NONE; i++)
-  {
-    if(ff_fmt_conversion_table[i].v4l2_fmt == v4l2_fmt
-       && ff_fmt_conversion_table[i].codec_id == codec_id)
-    {
-      return ff_fmt_conversion_table[i].ff_fmt;
-    }
-  }
-
-  return AV_PIX_FMT_NONE;
+  for(const auto& c : compressed_formats)
+    if(c.v4l2_fmt == v4l2_fmt)
+      return c.codec_id;
+  return score::gfx::interop::fromV4L2PixelFormat(v4l2_fmt)
+                 != score::gfx::interop::VideoPixelFormat::Unknown
+             ? AV_CODEC_ID_RAWVIDEO
+             : AV_CODEC_ID_NONE;
 }
 
-enum AVCodecID ff_fmt_v4l2codec(uint32_t v4l2_fmt)
+AVPixelFormat ff_fmt_v4l2ff(uint32_t v4l2_fmt, AVCodecID codec_id)
 {
-  int i;
-
-  for(i = 0; ff_fmt_conversion_table[i].codec_id != AV_CODEC_ID_NONE; i++)
-  {
-    if(ff_fmt_conversion_table[i].v4l2_fmt == v4l2_fmt)
-    {
-      return ff_fmt_conversion_table[i].codec_id;
-    }
-  }
-
-  return AV_CODEC_ID_NONE;
+  if(codec_id != AV_CODEC_ID_RAWVIDEO)
+    return AV_PIX_FMT_NONE;
+
+  using namespace score::gfx::interop;
+  const auto layout = fromV4L2PixelFormat(v4l2_fmt);
+  if(const auto av = toAVPixelFormat(layout); av != AV_PIX_FMT_NONE)
+    return av;
+  // The V-before-U layouts have no AVPixelFormat of their own. Name the twin so
+  // the format stays offered, as it was before this mapping was shared; a
+  // consumer wanting correct chroma must exchange the U and V planes, which
+  // chromaSwappedTwin() is what records.
+  return toAVPixelFormat(chromaSwappedTwin(layout));
 }
 
 class libv4l2
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.cpp
new file mode 100644
index 0000000000..7d893b4ac6
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.cpp
@@ -0,0 +1,178 @@
+#include <Gfx/Graph/interop/V4L2PixelFormat.hpp>
+
+#if defined(__linux__)
+#include <linux/videodev2.h>
+
+namespace score::gfx::interop
+{
+
+VideoPixelFormat fromV4L2PixelFormat(uint32_t fourcc) noexcept
+{
+  using V = VideoPixelFormat;
+  switch(fourcc)
+  {
+    // -- packed YUV 4:2:2 --
+    case V4L2_PIX_FMT_UYVY:    return V::UYVY422;
+    case V4L2_PIX_FMT_YUYV:    return V::YUYV422;
+    case V4L2_PIX_FMT_YVYU:    return V::YVYU422;
+    case V4L2_PIX_FMT_VYUY:    return V::VYUY422;
+
+    // -- semi-planar --
+    case V4L2_PIX_FMT_NV12:    return V::NV12;
+    case V4L2_PIX_FMT_NV21:    return V::NV21;
+    case V4L2_PIX_FMT_NV16:    return V::NV16;
+    case V4L2_PIX_FMT_NV61:    return V::NV61;
+    case V4L2_PIX_FMT_NV24:    return V::NV24;
+    case V4L2_PIX_FMT_NV42:    return V::NV42;
+
+    // -- fully planar. The V-first orders are distinct layouts, not the
+    //    U-first ones with a flag: reading YV12 as I420 swaps chroma.
+    case V4L2_PIX_FMT_YUV420:  return V::YUV420P;
+    case V4L2_PIX_FMT_YVU420:  return V::YVU420P;
+    case V4L2_PIX_FMT_YUV422P: return V::YUV422P;
+    case V4L2_PIX_FMT_YUV411P: return V::YUV411P;
+    case V4L2_PIX_FMT_YUV410:  return V::YUV410P;
+    case V4L2_PIX_FMT_YVU410:  return V::YVU410P;
+#ifdef V4L2_PIX_FMT_YUV444M
+    case V4L2_PIX_FMT_YUV444M: return V::YUV444P;
+#endif
+
+    // -- packed 4:4:4 with or without alpha --
+    case V4L2_PIX_FMT_VUYA32:  return V::VUYA;
+    case V4L2_PIX_FMT_VUYX32:  return V::VUYX;
+    case V4L2_PIX_FMT_AYUV32:  return V::AYUV;
+    case V4L2_PIX_FMT_XYUV32:  return V::XYUV;
+    case V4L2_PIX_FMT_YUVA32:  return V::YUVA;
+    case V4L2_PIX_FMT_YUVX32:  return V::YUVX;
+
+    // -- packed 16-bit YUV --
+    case V4L2_PIX_FMT_YUV444:  return V::AYUV4444;
+    case V4L2_PIX_FMT_YUV555:  return V::AYUV1555;
+    case V4L2_PIX_FMT_YUV565:  return V::YUV565;
+
+    // -- packed 32-bit RGB. The fourcc names the memory byte order.
+    case V4L2_PIX_FMT_ARGB32:  return V::ARGB8;
+    case V4L2_PIX_FMT_XRGB32:  return V::XRGB8;
+    case V4L2_PIX_FMT_ABGR32:  return V::BGRA8;
+    case V4L2_PIX_FMT_XBGR32:  return V::BGRX8;
+#ifdef V4L2_PIX_FMT_RGBA32
+    case V4L2_PIX_FMT_RGBA32:  return V::RGBA8;
+    case V4L2_PIX_FMT_RGBX32:  return V::RGBX8;
+    case V4L2_PIX_FMT_BGRA32:  return V::ABGR8;
+    case V4L2_PIX_FMT_BGRX32:  return V::XBGR8;
+#endif
+    // Deprecated aliases. The kernel documents them as the X-variants with
+    // undefined alpha, which is also what libavdevice has long assumed.
+    case V4L2_PIX_FMT_RGB32:   return V::XRGB8;
+    case V4L2_PIX_FMT_BGR32:   return V::BGRX8;
+
+    // -- packed 24-bit and sub-byte RGB --
+    case V4L2_PIX_FMT_RGB24:   return V::RGB24;
+    case V4L2_PIX_FMT_BGR24:   return V::BGR24;
+    case V4L2_PIX_FMT_RGB332:  return V::RGB332;
+    case V4L2_PIX_FMT_RGB565:  return V::RGB565;
+    case V4L2_PIX_FMT_RGB565X: return V::RGB565BE;
+    case V4L2_PIX_FMT_RGB555:  return V::RGB555;
+    case V4L2_PIX_FMT_RGB555X: return V::RGB555BE;
+    case V4L2_PIX_FMT_ARGB555: return V::ARGB1555;
+    case V4L2_PIX_FMT_ARGB444: return V::ARGB4444;
+    case V4L2_PIX_FMT_RGB444:  return V::RGB444;
+
+    // -- single channel: greyscale sensors and depth streams. Z16 is depth,
+    //    but its layout is a 16-bit single channel like any other.
+    case V4L2_PIX_FMT_GREY:    return V::Mono8;
+    case V4L2_PIX_FMT_Y10:     return V::Mono10;
+    case V4L2_PIX_FMT_Y12:     return V::Mono12;
+    case V4L2_PIX_FMT_Y16:     return V::Mono16;
+    case V4L2_PIX_FMT_Y16_BE:  return V::Mono16BE;
+#ifdef V4L2_PIX_FMT_Z16
+    case V4L2_PIX_FMT_Z16:     return V::Mono16;
+#endif
+
+    // -- Bayer: the fourcc names the colour-filter-array order --
+    case V4L2_PIX_FMT_SBGGR8:  return V::BayerBGGR8;
+    case V4L2_PIX_FMT_SGBRG8:  return V::BayerGBRG8;
+    case V4L2_PIX_FMT_SGRBG8:  return V::BayerGRBG8;
+    case V4L2_PIX_FMT_SRGGB8:  return V::BayerRGGB8;
+#ifdef V4L2_PIX_FMT_SBGGR16
+    case V4L2_PIX_FMT_SBGGR16: return V::BayerBGGR16;
+#endif
+#ifdef V4L2_PIX_FMT_SRGGB16
+    case V4L2_PIX_FMT_SRGGB16: return V::BayerRGGB16;
+#endif
+
+    default:                   return V::Unknown;
+  }
+}
+
+uint32_t toV4L2PixelFormat(VideoPixelFormat f) noexcept
+{
+  using V = VideoPixelFormat;
+  switch(f)
+  {
+    case V::UYVY422:    return V4L2_PIX_FMT_UYVY;
+    case V::YUYV422:    return V4L2_PIX_FMT_YUYV;
+    case V::YVYU422:    return V4L2_PIX_FMT_YVYU;
+    case V::VYUY422:    return V4L2_PIX_FMT_VYUY;
+    case V::NV12:       return V4L2_PIX_FMT_NV12;
+    case V::NV21:       return V4L2_PIX_FMT_NV21;
+    case V::NV16:       return V4L2_PIX_FMT_NV16;
+    case V::NV61:       return V4L2_PIX_FMT_NV61;
+    case V::NV24:       return V4L2_PIX_FMT_NV24;
+    case V::NV42:       return V4L2_PIX_FMT_NV42;
+    case V::YUV420P:    return V4L2_PIX_FMT_YUV420;
+    case V::YVU420P:    return V4L2_PIX_FMT_YVU420;
+    case V::YUV422P:    return V4L2_PIX_FMT_YUV422P;
+    case V::YUV411P:    return V4L2_PIX_FMT_YUV411P;
+    case V::YUV410P:    return V4L2_PIX_FMT_YUV410;
+    case V::YVU410P:    return V4L2_PIX_FMT_YVU410;
+    case V::VUYA:       return V4L2_PIX_FMT_VUYA32;
+    case V::VUYX:       return V4L2_PIX_FMT_VUYX32;
+    case V::AYUV:       return V4L2_PIX_FMT_AYUV32;
+    case V::XYUV:       return V4L2_PIX_FMT_XYUV32;
+    case V::YUVA:       return V4L2_PIX_FMT_YUVA32;
+    case V::YUVX:       return V4L2_PIX_FMT_YUVX32;
+    case V::AYUV4444:   return V4L2_PIX_FMT_YUV444;
+    case V::AYUV1555:   return V4L2_PIX_FMT_YUV555;
+    case V::YUV565:     return V4L2_PIX_FMT_YUV565;
+    case V::ARGB8:      return V4L2_PIX_FMT_ARGB32;
+    case V::XRGB8:      return V4L2_PIX_FMT_XRGB32;
+    case V::BGRA8:      return V4L2_PIX_FMT_ABGR32;
+    case V::BGRX8:      return V4L2_PIX_FMT_XBGR32;
+#ifdef V4L2_PIX_FMT_RGBA32
+    case V::RGBA8:      return V4L2_PIX_FMT_RGBA32;
+    case V::RGBX8:      return V4L2_PIX_FMT_RGBX32;
+    case V::ABGR8:      return V4L2_PIX_FMT_BGRA32;
+    case V::XBGR8:      return V4L2_PIX_FMT_BGRX32;
+#endif
+    case V::RGB24:      return V4L2_PIX_FMT_RGB24;
+    case V::BGR24:      return V4L2_PIX_FMT_BGR24;
+    case V::RGB332:     return V4L2_PIX_FMT_RGB332;
+    case V::RGB565:     return V4L2_PIX_FMT_RGB565;
+    case V::RGB565BE:   return V4L2_PIX_FMT_RGB565X;
+    case V::RGB555:     return V4L2_PIX_FMT_RGB555;
+    case V::RGB555BE:   return V4L2_PIX_FMT_RGB555X;
+    case V::ARGB1555:   return V4L2_PIX_FMT_ARGB555;
+    case V::ARGB4444:   return V4L2_PIX_FMT_ARGB444;
+    case V::RGB444:     return V4L2_PIX_FMT_RGB444;
+    case V::Mono8:      return V4L2_PIX_FMT_GREY;
+    case V::Mono10:     return V4L2_PIX_FMT_Y10;
+    case V::Mono12:     return V4L2_PIX_FMT_Y12;
+    case V::Mono16:     return V4L2_PIX_FMT_Y16;
+    case V::Mono16BE:   return V4L2_PIX_FMT_Y16_BE;
+    case V::BayerBGGR8: return V4L2_PIX_FMT_SBGGR8;
+    case V::BayerGBRG8: return V4L2_PIX_FMT_SGBRG8;
+    case V::BayerGRBG8: return V4L2_PIX_FMT_SGRBG8;
+    case V::BayerRGGB8: return V4L2_PIX_FMT_SRGGB8;
+#ifdef V4L2_PIX_FMT_SBGGR16
+    case V::BayerBGGR16: return V4L2_PIX_FMT_SBGGR16;
+#endif
+#ifdef V4L2_PIX_FMT_SRGGB16
+    case V::BayerRGGB16: return V4L2_PIX_FMT_SRGGB16;
+#endif
+    default:            return 0;
+  }
+}
+
+} // namespace score::gfx::interop
+#endif
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.hpp
new file mode 100644
index 0000000000..fa8ecffdd5
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/V4L2PixelFormat.hpp
@@ -0,0 +1,37 @@
+#pragma once
+
+/**
+ * @file V4L2PixelFormat.hpp
+ * @brief The one V4L2 fourcc <-> VideoPixelFormat table.
+ *
+ * Raw buffer layouts only. Compressed fourccs (MJPEG, JPEG, H.264, MPEG-4,
+ * CPIA) belong to the codec axis, not to a pixel-format vocabulary, and are
+ * resolved where the camera is enumerated.
+ *
+ * There used to be two independent V4L2 tables -- one to AVPixelFormat for
+ * camera enumeration, one to VideoPixelFormat for the DMA capture path -- and
+ * they disagreed. Anything needing an AVPixelFormat now goes through
+ * VideoPixelFormatAV rather than maintaining a second table.
+ */
+
+#include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+
+#include <score_plugin_gfx_export.h>
+
+#include <cstdint>
+
+namespace score::gfx::interop
+{
+
+/// The layout behind a V4L2 fourcc, or Unknown for compressed and unhandled
+/// fourccs. Takes the fourcc as a plain uint32_t so callers need no V4L2 header.
+SCORE_PLUGIN_GFX_EXPORT
+VideoPixelFormat fromV4L2PixelFormat(uint32_t fourcc) noexcept;
+
+/// The V4L2 fourcc a layout should be requested as, or 0 when V4L2 has none.
+/// Not a strict inverse: several fourccs alias onto one layout (the deprecated
+/// RGB32/BGR32 pair, Y16/Z16), and this returns the canonical one.
+SCORE_PLUGIN_GFX_EXPORT
+uint32_t toV4L2PixelFormat(VideoPixelFormat f) noexcept;
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
index a2f98392f7..aef8ef3fd4 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
@@ -61,6 +61,20 @@ const VideoPixelFormatInfo* allFormats(std::size_t& count) noexcept
   return kFormats;
 }
 
+VideoPixelFormat chromaSwappedTwin(VideoPixelFormat f) noexcept
+{
+  switch(f)
+  {
+    case VideoPixelFormat::YVU420P: return VideoPixelFormat::YUV420P;
+    case VideoPixelFormat::YVU422P: return VideoPixelFormat::YUV422P;
+    case VideoPixelFormat::YVU410P: return VideoPixelFormat::YUV410P;
+    case VideoPixelFormat::NV21:    return VideoPixelFormat::NV12;
+    case VideoPixelFormat::NV61:    return VideoPixelFormat::NV16;
+    case VideoPixelFormat::NV42:    return VideoPixelFormat::NV24;
+    default:                        return VideoPixelFormat::Unknown;
+  }
+}
+
 std::size_t rowBytes(VideoPixelFormat f, uint32_t width) noexcept
 {
   const auto& info = formatInfo(f);
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
index 694f87b793..5447d13624 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -280,6 +280,17 @@ const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept;
 SCORE_PLUGIN_GFX_EXPORT
 const char* formatName(VideoPixelFormat f) noexcept;
 
+/** For a layout that stores its chroma planes V-before-U (YV12, NV21, YV16,
+ *  ...), the otherwise identical U-before-V layout; Unknown for anything else.
+ *
+ *  FFmpeg has no pixel format for the swapped orders -- it expresses them by
+ *  exchanging the U and V pointers -- so a consumer that can only name an
+ *  AVPixelFormat needs both this twin and the knowledge that it must swap. That
+ *  is strictly more information than mapping the swapped layout onto its twin
+ *  and forgetting, which silently exchanges red and blue. */
+SCORE_PLUGIN_GFX_EXPORT
+VideoPixelFormat chromaSwappedTwin(VideoPixelFormat f) noexcept;
+
 /** Every described format, in table order. Lets callers -- and the unit test --
  *  enumerate the vocabulary without maintaining a second copy of the list. */
 SCORE_PLUGIN_GFX_EXPORT
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 3426b4b608..5ac130c1bb 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -24,6 +24,10 @@
 
 #include <Gfx/Graph/interop/VideoPixelFormat.hpp>
 #include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
+#if defined(__linux__)
+#include <Gfx/Graph/interop/V4L2PixelFormat.hpp>
+#include <linux/videodev2.h>
+#endif
 
 extern "C" {
 #include <libavutil/pixdesc.h>
@@ -454,3 +458,57 @@ TEST_CASE("descriptors agree with FFmpeg for every mapped format",
     CHECK((i->byteOrder == vpf::ByteOrder::Big) == avBigEndian);
   }
 }
+
+TEST_CASE("chroma-swapped twins are declared consistently", "[gfx][pixfmt]")
+{
+  for(const auto* i : described())
+  {
+    const auto twin = vpf::chromaSwappedTwin(i->format);
+    if(twin == V::Unknown)
+      continue;
+    INFO("format " << i->name << " twin " << vpf::formatName(twin));
+    const auto& t = vpf::formatInfo(twin);
+    // A swap changes which plane holds which component, nothing else: the two
+    // must agree on geometry, or one of the descriptors is wrong.
+    CHECK(t.planeCount == i->planeCount);
+    CHECK(t.horizontalSubsampling == i->horizontalSubsampling);
+    CHECK(t.verticalSubsampling == i->verticalSubsampling);
+    CHECK(t.blockPixels == i->blockPixels);
+    CHECK(t.blockBytes == i->blockBytes);
+    CHECK(t.colorModel == i->colorModel);
+    CHECK(vpf::bytesPerFrame(twin, 1920, 1080)
+          == vpf::bytesPerFrame(i->format, 1920, 1080));
+    // The twin is the U-before-V layout, so it is not itself swapped.
+    CHECK(vpf::chromaSwappedTwin(twin) == V::Unknown);
+    // FFmpeg names the semi-planar swaps (NV21, NV42) as formats of their own,
+    // but has none for the fully planar ones -- there it exchanges the U and V
+    // pointers instead. Either way a fallback must exist, which is what lets
+    // the camera enumeration keep offering these layouts.
+    if(vpf::toAVPixelFormat(i->format) == AV_PIX_FMT_NONE)
+      CHECK(vpf::toAVPixelFormat(twin) != AV_PIX_FMT_NONE);
+  }
+}
+
+#if defined(__linux__)
+TEST_CASE("V4L2 fourccs round-trip through the vocabulary", "[gfx][pixfmt][v4l2]")
+{
+  std::size_t mapped = 0;
+  for(const auto* i : described())
+  {
+    const auto fourcc = vpf::toV4L2PixelFormat(i->format);
+    if(fourcc == 0)
+      continue;
+    ++mapped;
+    INFO("format " << i->name);
+    CHECK(vpf::fromV4L2PixelFormat(fourcc) == i->format);
+  }
+  // The V4L2 camera formats are a large slice of the vocabulary; a collapse
+  // here would mean the table lost its cases.
+  CHECK(mapped >= 40);
+  CHECK(vpf::fromV4L2PixelFormat(0) == V::Unknown);
+  CHECK(vpf::fromV4L2PixelFormat(0xDEADBEEF) == V::Unknown);
+  // Compressed fourccs are on the codec axis and must not resolve to a layout.
+  CHECK(vpf::fromV4L2PixelFormat(V4L2_PIX_FMT_MJPEG) == V::Unknown);
+  CHECK(vpf::fromV4L2PixelFormat(V4L2_PIX_FMT_JPEG) == V::Unknown);
+}
+#endif

From c963414d4ba41ef77c596ecec78d0958b8690bc1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 08:30:39 -0400
Subject: [PATCH 12/20] gfx: size chroma planes with ceiling division, not
 truncation

bytesPerFrame computed the chroma plane dimensions as width / hsub and
height / vsub. A 4:2:0 frame of 1081 rows has 541 chroma rows, not 540, so the
reported size was short by a whole chroma row:

  YUV420P 1920x1081   3319808 reported   3321856 needed   -2048 B
  NV12    1920x1081                                       -2048 B
  P010    1920x1081                                       -3840 B
  YUV410P 1920x1081   270 chroma rows instead of 271

A caller sizing a buffer from this and then letting a capture card or decoder
write the ceiling row count overflows the allocation. Stride padding hides the
analogous odd-*width* truncation, but nothing hides a missing row.

This predates the vocabulary rework -- the original carried the same expression,
which is why comparing the rewrite against a captured baseline could not see it:
both sides truncated identically. It took mutation testing the suite to surface
it, and the reason the suite could not was that bytesPerFrame was only ever
asserted at 1920x1080, where both dimensions divide evenly. The odd widths in
the width sweep were used by rowBytes only.

The new case sweeps every format at odd widths and heights, and computes the
expectation with ceiling arithmetic rather than restating the implementation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 .../Gfx/Graph/interop/VideoPixelFormat.cpp    | 11 ++++-
 tests/unit/VideoPixelFormatTest.cpp           | 41 +++++++++++++++++++
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
index aef8ef3fd4..a237f14907 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.cpp
@@ -114,8 +114,15 @@ bytesPerFrame(VideoPixelFormat f, uint32_t width, uint32_t height) noexcept
   // preferred stride as luma. Semi-planar formats gather both chroma components
   // into one plane of double width; fully planar ones use two separate planes,
   // which comes to the same number of samples.
-  const auto cWidth = uint32_t(width / info.horizontalSubsampling);
-  const auto cHeight = std::size_t(height / info.verticalSubsampling);
+  //
+  // Round the chroma dimensions UP: a 4:2:0 frame of 1081 rows has 541 chroma
+  // rows, not 540. Truncating under-reports the frame by a whole chroma row, so
+  // a caller sizing a buffer from this and then letting a card or decoder write
+  // the ceiling row count overflows the allocation.
+  const auto cWidth
+      = uint32_t((width + info.horizontalSubsampling - 1) / info.horizontalSubsampling);
+  const auto cHeight
+      = std::size_t((height + info.verticalSubsampling - 1) / info.verticalSubsampling);
   switch(info.planeCount)
   {
     case 2:
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 5ac130c1bb..a245a60ceb 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -512,3 +512,44 @@ TEST_CASE("V4L2 fourccs round-trip through the vocabulary", "[gfx][pixfmt][v4l2]
   CHECK(vpf::fromV4L2PixelFormat(V4L2_PIX_FMT_JPEG) == V::Unknown);
 }
 #endif
+
+TEST_CASE("bytesPerFrame rounds chroma up at odd sizes", "[gfx][pixfmt]")
+{
+  // Truncating the chroma dimensions loses a whole row or column, and the
+  // shortfall is invisible at 1920x1080 because both dimensions divide evenly.
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    for(uint32_t w : {1u, 3u, 7u, 719u, 1921u})
+    {
+      for(uint32_t h : {1u, 3u, 1081u})
+      {
+        const auto cw
+            = (w + i->horizontalSubsampling - 1) / i->horizontalSubsampling;
+        const auto ch = std::size_t((h + i->verticalSubsampling - 1)
+                                    / i->verticalSubsampling);
+        const auto y = vpf::defaultStride(i->format, w) * std::size_t(h);
+        std::size_t expect = y;
+        if(i->planeCount == 2)
+          expect += vpf::defaultStride(i->format, cw * 2) * ch;
+        else if(i->planeCount == 3)
+          expect += 2 * (vpf::defaultStride(i->format, cw) * ch);
+        else if(i->planeCount == 4)
+          expect += 2 * (vpf::defaultStride(i->format, cw) * ch) + y;
+        CHECK(vpf::bytesPerFrame(i->format, w, h) == expect);
+      }
+    }
+  }
+  // Going from an odd to the next even row count grows luma by one row and
+  // leaves chroma alone, since the odd count already paid for its chroma row.
+  // Under the old truncating arithmetic the difference was two rows.
+  for(auto f : {V::NV12, V::YUV420P, V::P010})
+  {
+    INFO("format " << vpf::formatName(f));
+    CHECK(vpf::bytesPerFrame(f, 1920, 1082) - vpf::bytesPerFrame(f, 1920, 1081)
+          == vpf::defaultStride(f, 1920));
+  }
+  // and strictly more than the truncating answer did
+  CHECK(vpf::bytesPerFrame(V::NV12, 1920, 1081)
+        > vpf::bytesPerFrame(V::NV12, 1920, 1080));
+}

From 57c373433a86f174fd08dc28b45a64690959fdff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 08:34:22 -0400
Subject: [PATCH 13/20] gfx: correct the r210 and 12-bit RGB row geometry

An adversarial audit of every table row against the vendor specifications found
two rows whose block geometry produced row sizes the hardware does not accept.

r210 pads to a 64-pixel, 256-byte row, and that padding is part of the format
rather than a preference -- DeckLink documents rowBytes as
((width + 63) / 64) * 256. It was described as 1 pixel per 4 bytes with a
preferred 256-byte alignment, so the tight rowBytes() was 7684 at width 1921,
which is not a legal r210 row. Putting the 64/256 group in the block, exactly as
v210 already does with its 48/128 group, makes every row legal by construction
and leaves aligned widths unchanged.

R12B and R12L claimed 8 pixels per 36 bytes. 36 bits per pixel is exactly 2
pixels per 9 bytes, which is both the finer correct granularity and what the
vendor formula (width * 36) / 8 implies; the coarser block over-reported by 27
bytes at width 1922. RGB12P, the same 36-bit packing, was already 2/9 in the
same table -- so one layout had two different geometries in one file. The suite
had frozen both answers, which is why it agreed with each.

RGB12P also declared ByteOrder::NA, in violation of the rule stated a few lines
above it: 12-bit components straddle byte boundaries, and R12B/R12L are
identical rows differing only in that column, so a consumer handed RGB12P could
not tell which packing it held.

Corrected alongside: the header called 10-bit ARGB "A2-ARGB10", which describes
a 4-byte A2R10G10B10 and would have justified "fixing" the correct 5-byte row.
AJA packs it as four 10-bit components including a real 10-bit alpha. The
plane-count and subsampling field comments were stale (a four-plane format and
subsampling of 4 both exist now), and BayerRG8/BayerRG12 are now documented as
the PFNC spellings of the RGGB order, deliberately left unbridged so that no two
enumerators claim one AVPixelFormat.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 .../Gfx/Graph/interop/VideoPixelFormat.hpp    |  31 +++--
 .../Gfx/Graph/interop/VideoPixelFormatAV.cpp  |   6 +-
 tests/unit/VideoPixelFormatTest.cpp           | 121 +++++++++++++++++-
 3 files changed, 138 insertions(+), 20 deletions(-)

diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
index 5447d13624..7068965ad2 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -13,7 +13,7 @@
  *
  * `AVPixelFormat` cannot serve as that vocabulary on its own: FFmpeg models
  * several formats the SDI cards put on the wire as *codecs* rather than pixel
- * formats (v210, v216, r210, DPX 10/12-bit, 12-bit packed RGB, A2-ARGB10), so
+ * formats (v210, v216, r210, DPX 10/12-bit, 12-bit packed RGB, 10-bit ARGB), so
  * they have no `AV_PIX_FMT_*` at all. `VideoPixelFormatAV.hpp` bridges the
  * representable subset in both directions.
  *
@@ -106,16 +106,19 @@ enum class ByteOrder : uint8_t
   X(XRGB8, 9, RGB, 1, 1, 1, 1, 4, false, NA, 256)                              \
   X(XBGR8, 19, RGB, 1, 1, 1, 1, 4, false, NA, 256)                             \
   /* -- Packed 10/12-bit RGB ----------------------------------------------- */ \
-  /* R210 is DeckLink r210 / AV_CODEC_ID_R210: (R<<20)|(G<<10)|B, big-endian. */ \
-  /* RGB10 is AJA NTV2_FBF_10BIT_RGB: (B<<20)|(G<<10)|R, little-endian.       */ \
-  /* R12B/R12L pack 8 pixels into 36 bytes (12 bits per component).           */ \
-  X(R210, 10, RGB, 1, 1, 1, 1, 4, false, Big, 256)                             \
-  X(R12B, 11, RGB, 1, 1, 1, 8, 36, false, Big, 256)                            \
-  X(R12L, 12, RGB, 1, 1, 1, 8, 36, false, Little, 256)                         \
+  /* R210 is DeckLink r210 / AV_CODEC_ID_R210: (R<<20)|(G<<10)|B, big-endian.  */ \
+  /* Its 64-pixel/256-byte row is mandatory, not padding, so it belongs in the  */ \
+  /* block like v210 s: a tight row would not be a legal r210 frame.            */ \
+  /* RGB10 is AJA NTV2_FBF_10BIT_RGB: (B<<20)|(G<<10)|R, little-endian.         */ \
+  /* R12B/R12L/RGB12P all carry 36 bits per pixel, which is exactly 2 pixels    */ \
+  /* per 9 bytes; they differ only in component and byte order.                 */ \
+  X(R210, 10, RGB, 1, 1, 1, 64, 256, false, Big, 256)                          \
+  X(R12B, 11, RGB, 1, 1, 1, 2, 9, false, Big, 256)                             \
+  X(R12L, 12, RGB, 1, 1, 1, 2, 9, false, Little, 256)                          \
   X(ARGB10, 13, RGB, 1, 1, 1, 1, 5, true, Little, 256)                         \
   X(DPX10, 14, RGB, 1, 1, 1, 1, 4, false, Big, 256)                            \
   X(DPX10LE, 15, RGB, 1, 1, 1, 1, 4, false, Little, 256)                       \
-  X(RGB12P, 16, RGB, 1, 1, 1, 2, 9, false, NA, 256)                            \
+  X(RGB12P, 16, RGB, 1, 1, 1, 2, 9, false, Little, 256)                        \
   X(RGB48, 17, RGB, 1, 1, 1, 1, 6, false, Little, 256)                         \
   X(RGB10, 18, RGB, 1, 1, 1, 1, 4, false, Little, 256)                         \
   /* -- Packed sub-byte RGB / YUV (legacy, embedded, V4L2 cameras) --------- */ \
@@ -193,6 +196,11 @@ enum class ByteOrder : uint8_t
   X(Mono10, 81, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
   X(Mono12, 82, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
   X(Mono16, 83, Grey, 1, 1, 1, 1, 2, false, Little, 64)                        \
+  /* BayerRG8/BayerRG12 are the GenICam PFNC spellings of the RGGB order, so   */ \
+  /* they name the same bytes as BayerRGGB8/BayerRGGB16. They are kept because  */ \
+  /* their values are serialized, and deliberately left unbridged: mapping two  */ \
+  /* enumerators onto one AVPixelFormat would make the round-trip ambiguous.    */ \
+  /* Prefer the explicit orders.                                               */ \
   X(BayerRG8, 84, Bayer, 1, 1, 1, 1, 1, false, NA, 64)                         \
   X(BayerRG12, 85, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                    \
   /* The CFA order decides how a demosaic reads the mosaic, so the four 8-bit  */ \
@@ -229,8 +237,7 @@ constexpr std::size_t formatCount() noexcept
  *   - 1: packed (BGRA8, UYVY, v210, R210, Mono*)
  *   - 2: semi-planar, chroma interleaved into one plane (NV12, P010, P210)
  *   - 3: fully planar (YUV420P, YUV422P, ...)
- *   - 4: fully planar plus an alpha plane (none declared yet; sized correctly
- *        by `bytesPerFrame` if one is added)
+ *   - 4: fully planar plus a full-resolution alpha plane (YUVA444P)
  */
 struct VideoPixelFormatInfo
 {
@@ -238,8 +245,8 @@ struct VideoPixelFormatInfo
   VideoPixelFormat format{VideoPixelFormat::Unknown};
   ColorModel colorModel{ColorModel::Unknown};
   uint8_t planeCount{1};
-  uint8_t horizontalSubsampling{1}; /**< 1 for 4:4:4, 2 for 4:2:2 and 4:2:0. */
-  uint8_t verticalSubsampling{1};   /**< 1 for 4:2:2, 2 for 4:2:0. */
+  uint8_t horizontalSubsampling{1}; /**< 1 for 4:4:4, 2 for 4:2:2 and 4:2:0, 4 for 4:1:1 and 4:1:0. */
+  uint8_t verticalSubsampling{1};   /**< 1 for 4:2:2 and 4:1:1, 2 for 4:2:0, 4 for 4:1:0. */
   /** Primary-plane block geometry: `blockPixels` pixels occupy `blockBytes`
    *  bytes. See the table header for why this replaces bits-per-pixel. */
   uint16_t blockPixels{1};
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
index cf093b4d9d..fee4a3afb4 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
@@ -99,7 +99,7 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     case V::RGB10:     // AJA NTV2_FBF_10BIT_RGB (little-endian, B high)
     case V::R12B:      // AV_CODEC_ID_DPX
     case V::R12L:
-    case V::ARGB10:    // A2R10G10B10 packed
+    case V::ARGB10:    // 4x10 bits packed into 5 bytes, alpha included
     case V::DPX10:
     case V::DPX10LE:
     case V::RGB12P:
@@ -107,7 +107,9 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     // -- no clean/unambiguous AVPixelFormat twin --
     case V::RGBA16F:   // no packed half-float RGBA pixfmt
     case V::RGBA32F:   // no packed float RGBA pixfmt (GBRPF32 is planar)
-    case V::BayerRG8:  // Bayer order differs per sensor; keep explicit
+    // PFNC aliases of the RGGB order; see the table. Unbridged so that no two
+    // enumerators claim the same AVPixelFormat.
+    case V::BayerRG8:
     case V::BayerRG12:
     // FFmpeg has no plane-swapped planar twin: YV12 is expressed as yuv420p
     // with the U and V pointers exchanged, so returning yuv420p here would
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index a245a60ceb..0cf0d16d4b 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -254,12 +254,28 @@ TEST_CASE("hand-computed strides: packed formats", "[gfx][pixfmt]")
   CHECK(vpf::rowBytes(V::UYVY422, 2) == 4);
   // An odd width still occupies the whole trailing block.
   CHECK(vpf::rowBytes(V::UYVY422, 3) == 8);
-  // 12-bit RGB: 8 pixels per 36 bytes.
-  CHECK(vpf::rowBytes(V::R12B, 8) == 36);
-  CHECK(vpf::rowBytes(V::R12B, 9) == 72);
-  CHECK(vpf::rowBytes(V::R12B, 1920) == 8640);
-  // 12-bit packed RGB: 2 pixels per 9 bytes.
-  CHECK(vpf::rowBytes(V::RGB12P, 1920) == 8640);
+  // 36 bits per pixel is exactly 2 pixels per 9 bytes, and all three 12-bit
+  // layouts share that granularity. (width * 36) / 8, the vendor row formula,
+  // agrees at every even width.
+  for(auto f : {V::R12B, V::R12L, V::RGB12P})
+  {
+    INFO("format " << vpf::formatName(f));
+    CHECK(vpf::rowBytes(f, 2) == 9);
+    CHECK(vpf::rowBytes(f, 8) == 36);
+    CHECK(vpf::rowBytes(f, 9) == 45);
+    CHECK(vpf::rowBytes(f, 1920) == 8640);
+    CHECK(vpf::rowBytes(f, 1922) == (1922u * 36u) / 8u);
+  }
+  // r210 pads to a 64-pixel/256-byte row, and that is mandatory rather than a
+  // preference: a tight row is not a legal r210 frame.
+  CHECK(vpf::rowBytes(V::R210, 64) == 256);
+  CHECK(vpf::rowBytes(V::R210, 65) == 512);
+  CHECK(vpf::rowBytes(V::R210, 1920) == 7680);
+  CHECK(vpf::rowBytes(V::R210, 1921) == 7936);
+  CHECK(vpf::rowBytes(V::R210, 1921) == ((1921u + 63u) / 64u) * 256u);
+  // so the preferred alignment adds nothing on top
+  for(auto w : {64u, 65u, 1920u, 1921u})
+    CHECK(vpf::defaultStride(V::R210, w) == vpf::rowBytes(V::R210, w));
   // 16-bit and float RGB.
   CHECK(vpf::rowBytes(V::RGB48, 1920) == 11520);
   CHECK(vpf::rowBytes(V::RGBA16, 1920) == 15360);
@@ -553,3 +569,96 @@ TEST_CASE("bytesPerFrame rounds chroma up at odd sizes", "[gfx][pixfmt]")
   CHECK(vpf::bytesPerFrame(V::NV12, 1920, 1081)
         > vpf::bytesPerFrame(V::NV12, 1920, 1080));
 }
+
+// Every AVPixelFormat mapping, pinned to the FFmpeg format NAME rather than to
+// the enumerator. The round-trip tests only compose toAV and fromAV, so any
+// self-consistent permutation between two formats of identical geometry -- BGRA8
+// with RGBA8, NV12 with NV21 -- satisfies them, and satisfies the descriptor
+// cross-check too, since those pairs agree on plane count, subsampling, alpha
+// and endianness. Component-order confusion is the bug class this vocabulary
+// exists to prevent, so it has to be nailed down by name.
+TEST_CASE("every AV mapping is pinned to a named FFmpeg format", "[gfx][pixfmt][av]")
+{
+  struct Pin { V f; const char* av; };
+  static constexpr Pin kPinned[] = {
+    {V::BGRA8, "bgra"},
+    {V::RGBA8, "rgba"},
+    {V::ARGB8, "argb"},
+    {V::ABGR8, "abgr"},
+    {V::RGB24, "rgb24"},
+    {V::BGR24, "bgr24"},
+    {V::BGRX8, "bgr0"},
+    {V::RGBX8, "rgb0"},
+    {V::XRGB8, "0rgb"},
+    {V::XBGR8, "0bgr"},
+    {V::RGB48, "rgb48le"},
+    {V::RGB565, "rgb565le"},
+    {V::RGB565BE, "rgb565be"},
+    {V::RGB555, "rgb555le"},
+    {V::RGB555BE, "rgb555be"},
+    {V::RGB444, "rgb444le"},
+    {V::UYVY422, "uyvy422"},
+    {V::YUYV422, "yuyv422"},
+    {V::YVYU422, "yvyu422"},
+    {V::Y210, "y210le"},
+    {V::NV12, "nv12"},
+    {V::P010, "p010le"},
+    {V::YUV420P, "yuv420p"},
+    {V::YUV420P10, "yuv420p10le"},
+    {V::NV21, "nv21"},
+    {V::P210, "p210le"},
+    {V::YUV422P, "yuv422p"},
+    {V::YUV422P10, "yuv422p10le"},
+    {V::NV16, "nv16"},
+    {V::YUV422P12, "yuv422p12le"},
+    {V::YUV422P16, "yuv422p16le"},
+    {V::P216, "p216le"},
+    {V::YUV411P, "yuv411p"},
+    {V::YUV410P, "yuv410p"},
+    {V::UYYVYY411, "uyyvyy411"},
+    {V::YUV444P, "yuv444p"},
+    {V::YUV444P10, "yuv444p10le"},
+    {V::YUV444P12, "yuv444p12le"},
+    {V::NV24, "nv24"},
+    {V::NV42, "nv42"},
+    {V::VUYA, "vuya"},
+    {V::VUYX, "vuyx"},
+    {V::YUVA444P, "yuva444p"},
+    {V::P416, "p416le"},
+    {V::XV30, "xv30le"},
+    {V::AYUV64, "ayuv64le"},
+    {V::RGBA16, "rgba64le"},
+    {V::Mono8, "gray"},
+    {V::Mono10, "gray10le"},
+    {V::Mono12, "gray12le"},
+    {V::Mono16, "gray16le"},
+    {V::BayerBGGR8, "bayer_bggr8"},
+    {V::BayerGBRG8, "bayer_gbrg8"},
+    {V::BayerGRBG8, "bayer_grbg8"},
+    {V::BayerRGGB8, "bayer_rggb8"},
+    {V::BayerBGGR16, "bayer_bggr16le"},
+    {V::BayerRGGB16, "bayer_rggb16le"},
+    {V::Mono16BE, "gray16be"},
+  };
+  std::set<V> pinned;
+  for(auto [f, name] : kPinned)
+  {
+    INFO(vpf::formatName(f) << " must map to " << name);
+    const auto want = av_get_pix_fmt(name);
+    REQUIRE(want != AV_PIX_FMT_NONE);
+    CHECK(vpf::toAVPixelFormat(f) == want);
+    CHECK(vpf::fromAVPixelFormat(want) == f);
+    pinned.insert(f);
+  }
+  // No mapping may exist that this list does not pin, so adding one without
+  // pinning it fails here rather than going unverified.
+  for(const auto* i : described())
+  {
+    if(vpf::toAVPixelFormat(i->format) != AV_PIX_FMT_NONE)
+    {
+      INFO(i->name << " has an AV mapping but is not pinned");
+      CHECK(pinned.count(i->format) == 1);
+    }
+  }
+  CHECK(pinned.size() == 58);
+}

From 4cd472ffdaf16f110a77fd0cc7c575056ddafbd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 08:37:00 -0400
Subject: [PATCH 14/20] tests: pin the format bridges by name, not just by
 symmetry

Mutation-testing the suite with 33 injected defects caught 12 and missed 21. The
headline miss: both bridges were verified for *symmetry* and never for
*correctness*. Swapping two formats of identical geometry in both directions --
BGRA8 with RGBA8, NV12 with NV21 -- satisfies the round-trip tests, because those
only compose the two functions, and satisfies the FFmpeg descriptor cross-check
too, since such pairs agree on plane count, subsampling, planarity, alpha and
endianness. Component-order confusion is the one bug class this vocabulary exists
to prevent, and it was the class the suite could not see: a mutant that makes
every decoded frame in score red/blue-swapped kept it green.

Pin every mapping instead:
  - all 58 AVPixelFormat mappings to the FFmpeg format NAME, resolved through
    av_get_pix_fmt() so the expectation comes from FFmpeg rather than from a
    retyped enumerator
  - all 54 V4L2 mappings to the kernel constant
  - plus the four one-way aliases a score->fourcc->score sweep can never reach,
    including the deprecated RGB32/BGR32 pair where the two old tables disagreed
Both cases also assert that no mapping exists which the pin list omits, so adding
one without pinning it fails rather than going unverified.

Verified against the two headline mutants: each is now caught.

Also closed:
  - exact counts replace floors (>= 69, >= 40) which let batches of mappings be
    deleted silently -- 15 could go and the suite stayed green
  - positive coverage for chromaSwappedTwin, whose sweep skipped anything
    returning Unknown, so deleting all six cases passed vacuously
  - rowBytes cross-checked against av_image_get_linesize for every mapped format,
    which catches a wrong blockBytes mechanically; the existing rowBytes sweep
    derives its expectation from blockBytes and so agrees with any value there

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 tests/unit/VideoPixelFormatTest.cpp | 169 ++++++++++++++++++++++++++--
 1 file changed, 162 insertions(+), 7 deletions(-)

diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 0cf0d16d4b..55cba5a9f2 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -30,6 +30,8 @@
 #endif
 
 extern "C" {
+#include <libavutil/imgutils.h>
+#include <libavutil/imgutils.h>
 #include <libavutil/pixdesc.h>
 }
 
@@ -37,6 +39,8 @@ extern "C" {
 
 #include <set>
 #include <string>
+#include <string_view>
+#include <string_view>
 #include <vector>
 
 namespace vpf = score::gfx::interop;
@@ -85,7 +89,7 @@ TEST_CASE("the vocabulary is non-trivial and self-consistent", "[gfx][pixfmt]")
   const auto all = described();
   REQUIRE(all.size() == vpf::formatCount());
   // Guards against the table being accidentally emptied or halved.
-  CHECK(all.size() >= 69);
+  CHECK(all.size() == 88);
 
   for(const auto* i : all)
   {
@@ -403,9 +407,8 @@ TEST_CASE("AV bridge: score -> AV -> score round-trip", "[gfx][pixfmt][av]")
     INFO("format " << i->name << " -> " << av_get_pix_fmt_name(av));
     CHECK(vpf::fromAVPixelFormat(av) == i->format);
   }
-  // The bridge is meant to cover most of the vocabulary; a collapse to a
-  // handful would mean the switch lost its cases.
-  CHECK(twins >= 40);
+  // Exact, not a floor: a floor lets a batch of mappings be deleted silently.
+  CHECK(twins == 58);
 }
 
 TEST_CASE("AV bridge: AV -> score -> AV round-trip", "[gfx][pixfmt][av]")
@@ -518,9 +521,8 @@ TEST_CASE("V4L2 fourccs round-trip through the vocabulary", "[gfx][pixfmt][v4l2]
     INFO("format " << i->name);
     CHECK(vpf::fromV4L2PixelFormat(fourcc) == i->format);
   }
-  // The V4L2 camera formats are a large slice of the vocabulary; a collapse
-  // here would mean the table lost its cases.
-  CHECK(mapped >= 40);
+  // Exact, for the same reason as the AV count.
+  CHECK(mapped == 54);
   CHECK(vpf::fromV4L2PixelFormat(0) == V::Unknown);
   CHECK(vpf::fromV4L2PixelFormat(0xDEADBEEF) == V::Unknown);
   // Compressed fourccs are on the codec axis and must not resolve to a layout.
@@ -662,3 +664,156 @@ TEST_CASE("every AV mapping is pinned to a named FFmpeg format", "[gfx][pixfmt][
   }
   CHECK(pinned.size() == 58);
 }
+
+// Every V4L2 fourcc pinned to the kernel constant. The round-trip sweep only
+// composes to/from, so swapping two same-geometry formats in BOTH directions --
+// NV12 with NV21 -- satisfies it while every camera silently delivers exchanged
+// chroma.
+TEST_CASE("every V4L2 mapping is pinned to a kernel constant", "[gfx][pixfmt][v4l2]")
+{
+  struct Pin { V f; uint32_t fourcc; };
+  static const Pin kFourcc[] = {
+      {V::UYVY422, V4L2_PIX_FMT_UYVY},
+      {V::YUYV422, V4L2_PIX_FMT_YUYV},
+      {V::YVYU422, V4L2_PIX_FMT_YVYU},
+      {V::VYUY422, V4L2_PIX_FMT_VYUY},
+      {V::NV12, V4L2_PIX_FMT_NV12},
+      {V::NV21, V4L2_PIX_FMT_NV21},
+      {V::NV16, V4L2_PIX_FMT_NV16},
+      {V::NV61, V4L2_PIX_FMT_NV61},
+      {V::NV24, V4L2_PIX_FMT_NV24},
+      {V::NV42, V4L2_PIX_FMT_NV42},
+      {V::YUV420P, V4L2_PIX_FMT_YUV420},
+      {V::YVU420P, V4L2_PIX_FMT_YVU420},
+      {V::YUV422P, V4L2_PIX_FMT_YUV422P},
+      {V::YUV411P, V4L2_PIX_FMT_YUV411P},
+      {V::YUV410P, V4L2_PIX_FMT_YUV410},
+      {V::YVU410P, V4L2_PIX_FMT_YVU410},
+      {V::VUYA, V4L2_PIX_FMT_VUYA32},
+      {V::VUYX, V4L2_PIX_FMT_VUYX32},
+      {V::AYUV, V4L2_PIX_FMT_AYUV32},
+      {V::XYUV, V4L2_PIX_FMT_XYUV32},
+      {V::YUVA, V4L2_PIX_FMT_YUVA32},
+      {V::YUVX, V4L2_PIX_FMT_YUVX32},
+      {V::AYUV4444, V4L2_PIX_FMT_YUV444},
+      {V::AYUV1555, V4L2_PIX_FMT_YUV555},
+      {V::YUV565, V4L2_PIX_FMT_YUV565},
+      {V::ARGB8, V4L2_PIX_FMT_ARGB32},
+      {V::XRGB8, V4L2_PIX_FMT_XRGB32},
+      {V::BGRA8, V4L2_PIX_FMT_ABGR32},
+      {V::BGRX8, V4L2_PIX_FMT_XBGR32},
+#ifdef V4L2_PIX_FMT_RGBA32
+      {V::RGBA8, V4L2_PIX_FMT_RGBA32},
+#endif
+#ifdef V4L2_PIX_FMT_RGBA32
+      {V::RGBX8, V4L2_PIX_FMT_RGBX32},
+#endif
+#ifdef V4L2_PIX_FMT_RGBA32
+      {V::ABGR8, V4L2_PIX_FMT_BGRA32},
+#endif
+#ifdef V4L2_PIX_FMT_RGBA32
+      {V::XBGR8, V4L2_PIX_FMT_BGRX32},
+#endif
+      {V::RGB24, V4L2_PIX_FMT_RGB24},
+      {V::BGR24, V4L2_PIX_FMT_BGR24},
+      {V::RGB332, V4L2_PIX_FMT_RGB332},
+      {V::RGB565, V4L2_PIX_FMT_RGB565},
+      {V::RGB565BE, V4L2_PIX_FMT_RGB565X},
+      {V::RGB555, V4L2_PIX_FMT_RGB555},
+      {V::RGB555BE, V4L2_PIX_FMT_RGB555X},
+      {V::ARGB1555, V4L2_PIX_FMT_ARGB555},
+      {V::ARGB4444, V4L2_PIX_FMT_ARGB444},
+      {V::RGB444, V4L2_PIX_FMT_RGB444},
+      {V::Mono8, V4L2_PIX_FMT_GREY},
+      {V::Mono10, V4L2_PIX_FMT_Y10},
+      {V::Mono12, V4L2_PIX_FMT_Y12},
+      {V::Mono16, V4L2_PIX_FMT_Y16},
+      {V::Mono16BE, V4L2_PIX_FMT_Y16_BE},
+      {V::BayerBGGR8, V4L2_PIX_FMT_SBGGR8},
+      {V::BayerGBRG8, V4L2_PIX_FMT_SGBRG8},
+      {V::BayerGRBG8, V4L2_PIX_FMT_SGRBG8},
+      {V::BayerRGGB8, V4L2_PIX_FMT_SRGGB8},
+#ifdef V4L2_PIX_FMT_SBGGR16
+      {V::BayerBGGR16, V4L2_PIX_FMT_SBGGR16},
+#endif
+#ifdef V4L2_PIX_FMT_SRGGB16
+      {V::BayerRGGB16, V4L2_PIX_FMT_SRGGB16},
+#endif
+  };
+  std::set<V> pinned;
+  for(auto [f, fourcc] : kFourcc)
+  {
+    INFO(vpf::formatName(f));
+    CHECK(vpf::toV4L2PixelFormat(f) == fourcc);
+    CHECK(vpf::fromV4L2PixelFormat(fourcc) == f);
+    pinned.insert(f);
+  }
+  for(const auto* i : described())
+  {
+    if(vpf::toV4L2PixelFormat(i->format) != 0)
+    {
+      INFO(i->name << " has a fourcc but is not pinned");
+      CHECK(pinned.count(i->format) == 1);
+    }
+  }
+  // The one-way aliases can never be reached by a score->fourcc->score sweep, so
+  // they need naming. The deprecated RGB32/BGR32 pair is where the two old
+  // tables disagreed.
+  CHECK(vpf::fromV4L2PixelFormat(V4L2_PIX_FMT_RGB32) == V::XRGB8);
+  CHECK(vpf::fromV4L2PixelFormat(V4L2_PIX_FMT_BGR32) == V::BGRX8);
+#ifdef V4L2_PIX_FMT_Z16
+  CHECK(vpf::fromV4L2PixelFormat(V4L2_PIX_FMT_Z16) == V::Mono16);
+#endif
+}
+
+// chromaSwappedTwin needs positive coverage: the sweep over described formats
+// skips anything returning Unknown, so deleting every case would pass vacuously.
+TEST_CASE("the chroma-swapped layouts each declare their twin", "[gfx][pixfmt]")
+{
+  struct T { V swapped; V twin; };
+  static constexpr T kTwins[] = {
+      {V::YVU420P, V::YUV420P}, {V::YVU422P, V::YUV422P},
+      {V::YVU410P, V::YUV410P}, {V::NV21, V::NV12},
+      {V::NV61, V::NV16},       {V::NV42, V::NV24}};
+  for(auto [a, b] : kTwins)
+  {
+    INFO(vpf::formatName(a));
+    CHECK(vpf::chromaSwappedTwin(a) == b);
+  }
+  int found = 0;
+  for(const auto* i : described())
+    if(vpf::chromaSwappedTwin(i->format) != V::Unknown)
+      ++found;
+  CHECK(found == int(std::size(kTwins)));
+  // Structural, so a newly added V-first layout fails until it declares a twin.
+  for(const auto* i : described())
+  {
+    const std::string_view n{i->name};
+    if(n.substr(0, 3) == "YVU" || n == "NV21" || n == "NV61" || n == "NV42")
+    {
+      INFO(i->name << " is a V-first layout with no twin declared");
+      CHECK(vpf::chromaSwappedTwin(i->format) != V::Unknown);
+    }
+  }
+}
+
+// Cross-check rowBytes against FFmpeg's own linesize. This catches a wrong
+// blockBytes mechanically and with no second list: the rowBytes sweep derives its
+// expectation from blockBytes, so it agrees with whatever value is put there.
+TEST_CASE("rowBytes agrees with the FFmpeg linesize", "[gfx][pixfmt][av]")
+{
+  for(const auto* i : described())
+  {
+    const auto av = vpf::toAVPixelFormat(i->format);
+    if(av == AV_PIX_FMT_NONE)
+      continue;
+    for(uint32_t w : {16u, 48u, 64u, 720u, 1920u, 3840u})
+    {
+      const int ls = av_image_get_linesize(av, int(w), 0);
+      if(ls <= 0)
+        continue;
+      INFO(i->name << " at width " << w);
+      CHECK(vpf::rowBytes(i->format, w) == std::size_t(ls));
+    }
+  }
+}

From cee3669cc8c1bb394a9d99dba6940bdf329f4838 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 09:06:59 -0400
Subject: [PATCH 15/20] tests: freeze the wire-only descriptors, the byte-order
 rule, and all 88 values

Closes the last three holes the mutation audit found.

The 30 formats with no AVPixelFormat had nothing verifying them. The design goal
of keeping no second list of formats is what makes the other 58 checkable against
FFmpeg for free, and it is also exactly what left these 30 unverifiable: mutating
any field changes the code and every expectation derived from it together. They
now have a golden row each, freezing colour model, plane count, subsampling,
block geometry, alpha, byte order and preferred alignment. The values were
audited against the vendor specifications rather than copied from the table, and
the case asserts that the golden set plus the 58 mapped ones is the whole
vocabulary, so a new wire-only format has to be frozen before it passes.

The byte-order rule was only asserted in one direction, so a multi-byte format
could silently declare NA -- and FFmpeg's descriptor cannot see that, since its
flag only marks big-endian. Two attempts at deriving the rule were wrong and are
worth recording: component depth does not decide it (RGB565 has 5- and 6-bit
components but is packed into a 16-bit word, so order matters) and neither does
bytes-per-pixel (UYVY422 is 4 bytes per 2 pixels with four whole-byte components
and correctly declares NA). FFmpeg's naming convention encodes precisely the
distinction, spelling an le/be pair only where the order is part of the identity,
so it is the authority for the mapped formats.

All 88 serialized values are now frozen as literals, up from 14. The table header
promises that a renumbering breaks the build; it was true for 16% of the
vocabulary. Deliberately written out rather than generated from
SCORE_VIDEO_PIXEL_FORMATS, which would be a tautology. Verified by renumbering
one format and confirming the build fails.

26940 assertions in 26 cases.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 tests/unit/VideoPixelFormatTest.cpp | 198 +++++++++++++++++++++++++++-
 1 file changed, 194 insertions(+), 4 deletions(-)

diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 55cba5a9f2..48d21f65a5 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -37,6 +37,7 @@ extern "C" {
 
 #include <catch2/catch_test_macros.hpp>
 
+#include <algorithm>
 #include <set>
 #include <string>
 #include <string_view>
@@ -66,23 +67,99 @@ std::vector<const vpf::VideoPixelFormatInfo*> described()
 constexpr uint32_t kWidths[] = {1, 2, 6, 63, 64, 65, 720, 1919, 1920, 1921, 3840, 7680, 8192};
 } // namespace
 
-// The values are serialized, so freezing a representative spread here makes an
-// accidental renumbering break the build rather than silently invalidate saved
-// documents.
+// The values are serialized into saved documents, so every one is frozen here as
+// a literal. Generating these from SCORE_VIDEO_PIXEL_FORMATS would be a
+// tautology and catch nothing; written out, a renumbering breaks the build,
+// which is what the table header promises.
 static_assert(uint16_t(V::Unknown) == 0);
 static_assert(uint16_t(V::BGRA8) == 1);
+static_assert(uint16_t(V::RGBA8) == 2);
+static_assert(uint16_t(V::ARGB8) == 3);
+static_assert(uint16_t(V::ABGR8) == 4);
+static_assert(uint16_t(V::RGB24) == 5);
+static_assert(uint16_t(V::BGR24) == 6);
 static_assert(uint16_t(V::BGRX8) == 7);
+static_assert(uint16_t(V::RGBX8) == 8);
+static_assert(uint16_t(V::XRGB8) == 9);
 static_assert(uint16_t(V::XBGR8) == 19);
+static_assert(uint16_t(V::R210) == 10);
+static_assert(uint16_t(V::R12B) == 11);
+static_assert(uint16_t(V::R12L) == 12);
+static_assert(uint16_t(V::ARGB10) == 13);
+static_assert(uint16_t(V::DPX10) == 14);
+static_assert(uint16_t(V::DPX10LE) == 15);
+static_assert(uint16_t(V::RGB12P) == 16);
+static_assert(uint16_t(V::RGB48) == 17);
+static_assert(uint16_t(V::RGB10) == 18);
+static_assert(uint16_t(V::RGB332) == 90);
+static_assert(uint16_t(V::RGB565) == 91);
+static_assert(uint16_t(V::RGB565BE) == 92);
+static_assert(uint16_t(V::RGB555) == 93);
+static_assert(uint16_t(V::RGB555BE) == 94);
+static_assert(uint16_t(V::ARGB1555) == 95);
+static_assert(uint16_t(V::RGB444) == 96);
+static_assert(uint16_t(V::ARGB4444) == 97);
+static_assert(uint16_t(V::AYUV4444) == 98);
+static_assert(uint16_t(V::AYUV1555) == 99);
+static_assert(uint16_t(V::YUV565) == 100);
 static_assert(uint16_t(V::UYVY422) == 20);
+static_assert(uint16_t(V::YUYV422) == 21);
+static_assert(uint16_t(V::YVYU422) == 22);
+static_assert(uint16_t(V::VYUY422) == 23);
 static_assert(uint16_t(V::V210) == 30);
+static_assert(uint16_t(V::V216) == 31);
+static_assert(uint16_t(V::Y210) == 106);
+static_assert(uint16_t(V::Y216) == 107);
 static_assert(uint16_t(V::NV12) == 40);
+static_assert(uint16_t(V::P010) == 41);
+static_assert(uint16_t(V::YUV420P) == 42);
+static_assert(uint16_t(V::YUV420P10) == 43);
+static_assert(uint16_t(V::NV21) == 44);
 static_assert(uint16_t(V::YVU420P) == 45);
+static_assert(uint16_t(V::P210) == 50);
+static_assert(uint16_t(V::YUV422P) == 51);
+static_assert(uint16_t(V::YUV422P10) == 52);
+static_assert(uint16_t(V::NV16) == 53);
+static_assert(uint16_t(V::NV61) == 54);
 static_assert(uint16_t(V::YUV422P12) == 55);
+static_assert(uint16_t(V::YUV422P16) == 110);
+static_assert(uint16_t(V::YVU422P) == 104);
+static_assert(uint16_t(V::P216) == 108);
+static_assert(uint16_t(V::YUV411P) == 101);
+static_assert(uint16_t(V::YUV410P) == 102);
+static_assert(uint16_t(V::YVU410P) == 103);
+static_assert(uint16_t(V::UYYVYY411) == 105);
 static_assert(uint16_t(V::YUV444P) == 60);
+static_assert(uint16_t(V::YUV444P10) == 61);
+static_assert(uint16_t(V::YUV444P12) == 62);
+static_assert(uint16_t(V::NV24) == 63);
+static_assert(uint16_t(V::NV42) == 64);
+static_assert(uint16_t(V::VUYA) == 65);
+static_assert(uint16_t(V::VUYX) == 66);
+static_assert(uint16_t(V::AYUV) == 67);
+static_assert(uint16_t(V::XYUV) == 68);
+static_assert(uint16_t(V::YUVA) == 69);
 static_assert(uint16_t(V::YUVX) == 73);
+static_assert(uint16_t(V::YUVA444P) == 111);
+static_assert(uint16_t(V::P416) == 109);
+static_assert(uint16_t(V::XV30) == 112);
+static_assert(uint16_t(V::AYUV64) == 113);
+static_assert(uint16_t(V::RGBA16) == 70);
+static_assert(uint16_t(V::RGBA16F) == 71);
+static_assert(uint16_t(V::RGBA32F) == 72);
 static_assert(uint16_t(V::Mono8) == 80);
+static_assert(uint16_t(V::Mono10) == 81);
+static_assert(uint16_t(V::Mono12) == 82);
+static_assert(uint16_t(V::Mono16) == 83);
+static_assert(uint16_t(V::BayerRG8) == 84);
+static_assert(uint16_t(V::BayerRG12) == 85);
+static_assert(uint16_t(V::BayerBGGR8) == 114);
+static_assert(uint16_t(V::BayerGBRG8) == 115);
+static_assert(uint16_t(V::BayerGRBG8) == 116);
+static_assert(uint16_t(V::BayerRGGB8) == 117);
+static_assert(uint16_t(V::BayerBGGR16) == 118);
+static_assert(uint16_t(V::BayerRGGB16) == 119);
 static_assert(uint16_t(V::Mono16BE) == 86);
-static_assert(uint16_t(V::YUV565) == 100);
 
 TEST_CASE("the vocabulary is non-trivial and self-consistent", "[gfx][pixfmt]")
 {
@@ -817,3 +894,116 @@ TEST_CASE("rowBytes agrees with the FFmpeg linesize", "[gfx][pixfmt][av]")
     }
   }
 }
+
+// The 30 formats FFmpeg cannot vouch for, frozen field by field.
+//
+// The design goal elsewhere is that no second list of formats exists, which is
+// what makes the AV-mapped 58 verifiable against FFmpeg with no maintenance. It
+// is also exactly what leaves these 30 unverifiable: a mutation to any field of
+// a wire-only format changes both the code and every expectation derived from
+// it. So these get a golden row each. The values below were audited against the
+// vendor specifications -- DeckLink and AJA SDK row-size formulas, Apple TN2162
+// for v210/v216, GenICam PFNC for the Bayer naming -- not merely copied out of
+// the table.
+TEST_CASE("wire-only descriptors are frozen", "[gfx][pixfmt]")
+{
+  struct Golden
+  {
+    V f;
+    ColorModel model;
+    int planes, hsub, vsub, blockPixels, blockBytes;
+    bool alpha;
+    vpf::ByteOrder order;
+    int align;
+  };
+  static constexpr Golden kGolden[] = {
+      {V::R210, ColorModel::RGB, 1, 1, 1, 64, 256, false, vpf::ByteOrder::Big, 256},
+      {V::R12B, ColorModel::RGB, 1, 1, 1, 2, 9, false, vpf::ByteOrder::Big, 256},
+      {V::R12L, ColorModel::RGB, 1, 1, 1, 2, 9, false, vpf::ByteOrder::Little, 256},
+      {V::ARGB10, ColorModel::RGB, 1, 1, 1, 1, 5, true, vpf::ByteOrder::Little, 256},
+      {V::DPX10, ColorModel::RGB, 1, 1, 1, 1, 4, false, vpf::ByteOrder::Big, 256},
+      {V::DPX10LE, ColorModel::RGB, 1, 1, 1, 1, 4, false, vpf::ByteOrder::Little, 256},
+      {V::RGB12P, ColorModel::RGB, 1, 1, 1, 2, 9, false, vpf::ByteOrder::Little, 256},
+      {V::RGB10, ColorModel::RGB, 1, 1, 1, 1, 4, false, vpf::ByteOrder::Little, 256},
+      {V::RGB332, ColorModel::RGB, 1, 1, 1, 1, 1, false, vpf::ByteOrder::NA, 64},
+      {V::ARGB1555, ColorModel::RGB, 1, 1, 1, 1, 2, true, vpf::ByteOrder::Little, 64},
+      {V::ARGB4444, ColorModel::RGB, 1, 1, 1, 1, 2, true, vpf::ByteOrder::Little, 64},
+      {V::AYUV4444, ColorModel::YUV, 1, 1, 1, 1, 2, true, vpf::ByteOrder::Little, 64},
+      {V::AYUV1555, ColorModel::YUV, 1, 1, 1, 1, 2, true, vpf::ByteOrder::Little, 64},
+      {V::YUV565, ColorModel::YUV, 1, 1, 1, 1, 2, false, vpf::ByteOrder::Little, 64},
+      {V::VYUY422, ColorModel::YUV, 1, 2, 1, 2, 4, false, vpf::ByteOrder::NA, 256},
+      {V::V210, ColorModel::YUV, 1, 2, 1, 48, 128, false, vpf::ByteOrder::Little, 128},
+      {V::V216, ColorModel::YUV, 1, 2, 1, 2, 8, false, vpf::ByteOrder::Little, 256},
+      {V::Y216, ColorModel::YUV, 1, 2, 1, 2, 8, false, vpf::ByteOrder::Little, 256},
+      {V::YVU420P, ColorModel::YUV, 3, 2, 2, 1, 1, false, vpf::ByteOrder::NA, 256},
+      {V::NV61, ColorModel::YUV, 2, 2, 1, 1, 1, false, vpf::ByteOrder::NA, 256},
+      {V::YVU422P, ColorModel::YUV, 3, 2, 1, 1, 1, false, vpf::ByteOrder::NA, 256},
+      {V::YVU410P, ColorModel::YUV, 3, 4, 4, 1, 1, false, vpf::ByteOrder::NA, 256},
+      {V::AYUV, ColorModel::YUV, 1, 1, 1, 1, 4, true, vpf::ByteOrder::NA, 256},
+      {V::XYUV, ColorModel::YUV, 1, 1, 1, 1, 4, false, vpf::ByteOrder::NA, 256},
+      {V::YUVA, ColorModel::YUV, 1, 1, 1, 1, 4, true, vpf::ByteOrder::NA, 256},
+      {V::YUVX, ColorModel::YUV, 1, 1, 1, 1, 4, false, vpf::ByteOrder::NA, 256},
+      {V::RGBA16F, ColorModel::RGB, 1, 1, 1, 1, 8, true, vpf::ByteOrder::Little, 256},
+      {V::RGBA32F, ColorModel::RGB, 1, 1, 1, 1, 16, true, vpf::ByteOrder::Little, 256},
+      {V::BayerRG8, ColorModel::Bayer, 1, 1, 1, 1, 1, false, vpf::ByteOrder::NA, 64},
+      {V::BayerRG12, ColorModel::Bayer, 1, 1, 1, 1, 2, false, vpf::ByteOrder::Little, 64},
+  };
+  std::set<V> frozen;
+  for(const auto& g : kGolden)
+  {
+    const auto& i = vpf::formatInfo(g.f);
+    INFO("format " << i.name);
+    CHECK(i.colorModel == g.model);
+    CHECK(i.planeCount == g.planes);
+    CHECK(i.horizontalSubsampling == g.hsub);
+    CHECK(i.verticalSubsampling == g.vsub);
+    CHECK(i.blockPixels == g.blockPixels);
+    CHECK(i.blockBytes == g.blockBytes);
+    CHECK(i.hasAlpha == g.alpha);
+    CHECK(i.byteOrder == g.order);
+    CHECK(i.preferredStrideAlignment == g.align);
+    frozen.insert(g.f);
+  }
+  // Every format without an AV twin must be frozen here, so adding a wire-only
+  // format without a golden row fails rather than going unverified.
+  for(const auto* i : described())
+  {
+    if(vpf::toAVPixelFormat(i->format) == AV_PIX_FMT_NONE)
+    {
+      INFO(i->name << " has no AV twin and no golden row");
+      CHECK(frozen.count(i->format) == 1);
+    }
+  }
+  CHECK(frozen.size() == 30);
+  // and together the two sets are the whole vocabulary
+  CHECK(frozen.size() + 58u == vpf::formatCount());
+}
+
+// The byteOrder rule stated in the header has two halves; only the first was
+// asserted, so a multi-byte format could silently declare NA.
+//
+// Whether an order is required is not derivable from this descriptor, and not
+// from component depth either: RGB565 has 5- and 6-bit components yet is packed
+// into a 16-bit word, so its order matters, while UYVY422 has four whole-byte
+// components and no order to state. FFmpeg's naming convention encodes exactly
+// that distinction -- it spells an le/be pair only for formats where the order
+// is part of the identity -- so take it as the authority for the mapped formats.
+// The wire-only ones have their byteOrder frozen by the golden table above.
+TEST_CASE("byte order is declared exactly when FFmpeg spells one",
+          "[gfx][pixfmt][av]")
+{
+  for(const auto* i : described())
+  {
+    const auto av = vpf::toAVPixelFormat(i->format);
+    if(av == AV_PIX_FMT_NONE)
+      continue;
+    const std::string_view name{av_get_pix_fmt_name(av)};
+    INFO("format " << i->name << " vs " << name);
+    if(name.size() > 2 && name.substr(name.size() - 2) == "le")
+      CHECK(i->byteOrder == vpf::ByteOrder::Little);
+    else if(name.size() > 2 && name.substr(name.size() - 2) == "be")
+      CHECK(i->byteOrder == vpf::ByteOrder::Big);
+    else
+      CHECK(i->byteOrder == vpf::ByteOrder::NA);
+  }
+}

From 9b688179e507e3e8b7e3e13d6743e11833e68d89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 09:11:32 -0400
Subject: [PATCH 16/20] gfx: share the DirectShow fourcc mapping and fix its
 chroma swaps

Every YUV MEDIASUBTYPE is {fourcc, 0x0000, 0x0010, {0x80,0,0,0xaa,0,0x38,0x9b,0x71}},
so the subtype reduces to the fourcc in Data1. Putting the table in those terms
makes it portable and unit-testable on any host, which matters because the
mapping it replaces lived in Windows-only code and had gone unexercised long
enough to accumulate:

  YV12 -> AV_PIX_FMT_YUV420P    V before U, so red and blue were exchanged
  YVU9 -> AV_PIX_FMT_YUV410P    same swap at 4:1:0
  V216 -> AV_PIX_FMT_Y216LE     a different component order, and marked "not sure"

All three now resolve through the shared table to YVU420P, YVU410P and V216, and
the enumeration falls back to chromaSwappedTwin for the V-first layouts so those
cameras stay offered exactly as before while the swap is recorded rather than
lost. The superseded branches are removed rather than left dead and wrong; IF09,
which the shared table does not cover, keeps its own branch.

Compression is now detected from the fourcc instead of from guidToPixelFormat
happening to answer AV_PIX_FMT_YUVJ420P. That sentinel worked, but it meant a
camera genuinely offering YUVJ420P would have been taken for MJPEG, and it put a
codec on the pixel-format axis. H.264 and the three historical Motion-JPEG
spellings are recognised alongside MJPG.

The RGB subtypes are genuine SDK GUIDs rather than fourccs and keep their GUID
comparisons. ARGB1555 still drops its single alpha bit, because FFmpeg has no
5:5:5 format carrying alpha; that is now stated rather than silent.

Testable here despite being Windows data: 30 fourccs pinned by literal
four-character code, and the GUID extraction verified against the real
MEDIASUBTYPE constants for YV12, V216, MJPG and an RGB subtype, confirming the
RGB GUIDs are not mistaken for fourccs. Compiling CameraDevice.win32.cpp itself
still needs the Windows box.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-gfx/CMakeLists.txt   |  2 +
 .../Gfx/CameraDevice.win32.cpp                | 63 ++++++++++--
 .../Graph/interop/DirectShowPixelFormat.cpp   | 98 +++++++++++++++++++
 .../Graph/interop/DirectShowPixelFormat.hpp   | 44 +++++++++
 tests/unit/VideoPixelFormatTest.cpp           | 55 +++++++++++
 5 files changed, 252 insertions(+), 10 deletions(-)
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.cpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.hpp

diff --git a/src/plugins/score-plugin-gfx/CMakeLists.txt b/src/plugins/score-plugin-gfx/CMakeLists.txt
index 0e81b30f43..a961cecdb8 100644
--- a/src/plugins/score-plugin-gfx/CMakeLists.txt
+++ b/src/plugins/score-plugin-gfx/CMakeLists.txt
@@ -243,8 +243,10 @@ set(HDRS
     Gfx/Graph/interop/VideoPixelFormatAV.cpp
     Gfx/Graph/interop/VideoPixelFormat.hpp
     Gfx/Graph/interop/V4L2PixelFormat.hpp
+    Gfx/Graph/interop/DirectShowPixelFormat.hpp
     Gfx/Graph/interop/VideoPixelFormat.cpp
     Gfx/Graph/interop/V4L2PixelFormat.cpp
+    Gfx/Graph/interop/DirectShowPixelFormat.cpp
 
     Gfx/Graph/decoders/GPUVideoDecoder.hpp
     Gfx/Graph/decoders/GPUVideoDecoderFactory.hpp
diff --git a/src/plugins/score-plugin-gfx/Gfx/CameraDevice.win32.cpp b/src/plugins/score-plugin-gfx/Gfx/CameraDevice.win32.cpp
index 725a13bf26..8784c017ef 100644
--- a/src/plugins/score-plugin-gfx/Gfx/CameraDevice.win32.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/CameraDevice.win32.cpp
@@ -17,6 +17,9 @@ extern "C" {
 #include <wmcodecdsp.h>
 #include <oleauto.h>
 
+#include <Gfx/Graph/interop/DirectShowPixelFormat.hpp>
+#include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
+
 namespace Gfx
 {
 static constexpr const GUID MEDIASUBTYPE_Y800             = { 0x30303859, 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}};
@@ -38,8 +41,52 @@ static constexpr const GUID MEDIASUBTYPE_Y210             = { '012Y', 0x0000, 0x
 static constexpr const GUID MEDIASUBTYPE_Y216             = { '612Y', 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 }};
 static constexpr const GUID MEDIASUBTYPE_P408             = { '804P', 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 }};
 
+// Every YUV MEDIASUBTYPE is {fourcc, 0x0000, 0x0010, {0x80,0,0,0xaa,0,0x38,0x9b,0x71}},
+// so the subtype reduces to the fourcc in Data1. Returns 0 for the RGB subtypes,
+// which are genuine SDK GUIDs and are matched below.
+static uint32_t subtypeFourcc(const GUID& subtype) noexcept
+{
+  static const uint8_t suffix[8]
+      = {0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71};
+  if(subtype.Data2 != 0x0000 || subtype.Data3 != 0x0010)
+    return 0;
+  for(int i = 0; i < 8; ++i)
+    if(subtype.Data4[i] != suffix[i])
+      return 0;
+  return uint32_t(subtype.Data1);
+}
+
+// True when the subtype names a compressed stream. Previously this was inferred
+// from guidToPixelFormat happening to answer AV_PIX_FMT_YUVJ420P, which meant a
+// camera genuinely offering that layout would have been taken for MJPEG.
+static bool isCompressedSubtype(const GUID& subtype) noexcept
+{
+  const auto fourcc = subtypeFourcc(subtype);
+  return fourcc != 0
+         && score::gfx::interop::isDirectShowCompressedFourcc(fourcc);
+}
+
 static int guidToPixelFormat(const GUID& subtype)
 {
+  // The YUV layouts come from the shared, host-testable fourcc table, so they
+  // cannot drift and are not carrying the chroma swaps this function used to.
+  if(const auto fourcc = subtypeFourcc(subtype))
+  {
+    using namespace score::gfx::interop;
+    const auto layout = fromDirectShowFourcc(fourcc);
+    if(layout != VideoPixelFormat::Unknown)
+    {
+      if(const auto av = toAVPixelFormat(layout); av != AV_PIX_FMT_NONE)
+        return av;
+      // The V-before-U layouts have no AVPixelFormat of their own; name the twin
+      // so the format stays offered, and chromaSwappedTwin records that a
+      // consumer wanting correct chroma must exchange the U and V planes.
+      if(const auto twin = toAVPixelFormat(chromaSwappedTwin(layout));
+         twin != AV_PIX_FMT_NONE)
+        return twin;
+    }
+  }
+
   if(subtype == MEDIASUBTYPE_RGB24)
     return AV_PIX_FMT_BGR24;
   else if(subtype == MEDIASUBTYPE_RGB32)
@@ -51,6 +98,8 @@ static int guidToPixelFormat(const GUID& subtype)
   else if(subtype == MEDIASUBTYPE_RGB555)
     return AV_PIX_FMT_BGR555LE;
   else if(subtype == MEDIASUBTYPE_ARGB1555)
+    // FFmpeg has no 5:5:5 format carrying alpha, so the single alpha bit is
+    // dropped. The layout is otherwise identical to RGB555.
     return AV_PIX_FMT_BGR555LE;
   else if(subtype == MEDIASUBTYPE_RGB8)
     return AV_PIX_FMT_PAL8;
@@ -86,8 +135,6 @@ static int guidToPixelFormat(const GUID& subtype)
     return AV_PIX_FMT_YUV420P;
   else if(subtype == MEDIASUBTYPE_I420)
     return AV_PIX_FMT_YUV420P;
-  else if(subtype == MEDIASUBTYPE_YV12)
-    return AV_PIX_FMT_YUV420P;
   else if(subtype == MEDIASUBTYPE_NV12)
     return AV_PIX_FMT_NV12;
 //  else if(subtype == MEDIASUBTYPE_NV21)
@@ -114,8 +161,6 @@ static int guidToPixelFormat(const GUID& subtype)
     return AV_PIX_FMT_Y210LE;
   else if(subtype == MEDIASUBTYPE_Y216)
     return AV_PIX_FMT_Y216LE;
-  else if(subtype == MEDIASUBTYPE_V216) // not sure
-    return AV_PIX_FMT_Y216LE;
 
 /////   Not supported in dshow as of ffmpeg 8, causes hangs in avformat_find_stream_info
   else if(subtype == MEDIASUBTYPE_Y8) {
@@ -130,7 +175,7 @@ static int guidToPixelFormat(const GUID& subtype)
   else if(subtype == MEDIASUBTYPE_MICROSOFT_IR8) {
     return AV_PIX_FMT_GRAY8;
   }
-  else if (subtype == MEDIASUBTYPE_YVU9 || subtype == MEDIASUBTYPE_IF09)
+  else if(subtype == MEDIASUBTYPE_IF09)
     return AV_PIX_FMT_YUV410P;
 
   else if (subtype == MEDIASUBTYPE_Y411 || subtype == MEDIASUBTYPE_Y41P)
@@ -144,8 +189,6 @@ static int guidToPixelFormat(const GUID& subtype)
     return AV_PIX_FMT_YUVJ420P;
   else if(subtype == MEDIASUBTYPE_Plum)
     return AV_PIX_FMT_YUVJ420P;
-  else if(subtype == MEDIASUBTYPE_YVU9)
-    return AV_PIX_FMT_YUV410P;
   else
     return AV_PIX_FMT_NONE;
 }
@@ -163,7 +206,8 @@ static void enumerateCameraFormat(
   source.pixelformat = guidToPixelFormat(subtype);
 
   // Basic validation
-  if(width <= 0 || height <= 0 || source.pixelformat == AV_PIX_FMT_NONE)
+  if(width <= 0 || height <= 0
+     || (source.pixelformat == AV_PIX_FMT_NONE && !isCompressedSubtype(subtype)))
   {
     // OLECHAR* guidString;
     // StringFromCLSID(subtype, &guidString);
@@ -172,8 +216,7 @@ static void enumerateCameraFormat(
     return;
   }
 
-  // MJPEG special case
-  if(source.pixelformat == AV_PIX_FMT_YUVJ420P)
+  if(isCompressedSubtype(subtype))
   {
     source.codec = AV_CODEC_ID_MJPEG;
     source.pixelformat = AV_PIX_FMT_NONE;
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.cpp
new file mode 100644
index 0000000000..38fd824ab7
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.cpp
@@ -0,0 +1,98 @@
+#include <Gfx/Graph/interop/DirectShowPixelFormat.hpp>
+
+namespace score::gfx::interop
+{
+namespace
+{
+constexpr auto fcc = directShowFourcc;
+}
+
+VideoPixelFormat fromDirectShowFourcc(uint32_t fourcc) noexcept
+{
+  using V = VideoPixelFormat;
+
+  // -- packed 4:2:2, 8-bit --
+  if(fourcc == fcc('Y', 'U', 'Y', '2') || fourcc == fcc('Y', 'U', 'Y', 'V'))
+    return V::YUYV422;
+  if(fourcc == fcc('U', 'Y', 'V', 'Y') || fourcc == fcc('Y', '4', '2', '2'))
+    return V::UYVY422;
+  if(fourcc == fcc('Y', 'V', 'Y', 'U'))
+    return V::YVYU422;
+
+  // -- packed 4:2:2, 10 and 16-bit. Y210/Y216 carry YUYV component order;
+  //    V216 differs from Y216 only in that order, and conflating the two was
+  //    the reason the old mapping carried a "not sure" note.
+  if(fourcc == fcc('Y', '2', '1', '0'))
+    return V::Y210;
+  if(fourcc == fcc('Y', '2', '1', '6'))
+    return V::Y216;
+  if(fourcc == fcc('V', '2', '1', '6'))
+    return V::V216;
+
+  // -- planar 4:2:0. YV12 stores V before U, so it is YVU420P: naming it
+  //    YUV420P exchanges red and blue.
+  if(fourcc == fcc('I', '4', '2', '0') || fourcc == fcc('I', 'Y', 'U', 'V'))
+    return V::YUV420P;
+  if(fourcc == fcc('Y', 'V', '1', '2'))
+    return V::YVU420P;
+
+  // -- planar 4:2:2 and 4:1:0, likewise V-before-U --
+  if(fourcc == fcc('Y', 'V', '1', '6'))
+    return V::YVU422P;
+  if(fourcc == fcc('Y', 'V', 'U', '9'))
+    return V::YVU410P;
+
+  // -- semi-planar. P208/P408 are the 8-bit 4:2:2 and 4:4:4 spellings.
+  if(fourcc == fcc('N', 'V', '1', '2'))
+    return V::NV12;
+  if(fourcc == fcc('N', 'V', '2', '1'))
+    return V::NV21;
+  if(fourcc == fcc('N', 'V', '1', '6') || fourcc == fcc('P', '2', '0', '8'))
+    return V::NV16;
+  if(fourcc == fcc('N', 'V', '2', '4') || fourcc == fcc('P', '4', '0', '8'))
+    return V::NV24;
+  if(fourcc == fcc('N', 'V', '4', '2'))
+    return V::NV42;
+  if(fourcc == fcc('P', '0', '1', '0'))
+    return V::P010;
+  if(fourcc == fcc('P', '2', '1', '0'))
+    return V::P210;
+  if(fourcc == fcc('P', '2', '1', '6'))
+    return V::P216;
+
+  // -- packed 4:4:4. DirectShow AYUV puts V,U,Y,A in memory, which is what
+  //    FFmpeg calls VUYA; Y410 is 2 padding bits plus three 10-bit components,
+  //    Y416 the same geometry at 16 bits with real alpha.
+  if(fourcc == fcc('A', 'Y', 'U', 'V'))
+    return V::VUYA;
+  if(fourcc == fcc('Y', '4', '1', '0'))
+    return V::XV30;
+  if(fourcc == fcc('Y', '4', '1', '6'))
+    return V::AYUV64;
+
+  // -- packed 4:1:1 --
+  if(fourcc == fcc('Y', '4', '1', 'P'))
+    return V::UYYVYY411;
+
+  // -- single channel. Z16 and Y16 are depth and luminance respectively, but
+  //    both are a 16-bit single channel as far as the layout goes.
+  if(fourcc == fcc('G', 'R', 'E', 'Y') || fourcc == fcc('Y', '8', ' ', ' ')
+     || fourcc == fcc('Y', '8', '0', '0'))
+    return V::Mono8;
+  if(fourcc == fcc('Y', '1', '6', '0') || fourcc == fcc('Z', '1', '6', ' '))
+    return V::Mono16;
+
+  return V::Unknown;
+}
+
+bool isDirectShowCompressedFourcc(uint32_t fourcc) noexcept
+{
+  // MJPG and the three historical Motion-JPEG spellings DirectShow still
+  // reports. These are codecs, so they must not resolve to a pixel format:
+  // handing raw JPEG bytes to a planar-YUV path renders noise.
+  return fourcc == fcc('M', 'J', 'P', 'G') || fourcc == fcc('T', 'V', 'M', 'J')
+         || fourcc == fcc('W', 'A', 'K', 'E') || fourcc == fcc('P', 'l', 'u', 'm')
+         || fourcc == fcc('d', 'v', 's', 'd') || fourcc == fcc('H', '2', '6', '4');
+}
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.hpp
new file mode 100644
index 0000000000..c51d4bf644
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DirectShowPixelFormat.hpp
@@ -0,0 +1,44 @@
+#pragma once
+
+/**
+ * @file DirectShowPixelFormat.hpp
+ * @brief DirectShow / Video-for-Windows fourcc <-> VideoPixelFormat.
+ *
+ * The YUV `MEDIASUBTYPE_*` GUIDs are all of the form
+ * `{fourcc, 0x0000, 0x0010, {0x80,0x00,0x00,0xaa,0x00,0x38,0x9b,0x71}}`, so the
+ * subtype reduces to the fourcc in `Data1`. Keeping the table in those terms
+ * makes it portable and unit-testable on any host, instead of hiding a mapping
+ * nobody can exercise inside Windows-only code. The RGB subtypes are genuine
+ * SDK GUIDs rather than fourccs and stay with the DirectShow enumeration.
+ *
+ * Deliberately not platform-guarded: the point is that it builds and is tested
+ * everywhere.
+ */
+
+#include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+
+#include <score_plugin_gfx_export.h>
+
+#include <cstdint>
+
+namespace score::gfx::interop
+{
+
+/// Build a fourcc the way DirectShow spells it, least-significant byte first.
+constexpr uint32_t directShowFourcc(char a, char b, char c, char d) noexcept
+{
+  return uint32_t(uint8_t(a)) | (uint32_t(uint8_t(b)) << 8)
+         | (uint32_t(uint8_t(c)) << 16) | (uint32_t(uint8_t(d)) << 24);
+}
+
+/// The layout behind a DirectShow YUV fourcc, or Unknown for compressed,
+/// RGB-GUID and unhandled subtypes.
+SCORE_PLUGIN_GFX_EXPORT
+VideoPixelFormat fromDirectShowFourcc(uint32_t fourcc) noexcept;
+
+/// True when the fourcc names a compressed stream rather than a raw layout, so
+/// the caller reaches for a decoder instead of a pixel format.
+SCORE_PLUGIN_GFX_EXPORT
+bool isDirectShowCompressedFourcc(uint32_t fourcc) noexcept;
+
+} // namespace score::gfx::interop
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 48d21f65a5..b976558c83 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -23,6 +23,7 @@
 //     alpha and RGB-ness. A mismatch there is a real bug, not a test artifact.
 
 #include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+#include <Gfx/Graph/interop/DirectShowPixelFormat.hpp>
 #include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
 #if defined(__linux__)
 #include <Gfx/Graph/interop/V4L2PixelFormat.hpp>
@@ -1007,3 +1008,57 @@ TEST_CASE("byte order is declared exactly when FFmpeg spells one",
       CHECK(i->byteOrder == vpf::ByteOrder::NA);
   }
 }
+
+// The DirectShow fourcc table, pinned by literal fourcc. This is Windows-only
+// data, but keeping it in fourcc terms makes it testable on any host, which is
+// the point: the mapping it replaces lived in Windows-only code and had gone
+// unexercised long enough to accumulate a chroma swap and a "not sure".
+TEST_CASE("DirectShow fourccs resolve to the right layout", "[gfx][pixfmt][dshow]")
+{
+  using vpf::directShowFourcc;
+  const auto f = [](const char* s) {
+    return directShowFourcc(s[0], s[1], s[2], s[3]);
+  };
+  struct Pin { const char* fourcc; V expect; };
+  static const Pin kPins[] = {
+      // packed 4:2:2
+      {"YUY2", V::YUYV422}, {"YUYV", V::YUYV422}, {"UYVY", V::UYVY422},
+      {"Y422", V::UYVY422}, {"YVYU", V::YVYU422},
+      {"Y210", V::Y210},    {"Y216", V::Y216},    {"V216", V::V216},
+      // planar; the V-before-U spellings must not collapse onto the U-first ones
+      {"I420", V::YUV420P}, {"IYUV", V::YUV420P}, {"YV12", V::YVU420P},
+      {"YV16", V::YVU422P}, {"YVU9", V::YVU410P},
+      // semi-planar
+      {"NV12", V::NV12}, {"NV21", V::NV21}, {"NV16", V::NV16},
+      {"P208", V::NV16}, {"NV24", V::NV24}, {"P408", V::NV24},
+      {"NV42", V::NV42}, {"P010", V::P010}, {"P210", V::P210},
+      {"P216", V::P216},
+      // packed 4:4:4 and 4:1:1
+      {"AYUV", V::VUYA}, {"Y410", V::XV30}, {"Y416", V::AYUV64},
+      {"Y41P", V::UYYVYY411},
+      // single channel
+      {"GREY", V::Mono8}, {"Y800", V::Mono8}, {"Y160", V::Mono16},
+  };
+  for(const auto& p : kPins)
+  {
+    INFO("fourcc " << p.fourcc);
+    CHECK(vpf::fromDirectShowFourcc(f(p.fourcc)) == p.expect);
+  }
+  // YV12 and I420 are the same geometry and differ only in plane order, so the
+  // swap must be visible in the vocabulary rather than lost.
+  CHECK(vpf::chromaSwappedTwin(vpf::fromDirectShowFourcc(f("YV12")))
+        == vpf::fromDirectShowFourcc(f("I420")));
+  CHECK(vpf::chromaSwappedTwin(vpf::fromDirectShowFourcc(f("YV16")))
+        == V::YUV422P);
+  CHECK(vpf::chromaSwappedTwin(vpf::fromDirectShowFourcc(f("YVU9")))
+        == V::YUV410P);
+  // Compressed subtypes are on the codec axis.
+  for(const char* c : {"MJPG", "TVMJ", "WAKE", "Plum", "H264"})
+  {
+    INFO("compressed " << c);
+    CHECK(vpf::isDirectShowCompressedFourcc(f(c)));
+    CHECK(vpf::fromDirectShowFourcc(f(c)) == V::Unknown);
+  }
+  CHECK_FALSE(vpf::isDirectShowCompressedFourcc(f("NV12")));
+  CHECK(vpf::fromDirectShowFourcc(0) == V::Unknown);
+}

From a9cdd59e682f0ba654b5212eb147cff4e53ecff1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 09:14:38 -0400
Subject: [PATCH 17/20] gfx: route DRM fourccs through the vocabulary

DRM was the second format hub: dma-buf and PipeWire reached AVPixelFormat through
their own table, and PipeWire got there in two hops via DRM, so nothing connected
either to the layout vocabulary the capture cards use.

Add the DRM fourcc mapping next to the V4L2 and DirectShow ones, computing the
fourccs from their characters so it needs neither libdrm nor libspa and is
testable on any host.

The mapping states memory order in every comment, because a DRM fourcc reads in
machine-word order and the memory bytes are its reverse: DRM_ARGB8888 is B,G,R,A
in memory, so it is BGRA8, not ARGB8. That inversion is the most common source of
red/blue swaps on the dma-buf path, and the suite asserts the direction
explicitly rather than relying on a round-trip, which would accept either
reading.

Format modifiers are deliberately absent. Tiling and compression are not part of
a pixel format -- the same fourcc arrives linear or tiled -- and folding one in
would repeat the mistake of baking stride alignment into a descriptor. Callers
pass modifiers alongside.

Two rows were needed to make the DRM path lossless rather than dropping to
Unknown: X2RGB10 and X2BGR10, the ARGB2101010/ABGR2101010 layouts, whose top two
bits are padding rather than alpha.

Adding those two immediately failed the exact-count and pin-completeness
guardrails added earlier, which is what they are for: the new formats could not
pass until they were pinned and frozen.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-gfx/CMakeLists.txt   |   2 +
 .../Gfx/Graph/interop/DrmPixelFormat.cpp      | 128 ++++++++++++++++++
 .../Gfx/Graph/interop/DrmPixelFormat.hpp      |  50 +++++++
 .../Gfx/Graph/interop/VideoPixelFormat.hpp    |   5 +
 .../Gfx/Graph/interop/VideoPixelFormatAV.cpp  |   5 +
 tests/unit/VideoPixelFormatTest.cpp           |  68 +++++++++-
 6 files changed, 254 insertions(+), 4 deletions(-)
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.cpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.hpp

diff --git a/src/plugins/score-plugin-gfx/CMakeLists.txt b/src/plugins/score-plugin-gfx/CMakeLists.txt
index a961cecdb8..df9944431e 100644
--- a/src/plugins/score-plugin-gfx/CMakeLists.txt
+++ b/src/plugins/score-plugin-gfx/CMakeLists.txt
@@ -244,9 +244,11 @@ set(HDRS
     Gfx/Graph/interop/VideoPixelFormat.hpp
     Gfx/Graph/interop/V4L2PixelFormat.hpp
     Gfx/Graph/interop/DirectShowPixelFormat.hpp
+    Gfx/Graph/interop/DrmPixelFormat.hpp
     Gfx/Graph/interop/VideoPixelFormat.cpp
     Gfx/Graph/interop/V4L2PixelFormat.cpp
     Gfx/Graph/interop/DirectShowPixelFormat.cpp
+    Gfx/Graph/interop/DrmPixelFormat.cpp
 
     Gfx/Graph/decoders/GPUVideoDecoder.hpp
     Gfx/Graph/decoders/GPUVideoDecoderFactory.hpp
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.cpp
new file mode 100644
index 0000000000..0a467e1622
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.cpp
@@ -0,0 +1,128 @@
+#include <Gfx/Graph/interop/DrmPixelFormat.hpp>
+
+namespace score::gfx::interop
+{
+namespace
+{
+constexpr auto drmFcc = drmPixelFourcc;
+
+// A DRM fourcc reads in machine-word order, so the memory byte order is the
+// reverse of the name. The comments give the memory order, which is what a
+// VideoPixelFormat names.
+constexpr uint32_t kArgb8888 = drmFcc('A', 'R', '2', '4');     // B,G,R,A
+constexpr uint32_t kAbgr8888 = drmFcc('A', 'B', '2', '4');     // R,G,B,A
+constexpr uint32_t kXrgb8888 = drmFcc('X', 'R', '2', '4');     // B,G,R,X
+constexpr uint32_t kXbgr8888 = drmFcc('X', 'B', '2', '4');     // R,G,B,X
+constexpr uint32_t kRgba8888 = drmFcc('R', 'A', '2', '4');     // A,B,G,R
+constexpr uint32_t kBgra8888 = drmFcc('B', 'A', '2', '4');     // A,R,G,B
+constexpr uint32_t kRgb888 = drmFcc('R', 'G', '2', '4');       // B,G,R
+constexpr uint32_t kBgr888 = drmFcc('B', 'G', '2', '4');       // R,G,B
+constexpr uint32_t kRgb565 = drmFcc('R', 'G', '1', '6');
+constexpr uint32_t kArgb2101010 = drmFcc('A', 'R', '3', '0');  // 2R10G10B10, LE word
+constexpr uint32_t kAbgr2101010 = drmFcc('A', 'B', '3', '0');  // 2B10G10R10, LE word
+constexpr uint32_t kAbgr16161616f = drmFcc('A', 'B', '4', 'H');
+constexpr uint32_t kNv12 = drmFcc('N', 'V', '1', '2');
+constexpr uint32_t kNv21 = drmFcc('N', 'V', '2', '1');
+constexpr uint32_t kNv16 = drmFcc('N', 'V', '1', '6');
+constexpr uint32_t kNv61 = drmFcc('N', 'V', '6', '1');
+constexpr uint32_t kNv24 = drmFcc('N', 'V', '2', '4');
+constexpr uint32_t kNv42 = drmFcc('N', 'V', '4', '2');
+constexpr uint32_t kP010 = drmFcc('P', '0', '1', '0');
+constexpr uint32_t kP210 = drmFcc('P', '2', '1', '0');
+constexpr uint32_t kP410 = drmFcc('P', '4', '1', '0');
+constexpr uint32_t kYuv420 = drmFcc('Y', 'U', '1', '2');
+constexpr uint32_t kYvu420 = drmFcc('Y', 'V', '1', '2');
+constexpr uint32_t kYuv422 = drmFcc('Y', 'U', '1', '6');
+constexpr uint32_t kYvu422 = drmFcc('Y', 'V', '1', '6');
+constexpr uint32_t kYuv444 = drmFcc('Y', 'U', '2', '4');
+constexpr uint32_t kYuyv = drmFcc('Y', 'U', 'Y', 'V');
+constexpr uint32_t kYvyu = drmFcc('Y', 'V', 'Y', 'U');
+constexpr uint32_t kUyvy = drmFcc('U', 'Y', 'V', 'Y');
+constexpr uint32_t kVyuy = drmFcc('V', 'Y', 'U', 'Y');
+constexpr uint32_t kR8 = drmFcc('R', '8', ' ', ' ');
+constexpr uint32_t kR16 = drmFcc('R', '1', '6', ' ');
+} // namespace
+
+VideoPixelFormat fromDrmFourcc(uint32_t fourcc) noexcept
+{
+  using V = VideoPixelFormat;
+  switch(fourcc)
+  {
+    case kArgb8888:      return V::BGRA8;
+    case kAbgr8888:      return V::RGBA8;
+    case kXrgb8888:      return V::BGRX8;
+    case kXbgr8888:      return V::RGBX8;
+    case kRgba8888:      return V::ABGR8;
+    case kBgra8888:      return V::ARGB8;
+    case kRgb888:        return V::BGR24;
+    case kBgr888:        return V::RGB24;
+    case kRgb565:        return V::RGB565;
+    case kArgb2101010:   return V::X2RGB10;
+    case kAbgr2101010:   return V::X2BGR10;
+    case kAbgr16161616f: return V::RGBA16F;
+    case kNv12:          return V::NV12;
+    case kNv21:          return V::NV21;
+    case kNv16:          return V::NV16;
+    case kNv61:          return V::NV61;
+    case kNv24:          return V::NV24;
+    case kNv42:          return V::NV42;
+    case kP010:          return V::P010;
+    case kP210:          return V::P210;
+    case kP410:          return V::P416;
+    case kYuv420:        return V::YUV420P;
+    case kYvu420:        return V::YVU420P;
+    case kYuv422:        return V::YUV422P;
+    case kYvu422:        return V::YVU422P;
+    case kYuv444:        return V::YUV444P;
+    case kYuyv:          return V::YUYV422;
+    case kYvyu:          return V::YVYU422;
+    case kUyvy:          return V::UYVY422;
+    case kVyuy:          return V::VYUY422;
+    case kR8:            return V::Mono8;
+    case kR16:           return V::Mono16;
+    default:             return V::Unknown;
+  }
+}
+
+uint32_t toDrmFourcc(VideoPixelFormat f) noexcept
+{
+  using V = VideoPixelFormat;
+  switch(f)
+  {
+    case V::BGRA8:   return kArgb8888;
+    case V::RGBA8:   return kAbgr8888;
+    case V::BGRX8:   return kXrgb8888;
+    case V::RGBX8:   return kXbgr8888;
+    case V::ABGR8:   return kRgba8888;
+    case V::ARGB8:   return kBgra8888;
+    case V::BGR24:   return kRgb888;
+    case V::RGB24:   return kBgr888;
+    case V::RGB565:  return kRgb565;
+    case V::X2RGB10: return kArgb2101010;
+    case V::X2BGR10: return kAbgr2101010;
+    case V::RGBA16F: return kAbgr16161616f;
+    case V::NV12:    return kNv12;
+    case V::NV21:    return kNv21;
+    case V::NV16:    return kNv16;
+    case V::NV61:    return kNv61;
+    case V::NV24:    return kNv24;
+    case V::NV42:    return kNv42;
+    case V::P010:    return kP010;
+    case V::P210:    return kP210;
+    case V::P416:    return kP410;
+    case V::YUV420P: return kYuv420;
+    case V::YVU420P: return kYvu420;
+    case V::YUV422P: return kYuv422;
+    case V::YVU422P: return kYvu422;
+    case V::YUV444P: return kYuv444;
+    case V::YUYV422: return kYuyv;
+    case V::YVYU422: return kYvyu;
+    case V::UYVY422: return kUyvy;
+    case V::VYUY422: return kVyuy;
+    case V::Mono8:   return kR8;
+    case V::Mono16:  return kR16;
+    default:         return 0;
+  }
+}
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.hpp
new file mode 100644
index 0000000000..6b3688c721
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/DrmPixelFormat.hpp
@@ -0,0 +1,50 @@
+#pragma once
+
+/**
+ * @file DrmPixelFormat.hpp
+ * @brief DRM fourcc <-> VideoPixelFormat, and the PipeWire SPA formats.
+ *
+ * A DRM fourcc names the component order of a little-endian machine word, so
+ * DRM_ARGB8888 is B,G,R,A in memory -- the reverse of how the name reads. That
+ * inversion is the single most common source of red/blue swaps on the dma-buf
+ * path, so the mapping states the memory order in each comment.
+ *
+ * A DRM *format modifier* (tiling, compression) is deliberately absent. It is
+ * not part of a pixel format: the same fourcc can arrive linear or tiled, and
+ * folding one into the other would be the same category error as baking a stride
+ * alignment into a format descriptor. Callers pass modifiers alongside.
+ *
+ * PipeWire's SPA video formats live here too, since they are defined in DRM
+ * terms and reached the rest of score through DRM already.
+ *
+ * Deliberately header-free of libdrm and libspa: the fourccs are computed from
+ * their characters, so this builds and is tested everywhere.
+ */
+
+#include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+
+#include <score_plugin_gfx_export.h>
+
+#include <cstdint>
+
+namespace score::gfx::interop
+{
+
+/// Build a DRM fourcc from its characters, least-significant byte first.
+constexpr uint32_t drmPixelFourcc(char a, char b, char c, char d) noexcept
+{
+  return uint32_t(uint8_t(a)) | (uint32_t(uint8_t(b)) << 8)
+         | (uint32_t(uint8_t(c)) << 16) | (uint32_t(uint8_t(d)) << 24);
+}
+
+/// The layout behind a DRM fourcc, or Unknown when score has no row for it.
+SCORE_PLUGIN_GFX_EXPORT
+VideoPixelFormat fromDrmFourcc(uint32_t fourcc) noexcept;
+
+/// The DRM fourcc a layout should be exported as, or 0 when DRM has none.
+/// Not a strict inverse: several fourccs can share a layout, and this returns
+/// the canonical one.
+SCORE_PLUGIN_GFX_EXPORT
+uint32_t toDrmFourcc(VideoPixelFormat f) noexcept;
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
index 7068965ad2..0e1d60e481 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormat.hpp
@@ -121,6 +121,11 @@ enum class ByteOrder : uint8_t
   X(RGB12P, 16, RGB, 1, 1, 1, 2, 9, false, Little, 256)                        \
   X(RGB48, 17, RGB, 1, 1, 1, 1, 6, false, Little, 256)                         \
   X(RGB10, 18, RGB, 1, 1, 1, 1, 4, false, Little, 256)                         \
+  /* X2RGB10/X2BGR10 hold two padding bits plus three 10-bit components in a    */ \
+  /* 32-bit little-endian word; the pad is not alpha. These are the DRM         */ \
+  /* ARGB2101010/ABGR2101010 layouts.                                          */ \
+  X(X2RGB10, 120, RGB, 1, 1, 1, 1, 4, false, Little, 256)                      \
+  X(X2BGR10, 121, RGB, 1, 1, 1, 1, 4, false, Little, 256)                      \
   /* -- Packed sub-byte RGB / YUV (legacy, embedded, V4L2 cameras) --------- */ \
   X(RGB332, 90, RGB, 1, 1, 1, 1, 1, false, NA, 64)                             \
   X(RGB565, 91, RGB, 1, 1, 1, 1, 2, false, Little, 64)                         \
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
index fee4a3afb4..a4980de9ac 100644
--- a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatAV.cpp
@@ -23,6 +23,9 @@ AVPixelFormat toAVPixelFormat(VideoPixelFormat f) noexcept
     case V::XRGB8:     return AV_PIX_FMT_0RGB;
     case V::XBGR8:     return AV_PIX_FMT_0BGR;
 
+    case V::X2RGB10:   return AV_PIX_FMT_X2RGB10LE;
+    case V::X2BGR10:   return AV_PIX_FMT_X2BGR10LE;
+
     // -- packed sub-byte RGB --
     case V::RGB565:    return AV_PIX_FMT_RGB565LE;
     case V::RGB565BE:  return AV_PIX_FMT_RGB565BE;
@@ -154,6 +157,8 @@ VideoPixelFormat fromAVPixelFormat(AVPixelFormat f) noexcept
     case AV_PIX_FMT_RGB0:        return V::RGBX8;
     case AV_PIX_FMT_0RGB:        return V::XRGB8;
     case AV_PIX_FMT_0BGR:        return V::XBGR8;
+    case AV_PIX_FMT_X2RGB10LE:   return V::X2RGB10;
+    case AV_PIX_FMT_X2BGR10LE:   return V::X2BGR10;
     case AV_PIX_FMT_RGB565LE:    return V::RGB565;
     case AV_PIX_FMT_RGB565BE:    return V::RGB565BE;
     case AV_PIX_FMT_RGB555LE:    return V::RGB555;
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index b976558c83..ddc58bcdf0 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -24,6 +24,7 @@
 
 #include <Gfx/Graph/interop/VideoPixelFormat.hpp>
 #include <Gfx/Graph/interop/DirectShowPixelFormat.hpp>
+#include <Gfx/Graph/interop/DrmPixelFormat.hpp>
 #include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
 #if defined(__linux__)
 #include <Gfx/Graph/interop/V4L2PixelFormat.hpp>
@@ -92,6 +93,8 @@ static_assert(uint16_t(V::DPX10LE) == 15);
 static_assert(uint16_t(V::RGB12P) == 16);
 static_assert(uint16_t(V::RGB48) == 17);
 static_assert(uint16_t(V::RGB10) == 18);
+static_assert(uint16_t(V::X2RGB10) == 120);
+static_assert(uint16_t(V::X2BGR10) == 121);
 static_assert(uint16_t(V::RGB332) == 90);
 static_assert(uint16_t(V::RGB565) == 91);
 static_assert(uint16_t(V::RGB565BE) == 92);
@@ -167,7 +170,7 @@ TEST_CASE("the vocabulary is non-trivial and self-consistent", "[gfx][pixfmt]")
   const auto all = described();
   REQUIRE(all.size() == vpf::formatCount());
   // Guards against the table being accidentally emptied or halved.
-  CHECK(all.size() == 88);
+  CHECK(all.size() == 90);
 
   for(const auto* i : all)
   {
@@ -486,7 +489,7 @@ TEST_CASE("AV bridge: score -> AV -> score round-trip", "[gfx][pixfmt][av]")
     CHECK(vpf::fromAVPixelFormat(av) == i->format);
   }
   // Exact, not a floor: a floor lets a batch of mappings be deleted silently.
-  CHECK(twins == 58);
+  CHECK(twins == 60);
 }
 
 TEST_CASE("AV bridge: AV -> score -> AV round-trip", "[gfx][pixfmt][av]")
@@ -672,6 +675,8 @@ TEST_CASE("every AV mapping is pinned to a named FFmpeg format", "[gfx][pixfmt][
     {V::XRGB8, "0rgb"},
     {V::XBGR8, "0bgr"},
     {V::RGB48, "rgb48le"},
+    {V::X2RGB10, "x2rgb10le"},
+    {V::X2BGR10, "x2bgr10le"},
     {V::RGB565, "rgb565le"},
     {V::RGB565BE, "rgb565be"},
     {V::RGB555, "rgb555le"},
@@ -740,7 +745,7 @@ TEST_CASE("every AV mapping is pinned to a named FFmpeg format", "[gfx][pixfmt][
       CHECK(pinned.count(i->format) == 1);
     }
   }
-  CHECK(pinned.size() == 58);
+  CHECK(pinned.size() == 60);
 }
 
 // Every V4L2 fourcc pinned to the kernel constant. The round-trip sweep only
@@ -977,7 +982,7 @@ TEST_CASE("wire-only descriptors are frozen", "[gfx][pixfmt]")
   }
   CHECK(frozen.size() == 30);
   // and together the two sets are the whole vocabulary
-  CHECK(frozen.size() + 58u == vpf::formatCount());
+  CHECK(frozen.size() + 60u == vpf::formatCount());
 }
 
 // The byteOrder rule stated in the header has two halves; only the first was
@@ -1062,3 +1067,58 @@ TEST_CASE("DirectShow fourccs resolve to the right layout", "[gfx][pixfmt][dshow
   CHECK_FALSE(vpf::isDirectShowCompressedFourcc(f("NV12")));
   CHECK(vpf::fromDirectShowFourcc(0) == V::Unknown);
 }
+
+// DRM fourccs, pinned by literal characters. A DRM name reads in machine-word
+// order, so the memory byte order is its reverse -- DRM_ARGB8888 is B,G,R,A in
+// memory. Getting that inversion wrong is the most common red/blue swap on the
+// dma-buf path, so the direction is asserted explicitly rather than left to a
+// round-trip that would accept either reading.
+TEST_CASE("DRM fourccs resolve with the word-order inversion", "[gfx][pixfmt][drm]")
+{
+  using vpf::drmPixelFourcc;
+  const auto f = [](const char* s) { return drmPixelFourcc(s[0], s[1], s[2], s[3]); };
+  struct Pin { const char* fourcc; V expect; };
+  static const Pin kPins[] = {
+      // the inversion: the name says ARGB, memory holds B,G,R,A
+      {"AR24", V::BGRA8},   {"AB24", V::RGBA8},
+      {"XR24", V::BGRX8},   {"XB24", V::RGBX8},
+      {"RA24", V::ABGR8},   {"BA24", V::ARGB8},
+      {"RG24", V::BGR24},   {"BG24", V::RGB24},
+      {"RG16", V::RGB565},
+      {"AR30", V::X2RGB10}, {"AB30", V::X2BGR10},
+      {"AB4H", V::RGBA16F},
+      // semi-planar and planar
+      {"NV12", V::NV12}, {"NV21", V::NV21}, {"NV16", V::NV16},
+      {"NV61", V::NV61}, {"NV24", V::NV24}, {"NV42", V::NV42},
+      {"P010", V::P010}, {"P210", V::P210}, {"P410", V::P416},
+      {"YU12", V::YUV420P}, {"YV12", V::YVU420P},
+      {"YU16", V::YUV422P}, {"YV16", V::YVU422P},
+      {"YU24", V::YUV444P},
+      // packed 4:2:2
+      {"YUYV", V::YUYV422}, {"YVYU", V::YVYU422},
+      {"UYVY", V::UYVY422}, {"VYUY", V::VYUY422},
+      // single channel
+      {"R8  ", V::Mono8}, {"R16 ", V::Mono16},
+  };
+  std::set<V> pinned;
+  for(const auto& p : kPins)
+  {
+    INFO("DRM fourcc " << p.fourcc);
+    CHECK(vpf::fromDrmFourcc(f(p.fourcc)) == p.expect);
+    CHECK(vpf::toDrmFourcc(p.expect) == f(p.fourcc));
+    pinned.insert(p.expect);
+  }
+  for(const auto* i : described())
+  {
+    if(vpf::toDrmFourcc(i->format) != 0)
+    {
+      INFO(i->name << " has a DRM fourcc but is not pinned");
+      CHECK(pinned.count(i->format) == 1);
+    }
+  }
+  // The V-first DRM layouts must keep their swap visible, exactly as elsewhere.
+  CHECK(vpf::chromaSwappedTwin(vpf::fromDrmFourcc(f("YV12"))) == V::YUV420P);
+  CHECK(vpf::chromaSwappedTwin(vpf::fromDrmFourcc(f("YV16"))) == V::YUV422P);
+  CHECK(vpf::fromDrmFourcc(0) == V::Unknown);
+  CHECK(vpf::toDrmFourcc(V::Unknown) == 0);
+}

From 113023960fa7cd5afc9779492c572b2476388075 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 09:17:28 -0400
Subject: [PATCH 18/20] gfx: add the GPU-texture axis alongside the buffer
 vocabulary

Spout hands over a D3D11 texture, Syphon an IOSurface, dma-buf import an
EGLImage. None of those is a CPU buffer, so forcing them through the buffer
vocabulary is a category error -- the same mistake as baking stride alignment
into a format descriptor. What they share is a third axis: what a GPU texture
holds.

Map between the two, and be explicit that it is not a bijection:

  - a planar layout needs one texture per plane, so the answer is per plane; a
    semi-planar chroma plane is RG8/RG16, a fully planar one R8/R16
  - a packed YUV layout samples as a wider RGBA8 texture and is unpacked in a
    shader, because QRhi has no YUV format. Its texture format therefore says
    nothing about its colour model, and UYVY422 is 960 texels wide for a
    1920-pixel row
  - the wire-only layouts (v210, r210, DPX, 12-bit packed) have no texture at
    all: they must be decoded first, and answer UnknownFormat
  - the reverse direction only covers the unambiguous RGB formats, since a
    shader-unpacked YUV texture is RGBA8 like any other

Chroma plane dimensions round up, matching the buffer arithmetic, so an odd
raster does not lose its last chroma row or column here either.

Kept in its own header so the vocabulary stays free of Qt and RHI includes,
exactly as the libav bridge is kept separate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-gfx/CMakeLists.txt   |   2 +
 .../Graph/interop/VideoPixelFormatQRhi.cpp    | 146 ++++++++++++++++++
 .../Graph/interop/VideoPixelFormatQRhi.hpp    |  64 ++++++++
 tests/unit/VideoPixelFormatTest.cpp           |  92 +++++++++++
 4 files changed, 304 insertions(+)
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.cpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.hpp

diff --git a/src/plugins/score-plugin-gfx/CMakeLists.txt b/src/plugins/score-plugin-gfx/CMakeLists.txt
index df9944431e..30faa00df7 100644
--- a/src/plugins/score-plugin-gfx/CMakeLists.txt
+++ b/src/plugins/score-plugin-gfx/CMakeLists.txt
@@ -245,10 +245,12 @@ set(HDRS
     Gfx/Graph/interop/V4L2PixelFormat.hpp
     Gfx/Graph/interop/DirectShowPixelFormat.hpp
     Gfx/Graph/interop/DrmPixelFormat.hpp
+    Gfx/Graph/interop/VideoPixelFormatQRhi.hpp
     Gfx/Graph/interop/VideoPixelFormat.cpp
     Gfx/Graph/interop/V4L2PixelFormat.cpp
     Gfx/Graph/interop/DirectShowPixelFormat.cpp
     Gfx/Graph/interop/DrmPixelFormat.cpp
+    Gfx/Graph/interop/VideoPixelFormatQRhi.cpp
 
     Gfx/Graph/decoders/GPUVideoDecoder.hpp
     Gfx/Graph/decoders/GPUVideoDecoderFactory.hpp
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.cpp
new file mode 100644
index 0000000000..0763492818
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.cpp
@@ -0,0 +1,146 @@
+#include <Gfx/Graph/interop/VideoPixelFormatQRhi.hpp>
+
+namespace score::gfx::interop
+{
+
+QRhiTexture::Format planeTextureFormat(VideoPixelFormat f, int plane) noexcept
+{
+  const auto& info = formatInfo(f);
+  if(!info.valid() || plane < 0 || plane >= info.planeCount)
+    return QRhiTexture::UnknownFormat;
+
+  if(info.isPlanar())
+  {
+    // One texture per plane. A semi-planar chroma plane carries two components
+    // per site, a fully planar one carries a single component.
+    const bool chroma = plane > 0;
+    const bool twoComponents = chroma && info.planeCount == 2;
+    const bool sixteenBit = info.blockBytes == 2;
+    if(twoComponents)
+      return sixteenBit ? QRhiTexture::RG16 : QRhiTexture::RG8;
+    return sixteenBit ? QRhiTexture::R16 : QRhiTexture::R8;
+  }
+
+  // Packed. Everything a shader can unpack is sampled as some fixed-width
+  // texture; the format below is the sampling format, not a statement about the
+  // colour model.
+  switch(f)
+  {
+    case VideoPixelFormat::BGRA8:
+    case VideoPixelFormat::BGRX8:
+      return QRhiTexture::BGRA8;
+
+    case VideoPixelFormat::RGBA8:
+    case VideoPixelFormat::RGBX8:
+    case VideoPixelFormat::ARGB8:
+    case VideoPixelFormat::ABGR8:
+    case VideoPixelFormat::XRGB8:
+    case VideoPixelFormat::XBGR8:
+    // Packed 4:2:2 and 4:4:4 YUV: four bytes per texel, unpacked in a shader.
+    case VideoPixelFormat::UYVY422:
+    case VideoPixelFormat::YUYV422:
+    case VideoPixelFormat::YVYU422:
+    case VideoPixelFormat::VYUY422:
+    case VideoPixelFormat::VUYA:
+    case VideoPixelFormat::VUYX:
+    case VideoPixelFormat::AYUV:
+    case VideoPixelFormat::XYUV:
+    case VideoPixelFormat::YUVA:
+    case VideoPixelFormat::YUVX:
+      return QRhiTexture::RGBA8;
+
+    case VideoPixelFormat::X2RGB10:
+    case VideoPixelFormat::X2BGR10:
+      return QRhiTexture::RGB10A2;
+
+    case VideoPixelFormat::RGBA16:
+    case VideoPixelFormat::Y210:
+    case VideoPixelFormat::Y216:
+    case VideoPixelFormat::V216:
+    case VideoPixelFormat::AYUV64:
+      return QRhiTexture::RGBA16F;
+    case VideoPixelFormat::RGBA16F:
+      return QRhiTexture::RGBA16F;
+    case VideoPixelFormat::RGBA32F:
+      return QRhiTexture::RGBA32F;
+
+    case VideoPixelFormat::Mono8:
+    case VideoPixelFormat::BayerBGGR8:
+    case VideoPixelFormat::BayerGBRG8:
+    case VideoPixelFormat::BayerGRBG8:
+    case VideoPixelFormat::BayerRGGB8:
+    case VideoPixelFormat::BayerRG8:
+      return QRhiTexture::R8;
+    case VideoPixelFormat::Mono10:
+    case VideoPixelFormat::Mono12:
+    case VideoPixelFormat::Mono16:
+    case VideoPixelFormat::Mono16BE:
+    case VideoPixelFormat::BayerBGGR16:
+    case VideoPixelFormat::BayerRGGB16:
+    case VideoPixelFormat::BayerRG12:
+      return QRhiTexture::R16;
+
+    default:
+      // The wire-only layouts (v210, r210, DPX, 12-bit packed, the sub-byte RGB
+      // group) have no texture a shader can sample directly; they are decoded
+      // into one of the above first.
+      return QRhiTexture::UnknownFormat;
+  }
+}
+
+uint32_t
+planeTextureWidth(VideoPixelFormat f, int plane, uint32_t width) noexcept
+{
+  const auto& info = formatInfo(f);
+  if(!info.valid() || plane < 0 || plane >= info.planeCount || width == 0)
+    return 0;
+  if(info.isPlanar())
+  {
+    if(plane == 0 || plane == 3)
+      return width;
+    return (width + info.horizontalSubsampling - 1) / info.horizontalSubsampling;
+  }
+  // Packed: as many texels as the block geometry needs. UYVY422 packs two pixels
+  // into one RGBA8 texel, so a 1920-pixel row is 960 texels wide.
+  const auto texelBytes = 4u;
+  const auto bytes = rowBytes(f, width);
+  return uint32_t((bytes + texelBytes - 1) / texelBytes);
+}
+
+uint32_t
+planeTextureHeight(VideoPixelFormat f, int plane, uint32_t height) noexcept
+{
+  const auto& info = formatInfo(f);
+  if(!info.valid() || plane < 0 || plane >= info.planeCount || height == 0)
+    return 0;
+  if(info.isPlanar() && plane > 0 && plane < 3)
+    return (height + info.verticalSubsampling - 1) / info.verticalSubsampling;
+  return height;
+}
+
+VideoPixelFormat fromTextureFormat(QRhiTexture::Format f) noexcept
+{
+  // Only the unambiguous RGB formats. A shader-unpacked YUV texture is RGBA8
+  // like any other, so the direction genuinely cannot be inverted for those.
+  switch(f)
+  {
+    case QRhiTexture::BGRA8:
+      return VideoPixelFormat::BGRA8;
+    case QRhiTexture::RGBA8:
+      return VideoPixelFormat::RGBA8;
+    case QRhiTexture::RGBA16F:
+      return VideoPixelFormat::RGBA16F;
+    case QRhiTexture::RGBA32F:
+      return VideoPixelFormat::RGBA32F;
+    case QRhiTexture::RGB10A2:
+      return VideoPixelFormat::X2RGB10;
+    case QRhiTexture::R8:
+      return VideoPixelFormat::Mono8;
+    case QRhiTexture::R16:
+      return VideoPixelFormat::Mono16;
+    default:
+      return VideoPixelFormat::Unknown;
+  }
+}
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.hpp
new file mode 100644
index 0000000000..d2ded51bbc
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/VideoPixelFormatQRhi.hpp
@@ -0,0 +1,64 @@
+#pragma once
+
+/**
+ * @file VideoPixelFormatQRhi.hpp
+ * @brief Bridge between a CPU/DMA buffer layout and a GPU texture format.
+ *
+ * These are two different axes, and conflating them is a category error:
+ *
+ *   VideoPixelFormat   what a buffer physically holds (a card's DMA target, a
+ *                      dma-buf, a shared-memory frame)
+ *   QRhiTexture::Format what a GPU texture holds
+ *
+ * They are not in bijection. A planar layout needs several textures, one per
+ * plane, so it has no single texture format -- `planeTextureFormat()` answers
+ * per plane. A packed YUV layout like UYVY422 is uploaded as a wider RGBA8
+ * texture and unpacked in a shader, so its texture format says nothing about its
+ * colour model. And the wire-only formats (v210, r210, 12-bit packed) have no
+ * texture format at all: they must be decoded first.
+ *
+ * This is the axis shared texture transports work in -- Spout hands over a D3D11
+ * texture, Syphon an IOSurface, dma-buf import an EGLImage -- so they belong
+ * here rather than being forced through the buffer vocabulary.
+ *
+ * Kept separate from VideoPixelFormat.hpp so the vocabulary itself stays free of
+ * Qt and RHI dependencies, exactly as the libav bridge is kept separate.
+ */
+
+#include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+
+#include <score_plugin_gfx_export.h>
+
+#include <QtGui/private/qrhi_p.h>
+
+namespace score::gfx::interop
+{
+
+/// Texture format for plane `plane` of `f`, or UnknownFormat when the layout has
+/// no direct GPU representation (wire-only formats) or the plane does not exist.
+///
+/// For packed layouts only plane 0 exists, and the answer is the format a shader
+/// samples to recover the pixels -- which for packed YUV is a wider RGBA8
+/// texture, not a YUV format, because QRhi has none.
+SCORE_PLUGIN_GFX_EXPORT
+QRhiTexture::Format
+planeTextureFormat(VideoPixelFormat f, int plane) noexcept;
+
+/// Width in texels of plane `plane` for a frame `width` pixels wide. Packed YUV
+/// needs fewer texels than pixels because several components share one texel;
+/// chroma planes are narrowed by the subsampling.
+SCORE_PLUGIN_GFX_EXPORT
+uint32_t planeTextureWidth(VideoPixelFormat f, int plane, uint32_t width) noexcept;
+
+/// Height in texels of plane `plane` for a frame `height` pixels tall.
+SCORE_PLUGIN_GFX_EXPORT
+uint32_t planeTextureHeight(VideoPixelFormat f, int plane, uint32_t height) noexcept;
+
+/// The layout a texture of this format holds, for the transports that hand over
+/// a texture rather than a buffer (Spout, Syphon, dma-buf import). Only the
+/// unambiguous RGB formats round-trip: a shader-unpacked YUV texture is RGBA8
+/// like any other, so the direction cannot be inverted for those.
+SCORE_PLUGIN_GFX_EXPORT
+VideoPixelFormat fromTextureFormat(QRhiTexture::Format f) noexcept;
+
+} // namespace score::gfx::interop
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index ddc58bcdf0..69c4908f9c 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -25,6 +25,7 @@
 #include <Gfx/Graph/interop/VideoPixelFormat.hpp>
 #include <Gfx/Graph/interop/DirectShowPixelFormat.hpp>
 #include <Gfx/Graph/interop/DrmPixelFormat.hpp>
+#include <Gfx/Graph/interop/VideoPixelFormatQRhi.hpp>
 #include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
 #if defined(__linux__)
 #include <Gfx/Graph/interop/V4L2PixelFormat.hpp>
@@ -1122,3 +1123,94 @@ TEST_CASE("DRM fourccs resolve with the word-order inversion", "[gfx][pixfmt][dr
   CHECK(vpf::fromDrmFourcc(0) == V::Unknown);
   CHECK(vpf::toDrmFourcc(V::Unknown) == 0);
 }
+
+// The GPU-texture axis. Not a bijection with the buffer axis, and the test says
+// so rather than pretending: planar layouts answer per plane, packed YUV samples
+// as RGBA8 because QRhi has no YUV format, and the wire-only layouts have no
+// texture at all.
+TEST_CASE("plane texture formats and sizes", "[gfx][pixfmt][qrhi]")
+{
+  // Packed RGB keeps its own format and full width.
+  CHECK(vpf::planeTextureFormat(V::BGRA8, 0) == QRhiTexture::BGRA8);
+  CHECK(vpf::planeTextureWidth(V::BGRA8, 0, 1920) == 1920);
+  CHECK(vpf::planeTextureHeight(V::BGRA8, 0, 1080) == 1080);
+
+  // Packed 4:2:2 samples as RGBA8 at half the texel width: two pixels per texel.
+  CHECK(vpf::planeTextureFormat(V::UYVY422, 0) == QRhiTexture::RGBA8);
+  CHECK(vpf::planeTextureWidth(V::UYVY422, 0, 1920) == 960);
+  CHECK(vpf::planeTextureHeight(V::UYVY422, 0, 1080) == 1080);
+
+  // Semi-planar: R8 luma plus an RG8 chroma plane at half size.
+  CHECK(vpf::planeTextureFormat(V::NV12, 0) == QRhiTexture::R8);
+  CHECK(vpf::planeTextureFormat(V::NV12, 1) == QRhiTexture::RG8);
+  CHECK(vpf::planeTextureWidth(V::NV12, 1, 1920) == 960);
+  CHECK(vpf::planeTextureHeight(V::NV12, 1, 1080) == 540);
+  CHECK(vpf::planeTextureFormat(V::NV12, 2) == QRhiTexture::UnknownFormat);
+
+  // 10-bit semi-planar uses 16-bit lanes.
+  CHECK(vpf::planeTextureFormat(V::P010, 0) == QRhiTexture::R16);
+  CHECK(vpf::planeTextureFormat(V::P010, 1) == QRhiTexture::RG16);
+
+  // Fully planar: three single-component planes.
+  CHECK(vpf::planeTextureFormat(V::YUV420P, 0) == QRhiTexture::R8);
+  CHECK(vpf::planeTextureFormat(V::YUV420P, 1) == QRhiTexture::R8);
+  CHECK(vpf::planeTextureFormat(V::YUV420P, 2) == QRhiTexture::R8);
+  CHECK(vpf::planeTextureFormat(V::YUV422P10, 1) == QRhiTexture::R16);
+
+  // Odd sizes round the chroma plane up, as the buffer arithmetic does.
+  CHECK(vpf::planeTextureWidth(V::YUV420P, 1, 1921) == 961);
+  CHECK(vpf::planeTextureHeight(V::YUV420P, 1, 1081) == 541);
+
+  // The wire-only layouts must be decoded before they are a texture.
+  for(auto f : {V::V210, V::R210, V::R12B, V::RGB12P, V::DPX10})
+  {
+    INFO("wire-only " << vpf::formatName(f));
+    CHECK(vpf::planeTextureFormat(f, 0) == QRhiTexture::UnknownFormat);
+  }
+
+  // Degenerate inputs
+  CHECK(vpf::planeTextureFormat(V::Unknown, 0) == QRhiTexture::UnknownFormat);
+  CHECK(vpf::planeTextureWidth(V::BGRA8, 0, 0) == 0);
+  CHECK(vpf::planeTextureWidth(V::BGRA8, -1, 1920) == 0);
+
+  // Every format either offers a plane-0 texture or is a decode-first layout;
+  // none may answer a format for a plane it does not have.
+  for(const auto* i : described())
+  {
+    INFO("format " << i->name);
+    CHECK(vpf::planeTextureFormat(i->format, i->planeCount)
+          == QRhiTexture::UnknownFormat);
+    for(int p = 0; p < i->planeCount; ++p)
+    {
+      if(vpf::planeTextureFormat(i->format, p) != QRhiTexture::UnknownFormat)
+      {
+        CHECK(vpf::planeTextureWidth(i->format, p, 1920) > 0);
+        CHECK(vpf::planeTextureHeight(i->format, p, 1080) > 0);
+      }
+    }
+  }
+}
+
+// The texture-to-buffer direction is for transports that hand over a texture:
+// Spout a D3D11 texture, Syphon an IOSurface, dma-buf an EGLImage.
+TEST_CASE("texture formats map back only where unambiguous", "[gfx][pixfmt][qrhi]")
+{
+  CHECK(vpf::fromTextureFormat(QRhiTexture::BGRA8) == V::BGRA8);
+  CHECK(vpf::fromTextureFormat(QRhiTexture::RGBA8) == V::RGBA8);
+  CHECK(vpf::fromTextureFormat(QRhiTexture::RGBA16F) == V::RGBA16F);
+  CHECK(vpf::fromTextureFormat(QRhiTexture::RGBA32F) == V::RGBA32F);
+  CHECK(vpf::fromTextureFormat(QRhiTexture::R8) == V::Mono8);
+  CHECK(vpf::fromTextureFormat(QRhiTexture::R16) == V::Mono16);
+  // Depth and compressed textures are not video buffers.
+  for(auto t : {QRhiTexture::D16, QRhiTexture::D32F, QRhiTexture::BC1,
+                QRhiTexture::UnknownFormat})
+  {
+    CHECK(vpf::fromTextureFormat(t) == V::Unknown);
+  }
+  // And the round-trip holds for the ones that do map back.
+  for(auto f : {V::BGRA8, V::RGBA8, V::RGBA16F, V::RGBA32F, V::Mono8, V::Mono16})
+  {
+    INFO(vpf::formatName(f));
+    CHECK(vpf::fromTextureFormat(vpf::planeTextureFormat(f, 0)) == f);
+  }
+}

From 00a35f870f3c067e63cc61967ff9e0e79cb80166 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 09:20:00 -0400
Subject: [PATCH 19/20] gfx: add the GStreamer name edge for the shared-memory
 transports

Sh4lt and Shmdata hand over shared-memory *buffers*, not streams, and resolve
their caps through Video::gstreamerToLibav() to an AVPixelFormat -- after which a
format the decode path does not take natively is CPU-converted to RGBA. Removing
that conversion needs the layout and a stride, which is what a VideoPixelFormat
is, so they need an edge into the vocabulary.

The rest of the 54-entry gst map stays AV-first, as agreed: most of what arrives
over GStreamer is a stream format and the decode pipeline is AV-based. This table
covers the buffer layouts only.

It is a direct table rather than the existing map composed with the libav bridge,
and that is the point. Routing through AVPixelFormat loses the V-before-U
layouts, because FFmpeg has no pixel format for them: "YV12" would arrive as
YUV420P with red and blue exchanged, and "YVU9" likewise. The suite asserts that
YV12 and I420 do not collapse onto each other and that the swap is recorded.

This is the mapping, not the rewiring. Pointing Sh4lt and Shmdata at host-import
instead of the rescaler is the follow-up, and it wants those transports actually
running to validate, which needs a producer this machine does not have.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 src/plugins/score-plugin-gfx/CMakeLists.txt   |  2 +
 .../Graph/interop/GStreamerPixelFormat.cpp    | 70 +++++++++++++++++++
 .../Graph/interop/GStreamerPixelFormat.hpp    | 41 +++++++++++
 tests/unit/VideoPixelFormatTest.cpp           | 53 ++++++++++++++
 4 files changed, 166 insertions(+)
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.cpp
 create mode 100644 src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.hpp

diff --git a/src/plugins/score-plugin-gfx/CMakeLists.txt b/src/plugins/score-plugin-gfx/CMakeLists.txt
index 30faa00df7..04ac7c0df1 100644
--- a/src/plugins/score-plugin-gfx/CMakeLists.txt
+++ b/src/plugins/score-plugin-gfx/CMakeLists.txt
@@ -246,11 +246,13 @@ set(HDRS
     Gfx/Graph/interop/DirectShowPixelFormat.hpp
     Gfx/Graph/interop/DrmPixelFormat.hpp
     Gfx/Graph/interop/VideoPixelFormatQRhi.hpp
+    Gfx/Graph/interop/GStreamerPixelFormat.hpp
     Gfx/Graph/interop/VideoPixelFormat.cpp
     Gfx/Graph/interop/V4L2PixelFormat.cpp
     Gfx/Graph/interop/DirectShowPixelFormat.cpp
     Gfx/Graph/interop/DrmPixelFormat.cpp
     Gfx/Graph/interop/VideoPixelFormatQRhi.cpp
+    Gfx/Graph/interop/GStreamerPixelFormat.cpp
 
     Gfx/Graph/decoders/GPUVideoDecoder.hpp
     Gfx/Graph/decoders/GPUVideoDecoderFactory.hpp
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.cpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.cpp
new file mode 100644
index 0000000000..a44d76f6c6
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.cpp
@@ -0,0 +1,70 @@
+#include <Gfx/Graph/interop/GStreamerPixelFormat.hpp>
+
+#include <algorithm>
+#include <array>
+#include <utility>
+
+namespace score::gfx::interop
+{
+namespace
+{
+using Row = std::pair<std::string_view, VideoPixelFormat>;
+using V = VideoPixelFormat;
+
+// GStreamer names the memory byte order directly, so these read literally: its
+// "RGBA" is R,G,B,A in memory. The V-before-U spellings are distinct layouts, not
+// their U-first twins with a flag.
+constexpr std::array kRows{
+    // packed 8-bit RGB
+    Row{"RGBA", V::RGBA8}, Row{"BGRA", V::BGRA8},
+    Row{"ARGB", V::ARGB8}, Row{"ABGR", V::ABGR8},
+    Row{"RGBx", V::RGBX8}, Row{"BGRx", V::BGRX8},
+    Row{"xRGB", V::XRGB8}, Row{"xBGR", V::XBGR8},
+    Row{"RGB", V::RGB24},  Row{"BGR", V::BGR24},
+    Row{"RGB16", V::RGB565}, Row{"RGB15", V::RGB555},
+    // packed 10-bit RGB
+    Row{"r210", V::R210},
+    // packed YUV
+    Row{"YUY2", V::YUYV422}, Row{"YVYU", V::YVYU422},
+    Row{"UYVY", V::UYVY422}, Row{"VYUY", V::VYUY422},
+    Row{"AYUV", V::AYUV},    Row{"VUYA", V::VUYA},
+    Row{"v210", V::V210},    Row{"v216", V::V216},
+    Row{"Y210", V::Y210},    Row{"Y410", V::XV30},
+    Row{"IYU1", V::UYYVYY411},
+    // planar, U before V
+    Row{"I420", V::YUV420P}, Row{"Y42B", V::YUV422P},
+    Row{"Y444", V::YUV444P}, Row{"Y41B", V::YUV411P},
+    Row{"YUV9", V::YUV410P},
+    // planar, V before U
+    Row{"YV12", V::YVU420P}, Row{"YVU9", V::YVU410P},
+    // planar high bit depth
+    Row{"I420_10LE", V::YUV420P10}, Row{"I422_10LE", V::YUV422P10},
+    Row{"Y444_10LE", V::YUV444P10}, Row{"I422_12LE", V::YUV422P12},
+    Row{"Y444_12LE", V::YUV444P12}, Row{"I422_16LE", V::YUV422P16},
+    Row{"A444", V::YUVA444P},
+    // semi-planar
+    Row{"NV12", V::NV12}, Row{"NV21", V::NV21},
+    Row{"NV16", V::NV16}, Row{"NV61", V::NV61},
+    Row{"NV24", V::NV24},
+    Row{"P010_10LE", V::P010}, Row{"P016_LE", V::P216},
+    // greyscale
+    Row{"GRAY8", V::Mono8},
+    Row{"GRAY16_LE", V::Mono16}, Row{"GRAY16_BE", V::Mono16BE},
+};
+} // namespace
+
+VideoPixelFormat fromGStreamerFormat(std::string_view name) noexcept
+{
+  const auto it = std::find_if(
+      kRows.begin(), kRows.end(), [name](const Row& r) { return r.first == name; });
+  return it != kRows.end() ? it->second : V::Unknown;
+}
+
+std::string_view toGStreamerFormat(VideoPixelFormat f) noexcept
+{
+  const auto it = std::find_if(
+      kRows.begin(), kRows.end(), [f](const Row& r) { return r.second == f; });
+  return it != kRows.end() ? it->first : std::string_view{};
+}
+
+} // namespace score::gfx::interop
diff --git a/src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.hpp b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.hpp
new file mode 100644
index 0000000000..aec5be0006
--- /dev/null
+++ b/src/plugins/score-plugin-gfx/Gfx/Graph/interop/GStreamerPixelFormat.hpp
@@ -0,0 +1,41 @@
+#pragma once
+
+/**
+ * @file GStreamerPixelFormat.hpp
+ * @brief GStreamer video-format name <-> VideoPixelFormat.
+ *
+ * GStreamer names formats with strings in caps ("NV12", "I420", "v210"), and
+ * `Video::gstreamerToLibav()` already maps those to AVPixelFormat for the decode
+ * path. That mapping stays: most of what arrives over GStreamer is a *stream*
+ * format, and the decode pipeline is AV-based.
+ *
+ * This table exists for the transports that hand over a *buffer* -- Sh4lt and
+ * Shmdata pass shared memory -- where the layout is what matters, because a
+ * layout plus a stride is what lets a frame be imported straight onto the GPU
+ * instead of being converted on the CPU first.
+ *
+ * It is a direct table rather than a composition of the existing map with the
+ * libav bridge, and that is the point: going through AVPixelFormat loses the
+ * V-before-U layouts, since FFmpeg has no pixel format for them. "YV12" would
+ * arrive as YUV420P with red and blue exchanged.
+ */
+
+#include <Gfx/Graph/interop/VideoPixelFormat.hpp>
+
+#include <score_plugin_gfx_export.h>
+
+#include <string_view>
+
+namespace score::gfx::interop
+{
+
+/// The layout behind a GStreamer format name, or Unknown when score has no row
+/// for it -- which includes the formats that are streams rather than buffers.
+SCORE_PLUGIN_GFX_EXPORT
+VideoPixelFormat fromGStreamerFormat(std::string_view name) noexcept;
+
+/// The GStreamer name for a layout, or an empty view when it has none.
+SCORE_PLUGIN_GFX_EXPORT
+std::string_view toGStreamerFormat(VideoPixelFormat f) noexcept;
+
+} // namespace score::gfx::interop
diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 69c4908f9c..3ebce5d381 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -25,6 +25,7 @@
 #include <Gfx/Graph/interop/VideoPixelFormat.hpp>
 #include <Gfx/Graph/interop/DirectShowPixelFormat.hpp>
 #include <Gfx/Graph/interop/DrmPixelFormat.hpp>
+#include <Gfx/Graph/interop/GStreamerPixelFormat.hpp>
 #include <Gfx/Graph/interop/VideoPixelFormatQRhi.hpp>
 #include <Gfx/Graph/interop/VideoPixelFormatAV.hpp>
 #if defined(__linux__)
@@ -1214,3 +1215,55 @@ TEST_CASE("texture formats map back only where unambiguous", "[gfx][pixfmt][qrhi
     CHECK(vpf::fromTextureFormat(vpf::planeTextureFormat(f, 0)) == f);
   }
 }
+
+// GStreamer names, for the transports that hand over a buffer rather than a
+// stream. Composing the existing gst->AV map with the libav bridge would lose the
+// V-before-U layouts, so this asserts the direct table gets them right -- that is
+// the whole reason it exists.
+TEST_CASE("GStreamer names resolve to the right layout", "[gfx][pixfmt][gst]")
+{
+  struct Pin { const char* name; V expect; };
+  static const Pin kPins[] = {
+      {"RGBA", V::RGBA8}, {"BGRA", V::BGRA8}, {"ARGB", V::ARGB8}, {"ABGR", V::ABGR8},
+      {"RGBx", V::RGBX8}, {"BGRx", V::BGRX8}, {"xRGB", V::XRGB8}, {"xBGR", V::XBGR8},
+      {"RGB", V::RGB24},  {"BGR", V::BGR24},
+      {"YUY2", V::YUYV422}, {"UYVY", V::UYVY422}, {"YVYU", V::YVYU422},
+      {"v210", V::V210},  {"v216", V::V216},  {"r210", V::R210},
+      {"I420", V::YUV420P}, {"Y42B", V::YUV422P}, {"Y444", V::YUV444P},
+      {"Y41B", V::YUV411P}, {"YUV9", V::YUV410P},
+      {"NV12", V::NV12},  {"NV21", V::NV21},  {"NV16", V::NV16},
+      {"NV61", V::NV61},  {"NV24", V::NV24},
+      {"I420_10LE", V::YUV420P10}, {"I422_10LE", V::YUV422P10},
+      {"P010_10LE", V::P010}, {"A444", V::YUVA444P},
+      {"GRAY8", V::Mono8}, {"GRAY16_LE", V::Mono16}, {"GRAY16_BE", V::Mono16BE},
+  };
+  for(const auto& p : kPins)
+  {
+    INFO("gst format " << p.name);
+    CHECK(vpf::fromGStreamerFormat(p.name) == p.expect);
+    CHECK(vpf::toGStreamerFormat(p.expect) == std::string_view{p.name});
+  }
+  // The point of a direct table: these must NOT collapse onto their U-first
+  // twins, which is what routing through AVPixelFormat would have done.
+  CHECK(vpf::fromGStreamerFormat("YV12") == V::YVU420P);
+  CHECK(vpf::fromGStreamerFormat("YVU9") == V::YVU410P);
+  CHECK(vpf::fromGStreamerFormat("YV12") != vpf::fromGStreamerFormat("I420"));
+  CHECK(vpf::chromaSwappedTwin(vpf::fromGStreamerFormat("YV12"))
+        == vpf::fromGStreamerFormat("I420"));
+  CHECK(vpf::chromaSwappedTwin(vpf::fromGStreamerFormat("NV21"))
+        == vpf::fromGStreamerFormat("NV12"));
+  // Case matters in caps, and unknown names must not guess.
+  CHECK(vpf::fromGStreamerFormat("nv12") == V::Unknown);
+  CHECK(vpf::fromGStreamerFormat("") == V::Unknown);
+  CHECK(vpf::fromGStreamerFormat("ENCODED") == V::Unknown);
+  CHECK(vpf::toGStreamerFormat(V::Unknown).empty());
+  // A name maps to one layout and back, for every row.
+  for(const auto* i : described())
+  {
+    const auto name = vpf::toGStreamerFormat(i->format);
+    if(name.empty())
+      continue;
+    INFO(i->name << " <-> " << name);
+    CHECK(vpf::fromGStreamerFormat(name) == i->format);
+  }
+}

From 7bc0e11f55f7368b7c267f7442301301549ad6de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Micha=C3=ABl=20Celerier?=
 <jeanmichael.celerier@gmail.com>
Date: Thu, 30 Jul 2026 12:23:11 -0400
Subject: [PATCH 20/20] tests: guard the V4L2 pin case for non-Linux hosts

The V4L2 round-trip case was inside #if defined(__linux__), but the pinned-
constants case added alongside it was not, so every V4L2_PIX_FMT_* reference in
it broke the build anywhere without linux/videodev2.h.

Found by compiling on Windows, which is the only thing that could have found it:
the Linux build is green either way, and nothing in review flags a missing guard
on a block that sits next to a guarded one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014rZgzE8JjWvHDtaVUhxpLE
---
 tests/unit/VideoPixelFormatTest.cpp | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/unit/VideoPixelFormatTest.cpp b/tests/unit/VideoPixelFormatTest.cpp
index 3ebce5d381..963f849627 100644
--- a/tests/unit/VideoPixelFormatTest.cpp
+++ b/tests/unit/VideoPixelFormatTest.cpp
@@ -750,6 +750,7 @@ TEST_CASE("every AV mapping is pinned to a named FFmpeg format", "[gfx][pixfmt][
   CHECK(pinned.size() == 60);
 }
 
+#if defined(__linux__)
 // Every V4L2 fourcc pinned to the kernel constant. The round-trip sweep only
 // composes to/from, so swapping two same-geometry formats in BOTH directions --
 // NV12 with NV21 -- satisfies it while every camera silently delivers exchanged
@@ -850,6 +851,7 @@ TEST_CASE("every V4L2 mapping is pinned to a kernel constant", "[gfx][pixfmt][v4
   CHECK(vpf::fromV4L2PixelFormat(V4L2_PIX_FMT_Z16) == V::Mono16);
 #endif
 }
+#endif
 
 // chromaSwappedTwin needs positive coverage: the sweep over described formats
 // skips anything returning Unknown, so deleting every case would pass vacuously.