pixelformat.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_PROAV
#include <promeki/namespace.h>
#include <promeki/string.h>
#include <promeki/list.h>
#include <promeki/error.h>
#include <promeki/result.h>
#include <promeki/fourcc.h>
#include <promeki/colormodel.h>
#include <promeki/pixelmemlayout.h>
#include <promeki/videocodec.h>
#include <promeki/enums.h>
#include <promeki/datatype.h>
 
PROMEKI_NAMESPACE_BEGIN
 
class DataStream;
 
class Image;
class ImageDesc;
class UncompressedVideoPayload;
class PaintEngine;
 
class PixelFormat {
        public:
                PROMEKI_DATATYPE(PixelFormat, DataTypePixelFormat, 1)
 
                
                Error writeToStream(DataStream &s) const;
                template <uint32_t V> static Result<PixelFormat> readFromStream(DataStream &s);
 
                static constexpr size_t MaxComps = PixelMemLayout::MaxComps; 
 
                enum ID {
                        Invalid = 0, 
 
                        // -- RGB/RGBA uncompressed (8-bit, byte-aligned) --
                        RGBA8_sRGB = 1, 
                        RGB8_sRGB = 2,  
 
                        // -- RGB DPX packed --
                        RGB10_DPX_sRGB = 3, 
 
                        // -- YCbCr 4:2:2 interleaved YUYV --
                        YUV8_422_Rec709 = 4,  
                        YUV10_422_Rec709 = 5, 
 
                        // -- JPEG compressed --
                        JPEG_RGBA8_sRGB = 6, 
                        JPEG_RGB8_sRGB = 7,  
                        JPEG_YUV8_422_Rec709 =
                                8, 
                        JPEG_YUV8_420_Rec709 =
                                9, 
 
                        // -- YCbCr 4:2:2 UYVY --
                        YUV8_422_UYVY_Rec709 = 10,     
                        YUV10_422_UYVY_LE_Rec709 = 11, 
                        YUV10_422_UYVY_BE_Rec709 = 12, 
                        YUV12_422_UYVY_LE_Rec709 = 13, 
                        YUV12_422_UYVY_BE_Rec709 = 14, 
 
                        // -- YCbCr 4:2:2 v210 --
                        YUV10_422_v210_Rec709 = 15, 
 
                        // -- YCbCr 4:2:2 planar --
                        YUV8_422_Planar_Rec709 = 16,     
                        YUV10_422_Planar_LE_Rec709 = 17, 
                        YUV10_422_Planar_BE_Rec709 = 18, 
                        YUV12_422_Planar_LE_Rec709 = 19, 
                        YUV12_422_Planar_BE_Rec709 = 20, 
 
                        // -- YCbCr 4:2:0 planar --
                        YUV8_420_Planar_Rec709 = 21,     
                        YUV10_420_Planar_LE_Rec709 = 22, 
                        YUV10_420_Planar_BE_Rec709 = 23, 
                        YUV12_420_Planar_LE_Rec709 = 24, 
                        YUV12_420_Planar_BE_Rec709 = 25, 
 
                        // -- YCbCr 4:2:0 semi-planar (NV12) --
                        YUV8_420_SemiPlanar_Rec709 = 26,     
                        YUV10_420_SemiPlanar_LE_Rec709 = 27, 
                        YUV10_420_SemiPlanar_BE_Rec709 = 28, 
                        YUV12_420_SemiPlanar_LE_Rec709 = 29, 
                        YUV12_420_SemiPlanar_BE_Rec709 = 30, 
 
                        // -- RGB/RGBA 10/12/16-bit in 16-bit words --
                        RGBA10_LE_sRGB = 31, 
                        RGBA10_BE_sRGB = 32, 
                        RGB10_LE_sRGB = 33,  
                        RGB10_BE_sRGB = 34,  
                        RGBA12_LE_sRGB = 35, 
                        RGBA12_BE_sRGB = 36, 
                        RGB12_LE_sRGB = 37,  
                        RGB12_BE_sRGB = 38,  
                        RGBA16_LE_sRGB = 39, 
                        RGBA16_BE_sRGB = 40, 
                        RGB16_LE_sRGB = 41,  
                        RGB16_BE_sRGB = 42,  
 
                        // -- YCbCr 4:4:4 DPX packed --
                        YUV10_DPX_Rec709 = 43, 
 
                        // -- BGRA/BGR (reversed component order) --
                        BGRA8_sRGB = 44,     
                        BGR8_sRGB = 45,      
                        BGRA10_LE_sRGB = 46, 
                        BGRA10_BE_sRGB = 47, 
                        BGR10_LE_sRGB = 48,  
                        BGR10_BE_sRGB = 49,  
                        BGRA12_LE_sRGB = 50, 
                        BGRA12_BE_sRGB = 51, 
                        BGR12_LE_sRGB = 52,  
                        BGR12_BE_sRGB = 53,  
                        BGRA16_LE_sRGB = 54, 
                        BGRA16_BE_sRGB = 55, 
                        BGR16_LE_sRGB = 56,  
                        BGR16_BE_sRGB = 57,  
 
                        // -- ARGB (alpha-first) --
                        ARGB8_sRGB = 58,     
                        ARGB10_LE_sRGB = 59, 
                        ARGB10_BE_sRGB = 60, 
                        ARGB12_LE_sRGB = 61, 
                        ARGB12_BE_sRGB = 62, 
                        ARGB16_LE_sRGB = 63, 
                        ARGB16_BE_sRGB = 64, 
 
                        // -- ABGR (alpha-first, blue-first) --
                        ABGR8_sRGB = 65,     
                        ABGR10_LE_sRGB = 66, 
                        ABGR10_BE_sRGB = 67, 
                        ABGR12_LE_sRGB = 68, 
                        ABGR12_BE_sRGB = 69, 
                        ABGR16_LE_sRGB = 70, 
                        ABGR16_BE_sRGB = 71, 
 
                        // -- Monochrome (sRGB luminance) --
                        Mono8_sRGB = 72,     
                        Mono10_LE_sRGB = 73, 
                        Mono10_BE_sRGB = 74, 
                        Mono12_LE_sRGB = 75, 
                        Mono12_BE_sRGB = 76, 
                        Mono16_LE_sRGB = 77, 
                        Mono16_BE_sRGB = 78, 
 
                        // -- Float RGBA/RGB/Mono (linear Rec.709 primaries) --
                        RGBAF16_LE_LinearRec709 = 79, 
                        RGBAF16_BE_LinearRec709 = 80, 
                        RGBF16_LE_LinearRec709 = 81,  
                        RGBF16_BE_LinearRec709 = 82,  
                        MonoF16_LE_LinearRec709 = 83, 
                        MonoF16_BE_LinearRec709 = 84, 
                        RGBAF32_LE_LinearRec709 = 85, 
                        RGBAF32_BE_LinearRec709 = 86, 
                        RGBF32_LE_LinearRec709 = 87,  
                        RGBF32_BE_LinearRec709 = 88,  
                        MonoF32_LE_LinearRec709 = 89, 
                        MonoF32_BE_LinearRec709 = 90, 
 
                        // -- 10:10:10:2 packed (3x10 + 1x2 in 32 bits) --
                        RGB10A2_LE_sRGB = 91, 
                        RGB10A2_BE_sRGB = 92, 
                        BGR10A2_LE_sRGB = 93, 
                        BGR10A2_BE_sRGB = 94, 
 
                        // -- YCbCr 4:4:4 (non-DPX, Rec.709) --
                        YUV8_Rec709 = 95,      
                        YUV10_LE_Rec709 = 96,  
                        YUV10_BE_Rec709 = 97,  
                        YUV12_LE_Rec709 = 98,  
                        YUV12_BE_Rec709 = 99,  
                        YUV16_LE_Rec709 = 100, 
                        YUV16_BE_Rec709 = 101, 
 
                        // -- Rec.2020 YCbCr --
                        YUV10_422_UYVY_LE_Rec2020 = 102,   
                        YUV10_422_UYVY_BE_Rec2020 = 103,   
                        YUV12_422_UYVY_LE_Rec2020 = 104,   
                        YUV12_422_UYVY_BE_Rec2020 = 105,   
                        YUV10_420_Planar_LE_Rec2020 = 106, 
                        YUV10_420_Planar_BE_Rec2020 = 107, 
                        YUV12_420_Planar_LE_Rec2020 = 108, 
                        YUV12_420_Planar_BE_Rec2020 = 109, 
 
                        // -- BT.2100 PQ / HLG HDR --
                        // Memory layout identical to the SDR
                        // BT.2020 entries above; the distinction is
                        // entirely the EOTF / transfer claim, so
                        // these IDs anchor a different ColorModel
                        // (Rec2020_PQ / Rec2020_HLG /
                        // YCbCr_Rec2020_PQ / YCbCr_Rec2020_HLG)
                        // whose @ref ColorModel::toH273 reports the
                        // matching H.273 transfer codepoint
                        // (16 = PQ, 18 = HLG).  Includes only the
                        // memory layouts that practically carry HDR
                        // (V210, P010, P216, 10-bit RGB packed, 16-
                        // bit RGB) — the combinatorial sweep across
                        // every layout × {PQ, HLG} would inflate
                        // the catalog without practical benefit.
                        // SDI / NDI HDR (PQ + HLG):
                        YUV10_422_UYVY_LE_Rec2020_PQ = 200,   
                        YUV10_422_UYVY_LE_Rec2020_HLG = 201,  
                        YUV12_422_UYVY_LE_Rec2020_PQ = 202,   
                        YUV12_422_UYVY_LE_Rec2020_HLG = 203,  
                        // Codec / NVDEC HDR output (4:2:0 PQ / HLG):
                        YUV10_420_Planar_LE_Rec2020_PQ = 204,  
                        YUV10_420_Planar_LE_Rec2020_HLG = 205, 
                        YUV12_420_Planar_LE_Rec2020_PQ = 206,  
                        YUV12_420_Planar_LE_Rec2020_HLG = 207, 
                        // NV12 / P010 semi-planar HDR (NVDEC, Intel QSV, AMD UVD):
                        YUV10_420_SemiPlanar_LE_Rec2020_PQ = 208,  
                        YUV10_420_SemiPlanar_LE_Rec2020_HLG = 209, 
                        // P216 (NDI 16-bit HDR):
                        YUV16_422_SemiPlanar_LE_Rec2020_PQ = 210,  
                        YUV16_422_SemiPlanar_LE_Rec2020_HLG = 211, 
                        // 10-bit RGB packed (RGB10A2):
                        RGB10A2_LE_Rec2020_PQ = 212,   
                        RGB10A2_LE_Rec2020_HLG = 213,  
                        // 16-bit RGB (host order):
                        RGB16_LE_Rec2020_PQ = 214,     
                        RGB16_LE_Rec2020_HLG = 215,    
                        // Half-float scene-referred linear (cinema HDR working space):
                        RGBAF16_LE_LinearRec2020 = 216, 
                        RGBF16_LE_LinearRec2020 = 217,  
                        // DCI-P3 PQ (cinema):
                        RGB16_LE_DCI_P3_PQ = 218,       
 
                        // -- Rec.601 YCbCr --
                        YUV8_422_Rec601 = 110,            
                        YUV8_422_UYVY_Rec601 = 111,       
                        YUV8_420_Planar_Rec601 = 112,     
                        YUV8_420_SemiPlanar_Rec601 = 113, 
 
                        // -- NV21 (semi-planar 4:2:0, CrCb order, Rec.709) --
                        YUV8_420_NV21_Rec709 = 114,     
                        YUV10_420_NV21_LE_Rec709 = 115, 
                        YUV10_420_NV21_BE_Rec709 = 116, 
                        YUV12_420_NV21_LE_Rec709 = 117, 
                        YUV12_420_NV21_BE_Rec709 = 118, 
 
                        // -- Semi-planar 4:2:2 (NV16, Rec.709) --
                        YUV8_422_SemiPlanar_Rec709 = 119,     
                        YUV10_422_SemiPlanar_LE_Rec709 = 120, 
                        YUV10_422_SemiPlanar_BE_Rec709 = 121, 
                        YUV12_422_SemiPlanar_LE_Rec709 = 122, 
                        YUV12_422_SemiPlanar_BE_Rec709 = 123, 
 
                        // -- Planar 4:1:1 (Rec.709) --
                        YUV8_411_Planar_Rec709 = 124, 
 
                        // -- 16-bit YCbCr (Rec.709) --
                        YUV16_422_UYVY_LE_Rec709 = 125,       
                        YUV16_422_UYVY_BE_Rec709 = 126,       
                        YUV16_422_Planar_LE_Rec709 = 127,     
                        YUV16_422_Planar_BE_Rec709 = 128,     
                        YUV16_420_Planar_LE_Rec709 = 129,     
                        YUV16_420_Planar_BE_Rec709 = 130,     
                        YUV16_420_SemiPlanar_LE_Rec709 = 131, 
                        YUV16_420_SemiPlanar_BE_Rec709 = 132, 
                        YUV16_422_SemiPlanar_LE_Rec709 = 164, 
                        YUV16_422_SemiPlanar_BE_Rec709 = 165, 
 
                        // -- DPX additional packed formats --
                        RGB10_DPX_LE_sRGB = 133,  
                        YUV10_DPX_B_Rec709 = 134, 
 
                        // ----- Video codec compressed formats (QuickTime/MP4 family) ------------
                        H264 = 135,             
                        HEVC = 136,             
                        AV1 = 161,              
                        ProRes_422_Proxy = 137, 
                        ProRes_422_LT = 138,    
                        ProRes_422 = 139,       
                        ProRes_422_HQ = 140,    
                        ProRes_4444 = 141,      
                        ProRes_4444_XQ = 142,   
 
                        // -- Full-range uncompressed YCbCr --
                        //
                        // The library-wide YCbCr naming convention is that
                        // the unsuffixed form (e.g. YUV8_422_Rec709) is
                        // limited-range (16..235 Y, 16..240 Cb/Cr) to match
                        // broadcast / SDI / ST 2110 defaults.  The explicit
                        // "_Full" suffix opts in to full-range 0..255 Y and
                        // 0..255 Cb/Cr, which is what JPEG / JFIF uses and
                        // what most consumer video decoders (ffplay,
                        // browsers, libjpeg-turbo) expect.  These
                        // PixelFormats exist both as general-purpose
                        // full-range YCbCr storage and as encode-source
                        // intermediates for the full-range JPEG variants
                        // below.
                        YUV8_422_Rec709_Full = 143,        
                        YUV8_422_Rec601_Full = 144,        
                        YUV8_420_Planar_Rec709_Full = 145, 
                        YUV8_420_Planar_Rec601_Full = 146, 
 
                        // -- Full complement of JPEG YCbCr variants (matrix × range) --
                        //
                        // Following the library-wide YCbCr convention: the
                        // unsuffixed JPEG names (existing
                        // JPEG_YUV8_422_Rec709 / JPEG_YUV8_420_Rec709) are
                        // limited-range to stay consistent with the
                        // uncompressed YCbCr defaults.  Full-range variants
                        // take the explicit "_Full" suffix.  All eight
                        // combinations (matrix × range × subsampling) are
                        // provided; pick the one that matches what the
                        // downstream decoder expects to interpret:
                        //
                        //   - Rec.601 + full range (strict JFIF) → ffplay,
                        //     browsers, libjpeg-turbo, most consumer apps
                        //   - Rec.709 + full range → modern cameras with
                        //     an ICC profile; good for high-quality still
                        //     storage that a colour-managed viewer honours
                        //   - Rec.709 + limited range (existing default) →
                        //     broadcast / SDI JPEG pipelines (ST 2110 JPEG XS
                        //     style)
                        //   - Rec.601 + limited range → legacy broadcast
                        JPEG_YUV8_422_Rec601 =
                                147, 
                        JPEG_YUV8_420_Rec601 =
                                148, 
                        JPEG_YUV8_422_Rec709_Full =
                                149, 
                        JPEG_YUV8_420_Rec709_Full =
                                150, 
                        JPEG_YUV8_422_Rec601_Full =
                                151, 
                        JPEG_YUV8_420_Rec601_Full =
                                152, 
 
                        // -- JPEG XS (ISO/IEC 21122) compressed variants --
                        //
                        // Modern low-complexity intra-only codec.  JPEG XS
                        // carries matrix / range out-of-band (in the MP4 sample
                        // entry or RTP SDP — see RFC 9134) rather than inside
                        // the bitstream, so the compressed PixelFormats only
                        // distinguish bit depth and subsampling; Rec.709 is the
                        // canonical broadcast default and the one wired up
                        // here.  10- and 12-bit variants are first-class
                        // citizens since JPEG XS targets high-bit-depth
                        // contribution workflows.
                        JPEG_XS_YUV8_422_Rec709 =
                                153, 
                        JPEG_XS_YUV10_422_Rec709 =
                                154, 
                        JPEG_XS_YUV12_422_Rec709 =
                                155, 
                        JPEG_XS_YUV8_420_Rec709 =
                                156, 
                        JPEG_XS_YUV10_420_Rec709 =
                                157, 
                        JPEG_XS_YUV12_420_Rec709 =
                                158,             
                        JPEG_XS_RGB8_sRGB = 159, 
 
                        // -- Planar RGB --
                        RGB8_Planar_sRGB = 160, 
 
                        // -- Planar 4:4:4 YCbCr --
                        YUV8_444_Planar_Rec709 = 162,     
                        YUV10_444_Planar_LE_Rec709 = 163, 
 
                        UserDefined = 1024 
                };
 
                using IDList = ::promeki::List<ID>;
 
                struct CompSemantic {
                                String name;         
                                String abbrev;       
                                float  rangeMin = 0; 
                                float  rangeMax = 0; 
                };
 
                struct Data {
                                ID             id = Invalid;        
                                String         name;                
                                String         desc;                
                                PixelMemLayout memLayout;           
                                ColorModel     colorModel;          
                                bool           hasAlpha = false;    
                                int            alphaCompIndex = -1; 
                                bool           compressed = false;  
                                VideoCodec
                                        videoCodec; 
                                List<ID>     encodeSources; 
                                List<ID>     decodeTargets; 
                                FourCC::List fourccList;    
                                CompSemantic compSemantics[MaxComps] = {}; 
                                VideoRange
                                        videoRange; 
 
                                PaintEngine (*createPaintEngineFunc)(const Data                     *d,
                                                                     const UncompressedVideoPayload &payload) = nullptr;
                };
 
                static ID registerType();
 
                static void registerData(Data &&data);
 
                static IDList registeredIDs();
 
                static PixelFormat lookup(const String &name);
 
                static PixelFormat lookup(const String &name, Error *err);
 
                static Result<PixelFormat> fromString(const String &name) {
                        Error err;
                        PixelFormat p = lookup(name, &err);
                        if (err.isError()) return makeError<PixelFormat>(err);
                        return makeResult(p);
                }
 
                inline PixelFormat(ID id = Invalid);
 
                bool isValid() const { return d != nullptr && d->id != Invalid; }
 
                ID id() const { return d->id; }
 
                const String &name() const { return d->name; }
 
                String toString() const { return d->name; }
 
                const String &desc() const { return d->desc; }
 
                const PixelMemLayout &memLayout() const { return d->memLayout; }
 
                const ColorModel &colorModel() const { return d->colorModel; }
 
                VideoRange videoRange() const { return d->videoRange; }
 
                bool hasAlpha() const { return d->hasAlpha; }
 
                int alphaCompIndex() const { return d->alphaCompIndex; }
 
                bool isCompressed() const { return d->compressed; }
 
                const VideoCodec &videoCodec() const { return d->videoCodec; }
 
                const List<ID> &encodeSources() const { return d->encodeSources; }
 
                const List<ID> &decodeTargets() const { return d->decodeTargets; }
 
                const FourCC::List &fourccList() const { return d->fourccList; }
 
                size_t compCount() const { return d->memLayout.compCount(); }
 
                const CompSemantic &compSemantic(size_t index) const { return d->compSemantics[index]; }
 
                size_t planeCount() const { return d->memLayout.planeCount(); }
 
                // The following methods depend on proav types (ImageDesc, Image,
                // PaintEngine) — defined in pixelformat.cpp.
 
                size_t lineStride(size_t planeIndex, const ImageDesc &desc) const;
 
                size_t planeSize(size_t planeIndex, const ImageDesc &desc) const;
 
                PaintEngine createPaintEngine(const UncompressedVideoPayload &payload) const;
 
                bool hasPaintEngine() const { return d != nullptr && d->createPaintEngineFunc != nullptr; }
 
                bool operator==(const PixelFormat &o) const { return d == o.d; }
 
                bool operator!=(const PixelFormat &o) const { return d != o.d; }
 
                const Data *data() const { return d; }
 
        private:
                const Data        *d = nullptr;
                static const Data *lookupData(ID id);
};
 
inline PixelFormat::PixelFormat(ID id) : d(lookupData(id)) {}
 
PROMEKI_NAMESPACE_END
 
#endif // PROMEKI_ENABLE_PROAV