oneVPL Spec update to version 2.4 (#329)

Co-authored-by: Igor Belyakov <[email protected]>

Author: akwrobel

oneapi-doc.json

@@ -1,5 +1,5 @@
 {
     "version": "1.1-provisional-rev-1",
-    "vpl_version": "2.3.1",
+    "vpl_version": "2.4.0",
     "art_version": "0.5-rev-1"
 }

source/elements/oneVPL/include/vpl/mfxcommon.h

@@ -431,7 +431,10 @@ MFX_PACK_END()
 /* The mfxImplCapsDeliveryFormat enumerator specifies delivery format of the implementation capability. */
 typedef enum {
     MFX_IMPLCAPS_IMPLDESCSTRUCTURE       = 1,  /*!< Deliver capabilities as mfxImplDescription structure. */
-    MFX_IMPLCAPS_IMPLEMENTEDFUNCTIONS    = 2   /*!< Deliver capabilities as mfxImplementedFunctions structure. */
+    MFX_IMPLCAPS_IMPLEMENTEDFUNCTIONS    = 2,  /*!< Deliver capabilities as mfxImplementedFunctions structure. */
+    MFX_IMPLCAPS_IMPLPATH                = 3   /*!< Deliver pointer to the null-terminated string with the path to the
+                                                    implementation. String is delivered in a form of buffer of
+                                                    mfxChar type. */
 } mfxImplCapsDeliveryFormat;
 
 MFX_PACK_BEGIN_STRUCT_W_PTR()

source/elements/oneVPL/include/vpl/mfxdefs.h

@@ -1,5 +1,5 @@
 /*############################################################################
-  # Copyright (C) 2019-2020 Intel Corporation
+  # Copyright (C) 2019-2021 Intel Corporation
   #
   # SPDX-License-Identifier: MIT
   ############################################################################*/
@@ -8,7 +8,7 @@
 #define __MFXDEFS_H__
 
 #define MFX_VERSION_MAJOR 2
-#define MFX_VERSION_MINOR 3
+#define MFX_VERSION_MINOR 4
 
 // MFX_VERSION - version of API that 'assumed' by build may be provided externally
 // if it omitted then latest stable API derived from Major.Minor is assumed
@@ -176,20 +176,35 @@ MFX_PACK_END()
 
 #define MFX_VARIANT_VERSION MFX_STRUCT_VERSION(1, 0)
 
-/*! The mfxVariantType enumerator data types for mfxVarianf type. */
+/*! The mfxDataType enumerates data type for mfxDataType. */
+typedef enum {
+    MFX_DATA_TYPE_UNSET   = 0,            /*!< Undefined type. */
+    MFX_DATA_TYPE_U8,                     /*!< 8-bit unsigned integer. */
+    MFX_DATA_TYPE_I8,                     /*!< 8-bit signed integer. */
+    MFX_DATA_TYPE_U16,                    /*!< 16-bit unsigned integer. */
+    MFX_DATA_TYPE_I16,                    /*!< 16-bit signed integer. */
+    MFX_DATA_TYPE_U32,                    /*!< 32-bit unsigned integer. */
+    MFX_DATA_TYPE_I32,                    /*!< 32-bit signed integer. */
+    MFX_DATA_TYPE_U64,                    /*!< 64-bit unsigned integer. */
+    MFX_DATA_TYPE_I64,                    /*!< 64-bit signed integer. */
+    MFX_DATA_TYPE_F32,                    /*!< 32-bit single precision floating point. */
+    MFX_DATA_TYPE_F64,                    /*!< 64-bit double precision floating point. */
+}mfxDataType;
+
+/*! The mfxVariantType enumerator data types for mfxVariantType. */
 typedef enum {
-    MFX_VARIANT_TYPE_UNSET = 0, /*!< Undefined type. */
-    MFX_VARIANT_TYPE_U8 = 1,   /*!< 8-bit unsigned integer. */
-    MFX_VARIANT_TYPE_I8,       /*!< 8-bit signed integer. */
-    MFX_VARIANT_TYPE_U16,      /*!< 16-bit unsigned integer. */
-    MFX_VARIANT_TYPE_I16,      /*!< 16-bit signed integer. */
-    MFX_VARIANT_TYPE_U32,      /*!< 32-bit unsigned integer. */
-    MFX_VARIANT_TYPE_I32,      /*!< 32-bit signed integer. */
-    MFX_VARIANT_TYPE_U64,      /*!< 64-bit unsigned integer. */
-    MFX_VARIANT_TYPE_I64,      /*!< 64-bit signed integer. */
-    MFX_VARIANT_TYPE_F32,      /*!< 32-bit single precision floating point. */
-    MFX_VARIANT_TYPE_F64,      /*!< 64-bit double precision floating point. */
-    MFX_VARIANT_TYPE_PTR,      /*!< Generic type pointer. */
+    MFX_VARIANT_TYPE_UNSET = MFX_DATA_TYPE_UNSET,                        /*!< Undefined type. */
+    MFX_VARIANT_TYPE_U8    = MFX_DATA_TYPE_U8,                           /*!< 8-bit unsigned integer. */
+    MFX_VARIANT_TYPE_I8    = MFX_DATA_TYPE_I8,                           /*!< 8-bit signed integer. */
+    MFX_VARIANT_TYPE_U16   = MFX_DATA_TYPE_U16,                          /*!< 16-bit unsigned integer. */
+    MFX_VARIANT_TYPE_I16   = MFX_DATA_TYPE_I16,                          /*!< 16-bit signed integer. */
+    MFX_VARIANT_TYPE_U32   = MFX_DATA_TYPE_U32,                          /*!< 32-bit unsigned integer. */
+    MFX_VARIANT_TYPE_I32   = MFX_DATA_TYPE_I32,                          /*!< 32-bit signed integer. */
+    MFX_VARIANT_TYPE_U64   = MFX_DATA_TYPE_U64,                          /*!< 64-bit unsigned integer. */
+    MFX_VARIANT_TYPE_I64   = MFX_DATA_TYPE_I64,                          /*!< 64-bit signed integer. */
+    MFX_VARIANT_TYPE_F32   = MFX_DATA_TYPE_F32,                          /*!< 32-bit single precision floating point. */
+    MFX_VARIANT_TYPE_F64   = MFX_DATA_TYPE_F64,                          /*!< 64-bit double precision floating point. */
+    MFX_VARIANT_TYPE_PTR,                                                /*!< Generic type pointer. */
 } mfxVariantType;
 
 MFX_PACK_BEGIN_STRUCT_W_PTR()
@@ -294,6 +309,17 @@ typedef enum
 } mfxStatus;
 
 
+MFX_PACK_BEGIN_USUAL_STRUCT()
+/*! Represents Globally Unique Identifier (GUID) with memory layout 
+    compliant to RFC 4122. See https://www.rfc-editor.org/info/rfc4122 for details. */
+typedef struct
+{
+    mfxU8 Data[16]; /*!< Array to keep GUID. */
+} mfxGUID;
+MFX_PACK_END()
+
+
+
 // Application
 #if defined(MFX_DISPATCHER_EXPOSED_PREFIX)
 

source/elements/oneVPL/include/vpl/mfxdispatcher.h

@@ -27,7 +27,7 @@ typedef struct _mfxConfig *mfxConfig;
 
    @since This function is available since API version 2.0.
 */
-mfxLoader MFX_CDECL MFXLoad();
+mfxLoader MFX_CDECL MFXLoad(void);
 
 /*!
    @brief Destroys the dispatcher.
@@ -65,66 +65,6 @@ mfxConfig MFX_CDECL MFXCreateConfig(mfxLoader loader);
           @note Each new call with the same parameter name will overwrite the previously set value. This may invalidate other properties.
           @note Each new call with another parameter name will delete the previous property and create a new property based on new name's value.
 
-          Simple usage example:
-          @code
-             mfxLoader loader = MFXLoad();
-             mfxConfig cfg = MFXCreateConfig(loader);
-             mfxVariant ImplValue;
-             ImplValue.Type = MFX_VARIANT_TYPE_U32;
-             ImplValue.Data.U32 = MFX_IMPL_TYPE_HARDWARE;
-             MFXSetConfigFilterProperty(cfg,"mfxImplDescription.Impl",ImplValue);
-             MFXCreateSession(loader,0,&session);
-          @endcode
-
-          Usage example with two sessions (multiple loaders):
-          @code
-             // Create session with software based implementation
-             mfxLoader loader1 = MFXLoad();
-             mfxConfig cfg1 = MFXCreateConfig(loader1);
-             mfxVariant ImplValueSW;
-             ImplValueSW.Type = MFX_VARIANT_TYPE_U32;
-             ImplValueSW.Data.U32 = MFX_IMPL_TYPE_SOFTWARE;
-             MFXSetConfigFilterProperty(cfg1,"mfxImplDescription.Impl",ImplValueSW);
-             MFXCreateSession(loader1,0,&sessionSW);
-
-             // Create session with hardware based implementation
-             mfxLoader loader2 = MFXLoad();
-             mfxConfig cfg2 = MFXCreateConfig(loader2);
-             mfxVariant ImplValueHW;
-             ImplValueHW.Type = MFX_VARIANT_TYPE_U32;
-             ImplValueHW.Data.U32 = MFX_IMPL_TYPE_HARDWARE;
-             MFXSetConfigFilterProperty(cfg2,"mfxImplDescription.Impl",ImplValueHW);
-             MFXCreateSession(loader2,0,&sessionHW);
-
-             // use both sessionSW and sessionHW
-             // ...
-             // Close everything
-             MFXClose(sessionSW);
-             MFXClose(sessionHW);
-             MFXUnload(loader1); // cfg1 will be destroyed here.
-             MFXUnload(loader2); // cfg2 will be destroyed here.
-          @endcode
-
-          Usage example with two decoders (multiple config objects):
-          @code
-             mfxLoader loader = MFXLoad();
-
-             mfxConfig cfg1 = MFXCreateConfig(loader);
-             mfxVariant ImplValue;
-             val.Type = MFX_VARIANT_TYPE_U32;
-             val.Data.U32 = MFX_CODEC_AVC;
-             MFXSetConfigFilterProperty(cfg1,"mfxImplDescription.mfxDecoderDescription.decoder.CodecID",ImplValue);
-
-             mfxConfig cfg2 = MFXCreateConfig(loader);
-             mfxVariant ImplValue;
-             val.Type = MFX_VARIANT_TYPE_U32;
-             val.Data.U32 = MFX_CODEC_HEVC;
-             MFXSetConfigFilterProperty(cfg2,"mfxImplDescription.mfxDecoderDescription.decoder.CodecID",ImplValue);
-
-             MFXCreateSession(loader,0,&sessionAVC);
-             MFXCreateSession(loader,0,&sessionHEVC);
-          @endcode
-
    @param[in] config Config handle.
    @param[in] name Name of the parameter (see mfxImplDescription structure and example).
    @param[in] value Value of the parameter.

source/elements/oneVPL/include/vpl/mfxstructures.h

@@ -166,6 +166,8 @@ enum {
     MFX_FOURCC_I010         = MFX_MAKEFOURCC('I', '0', '1', '0'), /*!< 10-bit YUV 4:2:0, each component has its own plane. */
     MFX_FOURCC_I420         = MFX_FOURCC_IYUV,                 /*!< Alias for the IYUV color format. */
     MFX_FOURCC_BGRA         = MFX_FOURCC_RGB4,                 /*!< Alias for the RGB4 color format. */
+    /*! BGR 24 bit planar layout (3 separate channels, 8-bits per sample each). This format should be mapped to VA_FOURCC_BGRP. */
+    MFX_FOURCC_BGRP         = MFX_MAKEFOURCC('B','G','R','P'),
 };
 
 /* PicStruct */
@@ -567,8 +569,27 @@ typedef struct mfxFrameSurfaceInterface {
 
     */
     void               (MFX_CDECL *OnComplete)(mfxStatus sts);
+    
+   /*! @brief
+    Returns an interface defined by the GUID. If the returned interface is a reference 
+    counted object the caller should release the obtained interface to avoid memory leaks.
 
-    mfxHDL              reserved2[3];
+    @param[in]  surface   Valid surface.
+    @param[in]  guid      GUID of the requested interface.
+    @param[out] iface     Interface.
+
+
+    @return
+     MFX_ERR_NONE               If no error. \n
+     MFX_ERR_NULL_PTR           If interface or surface is NULL. \n
+     MFX_ERR_UNSUPPORTED        If requested interface is not supported. \n
+     MFX_ERR_NOT_IMPLEMENTED    If requested interface is not implemented. \n
+     MFX_ERR_NOT_INITIALIZED    If requested interface is not available (not created or already deleted). \n
+     MFX_ERR_UNKNOWN            Any internal error.
+    */
+    mfxStatus           (MFX_CDECL *QueryInterface)(mfxFrameSurface1* surface, mfxGUID guid, mfxHDL* iface); 
+
+    mfxHDL              reserved2[2];
 } mfxFrameSurfaceInterface;
 MFX_PACK_END()
 
@@ -1663,12 +1684,16 @@ typedef struct {
        @note Not all codecs and implementations support this value. Use the Query API function to check if this feature is supported.
     */
     mfxU16      EnableNalUnitType;
-    /*!
-       Turn OFF to prevent Adaptive marking of Long Term Reference Frames when using ExtBRC. When set to ON and using ExtBRC, encoders will mark,
-       modify, or remove LTR frames based on encoding parameters and content properties. The application must set each input frame's
-       mfxFrameData::FrameOrder for correct operation of LTR.
-    */
-    mfxU16      ExtBrcAdaptiveLTR;         /* Tri-state option for ExtBRC. */
+
+    union {
+        mfxU16      ExtBrcAdaptiveLTR; /* Deprecated */
+        
+        /*!
+            If this flag is set to ON, encoder will mark, modify, or remove LTR frames based on encoding parameters and content          
+            properties. Turn OFF to prevent Adaptive marking of Long Term Reference Frames. 
+        */
+        mfxU16      AdaptiveLTR;
+    };
     /*!
        If this flag is set to ON, encoder adaptively selects one of implementation-defined quantization matrices for each frame.
        Non-default quantization matrices aim to improve subjective visual quality under certain conditions.
@@ -1677,8 +1702,13 @@ typedef struct {
        This parameter is valid only during initialization.
     */
     mfxU16      AdaptiveCQM;
-
-    mfxU16      reserved[162];
+    /*!
+       If this flag is set to ON, encoder adaptively selects list of reference frames to imrove encoding quality.
+       Enabling of the flag can increase computation complexity and introduce additional delay.
+       If this flag is set to OFF, regular reference frames are used for encoding.
+    */
+    mfxU16      AdaptiveRef;
+    mfxU16      reserved[161];
 } mfxExtCodingOption3;
 MFX_PACK_END()
 
@@ -2033,7 +2063,12 @@ enum {
     /*!
        See the mfxExtHyperModeParam structure for more details.
     */
-    MFX_EXTBUFF_HYPER_MODE_PARAM = MFX_MAKEFOURCC('H', 'Y', 'P', 'M')
+    MFX_EXTBUFF_HYPER_MODE_PARAM = MFX_MAKEFOURCC('H', 'Y', 'P', 'M'),
+
+    /*!
+       See the mfxExtVPP3DLut structure for more details.
+    */
+    MFX_EXTBUFF_VPP_3DLUT = MFX_MAKEFOURCC('T','D','L','T'),
 };
 
 /* VPP Conf: Do not use certain algorithms  */
@@ -2091,6 +2126,94 @@ typedef struct {
 } mfxExtVPPDenoise2;
 MFX_PACK_END()
 
+/*! The mfx3DLutChannelMapping enumerator specifies the channel mapping of 3DLUT. */
+typedef enum {
+    MFX_3DLUT_CHANNEL_MAPPING_DEFAULT            = 0,   /*!< Default 3DLUT channel mapping. The library selects the most appropriate 3DLUT channel mapping. */
+    MFX_3DLUT_CHANNEL_MAPPING_RGB_RGB            = 1,   /*!< 3DLUT RGB channels map to RGB channels. */
+    MFX_3DLUT_CHANNEL_MAPPING_YUV_RGB            = 2,   /*!< 3DLUT YUV channels map to RGB channels. */
+    MFX_3DLUT_CHANNEL_MAPPING_VUY_RGB            = 3,   /*!< 3DLUT VUY channels map to RGB channels. */
+} mfx3DLutChannelMapping;
+
+/*! The mfx3DLutMemoryLayout enumerator specifies the memory layout of 3DLUT. */
+typedef enum {
+    MFX_3DLUT_MEMORY_LAYOUT_DEFAULT                        = 0,          /*!< Default 3DLUT memory layout. The library selects the most appropriate 3DLUT memory layout.*/
+
+    MFX_3DLUT_MEMORY_LAYOUT_VENDOR                         = 0x1000,     /*!< The enumeration to separate default above and vendor specific.*/
+    /*!
+       Intel specific memory layout. The enumerator indicates the attributes and memory layout of 3DLUT.
+       3DLUT size is 17(the number of elements per dimension), 4 channels(3 valid channels, 1 channel is reserved), every channel must be 16-bit unsigned integer.
+       3DLUT contains 17x17x32 entries with holes that are not filled. Take RGB as example, the nodes RxGx17 to RxGx31 are not filled, are "don't care" bits, and not accessed for the 17x17x17 nodes.
+    */
+    MFX_3DLUT_MEMORY_LAYOUT_INTEL_17LUT                    = MFX_3DLUT_MEMORY_LAYOUT_VENDOR + 1,
+    /*!
+       Intel specific memory layout. The enumerator indicates the attributes and memory layout of 3DLUT.
+       3DLUT size is 33(the number of elements per dimension), 4 channels(3 valid channels, 1 channel is reserved), every channel must be 16-bit unsigned integer.
+       3DLUT contains 33x33x64 entries with holes that are not filled. Take RGB as example, the nodes RxGx33 to RxGx63 are not filled, are "don't care" bits, and not accessed for the 33x33x33 nodes.
+    */
+    MFX_3DLUT_MEMORY_LAYOUT_INTEL_33LUT                    = MFX_3DLUT_MEMORY_LAYOUT_VENDOR + 2,
+    /*!
+       Intel specific memory layout. The enumerator indicates the attributes and memory layout of 3DLUT.
+       3DLUT size is 65(the number of elements per dimension), 4 channels(3 valid channels, 1 channel is reserved), every channel must be 16-bit unsigned integer.
+       3DLUT contains 65x65x128 entries with holes that are not filled. Take RGB as example, the nodes RxGx65 to RxGx127 are not filled, are "don't care" bits, and not accessed for the 65x65x65 nodes.
+    */
+    MFX_3DLUT_MEMORY_LAYOUT_INTEL_65LUT                    = MFX_3DLUT_MEMORY_LAYOUT_VENDOR + 3,
+} mfx3DLutMemoryLayout;
+
+MFX_PACK_BEGIN_STRUCT_W_PTR()
+/*!
+    A hint structure that configures the data channel.
+*/
+typedef struct {
+    mfxDataType  DataType;                /*!< Data type, mfxDataType enumerator.*/
+    mfxU32       Size;                    /*!< Size of Look up table, the number of elements per dimension.*/
+    union
+    {
+        mfxU8*     Data;                  /*!< The pointer to 3DLUT data, 8 bit unsigned integer.*/
+        mfxU16*    Data16;                /*!< The pointer to 3DLUT data, 16 bit unsigned integer.*/
+    };
+    mfxU32       reserved[4];             /*!< Reserved for future extension.*/
+} mfxChannel;
+MFX_PACK_END()
+
+MFX_PACK_BEGIN_USUAL_STRUCT()
+/*!
+    A hint structure that configures 3DLUT system buffer.
+*/
+typedef struct {
+    mfxChannel           Channel[3];        /*!< 3 Channels, can be RGB or YUV, mfxChannel structure.*/
+    mfxU32               reserved[8];       /*!< Reserved for future extension.*/
+} mfx3DLutSystemBuffer;
+MFX_PACK_END()
+
+MFX_PACK_BEGIN_USUAL_STRUCT()
+/*!
+    A hint structure that configures 3DLUT video buffer.
+*/
+typedef struct {
+    mfxDataType                DataType;       /*!< Data type, mfxDataType enumerator.*/
+    mfx3DLutMemoryLayout       MemLayout;      /*!< Indicates 3DLUT memory layout. mfx3DLutMemoryLayout enumerator.*/
+    mfxMemId                   MemId;          /*!< Memory ID for holding the lookup table data. One MemID is dedicated for one instance of VPP.*/
+    mfxU32                     reserved[8];    /*!< Reserved for future extension.*/
+} mfx3DLutVideoBuffer;
+MFX_PACK_END()
+
+MFX_PACK_BEGIN_USUAL_STRUCT()
+/*!
+    A hint structure that configures 3DLUT filter.
+*/
+typedef struct {
+    mfxExtBuffer             Header;           /*!< Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_VPP_3DLUT..*/
+    mfx3DLutChannelMapping   ChannelMapping;   /*!< Indicates 3DLUT channel mapping. mfx3DLutChannelMapping enumerator.*/
+    mfxResourceType          BufferType;       /*!< Indicates 3DLUT buffer type. mfxResourceType enumerator, can be system memory, VA surface, DX11 texture/buffer etc.*/
+    union
+    {
+        mfx3DLutSystemBuffer SystemBuffer;     /*!< The 3DLUT system buffer. mfx3DLutSystemBuffer structure describes the details of the buffer.*/
+        mfx3DLutVideoBuffer  VideoBuffer;      /*!< The 3DLUT video buffer. mfx3DLutVideoBuffer describes the details of 3DLUT video buffer.*/
+    };
+    mfxU32                   reserved[4];      /*!< Reserved for future extension.*/
+} mfxExtVPP3DLut;
+MFX_PACK_END()
+
 MFX_PACK_BEGIN_USUAL_STRUCT()
 /*!
    A hint structure that configures the VPP detail/edge enhancement filter algorithm.