opt.h 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733
  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. /**
  34. * @defgroup avoptions AVOptions
  35. * @ingroup lavu_data
  36. * @{
  37. * AVOptions provide a generic system to declare options on arbitrary structs
  38. * ("objects"). An option can have a help text, a type and a range of possible
  39. * values. Options may then be enumerated, read and written to.
  40. *
  41. * @section avoptions_implement Implementing AVOptions
  42. * This section describes how to add AVOptions capabilities to a struct.
  43. *
  44. * All AVOptions-related information is stored in an AVClass. Therefore
  45. * the first member of the struct should be a pointer to an AVClass describing it.
  46. * The option field of the AVClass must be set to a NULL-terminated static array
  47. * of AVOptions. Each AVOption must have a non-empty name, a type, a default
  48. * value and for number-type AVOptions also a range of allowed values. It must
  49. * also declare an offset in bytes from the start of the struct, where the field
  50. * associated with this AVOption is located. Other fields in the AVOption struct
  51. * should also be set when applicable, but are not required.
  52. *
  53. * The following example illustrates an AVOptions-enabled struct:
  54. * @code
  55. * typedef struct test_struct {
  56. * AVClass *class;
  57. * int int_opt;
  58. * char *str_opt;
  59. * uint8_t *bin_opt;
  60. * int bin_len;
  61. * } test_struct;
  62. *
  63. * static const AVOption options[] = {
  64. * { "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt),
  65. * AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX },
  66. * { "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
  67. * AV_OPT_TYPE_STRING },
  68. * { "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
  69. * AV_OPT_TYPE_BINARY },
  70. * { NULL },
  71. * };
  72. *
  73. * static const AVClass test_class = {
  74. * .class_name = "test class",
  75. * .item_name = av_default_item_name,
  76. * .option = options,
  77. * .version = LIBAVUTIL_VERSION_INT,
  78. * };
  79. * @endcode
  80. *
  81. * Next, when allocating your struct, you must ensure that the AVClass pointer
  82. * is set to the correct value. Then, av_opt_set_defaults() can be called to
  83. * initialize defaults. After that the struct is ready to be used with the
  84. * AVOptions API.
  85. *
  86. * When cleaning up, you may use the av_opt_free() function to automatically
  87. * free all the allocated string and binary options.
  88. *
  89. * Continuing with the above example:
  90. *
  91. * @code
  92. * test_struct *alloc_test_struct(void)
  93. * {
  94. * test_struct *ret = av_malloc(sizeof(*ret));
  95. * ret->class = &test_class;
  96. * av_opt_set_defaults(ret);
  97. * return ret;
  98. * }
  99. * void free_test_struct(test_struct **foo)
  100. * {
  101. * av_opt_free(*foo);
  102. * av_freep(foo);
  103. * }
  104. * @endcode
  105. *
  106. * @subsection avoptions_implement_nesting Nesting
  107. * It may happen that an AVOptions-enabled struct contains another
  108. * AVOptions-enabled struct as a member (e.g. AVCodecContext in
  109. * libavcodec exports generic options, while its priv_data field exports
  110. * codec-specific options). In such a case, it is possible to set up the
  111. * parent struct to export a child's options. To do that, simply
  112. * implement AVClass.child_next() and AVClass.child_class_next() in the
  113. * parent struct's AVClass.
  114. * Assuming that the test_struct from above now also contains a
  115. * child_struct field:
  116. *
  117. * @code
  118. * typedef struct child_struct {
  119. * AVClass *class;
  120. * int flags_opt;
  121. * } child_struct;
  122. * static const AVOption child_opts[] = {
  123. * { "test_flags", "This is a test option of flags type.",
  124. * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX },
  125. * { NULL },
  126. * };
  127. * static const AVClass child_class = {
  128. * .class_name = "child class",
  129. * .item_name = av_default_item_name,
  130. * .option = child_opts,
  131. * .version = LIBAVUTIL_VERSION_INT,
  132. * };
  133. *
  134. * void *child_next(void *obj, void *prev)
  135. * {
  136. * test_struct *t = obj;
  137. * if (!prev && t->child_struct)
  138. * return t->child_struct;
  139. * return NULL
  140. * }
  141. * const AVClass child_class_next(const AVClass *prev)
  142. * {
  143. * return prev ? NULL : &child_class;
  144. * }
  145. * @endcode
  146. * Putting child_next() and child_class_next() as defined above into
  147. * test_class will now make child_struct's options accessible through
  148. * test_struct (again, proper setup as described above needs to be done on
  149. * child_struct right after it is created).
  150. *
  151. * From the above example it might not be clear why both child_next()
  152. * and child_class_next() are needed. The distinction is that child_next()
  153. * iterates over actually existing objects, while child_class_next()
  154. * iterates over all possible child classes. E.g. if an AVCodecContext
  155. * was initialized to use a codec which has private options, then its
  156. * child_next() will return AVCodecContext.priv_data and finish
  157. * iterating. OTOH child_class_next() on AVCodecContext.av_class will
  158. * iterate over all available codecs with private options.
  159. *
  160. * @subsection avoptions_implement_named_constants Named constants
  161. * It is possible to create named constants for options. Simply set the unit
  162. * field of the option the constants should apply to to a string and
  163. * create the constants themselves as options of type AV_OPT_TYPE_CONST
  164. * with their unit field set to the same string.
  165. * Their default_val field should contain the value of the named
  166. * constant.
  167. * For example, to add some named constants for the test_flags option
  168. * above, put the following into the child_opts array:
  169. * @code
  170. * { "test_flags", "This is a test option of flags type.",
  171. * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" },
  172. * { "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0, "test_unit" },
  173. * @endcode
  174. *
  175. * @section avoptions_use Using AVOptions
  176. * This section deals with accessing options in an AVOptions-enabled struct.
  177. * Such structs in FFmpeg are e.g. AVCodecContext in libavcodec or
  178. * AVFormatContext in libavformat.
  179. *
  180. * @subsection avoptions_use_examine Examining AVOptions
  181. * The basic functions for examining options are av_opt_next(), which iterates
  182. * over all options defined for one object, and av_opt_find(), which searches
  183. * for an option with the given name.
  184. *
  185. * The situation is more complicated with nesting. An AVOptions-enabled struct
  186. * may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag
  187. * to av_opt_find() will make the function search children recursively.
  188. *
  189. * For enumerating there are basically two cases. The first is when you want to
  190. * get all options that may potentially exist on the struct and its children
  191. * (e.g. when constructing documentation). In that case you should call
  192. * av_opt_child_class_next() recursively on the parent struct's AVClass. The
  193. * second case is when you have an already initialized struct with all its
  194. * children and you want to get all options that can be actually written or read
  195. * from it. In that case you should call av_opt_child_next() recursively (and
  196. * av_opt_next() on each result).
  197. *
  198. * @subsection avoptions_use_get_set Reading and writing AVOptions
  199. * When setting options, you often have a string read directly from the
  200. * user. In such a case, simply passing it to av_opt_set() is enough. For
  201. * non-string type options, av_opt_set() will parse the string according to the
  202. * option type.
  203. *
  204. * Similarly av_opt_get() will read any option type and convert it to a string
  205. * which will be returned. Do not forget that the string is allocated, so you
  206. * have to free it with av_free().
  207. *
  208. * In some cases it may be more convenient to put all options into an
  209. * AVDictionary and call av_opt_set_dict() on it. A specific case of this
  210. * are the format/codec open functions in lavf/lavc which take a dictionary
  211. * filled with option as a parameter. This allows to set some options
  212. * that cannot be set otherwise, since e.g. the input file format is not known
  213. * before the file is actually opened.
  214. */
  215. enum AVOptionType{
  216. AV_OPT_TYPE_FLAGS,
  217. AV_OPT_TYPE_INT,
  218. AV_OPT_TYPE_INT64,
  219. AV_OPT_TYPE_DOUBLE,
  220. AV_OPT_TYPE_FLOAT,
  221. AV_OPT_TYPE_STRING,
  222. AV_OPT_TYPE_RATIONAL,
  223. AV_OPT_TYPE_BINARY, ///< offset must point to a pointer immediately followed by an int for the length
  224. AV_OPT_TYPE_CONST = 128,
  225. AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), ///< offset must point to two consecutive integers
  226. AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'),
  227. AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'),
  228. #if FF_API_OLD_AVOPTIONS
  229. FF_OPT_TYPE_FLAGS = 0,
  230. FF_OPT_TYPE_INT,
  231. FF_OPT_TYPE_INT64,
  232. FF_OPT_TYPE_DOUBLE,
  233. FF_OPT_TYPE_FLOAT,
  234. FF_OPT_TYPE_STRING,
  235. FF_OPT_TYPE_RATIONAL,
  236. FF_OPT_TYPE_BINARY, ///< offset must point to a pointer immediately followed by an int for the length
  237. FF_OPT_TYPE_CONST=128,
  238. #endif
  239. };
  240. /**
  241. * AVOption
  242. */
  243. typedef struct AVOption {
  244. const char *name;
  245. /**
  246. * short English help text
  247. * @todo What about other languages?
  248. */
  249. const char *help;
  250. /**
  251. * The offset relative to the context structure where the option
  252. * value is stored. It should be 0 for named constants.
  253. */
  254. int offset;
  255. enum AVOptionType type;
  256. /**
  257. * the default value for scalar options
  258. */
  259. union {
  260. int64_t i64;
  261. double dbl;
  262. const char *str;
  263. /* TODO those are unused now */
  264. AVRational q;
  265. } default_val;
  266. double min; ///< minimum valid value for the option
  267. double max; ///< maximum valid value for the option
  268. int flags;
  269. #define AV_OPT_FLAG_ENCODING_PARAM 1 ///< a generic parameter which can be set by the user for muxing or encoding
  270. #define AV_OPT_FLAG_DECODING_PARAM 2 ///< a generic parameter which can be set by the user for demuxing or decoding
  271. #define AV_OPT_FLAG_METADATA 4 ///< some data extracted or inserted into the file like title, comment, ...
  272. #define AV_OPT_FLAG_AUDIO_PARAM 8
  273. #define AV_OPT_FLAG_VIDEO_PARAM 16
  274. #define AV_OPT_FLAG_SUBTITLE_PARAM 32
  275. #define AV_OPT_FLAG_FILTERING_PARAM (1<<16) ///< a generic parameter which can be set by the user for filtering
  276. //FIXME think about enc-audio, ... style flags
  277. /**
  278. * The logical unit to which the option belongs. Non-constant
  279. * options and corresponding named constants share the same
  280. * unit. May be NULL.
  281. */
  282. const char *unit;
  283. } AVOption;
  284. /**
  285. * A single allowed range of values, or a single allowed value.
  286. */
  287. typedef struct AVOptionRange {
  288. const char *str;
  289. double value_min, value_max; ///< For string ranges this represents the min/max length, for dimensions this represents the min/max pixel count
  290. double component_min, component_max; ///< For string this represents the unicode range for chars, 0-127 limits to ASCII
  291. int is_range; ///< if set to 1 the struct encodes a range, if set to 0 a single value
  292. } AVOptionRange;
  293. /**
  294. * List of AVOptionRange structs
  295. */
  296. typedef struct AVOptionRanges {
  297. AVOptionRange **range;
  298. int nb_ranges;
  299. } AVOptionRanges;
  300. #if FF_API_FIND_OPT
  301. /**
  302. * Look for an option in obj. Look only for the options which
  303. * have the flags set as specified in mask and flags (that is,
  304. * for which it is the case that opt->flags & mask == flags).
  305. *
  306. * @param[in] obj a pointer to a struct whose first element is a
  307. * pointer to an AVClass
  308. * @param[in] name the name of the option to look for
  309. * @param[in] unit the unit of the option to look for, or any if NULL
  310. * @return a pointer to the option found, or NULL if no option
  311. * has been found
  312. *
  313. * @deprecated use av_opt_find.
  314. */
  315. attribute_deprecated
  316. const AVOption *av_find_opt(void *obj, const char *name, const char *unit, int mask, int flags);
  317. #endif
  318. #if FF_API_OLD_AVOPTIONS
  319. /**
  320. * Set the field of obj with the given name to value.
  321. *
  322. * @param[in] obj A struct whose first element is a pointer to an
  323. * AVClass.
  324. * @param[in] name the name of the field to set
  325. * @param[in] val The value to set. If the field is not of a string
  326. * type, then the given string is parsed.
  327. * SI postfixes and some named scalars are supported.
  328. * If the field is of a numeric type, it has to be a numeric or named
  329. * scalar. Behavior with more than one scalar and +- infix operators
  330. * is undefined.
  331. * If the field is of a flags type, it has to be a sequence of numeric
  332. * scalars or named flags separated by '+' or '-'. Prefixing a flag
  333. * with '+' causes it to be set without affecting the other flags;
  334. * similarly, '-' unsets a flag.
  335. * @param[out] o_out if non-NULL put here a pointer to the AVOption
  336. * found
  337. * @param alloc this parameter is currently ignored
  338. * @return 0 if the value has been set, or an AVERROR code in case of
  339. * error:
  340. * AVERROR_OPTION_NOT_FOUND if no matching option exists
  341. * AVERROR(ERANGE) if the value is out of range
  342. * AVERROR(EINVAL) if the value is not valid
  343. * @deprecated use av_opt_set()
  344. */
  345. attribute_deprecated
  346. int av_set_string3(void *obj, const char *name, const char *val, int alloc, const AVOption **o_out);
  347. attribute_deprecated const AVOption *av_set_double(void *obj, const char *name, double n);
  348. attribute_deprecated const AVOption *av_set_q(void *obj, const char *name, AVRational n);
  349. attribute_deprecated const AVOption *av_set_int(void *obj, const char *name, int64_t n);
  350. double av_get_double(void *obj, const char *name, const AVOption **o_out);
  351. AVRational av_get_q(void *obj, const char *name, const AVOption **o_out);
  352. int64_t av_get_int(void *obj, const char *name, const AVOption **o_out);
  353. attribute_deprecated const char *av_get_string(void *obj, const char *name, const AVOption **o_out, char *buf, int buf_len);
  354. attribute_deprecated const AVOption *av_next_option(void *obj, const AVOption *last);
  355. #endif
  356. /**
  357. * Show the obj options.
  358. *
  359. * @param req_flags requested flags for the options to show. Show only the
  360. * options for which it is opt->flags & req_flags.
  361. * @param rej_flags rejected flags for the options to show. Show only the
  362. * options for which it is !(opt->flags & req_flags).
  363. * @param av_log_obj log context to use for showing the options
  364. */
  365. int av_opt_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags);
  366. /**
  367. * Set the values of all AVOption fields to their default values.
  368. *
  369. * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass)
  370. */
  371. void av_opt_set_defaults(void *s);
  372. #if FF_API_OLD_AVOPTIONS
  373. attribute_deprecated
  374. void av_opt_set_defaults2(void *s, int mask, int flags);
  375. #endif
  376. /**
  377. * Parse the key/value pairs list in opts. For each key/value pair
  378. * found, stores the value in the field in ctx that is named like the
  379. * key. ctx must be an AVClass context, storing is done using
  380. * AVOptions.
  381. *
  382. * @param opts options string to parse, may be NULL
  383. * @param key_val_sep a 0-terminated list of characters used to
  384. * separate key from value
  385. * @param pairs_sep a 0-terminated list of characters used to separate
  386. * two pairs from each other
  387. * @return the number of successfully set key/value pairs, or a negative
  388. * value corresponding to an AVERROR code in case of error:
  389. * AVERROR(EINVAL) if opts cannot be parsed,
  390. * the error code issued by av_set_string3() if a key/value pair
  391. * cannot be set
  392. */
  393. int av_set_options_string(void *ctx, const char *opts,
  394. const char *key_val_sep, const char *pairs_sep);
  395. /**
  396. * Parse the key-value pairs list in opts. For each key=value pair found,
  397. * set the value of the corresponding option in ctx.
  398. *
  399. * @param ctx the AVClass object to set options on
  400. * @param opts the options string, key-value pairs separated by a
  401. * delimiter
  402. * @param shorthand a NULL-terminated array of options names for shorthand
  403. * notation: if the first field in opts has no key part,
  404. * the key is taken from the first element of shorthand;
  405. * then again for the second, etc., until either opts is
  406. * finished, shorthand is finished or a named option is
  407. * found; after that, all options must be named
  408. * @param key_val_sep a 0-terminated list of characters used to separate
  409. * key from value, for example '='
  410. * @param pairs_sep a 0-terminated list of characters used to separate
  411. * two pairs from each other, for example ':' or ','
  412. * @return the number of successfully set key=value pairs, or a negative
  413. * value corresponding to an AVERROR code in case of error:
  414. * AVERROR(EINVAL) if opts cannot be parsed,
  415. * the error code issued by av_set_string3() if a key/value pair
  416. * cannot be set
  417. *
  418. * Options names must use only the following characters: a-z A-Z 0-9 - . / _
  419. * Separators must use characters distinct from option names and from each
  420. * other.
  421. */
  422. int av_opt_set_from_string(void *ctx, const char *opts,
  423. const char *const *shorthand,
  424. const char *key_val_sep, const char *pairs_sep);
  425. /**
  426. * Free all string and binary options in obj.
  427. */
  428. void av_opt_free(void *obj);
  429. /**
  430. * Check whether a particular flag is set in a flags field.
  431. *
  432. * @param field_name the name of the flag field option
  433. * @param flag_name the name of the flag to check
  434. * @return non-zero if the flag is set, zero if the flag isn't set,
  435. * isn't of the right type, or the flags field doesn't exist.
  436. */
  437. int av_opt_flag_is_set(void *obj, const char *field_name, const char *flag_name);
  438. /**
  439. * Set all the options from a given dictionary on an object.
  440. *
  441. * @param obj a struct whose first element is a pointer to AVClass
  442. * @param options options to process. This dictionary will be freed and replaced
  443. * by a new one containing all options not found in obj.
  444. * Of course this new dictionary needs to be freed by caller
  445. * with av_dict_free().
  446. *
  447. * @return 0 on success, a negative AVERROR if some option was found in obj,
  448. * but could not be set.
  449. *
  450. * @see av_dict_copy()
  451. */
  452. int av_opt_set_dict(void *obj, struct AVDictionary **options);
  453. /**
  454. * Extract a key-value pair from the beginning of a string.
  455. *
  456. * @param ropts pointer to the options string, will be updated to
  457. * point to the rest of the string (one of the pairs_sep
  458. * or the final NUL)
  459. * @param key_val_sep a 0-terminated list of characters used to separate
  460. * key from value, for example '='
  461. * @param pairs_sep a 0-terminated list of characters used to separate
  462. * two pairs from each other, for example ':' or ','
  463. * @param flags flags; see the AV_OPT_FLAG_* values below
  464. * @param rkey parsed key; must be freed using av_free()
  465. * @param rval parsed value; must be freed using av_free()
  466. *
  467. * @return >=0 for success, or a negative value corresponding to an
  468. * AVERROR code in case of error; in particular:
  469. * AVERROR(EINVAL) if no key is present
  470. *
  471. */
  472. int av_opt_get_key_value(const char **ropts,
  473. const char *key_val_sep, const char *pairs_sep,
  474. unsigned flags,
  475. char **rkey, char **rval);
  476. enum {
  477. /**
  478. * Accept to parse a value without a key; the key will then be returned
  479. * as NULL.
  480. */
  481. AV_OPT_FLAG_IMPLICIT_KEY = 1,
  482. };
  483. /**
  484. * @defgroup opt_eval_funcs Evaluating option strings
  485. * @{
  486. * This group of functions can be used to evaluate option strings
  487. * and get numbers out of them. They do the same thing as av_opt_set(),
  488. * except the result is written into the caller-supplied pointer.
  489. *
  490. * @param obj a struct whose first element is a pointer to AVClass.
  491. * @param o an option for which the string is to be evaluated.
  492. * @param val string to be evaluated.
  493. * @param *_out value of the string will be written here.
  494. *
  495. * @return 0 on success, a negative number on failure.
  496. */
  497. int av_opt_eval_flags (void *obj, const AVOption *o, const char *val, int *flags_out);
  498. int av_opt_eval_int (void *obj, const AVOption *o, const char *val, int *int_out);
  499. int av_opt_eval_int64 (void *obj, const AVOption *o, const char *val, int64_t *int64_out);
  500. int av_opt_eval_float (void *obj, const AVOption *o, const char *val, float *float_out);
  501. int av_opt_eval_double(void *obj, const AVOption *o, const char *val, double *double_out);
  502. int av_opt_eval_q (void *obj, const AVOption *o, const char *val, AVRational *q_out);
  503. /**
  504. * @}
  505. */
  506. #define AV_OPT_SEARCH_CHILDREN 0x0001 /**< Search in possible children of the
  507. given object first. */
  508. /**
  509. * The obj passed to av_opt_find() is fake -- only a double pointer to AVClass
  510. * instead of a required pointer to a struct containing AVClass. This is
  511. * useful for searching for options without needing to allocate the corresponding
  512. * object.
  513. */
  514. #define AV_OPT_SEARCH_FAKE_OBJ 0x0002
  515. /**
  516. * Look for an option in an object. Consider only options which
  517. * have all the specified flags set.
  518. *
  519. * @param[in] obj A pointer to a struct whose first element is a
  520. * pointer to an AVClass.
  521. * Alternatively a double pointer to an AVClass, if
  522. * AV_OPT_SEARCH_FAKE_OBJ search flag is set.
  523. * @param[in] name The name of the option to look for.
  524. * @param[in] unit When searching for named constants, name of the unit
  525. * it belongs to.
  526. * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG).
  527. * @param search_flags A combination of AV_OPT_SEARCH_*.
  528. *
  529. * @return A pointer to the option found, or NULL if no option
  530. * was found.
  531. *
  532. * @note Options found with AV_OPT_SEARCH_CHILDREN flag may not be settable
  533. * directly with av_set_string3(). Use special calls which take an options
  534. * AVDictionary (e.g. avformat_open_input()) to set options found with this
  535. * flag.
  536. */
  537. const AVOption *av_opt_find(void *obj, const char *name, const char *unit,
  538. int opt_flags, int search_flags);
  539. /**
  540. * Look for an option in an object. Consider only options which
  541. * have all the specified flags set.
  542. *
  543. * @param[in] obj A pointer to a struct whose first element is a
  544. * pointer to an AVClass.
  545. * Alternatively a double pointer to an AVClass, if
  546. * AV_OPT_SEARCH_FAKE_OBJ search flag is set.
  547. * @param[in] name The name of the option to look for.
  548. * @param[in] unit When searching for named constants, name of the unit
  549. * it belongs to.
  550. * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG).
  551. * @param search_flags A combination of AV_OPT_SEARCH_*.
  552. * @param[out] target_obj if non-NULL, an object to which the option belongs will be
  553. * written here. It may be different from obj if AV_OPT_SEARCH_CHILDREN is present
  554. * in search_flags. This parameter is ignored if search_flags contain
  555. * AV_OPT_SEARCH_FAKE_OBJ.
  556. *
  557. * @return A pointer to the option found, or NULL if no option
  558. * was found.
  559. */
  560. const AVOption *av_opt_find2(void *obj, const char *name, const char *unit,
  561. int opt_flags, int search_flags, void **target_obj);
  562. /**
  563. * Iterate over all AVOptions belonging to obj.
  564. *
  565. * @param obj an AVOptions-enabled struct or a double pointer to an
  566. * AVClass describing it.
  567. * @param prev result of the previous call to av_opt_next() on this object
  568. * or NULL
  569. * @return next AVOption or NULL
  570. */
  571. const AVOption *av_opt_next(void *obj, const AVOption *prev);
  572. /**
  573. * Iterate over AVOptions-enabled children of obj.
  574. *
  575. * @param prev result of a previous call to this function or NULL
  576. * @return next AVOptions-enabled child or NULL
  577. */
  578. void *av_opt_child_next(void *obj, void *prev);
  579. /**
  580. * Iterate over potential AVOptions-enabled children of parent.
  581. *
  582. * @param prev result of a previous call to this function or NULL
  583. * @return AVClass corresponding to next potential child or NULL
  584. */
  585. const AVClass *av_opt_child_class_next(const AVClass *parent, const AVClass *prev);
  586. /**
  587. * @defgroup opt_set_funcs Option setting functions
  588. * @{
  589. * Those functions set the field of obj with the given name to value.
  590. *
  591. * @param[in] obj A struct whose first element is a pointer to an AVClass.
  592. * @param[in] name the name of the field to set
  593. * @param[in] val The value to set. In case of av_opt_set() if the field is not
  594. * of a string type, then the given string is parsed.
  595. * SI postfixes and some named scalars are supported.
  596. * If the field is of a numeric type, it has to be a numeric or named
  597. * scalar. Behavior with more than one scalar and +- infix operators
  598. * is undefined.
  599. * If the field is of a flags type, it has to be a sequence of numeric
  600. * scalars or named flags separated by '+' or '-'. Prefixing a flag
  601. * with '+' causes it to be set without affecting the other flags;
  602. * similarly, '-' unsets a flag.
  603. * @param search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN
  604. * is passed here, then the option may be set on a child of obj.
  605. *
  606. * @return 0 if the value has been set, or an AVERROR code in case of
  607. * error:
  608. * AVERROR_OPTION_NOT_FOUND if no matching option exists
  609. * AVERROR(ERANGE) if the value is out of range
  610. * AVERROR(EINVAL) if the value is not valid
  611. */
  612. int av_opt_set (void *obj, const char *name, const char *val, int search_flags);
  613. int av_opt_set_int (void *obj, const char *name, int64_t val, int search_flags);
  614. int av_opt_set_double(void *obj, const char *name, double val, int search_flags);
  615. int av_opt_set_q (void *obj, const char *name, AVRational val, int search_flags);
  616. int av_opt_set_bin (void *obj, const char *name, const uint8_t *val, int size, int search_flags);
  617. int av_opt_set_image_size(void *obj, const char *name, int w, int h, int search_flags);
  618. int av_opt_set_pixel_fmt (void *obj, const char *name, enum AVPixelFormat fmt, int search_flags);
  619. int av_opt_set_sample_fmt(void *obj, const char *name, enum AVSampleFormat fmt, int search_flags);
  620. /**
  621. * @}
  622. */
  623. /**
  624. * @defgroup opt_get_funcs Option getting functions
  625. * @{
  626. * Those functions get a value of the option with the given name from an object.
  627. *
  628. * @param[in] obj a struct whose first element is a pointer to an AVClass.
  629. * @param[in] name name of the option to get.
  630. * @param[in] search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN
  631. * is passed here, then the option may be found in a child of obj.
  632. * @param[out] out_val value of the option will be written here
  633. * @return 0 on success, a negative error code otherwise
  634. */
  635. /**
  636. * @note the returned string will av_malloc()ed and must be av_free()ed by the caller
  637. */
  638. int av_opt_get (void *obj, const char *name, int search_flags, uint8_t **out_val);
  639. int av_opt_get_int (void *obj, const char *name, int search_flags, int64_t *out_val);
  640. int av_opt_get_double(void *obj, const char *name, int search_flags, double *out_val);
  641. int av_opt_get_q (void *obj, const char *name, int search_flags, AVRational *out_val);
  642. int av_opt_get_image_size(void *obj, const char *name, int search_flags, int *w_out, int *h_out);
  643. int av_opt_get_pixel_fmt (void *obj, const char *name, int search_flags, enum AVPixelFormat *out_fmt);
  644. int av_opt_get_sample_fmt(void *obj, const char *name, int search_flags, enum AVSampleFormat *out_fmt);
  645. /**
  646. * @}
  647. */
  648. /**
  649. * Gets a pointer to the requested field in a struct.
  650. * This function allows accessing a struct even when its fields are moved or
  651. * renamed since the application making the access has been compiled,
  652. *
  653. * @returns a pointer to the field, it can be cast to the correct type and read
  654. * or written to.
  655. */
  656. void *av_opt_ptr(const AVClass *avclass, void *obj, const char *name);
  657. /**
  658. * Free an AVOptionRanges struct and set it to NULL.
  659. */
  660. void av_opt_freep_ranges(AVOptionRanges **ranges);
  661. /**
  662. * Get a list of allowed ranges for the given option.
  663. *
  664. * The returned list may depend on other fields in obj like for example profile.
  665. *
  666. * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored
  667. * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance
  668. *
  669. * The result must be freed with av_opt_freep_ranges.
  670. *
  671. * @return >= 0 on success, a negative errro code otherwise
  672. */
  673. int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags);
  674. /**
  675. * Get a default list of allowed ranges for the given option.
  676. *
  677. * This list is constructed without using the AVClass.query_ranges() callback
  678. * and can be used as fallback from within the callback.
  679. *
  680. * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored
  681. * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance
  682. *
  683. * The result must be freed with av_opt_free_ranges.
  684. *
  685. * @return >= 0 on success, a negative errro code otherwise
  686. */
  687. int av_opt_query_ranges_default(AVOptionRanges **, void *obj, const char *key, int flags);
  688. /**
  689. * @}
  690. */
  691. #endif /* AVUTIL_OPT_H */