Debian Codegraph @

doc/spec/source/appendix/VPL_apnds_d.rst

raw
1 .. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
2 ..
3 .. SPDX-License-Identifier: CC-BY-4.0
4
5 =========================================
6 Switchable Graphics and Multiple Monitors
7 =========================================
8
9 The following sections discuss support for switchable graphics and multiple
10 monitor configurations.
11
12 -------------------
13 Switchable Graphics
14 -------------------
15
16 Switchable Graphics refers to the machine configuration that multiple graphic
17 devices are available (integrated device for power saving and discrete
18 devices for performance.) Usually at one time or instance, one of the graphic
19 devices drives display and becomes the active device, and others become
20 inactive. There are different variations of software or hardware mechanisms to
21 switch between the graphic devices. In one of the switchable graphics variations,
22 it is possible to register an application in an affinity list to certain graphic
23 device so that the launch of the application automatically triggers a switch. The
24 actual techniques to enable such a switch are outside the scope of this document.
25 This section discusses the implication of switchable graphics to |msdk_full_name| and
26 |msdk_full_name| applications.
27
28 As |msdk_full_name| performs hardware acceleration through graphic devices, it is
29 critical that |msdk_full_name| can access the graphic device in the switchable
30 graphics setting. It is recommended to add the application to the graphic device
31 affinity list. If this is not possible, the application should handle the
32 following cases:
33
34 - By design, during legacy |msdk_full_name| library initialization, the
35 :cpp:func:`MFXInit` function searches for graphic devices. If a |msdk_full_name|
36 implementation is successfully loaded, the :cpp:func:`MFXInit` function returns :cpp:enumerator:`mfxStatus::MFX_ERR_NONE`
37 and the :cpp:func:`MFXQueryIMPL` function returns the actual implementation
38 type. If no |msdk_full_name| implementation is loaded, the :cpp:func:`MFXInit` function
39 returns :cpp:enumerator:`mfxStatus::MFX_ERR_UNSUPPORTED`. In the switchable graphics
40 environment, if the application is not in the graphic device affinity
41 list, it is possible that the graphic device will not be accessible
42 during the library initialization. The fact that the :cpp:func:`MFXInit`
43 function returns :cpp:enumerator:`mfxStatus::MFX_ERR_UNSUPPORTED` does not mean that
44 hardware acceleration is permanently impossible. The user may switch the
45 graphics later and the graphic device will become accessible. It
46 is recommended that the application initialize the library right before
47 the actual decoding, video processing, and encoding operations to determine
48 the hardware acceleration capability.
49 - During decoding, video processing, and encoding operations, if the application
50 is not in the graphic device affinity list, the previously accessible
51 graphic device may become inaccessible due to a switch event. The |msdk_full_name|
52 functions will return :cpp:enumerator:`mfxStatus::MFX_ERR_DEVICE_LOST` or
53 :cpp:enumerator:`mfxStatus::MFX_ERR_DEVICE_FAILED`, depending on when the switch occurs
54 and what stage the |msdk_full_name| functions operate. The application should handle these
55 errors and exit gracefully.
56
57 -----------------
58 Multiple Monitors
59 -----------------
60
61 Multiple monitors refer to the machine configuration that multiple graphic devices
62 are available. Some graphic devices connect to a display and become active
63 and accessible under the Microsoft\* DirectX\* infrastructure. Graphic devices
64 that are not connected to a display are inactive. Using the Microsoft Direct3D\* 9
65 infrastructure, devices that are not connected to a display are not accessible.
66
67 The legacy |msdk_full_name| uses the adapter number to access a specific graphic
68 device. Usually, the graphic device driving the main desktop becomes the primary
69 adapter. Other graphic devices take subsequent adapter numbers after the primary
70 adapter. Under the Microsoft Direct3D 9 infrastructure, only active adapters are
71 accessible and have an adapter number.
72
73 |msdk_full_name| extends the :cpp:type:`mfxIMPL` implementation type as shown in the
74 :ref:`Intel® Media SDK mfxIMPL Implementation Type Definitions table <mfxIMPL-def-1-table>`:
75
76 .. _mfxIMPL-def-1-table:
77
78 .. list-table:: Intel® Media SDK mfxIMPL Implementation Type Definitions
79 :header-rows: 1
80 :widths: 40 60
81
82 * - **Implementation Type**
83 - **Definition**
84 * - :cpp:enumerator:`MFX_IMPL_HARDWARE`
85 - |msdk_full_name| should initialize on the primary adapter
86 * - :cpp:enumerator:`MFX_IMPL_HARDWARE2`
87 - |msdk_full_name| should initialize on the 2nd graphic adapter
88 * - :cpp:enumerator:`MFX_IMPL_HARDWARE3`
89 - |msdk_full_name| should initialize on the 3rd graphic adapter
90 * - :cpp:enumerator:`MFX_IMPL_HARDWARE4`
91 - |msdk_full_name| should initialize on the 4th graphic adapter
92 * - :cpp:enumerator:`MFX_IMPL_HARDWARE_ANY`
93 - |msdk_full_name| should initialize on any graphic adapter.
94 * - :cpp:enumerator:`MFX_IMPL_AUTO_ANY`
95 - |msdk_full_name| should initialize on any graphic adapter. If not successful,
96 load the software implementation.
97
98 The application can use the first four definitions shown in the
99 :ref:`Intel® Media SDK mfxIMPL Implementation Type Definitions table <mfxIMPL-def-1-table>`
100 to instruct the legacy |msdk_full_name| library to initialize on a specific
101 graphic device. The application can use the definitions for
102 :cpp:enumerator:`MFX_IMPL_HARDWARE_ANY` and
103 :cpp:enumerator:`MFX_IMPL_AUTO_ANY` for automatic detection.
104
105 If the application uses the Microsoft DirectX surfaces for I/O, it is critical
106 that the application and |msdk_full_name| work on the same graphic device. It is
107 recommended that the application use the following procedure:
108
109 #. The application uses the :cpp:func:`MFXInit` function to initialize the legacy
110 |msdk_full_name|, with option :cpp:enumerator:`MFX_IMPL_HARDWARE_ANY` or
111 :cpp:enumerator:`MFX_IMPL_AUTO_ANY`. The :cpp:func:`MFXInit` function returns
112 :cpp:enumerator:`mfxStatus::MFX_ERR_NONE` if successful.
113 #. The application uses the :cpp:func:`MFXQueryIMPL` function to check the actual
114 implementation type. The implementation type :cpp:enumerator:`MFX_IMPL_HARDWARE`,
115 :cpp:enumerator:`MFX_IMPL_HARDWARE2`, :cpp:enumerator:`MFX_IMPL_HARDWARE3`,
116 or :cpp:enumerator:`MFX_IMPL_HARDWARE4` indicates the graphic adapter the
117 |msdk_full_name| works on.
118 #. The application creates the Direct3D device on the respective graphic adapter
119 and passes it to |msdk_full_name| through the :cpp:func:`MFXVideoCORE_SetHandle` function.
120
121 Similar to the switchable graphics cases, interruption may result if the user
122 disconnects monitors from the graphic devices or remaps the primary adapter. If
123 the interruption occurs during the |msdk_full_name| library initialization, the
124 :cpp:func:`MFXInit` function may return :cpp:enumerator:`mfxStatus::MFX_ERR_UNSUPPORTED`.
125 This means hardware acceleration is currently not available. It is recommended
126 that the application initialize |msdk_full_name| right before the actual decoding,
127 video processing, and encoding operations to determine the hardware acceleration
128 capability.
129
130 If the interruption occurs during decoding, video processing, or encoding
131 operations, |vpl_short_name| functions will return :cpp:enumerator:`mfxStatus::MFX_ERR_DEVICE_LOST`
132 or :cpp:enumerator:`mfxStatus::MFX_ERR_DEVICE_FAILED`. The application should handle these
133 errors and exit gracefully.