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