annotate opt.h @ 7556:a8ddede2248f libavcodec

mlpdec: Put some doxy comments to the right of vars instead of interleaved.
author ramiro
date Wed, 13 Aug 2008 01:41:06 +0000
parents a725aab8fe81
children c4a4495715dd
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3699
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
1 /*
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
2 * AVOptions
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
3 * copyright (c) 2005 Michael Niedermayer <michaelni@gmx.at>
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
4 *
3947
c8c591fe26f8 Change license headers to say 'FFmpeg' instead of 'this program/this library'
diego
parents: 3702
diff changeset
5 * This file is part of FFmpeg.
c8c591fe26f8 Change license headers to say 'FFmpeg' instead of 'this program/this library'
diego
parents: 3702
diff changeset
6 *
c8c591fe26f8 Change license headers to say 'FFmpeg' instead of 'this program/this library'
diego
parents: 3702
diff changeset
7 * FFmpeg is free software; you can redistribute it and/or
3699
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
8 * modify it under the terms of the GNU Lesser General Public
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
9 * License as published by the Free Software Foundation; either
3947
c8c591fe26f8 Change license headers to say 'FFmpeg' instead of 'this program/this library'
diego
parents: 3702
diff changeset
10 * version 2.1 of the License, or (at your option) any later version.
3699
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
11 *
3947
c8c591fe26f8 Change license headers to say 'FFmpeg' instead of 'this program/this library'
diego
parents: 3702
diff changeset
12 * FFmpeg is distributed in the hope that it will be useful,
3699
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
15 * Lesser General Public License for more details.
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
16 *
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
17 * You should have received a copy of the GNU Lesser General Public
3947
c8c591fe26f8 Change license headers to say 'FFmpeg' instead of 'this program/this library'
diego
parents: 3702
diff changeset
18 * License along with FFmpeg; if not, write to the Free Software
3699
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
20 */
c537a97eec66 Add official LGPL license headers to the files that were missing them.
diego
parents: 2967
diff changeset
21
5830
1d83e9c34641 Add FFMPEG_ prefix to all multiple inclusion guards.
diego
parents: 5299
diff changeset
22 #ifndef FFMPEG_OPT_H
1d83e9c34641 Add FFMPEG_ prefix to all multiple inclusion guards.
diego
parents: 5299
diff changeset
23 #define FFMPEG_OPT_H
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
24
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
25 /**
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
26 * @file opt.h
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
27 * AVOptions
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
28 */
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
29
6395
9259af8a686b Install headers in $prefix/include/$libname
mru
parents: 6034
diff changeset
30 #include "libavutil/rational.h"
5162
4394344397d8 include all prerequisites in header files
mru
parents: 4629
diff changeset
31
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
32 enum AVOptionType{
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
33 FF_OPT_TYPE_FLAGS,
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
34 FF_OPT_TYPE_INT,
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
35 FF_OPT_TYPE_INT64,
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
36 FF_OPT_TYPE_DOUBLE,
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
37 FF_OPT_TYPE_FLOAT,
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
38 FF_OPT_TYPE_STRING,
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
39 FF_OPT_TYPE_RATIONAL,
6034
72bb141d9c05 Add FF_OPT_TYPE_BINARY and use it to add a cryptokey option
reimar
parents: 5830
diff changeset
40 FF_OPT_TYPE_BINARY, ///< offset must point to a pointer immediately followed by an int for the length
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
41 FF_OPT_TYPE_CONST=128,
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
42 };
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
43
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
44 /**
7007
fa39bba4c8a4 minor spelling/grammar fixes
diego
parents: 6395
diff changeset
45 * AVOption
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
46 */
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
47 typedef struct AVOption {
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
48 const char *name;
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
49
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
50 /**
7007
fa39bba4c8a4 minor spelling/grammar fixes
diego
parents: 6395
diff changeset
51 * short English help text
fa39bba4c8a4 minor spelling/grammar fixes
diego
parents: 6395
diff changeset
52 * @todo What about other languages?
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
53 */
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
54 const char *help;
7086
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
55
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
56 /**
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
57 * The offset relative to the context structure where the option
7099
07172377ec9f Fix typo in libavcodec/opt.h.
stefano
parents: 7086
diff changeset
58 * value is stored. It should be 0 for named constants.
7086
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
59 */
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
60 int offset;
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
61 enum AVOptionType type;
2967
ef2149182f1c COSMETICS: Remove all trailing whitespace.
diego
parents: 2876
diff changeset
62
7086
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
63 /**
7175
4a635a1859f0 Clarify/simplify documentation for the default_val field in AVOption.
stefano
parents: 7099
diff changeset
64 * the default value for scalar options
7086
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
65 */
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
66 double default_val;
7086
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
67 double min; ///< minimum valid value for the option
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
68 double max; ///< maximum valid value for the option
2967
ef2149182f1c COSMETICS: Remove all trailing whitespace.
diego
parents: 2876
diff changeset
69
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
70 int flags;
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
71 #define AV_OPT_FLAG_ENCODING_PARAM 1 ///< a generic parameter which can be set by the user for muxing or encoding
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
72 #define AV_OPT_FLAG_DECODING_PARAM 2 ///< a generic parameter which can be set by the user for demuxing or decoding
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
73 #define AV_OPT_FLAG_METADATA 4 ///< some data extracted or inserted into the file like title, comment, ...
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
74 #define AV_OPT_FLAG_AUDIO_PARAM 8
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
75 #define AV_OPT_FLAG_VIDEO_PARAM 16
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
76 #define AV_OPT_FLAG_SUBTITLE_PARAM 32
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
77 //FIXME think about enc-audio, ... style flags
7086
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
78
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
79 /**
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
80 * The logical unit to which the option belongs. Non-constant
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
81 * options and corresponding named constants share the same
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
82 * unit. May be NULL.
18279e49cd4a Extend documentation for AVOption.
stefano
parents: 7007
diff changeset
83 */
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
84 const char *unit;
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
85 } AVOption;
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
86
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
87
7205
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
88 /**
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
89 * Looks for an option in \p obj. Looks only for the options which
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
90 * have the flags set as specified in \p mask and \p flags (that is,
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
91 * for which it is the case that opt->flags & mask == flags).
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
92 *
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
93 * @param[in] obj a pointer to a struct whose first element is a
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
94 * pointer to an #AVClass
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
95 * @param[in] name the name of the option to look for
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
96 * @param[in] unit the unit of the option to look for, or any if NULL
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
97 * @return a pointer to the option found, or NULL if no option
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
98 * has been found
68528efbc91f Document av_find_opt().
stefano
parents: 7175
diff changeset
99 */
4628
b0016ed89048 make av_find_opt() available to the public and add a mask+flags parameter to search for specific AVOptions
michael
parents: 4369
diff changeset
100 const AVOption *av_find_opt(void *obj, const char *name, const char *unit, int mask, int flags);
7224
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
101
7427
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
102 /**
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
103 * @see av_set_string2()
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
104 */
7224
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
105 attribute_deprecated const AVOption *av_set_string(void *obj, const char *name, const char *val);
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
106
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
107 /**
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
108 * Sets the field of obj with the given name to value.
7427
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
109 *
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
110 * @param[in] obj A struct whose first element is a pointer to an
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
111 * AVClass.
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
112 * @param[in] name the name of the field to set
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
113 * @param[in] val The value to set. If the field is not of a string
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
114 * type, then the given string is parsed.
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
115 * SI postfixes and some named scalars are supported.
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
116 * If the field is of a numeric type, it has to be a numeric or named
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
117 * scalar. Behavior with more than one scalar and +- infix operators
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
118 * is undefined.
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
119 * If the field is of a flags type, it has to be a sequence of numeric
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
120 * scalars or named flags separated by '+' or '-'. Prefixing a flag
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
121 * with '+' causes it to be set without affecting the other flags;
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
122 * similarly, '-' unsets a flag.
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
123 * @return a pointer to the AVOption corresponding to the field set or
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
124 * NULL if no matching AVOption exists, or if the value \p val is not
a725aab8fe81 Complete documentation for av_set_string().
stefano
parents: 7224
diff changeset
125 * valid
7224
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
126 * @param alloc when 1 then the old value will be av_freed() and the
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
127 * new av_strduped()
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
128 * when 0 then no av_free() nor av_strdup() will be used
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
129 */
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
130 const AVOption *av_set_string2(void *obj, const char *name, const char *val, int alloc);
d5a52b28c9de Fix the av_set_string() free / alloc issue.
michael
parents: 7205
diff changeset
131
4369
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
132 const AVOption *av_set_double(void *obj, const char *name, double n);
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
133 const AVOption *av_set_q(void *obj, const char *name, AVRational n);
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
134 const AVOption *av_set_int(void *obj, const char *name, int64_t n);
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
135 double av_get_double(void *obj, const char *name, const AVOption **o_out);
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
136 AVRational av_get_q(void *obj, const char *name, const AVOption **o_out);
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
137 int64_t av_get_int(void *obj, const char *name, const AVOption **o_out);
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
138 const char *av_get_string(void *obj, const char *name, const AVOption **o_out, char *buf, int buf_len);
e10acab2322a Constantize AVOption, solve few warnings, patch from flameeyes@gentoo.org aka "the other Diego"
lu_zero
parents: 3947
diff changeset
139 const AVOption *av_next_option(void *obj, const AVOption *last);
2876
8026edf6a349 avoid stdio.h
michael
parents: 2874
diff changeset
140 int av_opt_show(void *obj, void *av_log_obj);
3702
7e7d8a3fe080 make AVOptions default value field work.
gpoirier
parents: 3699
diff changeset
141 void av_opt_set_defaults(void *s);
4629
2faa1399dd68 add av_opt_set_defaults2() which sets just defaults from AVOptions whos flags match a user specified & mask = flags
michael
parents: 4628
diff changeset
142 void av_opt_set_defaults2(void *s, int mask, int flags);
2874
b6def74f5811 flags and named constants with type checking of course for AVOption
michael
parents:
diff changeset
143
5830
1d83e9c34641 Add FFMPEG_ prefix to all multiple inclusion guards.
diego
parents: 5299
diff changeset
144 #endif /* FFMPEG_OPT_H */