1 | The 0.5 TMuC release introduces new unified config file and command line |
---|
2 | parsing code. This allows all configuration file options to be specified |
---|
3 | on the command line and permits the use of multiple config files. |
---|
4 | |
---|
5 | Compatability with command line options in previous TMuC releases is |
---|
6 | maintained with the following exceptions: |
---|
7 | - Commandline -1/-0 FEN does not implicitly set ASR, |
---|
8 | this now matches the behaviour of the config file. |
---|
9 | - FramesToBeEncoded is now the preferred name for FrameToBeEncoded |
---|
10 | (the old option still exists for compatibility) |
---|
11 | - Commandline & Config, setting of GOPSize nolonger unconditionally |
---|
12 | sets RateGOPSize. If RateGOPSize is never set, it assumes as its |
---|
13 | default value, the value of GOPSize. |
---|
14 | |
---|
15 | Unless it is specifically required, do not set the RateGOPSize to a |
---|
16 | value other than -1. This value (the default) causes RateGOPSize |
---|
17 | to inherit the final value of GOPSize. While setting config files |
---|
18 | to have RateGOPSize = GOPSize does no immediate harm, it causes |
---|
19 | confusion when GOPSize is altered (without altering RateGOPSize) and |
---|
20 | behaviour changes relating to GPB. |
---|
21 | |
---|
22 | All configuration options may be specified on the command line using the |
---|
23 | following syntax: |
---|
24 | --CfgOptionName=value |
---|
25 | For example, |
---|
26 | --InputFile=Kimono1_1920x1080_24.yuv |
---|
27 | |
---|
28 | A list of all options avaliable is provided by running the encoder with |
---|
29 | either no options, or the option "--help". |
---|
30 | |
---|
31 | The command line is evaluated in the order of options given, for example: |
---|
32 | ./encoder -c file1.cfg --UseFoo=7 -c file2.cfg |
---|
33 | |
---|
34 | The following may be observed: |
---|
35 | - file2.cfg overrides any arguments set in file1. |
---|
36 | - file1.cfg overrides any default arguments |
---|
37 | - if file2.cfg specifies "UseFoo", this value will be used |
---|
38 | otherwise, "UseFoo" will have the value 7. |
---|
39 | |
---|
40 | ==================== |
---|
41 | Notes for developers |
---|
42 | ==================== |
---|
43 | The new unified config file and command line parsing code allows all |
---|
44 | configuration options, storage location, defaults, help text to be specified |
---|
45 | in a single place. No custom value parsing code is required. |
---|
46 | |
---|
47 | Options are specified in TAppEncCfg::parseCfg() using the following syntax: |
---|
48 | {{{ |
---|
49 | /* storage for options */ |
---|
50 | int storage_variable_int; |
---|
51 | unsigned storage_variable_unsigned; |
---|
52 | float storage_variable_float; |
---|
53 | bool storage_variable_bool; |
---|
54 | string storage_variable_string; |
---|
55 | |
---|
56 | /* set up configuration */ |
---|
57 | namespace po = df::program_options_lite; |
---|
58 | po::Options opts; |
---|
59 | opts.addOptions() |
---|
60 | /*( option spec , reference to storage, default, help text)*/ |
---|
61 | ("option_spec0", storage_variable_int, -42, "help text") |
---|
62 | ("option_spec1", storage_variable_unsigned, 17u, "help text") |
---|
63 | ("option_spec2", storage_variable_bool, true, "help text") |
---|
64 | ("option_spec3", storage_variable_float, 4.0f, "help text") |
---|
65 | ("option_spec4", storage_variable_string, string("foo"), "help text") |
---|
66 | ; |
---|
67 | }}} |
---|
68 | |
---|
69 | NB, the help text is optional. |
---|
70 | |
---|
71 | Where, the option_spec is a string containing comma separated names in |
---|
72 | the following forms: |
---|
73 | - multi-charcter names are longopts that are handled in gnu style |
---|
74 | (and may be handled in a config file) |
---|
75 | - single-character names are short opts that are handled in posix style |
---|
76 | (and are not handled in a config file) |
---|
77 | prefixing a multi-character name stops it being handled in the config. |
---|
78 | |
---|
79 | For example: |
---|
80 | option spec | config file formats | command line formats |
---|
81 | "Name" | Name:value | --Name=value |
---|
82 | "n" | --none-- | -n value |
---|
83 | "-name" | --none-- | -name value |
---|
84 | "Name,n" | Name:value | "--Name=value" or "-n value" |
---|
85 | |
---|
86 | Caveats: |
---|
87 | - The default values need to be specified in the same type as the storage |
---|
88 | variable. Eg, an unsigned int, would need to be specified as "17u" not |
---|
89 | "17" |
---|
90 | |
---|
91 | Help text formatting: |
---|
92 | - Help text will be automatically wrapped and aligned if longer than the |
---|
93 | available space. |
---|
94 | - To force wrapping at a particular point, insert a newline character '\n' |
---|
95 | Eg: "Foo values:\n value1 - a\n value2 - b\n value3 - c" |
---|
96 | Gives: |
---|
97 | Foo values: |
---|
98 | value1 - a |
---|
99 | value2 - b |
---|
100 | value3 - c |
---|
101 | |
---|
102 | Please report any issues, or requests for support with the configuration to: |
---|
103 | David Flynn <davidf@rd.bbc.co.uk> |
---|