opt.h 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865
  1. /*
  2. * AVOptions
  3. * copyright (c) 2005 Michael Niedermayer <michaelni@gmx.at>
  4. *
  5. * This file is part of FFmpeg.
  6. *
  7. * FFmpeg is free software; you can redistribute it and/or
  8. * modify it under the terms of the GNU Lesser General Public
  9. * License as published by the Free Software Foundation; either
  10. * version 2.1 of the License, or (at your option) any later version.
  11. *
  12. * FFmpeg is distributed in the hope that it will be useful,
  13. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  15. * Lesser General Public License for more details.
  16. *
  17. * You should have received a copy of the GNU Lesser General Public
  18. * License along with FFmpeg; if not, write to the Free Software
  19. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  20. */
  21. #ifndef AVUTIL_OPT_H
  22. #define AVUTIL_OPT_H
  23. /**
  24. * @file
  25. * AVOptions
  26. */
  27. #include "rational.h"
  28. #include "avutil.h"
  29. #include "dict.h"
  30. #include "log.h"
  31. #include "pixfmt.h"
  32. #include "samplefmt.h"
  33. #include "version.h"
  34. /**
  35. * @defgroup avoptions AVOptions
  36. * @ingroup lavu_data
  37. * @{
  38. * AVOptions provide a generic system to declare options on arbitrary structs
  39. * ("objects"). An option can have a help text, a type and a range of possible
  40. * values. Options may then be enumerated, read and written to.
  41. *
  42. * @section avoptions_implement Implementing AVOptions
  43. * This section describes how to add AVOptions capabilities to a struct.
  44. *
  45. * All AVOptions-related information is stored in an AVClass. Therefore
  46. * the first member of the struct should be a pointer to an AVClass describing it.
  47. * The option field of the AVClass must be set to a NULL-terminated static array
  48. * of AVOptions. Each AVOption must have a non-empty name, a type, a default
  49. * value and for number-type AVOptions also a range of allowed values. It must
  50. * also declare an offset in bytes from the start of the struct, where the field
  51. * associated with this AVOption is located. Other fields in the AVOption struct
  52. * should also be set when applicable, but are not required.
  53. *
  54. * The following example illustrates an AVOptions-enabled struct:
  55. * @code
  56. * typedef struct test_struct {
  57. * const AVClass *class;
  58. * int int_opt;
  59. * char *str_opt;
  60. * uint8_t *bin_opt;
  61. * int bin_len;
  62. * } test_struct;
  63. *
  64. * static const AVOption test_options[] = {
  65. * { "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt),
  66. * AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX },
  67. * { "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
  68. * AV_OPT_TYPE_STRING },
  69. * { "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
  70. * AV_OPT_TYPE_BINARY },
  71. * { NULL },
  72. * };
  73. *
  74. * static const AVClass test_class = {
  75. * .class_name = "test class",
  76. * .item_name = av_default_item_name,
  77. * .option = test_options,
  78. * .version = LIBAVUTIL_VERSION_INT,
  79. * };
  80. * @endcode
  81. *
  82. * Next, when allocating your struct, you must ensure that the AVClass pointer
  83. * is set to the correct value. Then, av_opt_set_defaults() can be called to
  84. * initialize defaults. After that the struct is ready to be used with the
  85. * AVOptions API.
  86. *
  87. * When cleaning up, you may use the av_opt_free() function to automatically
  88. * free all the allocated string and binary options.
  89. *
  90. * Continuing with the above example:
  91. *
  92. * @code
  93. * test_struct *alloc_test_struct(void)
  94. * {
  95. * test_struct *ret = av_mallocz(sizeof(*ret));
  96. * ret->class = &test_class;
  97. * av_opt_set_defaults(ret);
  98. * return ret;
  99. * }
  100. * void free_test_struct(test_struct **foo)
  101. * {
  102. * av_opt_free(*foo);
  103. * av_freep(foo);
  104. * }
  105. * @endcode
  106. *
  107. * @subsection avoptions_implement_nesting Nesting
  108. * It may happen that an AVOptions-enabled struct contains another
  109. * AVOptions-enabled struct as a member (e.g. AVCodecContext in
  110. * libavcodec exports generic options, while its priv_data field exports
  111. * codec-specific options). In such a case, it is possible to set up the
  112. * parent struct to export a child's options. To do that, simply
  113. * implement AVClass.child_next() and AVClass.child_class_next() in the
  114. * parent struct's AVClass.
  115. * Assuming that the test_struct from above now also contains a
  116. * child_struct field:
  117. *
  118. * @code
  119. * typedef struct child_struct {
  120. * AVClass *class;
  121. * int flags_opt;
  122. * } child_struct;
  123. * static const AVOption child_opts[] = {
  124. * { "test_flags", "This is a test option of flags type.",
  125. * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX },
  126. * { NULL },
  127. * };
  128. * static const AVClass child_class = {
  129. * .class_name = "child class",
  130. * .item_name = av_default_item_name,
  131. * .option = child_opts,
  132. * .version = LIBAVUTIL_VERSION_INT,
  133. * };
  134. *
  135. * void *child_next(void *obj, void *prev)
  136. * {
  137. * test_struct *t = obj;
  138. * if (!prev && t->child_struct)
  139. * return t->child_struct;
  140. * return NULL
  141. * }
  142. * const AVClass child_class_next(const AVClass *prev)
  143. * {
  144. * return prev ? NULL : &child_class;
  145. * }
  146. * @endcode
  147. * Putting child_next() and child_class_next() as defined above into
  148. * test_class will now make child_struct's options accessible through
  149. * test_struct (again, proper setup as described above needs to be done on
  150. * child_struct right after it is created).
  151. *
  152. * From the above example it might not be clear why both child_next()
  153. * and child_class_next() are needed. The distinction is that child_next()
  154. * iterates over actually existing objects, while child_class_next()
  155. * iterates over all possible child classes. E.g. if an AVCodecContext
  156. * was initialized to use a codec which has private options, then its
  157. * child_next() will return AVCodecContext.priv_data and finish
  158. * iterating. OTOH child_class_next() on AVCodecContext.av_class will
  159. * iterate over all available codecs with private options.
  160. *
  161. * @subsection avoptions_implement_named_constants Named constants
  162. * It is possible to create named constants for options. Simply set the unit
  163. * field of the option the constants should apply to a string and
  164. * create the constants themselves as options of type AV_OPT_TYPE_CONST
  165. * with their unit field set to the same string.
  166. * Their default_val field should contain the value of the named
  167. * constant.
  168. * For example, to add some named constants for the test_flags option
  169. * above, put the following into the child_opts array:
  170. * @code
  171. * { "test_flags", "This is a test option of flags type.",
  172. * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" },
  173. * { "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0, "test_unit" },
  174. * @endcode
  175. *
  176. * @section avoptions_use Using AVOptions
  177. * This section deals with accessing options in an AVOptions-enabled struct.
  178. * Such structs in FFmpeg are e.g. AVCodecContext in libavcodec or
  179. * AVFormatContext in libavformat.
  180. *
  181. * @subsection avoptions_use_examine Examining AVOptions
  182. * The basic functions for examining options are av_opt_next(), which iterates
  183. * over all options defined for one object, and av_opt_find(), which searches
  184. * for an option with the given name.
  185. *
  186. * The situation is more complicated with nesting. An AVOptions-enabled struct
  187. * may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag
  188. * to av_opt_find() will make the function search children recursively.
  189. *
  190. * For enumerating there are basically two cases. The first is when you want to
  191. * get all options that may potentially exist on the struct and its children
  192. * (e.g. when constructing documentation). In that case you should call
  193. * av_opt_child_class_next() recursively on the parent struct's AVClass. The
  194. * second case is when you have an already initialized struct with all its
  195. * children and you want to get all options that can be actually written or read
  196. * from it. In that case you should call av_opt_child_next() recursively (and
  197. * av_opt_next() on each result).
  198. *
  199. * @subsection avoptions_use_get_set Reading and writing AVOptions
  200. * When setting options, you often have a string read directly from the
  201. * user. In such a case, simply passing it to av_opt_set() is enough. For
  202. * non-string type options, av_opt_set() will parse the string according to the
  203. * option type.
  204. *
  205. * Similarly av_opt_get() will read any option type and convert it to a string
  206. * which will be returned. Do not forget that the string is allocated, so you
  207. * have to free it with av_free().
  208. *
  209. * In some cases it may be more convenient to put all options into an
  210. * AVDictionary and call av_opt_set_dict() on it. A specific case of this
  211. * are the format/codec open functions in lavf/lavc which take a dictionary
  212. * filled with option as a parameter. This makes it possible to set some options
  213. * that cannot be set otherwise, since e.g. the input file format is not known
  214. * before the file is actually opened.
  215. */
  216. enum AVOptionType{
  217. AV_OPT_TYPE_FLAGS,
  218. AV_OPT_TYPE_INT,
  219. AV_OPT_TYPE_INT64,
  220. AV_OPT_TYPE_DOUBLE,
  221. AV_OPT_TYPE_FLOAT,
  222. AV_OPT_TYPE_STRING,
  223. AV_OPT_TYPE_RATIONAL,
  224. AV_OPT_TYPE_BINARY, ///< offset must point to a pointer immediately followed by an int for the length
  225. AV_OPT_TYPE_DICT,
  226. AV_OPT_TYPE_CONST = 128,
  227. AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), ///< offset must point to two consecutive integers
  228. AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'),
  229. AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'),
  230. AV_OPT_TYPE_VIDEO_RATE = MKBETAG('V','R','A','T'), ///< offset must point to AVRational
  231. AV_OPT_TYPE_DURATION = MKBETAG('D','U','R',' '),
  232. AV_OPT_TYPE_COLOR = MKBETAG('C','O','L','R'),
  233. AV_OPT_TYPE_CHANNEL_LAYOUT = MKBETAG('C','H','L','A'),
  234. AV_OPT_TYPE_BOOL = MKBETAG('B','O','O','L'),
  235. };
  236. /**
  237. * AVOption
  238. */
  239. typedef struct AVOption {
  240. const char *name;
  241. /**
  242. * short English help text
  243. * @todo What about other languages?
  244. */
  245. const char *help;
  246. /**
  247. * The offset relative to the context structure where the option
  248. * value is stored. It should be 0 for named constants.
  249. */
  250. int offset;
  251. enum AVOptionType type;
  252. /**
  253. * the default value for scalar options
  254. */
  255. union {
  256. int64_t i64;
  257. double dbl;
  258. const char *str;
  259. /* TODO those are unused now */
  260. AVRational q;
  261. } default_val;
  262. double min; ///< minimum valid value for the option
  263. double max; ///< maximum valid value for the option
  264. int flags;
  265. #define AV_OPT_FLAG_ENCODING_PARAM 1 ///< a generic parameter which can be set by the user for muxing or encoding
  266. #define AV_OPT_FLAG_DECODING_PARAM 2 ///< a generic parameter which can be set by the user for demuxing or decoding
  267. #if FF_API_OPT_TYPE_METADATA
  268. #define AV_OPT_FLAG_METADATA 4 ///< some data extracted or inserted into the file like title, comment, ...
  269. #endif
  270. #define AV_OPT_FLAG_AUDIO_PARAM 8
  271. #define AV_OPT_FLAG_VIDEO_PARAM 16
  272. #define AV_OPT_FLAG_SUBTITLE_PARAM 32
  273. /**
  274. * The option is intended for exporting values to the caller.
  275. */
  276. #define AV_OPT_FLAG_EXPORT 64
  277. /**
  278. * The option may not be set through the AVOptions API, only read.
  279. * This flag only makes sense when AV_OPT_FLAG_EXPORT is also set.
  280. */
  281. #define AV_OPT_FLAG_READONLY 128
  282. #define AV_OPT_FLAG_FILTERING_PARAM (1<<16) ///< a generic parameter which can be set by the user for filtering
  283. //FIXME think about enc-audio, ... style flags
  284. /**
  285. * The logical unit to which the option belongs. Non-constant
  286. * options and corresponding named constants share the same
  287. * unit. May be NULL.
  288. */
  289. const char *unit;
  290. } AVOption;
  291. /**
  292. * A single allowed range of values, or a single allowed value.
  293. */
  294. typedef struct AVOptionRange {
  295. const char *str;
  296. /**
  297. * Value range.
  298. * For string ranges this represents the min/max length.
  299. * For dimensions this represents the min/max pixel count or width/height in multi-component case.
  300. */
  301. double value_min, value_max;
  302. /**
  303. * Value's component range.
  304. * For string this represents the unicode range for chars, 0-127 limits to ASCII.
  305. */
  306. double component_min, component_max;
  307. /**
  308. * Range flag.
  309. * If set to 1 the struct encodes a range, if set to 0 a single value.
  310. */
  311. int is_range;
  312. } AVOptionRange;
  313. /**
  314. * List of AVOptionRange structs.
  315. */
  316. typedef struct AVOptionRanges {
  317. /**
  318. * Array of option ranges.
  319. *
  320. * Most of option types use just one component.
  321. * Following describes multi-component option types:
  322. *
  323. * AV_OPT_TYPE_IMAGE_SIZE:
  324. * component index 0: range of pixel count (width * height).
  325. * component index 1: range of width.
  326. * component index 2: range of height.
  327. *
  328. * @note To obtain multi-component version of this structure, user must
  329. * provide AV_OPT_MULTI_COMPONENT_RANGE to av_opt_query_ranges or
  330. * av_opt_query_ranges_default function.
  331. *
  332. * Multi-component range can be read as in following example:
  333. *
  334. * @code
  335. * int range_index, component_index;
  336. * AVOptionRanges *ranges;
  337. * AVOptionRange *range[3]; //may require more than 3 in the future.
  338. * av_opt_query_ranges(&ranges, obj, key, AV_OPT_MULTI_COMPONENT_RANGE);
  339. * for (range_index = 0; range_index < ranges->nb_ranges; range_index++) {
  340. * for (component_index = 0; component_index < ranges->nb_components; component_index++)
  341. * range[component_index] = ranges->range[ranges->nb_ranges * component_index + range_index];
  342. * //do something with range here.
  343. * }
  344. * av_opt_freep_ranges(&ranges);
  345. * @endcode
  346. */
  347. AVOptionRange **range;
  348. /**
  349. * Number of ranges per component.
  350. */
  351. int nb_ranges;
  352. /**
  353. * Number of componentes.
  354. */
  355. int nb_components;
  356. } AVOptionRanges;
  357. /**
  358. * Show the obj options.
  359. *
  360. * @param req_flags requested flags for the options to show. Show only the
  361. * options for which it is opt->flags & req_flags.
  362. * @param rej_flags rejected flags for the options to show. Show only the
  363. * options for which it is !(opt->flags & req_flags).
  364. * @param av_log_obj log context to use for showing the options
  365. */
  366. int av_opt_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags);
  367. /**
  368. * Set the values of all AVOption fields to their default values.
  369. *
  370. * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass)
  371. */
  372. void av_opt_set_defaults(void *s);
  373. /**
  374. * Set the values of all AVOption fields to their default values. Only these
  375. * AVOption fields for which (opt->flags & mask) == flags will have their
  376. * default applied to s.
  377. *
  378. * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass)
  379. * @param mask combination of AV_OPT_FLAG_*
  380. * @param flags combination of AV_OPT_FLAG_*
  381. */
  382. void av_opt_set_defaults2(void *s, int mask, int flags);
  383. /**
  384. * Parse the key/value pairs list in opts. For each key/value pair
  385. * found, stores the value in the field in ctx that is named like the
  386. * key. ctx must be an AVClass context, storing is done using
  387. * AVOptions.
  388. *
  389. * @param opts options string to parse, may be NULL
  390. * @param key_val_sep a 0-terminated list of characters used to
  391. * separate key from value
  392. * @param pairs_sep a 0-terminated list of characters used to separate
  393. * two pairs from each other
  394. * @return the number of successfully set key/value pairs, or a negative
  395. * value corresponding to an AVERROR code in case of error:
  396. * AVERROR(EINVAL) if opts cannot be parsed,
  397. * the error code issued by av_opt_set() if a key/value pair
  398. * cannot be set
  399. */
  400. int av_set_options_string(void *ctx, const char *opts,
  401. const char *key_val_sep, const char *pairs_sep);
  402. /**
  403. * Parse the key-value pairs list in opts. For each key=value pair found,
  404. * set the value of the corresponding option in ctx.
  405. *
  406. * @param ctx the AVClass object to set options on
  407. * @param opts the options string, key-value pairs separated by a
  408. * delimiter
  409. * @param shorthand a NULL-terminated array of options names for shorthand
  410. * notation: if the first field in opts has no key part,
  411. * the key is taken from the first element of shorthand;
  412. * then again for the second, etc., until either opts is
  413. * finished, shorthand is finished or a named option is
  414. * found; after that, all options must be named
  415. * @param key_val_sep a 0-terminated list of characters used to separate
  416. * key from value, for example '='
  417. * @param pairs_sep a 0-terminated list of characters used to separate
  418. * two pairs from each other, for example ':' or ','
  419. * @return the number of successfully set key=value pairs, or a negative
  420. * value corresponding to an AVERROR code in case of error:
  421. * AVERROR(EINVAL) if opts cannot be parsed,
  422. * the error code issued by av_set_string3() if a key/value pair
  423. * cannot be set
  424. *
  425. * Options names must use only the following characters: a-z A-Z 0-9 - . / _
  426. * Separators must use characters distinct from option names and from each
  427. * other.
  428. */
  429. int av_opt_set_from_string(void *ctx, const char *opts,
  430. const char *const *shorthand,
  431. const char *key_val_sep, const char *pairs_sep);
  432. /**
  433. * Free all allocated objects in obj.
  434. */
  435. void av_opt_free(void *obj);
  436. /**
  437. * Check whether a particular flag is set in a flags field.
  438. *
  439. * @param field_name the name of the flag field option
  440. * @param flag_name the name of the flag to check
  441. * @return non-zero if the flag is set, zero if the flag isn't set,
  442. * isn't of the right type, or the flags field doesn't exist.
  443. */
  444. int av_opt_flag_is_set(void *obj, const char *field_name, const char *flag_name);
  445. /**
  446. * Set all the options from a given dictionary on an object.
  447. *
  448. * @param obj a struct whose first element is a pointer to AVClass
  449. * @param options options to process. This dictionary will be freed and replaced
  450. * by a new one containing all options not found in obj.
  451. * Of course this new dictionary needs to be freed by caller
  452. * with av_dict_free().
  453. *
  454. * @return 0 on success, a negative AVERROR if some option was found in obj,
  455. * but could not be set.
  456. *
  457. * @see av_dict_copy()
  458. */
  459. int av_opt_set_dict(void *obj, struct AVDictionary **options);
  460. /**
  461. * Set all the options from a given dictionary on an object.
  462. *
  463. * @param obj a struct whose first element is a pointer to AVClass
  464. * @param options options to process. This dictionary will be freed and replaced
  465. * by a new one containing all options not found in obj.
  466. * Of course this new dictionary needs to be freed by caller
  467. * with av_dict_free().
  468. * @param search_flags A combination of AV_OPT_SEARCH_*.
  469. *
  470. * @return 0 on success, a negative AVERROR if some option was found in obj,
  471. * but could not be set.
  472. *
  473. * @see av_dict_copy()
  474. */
  475. int av_opt_set_dict2(void *obj, struct AVDictionary **options, int search_flags);
  476. /**
  477. * Extract a key-value pair from the beginning of a string.
  478. *
  479. * @param ropts pointer to the options string, will be updated to
  480. * point to the rest of the string (one of the pairs_sep
  481. * or the final NUL)
  482. * @param key_val_sep a 0-terminated list of characters used to separate
  483. * key from value, for example '='
  484. * @param pairs_sep a 0-terminated list of characters used to separate
  485. * two pairs from each other, for example ':' or ','
  486. * @param flags flags; see the AV_OPT_FLAG_* values below
  487. * @param rkey parsed key; must be freed using av_free()
  488. * @param rval parsed value; must be freed using av_free()
  489. *
  490. * @return >=0 for success, or a negative value corresponding to an
  491. * AVERROR code in case of error; in particular:
  492. * AVERROR(EINVAL) if no key is present
  493. *
  494. */
  495. int av_opt_get_key_value(const char **ropts,
  496. const char *key_val_sep, const char *pairs_sep,
  497. unsigned flags,
  498. char **rkey, char **rval);
  499. enum {
  500. /**
  501. * Accept to parse a value without a key; the key will then be returned
  502. * as NULL.
  503. */
  504. AV_OPT_FLAG_IMPLICIT_KEY = 1,
  505. };
  506. /**
  507. * @defgroup opt_eval_funcs Evaluating option strings
  508. * @{
  509. * This group of functions can be used to evaluate option strings
  510. * and get numbers out of them. They do the same thing as av_opt_set(),
  511. * except the result is written into the caller-supplied pointer.
  512. *
  513. * @param obj a struct whose first element is a pointer to AVClass.
  514. * @param o an option for which the string is to be evaluated.
  515. * @param val string to be evaluated.
  516. * @param *_out value of the string will be written here.
  517. *
  518. * @return 0 on success, a negative number on failure.
  519. */
  520. int av_opt_eval_flags (void *obj, const AVOption *o, const char *val, int *flags_out);
  521. int av_opt_eval_int (void *obj, const AVOption *o, const char *val, int *int_out);
  522. int av_opt_eval_int64 (void *obj, const AVOption *o, const char *val, int64_t *int64_out);
  523. int av_opt_eval_float (void *obj, const AVOption *o, const char *val, float *float_out);
  524. int av_opt_eval_double(void *obj, const AVOption *o, const char *val, double *double_out);
  525. int av_opt_eval_q (void *obj, const AVOption *o, const char *val, AVRational *q_out);
  526. /**
  527. * @}
  528. */
  529. #define AV_OPT_SEARCH_CHILDREN (1 << 0) /**< Search in possible children of the
  530. given object first. */
  531. /**
  532. * The obj passed to av_opt_find() is fake -- only a double pointer to AVClass
  533. * instead of a required pointer to a struct containing AVClass. This is
  534. * useful for searching for options without needing to allocate the corresponding
  535. * object.
  536. */
  537. #define AV_OPT_SEARCH_FAKE_OBJ (1 << 1)
  538. /**
  539. * In av_opt_get, return NULL if the option has a pointer type and is set to NULL,
  540. * rather than returning an empty string.
  541. */
  542. #define AV_OPT_ALLOW_NULL (1 << 2)
  543. /**
  544. * Allows av_opt_query_ranges and av_opt_query_ranges_default to return more than
  545. * one component for certain option types.
  546. * @see AVOptionRanges for details.
  547. */
  548. #define AV_OPT_MULTI_COMPONENT_RANGE (1 << 12)
  549. /**
  550. * Look for an option in an object. Consider only options which
  551. * have all the specified flags set.
  552. *
  553. * @param[in] obj A pointer to a struct whose first element is a
  554. * pointer to an AVClass.
  555. * Alternatively a double pointer to an AVClass, if
  556. * AV_OPT_SEARCH_FAKE_OBJ search flag is set.
  557. * @param[in] name The name of the option to look for.
  558. * @param[in] unit When searching for named constants, name of the unit
  559. * it belongs to.
  560. * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG).
  561. * @param search_flags A combination of AV_OPT_SEARCH_*.
  562. *
  563. * @return A pointer to the option found, or NULL if no option
  564. * was found.
  565. *
  566. * @note Options found with AV_OPT_SEARCH_CHILDREN flag may not be settable
  567. * directly with av_opt_set(). Use special calls which take an options
  568. * AVDictionary (e.g. avformat_open_input()) to set options found with this
  569. * flag.
  570. */
  571. const AVOption *av_opt_find(void *obj, const char *name, const char *unit,
  572. int opt_flags, int search_flags);
  573. /**
  574. * Look for an option in an object. Consider only options which
  575. * have all the specified flags set.
  576. *
  577. * @param[in] obj A pointer to a struct whose first element is a
  578. * pointer to an AVClass.
  579. * Alternatively a double pointer to an AVClass, if
  580. * AV_OPT_SEARCH_FAKE_OBJ search flag is set.
  581. * @param[in] name The name of the option to look for.
  582. * @param[in] unit When searching for named constants, name of the unit
  583. * it belongs to.
  584. * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG).
  585. * @param search_flags A combination of AV_OPT_SEARCH_*.
  586. * @param[out] target_obj if non-NULL, an object to which the option belongs will be
  587. * written here. It may be different from obj if AV_OPT_SEARCH_CHILDREN is present
  588. * in search_flags. This parameter is ignored if search_flags contain
  589. * AV_OPT_SEARCH_FAKE_OBJ.
  590. *
  591. * @return A pointer to the option found, or NULL if no option
  592. * was found.
  593. */
  594. const AVOption *av_opt_find2(void *obj, const char *name, const char *unit,
  595. int opt_flags, int search_flags, void **target_obj);
  596. /**
  597. * Iterate over all AVOptions belonging to obj.
  598. *
  599. * @param obj an AVOptions-enabled struct or a double pointer to an
  600. * AVClass describing it.
  601. * @param prev result of the previous call to av_opt_next() on this object
  602. * or NULL
  603. * @return next AVOption or NULL
  604. */
  605. const AVOption *av_opt_next(const void *obj, const AVOption *prev);
  606. /**
  607. * Iterate over AVOptions-enabled children of obj.
  608. *
  609. * @param prev result of a previous call to this function or NULL
  610. * @return next AVOptions-enabled child or NULL
  611. */
  612. void *av_opt_child_next(void *obj, void *prev);
  613. /**
  614. * Iterate over potential AVOptions-enabled children of parent.
  615. *
  616. * @param prev result of a previous call to this function or NULL
  617. * @return AVClass corresponding to next potential child or NULL
  618. */
  619. const AVClass *av_opt_child_class_next(const AVClass *parent, const AVClass *prev);
  620. /**
  621. * @defgroup opt_set_funcs Option setting functions
  622. * @{
  623. * Those functions set the field of obj with the given name to value.
  624. *
  625. * @param[in] obj A struct whose first element is a pointer to an AVClass.
  626. * @param[in] name the name of the field to set
  627. * @param[in] val The value to set. In case of av_opt_set() if the field is not
  628. * of a string type, then the given string is parsed.
  629. * SI postfixes and some named scalars are supported.
  630. * If the field is of a numeric type, it has to be a numeric or named
  631. * scalar. Behavior with more than one scalar and +- infix operators
  632. * is undefined.
  633. * If the field is of a flags type, it has to be a sequence of numeric
  634. * scalars or named flags separated by '+' or '-'. Prefixing a flag
  635. * with '+' causes it to be set without affecting the other flags;
  636. * similarly, '-' unsets a flag.
  637. * @param search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN
  638. * is passed here, then the option may be set on a child of obj.
  639. *
  640. * @return 0 if the value has been set, or an AVERROR code in case of
  641. * error:
  642. * AVERROR_OPTION_NOT_FOUND if no matching option exists
  643. * AVERROR(ERANGE) if the value is out of range
  644. * AVERROR(EINVAL) if the value is not valid
  645. */
  646. int av_opt_set (void *obj, const char *name, const char *val, int search_flags);
  647. int av_opt_set_int (void *obj, const char *name, int64_t val, int search_flags);
  648. int av_opt_set_double (void *obj, const char *name, double val, int search_flags);
  649. int av_opt_set_q (void *obj, const char *name, AVRational val, int search_flags);
  650. int av_opt_set_bin (void *obj, const char *name, const uint8_t *val, int size, int search_flags);
  651. int av_opt_set_image_size(void *obj, const char *name, int w, int h, int search_flags);
  652. int av_opt_set_pixel_fmt (void *obj, const char *name, enum AVPixelFormat fmt, int search_flags);
  653. int av_opt_set_sample_fmt(void *obj, const char *name, enum AVSampleFormat fmt, int search_flags);
  654. int av_opt_set_video_rate(void *obj, const char *name, AVRational val, int search_flags);
  655. int av_opt_set_channel_layout(void *obj, const char *name, int64_t ch_layout, int search_flags);
  656. /**
  657. * @note Any old dictionary present is discarded and replaced with a copy of the new one. The
  658. * caller still owns val is and responsible for freeing it.
  659. */
  660. int av_opt_set_dict_val(void *obj, const char *name, const AVDictionary *val, int search_flags);
  661. /**
  662. * Set a binary option to an integer list.
  663. *
  664. * @param obj AVClass object to set options on
  665. * @param name name of the binary option
  666. * @param val pointer to an integer list (must have the correct type with
  667. * regard to the contents of the list)
  668. * @param term list terminator (usually 0 or -1)
  669. * @param flags search flags
  670. */
  671. #define av_opt_set_int_list(obj, name, val, term, flags) \
  672. (av_int_list_length(val, term) > INT_MAX / sizeof(*(val)) ? \
  673. AVERROR(EINVAL) : \
  674. av_opt_set_bin(obj, name, (const uint8_t *)(val), \
  675. av_int_list_length(val, term) * sizeof(*(val)), flags))
  676. /**
  677. * @}
  678. */
  679. /**
  680. * @defgroup opt_get_funcs Option getting functions
  681. * @{
  682. * Those functions get a value of the option with the given name from an object.
  683. *
  684. * @param[in] obj a struct whose first element is a pointer to an AVClass.
  685. * @param[in] name name of the option to get.
  686. * @param[in] search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN
  687. * is passed here, then the option may be found in a child of obj.
  688. * @param[out] out_val value of the option will be written here
  689. * @return >=0 on success, a negative error code otherwise
  690. */
  691. /**
  692. * @note the returned string will be av_malloc()ed and must be av_free()ed by the caller
  693. *
  694. * @note if AV_OPT_ALLOW_NULL is set in search_flags in av_opt_get, and the option has
  695. * AV_OPT_TYPE_STRING or AV_OPT_TYPE_BINARY and is set to NULL, *out_val will be set
  696. * to NULL instead of an allocated empty string.
  697. */
  698. int av_opt_get (void *obj, const char *name, int search_flags, uint8_t **out_val);
  699. int av_opt_get_int (void *obj, const char *name, int search_flags, int64_t *out_val);
  700. int av_opt_get_double (void *obj, const char *name, int search_flags, double *out_val);
  701. int av_opt_get_q (void *obj, const char *name, int search_flags, AVRational *out_val);
  702. int av_opt_get_image_size(void *obj, const char *name, int search_flags, int *w_out, int *h_out);
  703. int av_opt_get_pixel_fmt (void *obj, const char *name, int search_flags, enum AVPixelFormat *out_fmt);
  704. int av_opt_get_sample_fmt(void *obj, const char *name, int search_flags, enum AVSampleFormat *out_fmt);
  705. int av_opt_get_video_rate(void *obj, const char *name, int search_flags, AVRational *out_val);
  706. int av_opt_get_channel_layout(void *obj, const char *name, int search_flags, int64_t *ch_layout);
  707. /**
  708. * @param[out] out_val The returned dictionary is a copy of the actual value and must
  709. * be freed with av_dict_free() by the caller
  710. */
  711. int av_opt_get_dict_val(void *obj, const char *name, int search_flags, AVDictionary **out_val);
  712. /**
  713. * @}
  714. */
  715. /**
  716. * Gets a pointer to the requested field in a struct.
  717. * This function allows accessing a struct even when its fields are moved or
  718. * renamed since the application making the access has been compiled,
  719. *
  720. * @returns a pointer to the field, it can be cast to the correct type and read
  721. * or written to.
  722. */
  723. void *av_opt_ptr(const AVClass *avclass, void *obj, const char *name);
  724. /**
  725. * Free an AVOptionRanges struct and set it to NULL.
  726. */
  727. void av_opt_freep_ranges(AVOptionRanges **ranges);
  728. /**
  729. * Get a list of allowed ranges for the given option.
  730. *
  731. * The returned list may depend on other fields in obj like for example profile.
  732. *
  733. * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored
  734. * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance
  735. * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges
  736. *
  737. * The result must be freed with av_opt_freep_ranges.
  738. *
  739. * @return number of compontents returned on success, a negative errro code otherwise
  740. */
  741. int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags);
  742. /**
  743. * Copy options from src object into dest object.
  744. *
  745. * Options that require memory allocation (e.g. string or binary) are malloc'ed in dest object.
  746. * Original memory allocated for such options is freed unless both src and dest options points to the same memory.
  747. *
  748. * @param dest Object to copy from
  749. * @param src Object to copy into
  750. * @return 0 on success, negative on error
  751. */
  752. int av_opt_copy(void *dest, const void *src);
  753. /**
  754. * Get a default list of allowed ranges for the given option.
  755. *
  756. * This list is constructed without using the AVClass.query_ranges() callback
  757. * and can be used as fallback from within the callback.
  758. *
  759. * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored
  760. * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance
  761. * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges
  762. *
  763. * The result must be freed with av_opt_free_ranges.
  764. *
  765. * @return number of compontents returned on success, a negative errro code otherwise
  766. */
  767. int av_opt_query_ranges_default(AVOptionRanges **, void *obj, const char *key, int flags);
  768. /**
  769. * Check if given option is set to its default value.
  770. *
  771. * Options o must belong to the obj. This function must not be called to check child's options state.
  772. * @see av_opt_is_set_to_default_by_name().
  773. *
  774. * @param obj AVClass object to check option on
  775. * @param o option to be checked
  776. * @return >0 when option is set to its default,
  777. * 0 when option is not set its default,
  778. * <0 on error
  779. */
  780. int av_opt_is_set_to_default(void *obj, const AVOption *o);
  781. /**
  782. * Check if given option is set to its default value.
  783. *
  784. * @param obj AVClass object to check option on
  785. * @param name option name
  786. * @param search_flags combination of AV_OPT_SEARCH_*
  787. * @return >0 when option is set to its default,
  788. * 0 when option is not set its default,
  789. * <0 on error
  790. */
  791. int av_opt_is_set_to_default_by_name(void *obj, const char *name, int search_flags);
  792. #define AV_OPT_SERIALIZE_SKIP_DEFAULTS 0x00000001 ///< Serialize options that are not set to default values only.
  793. #define AV_OPT_SERIALIZE_OPT_FLAGS_EXACT 0x00000002 ///< Serialize options that exactly match opt_flags only.
  794. /**
  795. * Serialize object's options.
  796. *
  797. * Create a string containing object's serialized options.
  798. * Such string may be passed back to av_opt_set_from_string() in order to restore option values.
  799. * A key/value or pairs separator occurring in the serialized value or
  800. * name string are escaped through the av_escape() function.
  801. *
  802. * @param[in] obj AVClass object to serialize
  803. * @param[in] opt_flags serialize options with all the specified flags set (AV_OPT_FLAG)
  804. * @param[in] flags combination of AV_OPT_SERIALIZE_* flags
  805. * @param[out] buffer Pointer to buffer that will be allocated with string containg serialized options.
  806. * Buffer must be freed by the caller when is no longer needed.
  807. * @param[in] key_val_sep character used to separate key from value
  808. * @param[in] pairs_sep character used to separate two pairs from each other
  809. * @return >= 0 on success, negative on error
  810. * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same.
  811. */
  812. int av_opt_serialize(void *obj, int opt_flags, int flags, char **buffer,
  813. const char key_val_sep, const char pairs_sep);
  814. /**
  815. * @}
  816. */
  817. #endif /* AVUTIL_OPT_H */