Debian Codegraph @

doc/spec/source/programming_guide/VPL_prg_stc.rst

raw
1 .. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
2 ..
3 .. SPDX-License-Identifier: CC-BY-4.0
4
5 ============
6 Status Codes
7 ============
8
9 The |vpl_short_name| functions are organized into categories for easy reference. The categories
10 include :term:`ENCODE` (encoding functions), :term:`DECODE` (decoding functions),
11 and :term:`VPP` (video processing functions).
12
13 **Init**, **Reset**, and **Close** are member functions within the ENCODE,
14 DECODE, and VPP classes that initialize, restart, and deinitialize
15 specific operations defined for the class. Call all member functions of a
16 given class within the **Init** **-** **Reset** **-** **Close** sequence, except
17 **Query** and **QueryIOSurf**. **Reset** functions are optional within the sequence.
18
19 The **Init** and **Reset** member functions set up necessary internal
20 structures for media processing. **Init** functions allocate memory and **Reset**
21 functions only reuse allocated internal memory. If |vpl_short_name| needs to allocate
22 additional memory, **Reset** can fail. **Reset** functions can also
23 fine-tune ENCODE and VPP parameters during those processes or reposition
24 a bitstream during DECODE.
25
26 All |vpl_short_name| functions return status codes to indicate if an operation succeeded
27 or failed. The :cpp:enumerator:`mfxStatus::MFX_ERR_NONE` status code indicates
28 that the function successfully completed its operation. Error status codes are
29 less than :cpp:enumerator:`mfxStatus::MFX_ERR_NONE` and warning status codes are
30 greater than :cpp:enumerator:`mfxStatus::MFX_ERR_NONE`. See the
31 :cpp:enum:`mfxStatus` enumerator for all defined status codes.
32
33 If a |vpl_short_name| function returns a warning, it has sufficiently completed its operation.
34 Note that the output of the function might not be strictly reliable. The
35 application must check the validity of the output generated by the function.
36
37 If a |vpl_short_name| function returns an error (except :cpp:enumerator:`mfxStatus::MFX_ERR_MORE_DATA`,
38 :cpp:enumerator:`mfxStatus::MFX_ERR_MORE_SURFACE`, or
39 :cpp:enumerator:`mfxStatus::MFX_ERR_MORE_BITSTREAM`), the function aborts the
40 operation. The application must call either the **Reset** function to reset the
41 class back to a clean state or the **Close** function to terminate the operation.
42 The behavior is undefined if the application continues to call any class member
43 functions without a **Reset** or **Close**. To avoid memory leaks, always call the
44 **Close** function after **Init**.