| 1 |
.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation |
| 2 |
.. |
| 3 |
.. SPDX-License-Identifier: CC-BY-4.0 |
| 4 |
|
| 5 |
================ |
| 6 |
Frame and Fields |
| 7 |
================ |
| 8 |
|
| 9 |
In |vpl_short_name| terminology, a frame (also referred to as frame surface) contains either |
| 10 |
a progressive frame or a complementary field pair. If the frame is a |
| 11 |
complementary field pair, the odd lines of the surface buffer store the top |
| 12 |
fields and the even lines of the surface buffer store the bottom fields. |
| 13 |
|
| 14 |
.. _frame-surface-manag: |
| 15 |
|
| 16 |
------------------------ |
| 17 |
Frame Surface Management |
| 18 |
------------------------ |
| 19 |
|
| 20 |
During encoding, decoding, or video processing, cases arise that require reserving |
| 21 |
input or output frames for future use. For example, when decoding, a frame that |
| 22 |
is ready for output must remain as a reference frame until the current sequence |
| 23 |
pattern ends. The usual method to manage this is to cache the frames internally. |
| 24 |
This method requires a copy operation, which can significantly reduce performance. |
| 25 |
|
| 26 |
|vpl_short_name| has two approaches to avoid the need for copy operations. The legacy approach |
| 27 |
uses a frame-locking mechanism that works as follows: |
| 28 |
|
| 29 |
#. The application allocates a pool of frame surfaces large enough to include |vpl_short_name| |
| 30 |
function I/O frame surfaces and internal cache needs. Each frame surface |
| 31 |
maintains a ``Locked`` counter, which is part of the :cpp:struct:`mfxFrameData` |
| 32 |
structure. The ``Locked`` counter is initially set to zero. |
| 33 |
#. The application calls a |vpl_short_name| function with frame surfaces from the pool whose |
| 34 |
``Locked`` counter is set as appropriate for the desired operation. For decoding |
| 35 |
or video processing operations, where |vpl_short_name| uses the surfaces to write, the |
| 36 |
``Locked`` counter should be equal to zero. If the |vpl_short_name| function needs to reserve |
| 37 |
any frame surface, the |vpl_short_name| function increases the ``Locked`` counter of the frame |
| 38 |
surface. A non-zero ``Locked`` counter indicates that the calling application must |
| 39 |
treat the frame surface as “in use.” When the frame surface is in use, the |
| 40 |
application can read but cannot alter, move, delete, or free the frame surface. |
| 41 |
#. In subsequent |vpl_short_name| executions, if the frame surface is no longer in use, |
| 42 |
|vpl_short_name| decreases the ``Locked`` counter. When the ``Locked`` counter reaches zero, the |
| 43 |
application is free to do as it wishes with the frame surface. |
| 44 |
|
| 45 |
In general, the application should not increase or decrease the ``Locked`` counter |
| 46 |
since |vpl_short_name| manages this field. If, for some reason, the application needs to |
| 47 |
modify the ``Locked`` counter, the operation must be atomic to avoid a race condition. |
| 48 |
|
| 49 |
|vpl_short_name| API version 2.0 introduces the :cpp:struct:`mfxFrameSurfaceInterface` structure |
| 50 |
which provides a set of callback functions for the :cpp:struct:`mfxFrameSurface1` |
| 51 |
structure to work with frame surfaces. This interface defines :cpp:struct:`mfxFrameSurface1` as a |
| 52 |
reference counted object which can be allocated by |vpl_short_name| or the application. The |
| 53 |
application must follow the general rules of operation with reference counted |
| 54 |
objects. For example, when surfaces are allocated by |vpl_short_name| during |
| 55 |
:cpp:func:`MFXVideoDECODE_DecodeFrameAsync` or with the help of |
| 56 |
:cpp:func:`MFXMemory_GetSurfaceForVPP` or :cpp:func:`MFXMemory_GetSurfaceForVPPOut` or |
| 57 |
:cpp:func:`MFXMemory_GetSurfaceForEncode`, the application must call the corresponding |
| 58 |
:cpp:member:`mfxFrameSurfaceInterface::Release` |
| 59 |
function for the surfaces that are no longer in use. |
| 60 |
|
| 61 |
.. attention:: Note that the ``Locked`` counter defines read/write access policies |
| 62 |
and the reference counter is responsible for managing a frame's |
| 63 |
lifetime. |
| 64 |
|
| 65 |
The second approach to avoid the need for copy operations is based on the |
| 66 |
:cpp:struct:`mfxFrameSurfaceInterface` and works as follows: |
| 67 |
|
| 68 |
#. |vpl_short_name| or the application allocates a frame surface and the application stores |
| 69 |
a value of reference counter obtained through |
| 70 |
:cpp:member:`mfxFrameSurfaceInterface::GetRefCounter`. |
| 71 |
|
| 72 |
#. The application calls a |vpl_short_name| function with the frame surface. If |vpl_short_name| needs |
| 73 |
to reserve the frame surface it increments the reference counter through the |
| 74 |
:cpp:member:`mfxFrameSurfaceInterface::AddRef` call. |
| 75 |
When the frame surface is no longer in use by the |vpl_short_name| it decrements reference counter through |
| 76 |
the :cpp:member:`mfxFrameSurfaceInterface::Release` call |
| 77 |
which returns the reference counter to the original value. |
| 78 |
|
| 79 |
#. The application checks the reference counter of the frame surface and when it is equal |
| 80 |
to the original value after allocation, it can reuse the reference counter for subsequent operations. |
| 81 |
|
| 82 |
|
| 83 |
.. note:: All :cpp:struct:`mfxFrameSurface1` structures starting from |
| 84 |
mfxFrameSurface1::mfxStructVersion = {1,1} support the |
| 85 |
:cpp:struct:`mfxFrameSurfaceInterface`. |