From a4cfaeb30de8b5540d6487adb1dcc03605adb91a Mon Sep 17 00:00:00 2001 From: Andrew Wrobel Date: Fri, 3 Dec 2021 12:57:23 -0700 Subject: [PATCH] [oneVPL] Update to oneVPL Spec v2.6 (#393) --- oneapi-doc.json | 2 +- releases/index.rst | 38 ++++++++ source/elements/oneVPL/Doxyfile | 2 +- .../elements/oneVPL/include/vpl/mfxcommon.h | 46 +++++++++- source/elements/oneVPL/include/vpl/mfxdefs.h | 6 +- .../oneVPL/include/vpl/mfxstructures.h | 91 +++++++++++++++---- .../oneVPL/include/vpl/mfxsurfacepool.h | 2 +- source/elements/oneVPL/include/vpl/mfxvideo.h | 28 ++++-- .../oneVPL/source/API_ref/VPL_defines.rst | 3 + .../source/API_ref/VPL_disp_api_def.rst | 2 +- .../source/API_ref/VPL_disp_api_struct.rst | 8 ++ .../oneVPL/source/API_ref/VPL_enums.rst | 74 ++++++++++++++- .../oneVPL/source/API_ref/VPL_ref_types.rst | 3 + .../elements/oneVPL/source/Experimental.rst | 48 ++++++++++ .../elements/oneVPL/source/VPL_change_log.rst | 28 ++++++ .../oneVPL/source/VPL_deprecation.rst | 47 +++++++++- source/elements/oneVPL/source/index.rst | 1 + .../programming_guide/VPL_prg_session.rst | 24 +++-- .../source/programming_guide/VPL_prg_vpp.rst | 2 - source/elements/oneVPL/vplapi.py | 53 +++++------ 20 files changed, 429 insertions(+), 79 deletions(-) create mode 100644 source/elements/oneVPL/source/Experimental.rst diff --git a/oneapi-doc.json b/oneapi-doc.json index 2705d01531..2616bf8f0a 100644 --- a/oneapi-doc.json +++ b/oneapi-doc.json @@ -1,5 +1,5 @@ { "version": "1.1-rev-1", - "vpl_version": "2.5.0", + "vpl_version": "2.6.0", "art_version": "1.0-rev-1" } diff --git a/releases/index.rst b/releases/index.rst index 24735cd2b6..c80c41a2ba 100644 --- a/releases/index.rst +++ b/releases/index.rst @@ -306,6 +306,9 @@ oneVPL * - Version - Date - View + * - `oneVPL v2.6.0`_ + - 2021-12-3 + - `HTML `__ * - `oneVPL v2.5.0`_ - 2021-8-30 - `HTML `__ @@ -319,6 +322,41 @@ oneVPL Release Notes ------------- +oneVPL v2.6.0 +~~~~~~~~~~~~~ + +New in this release: + +* New development practice to treat some new API features as + experimental was introduced. + All new experimental API is wrapped with ONE_EXPERIMENTAL macro. +* Experimental API: introduced MFX_HANDLE_PXP_CONTEXT to support + protected content. +* Experimental API: introduced CPUEncToolsProcessing hint to run + adaptive encoding tools on CPU. +* Experimental API: extended device ID reporting to cover + multi-adapter cases. +* Experimental API: introduced common alias for mfxExtAVCRefListCtrl +* Experimental API: mfxExtDecodeErrorReport ErrorTypes enum extended + with new JPEG/MJPEG decode error report. +* Clarified LowPower flag meaning. +* Described that mfxExtThreadsParam can be attached to + mfxInitializationParam during session initialization. +* Refined description of the MFXVideoDECODE_VPP_DecodeFrameAsync + function. +* New dispatcher's config filter property: MediaAdapterType. +* Marked all deprecated fields as MFX_DEPRECATED. +* Introduced priority loading option for custom libraries. +* Clarified AV1 encoder behavior about writing of IVF headers. +* Removed outdated note about loading priority of |msdk_full_name|. + For loading details see + :ref:`onevpl_coexistense`. +* Spelled out mfxVariant type usage for strings. +* New product names for platforms: + + * Code name DG2, + * Code name ATS-M. + oneVPL v2.5.0 ~~~~~~~~~~~~~ diff --git a/source/elements/oneVPL/Doxyfile b/source/elements/oneVPL/Doxyfile index d0918afcd0..5d325ad7fc 100644 --- a/source/elements/oneVPL/Doxyfile +++ b/source/elements/oneVPL/Doxyfile @@ -2193,7 +2193,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = MFX_CDECL= MFX_DEPRECATED= +PREDEFINED = MFX_CDECL= MFX_DEPRECATED= ONEVPL_EXPERIMENTAL # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/source/elements/oneVPL/include/vpl/mfxcommon.h b/source/elements/oneVPL/include/vpl/mfxcommon.h index 849243870a..171a86b372 100644 --- a/source/elements/oneVPL/include/vpl/mfxcommon.h +++ b/source/elements/oneVPL/include/vpl/mfxcommon.h @@ -161,12 +161,13 @@ enum { MFX_PACK_BEGIN_USUAL_STRUCT() /*! Specifies options for threads created by this session. Attached to the - mfxInitParam structure during legacy Intel(r) Media SDK session initialization. */ + mfxInitParam structure during legacy Intel(r) Media SDK session initialization + or to mfxInitializationParam by the dispatcher in MFXCreateSession function. */ typedef struct { mfxExtBuffer Header; /*!< Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_THREADS_PARAM. */ mfxU16 NumThread; /*!< The number of threads. */ - mfxI32 SchedulingType; /*!< Scheduling policy for all threads. */ + mfxI32 SchedulingType; /*!< Scheduling policy for all threads.*/ mfxI32 Priority; /*!< Priority for all threads. */ mfxU16 reserved[55]; /*!< Reserved for future use. */ } mfxExtThreadsParam; @@ -197,6 +198,8 @@ enum { MFX_PLATFORM_ALDERLAKE_P = 44, /*!< Code name Alder Lake P. */ MFX_PLATFORM_ARCTICSOUND_P = 45, MFX_PLATFORM_XEHP_SDV = 45, /*!< Code name XeHP SDV. */ + MFX_PLATFORM_DG2 = 46, /*!< Code name DG2. */ + MFX_PLATFORM_ATS_M = 46, /*!< Code name ATS-M, same media functionality as DG2. */ MFX_PLATFORM_KEEMBAY = 50, /*!< Code name Keem Bay. */ }; @@ -459,14 +462,51 @@ typedef struct { } mfxImplementedFunctions; MFX_PACK_END() +#ifdef ONEVPL_EXPERIMENTAL + +#define MFX_EXTENDEDDEVICEID_VERSION MFX_STRUCT_VERSION(1, 0) + +MFX_PACK_BEGIN_USUAL_STRUCT() +/*! Specifies variouse physical device properties for device matching and identification outside of oneVPL. */ +typedef struct { + mfxStructVersion Version; /*!< Version of the structure. */ + mfxU16 VendorID; /*!< PCI vendor ID. */ + mfxU16 DeviceID; /*!< PCI device ID. */ + mfxU32 PCIDomain; /*!< PCI bus domain. Equals to '0' if OS doesn't support it or + has sequential numbering of buses accross domains. */ + mfxU32 PCIBus; /*!< The number of the bus that the physical device is located on. */ + mfxU32 PCIDevice; /*!< The index of the physical device on the bus. */ + mfxU32 PCIFunction; /*!< The function number of the device on the physical device. */ + mfxU8 DeviceLUID[8]; /*!< LUID of DXGI adapter. */ + mfxU32 LUIDDeviceNodeMask; /*!< Bitfield identifying the node within a linked + device adapter corresponding to the device. */ + mfxU32 LUIDValid; /*!< Boolean value that will be 1 if DeviceLUID contains a valid LUID + and LUIDDeviceNodeMask contains a valid node mask, + and 0 if they do not. */ + mfxU32 DRMRenderNodeNum; /*!< Number of the DRM render node from the path /dev/dri/RenderD. + Value equals to 0 means that this field doesn't contain valid DRM Render + Node number.*/ + mfxU32 DRMPrimaryNodeNum; /*!< Number of the DRM primary node from the path /dev/dri/card. + Value equals to 0x7FFFFFFF means that this field doesn't contain valid DRM Primary + Node number.*/ + mfxU8 reserved1[20]; /*!< Reserved for future use. */ + mfxChar DeviceName[MFX_STRFIELD_LEN]; /*!< Null-terminated string in utf-8 with the name of the device. */ +} mfxExtendedDeviceId; +MFX_PACK_END() + +#endif /* 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_IMPLPATH = 3 /*!< Deliver pointer to the null-terminated string with the path to the + 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. */ +#ifdef ONEVPL_EXPERIMENTAL + MFX_IMPLCAPS_DEVICE_ID_EXTENDED = 4 /*!< Deliver extended device ID information as mfxExtendedDeviceId + structure.*/ +#endif } mfxImplCapsDeliveryFormat; MFX_PACK_BEGIN_STRUCT_W_PTR() diff --git a/source/elements/oneVPL/include/vpl/mfxdefs.h b/source/elements/oneVPL/include/vpl/mfxdefs.h index 2295ab328a..e31c6f4bc7 100644 --- a/source/elements/oneVPL/include/vpl/mfxdefs.h +++ b/source/elements/oneVPL/include/vpl/mfxdefs.h @@ -8,7 +8,7 @@ #define __MFXDEFS_H__ #define MFX_VERSION_MAJOR 2 -#define MFX_VERSION_MINOR 5 +#define MFX_VERSION_MINOR 6 // 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 @@ -208,7 +208,7 @@ typedef enum { } mfxVariantType; MFX_PACK_BEGIN_STRUCT_W_PTR() -/*! The mfxVariantType enumerator data types for mfxVarianf type. */ +/*! The mfxVariantType enumerator data types for mfxVariant type. */ typedef struct { mfxStructVersion Version; /*!< Version of the structure. */ mfxVariantType Type; /*!< Value type. */ @@ -224,7 +224,7 @@ typedef struct { mfxI64 I64; /*!< mfxI64 data. */ mfxF32 F32; /*!< mfxF32 data. */ mfxF64 F64; /*!< mfxF64 data. */ - mfxHDL Ptr; /*!< Pointer. */ + mfxHDL Ptr; /*!< Pointer. When this points to a string the string must be null terminated. */ } Data; /*!< Value data member. */ } mfxVariant; MFX_PACK_END() diff --git a/source/elements/oneVPL/include/vpl/mfxstructures.h b/source/elements/oneVPL/include/vpl/mfxstructures.h index 6b0b2f9025..4f45fc3f82 100644 --- a/source/elements/oneVPL/include/vpl/mfxstructures.h +++ b/source/elements/oneVPL/include/vpl/mfxstructures.h @@ -128,7 +128,7 @@ enum { MFX_FOURCC_RGB565 = MFX_MAKEFOURCC('R','G','B','2'), /*!< 2 bytes per pixel, uint16 in little-endian format, where 0-4 bits are blue, bits 5-10 are green and bits 11-15 are red. */ /*! RGB 24 bit planar layout (3 separate channels, 8-bits per sample each). This format should be mapped to D3DFMT_R8G8B8 or VA_FOURCC_RGBP. */ MFX_FOURCC_RGBP = MFX_MAKEFOURCC('R','G','B','P'), - MFX_FOURCC_RGB3 = MFX_MAKEFOURCC('R','G','B','3'), /* Deprecated */ + MFX_DEPRECATED_ENUM_FIELD_INSIDE(MFX_FOURCC_RGB3) = MFX_MAKEFOURCC('R','G','B','3'), /* Deprecated. */ MFX_FOURCC_RGB4 = MFX_MAKEFOURCC('R','G','B','4'), /*!< RGB4 (RGB32) color planes. BGRA is the order, ‘B’ is 8 MSBs, then 8 bits for ‘G’ channel, then ‘R’ and ‘A’ channels. */ /*! Internal color format. The application should use the following functions to create a surface that corresponds to the Direct3D* version in use. @@ -353,6 +353,9 @@ typedef enum { MFX_HANDLE_VA_CONTEXT_ID = 7, /*!< Pointer to VAContextID interface. It represents external VA context for Common Encryption usage model. */ MFX_HANDLE_CM_DEVICE = 8, /*!< Pointer to CmDevice interface ( Intel(r) C for Metal Runtime ). */ MFX_HANDLE_HDDLUNITE_WORKLOADCONTEXT = 9, /*!< Pointer to HddlUnite::WorkloadContext interface. */ +#ifdef ONEVPL_EXPERIMENTAL + MFX_HANDLE_PXP_CONTEXT = 10, /*!< Pointer to PXP context for protected content support. */ +#endif } mfxHandleType; /*! The mfxMemoryFlags enumerator specifies memory access mode. */ @@ -616,7 +619,7 @@ MFX_PACK_BEGIN_USUAL_STRUCT() typedef struct { mfxU32 reserved[7]; /*!< Reserved for future use. */ - /*! For encoders, set this flag to ON to reduce power consumption and GPU usage. See the CodingOptionValue enumerator for values + /*! Hint to enable low power consumption mode for encoders. See the CodingOptionValue enumerator for values of this option. Use the Query API function to check if this feature is supported. */ mfxU16 LowPower; /*! Specifies a multiplier for bitrate control parameters. Affects the following variables: InitialDelayInKB, BufferSizeInKB, @@ -1166,7 +1169,7 @@ typedef struct { mfxU16 MECostType; /*!< Motion estimation cost type. This value is reserved and must be zero. */ mfxU16 MESearchType; /*!< Motion estimation search algorithm. This value is reserved and must be zero. */ mfxI16Pair MVSearchWindow; /*!< Rectangular size of the search window for motion estimation. This parameter is reserved and must be (0, 0). */ - mfxU16 EndOfSequence; /* Deprecated */ + MFX_DEPRECATED mfxU16 EndOfSequence; /* Deprecated */ mfxU16 FramePicture; /*!< Set this flag to encode interlaced fields as interlaced frames. This flag does not affect progressive input frames. See the CodingOptionValue enumerator for values of this option. */ mfxU16 CAVLC; /*!< If set, CAVLC is used; if unset, CABAC is used for encoding. See the CodingOptionValue enumerator for values of this option. */ @@ -1228,7 +1231,7 @@ typedef struct { mfxU16 MaxDecFrameBuffering; /*!< Specifies the maximum number of frames buffered in a DPB. A value of zero means unspecified. */ mfxU16 AUDelimiter; /*!< Set this flag to insert the Access Unit Delimiter NAL. See the CodingOptionValue enumerator for values of this option. */ - mfxU16 EndOfStream; /* Deprecated */ + MFX_DEPRECATED mfxU16 EndOfStream; /* Deprecated */ /*! Set this flag to insert the picture timing SEI with pic_struct syntax element. See sub-clauses D.1.2 and D.2.2 of the ISO/IEC 14496-10 specification for the definition of this syntax element. See the CodingOptionValue enumerator for values of this option. @@ -1693,7 +1696,7 @@ typedef struct { mfxU16 EnableNalUnitType; union { - mfxU16 ExtBrcAdaptiveLTR; /* Deprecated */ + MFX_DEPRECATED mfxU16 ExtBrcAdaptiveLTR; /* Deprecated */ /*! If this flag is set to ON, encoder will mark, modify, or remove LTR frames based on encoding parameters and content @@ -1715,7 +1718,19 @@ typedef struct { If this flag is set to OFF, regular reference frames are used for encoding. */ mfxU16 AdaptiveRef; + +#ifdef ONEVPL_EXPERIMENTAL + /*! + The tri-state option specifies hint for the library to execute encoding tools processing on CPU. + It may give better encoding quality, but leads to higher CPU utilization. + The library can ignore MFX_CODINGOPTION_ON if processing on CPU is not supported. + */ + mfxU16 CPUEncToolsProcessing; + mfxU16 reserved[160]; +#else mfxU16 reserved[161]; +#endif + } mfxExtCodingOption3; MFX_PACK_END() @@ -1786,9 +1801,9 @@ enum { The application can attach this buffer to the mfxVideoParam structure for video processing initialization. */ MFX_EXTBUFF_VPP_DENOISE2 = MFX_MAKEFOURCC('D','N','I','2'), - MFX_EXTBUFF_VPP_DENOISE = MFX_MAKEFOURCC('D','N','I','S'), /*!< Deprecated in 2.2 API version.*/ - MFX_EXTBUFF_VPP_SCENE_ANALYSIS = MFX_MAKEFOURCC('S','C','L','Y'), - MFX_EXTBUFF_VPP_SCENE_CHANGE = MFX_EXTBUFF_VPP_SCENE_ANALYSIS, /* Deprecated */ + MFX_DEPRECATED_ENUM_FIELD_INSIDE(MFX_EXTBUFF_VPP_DENOISE) = MFX_MAKEFOURCC('D','N','I','S'), /*!< Deprecated in 2.2 API version.*/ + MFX_EXTBUFF_VPP_SCENE_ANALYSIS = MFX_MAKEFOURCC('S','C','L','Y'), /*!< Reserved for future use. */ + MFX_DEPRECATED_ENUM_FIELD_INSIDE(MFX_EXTBUFF_VPP_SCENE_CHANGE) = MFX_EXTBUFF_VPP_SCENE_ANALYSIS, /* Deprecated. */ /*! The extended buffer defines control parameters for the VPP ProcAmp filter algorithm. See the mfxExtVPPProcAmp structure for details. The application can attach this buffer to the mfxVideoParam structure for video processing initialization or to the mfxFrameData @@ -2124,6 +2139,14 @@ enum { See the mfxExtTemporalLayers structure for more details. */ MFX_EXTBUFF_UNIVERSAL_TEMPORAL_LAYERS = MFX_MAKEFOURCC('U', 'T', 'M', 'P'), +#ifdef ONEVPL_EXPERIMENTAL + /*! + This extended buffer defines additional encoding controls for reference list. See the mfxExtRefListCtrl structure for details. + The application can attach this buffer to the mfxVideoParam structure for encoding & decoding initialization, or + the mfxEncodeCtrl structure for per-frame encoding configuration. + */ + MFX_EXTBUFF_UNIVERSAL_REFLIST_CTRL = MFX_EXTBUFF_AVC_REFLIST_CTRL, +#endif /*! See the mfxExtVPP3DLut structure for more details. */ @@ -2355,8 +2378,8 @@ typedef struct { union{ struct{ - mfxU32 SpatialComplexity; /* Deprecated */ - mfxU32 TemporalComplexity; /* Deprecated */ + MFX_DEPRECATED mfxU32 SpatialComplexity; /* Deprecated */ + MFX_DEPRECATED mfxU32 TemporalComplexity; /* Deprecated */ }; struct{ /*! @@ -2368,8 +2391,8 @@ typedef struct { mfxU16 reserved[3]; }; }; - mfxU16 SceneChangeRate; /* Deprecated */ - mfxU16 RepeatedFrame; /* Deprecated */ + MFX_DEPRECATED mfxU16 SceneChangeRate; /* Deprecated */ + MFX_DEPRECATED mfxU16 RepeatedFrame; /* Deprecated */ } mfxExtVppAuxData; MFX_PACK_END() @@ -3616,14 +3639,38 @@ MFX_PACK_END() /*! The ErrorTypes enumerator uses bit-ORed values to itemize bitstream error types. */ enum { - MFX_ERROR_NO = 0, /*!< No error in bitstream. */ - MFX_ERROR_PPS = (1 << 0), /*!< Invalid/corrupted PPS. */ - MFX_ERROR_SPS = (1 << 1), /*!< Invalid/corrupted SPS. */ - MFX_ERROR_SLICEHEADER = (1 << 2), /*!< Invalid/corrupted slice header. */ - MFX_ERROR_SLICEDATA = (1 << 3), /*!< Invalid/corrupted slice data. */ - MFX_ERROR_FRAME_GAP = (1 << 4), /*!< Missed frames. */ + MFX_ERROR_NO = 0, /*!< No error in bitstream. */ + MFX_ERROR_PPS = (1 << 0), /*!< Invalid/corrupted PPS. */ + MFX_ERROR_SPS = (1 << 1), /*!< Invalid/corrupted SPS. */ + MFX_ERROR_SLICEHEADER = (1 << 2), /*!< Invalid/corrupted slice header. */ + MFX_ERROR_SLICEDATA = (1 << 3), /*!< Invalid/corrupted slice data. */ + MFX_ERROR_FRAME_GAP = (1 << 4), /*!< Missed frames. */ +#ifdef ONEVPL_EXPERIMENTAL + MFX_ERROR_JPEG_APP0_MARKER = (1 << 5), /*!< Invalid/corrupted APP0 marker. */ + MFX_ERROR_JPEG_APP1_MARKER = (1 << 6), /*!< Invalid/corrupted APP1 marker. */ + MFX_ERROR_JPEG_APP2_MARKER = (1 << 7), /*!< Invalid/corrupted APP2 marker. */ + MFX_ERROR_JPEG_APP3_MARKER = (1 << 8), /*!< Invalid/corrupted APP3 marker. */ + MFX_ERROR_JPEG_APP4_MARKER = (1 << 9), /*!< Invalid/corrupted APP4 marker. */ + MFX_ERROR_JPEG_APP5_MARKER = (1 << 10), /*!< Invalid/corrupted APP5 marker. */ + MFX_ERROR_JPEG_APP6_MARKER = (1 << 11), /*!< Invalid/corrupted APP6 marker. */ + MFX_ERROR_JPEG_APP7_MARKER = (1 << 12), /*!< Invalid/corrupted APP7 marker. */ + MFX_ERROR_JPEG_APP8_MARKER = (1 << 13), /*!< Invalid/corrupted APP8 marker. */ + MFX_ERROR_JPEG_APP9_MARKER = (1 << 14), /*!< Invalid/corrupted APP9 marker. */ + MFX_ERROR_JPEG_APP10_MARKER = (1 << 15), /*!< Invalid/corrupted APP10 marker. */ + MFX_ERROR_JPEG_APP11_MARKER = (1 << 16), /*!< Invalid/corrupted APP11 marker. */ + MFX_ERROR_JPEG_APP12_MARKER = (1 << 17), /*!< Invalid/corrupted APP12 marker. */ + MFX_ERROR_JPEG_APP13_MARKER = (1 << 18), /*!< Invalid/corrupted APP13 marker. */ + MFX_ERROR_JPEG_APP14_MARKER = (1 << 19), /*!< Invalid/corrupted APP14 marker. */ + MFX_ERROR_JPEG_DQT_MARKER = (1 << 20), /*!< Invalid/corrupted DQT marker. */ + MFX_ERROR_JPEG_SOF0_MARKER = (1 << 21), /*!< Invalid/corrupted SOF0 marker. */ + MFX_ERROR_JPEG_DHT_MARKER = (1 << 22), /*!< Invalid/corrupted DHT marker. */ + MFX_ERROR_JPEG_DRI_MARKER = (1 << 23), /*!< Invalid/corrupted DRI marker. */ + MFX_ERROR_JPEG_SOS_MARKER = (1 << 24), /*!< Invalid/corrupted SOS marker. */ + MFX_ERROR_JPEG_UNKNOWN_MARKER = (1 << 25), /*!< Unknown Marker. */ +#endif }; + MFX_PACK_BEGIN_USUAL_STRUCT() /*! Used by the decoders to report bitstream error information right after DecodeHeader or DecodeFrameAsync. @@ -3889,6 +3936,10 @@ typedef mfxExtAVCRefListCtrl mfxExtHEVCRefListCtrl; typedef mfxExtAVCRefLists mfxExtHEVCRefLists; typedef mfxExtAvcTemporalLayers mfxExtHEVCTemporalLayers; +#ifdef ONEVPL_EXPERIMENTAL +typedef mfxExtAVCRefListCtrl mfxExtRefListCtrl; +#endif + /* The MirroringType enumerator itemizes mirroring types. */ enum { @@ -4357,7 +4408,9 @@ MFX_PACK_BEGIN_USUAL_STRUCT() typedef struct { mfxExtBuffer Header; /*!< Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_AV1_BITSTREAM_PARAM. */ - mfxU16 WriteIVFHeaders; /*!< Tri-state option to control IVF headers insertion, default is ON. */ + mfxU16 WriteIVFHeaders; /*!< Tri-state option to control IVF headers insertion, default is ON. + Writing IVF headers is enabled in the encoder when mfxExtAV1BitstreamParam is attached and its value is ON or zero. + Writing IVF headers is disabled by default in the encoder when mfxExtAV1BitstreamParam is not attached. */ mfxU16 reserved[31]; } mfxExtAV1BitstreamParam; diff --git a/source/elements/oneVPL/include/vpl/mfxsurfacepool.h b/source/elements/oneVPL/include/vpl/mfxsurfacepool.h index 0a2bed0ef4..a8908a6228 100644 --- a/source/elements/oneVPL/include/vpl/mfxsurfacepool.h +++ b/source/elements/oneVPL/include/vpl/mfxsurfacepool.h @@ -37,7 +37,7 @@ typedef struct { */ mfxU32 DeltaToAllocateOnTheFly; union { - mfxVPPPoolType VPPPoolType; /*!< Defines what VPP pool is targeted - input or output. Ignored for other components. */ + mfxVPPPoolType VPPPoolType; /*!< Defines what VPP pool is targeted - input or ouput. Ignored for other components. */ mfxU32 reserved; }; mfxU32 Wait; /*!< Time in milliseconds for GetSurfaceForXXX() and DecodeFrameAsync functions to wait until surface will be available. */ diff --git a/source/elements/oneVPL/include/vpl/mfxvideo.h b/source/elements/oneVPL/include/vpl/mfxvideo.h index c8f4c64ab7..9852ff13bc 100755 --- a/source/elements/oneVPL/include/vpl/mfxvideo.h +++ b/source/elements/oneVPL/include/vpl/mfxvideo.h @@ -769,8 +769,8 @@ mfxStatus MFX_CDECL MFXVideoDECODE_GetPayload(mfxSession session, mfxU64 *ts, mf MFX_WRN_DEVICE_BUSY Hardware device is currently busy. Call this function again after MFXVideoCORE_SyncOperation or in a few milliseconds. \n MFX_WRN_VIDEO_PARAM_CHANGED The decoder detected a new sequence header in the bitstream. Video parameters may have changed. \n MFX_ERR_INCOMPATIBLE_VIDEO_PARAM The decoder detected incompatible video parameters in the bitstream and failed to follow them. \n - MFX_ERR_REALLOC_SURFACE Bigger surface_work required. May be returned only if mfxInfoMFX::EnableReallocRequest was set to ON during initialization. - MFX_WRN_ALLOC_TIMEOUT_EXPIRED Timeout expired for internal output frame allocation (if set with mfxExtAllocationHints and NULL passed as surface_work). Repeat the call in a few milliseconds or re-initialize decoder with higher surface limit. \n + MFX_ERR_REALLOC_SURFACE Bigger surface_work required. May be returned only if mfxInfoMFX::EnableReallocRequest was set to ON during initialization. \n + MFX_WRN_ALLOC_TIMEOUT_EXPIRED Timeout expired for internal output frame allocation (if set with mfxExtAllocationHints and NULL passed as surface_work). Repeat the call in a few milliseconds or re-initialize decoder with higher surface limit. @since This function is available since API version 1.0. */ @@ -987,10 +987,12 @@ mfxStatus MFX_CDECL MFXVideoVPP_ProcessFrameAsync(mfxSession session, mfxFrameSu /*! @brief - Initialize the SDK in (decode + vpp) mode. The logic of this function is similar to MFXVideoDECODE_Init, but application has to provide array of pointers to mfxVideoChannelParam and num_channel_param - number of channels. Application is responsible for + Initialize the SDK in (decode + vpp) mode. The logic of this function is similar to MFXVideoDECODE_Init, + but application has to provide array of pointers to mfxVideoChannelParam and num_channel_param - number of channels. Application is responsible for memory allocation for mfxVideoChannelParam parameters and for each channel it should specify channel IDs: - mfxVideoChannelParam::mfxFrameInfo::ChannelId. ChannelId should be unique value within one session. - The application can attach mfxExtInCrops to mfxVideoChannelParam::ExtParam to annotate input video frame if it wants to enable + mfxVideoChannelParam::mfxFrameInfo::ChannelId. ChannelId should be unique value within one session. ChannelID equals to the 0 + is reserved for the orginal decoded frame. + The application can attach mfxExtInCrops to mfxVideoChannelParam::ExtParam to annotate input video frame if it wants to enable letterboxing operation. @param[in] session SDK session handle. @param[in] decode_par Pointer to the mfxVideoParam structure which contains initialization parameters for decoder. @@ -1013,11 +1015,17 @@ mfxStatus MFX_CDECL MFXVideoDECODE_VPP_Init(mfxSession session, mfxVideoParam* /*! @brief - This function is similar to MFXVideoDECODE_DecodeFrameAsync and inherits all bitstream processing logic. As output it allocates - and returns array of processed surfaces according to the chain of filters specified by applicaton in MFXVideoDECODE_VPP_Init. The - original decoded frames are returned through surfaces with mfxFrameInfo::ChannelId == 0. In other words, zero - ChannelId is reserved by the SDK for decoded output and cannot be used by application to set video processing channels during - initialization. + This function is similar to MFXVideoDECODE_DecodeFrameAsync and inherits all bitstream processing logic. As output, + it allocates and returns @p surf_array_out array of processed surfaces according to the chain of filters specified + by application in MFXVideoDECODE_VPP_Init, including original decoded frames. In the @p surf_array_out, the original + decoded frames are returned through surfaces with mfxFrameInfo::ChannelId == 0, followed by each of the subsequent + frame surfaces for each of the requested mfxVideoChannelParam entries provided to the MFXVideoCECODE_VPP_Init + function. At maximum, the number of frame surfaces return is 1 + the value of @p num_vpp_par to the + MFXVideoDECODE_VPP_Init function, but the application must be prepared to the case when some particular filters + are not ready to output surfaces, so the length of @p surf_array_out will be less. Application should use + mfxFrameInfo::ChannelId parameter to match output surface against configured filter. + + An application must synchronize each output surface from the @p surf_array_out surface array independently. @param[in] session SDK session handle. @param[in] bs Pointer to the input bitstream. diff --git a/source/elements/oneVPL/source/API_ref/VPL_defines.rst b/source/elements/oneVPL/source/API_ref/VPL_defines.rst index b1de92232c..7ab5c1b117 100644 --- a/source/elements/oneVPL/source/API_ref/VPL_defines.rst +++ b/source/elements/oneVPL/source/API_ref/VPL_defines.rst @@ -61,4 +61,7 @@ API .. doxygendefine::MFX_POOLPOLICYDESCRIPTION_VERSION :project: oneVPL + +.. doxygendefine::MFX_EXTENDEDDEVICEID_VERSION + :project: oneVPL diff --git a/source/elements/oneVPL/source/API_ref/VPL_disp_api_def.rst b/source/elements/oneVPL/source/API_ref/VPL_disp_api_def.rst index a7b9198ed9..4565beaae6 100644 --- a/source/elements/oneVPL/source/API_ref/VPL_disp_api_def.rst +++ b/source/elements/oneVPL/source/API_ref/VPL_disp_api_def.rst @@ -59,4 +59,4 @@ MFX_UPDATE_PROPERTY_U16 MFX_UPDATE_PROPERTY_PTR ----------------------- .. doxygendefine:: MFX_UPDATE_PROPERTY_PTR - :project: oneVPL + :project: oneVPL \ No newline at end of file diff --git a/source/elements/oneVPL/source/API_ref/VPL_disp_api_struct.rst b/source/elements/oneVPL/source/API_ref/VPL_disp_api_struct.rst index 1376528535..cd70dab15b 100644 --- a/source/elements/oneVPL/source/API_ref/VPL_disp_api_struct.rst +++ b/source/elements/oneVPL/source/API_ref/VPL_disp_api_struct.rst @@ -83,6 +83,14 @@ mfxImplementedFunctions :members: :protected-members: +mfxExtendedDeviceId +------------------- + +.. doxygenstruct:: mfxExtendedDeviceId + :project: oneVPL + :members: + :protected-members: + mfxPoolPolicyDescription ------------------------ diff --git a/source/elements/oneVPL/source/API_ref/VPL_enums.rst b/source/elements/oneVPL/source/API_ref/VPL_enums.rst index 09d10e8bf7..3b5192ccf7 100644 --- a/source/elements/oneVPL/source/API_ref/VPL_enums.rst +++ b/source/elements/oneVPL/source/API_ref/VPL_enums.rst @@ -789,6 +789,69 @@ The ErrorTypes enumerator uses bit-ORed values to itemize bitstream error types. .. doxygenenumvalue:: MFX_ERROR_FRAME_GAP :project: oneVPL +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP0_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP1_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP2_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP3_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP4_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP5_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP6_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP7_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP8_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP9_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP10_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP11_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP12_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP13_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_APP14_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_DQT_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_SOF0_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_DHT_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_DRI_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_SOS_MARKER + :project: oneVPL + +.. doxygenenumvalue:: MFX_ERROR_JPEG_UNKNOWN_MARKER + :project: oneVPL + .. _extendedbufferid: ---------------- @@ -813,9 +876,6 @@ extended buffers or video processing algorithm identifiers. .. doxygenenumvalue:: MFX_EXTBUFF_VPP_AUXDATA :project: oneVPL -.. doxygenenumvalue:: MFX_EXTBUFF_VPP_DENOISE - :project: oneVPL - .. doxygenenumvalue:: MFX_EXTBUFF_VPP_DENOISE2 :project: oneVPL @@ -1044,6 +1104,8 @@ extended buffers or video processing algorithm identifiers. .. doxygenenumvalue:: MFX_EXTBUFF_UNIVERSAL_TEMPORAL_LAYERS :project: oneVPL +.. doxygenenumvalue:: MFX_EXTBUFF_UNIVERSAL_REFLIST_CTRL + :project: oneVPL ---------------- ExtMemBufferType @@ -1885,6 +1947,12 @@ PlatformCodeName .. doxygenenumvalue:: MFX_PLATFORM_XEHP_SDV :project: oneVPL +.. doxygenenumvalue:: MFX_PLATFORM_DG2 + :project: oneVPL + +.. doxygenenumvalue:: MFX_PLATFORM_ATS_M + :project: oneVPL + .. doxygenenumvalue:: MFX_PLATFORM_KEEMBAY :project: oneVPL diff --git a/source/elements/oneVPL/source/API_ref/VPL_ref_types.rst b/source/elements/oneVPL/source/API_ref/VPL_ref_types.rst index f01fdd2412..76165c37f0 100644 --- a/source/elements/oneVPL/source/API_ref/VPL_ref_types.rst +++ b/source/elements/oneVPL/source/API_ref/VPL_ref_types.rst @@ -77,3 +77,6 @@ Typedefs .. doxygentypedef:: mfxSyncPoint :project: oneVPL + +.. doxygentypedef:: mfxExtRefListCtrl + :project: oneVPL \ No newline at end of file diff --git a/source/elements/oneVPL/source/Experimental.rst b/source/elements/oneVPL/source/Experimental.rst new file mode 100644 index 0000000000..4fef6ec5f4 --- /dev/null +++ b/source/elements/oneVPL/source/Experimental.rst @@ -0,0 +1,48 @@ +.. SPDX-FileCopyrightText: 2021 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +======================= +oneVPL Experimental API +======================= + +All API entries defined under the ONEVPL_EXPERIMENTAL macro are considered as +expiremental. Backward compatibility is not guaranteed for these features. +Future presense is not guaranteed as well. + +By default, experimental API is turned off in the header files. To enable +it, need to define ONEVPL_EXPERIMENTAL macro during the application +compilation stage. + +The following is a list of experimental interfaces, starting from API version +2.6. + + +.. list-table:: Experimental API + :header-rows: 1 + :widths: auto + + * - **Experimental API** + - **Added in API Version** + - **Removed in API Version** + - **Removal Reason** + * - :cpp:struct:`mfxExtendedDeviceId` + - 2.6 + - + - + * - :cpp:member:`mfxExtCodingOption3::CPUEncToolsProcessing` + - 2.6 + - + - + * - :cpp:type:`mfxExtRefListCtrl` + - 2.6 + - + - + * - Extended enum for :cpp:member:`mfxExtDecodeErrorReport::ErrorTypes` + - 2.6 + - + - + * - :cpp:enumerator:`mfxHandleType::MFX_HANDLE_PXP_CONTEXT` + - 2.6 + - + - diff --git a/source/elements/oneVPL/source/VPL_change_log.rst b/source/elements/oneVPL/source/VPL_change_log.rst index 73a2a1c751..49474a7848 100644 --- a/source/elements/oneVPL/source/VPL_change_log.rst +++ b/source/elements/oneVPL/source/VPL_change_log.rst @@ -12,6 +12,34 @@ This section describes the API evolution from version to version. :local: :depth: 1 +----------- +Version 2.6 +----------- + +New in this release: + +* New development practice to treat some new API features as experimental was introduced. + All new experimental API is wrapped with ONE_EXPERIMENTAL macro. +* Experimental API: introduced MFX_HANDLE_PXP_CONTEXT to support protected content. +* Experimental API: introduced CPUEncToolsProcessing hint to run adaptive encoding tools on CPU. +* Experimental API: extended device ID reporting to cover multi-adapter cases. +* Experimental API: introduced common alias for mfxExtAVCRefListCtrl +* Experimental API: mfxExtDecodeErrorReport ErrorTypes enum extended with new JPEG/MJPEG decode error report. +* Clarified LowPower flag meaning. +* Described that mfxExtThreadsParam can be attached to mfxInitializationParam during session initialization. +* Refined description of the MFXVideoDECODE_VPP_DecodeFrameAsync function. +* New dispatcher's config filter property: MediaAdapterType. +* Marked all deprecated fields as MFX_DEPRECATED. +* Introduced priority loading option for custom libraries. +* Clarified AV1 encoder behavior about writing of IVF headers. +* Removed outdated note about loading priority of |msdk_full_name|. For loading details see + :ref:`onevpl_coexistense`. +* Spelled out mfxVariant type usage for strings. +* New product names for platforms: + + * Code name DG2, + * Code name ATS-M. + ----------- Version 2.5 ----------- diff --git a/source/elements/oneVPL/source/VPL_deprecation.rst b/source/elements/oneVPL/source/VPL_deprecation.rst index db2c78de91..0a975658f3 100644 --- a/source/elements/oneVPL/source/VPL_deprecation.rst +++ b/source/elements/oneVPL/source/VPL_deprecation.rst @@ -32,4 +32,49 @@ The following is a list of deprecated interfaces, starting from API version 2.0. - 2.5 - - Use :cpp:struct:`mfxExtVPPDenoise2` - - No change \ No newline at end of file + - No change + * - :cpp:enumerator:`MFX_FOURCC_RGB3` + - 2.0 + - + - Use :cpp:enumerator:`MFX_FOURCC_RGB4` + - No change + * - :cpp:member:`mfxExtCodingOption::EndOfSequence` + - 2.0 + - + - Flag is ignored + - No change + * - :cpp:member:`mfxExtCodingOption::EndOfStream` + - 2.0 + - + - Flag is ignored + - No change + * - :cpp:member:`mfxExtCodingOption3::ExtBrcAdaptiveLTR` + - 2.4 + - + - Use :cpp:member:`mfxExtCodingOption3::AdaptiveLTR` + - No change + * - :cpp:enumerator:`MFX_EXTBUFF_VPP_SCENE_CHANGE` + - 2.0 + - + - Ignored + - No change + * - :cpp:member:`mfxExtVppAuxData::SpatialComplexity` + - 2.0 + - + - Field is not filled by the library + - No change + * - :cpp:member:`mfxExtVppAuxData::TemporalComplexity` + - 2.0 + - + - Field is not filled by the library + - No change + * - :cpp:member:`mfxExtVppAuxData::SceneChangeRate` + - 2.0 + - + - Field is not filled by the library + - No change + * - :cpp:member:`mfxExtVppAuxData::RepeatedFrame` + - 2.0 + - + - Field is not filled by the library + - No change diff --git a/source/elements/oneVPL/source/index.rst b/source/elements/oneVPL/source/index.rst index 3cbd14dc9d..c93a35ea15 100644 --- a/source/elements/oneVPL/source/index.rst +++ b/source/elements/oneVPL/source/index.rst @@ -31,6 +31,7 @@ Latest published version of oneVPL specification: ``. @@ -204,11 +210,6 @@ Internally, the dispatcher works as follows: :ref:`Exported Functions/API Version table ` for the list of functions to export. -.. note:: For backward compatibility with |msdk_full_name|, the dispatcher will - first try to load |msdk_full_name| if API version 1.x was requested. - If loading fails, the dispatcher will search for the implementation with - highest 2.x API version and load that version. - ------------------------------------------ oneVPL Dispatcher Configuration Properties ------------------------------------------ @@ -268,6 +269,11 @@ left to right from column to column and concatenate strings by using `.` (dot) a | | | .device | | | | | | .DeviceID | | | | +----------------------------+----------------------+---------------------------+ + | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | | + | | | .mfxDeviceDescription | | | + | | | .device | | | + | | | .MediaAdapterType | | | + | +----------------------------+----------------------+---------------------------+ | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | | | | .mfxDecoderDescription | | | | | | .decoder | | | @@ -419,7 +425,7 @@ left to right from column to column and concatenate strings by using `.` (dot) a | | | | | IDXGIFactory::EnumAdapters| +---------------------------------------+----------------------------+----------------------+---------------------------+ -.. important:: DXGIAdapterNum property is available for Windows only and filters only hardware implementations. +.. important:: DXGIAdapterIndex property is available for Windows only and filters only hardware implementations. Examples of the property name strings: @@ -443,6 +449,8 @@ influence on the implementation selection. They are used during the - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_U32` * - :cpp:type:`mfxHDL` - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_PTR` + * - :cpp:type:`NumThread` + - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_U32` ------------------------------ oneVPL Dispatcher Interactions @@ -743,8 +751,6 @@ VPP filter. * - **Filter ID** - **Description** - * - :cpp:enumerator:`MFX_EXTBUFF_VPP_DENOISE` - - Denoise filter (deprecated in 2.2) * - :cpp:enumerator:`MFX_EXTBUFF_VPP_DENOISE2` - Denoise filter * - :cpp:enumerator:`MFX_EXTBUFF_VPP_MCTF` @@ -801,6 +807,8 @@ shared library: :end-before: /*end5*/ :lineno-start: 1 +.. _onevpl_coexistense: + ----------------------------------------------------------------------------------------------------------- oneVPL implementation on |intel_r| platforms with X\ :sup:`e` architecture and |msdk_full_name| Coexistence ----------------------------------------------------------------------------------------------------------- diff --git a/source/elements/oneVPL/source/programming_guide/VPL_prg_vpp.rst b/source/elements/oneVPL/source/programming_guide/VPL_prg_vpp.rst index 6bb8a079a7..60c3584bd6 100644 --- a/source/elements/oneVPL/source/programming_guide/VPL_prg_vpp.rst +++ b/source/elements/oneVPL/source/programming_guide/VPL_prg_vpp.rst @@ -93,8 +93,6 @@ list of configurable filters. * - **Filter ID** - **Configuration Structure** - * - :cpp:enumerator:`MFX_EXTBUFF_VPP_DENOISE` - - :cpp:struct:`mfxExtVPPDenoise` * - :cpp:enumerator:`MFX_EXTBUFF_VPP_DENOISE2` - :cpp:struct:`mfxExtVPPDenoise2` * - :cpp:enumerator:`MFX_EXTBUFF_VPP_MCTF` diff --git a/source/elements/oneVPL/vplapi.py b/source/elements/oneVPL/vplapi.py index 552ac02a2c..ef47c99f0d 100644 --- a/source/elements/oneVPL/vplapi.py +++ b/source/elements/oneVPL/vplapi.py @@ -39,32 +39,33 @@ def check_definition_list_item(def_node): return None def process_function_nodes(app, doctree, fromdocname): - for section in doctree.traverse(nodes.section, descend=True): - for n in section: - type_of_section = type_of_node(n) - if type_of_section == 'title': - title_text = n[0] - if(title_text.startswith("MFX")): # this is function description section - # lets search for the `Since` term - isFunction = False - hasVersion = False - version = None - functionName = title_text - for k in n.traverse(condition=None, include_self=True, descend=True, siblings=True): - node_type = type_of_node(k) - if node_type == 'desc': - if k.hasattr('desctype'): - if k.get('desctype') == 'function': - isFunction = True - else: - continue - if node_type == 'definition_list_item': - tmp = check_definition_list_item(k) - if tmp: - version = tmp - hasVersion = True - if isFunction and not hasVersion: - logger.warning("Function {} doesn't have min API version defined".format(functionName)) + if fromdocname.find("VPL_") >= 0: + for section in doctree.traverse(nodes.section, descend=True): + for n in section: + type_of_section = type_of_node(n) + if type_of_section == 'title': + title_text = n[0] + if(title_text.startswith("MFX")): # this is function description section + # lets search for the `Since` term + isFunction = False + hasVersion = False + version = None + functionName = title_text + for k in n.traverse(condition=None, include_self=True, descend=True, siblings=True): + node_type = type_of_node(k) + if node_type == 'desc': + if k.hasattr('desctype'): + if k.get('desctype') == 'function': + isFunction = True + else: + continue + if node_type == 'definition_list_item': + tmp = check_definition_list_item(k) + if tmp: + version = tmp + hasVersion = True + if isFunction and not hasVersion: + logger.warning("Function {} doesn't have min API version defined".format(functionName)) def setup(app): app.connect('doctree-resolved', process_function_nodes)