| 1 |
.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation |
| 2 |
.. |
| 3 |
.. SPDX-License-Identifier: CC-BY-4.0 |
| 4 |
|
| 5 |
.. _config-interface: |
| 6 |
|
| 7 |
======================= |
| 8 |
Parameter Configuration |
| 9 |
======================= |
| 10 |
|
| 11 |
|vpl_short_name| API 2.10 introduces a new interface for configuring |
| 12 |
|vpl_short_name| for encode, decode, or video processing. Applications may |
| 13 |
optionally use the new function :cpp:member:`mfxConfigInterface::SetParameter` |
| 14 |
to fill in data structures used for initialization, including |
| 15 |
:cpp:struct:`mfxVideoParam` and extension buffers of type |
| 16 |
:cpp:struct:`mfxExtBuffer`. |
| 17 |
|
| 18 |
:cpp:member:`mfxConfigInterface::SetParameter` accepts as input key-value pairs |
| 19 |
of ``char *`` strings, converts these strings to appropriate C data types, and writes the |
| 20 |
results into the application-provided initialization structures. This can provide |
| 21 |
a simpler and more flexible initialization method for applications which accept |
| 22 |
user input in the form of strings, or which store configuration information in |
| 23 |
formats such as XML, YAML, or JSON. |
| 24 |
|
| 25 |
Applications may freely mix use of |
| 26 |
:cpp:member:`mfxConfigInterface::SetParameter` with standard C-style |
| 27 |
initialization of the same structures. Additionally, the use of |
| 28 |
:cpp:member:`mfxConfigInterface::SetParameter` facilitates support of new |
| 29 |
parameters which may be added to |vpl_short_name| API in the future. When new |
| 30 |
extension buffers are added to |vpl_short_name| API, |
| 31 |
:cpp:member:`mfxConfigInterface::SetParameter` will enable the application to |
| 32 |
allocate buffers of the appropriate size, and initialize them with the required |
| 33 |
values, without recompiling the application. |
| 34 |
|
| 35 |
------------------------------------ |
| 36 |
Setting a parameter in mfxVideoParam |
| 37 |
------------------------------------ |
| 38 |
|
| 39 |
The following code snippet shows an example of setting a parameter in the structure :cpp:struct:`mfxVideoParam`. |
| 40 |
|
| 41 |
.. literalinclude:: ../snippets/prg_config.cpp |
| 42 |
:language: c++ |
| 43 |
:start-after: /*beg1*/ |
| 44 |
:end-before: /*end1*/ |
| 45 |
:lineno-start: 1 |
| 46 |
|
| 47 |
------------------------------------------ |
| 48 |
Setting a parameter in an extension buffer |
| 49 |
------------------------------------------ |
| 50 |
|
| 51 |
The following code snippet shows an example of setting a parameter in the extension buffer |
| 52 |
:cpp:struct:`mfxExtHEVCParam` and attaching it to the structure :cpp:struct:`mfxVideoParam`. |
| 53 |
|
| 54 |
When setting a parameter which maps to an extension buffer, the function first |
| 55 |
checks whether the required extension buffer has been attached to the provided |
| 56 |
:cpp:struct:`mfxVideoParam`. If so, |vpl_short_name| will update the |
| 57 |
corresponding field in the extension buffer and return MFX_ERR_NONE. |
| 58 |
|
| 59 |
If the required extension buffer is not attached, |vpl_short_name| will instead |
| 60 |
return MFX_ERR_MORE_EXTBUFFER. If this happens, the application is required to |
| 61 |
allocate an extension buffer whose size and buffer ID are indicated by the |
| 62 |
ext_buffer parameter returned from the call to |
| 63 |
:cpp:member:`mfxConfigInterface::SetParameter`. This extension buffer must then |
| 64 |
be attached to :cpp:struct:`mfxVideoParam`, then |
| 65 |
:cpp:member:`mfxConfigInterface::SetParameter` should be called again with the |
| 66 |
same arguments. If the key and value strings represent a valid parameter in the |
| 67 |
newly-attached extension buffer, the function will now return MFX_ERR_NONE. |
| 68 |
|
| 69 |
.. literalinclude:: ../snippets/prg_config.cpp |
| 70 |
:language: c++ |
| 71 |
:start-after: /*beg2*/ |
| 72 |
:end-before: /*end2*/ |
| 73 |
:lineno-start: 1 |
| 74 |
|