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, or 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().

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 :file`/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).

The dispatcher searches for the implementation in the following folders at runtime, in priority order:

  1. User-defined search folders.

  2. oneVPL package.

  3. Path from PATH or LD_LIBRARY_PATH environmental variables, depending on OS.

  4. Default system folders.

  5. Standalone Intel® Media Software Development Kit package (or driver).

For more details, see the legacy dispatcher search order.

A user can develop their own implementation and direct the oneVPL dispatcher to load their implementation by providing a list of search folders. The specific steps depend on which OS is used.

  • Linux: User can provide a colon separated list of folders in the ONEVPL_SEARCH_PATH environmental variable.

  • Windows: User can provide a semicolon separated list of folders in the ONEVPL_SEARCH_PATH environmental variable. Alternatively, the user can use the Windows registry.

Dispatcher Environmental Variables

Variable

Purpose

ONEVPL_SEARCH_PATH

List of user-defined search folders used by the dispatcher during implementation search.

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 any shared library within the given search folders.

  2. For each loaded library, the dispatcher tries to resolve address of the MFXQueryImplsCapabilities() 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.

Note

For backward compatibility with Intel® Media Software Development Kit, dispatcher will try to load Intel® Media Software Development Kit first, if 1.x was requested to be loaded. If loading was failed, dispatcher will search for the implementation with highest 2.x API version.

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 to balance CPU/GPU workloads, the application can initialize multiple oneVPL sessions. Each independent oneVPL session can be a software-based session or hardware-based session.

The application can use multiple oneVPL sessions independently or run a “joined” session. Independently operated oneVPL sessions cannot share data unless the application explicitly synchronizes session operations. This is to ensure that data is valid and complete before passing from the source to the destination 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.

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.