VideoPixelFormat.hpp

Go to the documentation of this file.

#pragma once
 
#include <score_plugin_gfx_export.h>
 
#include <cstddef>
#include <cstdint>
 
namespace score::gfx::interop
{
 
enum class ColorModel : uint8_t
{
  Unknown = 0,
  RGB,
  YUV,
  Grey,  
  Bayer, 
};
 
enum class ByteOrder : uint8_t
{
  NA = 0,
  Little,
  Big,
};
 
// ---------------------------------------------------------------------------
// 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). An averaged bits-per-pixel cannot express v210 at all
// (128 bytes / 48 pixels = 21.33 bits) and over-computes planar strides, so a
// new packed layout needs a table row rather than 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. 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.  */ \
  /* 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, 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)                         \
  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)                           \
  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)                          \
  /* 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)                          \
  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)                     \
  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)                     \
  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)                              \
  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)                        \
  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)                        \
  /* 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  */ \
  /* 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)                 \
  /* The 10-bit CFA orders occupy a 16-bit little-endian container, so they are */ \
  /* two bytes per sample like the 16-bit orders. V4L2 defines the ten          */ \
  /* significant bits as right-aligned; a producer that left-aligns them        */ \
  /* (the Tegra VI does) is a sixty-fourfold scale a demosaic must be told      */ \
  /* about, not a distinct layout.                                             */ \
  X(BayerBGGR10, 123, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                 \
  X(BayerGBRG10, 124, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                 \
  X(BayerGRBG10, 125, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                 \
  X(BayerRGGB10, 126, Bayer, 1, 1, 1, 1, 2, false, Little, 64)                 \
  X(Mono16BE, 86, Grey, 1, 1, 1, 1, 2, false, Big, 64)
 
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
};
 
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
}
 
struct VideoPixelFormatInfo
{
  const char* name{"unknown"};
  VideoPixelFormat format{VideoPixelFormat::Unknown};
  ColorModel colorModel{ColorModel::Unknown};
  uint8_t planeCount{1};
  uint8_t horizontalSubsampling{1}; 
  uint8_t verticalSubsampling{1};   
  uint16_t blockPixels{1};
  uint16_t blockBytes{};
  bool hasAlpha{};
  ByteOrder byteOrder{ByteOrder::NA};
  uint16_t preferredStrideAlignment{256};
 
  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; }
  constexpr bool isAchromatic() const noexcept
  {
    return colorModel == ColorModel::Grey || colorModel == ColorModel::Bayer;
  }
  constexpr bool valid() const noexcept { return blockBytes != 0; }
};
 
constexpr std::size_t alignUp(std::size_t v, std::size_t a) noexcept
{
  return a <= 1 ? v : ((v + a - 1) / a) * a;
}
 
SCORE_PLUGIN_GFX_EXPORT
const VideoPixelFormatInfo& formatInfo(VideoPixelFormat f) noexcept;
 
SCORE_PLUGIN_GFX_EXPORT
const char* formatName(VideoPixelFormat f) noexcept;
 
SCORE_PLUGIN_GFX_EXPORT
VideoPixelFormat chromaSwappedTwin(VideoPixelFormat f) noexcept;
 
SCORE_PLUGIN_GFX_EXPORT
const VideoPixelFormatInfo* allFormats(std::size_t& count) noexcept;
 
SCORE_PLUGIN_GFX_EXPORT
std::size_t rowBytes(VideoPixelFormat f, uint32_t width) noexcept;
 
SCORE_PLUGIN_GFX_EXPORT
std::size_t
alignedRowBytes(VideoPixelFormat f, uint32_t width, std::size_t alignment) noexcept;
 
SCORE_PLUGIN_GFX_EXPORT
std::size_t defaultStride(VideoPixelFormat f, uint32_t width) noexcept;
 
SCORE_PLUGIN_GFX_EXPORT
std::size_t
bytesPerFrame(VideoPixelFormat f, uint32_t width, uint32_t height) noexcept;
 
} // namespace score::gfx::interop