Release 2021.6.0

New in This Release
===================

* Updated dispatcher and CPU runtime to API 2.5
* Internal memory support added to dpcpp-blur sample

For more information on the preview C++/Python APIs and Samples, see
https://software.intel.com/content/www/us/en/develop/articles/onevpl-preview-examples.html

oneVPL 2021.6.0 has been updated to include functional and security
updates. Users should update to the latest version.

Issues and Limitations
======================
* On Ubuntu 20.04, during basekit install you may see a warning about
  missing OpenCL support.  You can verify the graphics stack components
  are correctly installed by running one of the interop samples with
  -hw.  See https://github.com/oneapi-src/oneVPL for more information.

C++/Python previews
-------------------
* This is a preview release made available to gather feedback for API
  improvements.  Compatibility with future releases is not

Dispatcher
----------
* In multi-adapter configurations with a mix of legacy and Xe GPUs, only
  the oneVPL implementation will be loaded.  This means legacy MSDK
  device(s) cannot be used in this scenario.  In this case oneVPL
  applications should target only the Xe device(s).  If an application
  must target both, use Media SDK dispatcher and choose the default
  runtime to load with the INTEL_MEDIA_RUNTIME environment variable.
  See the [Media SDK
  Readme](https://github.com/Intel-Media-SDK/MediaSDK/blob/master/README.rst#intel-media-sdk)
  for more information.
* Builds of oneVPL from source assume single configuration generators on
  Linux and multi configuration generators on Windows.
* MFXInit() and MFXInitEx() functions have been deprecated in the 2.0
  oneVPL Specification.  Use MFXLoad() instead.  See the transition
  guide for more details.
* If initialized with MFXInit() or MFXInitEx(), support is limited to
  the 1.x API and will load Intel(R) Media SDK hardware library rather
  than oneVPL hardware library.
* If both Intel(R) Media SDK and oneVPL hardware libraries are
  installed, only oneVPL libraries will be loaded via MFXLoad(). See the
  oneVPL specification for more details.
* The Media SDK runtimes enabling legacy GPU hardware only provide API
  features up to 1.35, even when initialized with MFXLoad.  For more
  details, see [Upgrading from Intel® Media SDK to Intel® oneAPI Video
  Processing
  Library](https://software.intel.com/content/www/us/en/develop/articles/upgrading-from-msdk-to-onevpl.html).
* The libmfx.dll and libmfx.so.2021.1.11 dispatchers are
  deprecated. They are provided for backwards compatibility only and
  will be removed from a future release.  They do not include any
  changes since the 2021.1.1 release.
* Dispatcher support has been extended to include hardware
  implementations, including those that implement API versions lower
  then 2.0. Applications patterned after the 2021.1.1 release samples,
  rather than the 2.0 specification may fail after re-build as the
  previous sample code made the assumption that 2.0 APIs would be
  available. To remedy this please follow the coding patterns in the
  [oneVPL
  spec](https://spec.oneapi.com/versions/latest/elements/oneVPL/source/API_ref/VPL_disp_api_func.html#_CPPv47MFXLoadv)

Tools and samples
-----------------
* Releases installed prior to the 2.4 API update may cause CMAKE build
  failures on Linux due to compatibility issues.  Prior package versions
  were aligned with release version, rather than API.  As a result
  find_package will look for a current version i.e. 2.4 but find a
  larger legacy usage i.e. 2021.2.2 and assume forward compatibility.
* decvpp_tool requires the graphics stack installed even when in CPU
  only mode.
* sample_decode may not finish with multi-resolution input in external
  memory mode with CPU runtime.
* sample_encode does not work in case of enabled VPP and internal memory
  allocator.
* legacy-vpp sample in hardware mode is not supported on Sky Lake.
* decvpp_tool does not support gen12 platforms on Windows in Hardware mode.
* Encode B-frame distance setting is inconsistent between CPU and GPU
  implementations. For the CPU implementation 0 means no B-frames, while
  for the GPU implementation 1 means no B-frames.
* Colorspace flags are required when using sample_* tools, if colorspace
  is not set tools will fail.
* The sample_multi_transcode tool included in this release is only
  intended for GPU operation to remain more closely aligned with the
  version of this tool released with Intel(R) Media SDK.
* The sample_multi_transcode tool has a synchronization issue in 1->N
  pipelines. When decode is faster than encoders, the issue can cause
  the free frames consumed faster than the framework released,
  eventually resulting in tool crash when there is no more memory
  available.
* hello-transcode sample only supports the oneVPL CPU implementation in
  this release.
* sample_decode may stop responding if the input is switched between
  multiple resolutions.
* sample_encode software mode does not support NV12 as the input color
  format. Use i420 with the "i420" argument since NV12 is the default
  format.
* sample_encode occasionally hangs for (CPU) SVT-HEVC encodes when using
  VBR in Ubuntu 18.04.
* sample_encode does not support preprocess commands for scaling or
  color conversion.
* sample_encode, sample_decode, and sample_vpp are not in sync with
  Media SDK's version of these tools.  This will be corrected in future
  releases.
* Windows samples are installed to C:\Program
  Files (x86)\Intel\oneAPI\vpl\latest\examples by default. This should
  not be a writable location, so you will not be able to build samples
  here.  To build examples, copy this folder to another location first.

Author: mav-intel

CMakeLists.txt

@@ -78,6 +78,9 @@ include(cmake/oneAPIInstallDirs.cmake)
 # Keep executable bits on shared objects when installing regardless of distro
 set(CMAKE_INSTALL_SO_NO_EXE 0)
 
+# Directory for tools specific helper libraries
+set(_TOOLS_LIB_PATH "${CMAKE_INSTALL_FULL_LIBDIR}/${PROJECT_NAME}")
+
 include(cmake/CompileOptions.cmake)
 
 if(BUILD_TESTS)
@@ -117,6 +120,8 @@ if(USE_ONEAPI_INSTALL_LAYOUT)
 endif()
 
 include(cmake/PackageTarget.cmake)
+set(CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT runtime)
+include(InstallRequiredSystemLibraries)
 
 message(
   STATUS "---------------- Configuration summary ------------------------------"

README.md

@@ -1,4 +1,4 @@
-# oneAPI Video Processing Library
+# ![oneAPI](assets/oneapi-logo.png "oneAPI") Video Processing Library
 
 The oneAPI Video Processing Library (oneVPL) provides a single video processing
 API for encode, decode, and video processing that works across a wide range of
@@ -11,9 +11,9 @@ This repository contains the following components of oneVPL:
 - Examples demonstrating API usage
 - oneVPL command line tools
 
-This project is part of the larger [oneAPI](https://www.oneapi.com/) project.
-See the [oneAPI Specification](https://spec.oneapi.com) and the
-[oneVPL Specification](https://spec.oneapi.com/versions/latest/elements/oneVPL/source/index.html) for additional information.
+This project is part of the larger [oneAPI](https://www.oneapi.io/) project.
+See the [oneAPI Specification](https://spec.oneapi.io) and the
+[oneVPL Specification](https://spec.oneapi.io/versions/latest/elements/oneVPL/source/index.html) for additional information.
 
 The version of the oneVPL API is listed in the
 [mfxdefs.h](./api/vpl/mfxdefs.h) file.
@@ -23,10 +23,9 @@ The version of the oneVPL API is listed in the
 You can install oneVPL:
 
 - from [oneVPL home page](https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/onevpl.html) as a part of Intel® oneAPI Base Toolkit.
+- from source code.  See [Installation from Sources](INSTALL.md) for details.
 
-### Installation from Source 
-See [Installation from Sources](INSTALL.md) for details.
-
+For more details on installation options and procedures, see the [Intel® oneAPI Video Processing Library Installation Guide](https://software.intel.com/content/www/us/en/develop/articles/onevpl-installation-guide.html).
 
 ## Developer Usage
 
@@ -52,6 +51,9 @@ Add the following code to your CMakeLists, assuming TARGET is defined as the
 component that wants to use oneVPL:
 
 ```
+if(WIN32 AND CMAKE_SIZEOF_VOID_P EQUAL 4)
+ set(CMAKE_LIBRARY_ARCHITECTURE x86)
+endif()
 find_package(VPL REQUIRED)
 target_link_libraries(${TARGET} VPL::dispatcher)
 ```

api/vpl/mfx.h

@@ -22,4 +22,6 @@
 #include "mfxvp8.h"
 #include "mfxjpeg.h"
 
+#include "mfxsurfacepool.h" 
+
 #endif /* __MFXDEFS_H__ */

api/vpl/mfxcommon.h

@@ -163,7 +163,7 @@ 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. */
 typedef struct {
-    mfxExtBuffer Header; /*!< Must be MFX_EXTBUFF_THREADS_PARAM. */
+    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. */
@@ -222,8 +222,10 @@ MFX_PACK_END()
 /* The mfxResourceType enumerator specifies types of different native data frames and buffers. */
 typedef enum {
     MFX_RESOURCE_SYSTEM_SURFACE                  = 1, /*!< System memory. */
-    MFX_RESOURCE_VA_SURFACE                      = 2, /*!< VA surface. */
-    MFX_RESOURCE_VA_BUFFER                       = 3, /*!< VA buffer. */
+    MFX_RESOURCE_VA_SURFACE_PTR                  = 2, /*!< Pointer to VA surface index. */
+    MFX_RESOURCE_VA_SURFACE                      = MFX_RESOURCE_VA_SURFACE_PTR, /*!< Pointer to VA surface index. */
+    MFX_RESOURCE_VA_BUFFER_PTR                   = 3, /*!< Pointer to VA buffer index. */
+    MFX_RESOURCE_VA_BUFFER                       = MFX_RESOURCE_VA_BUFFER_PTR, /*!< Pointer to VA buffer index. */
     MFX_RESOURCE_DX9_SURFACE                     = 4, /*!< IDirect3DSurface9. */
     MFX_RESOURCE_DX11_TEXTURE                    = 5, /*!< ID3D11Texture2D. */
     MFX_RESOURCE_DX12_RESOURCE                   = 6, /*!< ID3D12Resource. */
@@ -336,13 +338,15 @@ typedef struct {
 } mfxVPPDescription;
 MFX_PACK_END()
 
-#define MFX_DEVICEDESCRIPTION_VERSION MFX_STRUCT_VERSION(1, 0)
+/*! The current version of mfxDeviceDescription structure. */
+#define MFX_DEVICEDESCRIPTION_VERSION MFX_STRUCT_VERSION(1, 1)
 
 MFX_PACK_BEGIN_STRUCT_W_PTR()
 /*! This structure represents device description. */
 typedef struct {
     mfxStructVersion Version;                            /*!< Version of the structure. */
-    mfxU16 reserved[7];                                  /*!< reserved for future use. */
+    mfxU16 reserved[6];                                  /*!< reserved for future use. */
+    mfxU16 MediaAdapterType; /*!< Graphics adapter type. See the mfxMediaAdapterType enumerator for a list of possible values. */
     mfxChar DeviceID[MFX_STRFIELD_LEN];                  /*!< Null terminated string with device ID. */
     mfxU16 NumSubDevices;                                /*!< Number of available uniform sub-devices. Pure software implementation can report 0. */
     /*! This structure represents sub-device description. */
@@ -387,7 +391,34 @@ typedef struct {
 } mfxAccelerationModeDescription;
 MFX_PACK_END()
 
-#define MFX_IMPLDESCRIPTION_VERSION MFX_STRUCT_VERSION(1, 1)
+/*! Specifies the surface pool allocation policies. */
+ typedef enum {
+    /*! Recommends to limit max pool size by sum of requested surfaces asked by components. */
+    MFX_ALLOCATION_OPTIMAL = 0, 
+
+    /*! Dynamic allocation with no limit. */
+    MFX_ALLOCATION_UNLIMITED   = 1, 
+    
+    /*! Max pool size is limited by NumberToPreAllocate + DeltaToAllocateOnTheFly. */
+    MFX_ALLOCATION_LIMITED     = 2,  
+
+} mfxPoolAllocationPolicy;
+
+/*! The current version of mfxPoolPolicyDescription structure. */
+#define MFX_POOLPOLICYDESCRIPTION_VERSION MFX_STRUCT_VERSION(1, 0)
+
+MFX_PACK_BEGIN_STRUCT_W_PTR()
+/*! This structure represents pool policy description. */
+typedef struct {
+    mfxStructVersion Version;                       /*!< Version of the structure. */
+    mfxU16 reserved[2];                             /*!< reserved for future use. */
+    mfxU16 NumPoolPolicies;                         /*!< Number of supported pool policies. */
+    mfxPoolAllocationPolicy* Policy;                /*!< Pointer to the array of supported pool policies. */
+} mfxPoolPolicyDescription;
+MFX_PACK_END()
+
+/*! The current version of mfxImplDescription structure. */
+#define MFX_IMPLDESCRIPTION_VERSION MFX_STRUCT_VERSION(1, 2)
 
 MFX_PACK_BEGIN_STRUCT_W_PTR()
 /*! This structure represents the implementation description. */
@@ -410,8 +441,9 @@ typedef struct {
         mfxAccelerationModeDescription   AccelerationModeDescription; /*!< Supported acceleration modes. */
         mfxU32 reserved3[4];
     };
-    mfxU32                 reserved[12];                 /*!< Reserved for future use. */
-    mfxU32                 NumExtParam;                  /*!< Number of extension buffers. Reserved for future use. Must be 0. */
+    mfxPoolPolicyDescription  PoolPolicies;                /*!< Supported surface pool polices. */
+    mfxU32                    reserved[8];                 /*!< Reserved for future use. */
+    mfxU32                    NumExtParam;                 /*!< Number of extension buffers. Reserved for future use. Must be 0. */
     union {
         mfxExtBuffer **ExtParam;                         /*!< Array of extension buffers. */
         mfxU64       Reserved2;                          /*!< Reserved for future use. */

api/vpl/mfxdefs.h

@@ -8,7 +8,7 @@
 #define __MFXDEFS_H__
 
 #define MFX_VERSION_MAJOR 2
-#define MFX_VERSION_MINOR 4
+#define MFX_VERSION_MINOR 5
 
 // 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
@@ -298,6 +298,8 @@ typedef enum
     /* low-delay partial output */
     MFX_ERR_NONE_PARTIAL_OUTPUT         = 12,   /*!< Frame is not ready, but bitstream contains partial output. */
 
+    MFX_WRN_ALLOC_TIMEOUT_EXPIRED       = 13,   /*!< Timeout expired for internal frame allocation. */
+
     /* threading statuses */
     MFX_TASK_DONE = MFX_ERR_NONE,               /*!< Task has been completed. */
     MFX_TASK_WORKING                    = 8,    /*!< There is some more work to do. */

api/vpl/mfxdispatcher.h

@@ -147,6 +147,98 @@ mfxStatus MFX_CDECL MFXCreateSession(mfxLoader loader, mfxU32 i, mfxSession* ses
 */
 mfxStatus MFX_CDECL MFXDispReleaseImplDescription(mfxLoader loader, mfxHDL hdl);
 
+/* Helper macro definitions to add config filter properties. */
+
+/*! Adds single property of mfxU32 type.
+   @param[in] loader Valid mfxLoader object
+   @param[in] name Property name string
+   @param[in] value Property value
+*/
+#define MFX_ADD_PROPERTY_U32(loader, name, value)               \
+{                                                               \
+    mfxVariant impl_value;                                      \
+    mfxConfig  cfg = MFXCreateConfig(loader);                   \
+    impl_value.Version.Version = MFX_VARIANT_VERSION;           \
+    impl_value.Type     = MFX_VARIANT_TYPE_U32;                 \
+    impl_value.Data.U32 = value;                                \
+    MFXSetConfigFilterProperty(cfg, (mfxU8 *)name, impl_value); \
+}
+
+/*! Adds single property of mfxU16 type.
+   @param[in] loader Valid mfxLoader object
+   @param[in] name Property name string
+   @param[in] value Property value
+*/
+#define MFX_ADD_PROPERTY_U16(loader, name, value)               \
+{                                                               \
+    mfxVariant impl_value               = { 0 };                \
+    mfxConfig  cfg = MFXCreateConfig(loader);                   \
+    impl_value.Version.Version = MFX_VARIANT_VERSION;           \
+    impl_value.Type     = MFX_VARIANT_TYPE_U16;                 \
+    impl_value.Data.U16 = value;                                \
+    MFXSetConfigFilterProperty(cfg, (mfxU8 *)name, impl_value); \
+}
+
+/*! Adds single property of pointer type.
+   @param[in] loader Valid mfxLoader object
+   @param[in] name Property name string
+   @param[in] value Property value
+*/
+#define MFX_ADD_PROPERTY_PTR(loader, name, value)               \
+{                                                               \
+    mfxVariant impl_value               = { 0 };                \
+    mfxConfig  cfg = MFXCreateConfig(loader);                   \
+    impl_value.Version.Version = MFX_VARIANT_VERSION;           \
+    impl_value.Type     = MFX_VARIANT_TYPE_PTR;                 \
+    impl_value.Data.Ptr = (mfxHDL)value;                        \
+    MFXSetConfigFilterProperty(cfg, (mfxU8 *)name, impl_value); \
+}
+
+/*! Update existing property of mfxU32 type.
+   @param[in] loader Valid mfxLoader object
+   @param[in] config Valid mfxConfig object
+   @param[in] name Property name string
+   @param[in] value Property value
+*/
+#define MFX_UPDATE_PROPERTY_U32(loader, config, name, value)       \
+{                                                                  \
+    mfxVariant impl_value;                                         \
+    impl_value.Version.Version = MFX_VARIANT_VERSION;              \
+    impl_value.Type     = MFX_VARIANT_TYPE_U32;                    \
+    impl_value.Data.U32 = value;                                   \
+    MFXSetConfigFilterProperty(config, (mfxU8 *)name, impl_value); \
+}
+
+/*! Update existing property of mfxU16 type.
+   @param[in] loader Valid mfxLoader object
+   @param[in] config Valid mfxConfig object
+   @param[in] name Property name string
+   @param[in] value Property value
+*/
+#define MFX_UPDATE_PROPERTY_U16(loader, config, name, value)       \
+{                                                                  \
+    mfxVariant impl_value;                                         \
+    impl_value.Version.Version = MFX_VARIANT_VERSION;              \
+    impl_value.Type     = MFX_VARIANT_TYPE_U16;                    \
+    impl_value.Data.U16 = value;                                   \
+    MFXSetConfigFilterProperty(config, (mfxU8 *)name, impl_value); \
+}
+
+/*! Update existing property of pointer type.
+   @param[in] loader Valid mfxLoader object
+   @param[in] config Valid mfxConfig object
+   @param[in] name Property name string
+   @param[in] value Property value
+*/
+#define MFX_UPDATE_PROPERTY_PTR(loader, config, name, value)       \
+{                                                                  \
+    mfxVariant impl_value;                                         \
+    impl_value.Version.Version = MFX_VARIANT_VERSION;              \
+    impl_value.Type     = MFX_VARIANT_TYPE_PTR;                    \
+    impl_value.Data.Ptr = (mfxHDL)value;                           \
+    MFXSetConfigFilterProperty(config, (mfxU8 *)name, impl_value); \
+}
+
 #ifdef __cplusplus
 }
 #endif