Release 2021.5.0

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

* Added option to build dispatcher as a static library
* Added ability to build dispatcher under MinGW
* Fixes for tools and samples

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

Issues and Limitations
=====================

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

Dispatcher
----------
* 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.
* dpccp-blur sample incorrectly states its usage.  The sample example
  commandline should read:

    dpcpp-blur -i in.i420 -w 128 -h 96
    To view: ffplay -f rawvideo -pixel_format bgra -video_size 256x192 -pixel_format yuv420p out.raw

* legacy-vpp sample in hardware mode is not supported on Sky Lake.
* hello-transcode readme incorrectly implies sample runs on hardware.
* 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.
* Input size should be aligned to 16 bytes for sample_encode.
* 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 occasionally hangs for (CPU) SVT-HEVC encodes when using
  VBR in Ubuntu 18.04.
* sample_encode does not work if the input is scaled or color converted.
* 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.
* When configuring systems to run the OpenVINO interop samples in Linux
  gmmlib version conflicts can occur. Debug shows undefined GmmLib
  symbols as the cause of a runtime error.  This can be mitigated by
  using the media stack integrated with OpenVINO installation.
  Uninstall other versions of libva, iHD, and libgmm then select Media
  SDK when installing OpenVINO as described in the [OpenVINO install
  documentation](https://docs.openvinotoolkit.org/latest/openvino_docs_install_guides_installing_openvino_linux.html#install-openvino).

.clang-format

@@ -53,7 +53,7 @@ ConstructorInitializerAllOnOneLineOrOnePerLine: true
 ConstructorInitializerIndentWidth: 8
 ContinuationIndentWidth: 4
 Cpp11BracedListStyle: false
-DerivePointerAlignment: true
+DerivePointerAlignment: false
 DisableFormat: false
 FixNamespaceComments: true
 ForEachMacros:
@@ -88,7 +88,7 @@ PenaltyBreakString: 1000
 PenaltyBreakTemplateDeclaration: 10
 PenaltyExcessCharacter: 1000000
 PenaltyReturnTypeOnItsOwnLine: 200
-PointerAlignment: Left
+PointerAlignment: Right
 RawStringFormats:
   - Language: Cpp
     Delimiters:

.pre-commit-config.yaml

@@ -7,6 +7,7 @@
 fail_fast: false
 default_language_version:
   python: python3
+exclude: /ext/
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.5.0

CMakeLists.txt

@@ -27,12 +27,21 @@ if(NOT CMAKE_BUILD_TYPE)
 endif()
 
 # Project options
+option(BUILD_SHARED_LIBS "Build shared instead of static libraries." ON)
+option(BUILD_TESTS "Build tests." OFF)
+
+set(BUILD_DEV
+    ON
+    CACHE BOOL "Build files that are only needed for development.")
 set(BUILD_DISPATCHER
     ON
     CACHE BOOL "Build dispatcher.")
-set(BUILD_DEV
+set(BUILD_TOOLS
     ON
-    CACHE BOOL "Build files that are only needed for development.")
+    CACHE BOOL "Build Tools.")
+set(BUILD_EXAMPLES
+    ON
+    CACHE BOOL "Build examples when building dev package.")
 
 # Off by default while this is a preview
 set(BUILD_PYTHON_BINDING
@@ -49,6 +58,7 @@ if(BUILD_DISPATCHER_ONLY)
 endif()
 if(BUILD_DEV_ONLY)
   set(BUILD_DISPATCHER OFF)
+  set(BUILD_TOOLS OFF)
   set(BUILD_PYTHON_BINDING OFF)
 endif()
 if(BUILD_PYTHON_BINDING_ONLY)
@@ -58,17 +68,6 @@ endif()
 
 option(USE_ONEAPI_INSTALL_LAYOUT "Use oneAPI install layout instead of FHS" OFF)
 
-if(USE_ONEAPI_INSTALL_LAYOUT)
-  set(CMAKE_INSTALL_DOCDIR "documentation")
-  set(CMAKE_INSTALL_LIBDIR "lib")
-  set(ONEAPI_INSTALL_ENVDIR "env")
-  set(ONEAPI_INSTALL_SYSCHECKDIR "sys_check")
-  set(ONEAPI_INSTALL_MODFILEDIR "modulefiles")
-  set(ONEAPI_INSTALL_EXAMPLEDIR "examples")
-  set(ONEAPI_INSTALL_LICENSEDIR "licensing/oneVPL")
-  set(ONEAPI_INSTALL_PYTHONDIR "python/lib")
-endif()
-
 # Set output directories
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
@@ -81,12 +80,19 @@ set(CMAKE_INSTALL_SO_NO_EXE 0)
 
 include(cmake/CompileOptions.cmake)
 
+if(BUILD_TESTS)
+  include(Dart)
+  enable_testing()
+endif()
+
 add_subdirectory(api)
 add_subdirectory(dispatcher)
+if(BUILD_TOOLS)
+  add_subdirectory(tools)
+endif()
 if(BUILD_DEV)
   add_subdirectory(env)
   add_subdirectory(modulefiles)
-  add_subdirectory(tools)
   add_subdirectory(examples)
 endif()
 add_subdirectory(preview)
@@ -157,10 +163,6 @@ message(
   STATUS "  CMAKE_INSTALL_FULL_LIBDIR      : ${CMAKE_INSTALL_FULL_LIBDIR}")
 message(
   STATUS "  CMAKE_INSTALL_FULL_DOCDIR      : ${CMAKE_INSTALL_FULL_DOCDIR}")
-message(
-  STATUS "  ONEAPI_INSTALL_FULL_BIN32DIR   : ${ONEAPI_INSTALL_FULL_BIN32DIR}")
-message(
-  STATUS "  ONEAPI_INSTALL_FULL_LIB32DIR   : ${ONEAPI_INSTALL_FULL_LIB32DIR}")
 message(
   STATUS "  ONEAPI_INSTALL_FULL_ENVDIR     : ${ONEAPI_INSTALL_FULL_ENVDIR}")
 message(
@@ -177,3 +179,8 @@ message(
 message(STATUS "Build:")
 message(STATUS "  BUILD_DEV                      : ${BUILD_DEV}")
 message(STATUS "  BUILD_DISPATCHER               : ${BUILD_DISPATCHER}")
+message(STATUS "  BUILD_TOOLS                    : ${BUILD_TOOLS}")
+message(STATUS "  BUILD_SHARED_LIBS              : ${BUILD_SHARED_LIBS}")
+message(STATUS "  BUILD_TESTS                    : ${BUILD_TESTS}")
+message(STATUS "  BUILD_EXAMPLES                 : ${BUILD_EXAMPLES}")
+message(STATUS "  BUILD_PYTHON_BINDING           : ${BUILD_PYTHON_BINDING}")

api/vpl/preview/defs.hpp

@@ -210,44 +210,6 @@ enum class frame_type : uint16_t {
 
 ENABLE_BIT_OPERATORS_WITH_ENUM(frame_type);
 
-static status mfxstatus_to_onevplstatus(mfxStatus s) {
-    switch (s) {
-        case MFX_ERR_NONE:
-            return status::Ok;
-        case MFX_WRN_IN_EXECUTION:
-            return status::ExecutionInProgress;
-        case MFX_WRN_DEVICE_BUSY:
-            return status::DeviceBusy;
-        case MFX_WRN_VIDEO_PARAM_CHANGED:
-            return status::VideoParamChanged;
-        case MFX_WRN_PARTIAL_ACCELERATION:
-            return status::PartialAcceleration;
-        case MFX_WRN_INCOMPATIBLE_VIDEO_PARAM:
-            return status::IncompartibleVideoParam;
-        case MFX_WRN_VALUE_NOT_CHANGED:
-            return status::ValueNotChanged;
-        case MFX_WRN_OUT_OF_RANGE:
-            return status::OutOfRange;
-        case MFX_TASK_WORKING:
-            return status::TaskWorking;
-        case MFX_TASK_BUSY:
-            return status::TaskBusy;
-        case MFX_WRN_FILTER_SKIPPED:
-            return status::FilterSkipped;
-        case MFX_ERR_NONE_PARTIAL_OUTPUT:
-            return status::PartialOutput;
-        //// Errors but they need to be treat as positive status in some cases.
-        case MFX_ERR_NOT_ENOUGH_BUFFER:
-            return status::NotEnoughBuffer;
-        case MFX_ERR_MORE_DATA:
-            return status::NotEnoughData;
-        case MFX_ERR_MORE_SURFACE:
-            return status::NotEnoughSurface;
-        default:
-            return status::Unknown;
-    }
-}
-
 enum class implementation : uint32_t {
     automatic        = MFX_IMPL_AUTO,
     unsupported      = MFX_IMPL_UNSUPPORTED,

api/vpl/preview/extension_buffer.hpp

@@ -346,8 +346,8 @@ REGISTER_TRIVIAL_EXT_BUFFER(ExtPartialBitstreamParam,
                                                                                                     \
         /*! @brief Dtor. */                                                                         \
         ~className() {                                                                              \
-            delete[] buffer_.ptr;                                                                   \
             buffer_.numElems = 0;                                                                   \
+            delete[] buffer_.ptr;                                                                   \
         }                                                                                           \
         /*! @brief Copy operator. */                                                                \
         /*! @param[in] other another object to use as data source. */                               \
@@ -358,7 +358,7 @@ REGISTER_TRIVIAL_EXT_BUFFER(ExtPartialBitstreamParam,
                                                                                                     \
             if (this->buffer_.ptr)                                                                  \
                 delete[] this->buffer_.ptr;                                                         \
-            this->buffer_ = other.buffer_;                                                          \
+                this->buffer_.ptr = NULL;                                                           \
                                                                                                     \
             if (other.buffer_.numElems) {                                                           \
                 this->buffer_.numElems = other.buffer_.numElems;                                    \
@@ -369,7 +369,6 @@ REGISTER_TRIVIAL_EXT_BUFFER(ExtPartialBitstreamParam,
             }                                                                                       \
             else {                                                                                  \
                 buffer_.numElems = 0;                                                               \
-                buffer_.ptr      = NULL;                                                            \
             }                                                                                       \
                                                                                                     \
             return *this;                                                                           \

api/vpl/preview/extension_buffer_list.hpp

@@ -24,9 +24,9 @@ static constexpr uint32_t ignore_ID_list[IGNORE_LIST_LEN] = { 0, MFX_EXTBUFF_VPP
 class buffer_list {
 public:
     /// @brief default ctor
-    buffer_list() : mfxBuffers_(0), extBuffers_() {}
+    buffer_list() : extBuffers_() , mfxBuffers_(0) {}
 
-    buffer_list(const buffer_list& other) : mfxBuffers_(0), extBuffers_(other.extBuffers_){}
+    buffer_list(const buffer_list& other) : extBuffers_(other.extBuffers_), mfxBuffers_(0){}
     buffer_list& operator=(const buffer_list& other){
         if(mfxBuffers_ != other.mfxBuffers_){
             if(mfxBuffers_){

api/vpl/preview/frame_surface.hpp

@@ -194,6 +194,18 @@ class frame_surface : public std::enable_shared_from_this<frame_surface> {
         return std::pair(frame_info(surface_->Info), frame_data(surface_->Data));
     }
 
+    /// @brief Maps data to the system memory.
+    /// @param flags Data access flag: read or write.
+    /// @return Pointers to the surface data strucuture in the system memory
+    auto map_data(memory_access flags) {
+        wait();
+        detail::c_api_invoker(detail::default_checker,
+                                surface_->FrameInterface->Map,
+                                surface_,
+                                (mfxMemoryFlags)flags);
+        return frame_data(surface_->Data);
+    }
+
     /// @brief Unmaps data to the system memory.
     void unmap() {
         detail::c_api_invoker(detail::default_checker, surface_->FrameInterface->Unmap, surface_);

api/vpl/preview/options.hpp

@@ -31,18 +31,18 @@ class property {
     /// @param[in] name Name of the property
     /// @param[in] value Value
     template <typename T>
-    property(property_name &name, T value) : value_(value),
-                                             name_(name.get_name()) {}
+    property(property_name &name, T value) : name_(name.get_name()), 
+                                             value_(value) {}
     /// @brief Constucts property with given name and the value
     /// @tparam T Type of the value
     /// @param[in] name Name of the property
     /// @param[in] value Value
     template <typename T>
-    property(std::string &name, T value) : value_(value),
-                                           name_(name) {}
+    property(std::string &name, T value) : name_(name),
+                                           value_(value) {}
     /// @brief Copy ctor
     /// @param[in] other another object to use as data source
-    property(const property &other) : value_(other.value_), name_(other.name_) {}
+    property(const property &other) : name_(other.name_), value_(other.value_) {}
     /// @brief Dtor
     virtual ~property() {}
 

api/vpl/preview/payload.hpp

@@ -61,7 +61,8 @@ class payload {
 
     /// @brief Copy ctor.
     /// @param[in] other Object to copy.
-    payload(const payload& other) {
+    payload(const payload& other) :
+        codec_id_(other.codec_id_) {
         ctor_helper(other.get_payload_data(),
                     other.payload_.NumBit,
                     other.payload_.Type,
@@ -76,6 +77,7 @@ class payload {
         payload_.NumBit    = other.payload_.NumBit;
         payload_.BufSize   = other.payload_.BufSize;
         payload_.Data      = other.payload_.Data;
+        codec_id_ = other.codec_id_;
 
         other.payload_.Data = 0;
     }
@@ -94,6 +96,7 @@ class payload {
                     other.payload_.NumBit,
                     other.payload_.Type,
                     other.payload_.CtrlFlags);
+        codec_id_ = other.codec_id_;
         return *this;
     }
 
@@ -112,7 +115,7 @@ class payload {
         payload_.NumBit    = other.payload_.NumBit;
         payload_.BufSize   = other.payload_.BufSize;
         payload_.Data      = other.payload_.Data;
-
+        codec_id_ = other.codec_id_;
         other.payload_.Data = 0;
         return *this;
     }

api/vpl/preview/property_name.hpp

@@ -288,7 +288,7 @@ class property_name {
     /// @brief Add item
     /// @param subname Subname
     constexpr void add_item(std::string_view subname) {
-        int i = 0;
+        unsigned int i = 0;
         ID_   = check_value(subname, level_, ID_);
 
         for (i = 0; i < subname.size(); i++) {

api/vpl/preview/session.hpp

@@ -30,6 +30,7 @@
   #include "va/va.h"
   #include "va/va_drm.h"
   #include <fcntl.h>
+  #include <unistd.h>
 #endif
 
 namespace oneapi {
@@ -187,6 +188,9 @@ class session {
     /// @brief Version of implementation
     mfxVersion version_;
 
+    /// @brief accelorator file handle
+    int fd_;
+
     void init_accelerator_handle() {
         mfxIMPL impl;
         mfxStatus sts = MFXQueryIMPL(session_, &impl);
@@ -196,11 +200,10 @@ class session {
         #ifdef LIBVA_SUPPORT
             if ((impl & MFX_IMPL_VIA_VAAPI) == MFX_IMPL_VIA_VAAPI) {
                 VADisplay va_dpy = NULL;
-                int fd;
                 // initialize VAAPI context and set session handle (req in Linux)
-                fd = open("/dev/dri/renderD128", O_RDWR);
-                if (fd >= 0) {
-                    va_dpy = vaGetDisplayDRM(fd);
+                fd_ = open("/dev/dri/renderD128", O_RDWR);
+                if (fd_ >= 0) {
+                    va_dpy = vaGetDisplayDRM(fd_);
                     if (va_dpy) {
                         int major_version = 0, minor_version = 0;
                         if (VA_STATUS_SUCCESS == vaInitialize(va_dpy, &major_version, &minor_version)) {
@@ -219,13 +222,54 @@ class session {
         #ifdef LIBVA_SUPPORT
             vaTerminate((VADisplay)accelerator_handle);
             accelerator_handle = nullptr;
+            close(fd_);
         #endif
     }
 
 
     /// @brief Accelerator handle
     void *accelerator_handle;
 
+    /// @brief Convert MFX_ return codes to oneVPL status
+    /// @return oneVPL status code
+    static status mfxstatus_to_onevplstatus(mfxStatus s) {
+        switch (s) {
+            case MFX_ERR_NONE:
+                return status::Ok;
+            case MFX_WRN_IN_EXECUTION:
+                return status::ExecutionInProgress;
+            case MFX_WRN_DEVICE_BUSY:
+                return status::DeviceBusy;
+            case MFX_WRN_VIDEO_PARAM_CHANGED:
+                return status::VideoParamChanged;
+            case MFX_WRN_PARTIAL_ACCELERATION:
+                return status::PartialAcceleration;
+            case MFX_WRN_INCOMPATIBLE_VIDEO_PARAM:
+                return status::IncompartibleVideoParam;
+            case MFX_WRN_VALUE_NOT_CHANGED:
+                return status::ValueNotChanged;
+            case MFX_WRN_OUT_OF_RANGE:
+                return status::OutOfRange;
+            case MFX_TASK_WORKING:
+                return status::TaskWorking;
+            case MFX_TASK_BUSY:
+                return status::TaskBusy;
+            case MFX_WRN_FILTER_SKIPPED:
+                return status::FilterSkipped;
+            case MFX_ERR_NONE_PARTIAL_OUTPUT:
+                return status::PartialOutput;
+            //// Errors but they need to be treat as positive status in some cases.
+            case MFX_ERR_NOT_ENOUGH_BUFFER:
+                return status::NotEnoughBuffer;
+            case MFX_ERR_MORE_DATA:
+                return status::NotEnoughData;
+            case MFX_ERR_MORE_SURFACE:
+                return status::NotEnoughSurface;
+            default:
+                return status::Unknown;
+        }
+    }
+
 private:
     mfxLoader loader_;
 };