Debian Codegraph @

doc/spec/source/programming_guide/VPL_prg_session.rst

raw
1 .. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
2 ..
3 .. SPDX-License-Identifier: CC-BY-4.0
4 ..
5 Intel® Video Processing Library (Intel® VPL)
6 .. _sdk-session:
7
8 ========================
9 |vpl_short_name| Session
10 ========================
11
12 Before calling any |vpl_short_name| functions, the application must initialize the
13 library and create a |vpl_short_name| session. A |vpl_short_name| session maintains context for the
14 use of any of :term:`DECODE`, :term:`ENCODE`, :term:`VPP`, :term:`DECODE_VPP`
15 functions.
16
17 ------------------------------------
18 |msdk_full_name| Dispatcher (Legacy)
19 ------------------------------------
20
21 The :cpp:func:`MFXInit` or :cpp:func:`MFXInitEx` function starts (initializes)
22 a session. The :cpp:func:`MFXClose` function closes (de-initializes) the
23 session. To avoid memory leaks, always call :cpp:func:`MFXClose` after
24 :cpp:func:`MFXInit`.
25
26 .. important:: :cpp:func:`MFXInit` and :cpp:func:`MFXInitEx` are deprecated
27 starting from API 2.0. Applications must use :cpp:func:`MFXLoad`
28 and :cpp:func:`MFXCreateSession` to initialize implementations.
29
30 .. important:: For backward compatibility with existent |msdk_full_name|
31 applications |vpl_short_name| session can be created and initialized by
32 the legacy dispatcher through :cpp:func:`MFXInit` or
33 :cpp:func:`MFXInitEx` calls. In this case, the reported API version
34 will be 1.255 on |intel_r| platforms with X\ :sup:`e` architecture.
35
36 The application can initialize a session as a software-based session
37 (:cpp:enumerator:`MFX_IMPL_SOFTWARE`) or a hardware-based session
38 (:cpp:enumerator:`MFX_IMPL_HARDWARE`). In a software-based session, the SDK
39 functions execute on a CPU. In a hardware-base session, the SDK functions
40 use platform acceleration capabilities. For platforms that expose multiple
41 graphic devices, the application can initialize a session on any
42 alternative graphic device using the :cpp:enumerator:`MFX_IMPL_HARDWARE`,
43 :cpp:enumerator:`MFX_IMPL_HARDWARE2`, :cpp:enumerator:`MFX_IMPL_HARDWARE3`, or
44 :cpp:enumerator:`MFX_IMPL_HARDWARE4` values of :cpp:type:`mfxIMPL`.
45
46 The application can also initialize a session to be automatic (
47 :cpp:enumerator:`MFX_IMPL_AUTO` or :cpp:enumerator:`MFX_IMPL_AUTO_ANY`),
48 instructing the dispatcher library to detect the platform capabilities and
49 choose the best SDK library available. After initialization, the SDK returns the
50 actual implementation through the :cpp:func:`MFXQueryIMPL` function.
51
52 Internally, the dispatcher works as follows:
53
54 #. Dispatcher searches for the shared library with the specific name:
55
56 ========= =============== ====================================
57 **OS** **Name** **Description**
58 ========= =============== ====================================
59 Linux\* libmfxsw64.so.1 64-bit software-based implementation
60 Linux libmfxsw32.so.1 32-bit software-based implementation
61 Linux libmfxhw64.so.1 64-bit hardware-based implementation
62 Linux libmfxhw64.so.1 32-bit hardware-based implementation
63 Windows\* libmfxsw32.dll 64-bit software-based implementation
64 Windows libmfxsw32.dll 32-bit software-based implementation
65 Windows libmfxhw64.dll 64-bit hardware-based implementation
66 Windows libmfxhw64.dll 32-bit hardware-based implementation
67 ========= =============== ====================================
68
69 #. Once the library is loaded, the dispatcher obtains addresses for each SDK
70 function. See the
71 :ref:`Exported Functions/API Version table <export-func-version-table-2x>` for
72 the list of functions to expose.
73
74 .. _legacy_search_order:
75
76 How the shared library is identified using the implementation search strategy
77 will vary according to the OS.
78
79 * On Windows, the dispatcher searches the following locations, in the specified
80 order, to find the correct implementation library:
81
82 #. The :file:`Driver Store` directory for the current adapter.
83 All types of graphics drivers can install libraries in this directory. `Learn more about Driver Store <https://docs.microsoft.com/en-us/windows-hardware/drivers/install/driver-store>`__.
84 #. The directory specified for the current hardware under the registry key
85 ``HKEY_CURRENT_USER\Software\Intel\MediaSDK\Dispatch``.
86 #. The directory specified for the current hardware under the registry key
87 ``HKEY_LOCAL_MACHINE\Software\Intel\MediaSDK\Dispatch``.
88 #. The directory that is stored in these registry keys: :file:`C:\Program Files\Intel\Media SDK`.
89 This directory is where legacy graphics drivers install libraries.
90 #. The directory where the current module (the module that links the dispatcher)
91 is located (only if the current module is a dll).
92
93 After the dispatcher completes the main search, it additionally checks:
94
95 #. The directory of the exe file of the current process, where it looks for
96 software implementation only, regardless of which implementation the
97 application requested.
98 #. Default dll search. This provides loading from the directory of the
99 application's exe file and from the :file:`System32` and :file:`SysWOW64`
100 directories. `Learn more about default dll search order <https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order?redirectedfrom=MSDN#search-order-for-desktop-applications>`__.
101 #. The :file:`System32` and :file:`SysWOW64` directories, which is where DCH
102 graphics drivers install libraries.
103
104 * On Linux, the dispatcher searches the following locations, in the specified
105 order, to find the correct implementation library:
106
107 #. Directories provided by the environment variable ``LD_LIBRARY_PATH``.
108 #. Content of the :file:`/etc/ld.so.cache` cache file.
109 #. Default path :file:`/lib`, then :file:`/usr/lib` or :file:`/lib64`, and then
110 :file:`/usr/lib64` on some 64 bit OSs. On Debian: :file:`/usr/lib/x86_64-linux-gnu`.
111 #. SDK installation folder.
112
113
114 .. _vpl-dispatcher:
115
116 ---------------------------
117 |vpl_short_name| Dispatcher
118 ---------------------------
119
120 The |vpl_short_name| dispatcher extends the legacy dispatcher by providing additional
121 ability to select the appropriate implementation based on the implementation
122 capabilities. Implementation capabilities include information about supported
123 decoders, encoders, and VPP filters. For each supported encoder, decoder, and
124 filter, capabilities include information about supported memory types, color
125 formats, and image (frame) size in pixels.
126
127 The recommended approach to configure the dispatcher's capabilities
128 search filters and to create a session based on a suitable implementation is as
129 follows:
130
131 #. Create loader with :cpp:func:`MFXLoad`.
132 #. Create loader's configuration with :cpp:func:`MFXCreateConfig`.
133 #. Add configuration properties with :cpp:func:`MFXSetConfigFilterProperty`.
134 #. Explore available implementations with :cpp:func:`MFXEnumImplementations`.
135 #. Create a suitable session with :cpp:func:`MFXCreateSession`.
136
137 The procedure to terminate an application is as follows:
138
139 #. Destroy session with :cpp:func:`MFXClose`.
140 #. Destroy loader with :cpp:func:`MFXUnload`.
141
142 .. note:: Multiple loader instances can be created.
143
144 .. note:: Each loader may have multiple configuration objects associated with it.
145 When a configuration object is modified through :cpp:func:`MFXSetConfigFilterProperty`
146 it implicitly impacts the state and configuration of the associated loader.
147
148 .. important:: One configuration object can handle only one filter property.
149
150 .. note:: Multiple sessions can be created by using one loader object.
151
152 When the dispatcher searches for the implementation, it uses the following
153 priority rules:
154
155 #. Hardware implementation has priority over software implementation.
156 #. General hardware implementation has priority over VSI hardware implementation.
157 #. Highest API version has higher priority over lower API version.
158
159 .. note:: Implementation has priority over the API version. In other words, the
160 dispatcher must return the implementation with the highest API
161 priority (greater than or equal to the implementation requested).
162
163 How the shared library is identified using the implementation search strategy
164 will vary according to the OS.
165
166 * On Windows, the dispatcher searches the following locations, in the specified
167 order, to find the correct implementation library:
168
169 #. The :file:`Driver Store` directory for all available adapters.
170 All types of graphics drivers can install libraries in this directory. `Learn more about Driver Store <https://docs.microsoft.com/en-us/windows-hardware/drivers/install/driver-store>`__.
171 Applicable only for Intel implementations.
172 #. The directory of the exe file of the current process.
173 #. `PATH` environmental variable.
174 #. For backward compatibility with older spec versions, dispatcher also checks
175 user-defined search folders which are provided by `ONEVPL_SEARCH_PATH`
176 environmental variable.
177
178 * On Linux, the dispatcher searches the following locations, in the specified
179 order, to find the correct implementation library:
180
181 #. Directories provided by the environment variable ``LD_LIBRARY_PATH``.
182 #. Default path :file:`/lib`, then :file:`/usr/lib` or :file:`/lib64`, and then
183 :file:`/usr/lib64` on some 64 bit OSs. On Debian: :file:`/usr/lib/x86_64-linux-gnu`.
184 #. For backward compatibility with older spec versions, dispatcher also checks
185 user-defined search folders which are provided by `ONEVPL_SEARCH_PATH`
186 environmental variable.
187 #. Optional: Library installation directory specified by ``CMAKE_INSTALL_FULL_LIBDIR``,
188 if and only if the project is configured with ``-D ENABLE_LIBDIR_IN_RUNTIME_SEARCH=ON``
189 during cmake configuration (default = OFF).
190
191 .. important:: To prioritize loading of custom |vpl_short_name| library, users may set environment variable
192 `ONEVPL_PRIORITY_PATH` with the path to the user-defined folder.
193 All libraries found in the ONEVPL_PRIORITY_PATH have the same priority
194 (higher than any others, and HW/SW or API version rules are not applied) and
195 should be loaded/filtered according to :cpp:func:`MFXSetConfigFilterProperty`.
196
197 When |vpl_short_name| dispatcher searchers for the legacy |msdk_full_name|
198 implementation it uses :ref:`legacy dispatcher search order <legacy_search_order>`,
199 excluding the current working directory and :file:`/etc/ld.so.cache`.
200
201 The dispatcher supports different software implementations. The user can use
202 the :cpp:member:`mfxImplDescription::VendorID` field, the
203 :cpp:member:`mfxImplDescription::VendorImplID` field, or the
204 :cpp:member:`mfxImplDescription::ImplName` field to search for the specific
205 implementation.
206
207 Internally, the dispatcher works as follows:
208
209 #. Dispatcher loads all shared libraries in the given search folders, whose names
210 match any of the patterns in the following table:
211
212 ================== ================== ================= =========================================
213 Windows 64-bit Windows 32-bit Linux 64-bit Description
214 ================== ================== ================= =========================================
215 libvpl\*.dll libvpl\*.dll libvpl\*.so\* Runtime library for any platform
216 libmfx64-gen.dll libmfx32-gen.dll libmfx-gen.so.1.2 Runtime library for |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture
217 libmfxhw64.dll libmfxhw32.dll libmfxhw64.so.1 Runtime library for |msdk_full_name|
218 ================== ================== ================= =========================================
219
220 #. For each loaded library, the dispatcher tries to resolve address of the
221 :cpp:func:`MFXQueryImplsDescription` function to collect the implementation's
222 capabilities.
223 #. Once the user has requested to create the session based on this implementation,
224 the dispatcher obtains addresses of each |vpl_short_name| function. See the
225 :ref:`Exported Functions/API Version table <export-func-version-table-2x>` for
226 the list of functions to export.
227
228 ----------------------------------------------------
229 |vpl_short_name| Dispatcher Configuration Properties
230 ----------------------------------------------------
231
232 The :ref:`Dispatcher Configuration Properties Table <dsp-conf-prop-table>` shows property strings
233 supported by the dispatcher. Table organized in the hierarchy way, to create the string, go from the
234 left to right from column to column and concatenate strings by using `.` (dot) as the separator.
235
236 .. _dsp-conf-prop-table:
237
238 .. container:: stripe-table
239
240 .. table:: Dispatcher Configuration Properties
241 :widths: 25 25 30 20
242
243 +---------------------------------------+----------------------------+----------------------+---------------------------+
244 | Structure name | Property | Value Data Type | Comment |
245 +=======================================+============================+======================+===========================+
246 | :cpp:struct:`mfxImplDescription` | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
247 | | | .Impl | | |
248 | +----------------------------+----------------------+---------------------------+
249 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | The mode will be used for |
250 | | | .AccelerationMode | | session initialization |
251 | +----------------------------+----------------------+---------------------------+
252 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
253 | | | .ApiVersion | | |
254 | | | .Version | | |
255 | +----------------------------+----------------------+---------------------------+
256 | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | |
257 | | | .ApiVersion | | |
258 | | | .Major | | |
259 | +----------------------------+----------------------+---------------------------+
260 | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | |
261 | | | .ApiVersion | | |
262 | | | .Minor | | |
263 | +----------------------------+----------------------+---------------------------+
264 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
265 | | | .ImplName | | null-terminated string. |
266 | +----------------------------+----------------------+---------------------------+
267 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
268 | | | .License | | null-terminated string. |
269 | +----------------------------+----------------------+---------------------------+
270 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
271 | | | .Keywords | | null-terminated string. |
272 | +----------------------------+----------------------+---------------------------+
273 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
274 | | | .VendorID | | |
275 | +----------------------------+----------------------+---------------------------+
276 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
277 | | | .VendorImplID | | |
278 | +----------------------------+----------------------+---------------------------+
279 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
280 | | | .mfxSurfacePoolMode | | |
281 | +----------------------------+----------------------+---------------------------+
282 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
283 | | | .mfxDeviceDescription | | null-terminated string. |
284 | | | .device | | |
285 | | | .DeviceID | | |
286 | +----------------------------+----------------------+---------------------------+
287 | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | |
288 | | | .mfxDeviceDescription | | |
289 | | | .device | | |
290 | | | .MediaAdapterType | | |
291 | +----------------------------+----------------------+---------------------------+
292 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
293 | | | .mfxDecoderDescription | | |
294 | | | .decoder | | |
295 | | | .CodecID | | |
296 | +----------------------------+----------------------+---------------------------+
297 | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | |
298 | | | .mfxDecoderDescription | | |
299 | | | .decoder | | |
300 | | | .MaxcodecLevel | | |
301 | +----------------------------+----------------------+---------------------------+
302 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
303 | | | .mfxDecoderDescription | | |
304 | | | .decoder | | |
305 | | | .decprofile | | |
306 | | | .Profile | | |
307 | +----------------------------+----------------------+---------------------------+
308 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
309 | | | .mfxDecoderDescription | | |
310 | | | .decoder | | |
311 | | | .decprofile | | |
312 | | | .Profile | | |
313 | | | .decmemdesc | | |
314 | | | .MemHandleType | | |
315 | +----------------------------+----------------------+---------------------------+
316 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
317 | | | .mfxDecoderDescription | | :cpp:struct:`mfxRange32U` |
318 | | | .decoder | | object |
319 | | | .decprofile | | |
320 | | | .Profile | | |
321 | | | .decmemdesc | | |
322 | | | .Width | | |
323 | +----------------------------+----------------------+---------------------------+
324 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
325 | | | .mfxDecoderDescription | | :cpp:struct:`mfxRange32U` |
326 | | | .decoder | | object |
327 | | | .decprofile | | |
328 | | | .Profile | | |
329 | | | .decmemdesc | | |
330 | | | .Height | | |
331 | +----------------------------+----------------------+---------------------------+
332 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
333 | | | .mfxDecoderDescription | | |
334 | | | .decoder | | |
335 | | | .decprofile | | |
336 | | | .Profile | | |
337 | | | .decmemdesc | | |
338 | | | .ColorFormats | | |
339 | +----------------------------+----------------------+---------------------------+
340 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
341 | | | .mfxEncoderDescription | | |
342 | | | .encoder | | |
343 | | | .CodecID | | |
344 | +----------------------------+----------------------+---------------------------+
345 | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | |
346 | | | .mfxEncoderDescription | | |
347 | | | .encoder | | |
348 | | | .MaxcodecLevel | | |
349 | +----------------------------+----------------------+---------------------------+
350 | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | |
351 | | | .mfxEncoderDescription | | |
352 | | | .encoder | | |
353 | | | .BiDirectionalPrediction | | |
354 | +----------------------------+----------------------+---------------------------+
355 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
356 | | | .mfxEncoderDescription | | |
357 | | | .encoder | | |
358 | | | .encprofile | | |
359 | | | .Profile | | |
360 | +----------------------------+----------------------+---------------------------+
361 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
362 | | | .mfxEncoderDescription | | |
363 | | | .encoder | | |
364 | | | .encprofile | | |
365 | | | .Profile | | |
366 | | | .encmemdesc | | |
367 | | | .MemHandleType | | |
368 | +----------------------------+----------------------+---------------------------+
369 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
370 | | | .mfxEncoderDescription | | :cpp:struct:`mfxRange32U` |
371 | | | .encoder | | object |
372 | | | .encprofile | | |
373 | | | .Profile | | |
374 | | | .encmemdesc | | |
375 | | | .Width | | |
376 | +----------------------------+----------------------+---------------------------+
377 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
378 | | | .mfxEncoderDescription | | :cpp:struct:`mfxRange32U` |
379 | | | .encoder | | object |
380 | | | .encprofile | | |
381 | | | .Profile | | |
382 | | | .encmemdesc | | |
383 | | | .Height | | |
384 | +----------------------------+----------------------+---------------------------+
385 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
386 | | | .mfxEncoderDescription | | |
387 | | | .encoder | | |
388 | | | .encprofile | | |
389 | | | .Profile | | |
390 | | | .encmemdesc | | |
391 | | | .ColorFormats | | |
392 | +----------------------------+----------------------+---------------------------+
393 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
394 | | | .mfxVPPDescription | | |
395 | | | .filter | | |
396 | | | .FilterFourCC | | |
397 | +----------------------------+----------------------+---------------------------+
398 | | | mfxImplDescription | MFX_VARIANT_TYPE_U16 | |
399 | | | .mfxVPPDescription | | |
400 | | | .filter | | |
401 | | | .MaxDelayInFrames | | |
402 | +----------------------------+----------------------+---------------------------+
403 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
404 | | | .mfxVPPDescription | | |
405 | | | .filter | | |
406 | | | .memdesc | | |
407 | | | .MemHandleType | | |
408 | +----------------------------+----------------------+---------------------------+
409 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
410 | | | .mfxVPPDescription | | :cpp:struct:`mfxRange32U` |
411 | | | .filter | | object |
412 | | | .memdesc | | |
413 | | | .Width | | |
414 | +----------------------------+----------------------+---------------------------+
415 | | | mfxImplDescription | MFX_VARIANT_TYPE_PTR | Pointer to the |
416 | | | .mfxVPPDescription | | :cpp:struct:`mfxRange32U` |
417 | | | .filter | | object |
418 | | | .memdesc | | |
419 | | | .Height | | |
420 | +----------------------------+----------------------+---------------------------+
421 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
422 | | | .mfxVPPDescription | | |
423 | | | .filter | | |
424 | | | .memdesc | | |
425 | | | .format | | |
426 | | | .InFormat | | |
427 | +----------------------------+----------------------+---------------------------+
428 | | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | |
429 | | | .mfxVPPDescription | | |
430 | | | .filter | | |
431 | | | .memdesc | | |
432 | | | .format | | |
433 | | | .OutFormats | | |
434 +---------------------------------------+----------------------------+----------------------+---------------------------+
435 | :cpp:struct:`mfxImplementedFunctions` | | mfxImplementedFunctions | MFX_VARIANT_TYPE_PTR | Pointer to the buffer |
436 | | | .FunctionsName | | with string |
437 +---------------------------------------+----------------------------+----------------------+---------------------------+
438 | N/A | | DXGIAdapterIndex | MFX_VARIANT_TYPE_U32 | Adapter index according |
439 | | | | | to |
440 | | | | | IDXGIFactory::EnumAdapters|
441 +---------------------------------------+----------------------------+----------------------+---------------------------+
442
443 .. important:: DXGIAdapterIndex property is available for Windows only and filters only hardware implementations.
444
445 Examples of the property name strings:
446
447 - mfxImplDescription.mfxDecoderDescription.decoder.decprofile.Profile
448 - mfxImplDescription.mfxDecoderDescription.decoder.decprofile.decmemdesc.MemHandleType
449 - mfxImplementedFunctions.FunctionsName
450
451 Following properties are supported in a special manner: they are used to send
452 additional data to the implementation through the dispatcher. Application needs
453 to use :cpp:func:`MFXSetConfigFilterProperty` to set them up but they don't
454 influence on the implementation selection. They are used during the
455 :cpp:func:`MFXCreateSession` function call to fine tune the implementation.
456
457 .. list-table:: Dispatcher's Special Properties
458 :header-rows: 1
459 :widths: auto
460
461 * - **Property Name**
462 - **Property Value**
463 - **Value data type**
464 * - mfxHandleType
465 - :cpp:enum:`mfxHandleType`
466 - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_U32`
467 * - mfxHDL
468 - :cpp:type:`mfxHDL`
469 - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_PTR`
470 * - NumThread
471 - Unsigned fixed-point integer value
472 - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_U32`
473 * - DeviceCopy
474 - :ref:`Device copy <gpu_copy>`
475 - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_U16`
476 * - ExtBuffer
477 - Pointer to the extension buffer
478 - :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_PTR`
479
480 .. _vpl-dispatcher-interactions:
481
482 ----------------------------------------
483 |vpl_short_name| Dispatcher Interactions
484 ----------------------------------------
485
486 This sequence diagram visualize how application communicates with implementations
487 via the dispatcher.
488
489 Dispatcher API
490 This API is implemented in the dispatcher.
491
492 Implementation API
493 This API is provided by the any implementation.
494
495 .. uml::
496
497 @startuml
498 actor Application as A
499 participant "Intel® VPL Dispatcher" as D
500 participant "Intel® VPL Implementation 1" as I1
501 participant "Intel® VPL Implementation 2" as I2
502 participant "Intel® VPL Implementation 3" as I3
503
504 ref over A, D : Dispatcher API
505 ref over D, I1, I2, I3 : Implementation API
506
507 activate A
508 == Initialization ==
509 group Dispatcher API [Enumerate and load implementations]
510 A -> D: mfxLoad()
511 activate D
512
513 D -> D: Search for the available runtimes
514
515 A -> D: MFXCreateConfig()
516 A -> D: MFXSetConfigProperty()
517 A -> D: MFXCreateConfig()
518 A -> D: MFXSetConfigProperty()
519 A -> D: MFXEnumImplementations()
520
521 note right of A
522 MFXEnumImplementations() may also be called
523 after MFXCreateSession().
524 end note
525
526 Activate I1
527
528 D -> I1: MFXQueryImplsDescription()
529 I1 --> D: mfxImplDescription
530
531 Activate I2
532 D -> I2: MFXQueryImplsDescription()
533 I2 --> D: mfxImplDescription
534
535 Activate I3
536 D -> I3: MFXQueryImplsDescription()
537 I3 --> D: mfxImplDescription
538
539 D --> A: list of mfxImplDescription structures es for all implementations
540
541 A -> D: MFXCreateSession(i=0)
542 D -> I1: MFXInitilize()
543 Activate I1 #DarkSalmon
544 I1 --> D: mfxSession1
545 D --> A: mfxSession1
546
547 A -> D: MFXCreateSession(i=1)
548 D -> I2: MFXInitilize()
549 Activate I2 #DarkSalmon
550 I2 --> D: mfxSession2
551 D --> A: mfxSession2
552
553 A -> D: MFXCreateSession(i=2)
554 D -> I3: MFXInitilize()
555 I3 --> D: mfxSession3
556 Activate I3 #DarkSalmon
557 D --> A: mfxSession3
558
559 A -> D: MFXDispReleaseImplDescription(hdl=0)
560 D -> I1: MFXReleaseImplDescription()
561
562 A -> D: MFXDispReleaseImplDescription(hdl=1)
563 D -> I2: MFXReleaseImplDescription()
564
565 A -> D: MFXDispReleaseImplDescription(hdl=2)
566 D -> I3: MFXReleaseImplDescription()
567 end
568 == Processing ==
569 group Implementation API [Process the data]
570 A -> I1: MFXVideoDECODE_Init()
571 A -> I1: MFXVideoDECODE_Query()
572 A -> I1: MFXVideoDECODE_DecodeFrameAsync()
573 ...
574 A -> I1: MFXVideoDECODE_Close()
575 |||
576 deactivate I1
577
578 A -> I2: MFXVideoENCODE_Init()
579 A -> I2: MFXVideoENCODE_Query()
580 A -> I2: MFXVideoENCODE_EncodeFrameAsync()
581 ...
582 A -> I2: MFXVideoENCODE_Close()
583 |||
584 deactivate I2
585
586 A -> I3: MFXVideoENCODE_Init()
587 A -> I3: MFXVideoENCODE_Query()
588 A -> I3: MFXVideoENCODE_EncodeFrameAsync()
589 ...
590 A -> I3: MFXVideoENCODE_Close()
591 |||
592 deactivate I3
593 end
594 == Finalization ==
595 group Implementation API [Release the implementations]
596 A -> I1: MFXClose()
597 deactivate I1
598 A -> I2: MFXClose()
599 deactivate I2
600 A -> I3: MFXClose()
601 deactivate I3
602 group Dispatcher API [Release the dispatcher's instance]
603 A -> D: MFXUnload()
604 end
605
606 deactivate D
607 @enduml
608
609 The |vpl_short_name| dispatcher is capable to load and initialize |msdk_full_name| legacy
610 library. The sequence diagram below demonstrates the approach.
611
612 .. uml::
613
614 @startuml
615 actor Application as A
616 participant "Intel® VPL Dispatcher" as D
617 participant "Intel® MediaSDK (legacy)" as M
618 A -> D: MFXLoad
619 activate D
620 D -> D: Search for the available runtimes
621 A -> D: MFXCreateConfig
622
623 note left of D
624 Setting properties to filter implementation.
625 MediaSDK supports only general parameters,
626 no filtering for Decode/VPP/Encoder details.
627 end note
628
629 group MediaSDK LegacyAPI
630 D -> M: MFXInitEx
631 activate M
632
633 M --> D: mfxSession
634 D -> M: MFXQueryIMPL
635 M --> D: Implementation speciefic
636
637 D -> M: MFXQueryVersion
638 M --> D: mfxVersion
639 end
640
641 D -> D: Fill mfxImplDescription for MediaSDK impl
642
643 A -> D: mfxEnumImplementations
644 D --> A: MediaSDK caps description
645
646 A -> D: MFXCreateSession
647 D --> A: mfxSession
648
649 A -> M: MFXVideoDECODE_Init()
650 A -> M: MFXVideoDECODE_Query()
651 A -> M: MFXVideoDECODE_DecodeFrameAsync()
652 ...
653 A -> M: MFXVideoDECODE_Close()
654 A -> M: MFXClose()
655
656 deactivate M
657
658 A -> D: MFXUnload()
659 deactivate D
660 @enduml
661
662 .. important:: The dispatcher doesn't filter and report
663 :cpp:struct:`mfxDeviceDescription`,
664 :cpp:struct:`mfxDecoderDescription`,
665 :cpp:struct:`mfxEncoderDescription`,
666 :cpp:struct:`mfxVPPDescription` when enumerates or creates
667 |msdk_full_name| implementation. Once |msdk_full_name| is loaded
668 applications have to use legacy approach to query capabilities.
669
670 -------------------------------------
671 |vpl_short_name| Dispatcher Debug Log
672 -------------------------------------
673
674 The debug output of the dispatcher is controlled with the `ONEVPL_DISPATCHER_LOG`
675 environment variable. To enable log output, set the `ONEVPL_DISPATCHER_LOG`
676 environment variable value equals to "ON".
677
678 By default, |vpl_short_name| dispatcher prints all log messages to the console.
679 To redirect log output to the desired file, set the `ONEVPL_DISPATCHER_LOG_FILE`
680 environmental variable with the file name of the log file.
681
682 ------------------------------
683 Examples of Dispatcher's Usage
684 ------------------------------
685
686 This code illustrates simple usage of dispatcher to load first available
687 library:
688
689 .. literalinclude:: ../snippets/prg_disp.c
690 :language: c++
691 :start-after: /*beg1*/
692 :end-before: /*end1*/
693 :lineno-start: 1
694
695 This code illustrates simple usage of dispatcher to load first available HW
696 accelerated library:
697
698 .. literalinclude:: ../snippets/prg_disp.c
699 :language: c++
700 :start-after: /*beg2*/
701 :end-before: /*end2*/
702 :lineno-start: 1
703
704 This code illustrates how multiple sessions from multiple loaders can be
705 created:
706
707 .. literalinclude:: ../snippets/prg_disp.c
708 :language: c++
709 :start-after: /*beg3*/
710 :end-before: /*end3*/
711 :lineno-start: 1
712
713 This code illustrates how multiple decoders from single loader can be
714 created:
715
716 .. literalinclude:: ../snippets/prg_disp.c
717 :language: c++
718 :start-after: /*beg4*/
719 :end-before: /*end4*/
720 :lineno-start: 1
721
722 ---------------------------------------
723 How To Check If Function is Implemented
724 ---------------------------------------
725
726 There are two ways to check if particular function is implemented or not by the
727 implementation.
728
729 This code illustrates how application can iterate through the whole list of
730 implemented functions:
731
732 .. literalinclude:: ../snippets/prg_session.cpp
733 :language: c++
734 :start-after: /*beg1*/
735 :end-before: /*end1*/
736 :lineno-start: 1
737
738 This code illustrates how application can check that specific functions are
739 implemented:
740
741 .. literalinclude:: ../snippets/prg_session.cpp
742 :language: c++
743 :start-after: /*beg2*/
744 :end-before: /*end2*/
745 :lineno-start: 1
746
747 --------------------------------------------------------------
748 How To Search For The Available encoder/decoder implementation
749 --------------------------------------------------------------
750
751 The :ref:`CodecFormatFourCC <codec-format-fourcc>` enum specifies codec's FourCC
752 values. Application needs to assign this value to the field of
753 :cpp:member:`mfxDecoderDescription::decoder::CodecID` to search for the decoder
754 or :cpp:member:`mfxEncoderDescription::encoder::CodecID` to search for the
755 encoder.
756
757 This code illustrates decoder's implementation search procedure:
758
759 .. literalinclude:: ../snippets/prg_session.cpp
760 :language: c++
761 :start-after: /*beg3*/
762 :end-before: /*end3*/
763 :lineno-start: 1
764
765 ---------------------------------------------------------
766 How To Search For The Available VPP Filter implementation
767 ---------------------------------------------------------
768
769 Each VPP filter identified by the filter ID. Filter ID is defined by
770 corresponding to the filter extension buffer ID value which is defined in a form
771 of FourCC value.
772 Filter ID values are subset of the general :ref:`ExtendedBufferID <extendedbufferid>`
773 enum. The :ref:`table <vpp-filters-ids>` references available IDs of VPP filters
774 to search. Application needs to assign this value to the field of
775 :cpp:member:`mfxVPPDescription::filter::FilterFourCC` to search for the needed
776 VPP filter.
777
778 .. _vpp-filters-ids:
779
780 .. list-table:: VPP Filters ID
781 :header-rows: 1
782 :widths: 58 42
783
784 * - **Filter ID**
785 - **Description**
786 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_DENOISE2`
787 - Denoise filter
788 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_MCTF`
789 - Motion-Compensated Temporal Filter (MCTF).
790 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_DETAIL`
791 - Detail/edge enhancement filter.
792 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_FRAME_RATE_CONVERSION`
793 - Frame rate conversion filter
794 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_IMAGE_STABILIZATION`
795 - Image stabilization filter
796 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_PROCAMP`
797 - ProcAmp filter
798 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_FIELD_PROCESSING`
799 - Field processing filter
800 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_COLOR_CONVERSION`
801 - Color Conversion filter
802 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_SCALING`
803 - Resize filter
804 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_COMPOSITE`
805 - Surfaces composition filter
806 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_DEINTERLACING`
807 - Deinterlace filter
808 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_ROTATION`
809 - Rotation filter
810 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_MIRRORING`
811 - Mirror filter
812 * - :cpp:enumerator:`MFX_EXTBUFF_VPP_COLORFILL`
813 - ColorFill filter
814
815 This code illustrates VPP mirror filter implementation search procedure:
816
817 .. literalinclude:: ../snippets/prg_session.cpp
818 :language: c++
819 :start-after: /*beg4*/
820 :end-before: /*end4*/
821 :lineno-start: 1
822
823 -------------------------------------------------------------
824 How To Get Path to the Shared Library With the Implementation
825 -------------------------------------------------------------
826
827 Sessions can be created from different implementations, each implementations can
828 be located in different shared libraries. To get path of the shared library with
829 the implementation from which session can be or was created, application can use
830 :cpp:func:`MFXEnumImplementations` and pass :cpp:enumerator:`MFX_IMPLCAPS_IMPLPATH`
831 value as the output data request.
832
833 This code illustrates collection and print out path of implementations's
834 shared library:
835
836 .. literalinclude:: ../snippets/prg_session.cpp
837 :language: c++
838 :start-after: /*beg5*/
839 :end-before: /*end5*/
840 :lineno-start: 1
841
842 --------------------------------------------------------------
843 How To Get Extended Capability Information for encoder/decoder
844 --------------------------------------------------------------
845
846 From |vpl_short_name| API 2.15 applications can get more capabilities information
847 for encoder/decoder with the help of the :cpp:func:`MFXEnumImplementations`
848 function, including list of supported extension buffers, list of supported
849 Bitrate Control for encoders, supported bit depth and chroma subsamplings.
850
851 :cpp:struct:`mfxDecoderDescription` is extended to contain
852 :cpp:struct:`mfxDecExtDescription` and :cpp:struct:`mfxDecMemExtDescription` from
853 the struct version 1.1. :cpp:struct:`mfxEncoderDescription` is extended to contain
854 :cpp:struct:`mfxEncExtDescription` and :cpp:struct:`mfxEncMemExtDescription` from
855 the struct version 1.1.
856
857 Applications can check the struct version and correspondent pointers in extended
858 :cpp:struct:`mfxDecoderDescription` and :cpp:struct:`mfxEncExtDescription` to
859 get the extended capability information.
860
861 This code illustrates how to get the extended capability information using
862 :cpp:func:`MFXEnumImplementations` before session creation:
863
864 .. literalinclude:: ../snippets/prg_session.cpp
865 :language: c++
866 :start-after: /*beg6*/
867 :end-before: /*end6*/
868 :lineno-start: 1
869
870 .. note:: :cpp:struct:`mfxEncExtDescription` and
871 :cpp:struct:`mfxEncMemExtDescription` report capabilities only
872 for VDEnc.
873
874 ---------------------------------------------------------------
875 How To Do Property-Based Query For The Available Implementation
876 ---------------------------------------------------------------
877
878 From |vpl_short_name| API 2.15 applications can use property-based query
879 to search for the available implementation. Applications can get only
880 shallow information for session creation without
881 filling out the following structures:
882 :cpp:struct:`mfxDecoderDescription`,
883 :cpp:struct:`mfxEncoderDescription`,
884 :cpp:struct:`mfxVPPDescription`.
885 Applications can also query specific encoder or decoder or VPP filter
886 before session creation. This will result in faster session creation
887 as compared with full query of all encoders, decoders and VPP filters.
888
889 Applications must use the data type
890 :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_QUERY` as bitmask to
891 OR with other variant data types to do property-based query.
892
893 This code illustrates how application can use the shallow information for
894 session creation:
895
896 .. literalinclude:: ../snippets/prg_session.cpp
897 :language: c++
898 :start-after: /*beg7*/
899 :end-before: /*end7*/
900 :lineno-start: 1
901
902 Applications can get only shallow information with
903 :cpp:func:`MFXEnumImplementations`.
904
905 This code illustrates how application can use the shallow information to
906 explore available implementations:
907
908 .. literalinclude:: ../snippets/prg_session.cpp
909 :language: c++
910 :start-after: /*beg8*/
911 :end-before: /*end8*/
912 :lineno-start: 1
913
914 Applications can also use :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_QUERY`
915 to find decoders or encoders or VPP filters.
916 This code illustrates how application can find one encoder for session creation:
917
918 .. literalinclude:: ../snippets/prg_session.cpp
919 :language: c++
920 :start-after: /*beg10*/
921 :end-before: /*end10*/
922 :lineno-start: 1
923
924 This code illustrates how application can find decoders for session creation:
925
926 .. literalinclude:: ../snippets/prg_session.cpp
927 :language: c++
928 :start-after: /*beg9*/
929 :end-before: /*end9*/
930 :lineno-start: 1
931
932 This code illustrates how application can find VPP filters for session
933 creation:
934
935 .. literalinclude:: ../snippets/prg_session.cpp
936 :language: c++
937 :start-after: /*beg11*/
938 :end-before: /*end11*/
939 :lineno-start: 1
940
941 Applications can use :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_QUERY`
942 to get decoder or encoder or VPP filter information with
943 :cpp:func:`MFXEnumImplementations`.
944 This code illustrates how application can query one encoder using
945 :cpp:func:`MFXEnumImplementations`:
946
947 .. literalinclude:: ../snippets/prg_session.cpp
948 :language: c++
949 :start-after: /*beg12*/
950 :end-before: /*end12*/
951 :lineno-start: 1
952
953 The :ref:`Query-able Properties Table <query-able-prop-table>` shows property
954 strings supported by property-based query. Applying the bitmask
955 :cpp:enumerator:`mfxVariantType::MFX_VARIANT_TYPE_QUERY` to properties not
956 listed in this table will cause :cpp:func:`MFXSetConfigFilterProperty` to return
957 MFX_ERR_UNSUPPORTED.
958
959 .. _query-able-prop-table:
960
961 .. container:: stripe-table
962
963 .. table:: Query-able Properties
964 :widths: 25 30 20
965
966 +----------------------------+------------------------+---------------------------+
967 | Property | Value Data Type | Comment |
968 +============================+========================+===========================+
969 | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | Query for shallow |
970 | | MFX_VARIANT_TYPE_QUERY | information |
971 +----------------------------+------------------------+---------------------------+
972 | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | Query for decoder |
973 | | .mfxDecoderDescription | MFX_VARIANT_TYPE_QUERY | |
974 | | .decoder | | |
975 | | .CodecID | | |
976 +----------------------------+------------------------+---------------------------+
977 | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | Query for encoder |
978 | | .mfxEncoderDescription | MFX_VARIANT_TYPE_QUERY | |
979 | | .encoder | | |
980 | | .CodecID | | |
981 +----------------------------+------------------------+---------------------------+
982 | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | Query for VPP filter |
983 | | .mfxVPPDescription | MFX_VARIANT_TYPE_QUERY | |
984 | | .filter | | |
985 | | .FilterFourCC | | |
986 +----------------------------+------------------------+---------------------------+
987 | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | Query for all decoders |
988 | | .mfxDecoderDescription | MFX_VARIANT_TYPE_QUERY | |
989 +----------------------------+------------------------+---------------------------+
990 | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | Query for all encoders |
991 | | .mfxEncoderDescription | MFX_VARIANT_TYPE_QUERY | |
992 +----------------------------+------------------------+---------------------------+
993 | | mfxImplDescription | MFX_VARIANT_TYPE_U32 | | Query for all VPP filters |
994 | | .mfxVPPDescription | MFX_VARIANT_TYPE_QUERY | |
995 +----------------------------+------------------------+---------------------------+
996
997 Examples of valid property name strings for query:
998
999 - mfxImplDescription
1000 - mfxImplDescription.mfxEncoderDescription.encoder.CodecID
1001 - mfxImplDescription.mfxDecoderDescription
1002
1003 .. important::
1004 To use property-based query, the application needs to configure at least
1005 one of the properties in the
1006 :ref:`Query-able Properties Table <query-able-prop-table>`.
1007 For example, if application wants to query a particular AV1 profile,
1008 it needs to set at least:
1009
1010 * mfxImplDescription.mfxEncoderDescription.encoder.CodecID and value data :cpp:enumerator:`MFX_CODEC_AV1` (to get all AV1 encoder properties)
1011
1012 or
1013
1014 * mfxImplDescription.mfxEncoderDescription (to get all encoder properties for all encoders)
1015
1016 No matter what property is queried, below shallow information will be filled in
1017 :cpp:struct:`mfxImplDescription`:
1018
1019 .. code-block:: c++
1020
1021 mfxStructVersion Version;
1022 mfxImplType Impl;
1023 mfxAccelerationMode AccelerationMode;
1024 mfxVersion ApiVersion;
1025 mfxChar ImplName[MFX_IMPL_NAME_LEN];
1026 mfxChar License[MFX_STRFIELD_LEN];
1027 mfxChar Keywords[MFX_STRFIELD_LEN];
1028 mfxU32 VendorID;
1029 mfxU32 VendorImplID;
1030 mfxDeviceDescription Dev;
1031 mfxAccelerationModeDescription AccelerationModeDescription;
1032 mfxPoolPolicyDescription PoolPolicies;
1033
1034 .. note:: When using property-based queries, all of the desired properties must be
1035 configured before the first call to either :cpp:func:`MFXCreateSession`
1036 or :cpp:func:`MFXEnumImplementations`.
1037
1038 .. _vpl_coexistense:
1039
1040 ---------------------------------------------------------------------------------------------------------------------
1041 |vpl_short_name| implementation on |intel_r| platforms with X\ :sup:`e` architecture and |msdk_full_name| Coexistence
1042 ---------------------------------------------------------------------------------------------------------------------
1043
1044 |vpl_short_name| supersedes |msdk_full_name| and is partially binary compatible with
1045 |msdk_full_name|. Both |vpl_short_name| and |msdk_full_name| includes own dispatcher and
1046 implementation. Coexistence of |vpl_short_name| and |msdk_full_name| dispatchers and
1047 implementations on single system is allowed until |msdk_full_name| is not EOL.
1048
1049 Usage of the following combinations of dispatchers and implementations within
1050 the single application is permitted for the legacy purposes only. In that
1051 scenario legacy applications developed with |msdk_full_name| will continue to
1052 work on any HW supported either by |msdk_full_name| or by the |vpl_short_name|.
1053
1054 .. attention:: Any application to work with the |vpl_short_name| API starting from version
1055 2.0 must use only |vpl_short_name| dispatcher.
1056
1057 |msdk_full_name| API
1058 |msdk_full_name| API of 1.x version.
1059
1060 Removed API
1061 |msdk_full_name| :ref:`API <deprecated-api>` which is removed from |vpl_short_name|.
1062
1063 Core API
1064 |msdk_full_name| API without removed API.
1065
1066 |vpl_short_name| API
1067 New :ref:`API <new-api>` introduced in |vpl_short_name| only started from API 2.0
1068 version.
1069
1070 |vpl_short_name| Dispatcher API
1071 Dispatcher :ref:`API <dispatcher-api>` introduced in |vpl_short_name| in 2.0
1072 API version. This is subset of |vpl_short_name| API.
1073
1074 .. list-table:: |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture and |msdk_full_name|
1075 :header-rows: 1
1076 :widths: 25 25 25 25
1077
1078 * - **Dispatcher**
1079 - **Installed on the device**
1080 - **Loaded**
1081 - **Allowed API**
1082 * - |vpl_short_name|
1083 - |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture
1084 - |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture
1085 - Usage of any API except removed API is allowed.
1086 * - |vpl_short_name|
1087 - |msdk_full_name|
1088 - |msdk_full_name|
1089 - Usage of core API plus dispatcher API is allowed only.
1090 * - |vpl_short_name|
1091 - |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture and |msdk_full_name|
1092 - |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture
1093 - Usage of any API except removed API is allowed.
1094 * - |msdk_full_name|
1095 - |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture
1096 - |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture
1097 - Usage of core API is allowed only.
1098 * - |msdk_full_name|
1099 - |vpl_short_name| for |intel_r| platforms with X\ :sup:`e` architecture and |msdk_full_name|
1100 - |msdk_full_name|
1101 - Usage of |msdk_full_name| API is allowed.
1102 * - |msdk_full_name|
1103 - |msdk_full_name|
1104 - |msdk_full_name|
1105 - Usage of |msdk_full_name| API is allowed.
1106
1107 .. note:: if system has multiple devices the logic of selection and loading implementations
1108 will be applied to each device accordingly to the system enumeration.
1109
1110 -----------------
1111 Multiple Sessions
1112 -----------------
1113
1114 Each |vpl_short_name| session can run exactly one instance of the DECODE, ENCODE, and
1115 VPP functions. This is adequate for a simple transcoding operation. If the
1116 application needs more than one instance of DECODE, ENCODE, or VPP
1117 in a complex transcoding setting or needs more simultaneous transcoding
1118 operations, the application can initialize multiple
1119 |vpl_short_name| sessions created from one or several |vpl_short_name| implementations.
1120
1121 The application can use multiple |vpl_short_name| sessions independently or run a “joined”
1122 session. To join two sessions together, the application can use the function
1123 :cpp:func:`MFXJoinSession`. Alternatively, the application can use the
1124 :cpp:func:`MFXCloneSession` function to duplicate an existing session. Joined
1125 |vpl_short_name| sessions work together as a single session, sharing all session
1126 resources, threading control, and prioritization operations except hardware
1127 acceleration devices and external allocators. When joined, the first session
1128 (first join) serves as the parent session and will schedule execution resources
1129 with all other child sessions. Child sessions rely on the parent session for
1130 resource management.
1131
1132 .. important:: Applications can join sessions created from the same |vpl_short_name|
1133 implementation only.
1134
1135 With joined sessions, the application can set the priority of session operations
1136 through the :cpp:func:`MFXSetPriority` function. A lower priority session
1137 receives fewer CPU cycles. Session priority does not affect hardware accelerated
1138 processing.
1139
1140 After the completion of all session operations, the application can use the
1141 :cpp:func:`MFXDisjoinSession` function to remove the joined state of a session.
1142 Do not close the parent session until all child sessions are disjoined or
1143 closed.