Debian Codegraph @

doc/spec/source/programming_guide/VPL_prg_mem.rst

raw
1 .. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
2 ..
3 .. SPDX-License-Identifier: CC-BY-4.0
4
5 .. _mem-alloc-ext-alloc:
6
7 =========================================
8 Memory Allocation and External Allocators
9 =========================================
10
11 There are two models of memory management in |vpl_short_name|: internal and external.
12
13 --------------------------
14 External Memory Management
15 --------------------------
16
17 In the external memory model, the application must allocate sufficient memory for
18 input and output parameters and buffers and deallocate it when |vpl_short_name| functions
19 complete their operations. During execution, the |vpl_short_name| functions use callback
20 functions to the application to manage memory for video frames through the
21 external allocator interface :cpp:struct:`mfxFrameAllocator`.
22
23 If an application needs to control the allocation of video frames, it can use
24 callback functions through the :cpp:struct:`mfxFrameAllocator` interface. If an
25 application does not specify an allocator, an internal allocator is used. However,
26 if an application uses video memory surfaces for input and output, it must specify
27 the hardware acceleration device and an external frame allocator using
28 :cpp:struct:`mfxFrameAllocator`.
29
30 The external frame allocator can allocate different frame types:
31
32 - In-system memory.
33 - In-video memory, as 'Decoder Render Targets' or 'Processor Render Targets.'
34 See :ref:`Working with Hardware Acceleration <hw-acceleration>` for additional
35 details.
36
37 The external frame allocator responds only to frame allocation requests for the
38 requested memory type and returns :cpp:enumerator:`mfxStatus::MFX_ERR_UNSUPPORTED`
39 for all other types. The allocation request uses flags (part of the memory type
40 field) to indicate which |vpl_short_name| class initiated the request so that the external
41 frame allocator can respond accordingly.
42
43 The following example shows a simple external frame allocator:
44
45 .. literalinclude:: ../snippets/prg_mem.c
46 :language: c++
47 :start-after: /*beg1*/
48 :end-before: /*end1*/
49 :lineno-start: 1
50
51 For system memory, it is highly recommended to allocate memory for all
52 planes of the same frame as a single buffer (using one single malloc call).
53
54 .. _internal-mem-manage:
55
56 --------------------------
57 Internal Memory Management
58 --------------------------
59
60 In the internal memory management model, |vpl_short_name| provides interface functions for
61 frames allocation:
62
63 - :cpp:func:`MFXMemory_GetSurfaceForVPP`
64
65 - :cpp:func:`MFXMemory_GetSurfaceForVPPOut`
66
67 - :cpp:func:`MFXMemory_GetSurfaceForEncode`
68
69 - :cpp:func:`MFXMemory_GetSurfaceForDecode`
70
71 These functions are used together with :cpp:struct:`mfxFrameSurfaceInterface`
72 for surface management. The surface returned by these functions is a reference
73 counted object and the application must call :cpp:member:`mfxFrameSurfaceInterface::Release`
74 after finishing all operations with the surface. In this model the application
75 does not need to create and set the external allocator to |vpl_short_name|.
76
77 Another method to obtain an internally allocated surface is to call
78 :cpp:func:`MFXVideoDECODE_DecodeFrameAsync` with a working surface equal to NULL
79 (see :ref:`Simplified decoding procedure <simplified-decoding-procedure>`). In
80 this scenario, the decoder will allocate a new refcountable
81 :cpp:struct:`mfxFrameSurface1` and return it to the user. All assumed contracts
82 with the user are similar to the **MFXMemory_GetSurfaceForXXX** functions.
83
84 ------------------------
85 mfxFrameSurfaceInterface
86 ------------------------
87
88 |vpl_short_name| API version 2.0 introduces :cpp:struct:`mfxFrameSurfaceInterface`. This
89 interface is a set of callback functions to manage the lifetime of allocated
90 surfaces, get access to pixel data, and obtain native handles and device
91 abstractions (if suitable). Instead of directly accessing
92 :cpp:struct:`mfxFrameSurface1` structure members, it's recommended to use
93 the :cpp:struct:`mfxFrameSurfaceInterface` if present or call external
94 allocator callback functions if set.
95
96 The following pseudo code shows the usage of :cpp:struct:`mfxFrameSurfaceInterface`
97 for memory sharing:
98
99 .. literalinclude:: ../snippets/prg_mem.c
100 :language: c++
101 :start-after: /*beg2*/
102 :end-before: /*end2*/
103 :lineno-start: 1