Debian Codegraph @

doc/spec/source/VPL_summary.rst

raw
1 .. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
2 ..
3 .. SPDX-License-Identifier: CC-BY-4.0
4
5 ============================
6 Mandatory APIs and Functions
7 ============================
8
9 ----------
10 Disclaimer
11 ----------
12
13 Developers can implement any subset of the |vpl_short_name| API.
14 The specification makes no claim about what encoder, decoder, VPP
15 filter, or any other underlying features are mandatory for the implementation.
16 The |vpl_short_name| API is designed such that users have several options
17 to discover capabilities exposed by the implementation:
18
19 #. Before or after session creation: Users can get a list of supported encoders, decoders,
20 VPP filters, correspondent color formats, and memory types with the help of
21 the :cpp:func:`MFXEnumImplementations` function. For more details, see
22 :ref:`vpl-dispatcher-interactions`.
23 #. After session is created: Users can call **Query** functions to obtain
24 low level implementation capabilities.
25
26 .. attention:: The legacy |msdk_full_name| implementation does not support the
27 first approach to obtain capabilities.
28
29 ------------------
30 Exported Functions
31 ------------------
32
33 The :ref:`Exported Functions table <export-func-version-table-2x>` lists all
34 functions that must be exposed by any |vpl_full_name| implementation.
35 The realization of all listed functions is mandatory; most functions may return
36 :cpp:enumerator:`mfxStatus::MFX_ERR_NOT_IMPLEMENTED`.
37
38 .. note:: Functions :cpp:func:`MFXInit` and :cpp:func:`MFXInitEx` are not required to be
39 exported.
40
41 See `Mandatory APIs`_ for details about which functions, in which conditions,
42 must not return :cpp:enumerator:`mfxStatus::MFX_ERR_NOT_IMPLEMENTED`.
43
44 .. _export-func-version-table-2x:
45
46 .. list-table:: Exported Functions
47 :header-rows: 1
48 :widths: 70 30
49
50 * - **Function**
51 - **API Version**
52 * - :cpp:func:`MFXClose`
53 - 1.0
54 * - :cpp:func:`MFXQueryIMPL`
55 - 1.0
56 * - :cpp:func:`MFXQueryVersion`
57 - 1.0
58 * - :cpp:func:`MFXJoinSession`
59 - 1.1
60 * - :cpp:func:`MFXDisjoinSession`
61 - 1.1
62 * - :cpp:func:`MFXCloneSession`
63 - 1.1
64 * - :cpp:func:`MFXSetPriority`
65 - 1.1
66 * - :cpp:func:`MFXGetPriority`
67 - 1.1
68 * - :cpp:func:`MFXVideoCORE_SetFrameAllocator`
69 - 1.0
70 * - :cpp:func:`MFXVideoCORE_SetHandle`
71 - 1.0
72 * - :cpp:func:`MFXVideoCORE_GetHandle`
73 - 1.0
74 * - :cpp:func:`MFXVideoCORE_SyncOperation`
75 - 1.0
76 * - :cpp:func:`MFXVideoENCODE_Query`
77 - 1.0
78 * - :cpp:func:`MFXVideoENCODE_QueryIOSurf`
79 - 1.0
80 * - :cpp:func:`MFXVideoENCODE_Init`
81 - 1.0
82 * - :cpp:func:`MFXVideoENCODE_Reset`
83 - 1.0
84 * - :cpp:func:`MFXVideoENCODE_Close`
85 - 1.0
86 * - :cpp:func:`MFXVideoENCODE_GetVideoParam`
87 - 1.0
88 * - :cpp:func:`MFXVideoENCODE_GetEncodeStat`
89 - 1.0
90 * - :cpp:func:`MFXVideoENCODE_EncodeFrameAsync`
91 - 1.0
92 * - :cpp:func:`MFXVideoDECODE_Query`
93 - 1.0
94 * - :cpp:func:`MFXVideoDECODE_DecodeHeader`
95 - 1.0
96 * - :cpp:func:`MFXVideoDECODE_QueryIOSurf`
97 - 1.0
98 * - :cpp:func:`MFXVideoDECODE_Init`
99 - 1.0
100 * - :cpp:func:`MFXVideoDECODE_Reset`
101 - 1.0
102 * - :cpp:func:`MFXVideoDECODE_Close`
103 - 1.0
104 * - :cpp:func:`MFXVideoDECODE_GetVideoParam`
105 - 1.0
106 * - :cpp:func:`MFXVideoDECODE_GetDecodeStat`
107 - 1.0
108 * - :cpp:func:`MFXVideoDECODE_SetSkipMode`
109 - 1.0
110 * - :cpp:func:`MFXVideoDECODE_GetPayload`
111 - 1.0
112 * - :cpp:func:`MFXVideoDECODE_DecodeFrameAsync`
113 - 1.0
114 * - :cpp:func:`MFXVideoVPP_Query`
115 - 1.0
116 * - :cpp:func:`MFXVideoVPP_QueryIOSurf`
117 - 1.0
118 * - :cpp:func:`MFXVideoVPP_Init`
119 - 1.0
120 * - :cpp:func:`MFXVideoVPP_Reset`
121 - 1.0
122 * - :cpp:func:`MFXVideoVPP_Close`
123 - 1.0
124 * - :cpp:func:`MFXVideoVPP_GetVideoParam`
125 - 1.0
126 * - :cpp:func:`MFXVideoVPP_GetVPPStat`
127 - 1.0
128 * - :cpp:func:`MFXVideoVPP_RunFrameVPPAsync`
129 - 1.0
130 * - :cpp:func:`MFXVideoCORE_QueryPlatform`
131 - 1.19
132 * - :cpp:func:`MFXQueryAdapters`
133 - 1.31
134 * - :cpp:func:`MFXQueryAdaptersDecode`
135 - 1.31
136 * - :cpp:func:`MFXQueryAdaptersNumber`
137 - 1.31
138 * - :cpp:func:`MFXMemory_GetSurfaceForVPP`
139 - 2.0
140 * - :cpp:func:`MFXMemory_GetSurfaceForEncode`
141 - 2.0
142 * - :cpp:func:`MFXMemory_GetSurfaceForDecode`
143 - 2.0
144 * - :cpp:func:`MFXQueryImplsDescription`
145 - 2.0
146 * - :cpp:func:`MFXReleaseImplDescription`
147 - 2.0
148 * - :cpp:func:`MFXInitialize`
149 - 2.0
150 * - :cpp:func:`MFXMemory_GetSurfaceForVPPOut`
151 - 2.1
152 * - :cpp:func:`MFXVideoVPP_ProcessFrameAsync`
153 - 2.1
154 * - :cpp:func:`MFXVideoDECODE_VPP_Init`
155 - 2.1
156 * - :cpp:func:`MFXVideoDECODE_VPP_DecodeFrameAsync`
157 - 2.1
158 * - :cpp:func:`MFXVideoDECODE_VPP_Reset`
159 - 2.1
160 * - :cpp:func:`MFXVideoDECODE_VPP_GetChannelParam`
161 - 2.1
162 * - :cpp:func:`MFXVideoDECODE_VPP_Close`
163 - 2.1
164
165 --------------
166 Mandatory APIs
167 --------------
168
169 All implementations must implement the APIs listed in the
170 :ref:`Mandatory APIs table <mandatory-apis-table>`:
171
172 .. _mandatory-apis-table:
173
174 .. list-table:: Mandatory APIs
175 :header-rows: 1
176 :widths: 50 50
177
178 * - **Functions**
179 - **Description**
180 * - | :cpp:func:`MFXInitialize`
181 | :cpp:func:`MFXClose`
182 - Required functions for the dispatcher to create a session.
183 * - | :cpp:func:`MFXQueryImplsDescription`
184 | :cpp:func:`MFXReleaseImplDescription`
185 - Required functions for the dispatcher to return implementation capabilities.
186 * - :cpp:func:`MFXVideoCORE_SyncOperation`
187 - Required function for synchronization of asynchronous operations.
188
189
190 If the implementation exposes any encoder, decoder, or VPP filter, it must
191 implement the corresponding mandatory APIs, as described in the
192 :ref:`Mandatory Encode <mandatory-enc-apis-table>`, :ref:`Decode <mandatory-dec-apis-table>`,
193 :ref:`VPP <mandatory-vpp-apis-table>` and :ref:`Decode+VPP <mandatory-dec-vpp-apis-table>` APIs
194 tables:
195
196 .. _mandatory-enc-apis-table:
197
198 .. list-table:: Mandatory Encode APIs
199 :header-rows: 1
200 :widths: 50 50
201
202 * - **Functions**
203 - **Description**
204 * - | :cpp:func:`MFXVideoENCODE_Init`
205 | :cpp:func:`MFXVideoENCODE_Close`
206 | :cpp:func:`MFXVideoENCODE_Query`
207 | :cpp:func:`MFXVideoENCODE_EncodeFrameAsync`
208 - Required functions if the implementation implements any encoder.
209
210 .. _mandatory-dec-apis-table:
211
212 .. list-table:: Mandatory Decode APIs
213 :header-rows: 1
214 :widths: 50 50
215
216 * - **Functions**
217 - **Description**
218 * - | :cpp:func:`MFXVideoDECODE_Init`
219 | :cpp:func:`MFXVideoDECODE_Close`
220 | :cpp:func:`MFXVideoDECODE_Query`
221 | :cpp:func:`MFXVideoDECODE_DecodeFrameAsync`
222 - Required functions if the implementation implements any decoder.
223
224 .. _mandatory-vpp-apis-table:
225
226 .. list-table:: Mandatory VPP APIs
227 :header-rows: 1
228 :widths: 50 50
229
230 * - **Functions**
231 - **Description**
232 * - | :cpp:func:`MFXVideoVPP_Init`
233 | :cpp:func:`MFXVideoVPP_Close`
234 | :cpp:func:`MFXVideoVPP_Query`
235 | :cpp:func:`MFXVideoVPP_RunFrameVPPAsync` or :cpp:func:`MFXVideoVPP_ProcessFrameAsync`
236 - Required functions if the implementation implements any VPP filter.
237
238 .. _mandatory-dec-vpp-apis-table:
239
240 .. list-table:: Mandatory Decode+VPP APIs
241 :header-rows: 1
242 :widths: 50 50
243
244 * - **Functions**
245 - **Description**
246 * - | :cpp:func:`MFXVideoDECODE_VPP_Init`
247 | :cpp:func:`MFXVideoDECODE_VPP_DecodeFrameAsync`
248 | :cpp:func:`MFXVideoDECODE_VPP_Close`
249 - Required functions if the implementation implements any Decode+VPP component.
250
251 .. note:: Mandatory functions must not return the
252 :cpp:enumerator:`MFX_ERR_NOT_IMPLEMENTED` status.
253
254 If at least one of the encoder, decoder, or VPP filter functions is implemented,
255 the :cpp:func:`MFXQueryImplsDescription` function must return a valid
256 :cpp:struct:`mfxImplDescription` structure instance with mandatory capabilities
257 of the implementation, including decoder, encoder, or VPP capabilities information.
258
259 If the implementation supports internal memory allocation by exposing at least one of the
260 function from that family: :ref:`internal memory allocation and management API <func_memory>` then
261 implementation of whole scope of the :cpp:struct:`mfxFrameSurfaceInterface` structure as a part of
262 the :cpp:struct:`mfxFrameSurface1` is mandatory.
263
264 Any other functions or extension buffers are optional for the implementation.
265
266