| 1 |
.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation |
| 2 |
.. |
| 3 |
.. SPDX-License-Identifier: CC-BY-4.0 |
| 4 |
|
| 5 |
======================================== |
| 6 |
Working Directly with VA-API for Linux\* |
| 7 |
======================================== |
| 8 |
|
| 9 |
|msdk_full_name| takes care of all memory and synchronization related operations in the VA-API. |
| 10 |
The application may need to extend |msdk_full_name| functionality by working directly |
| 11 |
with the VA-API for Linux\*, for example to implement a customized external allocator. |
| 12 |
This section describes basic memory management and synchronization techniques. |
| 13 |
|
| 14 |
To create the VA surface pool, the application should call the vaCreateSurfaces |
| 15 |
function: |
| 16 |
|
| 17 |
.. literalinclude:: ../snippets/appnd_e.c |
| 18 |
:language: c++ |
| 19 |
:start-after: /*beg1*/ |
| 20 |
:end-before: /*end1*/ |
| 21 |
:lineno-start: 1 |
| 22 |
|
| 23 |
To destroy the surface pool, the application should call the vaDestroySurfaces |
| 24 |
function: |
| 25 |
|
| 26 |
.. literalinclude:: ../snippets/appnd_e.c |
| 27 |
:language: c++ |
| 28 |
:start-after: /*beg2*/ |
| 29 |
:end-before: /*end2*/ |
| 30 |
:lineno-start: 1 |
| 31 |
|
| 32 |
If the application works with hardware acceleration through |msdk_full_name|, then it can |
| 33 |
access surface data immediately after successful completion of |
| 34 |
the :cpp:func:`MFXVideoCORE_SyncOperation` call. If the application works with |
| 35 |
hardware acceleration directly, then it must check surface status before |
| 36 |
accessing data in video memory. This check can be done asynchronously by calling |
| 37 |
the vaQuerySurfaceStatus function or synchronously by calling the vaSyncSurface |
| 38 |
function. |
| 39 |
|
| 40 |
After successful synchronization, the application can access surface data. |
| 41 |
Accessing surface data is performed in two steps: |
| 42 |
|
| 43 |
#. Create VAImage from surface. |
| 44 |
#. Map image buffer to system memory. |
| 45 |
|
| 46 |
After mapping, the VAImage.offsets[3] array holds offsets to each color |
| 47 |
plain in a mapped buffer and the VAImage.pitches[3] array holds color plain |
| 48 |
pitches in bytes. For packed data formats, only first entries in these |
| 49 |
arrays are valid. The following example shows how to access data in a NV12 surface: |
| 50 |
|
| 51 |
.. literalinclude:: ../snippets/appnd_e.c |
| 52 |
:language: c++ |
| 53 |
:start-after: /*beg3*/ |
| 54 |
:end-before: /*end3*/ |
| 55 |
:lineno-start: 1 |
| 56 |
|
| 57 |
|
| 58 |
After processing data in a VA surface, the application should release resources |
| 59 |
allocated for the mapped buffer and VAImage object: |
| 60 |
|
| 61 |
.. literalinclude:: ../snippets/appnd_e.c |
| 62 |
:language: c++ |
| 63 |
:start-after: /*beg4*/ |
| 64 |
:end-before: /*end4*/ |
| 65 |
:lineno-start: 1 |
| 66 |
|
| 67 |
In some cases, in order to retrieve encoded bitstream data from video memory, |
| 68 |
the application must use the VABuffer to store data. The following example shows |
| 69 |
how to create, use, and destroy the VABuffer: |
| 70 |
|
| 71 |
.. literalinclude:: ../snippets/appnd_e.c |
| 72 |
:language: c++ |
| 73 |
:start-after: /*beg5*/ |
| 74 |
:end-before: /*end5*/ |
| 75 |
:lineno-start: 1 |
| 76 |
|
| 77 |
Note that the vaMapBuffer function returns pointers to different objects |
| 78 |
depending on the mapped buffer type. The VAImage is a plain data buffer and the |
| 79 |
encoded bitstream is a VACodedBufferSegment structure. The application cannot use |
| 80 |
VABuffer for synchronization. If encoding, it is recommended to synchronize |
| 81 |
using the VA surface as described above. |