Debian Codegraph @

doc/spec/source/programming_guide/VPL_prg_frame.rst

raw
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`.