.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

============
Status Codes
============

The oneVPL functions are organized into categories for easy reference. The categories
include :term:`ENCODE` (encoding functions), :term:`DECODE` (decoding functions),
and :term:`VPP` (video processing functions).

**Init**, **Reset**, and **Close** are member functions within the ENCODE,
DECODE, and VPP classes that initialize, restart, and deinitialize
specific operations defined for the class. Call all member functions of a
given class within the **Init** **-** **Reset** **-** **Close** sequence, except
**Query** and **QueryIOSurf**. **Reset** functions are optional within the sequence.

The **Init** and **Reset** member functions set up necessary internal
structures for media processing. **Init** functions allocate memory and **Reset**
functions only reuse allocated internal memory. If oneVPL needs to allocate
additional memory, **Reset** can fail. **Reset** functions can also
fine-tune ENCODE and VPP parameters during those processes or reposition
a bitstream during DECODE.

All oneVPL functions return status codes to indicate if an operation succeeded
or failed. The :cpp:enumerator:`mfxStatus::MFX_ERR_NONE` status code indicates
that the function successfully completed its operation. Error status codes are
less than :cpp:enumerator:`mfxStatus::MFX_ERR_NONE` and warning status codes are
greater than :cpp:enumerator:`mfxStatus::MFX_ERR_NONE`. See the
:cpp:enum:`mfxStatus` enumerator for all defined status codes.

If a oneVPL function returns a warning, it has sufficiently completed its operation.
Note that the output of the function might not be strictly reliable. The
application must check the validity of the output generated by the function.

If a oneVPL function returns an error (except :cpp:enumerator:`mfxStatus::MFX_ERR_MORE_DATA`,
:cpp:enumerator:`mfxStatus::MFX_ERR_MORE_SURFACE`, or
:cpp:enumerator:`mfxStatus::MFX_ERR_MORE_BITSTREAM`), the function aborts the
operation. The application must call either the **Reset** function to reset the
class back to a clean state or the **Close** function to terminate the operation.
The behavior is undefined if the application continues to call any class member
functions without a **Reset** or **Close**. To avoid memory leaks, always call the
**Close** function after **Init**.