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 22 moduleffmpeg.libavutil.opt;
23 24 importcore.stdc.errno;
25 importcore.stdc.limits;
26 27 importffmpeg.libavutil.dict;
28 importffmpeg.libavutil.log;
29 importffmpeg.libavutil.pixfmt;
30 importffmpeg.libavutil.rational;
31 importffmpeg.libavutil.samplefmt;
32 33 extern (C):
34 importffmpeg; @nogcnothrow:
35 36 /**
37 * @file
38 * AVOptions
39 */40 41 /**
42 * @defgroup avoptions AVOptions
43 * @ingroup lavu_data
44 * @{
45 * AVOptions provide a generic system to declare options on arbitrary structs
46 * ("objects"). An option can have a help text, a type and a range of possible
47 * values. Options may then be enumerated, read and written to.
48 *
49 * @section avoptions_implement Implementing AVOptions
50 * This section describes how to add AVOptions capabilities to a struct.
51 *
52 * All AVOptions-related information is stored in an AVClass. Therefore
53 * the first member of the struct should be a pointer to an AVClass describing it.
54 * The option field of the AVClass must be set to a NULL-terminated static array
55 * of AVOptions. Each AVOption must have a non-empty name, a type, a default
56 * value and for number-type AVOptions also a range of allowed values. It must
57 * also declare an offset in bytes from the start of the struct, where the field
58 * associated with this AVOption is located. Other fields in the AVOption struct
59 * should also be set when applicable, but are not required.
60 *
61 * The following example illustrates an AVOptions-enabled struct:
62 * @code
63 * typedef struct test_struct {
64 * const AVClass *class;
65 * int int_opt;
66 * char *str_opt;
67 * uint8_t *bin_opt;
68 * int bin_len;
69 * } test_struct;
70 *
71 * static const AVOption test_options[] = {
72 * { "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt),
73 * AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX },
74 * { "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
75 * AV_OPT_TYPE_STRING },
76 * { "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
77 * AV_OPT_TYPE_BINARY },
78 * { NULL },
79 * };
80 *
81 * static const AVClass test_class = {
82 * .class_name = "test class",
83 * .item_name = av_default_item_name,
84 * .option = test_options,
85 * .version = LIBAVUTIL_VERSION_INT,
86 * };
87 * @endcode
88 *
89 * Next, when allocating your struct, you must ensure that the AVClass pointer
90 * is set to the correct value. Then, av_opt_set_defaults() can be called to
91 * initialize defaults. After that the struct is ready to be used with the
92 * AVOptions API.
93 *
94 * When cleaning up, you may use the av_opt_free() function to automatically
95 * free all the allocated string and binary options.
96 *
97 * Continuing with the above example:
98 *
99 * @code
100 * test_struct *alloc_test_struct(void)
101 * {
102 * test_struct *ret = av_mallocz(sizeof(*ret));
103 * ret->class = &test_class;
104 * av_opt_set_defaults(ret);
105 * return ret;
106 * }
107 * void free_test_struct(test_struct **foo)
108 * {
109 * av_opt_free(*foo);
110 * av_freep(foo);
111 * }
112 * @endcode
113 *
114 * @subsection avoptions_implement_nesting Nesting
115 * It may happen that an AVOptions-enabled struct contains another
116 * AVOptions-enabled struct as a member (e.g. AVCodecContext in
117 * libavcodec exports generic options, while its priv_data field exports
118 * codec-specific options). In such a case, it is possible to set up the
119 * parent struct to export a child's options. To do that, simply
120 * implement AVClass.child_next() and AVClass.child_class_next() in the
121 * parent struct's AVClass.
122 * Assuming that the test_struct from above now also contains a
123 * child_struct field:
124 *
125 * @code
126 * typedef struct child_struct {
127 * AVClass *class;
128 * int flags_opt;
129 * } child_struct;
130 * static const AVOption child_opts[] = {
131 * { "test_flags", "This is a test option of flags type.",
132 * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX },
133 * { NULL },
134 * };
135 * static const AVClass child_class = {
136 * .class_name = "child class",
137 * .item_name = av_default_item_name,
138 * .option = child_opts,
139 * .version = LIBAVUTIL_VERSION_INT,
140 * };
141 *
142 * void *child_next(void *obj, void *prev)
143 * {
144 * test_struct *t = obj;
145 * if (!prev && t->child_struct)
146 * return t->child_struct;
147 * return NULL
148 * }
149 * const AVClass child_class_next(const AVClass *prev)
150 * {
151 * return prev ? NULL : &child_class;
152 * }
153 * @endcode
154 * Putting child_next() and child_class_next() as defined above into
155 * test_class will now make child_struct's options accessible through
156 * test_struct (again, proper setup as described above needs to be done on
157 * child_struct right after it is created).
158 *
159 * From the above example it might not be clear why both child_next()
160 * and child_class_next() are needed. The distinction is that child_next()
161 * iterates over actually existing objects, while child_class_next()
162 * iterates over all possible child classes. E.g. if an AVCodecContext
163 * was initialized to use a codec which has private options, then its
164 * child_next() will return AVCodecContext.priv_data and finish
165 * iterating. OTOH child_class_next() on AVCodecContext.av_class will
166 * iterate over all available codecs with private options.
167 *
168 * @subsection avoptions_implement_named_constants Named constants
169 * It is possible to create named constants for options. Simply set the unit
170 * field of the option the constants should apply to a string and
171 * create the constants themselves as options of type AV_OPT_TYPE_CONST
172 * with their unit field set to the same string.
173 * Their default_val field should contain the value of the named
174 * constant.
175 * For example, to add some named constants for the test_flags option
176 * above, put the following into the child_opts array:
177 * @code
178 * { "test_flags", "This is a test option of flags type.",
179 * offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" },
180 * { "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0, "test_unit" },
181 * @endcode
182 *
183 * @section avoptions_use Using AVOptions
184 * This section deals with accessing options in an AVOptions-enabled struct.
185 * Such structs in FFmpeg are e.g. AVCodecContext in libavcodec or
186 * AVFormatContext in libavformat.
187 *
188 * @subsection avoptions_use_examine Examining AVOptions
189 * The basic functions for examining options are av_opt_next(), which iterates
190 * over all options defined for one object, and av_opt_find(), which searches
191 * for an option with the given name.
192 *
193 * The situation is more complicated with nesting. An AVOptions-enabled struct
194 * may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag
195 * to av_opt_find() will make the function search children recursively.
196 *
197 * For enumerating there are basically two cases. The first is when you want to
198 * get all options that may potentially exist on the struct and its children
199 * (e.g. when constructing documentation). In that case you should call
200 * av_opt_child_class_next() recursively on the parent struct's AVClass. The
201 * second case is when you have an already initialized struct with all its
202 * children and you want to get all options that can be actually written or read
203 * from it. In that case you should call av_opt_child_next() recursively (and
204 * av_opt_next() on each result).
205 *
206 * @subsection avoptions_use_get_set Reading and writing AVOptions
207 * When setting options, you often have a string read directly from the
208 * user. In such a case, simply passing it to av_opt_set() is enough. For
209 * non-string type options, av_opt_set() will parse the string according to the
210 * option type.
211 *
212 * Similarly av_opt_get() will read any option type and convert it to a string
213 * which will be returned. Do not forget that the string is allocated, so you
214 * have to free it with av_free().
215 *
216 * In some cases it may be more convenient to put all options into an
217 * AVDictionary and call av_opt_set_dict() on it. A specific case of this
218 * are the format/codec open functions in lavf/lavc which take a dictionary
219 * filled with option as a parameter. This makes it possible to set some options
220 * that cannot be set otherwise, since e.g. the input file format is not known
221 * before the file is actually opened.
222 */223 224 enumAVOptionType225 {
226 AV_OPT_TYPE_FLAGS = 0,
227 AV_OPT_TYPE_INT = 1,
228 AV_OPT_TYPE_INT64 = 2,
229 AV_OPT_TYPE_DOUBLE = 3,
230 AV_OPT_TYPE_FLOAT = 4,
231 AV_OPT_TYPE_STRING = 5,
232 AV_OPT_TYPE_RATIONAL = 6,
233 AV_OPT_TYPE_BINARY = 7, ///< offset must point to a pointer immediately followed by an int for the length234 AV_OPT_TYPE_DICT = 8,
235 AV_OPT_TYPE_UINT64 = 9,
236 AV_OPT_TYPE_CONST = 10,
237 AV_OPT_TYPE_IMAGE_SIZE = 11, ///< offset must point to two consecutive integers238 AV_OPT_TYPE_PIXEL_FMT = 12,
239 AV_OPT_TYPE_SAMPLE_FMT = 13,
240 AV_OPT_TYPE_VIDEO_RATE = 14, ///< offset must point to AVRational241 AV_OPT_TYPE_DURATION = 15,
242 AV_OPT_TYPE_COLOR = 16,
243 AV_OPT_TYPE_CHANNEL_LAYOUT = 17,
244 AV_OPT_TYPE_BOOL = 18245 }
246 247 /**
248 * AVOption
249 */250 structAVOption251 {
252 const(char)* name;
253 254 /**
255 * short English help text
256 * @todo What about other languages?
257 */258 const(char)* help;
259 260 /**
261 * The offset relative to the context structure where the option
262 * value is stored. It should be 0 for named constants.
263 */264 intoffset;
265 AVOptionTypetype;
266 267 /**
268 * the default value for scalar options
269 */270 271 /* TODO those are unused now */272 union_Anonymous_0273 {
274 longi64;
275 doubledbl;
276 const(char)* str;
277 AVRationalq;
278 }
279 280 _Anonymous_0default_val;
281 doublemin; ///< minimum valid value for the option282 doublemax; ///< maximum valid value for the option283 284 intflags;
285 ///< a generic parameter which can be set by the user for muxing or encoding286 ///< a generic parameter which can be set by the user for demuxing or decoding287 288 /**
289 * The option is intended for exporting values to the caller.
290 */291 292 /**
293 * The option may not be set through the AVOptions API, only read.
294 * This flag only makes sense when AV_OPT_FLAG_EXPORT is also set.
295 */296 297 ///< a generic parameter which can be set by the user for bit stream filtering298 ///< a generic parameter which can be set by the user for filtering299 ///< set if option is deprecated, users should refer to AVOption.help text for more information300 //FIXME think about enc-audio, ... style flags301 302 /**
303 * The logical unit to which the option belongs. Non-constant
304 * options and corresponding named constants share the same
305 * unit. May be NULL.
306 */307 const(char)* unit;
308 }
309 310 enumAV_OPT_FLAG_ENCODING_PARAM = 1;
311 enumAV_OPT_FLAG_DECODING_PARAM = 2;
312 enumAV_OPT_FLAG_AUDIO_PARAM = 8;
313 enumAV_OPT_FLAG_VIDEO_PARAM = 16;
314 enumAV_OPT_FLAG_SUBTITLE_PARAM = 32;
315 enumAV_OPT_FLAG_EXPORT = 64;
316 enumAV_OPT_FLAG_READONLY = 128;
317 enumAV_OPT_FLAG_BSF_PARAM = 1 << 8;
318 enumAV_OPT_FLAG_FILTERING_PARAM = 1 << 16;
319 enumAV_OPT_FLAG_DEPRECATED = 1 << 17;
320 321 /**
322 * A single allowed range of values, or a single allowed value.
323 */324 structAVOptionRange325 {
326 const(char)* str;
327 /**
328 * Value range.
329 * For string ranges this represents the min/max length.
330 * For dimensions this represents the min/max pixel count or width/height in multi-component case.
331 */332 doublevalue_min;
333 doublevalue_max;
334 /**
335 * Value's component range.
336 * For string this represents the unicode range for chars, 0-127 limits to ASCII.
337 */338 doublecomponent_min;
339 doublecomponent_max;
340 /**
341 * Range flag.
342 * If set to 1 the struct encodes a range, if set to 0 a single value.
343 */344 intis_range;
345 }
346 347 /**
348 * List of AVOptionRange structs.
349 */350 structAVOptionRanges351 {
352 /**
353 * Array of option ranges.
354 *
355 * Most of option types use just one component.
356 * Following describes multi-component option types:
357 *
358 * AV_OPT_TYPE_IMAGE_SIZE:
359 * component index 0: range of pixel count (width * height).
360 * component index 1: range of width.
361 * component index 2: range of height.
362 *
363 * @note To obtain multi-component version of this structure, user must
364 * provide AV_OPT_MULTI_COMPONENT_RANGE to av_opt_query_ranges or
365 * av_opt_query_ranges_default function.
366 *
367 * Multi-component range can be read as in following example:
368 *
369 * @code
370 * int range_index, component_index;
371 * AVOptionRanges *ranges;
372 * AVOptionRange *range[3]; //may require more than 3 in the future.
373 * av_opt_query_ranges(&ranges, obj, key, AV_OPT_MULTI_COMPONENT_RANGE);
374 * for (range_index = 0; range_index < ranges->nb_ranges; range_index++) {
375 * for (component_index = 0; component_index < ranges->nb_components; component_index++)
376 * range[component_index] = ranges->range[ranges->nb_ranges * component_index + range_index];
377 * //do something with range here.
378 * }
379 * av_opt_freep_ranges(&ranges);
380 * @endcode
381 */382 AVOptionRange** range;
383 /**
384 * Number of ranges per component.
385 */386 intnb_ranges;
387 /**
388 * Number of componentes.
389 */390 intnb_components;
391 }
392 393 /**
394 * Show the obj options.
395 *
396 * @param req_flags requested flags for the options to show. Show only the
397 * options for which it is opt->flags & req_flags.
398 * @param rej_flags rejected flags for the options to show. Show only the
399 * options for which it is !(opt->flags & req_flags).
400 * @param av_log_obj log context to use for showing the options
401 */402 intav_opt_show2 (void* obj, void* av_log_obj, intreq_flags, intrej_flags);
403 404 /**
405 * Set the values of all AVOption fields to their default values.
406 *
407 * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass)
408 */409 voidav_opt_set_defaults (void* s);
410 411 /**
412 * Set the values of all AVOption fields to their default values. Only these
413 * AVOption fields for which (opt->flags & mask) == flags will have their
414 * default applied to s.
415 *
416 * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass)
417 * @param mask combination of AV_OPT_FLAG_*
418 * @param flags combination of AV_OPT_FLAG_*
419 */420 voidav_opt_set_defaults2 (void* s, intmask, intflags);
421 422 /**
423 * Parse the key/value pairs list in opts. For each key/value pair
424 * found, stores the value in the field in ctx that is named like the
425 * key. ctx must be an AVClass context, storing is done using
426 * AVOptions.
427 *
428 * @param opts options string to parse, may be NULL
429 * @param key_val_sep a 0-terminated list of characters used to
430 * separate key from value
431 * @param pairs_sep a 0-terminated list of characters used to separate
432 * two pairs from each other
433 * @return the number of successfully set key/value pairs, or a negative
434 * value corresponding to an AVERROR code in case of error:
435 * AVERROR(EINVAL) if opts cannot be parsed,
436 * the error code issued by av_opt_set() if a key/value pair
437 * cannot be set
438 */439 intav_set_options_string (
440 void* ctx,
441 const(char)* opts,
442 const(char)* key_val_sep,
443 const(char)* pairs_sep);
444 445 /**
446 * Parse the key-value pairs list in opts. For each key=value pair found,
447 * set the value of the corresponding option in ctx.
448 *
449 * @param ctx the AVClass object to set options on
450 * @param opts the options string, key-value pairs separated by a
451 * delimiter
452 * @param shorthand a NULL-terminated array of options names for shorthand
453 * notation: if the first field in opts has no key part,
454 * the key is taken from the first element of shorthand;
455 * then again for the second, etc., until either opts is
456 * finished, shorthand is finished or a named option is
457 * found; after that, all options must be named
458 * @param key_val_sep a 0-terminated list of characters used to separate
459 * key from value, for example '='
460 * @param pairs_sep a 0-terminated list of characters used to separate
461 * two pairs from each other, for example ':' or ','
462 * @return the number of successfully set key=value pairs, or a negative
463 * value corresponding to an AVERROR code in case of error:
464 * AVERROR(EINVAL) if opts cannot be parsed,
465 * the error code issued by av_set_string3() if a key/value pair
466 * cannot be set
467 *
468 * Options names must use only the following characters: a-z A-Z 0-9 - . / _
469 * Separators must use characters distinct from option names and from each
470 * other.
471 */472 intav_opt_set_from_string (
473 void* ctx,
474 const(char)* opts,
475 const(char*)* shorthand,
476 const(char)* key_val_sep,
477 const(char)* pairs_sep);
478 /**
479 * Free all allocated objects in obj.
480 */481 voidav_opt_free (void* obj);
482 483 /**
484 * Check whether a particular flag is set in a flags field.
485 *
486 * @param field_name the name of the flag field option
487 * @param flag_name the name of the flag to check
488 * @return non-zero if the flag is set, zero if the flag isn't set,
489 * isn't of the right type, or the flags field doesn't exist.
490 */491 intav_opt_flag_is_set (void* obj, const(char)* field_name, const(char)* flag_name);
492 493 /**
494 * Set all the options from a given dictionary on an object.
495 *
496 * @param obj a struct whose first element is a pointer to AVClass
497 * @param options options to process. This dictionary will be freed and replaced
498 * by a new one containing all options not found in obj.
499 * Of course this new dictionary needs to be freed by caller
500 * with av_dict_free().
501 *
502 * @return 0 on success, a negative AVERROR if some option was found in obj,
503 * but could not be set.
504 *
505 * @see av_dict_copy()
506 */507 intav_opt_set_dict (void* obj, AVDictionary** options);
508 509 /**
510 * Set all the options from a given dictionary on an object.
511 *
512 * @param obj a struct whose first element is a pointer to AVClass
513 * @param options options to process. This dictionary will be freed and replaced
514 * by a new one containing all options not found in obj.
515 * Of course this new dictionary needs to be freed by caller
516 * with av_dict_free().
517 * @param search_flags A combination of AV_OPT_SEARCH_*.
518 *
519 * @return 0 on success, a negative AVERROR if some option was found in obj,
520 * but could not be set.
521 *
522 * @see av_dict_copy()
523 */524 intav_opt_set_dict2 (void* obj, AVDictionary** options, intsearch_flags);
525 526 /**
527 * Extract a key-value pair from the beginning of a string.
528 *
529 * @param ropts pointer to the options string, will be updated to
530 * point to the rest of the string (one of the pairs_sep
531 * or the final NUL)
532 * @param key_val_sep a 0-terminated list of characters used to separate
533 * key from value, for example '='
534 * @param pairs_sep a 0-terminated list of characters used to separate
535 * two pairs from each other, for example ':' or ','
536 * @param flags flags; see the AV_OPT_FLAG_* values below
537 * @param rkey parsed key; must be freed using av_free()
538 * @param rval parsed value; must be freed using av_free()
539 *
540 * @return >=0 for success, or a negative value corresponding to an
541 * AVERROR code in case of error; in particular:
542 * AVERROR(EINVAL) if no key is present
543 *
544 */545 intav_opt_get_key_value (
546 const(char*)* ropts,
547 const(char)* key_val_sep,
548 const(char)* pairs_sep,
549 uintflags,
550 char** rkey,
551 char** rval);
552 553 enum554 {
555 /**
556 * Accept to parse a value without a key; the key will then be returned
557 * as NULL.
558 */559 AV_OPT_FLAG_IMPLICIT_KEY = 1560 }
561 562 /**
563 * @defgroup opt_eval_funcs Evaluating option strings
564 * @{
565 * This group of functions can be used to evaluate option strings
566 * and get numbers out of them. They do the same thing as av_opt_set(),
567 * except the result is written into the caller-supplied pointer.
568 *
569 * @param obj a struct whose first element is a pointer to AVClass.
570 * @param o an option for which the string is to be evaluated.
571 * @param val string to be evaluated.
572 * @param *_out value of the string will be written here.
573 *
574 * @return 0 on success, a negative number on failure.
575 */576 intav_opt_eval_flags (void* obj, const(AVOption)* o, const(char)* val, int* flags_out);
577 intav_opt_eval_int (void* obj, const(AVOption)* o, const(char)* val, int* int_out);
578 intav_opt_eval_int64 (void* obj, const(AVOption)* o, const(char)* val, long* int64_out);
579 intav_opt_eval_float (void* obj, const(AVOption)* o, const(char)* val, float* float_out);
580 intav_opt_eval_double (void* obj, const(AVOption)* o, const(char)* val, double* double_out);
581 intav_opt_eval_q (void* obj, const(AVOption)* o, const(char)* val, AVRational* q_out);
582 /**
583 * @}
584 */585 586 enumAV_OPT_SEARCH_CHILDREN = 1 << 0; /**< Search in possible children of the
587 given object first. */588 /**
589 * The obj passed to av_opt_find() is fake -- only a double pointer to AVClass
590 * instead of a required pointer to a struct containing AVClass. This is
591 * useful for searching for options without needing to allocate the corresponding
592 * object.
593 */594 enumAV_OPT_SEARCH_FAKE_OBJ = 1 << 1;
595 596 /**
597 * In av_opt_get, return NULL if the option has a pointer type and is set to NULL,
598 * rather than returning an empty string.
599 */600 enumAV_OPT_ALLOW_NULL = 1 << 2;
601 602 /**
603 * Allows av_opt_query_ranges and av_opt_query_ranges_default to return more than
604 * one component for certain option types.
605 * @see AVOptionRanges for details.
606 */607 enumAV_OPT_MULTI_COMPONENT_RANGE = 1 << 12;
608 609 /**
610 * Look for an option in an object. Consider only options which
611 * have all the specified flags set.
612 *
613 * @param[in] obj A pointer to a struct whose first element is a
614 * pointer to an AVClass.
615 * Alternatively a double pointer to an AVClass, if
616 * AV_OPT_SEARCH_FAKE_OBJ search flag is set.
617 * @param[in] name The name of the option to look for.
618 * @param[in] unit When searching for named constants, name of the unit
619 * it belongs to.
620 * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG).
621 * @param search_flags A combination of AV_OPT_SEARCH_*.
622 *
623 * @return A pointer to the option found, or NULL if no option
624 * was found.
625 *
626 * @note Options found with AV_OPT_SEARCH_CHILDREN flag may not be settable
627 * directly with av_opt_set(). Use special calls which take an options
628 * AVDictionary (e.g. avformat_open_input()) to set options found with this
629 * flag.
630 */631 const(AVOption)* av_opt_find (
632 void* obj,
633 const(char)* name,
634 const(char)* unit,
635 intopt_flags,
636 intsearch_flags);
637 638 /**
639 * Look for an option in an object. Consider only options which
640 * have all the specified flags set.
641 *
642 * @param[in] obj A pointer to a struct whose first element is a
643 * pointer to an AVClass.
644 * Alternatively a double pointer to an AVClass, if
645 * AV_OPT_SEARCH_FAKE_OBJ search flag is set.
646 * @param[in] name The name of the option to look for.
647 * @param[in] unit When searching for named constants, name of the unit
648 * it belongs to.
649 * @param opt_flags Find only options with all the specified flags set (AV_OPT_FLAG).
650 * @param search_flags A combination of AV_OPT_SEARCH_*.
651 * @param[out] target_obj if non-NULL, an object to which the option belongs will be
652 * written here. It may be different from obj if AV_OPT_SEARCH_CHILDREN is present
653 * in search_flags. This parameter is ignored if search_flags contain
654 * AV_OPT_SEARCH_FAKE_OBJ.
655 *
656 * @return A pointer to the option found, or NULL if no option
657 * was found.
658 */659 const(AVOption)* av_opt_find2 (
660 void* obj,
661 const(char)* name,
662 const(char)* unit,
663 intopt_flags,
664 intsearch_flags,
665 void** target_obj);
666 667 /**
668 * Iterate over all AVOptions belonging to obj.
669 *
670 * @param obj an AVOptions-enabled struct or a double pointer to an
671 * AVClass describing it.
672 * @param prev result of the previous call to av_opt_next() on this object
673 * or NULL
674 * @return next AVOption or NULL
675 */676 const(AVOption)* av_opt_next (const(void)* obj, const(AVOption)* prev);
677 678 /**
679 * Iterate over AVOptions-enabled children of obj.
680 *
681 * @param prev result of a previous call to this function or NULL
682 * @return next AVOptions-enabled child or NULL
683 */684 void* av_opt_child_next (void* obj, void* prev);
685 686 /**
687 * Iterate over potential AVOptions-enabled children of parent.
688 *
689 * @param prev result of a previous call to this function or NULL
690 * @return AVClass corresponding to next potential child or NULL
691 */692 const(AVClass)* av_opt_child_class_next (const(AVClass)* parent, const(AVClass)* prev);
693 694 /**
695 * @defgroup opt_set_funcs Option setting functions
696 * @{
697 * Those functions set the field of obj with the given name to value.
698 *
699 * @param[in] obj A struct whose first element is a pointer to an AVClass.
700 * @param[in] name the name of the field to set
701 * @param[in] val The value to set. In case of av_opt_set() if the field is not
702 * of a string type, then the given string is parsed.
703 * SI postfixes and some named scalars are supported.
704 * If the field is of a numeric type, it has to be a numeric or named
705 * scalar. Behavior with more than one scalar and +- infix operators
706 * is undefined.
707 * If the field is of a flags type, it has to be a sequence of numeric
708 * scalars or named flags separated by '+' or '-'. Prefixing a flag
709 * with '+' causes it to be set without affecting the other flags;
710 * similarly, '-' unsets a flag.
711 * @param search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN
712 * is passed here, then the option may be set on a child of obj.
713 *
714 * @return 0 if the value has been set, or an AVERROR code in case of
715 * error:
716 * AVERROR_OPTION_NOT_FOUND if no matching option exists
717 * AVERROR(ERANGE) if the value is out of range
718 * AVERROR(EINVAL) if the value is not valid
719 */720 intav_opt_set (void* obj, const(char)* name, const(char)* val, intsearch_flags);
721 intav_opt_set_int (void* obj, const(char)* name, longval, intsearch_flags);
722 intav_opt_set_double (void* obj, const(char)* name, doubleval, intsearch_flags);
723 intav_opt_set_q (void* obj, const(char)* name, AVRationalval, intsearch_flags);
724 intav_opt_set_bin (void* obj, const(char)* name, const(ubyte)* val, intsize, intsearch_flags);
725 intav_opt_set_image_size (void* obj, const(char)* name, intw, inth, intsearch_flags);
726 intav_opt_set_pixel_fmt (void* obj, const(char)* name, AVPixelFormatfmt, intsearch_flags);
727 intav_opt_set_sample_fmt (void* obj, const(char)* name, AVSampleFormatfmt, intsearch_flags);
728 intav_opt_set_video_rate (void* obj, const(char)* name, AVRationalval, intsearch_flags);
729 intav_opt_set_channel_layout (void* obj, const(char)* name, longch_layout, intsearch_flags);
730 /**
731 * @note Any old dictionary present is discarded and replaced with a copy of the new one. The
732 * caller still owns val is and responsible for freeing it.
733 */734 intav_opt_set_dict_val (void* obj, const(char)* name, const(AVDictionary)* val, intsearch_flags);
735 736 /**
737 * Set a binary option to an integer list.
738 *
739 * @param obj AVClass object to set options on
740 * @param name name of the binary option
741 * @param val pointer to an integer list (must have the correct type with
742 * regard to the contents of the list)
743 * @param term list terminator (usually 0 or -1)
744 * @param flags search flags
745 */746 extern (D) autoav_opt_set_int_list(T0, T1, T2, T3, T4)(autorefT0obj, autorefT1name, autorefT2val, autorefT3term, autorefT4flags)
747 {
748 returnav_int_list_length(val, term) > INT_MAX / (*val).sizeof ? AVERROR(EINVAL) : av_opt_set_bin(obj, name, cast(const(ubyte)*) val, av_int_list_length(val, term) * (*val).sizeof, flags);
749 }
750 751 /**
752 * @}
753 */754 755 /**
756 * @defgroup opt_get_funcs Option getting functions
757 * @{
758 * Those functions get a value of the option with the given name from an object.
759 *
760 * @param[in] obj a struct whose first element is a pointer to an AVClass.
761 * @param[in] name name of the option to get.
762 * @param[in] search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN
763 * is passed here, then the option may be found in a child of obj.
764 * @param[out] out_val value of the option will be written here
765 * @return >=0 on success, a negative error code otherwise
766 */767 /**
768 * @note the returned string will be av_malloc()ed and must be av_free()ed by the caller
769 *
770 * @note if AV_OPT_ALLOW_NULL is set in search_flags in av_opt_get, and the option has
771 * AV_OPT_TYPE_STRING or AV_OPT_TYPE_BINARY and is set to NULL, *out_val will be set
772 * to NULL instead of an allocated empty string.
773 */774 intav_opt_get (void* obj, const(char)* name, intsearch_flags, ubyte** out_val);
775 intav_opt_get_int (void* obj, const(char)* name, intsearch_flags, long* out_val);
776 intav_opt_get_double (void* obj, const(char)* name, intsearch_flags, double* out_val);
777 intav_opt_get_q (void* obj, const(char)* name, intsearch_flags, AVRational* out_val);
778 intav_opt_get_image_size (void* obj, const(char)* name, intsearch_flags, int* w_out, int* h_out);
779 intav_opt_get_pixel_fmt (void* obj, const(char)* name, intsearch_flags, AVPixelFormat* out_fmt);
780 intav_opt_get_sample_fmt (void* obj, const(char)* name, intsearch_flags, AVSampleFormat* out_fmt);
781 intav_opt_get_video_rate (void* obj, const(char)* name, intsearch_flags, AVRational* out_val);
782 intav_opt_get_channel_layout (void* obj, const(char)* name, intsearch_flags, long* ch_layout);
783 /**
784 * @param[out] out_val The returned dictionary is a copy of the actual value and must
785 * be freed with av_dict_free() by the caller
786 */787 intav_opt_get_dict_val (void* obj, const(char)* name, intsearch_flags, AVDictionary** out_val);
788 /**
789 * @}
790 */791 /**
792 * Gets a pointer to the requested field in a struct.
793 * This function allows accessing a struct even when its fields are moved or
794 * renamed since the application making the access has been compiled,
795 *
796 * @returns a pointer to the field, it can be cast to the correct type and read
797 * or written to.
798 */799 void* av_opt_ptr (const(AVClass)* avclass, void* obj, const(char)* name);
800 801 /**
802 * Free an AVOptionRanges struct and set it to NULL.
803 */804 voidav_opt_freep_ranges (AVOptionRanges** ranges);
805 806 /**
807 * Get a list of allowed ranges for the given option.
808 *
809 * The returned list may depend on other fields in obj like for example profile.
810 *
811 * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored
812 * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance
813 * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges
814 *
815 * The result must be freed with av_opt_freep_ranges.
816 *
817 * @return number of compontents returned on success, a negative errro code otherwise
818 */819 intav_opt_query_ranges (AVOptionRanges**, void* obj, const(char)* key, intflags);
820 821 /**
822 * Copy options from src object into dest object.
823 *
824 * Options that require memory allocation (e.g. string or binary) are malloc'ed in dest object.
825 * Original memory allocated for such options is freed unless both src and dest options points to the same memory.
826 *
827 * @param dest Object to copy from
828 * @param src Object to copy into
829 * @return 0 on success, negative on error
830 */831 intav_opt_copy (void* dest, const(void)* src);
832 833 /**
834 * Get a default list of allowed ranges for the given option.
835 *
836 * This list is constructed without using the AVClass.query_ranges() callback
837 * and can be used as fallback from within the callback.
838 *
839 * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored
840 * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance
841 * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges
842 *
843 * The result must be freed with av_opt_free_ranges.
844 *
845 * @return number of compontents returned on success, a negative errro code otherwise
846 */847 intav_opt_query_ranges_default (AVOptionRanges**, void* obj, const(char)* key, intflags);
848 849 /**
850 * Check if given option is set to its default value.
851 *
852 * Options o must belong to the obj. This function must not be called to check child's options state.
853 * @see av_opt_is_set_to_default_by_name().
854 *
855 * @param obj AVClass object to check option on
856 * @param o option to be checked
857 * @return >0 when option is set to its default,
858 * 0 when option is not set its default,
859 * <0 on error
860 */861 intav_opt_is_set_to_default (void* obj, const(AVOption)* o);
862 863 /**
864 * Check if given option is set to its default value.
865 *
866 * @param obj AVClass object to check option on
867 * @param name option name
868 * @param search_flags combination of AV_OPT_SEARCH_*
869 * @return >0 when option is set to its default,
870 * 0 when option is not set its default,
871 * <0 on error
872 */873 intav_opt_is_set_to_default_by_name (void* obj, const(char)* name, intsearch_flags);
874 875 enumAV_OPT_SERIALIZE_SKIP_DEFAULTS = 0x00000001; ///< Serialize options that are not set to default values only.876 enumAV_OPT_SERIALIZE_OPT_FLAGS_EXACT = 0x00000002; ///< Serialize options that exactly match opt_flags only.877 878 /**
879 * Serialize object's options.
880 *
881 * Create a string containing object's serialized options.
882 * Such string may be passed back to av_opt_set_from_string() in order to restore option values.
883 * A key/value or pairs separator occurring in the serialized value or
884 * name string are escaped through the av_escape() function.
885 *
886 * @param[in] obj AVClass object to serialize
887 * @param[in] opt_flags serialize options with all the specified flags set (AV_OPT_FLAG)
888 * @param[in] flags combination of AV_OPT_SERIALIZE_* flags
889 * @param[out] buffer Pointer to buffer that will be allocated with string containg serialized options.
890 * Buffer must be freed by the caller when is no longer needed.
891 * @param[in] key_val_sep character used to separate key from value
892 * @param[in] pairs_sep character used to separate two pairs from each other
893 * @return >= 0 on success, negative on error
894 * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same.
895 */896 intav_opt_serialize (
897 void* obj,
898 intopt_flags,
899 intflags,
900 char** buffer,
901 constcharkey_val_sep,
902 constcharpairs_sep);
903 /**
904 * @}
905 */906 907 /* AVUTIL_OPT_H */