source: 3DVCSoftware/trunk/README-newconfig.txt @ 760

Last change on this file since 760 was 2, checked in by hhi, 13 years ago

inital import

  • Property svn:eol-style set to native
File size: 4.1 KB
Line 
1The 0.5 TMuC release introduces new unified config file and command line
2parsing code.  This allows all configuration file options to be specified
3on the command line and permits the use of multiple config files.
4
5Compatability with command line options in previous TMuC releases is
6maintained 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
22All configuration options may be specified on the command line using the
23following syntax:
24  --CfgOptionName=value
25For example,
26  --InputFile=Kimono1_1920x1080_24.yuv
27
28A list of all options avaliable is provided by running the encoder with
29either no options, or the option "--help".
30
31The command line is evaluated in the order of options given, for example:
32    ./encoder -c file1.cfg --UseFoo=7 -c file2.cfg
33
34The 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====================
41Notes for developers
42====================
43The new unified config file and command line parsing code allows all
44configuration options, storage location, defaults, help text to be specified
45in a single place.  No custom value parsing code is required.
46
47Options 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
69NB, the help text is optional.
70
71Where, the option_spec is a string containing comma separated names in
72the 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
79For 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
86Caveats:
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
91Help 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
102Please report any issues, or requests for support with the configuration to:
103  David Flynn <davidf@rd.bbc.co.uk>
Note: See TracBrowser for help on using the repository browser.