Debian Codegraph @

doc/spec/source/programming_guide/VPL_prg_config.rst

raw
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