oneVPL Session#

Before calling any oneVPL functions, the application must initialize the library and create a oneVPL session. A oneVPL session maintains context for the use of any of DECODE, ENCODE, VPP, DECODE_VPP functions.

Intel® Media Software Development Kit Dispatcher (Legacy)#

The MFXInit() or MFXInitEx() function starts (initializes) a session. The MFXClose() function closes (de-initializes) the session. To avoid memory leaks, always call MFXClose() after MFXInit().

Important

MFXInit() and MFXInitEx() are deprecated starting from API 2.0. Applications must use MFXLoad() and MFXCreateSession() to initialize implementations.

Important

For backward compatibility with existent Intel® Media Software Development Kit applications oneVPL session can be created and initialized by the legacy dispatcher through MFXInit() or MFXInitEx() calls. In this case, the reported API version will be 1.255 on Intel® platforms with Xe architecture.

The application can initialize a session as a software-based session (MFX_IMPL_SOFTWARE) or a hardware-based session (MFX_IMPL_HARDWARE). In a software-based session, the SDK functions execute on a CPU. In a hardware-base session, the SDK functions use platform acceleration capabilities. For platforms that expose multiple graphic devices, the application can initialize a session on any alternative graphic device using the MFX_IMPL_HARDWARE, MFX_IMPL_HARDWARE2, MFX_IMPL_HARDWARE3, or MFX_IMPL_HARDWARE4 values of mfxIMPL.

The application can also initialize a session to be automatic ( MFX_IMPL_AUTO or MFX_IMPL_AUTO_ANY), instructing the dispatcher library to detect the platform capabilities and choose the best SDK library available. After initialization, the SDK returns the actual implementation through the MFXQueryIMPL() function.

Internally, the dispatcher works as follows:

  1. Dispatcher searches for the shared library with the specific name:

    OS

    Name

    Description

    Linux*

    libmfxsw64.so.1

    64-bit software-based implementation

    Linux

    libmfxsw32.so.1

    32-bit software-based implementation

    Linux

    libmfxhw64.so.1

    64-bit hardware-based implementation

    Linux

    libmfxhw64.so.1

    32-bit hardware-based implementation

    Windows*

    libmfxsw32.dll

    64-bit software-based implementation

    Windows

    libmfxsw32.dll

    32-bit software-based implementation

    Windows

    libmfxhw64.dll

    64-bit hardware-based implementation

    Windows

    libmfxhw64.dll

    32-bit hardware-based implementation

  2. Once the library is loaded, the dispatcher obtains addresses for each SDK function. See the Exported Functions/API Version table for the list of functions to expose.

How the shared library is identified using the implementation search strategy will vary according to the OS.

  • On Windows, the dispatcher searches the following locations, in the specified order, to find the correct implementation library:

    1. The Driver Store directory for the current adapter. All types of graphics drivers can install libraries in this directory. Learn more about Driver Store.

    2. The directory specified for the current hardware under the registry key HKEY_CURRENT_USER\Software\Intel\MediaSDK\Dispatch.

    3. The directory specified for the current hardware under the registry key HKEY_LOCAL_MACHINE\Software\Intel\MediaSDK\Dispatch.

    4. The directory that is stored in these registry keys: C:Program FilesIntelMedia SDK. This directory is where legacy graphics drivers install libraries.

    5. The directory where the current module (the module that links the dispatcher) is located (only if the current module is a dll).

    After the dispatcher completes the main search, it additionally checks:

    1. The directory of the exe file of the current process, where it looks for software implementation only, regardless of which implementation the application requested.

    2. Default dll search. This provides loading from the directory of the application’s exe file and from the System32 and SysWOW64 directories. Learn more about default dll search order.

    3. The System32 and SysWOW64 directories, which is where DCH graphics drivers install libraries.

  • On Linux, the dispatcher searches the following locations, in the specified order, to find the correct implementation library:

    1. Directories provided by the environment variable LD_LIBRARY_PATH.

    2. Content of the /etc/ld.so.cache cache file.

    3. Default path /lib, then /usr/lib or /lib64, and then /usr/lib64 on some 64 bit OSs. On Debian: /usr/lib/x86_64-linux-gnu.

    4. SDK installation folder.

oneVPL Dispatcher#

The oneVPL dispatcher extends the legacy dispatcher by providing additional ability to select the appropriate implementation based on the implementation capabilities. Implementation capabilities include information about supported decoders, encoders, and VPP filters. For each supported encoder, decoder, and filter, capabilities include information about supported memory types, color formats, and image (frame) size in pixels.

The recommended approach to configure the dispatcher’s capabilities search filters and to create a session based on a suitable implementation is as follows:

  1. Create loader with MFXLoad().

  2. Create loader’s configuration with MFXCreateConfig().

  3. Add configuration properties with MFXSetConfigFilterProperty().

  4. Explore available implementations with MFXEnumImplementations().

  5. Create a suitable session with MFXCreateSession().

The procedure to terminate an application is as follows:

  1. Destroy session with MFXClose().

  2. Destroy loader with MFXUnload().

Note

Multiple loader instances can be created.

Note

Each loader may have multiple configuration objects associated with it. When a configuration object is modified through MFXSetConfigFilterProperty() it implicitly impacts the state and configuration of the associated loader.

Important

One configuration object can handle only one filter property.

Note

Multiple sessions can be created by using one loader object.

When the dispatcher searches for the implementation, it uses the following priority rules:

  1. Hardware implementation has priority over software implementation.

  2. General hardware implementation has priority over VSI hardware implementation.

  3. Highest API version has higher priority over lower API version.

Note

Implementation has priority over the API version. In other words, the dispatcher must return the implementation with the highest API priority (greater than or equal to the implementation requested).

How the shared library is identified using the implementation search strategy will vary according to the OS.

  • On Windows, the dispatcher searches the following locations, in the specified order, to find the correct implementation library:

    1. The Driver Store directory for all available adapters. All types of graphics drivers can install libraries in this directory. Learn more about Driver Store. Applicable only for Intel implementations.

    2. The directory of the exe file of the current process.

    3. Current working directory.

    4. PATH environmental variable.

    5. For backward compatibility with older spec versions, dispatcher also checks user-defined search folders which are provided by ONEVPL_SEARCH_PATH environmental variable.

  • On Linux, the dispatcher searches the following locations, in the specified order, to find the correct implementation library:

    1. Directories provided by the environment variable LD_LIBRARY_PATH.

    2. Default path /lib, then /usr/lib or /lib64, and then /usr/lib64 on some 64 bit OSs. On Debian: /usr/lib/x86_64-linux-gnu.

    3. Current working directory.

    4. For backward compatibility with older spec versions, dispatcher also checks user-defined search folders which are provided by ONEVPL_SEARCH_PATH environmental variable.

Important

To prioritize loading of custom oneVPL library, users may set environment variable ONEVPL_PRIORITY_PATH with the path to the user-defined folder. All libraries found in the ONEVPL_PRIORITY_PATH have the same priority (higher than any others, and HW/SW or API version rules are not applied) and should be loaded/filtered according to MFXSetConfigFilterProperty().

When oneVPL dispatcher searchers for the legacy Intel® Media Software Development Kit implementation it uses legacy dispatcher search order.

The dispatcher supports different software implementations. The user can use the mfxImplDescription::VendorID field, the mfxImplDescription::VendorImplID field, or the mfxImplDescription::ImplName field to search for the specific implementation.

Internally, the dispatcher works as follows:

  1. Dispatcher loads all shared libraries in the given search folders, whose names match any of the patterns in the following table:

    Windows 64-bit

    Windows 32-bit

    Linux 64-bit

    Description

    libvpl*.dll

    libvpl*.dll

    libvpl*.so*

    Runtime library for any platform

    libmfx64-gen.dll

    libmfx32-gen.dll

    libmfx-gen.so.1.2

    Runtime library for oneVPL for Intel® platforms with Xe architecture

    libmfxhw64.dll

    libmfxhw32.dll

    libmfxhw64.so.1

    Runtime library for Intel® Media Software Development Kit

  2. For each loaded library, the dispatcher tries to resolve address of the MFXQueryImplsDescription() function to collect the implementation’s capabilities.

  3. Once the user has requested to create the session based on this implementation, the dispatcher obtains addresses of each oneVPL function. See the Exported Functions/API Version table for the list of functions to export.

oneVPL Dispatcher Configuration Properties#

The Dispatcher Configuration Properties Table shows property strings supported by the dispatcher. Table organized in the hierarchy way, to create the string, go from the left to right from column to column and concatenate strings by using . (dot) as the separator.

Dispatcher Configuration Properties#

Structure name

Property

Value Data Type

Comment

mfxImplDescription

mfxImplDescription
.Impl

MFX_VARIANT_TYPE_U32

mfxImplDescription
.AccelerationMode

MFX_VARIANT_TYPE_U32

The mode will be used for session initialization

mfxImplDescription
.ApiVersion
.Version

MFX_VARIANT_TYPE_U32

mfxImplDescription
.ApiVersion
.Major

MFX_VARIANT_TYPE_U16

mfxImplDescription
.ApiVersion
.Minor

MFX_VARIANT_TYPE_U16

mfxImplDescription
.ImplName

MFX_VARIANT_TYPE_PTR

Pointer to the null-terminated string.

mfxImplDescription
.License

MFX_VARIANT_TYPE_PTR

Pointer to the null-terminated string.

mfxImplDescription
.Keywords

MFX_VARIANT_TYPE_PTR

Pointer to the null-terminated string.

mfxImplDescription
.VendorID

MFX_VARIANT_TYPE_U32

mfxImplDescription
.VendorImplID

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxSurfacePoolMode

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxDeviceDescription
.device
.DeviceID

MFX_VARIANT_TYPE_PTR

Pointer to the null-terminated string.

mfxImplDescription
.mfxDeviceDescription
.device
.MediaAdapterType

MFX_VARIANT_TYPE_U16

mfxImplDescription
.mfxDecoderDescription
.decoder
.CodecID

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxDecoderDescription
.decoder
.MaxcodecLevel

MFX_VARIANT_TYPE_U16

mfxImplDescription
.mfxDecoderDescription
.decoder
.decprofile
.Profile

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxDecoderDescription
.decoder
.decprofile
.Profile
.decmemdesc
.MemHandleType

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxDecoderDescription
.decoder
.decprofile
.Profile
.decmemdesc
.Width

MFX_VARIANT_TYPE_PTR

Pointer to the mfxRange32U object

mfxImplDescription
.mfxDecoderDescription
.decoder
.decprofile
.Profile
.decmemdesc
.Height

MFX_VARIANT_TYPE_PTR

Pointer to the mfxRange32U object

mfxImplDescription
.mfxDecoderDescription
.decoder
.decprofile
.Profile
.decmemdesc
.ColorFormats

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxEncoderDescription
.encoder
.CodecID

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxEncoderDescription
.encoder
.MaxcodecLevel

MFX_VARIANT_TYPE_U16

mfxImplDescription
.mfxEncoderDescription
.encoder
.BiDirectionalPrediction

MFX_VARIANT_TYPE_U16

mfxImplDescription
.mfxEncoderDescription
.encoder
.ReportedStats

MFX_VARIANT_TYPE_U16

mfxImplDescription
.mfxEncoderDescription
.encoder
.encprofile
.Profile

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxEncoderDescription
.encoder
.encprofile
.Profile
.encmemdesc
.MemHandleType

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxEncoderDescription
.encoder
.encprofile
.Profile
.encmemdesc
.Width

MFX_VARIANT_TYPE_PTR

Pointer to the mfxRange32U object

mfxImplDescription
.mfxEncoderDescription
.encoder
.encprofile
.Profile
.encmemdesc
.Height

MFX_VARIANT_TYPE_PTR

Pointer to the mfxRange32U object

mfxImplDescription
.mfxEncoderDescription
.encoder
.encprofile
.Profile
.encmemdesc
.ColorFormats

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxVPPDescription
.filter
.FilterFourCC

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxVPPDescription
.filter
.MaxDelayInFrames

MFX_VARIANT_TYPE_U16

mfxImplDescription
.mfxVPPDescription
.filter
.memdesc
.MemHandleType

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxVPPDescription
.filter
.memdesc
.Width

MFX_VARIANT_TYPE_PTR

Pointer to the mfxRange32U object

mfxImplDescription
.mfxVPPDescription
.filter
.memdesc
.Height

MFX_VARIANT_TYPE_PTR

Pointer to the mfxRange32U object

mfxImplDescription
.mfxVPPDescription
.filter
.memdesc
.format
.InFormat

MFX_VARIANT_TYPE_U32

mfxImplDescription
.mfxVPPDescription
.filter
.memdesc
.format
.OutFormats

MFX_VARIANT_TYPE_U32

mfxImplementedFunctions

mfxImplementedFunctions
.FunctionsName

MFX_VARIANT_TYPE_PTR

Pointer to the buffer with string

N/A

DXGIAdapterIndex


MFX_VARIANT_TYPE_U32

Adapter index according to IDXGIFactory::EnumAdapters

Important

DXGIAdapterIndex property is available for Windows only and filters only hardware implementations.

Examples of the property name strings:

  • mfxImplDescription.mfxDecoderDescription.decoder.decprofile.Profile

  • mfxImplDescription.mfxDecoderDescription.decoder.decprofile.decmemdesc.MemHandleType

  • mfxImplementedFunctions.FunctionsName

Following properties are supported in a special manner: they are used to send additional data to the implementation through the dispatcher. Application needs to use MFXSetConfigFilterProperty() to set them up but they don’t influence on the implementation selection. They are used during the MFXCreateSession() function call to fine tune the implementation.

Dispatcher’s Special Properties#

Property Name

Property Value

Value data type

mfxHandleType

mfxHandleType

mfxVariantType::MFX_VARIANT_TYPE_U32

mfxHDL

mfxHDL

mfxVariantType::MFX_VARIANT_TYPE_PTR

NumThread

Unsigned fixed-point integer value

mfxVariantType::MFX_VARIANT_TYPE_U32

DeviceCopy

Device copy

mfxVariantType::MFX_VARIANT_TYPE_U16

ExtBuffer

Pointer to the extension buffer

mfxVariantType::MFX_VARIANT_TYPE_PTR

oneVPL Dispatcher Interactions#

This sequence diagram visualize how application communicates with implementations via the dispatcher.

Dispatcher API

This API is implemented in the dispatcher.

Implementation API

This API is provided by the any implementation.

@startuml
actor Application as A
participant "oneVPL Dispatcher" as D
participant "oneVPL Implementation 1" as I1
participant "oneVPL Implementation 2" as I2
participant "oneVPL Implementation 3" as I3

ref over A, D : Dispatcher API
ref over D, I1, I2, I3 : Implementation API

activate A
== Initialization ==
group Dispatcher API [Enumerate and load implementations]
   A -> D: mfxLoad()
   activate D

   D -> D: Search for the available runtimes

   A -> D: MFXCreateConfig()
   A -> D: MFXSetConfigProperty()
   A -> D: MFXCreateConfig()
   A -> D: MFXSetConfigProperty()
   A -> D: MFXEnumImplementations()

   note right of A
   MFXEnumImplementations() may also be called
   after MFXCreateSession().
   end note

   Activate I1

   D -> I1: MFXQueryImplsDescription()
   I1 --> D: mfxImplDescription

   Activate I2
   D -> I2: MFXQueryImplsDescription()
   I2 --> D: mfxImplDescription

   Activate I3
   D -> I3: MFXQueryImplsDescription()
   I3 --> D: mfxImplDescription

   D --> A: list of mfxImplDescription structures es for all implementations

   A -> D: MFXCreateSession(i=0)
   D -> I1: MFXInitilize()
   Activate I1 #DarkSalmon
   I1 --> D: mfxSession1
   D --> A: mfxSession1

   A -> D: MFXCreateSession(i=1)
   D -> I2: MFXInitilize()
   Activate I2 #DarkSalmon
   I2 --> D: mfxSession2
   D --> A: mfxSession2

   A -> D: MFXCreateSession(i=2)
   D -> I3: MFXInitilize()
   I3 --> D: mfxSession3
   Activate I3 #DarkSalmon
   D --> A: mfxSession3

   A -> D: MFXDispReleaseImplDescription(hdl=0)
   D -> I1: MFXReleaseImplDescription()

   A -> D: MFXDispReleaseImplDescription(hdl=1)
   D -> I2: MFXReleaseImplDescription()

   A -> D: MFXDispReleaseImplDescription(hdl=2)
   D -> I3: MFXReleaseImplDescription()
end
== Processing ==
group Implementation API [Process the data]
   A -> I1: MFXVideoDECODE_Init()
   A -> I1: MFXVideoDECODE_Query()
   A -> I1: MFXVideoDECODE_DecodeFrameAsync()
   ...
   A -> I1: MFXVideoDECODE_Close()
   |||
   deactivate I1

   A -> I2: MFXVideoENCODE_Init()
   A -> I2: MFXVideoENCODE_Query()
   A -> I2: MFXVideoENCODE_EncodeFrameAsync()
   ...
   A -> I2: MFXVideoENCODE_Close()
   |||
   deactivate I2

   A -> I3: MFXVideoENCODE_Init()
   A -> I3: MFXVideoENCODE_Query()
   A -> I3: MFXVideoENCODE_EncodeFrameAsync()
   ...
   A -> I3: MFXVideoENCODE_Close()
   |||
   deactivate I3
end
== Finalization ==
group Implementation API [Release the implementations]
   A -> I1: MFXClose()
   deactivate I1
   A -> I2: MFXClose()
   deactivate I2
   A -> I3: MFXClose()
   deactivate I3
group Dispatcher API [Release the dispatcher's instance]
   A -> D: MFXUnload()
end

deactivate D
@enduml

The oneVPL dispatcher is capable to load and initialize Intel® Media Software Development Kit legacy library. The sequence diagram below demonstrates the approach.

@startuml
actor Application as A
participant "oneVPL Dispatcher" as D
participant "MediaSDK (legacy)" as M
A -> D: MFXLoad
activate D
D -> D: Search for the available runtimes
A -> D: MFXCreateConfig

note left of D
Setting properties to filter implementation.
MediaSDK supports only general parameters,
no filtering for Decode/VPP/Encoder details.
end note

group MediaSDK LegacyAPI
   D -> M: MFXInitEx
   activate M

   M --> D: mfxSession
   D -> M: MFXQueryIMPL
   M --> D: Implementation speciefic

   D -> M: MFXQueryVersion
   M --> D: mfxVersion
end

D -> D: Fill mfxImplDescription for MediaSDK impl

A -> D: mfxEnumImplementations
D --> A: MediaSDK caps description

A -> D: MFXCreateSession
D --> A: mfxSession

A -> M: MFXVideoDECODE_Init()
A -> M: MFXVideoDECODE_Query()
A -> M: MFXVideoDECODE_DecodeFrameAsync()
...
A -> M: MFXVideoDECODE_Close()
A -> M: MFXClose()

deactivate M

A -> D: MFXUnload()
deactivate D
@enduml

Important

The dispatcher doesn’t filter and report mfxDeviceDescription, mfxDecoderDescription, mfxEncoderDescription, mfxVPPDescription when enumerates or creates Intel® Media Software Development Kit implementation. Once Intel® Media Software Development Kit is loaded applications have to use legacy approach to query capabilities.

oneVPL Dispatcher Debug Log#

The debug output of the dispatcher is controlled with the ONEVPL_DISPATCHER_LOG environment variable. To enable log output, set the ONEVPL_DISPATCHER_LOG environment variable value equals to “ON”.

By default, oneVPL dispatcher prints all log messages to the console. To redirect log output to the desired file, set the ONEVPL_DISPATCHER_LOG_FILE environmental variable with the file name of the log file.

Examples of Dispatcher’s Usage#

This code illustrates simple usage of dispatcher to load first available library:

1mfxLoader loader = MFXLoad();
2MFXCreateSession(loader,0,&session);

This code illustrates simple usage of dispatcher to load first available HW accelerated library:

1mfxLoader loader = MFXLoad();
2mfxConfig cfg = MFXCreateConfig(loader);
3mfxVariant ImplValue;
4ImplValue.Type = MFX_VARIANT_TYPE_U32;
5ImplValue.Data.U32 = MFX_IMPL_TYPE_HARDWARE;
6MFXSetConfigFilterProperty(cfg,(const mfxU8 *)"mfxImplDescription.Impl",ImplValue);
7MFXCreateSession(loader,0,&session);

This code illustrates how multiple sessions from multiple loaders can be created:

 1// Create session with software based implementation
 2mfxLoader loader1 = MFXLoad();
 3mfxConfig cfg1 = MFXCreateConfig(loader1);
 4mfxVariant ImplValueSW;
 5ImplValueSW.Type = MFX_VARIANT_TYPE_U32;
 6ImplValueSW.Data.U32 = MFX_IMPL_TYPE_SOFTWARE;
 7MFXSetConfigFilterProperty(cfg1,(const mfxU8 *)"mfxImplDescription.Impl",ImplValueSW);
 8MFXCreateSession(loader1,0,&sessionSW);
 9
10// Create session with hardware based implementation
11mfxLoader loader2 = MFXLoad();
12mfxConfig cfg2 = MFXCreateConfig(loader2);
13mfxVariant ImplValueHW;
14ImplValueHW.Type = MFX_VARIANT_TYPE_U32;
15ImplValueHW.Data.U32 = MFX_IMPL_TYPE_HARDWARE;
16MFXSetConfigFilterProperty(cfg2,(const mfxU8 *)"mfxImplDescription.Impl",ImplValueHW);
17MFXCreateSession(loader2,0,&sessionHW);
18
19// use both sessionSW and sessionHW
20// ...
21// Close everything
22MFXClose(sessionSW);
23MFXClose(sessionHW);
24MFXUnload(loader1); // cfg1 will be destroyed here.
25MFXUnload(loader2); // cfg2 will be destroyed here.

This code illustrates how multiple decoders from single loader can be created:

 1mfxLoader loader = MFXLoad();
 2
 3// We want to have AVC decoder supported.
 4mfxConfig cfg1 = MFXCreateConfig(loader);
 5mfxVariant ImplValue;
 6ImplValue.Type = MFX_VARIANT_TYPE_U32;
 7ImplValue.Data.U32 = MFX_CODEC_AVC;
 8MFXSetConfigFilterProperty(cfg1,
 9            (const mfxU8 *)"mfxImplDescription.mfxDecoderDescription.decoder.CodecID",ImplValue);
10
11// And we want to have HEVC encoder supported by the same implementation.
12mfxConfig cfg2 = MFXCreateConfig(loader);
13ImplValue.Type = MFX_VARIANT_TYPE_U32;
14ImplValue.Data.U32 = MFX_CODEC_HEVC;
15MFXSetConfigFilterProperty(cfg2,
16            (const mfxU8 *)"mfxImplDescription.mfxEncoderDescription.encoder.CodecID",ImplValue);
17
18// To create single session with both capabilities.
19MFXCreateSession(loader,0,&session);

How To Check If Function is Implemented#

There are two ways to check if particular function is implemented or not by the implementation.

This code illustrates how application can iterate through the whole list of implemented functions:

 1mfxHDL h;
 2// request pointer to the list. Assume that implementation supports that.
 3// Assume that `loader` is configured before.
 4mfxStatus sts = MFXEnumImplementations(loader, idx, MFX_IMPLCAPS_IMPLEMENTEDFUNCTIONS, &h);
 5// break if no idx
 6if (sts != MFX_ERR_NOT_FOUND) {
 7  // Cast typeless handle to structure pointer
 8  mfxImplementedFunctions *implemented_functions = (mfxImplementedFunctions*)h;
 9
10  // print out list of functions' name
11  std::for_each(implemented_functions->FunctionsName, implemented_functions->FunctionsName +
12                                                      implemented_functions->NumFunctions,
13          [](mfxChar*  functionName) {
14              std::cout << functionName << " is implemented" << std::endl;
15          });
16  // Release resource
17  MFXDispReleaseImplDescription(loader, h);
18}

This code illustrates how application can check that specific functions are implemented:

 1mfxSession session_handle;
 2loader = mfxLoader();
 3
 4// We want to search for the implementation with Decode+VPP domain functions support.
 5// i.e we search for the MFXVideoDECODE_VPP_Init and MFXVideoDECODE_VPP_DecodeFrameAsync
 6// implemented functions
 7mfxConfig init_funct_prop = MFXCreateConfig(loader);
 8mfxVariant value;
 9
10// Filter property for the Init function
11value.Type = mfxVariantType::MFX_VARIANT_TYPE_PTR;
12value.Data.Ptr = (mfxHDL)"MFXVideoDECODE_VPP_Init";
13MFXSetConfigFilterProperty(init_funct_prop, (const mfxU8*)"mfxImplementedFunctions.FunctionsName",
14                           value);
15
16// Filter property for the Process function
17mfxConfig process_func_prop = MFXCreateConfig(loader);
18value.Data.Ptr = (mfxHDL)"MFXVideoDECODE_VPP_DecodeFrameAsync";
19MFXSetConfigFilterProperty(process_func_prop, (const mfxU8*)"mfxImplementedFunctions.FunctionsName",
20                           value);
21
22// create session from first matched implementation
23MFXCreateSession(loader, 0, &session_handle);

How To Search For The Available encoder/decoder implementation#

The CodecFormatFourCC enum specifies codec’s FourCC values. Application needs to assign this value to the field of mfxDecoderDescription::decoder::CodecID to search for the decoder or mfxEncoderDescription::encoder::CodecID to search for the encoder.

This code illustrates decoder’s implementation search procedure:

 1mfxSession hevc_session_handle;
 2loader = mfxLoader();
 3
 4// We want to search for the HEVC decoder implementation
 5mfxConfig hevc_decoder_config = MFXCreateConfig(loader);
 6mfxVariant value;
 7
 8// Filter property for the implementations with HEVC decoder
 9value.Type     = MFX_VARIANT_TYPE_U32;
10value.Data.U32 = MFX_CODEC_HEVC;
11
12MFXSetConfigFilterProperty(hevc_decoder_config
13      , (const mfxU8*)"mfxImplDescription.mfxDecoderDescription.decoder.CodecID"
14      , value);
15
16// create session from first matched implementation
17MFXCreateSession(loader, 0, &hevc_session_handle);

How To Search For The Available VPP Filter implementation#

Each VPP filter identified by the filter ID. Filter ID is defined by corresponding to the filter extension buffer ID value which is defined in a form of FourCC value. Filter ID values are subset of the general ExtendedBufferID enum. The table references available IDs of VPP filters to search. Application needs to assign this value to the field of mfxVPPDescription::filter::FilterFourCC to search for the needed VPP filter.

VPP Filters ID#

Filter ID

Description

MFX_EXTBUFF_VPP_DENOISE2

Denoise filter

MFX_EXTBUFF_VPP_MCTF

Motion-Compensated Temporal Filter (MCTF).

MFX_EXTBUFF_VPP_DETAIL

Detail/edge enhancement filter.

MFX_EXTBUFF_VPP_FRAME_RATE_CONVERSION

Frame rate conversion filter

MFX_EXTBUFF_VPP_IMAGE_STABILIZATION

Image stabilization filter

MFX_EXTBUFF_VPP_PROCAMP

ProcAmp filter

MFX_EXTBUFF_VPP_FIELD_PROCESSING

Field processing filter

MFX_EXTBUFF_VPP_COLOR_CONVERSION

Color Conversion filter

MFX_EXTBUFF_VPP_SCALING

Resize filter

MFX_EXTBUFF_VPP_COMPOSITE

Surfaces composition filter

MFX_EXTBUFF_VPP_DEINTERLACING

Deinterlace filter

MFX_EXTBUFF_VPP_ROTATION

Rotation filter

MFX_EXTBUFF_VPP_MIRRORING

Mirror filter

MFX_EXTBUFF_VPP_COLORFILL

ColorFill filter

This code illustrates VPP mirror filter implementation search procedure:

 1mfxSession mirror_session_handle;
 2loader = mfxLoader();
 3
 4// We want to search for the VPP mirror implementation
 5mfxConfig  mirror_flt_config = MFXCreateConfig(loader);
 6mfxVariant value;
 7
 8// Filter property for the implementations with VPP mirror
 9value.Type     = MFX_VARIANT_TYPE_U32;
10value.Data.U32 = MFX_EXTBUFF_VPP_MIRRORING;
11
12MFXSetConfigFilterProperty(mirror_flt_config
13      , (const mfxU8*)"mfxImplDescription.mfxVPPDescription.filter.FilterFourCC"
14      , value);
15
16// create session from first matched implementation
17MFXCreateSession(loader, 0, &mirror_session_handle);

How To Get Path to the Shared Library With the Implementation#

Sessions can be created from different implementations, each implementations can be located in different shared libraries. To get path of the shared library with the implementation from which session can be or was created, application can use MFXEnumImplementations() and pass MFX_IMPLCAPS_IMPLPATH value as the output data request.

This code illustrates collection and print out path of implementations’s shared library:

 1mfxHDL h;
 2mfxSession def_session;
 3
 4loader = mfxLoader();
 5
 6// Create session from the first available implementation.
 7// That's why we no any filters need to be set.
 8// First available implementation has index equal to the 0.
 9MFXCreateSession(loader, 0, &def_session);
10
11// Get and print out OS path to the loaded shared library
12// with the implementation. It is absolutely OK to call
13// MFXEnumImplementations after session creation just need to make
14// sure that the same index of implementation is provided to the
15// function call.
16MFXEnumImplementations(loader, 0, MFX_IMPLCAPS_IMPLPATH, &h);
17mfxChar* path = reinterpret_cast<mfxChar*>(h);
18
19// Print out the path
20std::cout << "Loaded shared library: " << path << std::endl;
21
22// Release the memory for the string with path.
23MFXDispReleaseImplDescription(loader, h);

oneVPL implementation on Intel® platforms with Xe architecture and Intel® Media Software Development Kit Coexistence#

oneVPL supersedes Intel® Media Software Development Kit and is partially binary compatible with Intel® Media Software Development Kit. Both oneVPL and Intel® Media Software Development Kit includes own dispatcher and implementation. Coexistence of oneVPL and Intel® Media Software Development Kit dispatchers and implementations on single system is allowed until Intel® Media Software Development Kit is not EOL.

Usage of the following combinations of dispatchers and implementations within the single application is permitted for the legacy purposes only. In that scenario legacy applications developed with Intel® Media Software Development Kit will continue to work on any HW supported either by Intel® Media Software Development Kit or by the oneVPL.

Attention

Any application to work with the oneVPL API starting from version 2.0 must use only oneVPL dispatcher.

Intel® Media Software Development Kit API

Intel® Media Software Development Kit API of 1.x version.

Removed API

Intel® Media Software Development Kit API which is removed from oneVPL.

Core API

Intel® Media Software Development Kit API without removed API.

oneVPL API

New API introduced in oneVPL only started from API 2.0 version.

oneVPL Dispatcher API

Dispatcher API introduced in oneVPL in 2.0 API version. This is subset of oneVPL API.

oneVPL for Intel® platforms with Xe architecture and Intel® Media Software Development Kit#

Dispatcher

Installed on the device

Loaded

Allowed API

oneVPL

oneVPL for Intel® platforms with Xe architecture

oneVPL for Intel® platforms with Xe architecture

Usage of any API except removed API is allowed.

oneVPL

Intel® Media Software Development Kit

Intel® Media Software Development Kit

Usage of core API plus dispatcher API is allowed only.

oneVPL

oneVPL for Intel® platforms with Xe architecture and Intel® Media Software Development Kit

oneVPL for Intel® platforms with Xe architecture

Usage of any API except removed API is allowed.

Intel® Media Software Development Kit

oneVPL for Intel® platforms with Xe architecture

oneVPL for Intel® platforms with Xe architecture

Usage of core API is allowed only.

Intel® Media Software Development Kit

oneVPL for Intel® platforms with Xe architecture and Intel® Media Software Development Kit

Intel® Media Software Development Kit

Usage of Intel® Media Software Development Kit API is allowed.

Intel® Media Software Development Kit

Intel® Media Software Development Kit

Intel® Media Software Development Kit

Usage of Intel® Media Software Development Kit API is allowed.

Note

if system has multiple devices the logic of selection and loading implementations will be applied to each device accordingly to the system enumeration.

Multiple Sessions#

Each oneVPL session can run exactly one instance of the DECODE, ENCODE, and VPP functions. This is adequate for a simple transcoding operation. If the application needs more than one instance of DECODE, ENCODE, or VPP in a complex transcoding setting or needs more simultaneous transcoding operations, the application can initialize multiple oneVPL sessions created from one or several oneVPL implementations.

The application can use multiple oneVPL sessions independently or run a “joined” session. To join two sessions together, the application can use the function MFXJoinSession(). Alternatively, the application can use the MFXCloneSession() function to duplicate an existing session. Joined oneVPL sessions work together as a single session, sharing all session resources, threading control, and prioritization operations except hardware acceleration devices and external allocators. When joined, the first session (first join) serves as the parent session and will schedule execution resources with all other child sessions. Child sessions rely on the parent session for resource management.

Important

Applications can join sessions created from the same oneVPL implementation only.

With joined sessions, the application can set the priority of session operations through the MFXSetPriority() function. A lower priority session receives fewer CPU cycles. Session priority does not affect hardware accelerated processing.

After the completion of all session operations, the application can use the MFXDisjoinSession() function to remove the joined state of a session. Do not close the parent session until all child sessions are disjoined or closed.