opt.h 24 KB

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