| 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 |