Release 2021.2.2

CMakeLists.txt

@@ -1,5 +1,5 @@
 # ##############################################################################
-# Copyright (C) 2020 Intel Corporation
+# Copyright (C) Intel Corporation
 #
 # SPDX-License-Identifier: MIT
 # ##############################################################################
@@ -8,9 +8,8 @@ cmake_minimum_required(VERSION 3.10.2)
 
 file(STRINGS "version.txt" version_txt)
 project(oneVPL VERSION ${version_txt})
-if(NOT "${CMAKE_SIZEOF_VOID_P}" STREQUAL "8")
-  message(FATAL_ERROR "Unsupported architecture: only 64-bit supported")
-endif()
+
+set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH};${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
 #
 # Project configuration options
@@ -28,7 +27,7 @@ if(NOT CMAKE_BUILD_TYPE)
 endif()
 
 # Project options
-option(OPTION_BUILD_EXAMPLES "Build examples." OFF)
+option(OPTION_COMPILE_PREVIEW_EXAMPLES "Build examples." OFF)
 
 # Set output directories
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
@@ -46,11 +45,8 @@ add_subdirectory(api)
 add_subdirectory(dispatcher)
 add_subdirectory(env)
 add_subdirectory(modulefiles)
-add_subdirectory(tools/cli)
-add_subdirectory(examples/hello-decode)
-add_subdirectory(examples/hello-encode)
-add_subdirectory(examples/hello-vpp)
-add_subdirectory(examples/hello-transcode)
+add_subdirectory(tools)
+add_subdirectory(examples)
 
 install(
   FILES third-party-programs.txt

LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -25,20 +25,42 @@ To build this project you will need:
 - A compiler with C++11 support
 - CMake 3.10 or newer
 
-## Build and Installation
+## Build and Installation of this package
 
 Build the project with the following commands:
 
 ```
+cd <vpl-repo-clone-location>
+
 mkdir _build
 cd _build
 cmake .. -DCMAKE_INSTALL_PREFIX=<vpl-install-location>
 cmake --build . --config Release
+# optional, create a portable zip file from the build
+# cmake --build . --config Release --target package
 cmake --build . --config Release --target install
 ```
 
 You can find the build output in `<vpl-install-location>`.
 
+Helper scripts are avalible in the `script` folder.
+
+- bootstrap : builds any dependencies (none at this time). Built dependencies will be placed in the location stored in VPL_BUILD_DEPENDENCIES if the variable is defined.
+- clean : removes intermediate build results
+- build : builds the package (all but the last step above)
+- install : installs the package (the last step above). Package will be installed in the location stored in VPL_INSTALL_DIR if the variable is defined.
+- test : run any smoke testing on the installed package
+
+You can build the project using the scripts with the follwoing commands
+```
+cd <vpl-repo-clone-location>
+script/bootstrap
+script/build
+script/install
+```
+
+Optionaly the environment variable VPL_INSTALL_DIR can be set to specify a location for the scripts to install the project.
+
 ## Getting an Implementation
 
 To use oneVPL for video processing you need to install at least one
@@ -47,6 +69,141 @@ implementation. Current implementations:
 - [oneVPL-cpu](https://github.com/oneapi-src/oneVPL-cpu), the CPU reference
   implementation
 
+## Building Base and CPU Implementations
+
+Normally you don't just want to build the base package, which is limited to the dispatcher and samples. You want to
+be able to do actual work like decoding video. To do this you need an implemetnation. As described above the CPU
+implementation is delivered alongside the Base package.
+
+You can extend the project build commands above as follows to also build the CPU implementation.
+
+```
+cd <vpl-repo-clone-location>
+
+mkdir _build
+cd _build
+cmake .. -DCMAKE_INSTALL_PREFIX=<vpl-install-location>
+cmake --build . --config Release
+cmake --build . --config Release --target package
+cmake --build . --config Release --target install
+
+cd <vpl-cpu-repo-clone-location>
+
+# optional, specify an external cache folder to store dependencies
+export VPL_BUILD_DEPENDENCIES=<dependencies-cache>
+
+# Build 3rd party dependencies.
+source script/bootstrap
+
+mkdir _build
+cd _build
+cmake .. -DCMAKE_INSTALL_PREFIX=<vpl-install-location>
+cmake --build . --config Release
+cmake --build . --config Release --target package
+cmake --build . --config Release --target install
+```
+
+You can find the build output in `<vpl-install-location>`.
+
+Helper scripts to build Base and CPU implemenation are avalible in the `script/e2e` folder.
+
+- bootstrap : builds any dependencies.
+- clean : removes intermediate build results
+- build : builds and installs the package
+- test : run any smoke testing on the installed package
+
+These scripts assume oneVPL and oneVPL-cpu are cloned into the same parent folder
+
+Note: `.bat` versions are also provided for Windows.
+
+### Using End-To-End Scripts
+
+You can build oneVPL base and CPU implementation with the End-To-End scripts using the following commands:
+
+```
+cd <vpl-root>
+oneVPL/script/e2e/bootstrap
+oneVPL/script/e2e/build
+```
+
+Optionaly you may set the environment variables VPL_INSTALL_DIR and
+VPL_BUILD_DEPENDENCIES to specify a location to install the project and to
+store the built dependencies respectivly.
+
+
+```
+cd <vpl-root>
+
+export VPL_BUILD_DEPENDENCIES=<dependencies-cache>
+export VPL_INSTALL_DIR=<vpl-install-location>
+
+oneVPL/script/e2e/bootstrap
+oneVPL/script/e2e/build
+```
+
+You can also clear build results by calling the clean script.
+Note, if VPL_INSTALL_DIR is set it will be cleared too.
+
+
+```
+cd <vpl-root>
+
+oneVPL/script/e2e/clean
+```
+
+A complete rebuild can be forced by cleaning and then rebuilding.
+
+```
+cd <vpl-root>
+
+export VPL_BUILD_DEPENDENCIES=<dependencies-cache>
+export VPL_INSTALL_DIR=<vpl-install-location>
+
+oneVPL/script/e2e/clean
+oneVPL/script/e2e/bootstrap
+oneVPL/script/e2e/build
+```
+
+## Developer Usage
+
+### Configure the Environment
+
+If you did not install to standard system locations, you need to set up the
+environment, so tools like CMake and pkg-config can find the library and
+headers.
+
+For Linux:
+```
+source <vpl-install-location>/env/vars.sh
+```
+
+For Windows:
+```
+<vpl-install-location>\env\vars.bat
+```
+
+
+### Link to oneVPL with CMake
+
+Add the following code to your CMakeLists, assuming TARGET is defined as the
+component that wants to use oneVPL:
+
+```
+find_package(VPL REQUIRED)
+target_link_libraries(${TARGET} VPL::dispatcher)
+```
+
+
+### Link to oneVPL from Bash with pkg-config
+
+The following command line illustrates how to link a simple program to oneVPL
+using pkg-config.
+
+```
+gcc program.cpp `pkg-config --cflags --libs vpl`
+```
+
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.

api/CMakeLists.txt

@@ -1,23 +1,39 @@
 # ##############################################################################
-# Copyright (C) 2020 Intel Corporation
+# Copyright (C) Intel Corporation
 #
 # SPDX-License-Identifier: MIT
 # ##############################################################################
 # oneAPI Video Processing Library (oneVPL) API build script
 cmake_minimum_required(VERSION 3.10.2)
 
+set(VPL_API_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+
+if(DEFINED ENV{ONEVPL_API_HEADER_DIRECTORY})
+  set(VPL_API_INCLUDE_DIR $ENV{ONEVPL_API_HEADER_DIRECTORY})
+  message(STATUS "Using custom API header directory: ${VPL_API_INCLUDE_DIR}")
+endif()
+
 # get API version
-file(READ vpl/mfxdefs.h mfxdefs)
+file(READ ${VPL_API_INCLUDE_DIR}/vpl/mfxdefs.h mfxdefs)
+
 string(REGEX MATCH "MFX_VERSION_MAJOR ([0-9]*)" _ ${mfxdefs})
+set(API_VERSION_MAJOR ${CMAKE_MATCH_1})
 set(API_VERSION_MAJOR
-    ${CMAKE_MATCH_1}
+    ${API_VERSION_MAJOR}
+    PARENT_SCOPE)
+
+string(REGEX MATCH "MFX_VERSION_MINOR ([0-9]*)" _ ${mfxdefs})
+set(API_VERSION_MINOR ${CMAKE_MATCH_1})
+set(API_VERSION_MINOR
+    ${API_VERSION_MINOR}
     PARENT_SCOPE)
 
+message(STATUS "API version: ${API_VERSION_MAJOR}.${API_VERSION_MINOR}")
 add_library(vpl-api INTERFACE)
 
-target_include_directories(vpl-api INTERFACE .)
+target_include_directories(vpl-api INTERFACE ${VPL_API_INCLUDE_DIR})
 
 install(
-  DIRECTORY vpl
+  DIRECTORY ${VPL_API_INCLUDE_DIR}/vpl
   DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
   COMPONENT dev)

api/vpl/mfxadapter.h

@@ -29,6 +29,8 @@ extern "C"
    @p input_info or adapters pointer is NULL. \n
    MFX_ERR_NOT_FOUND  No suitable adapters found. \n
    MFX_WRN_OUT_OF_RANGE  Not enough memory to report back entire list of adapters. In this case as many adapters as possible will be returned.
+
+   @since This function is available since API version 1.31.
 */
 mfxStatus MFX_CDECL MFXQueryAdapters(mfxComponentInfo* input_info, mfxAdaptersInfo* adapters);
 
@@ -45,6 +47,8 @@ mfxStatus MFX_CDECL MFXQueryAdapters(mfxComponentInfo* input_info, mfxAdaptersIn
    MFX_ERR_NULL_PTR  bitstream or @p adapters pointer is NULL. \n
    MFX_ERR_NOT_FOUND No suitable adapters found. \n
    MFX_WRN_OUT_OF_RANGE Not enough memory to report back entire list of adapters. In this case as many adapters as possible will be returned.
+
+   @since This function is available since API version 1.31.
 */
 mfxStatus MFX_CDECL MFXQueryAdaptersDecode(mfxBitstream* bitstream, mfxU32 codec_id, mfxAdaptersInfo* adapters);
 
@@ -57,6 +61,8 @@ mfxStatus MFX_CDECL MFXQueryAdaptersDecode(mfxBitstream* bitstream, mfxU32 codec
    @return
    MFX_ERR_NONE The function completed successfully. \n
    MFX_ERR_NULL_PTR  num_adapters pointer is NULL.
+
+   @since This function is available since API version 1.31.
 */
 mfxStatus MFX_CDECL MFXQueryAdaptersNumber(mfxU32* num_adapters);
 #ifdef __cplusplus

api/vpl/mfxbrc.h

@@ -76,7 +76,7 @@ enum {
     MFX_BRC_PANIC_SMALL_FRAME = 4  /*!< Coded frame is too small, no further recoding possible - required padding to mfxBRCFrameStatus::MinFrameSize. */
 };
 
-MFX_PACK_BEGIN_USUAL_STRUCT()
+MFX_PACK_BEGIN_STRUCT_W_PTR()
 /*!
    Specifies instructions for the encoder provided by external BRC after each frame encoding. See the BRCStatus enumerator for details.
 */