/* * AVOptions * copyright (c) 2005 Michael Niedermayer <michaelni@gmx.at> * * This file is part of FFmpeg. * * FFmpeg is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * FFmpeg is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with FFmpeg; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef AVUTIL_OPT_H#define AVUTIL_OPT_H /** * @file * AVOptions */ #include "rational.h"#include "avutil.h"#include "channel_layout.h"#include "dict.h"#include "log.h"#include "pixfmt.h"#include "samplefmt.h" /** * @defgroup avoptions AVOptions * @ingroup lavu_data * @{ * AVOptions provide a generic system to declare options on arbitrary structs * ("objects"). An option can have a help text, a type and a range of possible * values. Options may then be enumerated, read and written to. * * There are two modes of access to members of AVOption and its child structs. * One is called 'native access', and refers to access from the code that * declares the AVOption in question.  The other is 'foreign access', and refers * to access from other code. * * Certain struct members in this header are documented as 'native access only' * or similar - it means that only the code that declared the AVOption in * question is allowed to access the field. This allows us to extend the * semantics of those fields without breaking API compatibility. * * @section avoptions_scope Scope of AVOptions * * AVOptions is designed to support any set of multimedia configuration options * that can be defined at compile-time.  Although it is mainly used to expose * FFmpeg options, you are welcome to adapt it to your own use case. * * No single approach can ever fully solve the problem of configuration, * but please submit a patch if you believe you have found a problem * that is best solved by extending AVOptions. * * @section avoptions_implement Implementing AVOptions * This section describes how to add AVOptions capabilities to a struct. * * All AVOptions-related information is stored in an AVClass. Therefore * the first member of the struct should be a pointer to an AVClass describing it. * The option field of the AVClass must be set to a NULL-terminated static array * of AVOptions. Each AVOption must have a non-empty name, a type, a default * value and for number-type AVOptions also a range of allowed values. It must * also declare an offset in bytes from the start of the struct, where the field * associated with this AVOption is located. Other fields in the AVOption struct * should also be set when applicable, but are not required. * * The following example illustrates an AVOptions-enabled struct: * @code * typedef struct test_struct { *     const AVClass *class; *     int      int_opt; *     char    *str_opt; *     uint8_t *bin_opt; *     int      bin_len; * } test_struct; * * static const AVOption test_options[] = { *   { "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt), *     AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX }, *   { "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt), *     AV_OPT_TYPE_STRING }, *   { "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt), *     AV_OPT_TYPE_BINARY }, *   { NULL }, * }; * * static const AVClass test_class = { *     .class_name = "test class", *     .item_name  = av_default_item_name, *     .option     = test_options, *     .version    = LIBAVUTIL_VERSION_INT, * }; * @endcode * * Next, when allocating your struct, you must ensure that the AVClass pointer * is set to the correct value. Then, av_opt_set_defaults() can be called to * initialize defaults. After that the struct is ready to be used with the * AVOptions API. * * When cleaning up, you may use the av_opt_free() function to automatically * free all the allocated string and binary options. * * Continuing with the above example: * * @code * test_struct *alloc_test_struct(void) * { *     test_struct *ret = av_mallocz(sizeof(*ret)); *     ret->class = &test_class; *     av_opt_set_defaults(ret); *     return ret; * } * void free_test_struct(test_struct **foo) * { *     av_opt_free(*foo); *     av_freep(foo); * } * @endcode * * @subsection avoptions_implement_nesting Nesting *      It may happen that an AVOptions-enabled struct contains another *      AVOptions-enabled struct as a member (e.g. AVCodecContext in *      libavcodec exports generic options, while its priv_data field exports *      codec-specific options). In such a case, it is possible to set up the *      parent struct to export a child's options. To do that, simply *      implement AVClass.child_next() and AVClass.child_class_iterate() in the *      parent struct's AVClass. *      Assuming that the test_struct from above now also contains a *      child_struct field: * *      @code *      typedef struct child_struct { *          AVClass *class; *          int flags_opt; *      } child_struct; *      static const AVOption child_opts[] = { *          { "test_flags", "This is a test option of flags type.", *            offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX }, *          { NULL }, *      }; *      static const AVClass child_class = { *          .class_name = "child class", *          .item_name  = av_default_item_name, *          .option     = child_opts, *          .version    = LIBAVUTIL_VERSION_INT, *      }; * *      void *child_next(void *obj, void *prev) *      { *          test_struct *t = obj; *          if (!prev && t->child_struct) *              return t->child_struct; *          return NULL *      } *      const AVClass child_class_iterate(void **iter) *      { *          const AVClass *c = *iter ? NULL : &child_class; *          *iter = (void*)(uintptr_t)c; *          return c; *      } *      @endcode *      Putting child_next() and child_class_iterate() as defined above into *      test_class will now make child_struct's options accessible through *      test_struct (again, proper setup as described above needs to be done on *      child_struct right after it is created). * *      From the above example it might not be clear why both child_next() *      and child_class_iterate() are needed. The distinction is that child_next() *      iterates over actually existing objects, while child_class_iterate() *      iterates over all possible child classes. E.g. if an AVCodecContext *      was initialized to use a codec which has private options, then its *      child_next() will return AVCodecContext.priv_data and finish *      iterating. OTOH child_class_iterate() on AVCodecContext.av_class will *      iterate over all available codecs with private options. * * @subsection avoptions_implement_named_constants Named constants *      It is possible to create named constants for options. Simply set the unit *      field of the option the constants should apply to a string and *      create the constants themselves as options of type AV_OPT_TYPE_CONST *      with their unit field set to the same string. *      Their default_val field should contain the value of the named *      constant. *      For example, to add some named constants for the test_flags option *      above, put the following into the child_opts array: *      @code *      { "test_flags", "This is a test option of flags type.", *        offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" }, *      { "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0, "test_unit" }, *      @endcode * * @section avoptions_use Using AVOptions * This section deals with accessing options in an AVOptions-enabled struct. * Such structs in FFmpeg are e.g. AVCodecContext in libavcodec or * AVFormatContext in libavformat. * * @subsection avoptions_use_examine Examining AVOptions * The basic functions for examining options are av_opt_next(), which iterates * over all options defined for one object, and av_opt_find(), which searches * for an option with the given name. * * The situation is more complicated with nesting. An AVOptions-enabled struct * may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag * to av_opt_find() will make the function search children recursively. * * For enumerating there are basically two cases. The first is when you want to * get all options that may potentially exist on the struct and its children * (e.g.  when constructing documentation). In that case you should call * av_opt_child_class_iterate() recursively on the parent struct's AVClass.  The * second case is when you have an already initialized struct with all its * children and you want to get all options that can be actually written or read * from it. In that case you should call av_opt_child_next() recursively (and * av_opt_next() on each result). * * @subsection avoptions_use_get_set Reading and writing AVOptions * When setting options, you often have a string read directly from the * user. In such a case, simply passing it to av_opt_set() is enough. For * non-string type options, av_opt_set() will parse the string according to the * option type. * * Similarly av_opt_get() will read any option type and convert it to a string * which will be returned. Do not forget that the string is allocated, so you * have to free it with av_free(). * * In some cases it may be more convenient to put all options into an * AVDictionary and call av_opt_set_dict() on it. A specific case of this * are the format/codec open functions in lavf/lavc which take a dictionary * filled with option as a parameter. This makes it possible to set some options * that cannot be set otherwise, since e.g. the input file format is not known * before the file is actually opened. */ /** * An option type determines: * - for native access, the underlying C type of the field that an AVOption *   refers to; * - for foreign access, the semantics of accessing the option through this API, *   e.g. which av_opt_get_*() and av_opt_set_*() functions can be called, or *   what format will av_opt_get()/av_opt_set() expect/produce. */enum AVOptionType{    /**     * Underlying C type is unsigned int.     */    AV_OPT_TYPE_FLAGS = 1,    /**     * Underlying C type is int.     */    AV_OPT_TYPE_INT,    /**     * Underlying C type is int64_t.     */    AV_OPT_TYPE_INT64,    /**     * Underlying C type is double.     */    AV_OPT_TYPE_DOUBLE,    /**     * Underlying C type is float.     */    AV_OPT_TYPE_FLOAT,    /**     * Underlying C type is a uint8_t* that is either NULL or points to a C     * string allocated with the av_malloc() family of functions.     */    AV_OPT_TYPE_STRING,    /**     * Underlying C type is AVRational.     */    AV_OPT_TYPE_RATIONAL,    /**     * Underlying C type is a uint8_t* that is either NULL or points to an array     * allocated with the av_malloc() family of functions. The pointer is     * immediately followed by an int containing the array length in bytes.     */    AV_OPT_TYPE_BINARY,    /**     * Underlying C type is AVDictionary*.     */    AV_OPT_TYPE_DICT,    /**     * Underlying C type is uint64_t.     */    AV_OPT_TYPE_UINT64,    /**     * Special option type for declaring named constants. Does not correspond to     * an actual field in the object, offset must be 0.     */    AV_OPT_TYPE_CONST,    /**     * Underlying C type is two consecutive integers.     */    AV_OPT_TYPE_IMAGE_SIZE,    /**     * Underlying C type is enum AVPixelFormat.     */    AV_OPT_TYPE_PIXEL_FMT,    /**     * Underlying C type is enum AVSampleFormat.     */    AV_OPT_TYPE_SAMPLE_FMT,    /**     * Underlying C type is AVRational.     */    AV_OPT_TYPE_VIDEO_RATE,    /**     * Underlying C type is int64_t.     */    AV_OPT_TYPE_DURATION,    /**     * Underlying C type is uint8_t[4].     */    AV_OPT_TYPE_COLOR,    /**     * Underlying C type is int.     */    AV_OPT_TYPE_BOOL,    /**     * Underlying C type is AVChannelLayout.     */    AV_OPT_TYPE_CHLAYOUT,    /**     * Underlying C type is unsigned int.     */    AV_OPT_TYPE_UINT,     /**     * May be combined with another regular option type to declare an array     * option.     *     * For array options, @ref AVOption.offset should refer to a pointer     * corresponding to the option type. The pointer should be immediately     * followed by an unsigned int that will store the number of elements in the     * array.     */    AV_OPT_TYPE_FLAG_ARRAY = (1 << 16),}; /** * A generic parameter which can be set by the user for muxing or encoding. */#define AV_OPT_FLAG_ENCODING_PARAM  (1 << 0)/** * A generic parameter which can be set by the user for demuxing or decoding. */#define AV_OPT_FLAG_DECODING_PARAM  (1 << 1)#define AV_OPT_FLAG_AUDIO_PARAM     (1 << 3)#define AV_OPT_FLAG_VIDEO_PARAM     (1 << 4)#define AV_OPT_FLAG_SUBTITLE_PARAM  (1 << 5)/** * The option is intended for exporting values to the caller. */#define AV_OPT_FLAG_EXPORT          (1 << 6)/** * The option may not be set through the AVOptions API, only read. * This flag only makes sense when AV_OPT_FLAG_EXPORT is also set. */#define AV_OPT_FLAG_READONLY        (1 << 7)/** * A generic parameter which can be set by the user for bit stream filtering. */#define AV_OPT_FLAG_BSF_PARAM       (1 << 8) /** * A generic parameter which can be set by the user at runtime. */#define AV_OPT_FLAG_RUNTIME_PARAM   (1 << 15)/** * A generic parameter which can be set by the user for filtering. */#define AV_OPT_FLAG_FILTERING_PARAM (1 << 16)/** * Set if option is deprecated, users should refer to AVOption.help text for * more information. */#define AV_OPT_FLAG_DEPRECATED      (1 << 17)/** * Set if option constants can also reside in child objects. */#define AV_OPT_FLAG_CHILD_CONSTS    (1 << 18) /** * May be set as default_val for AV_OPT_TYPE_FLAG_ARRAY options. */typedef struct AVOptionArrayDef {    /**     * Native access only.     *     * Default value of the option, as would be serialized by av_opt_get() (i.e.     * using the value of sep as the separator).     */    const char         *def;     /**     * Minimum number of elements in the array. When this field is non-zero, def     * must be non-NULL and contain at least this number of elements.     */    unsigned            size_min;    /**     * Maximum number of elements in the array, 0 when unlimited.     */    unsigned            size_max;     /**     * Separator between array elements in string representations of this     * option, used by av_opt_set() and av_opt_get(). It must be a printable     * ASCII character, excluding alphanumeric and the backslash. A comma is     * used when sep=0.     *     * The separator and the backslash must be backslash-escaped in order to     * appear in string representations of the option value.     */    char                sep;} AVOptionArrayDef; /** * AVOption */typedef struct AVOption {    const char *name;     /**     * short English help text     * @todo What about other languages?     */    const char *help;     /**     * Native access only.     *     * The offset relative to the context structure where the option     * value is stored. It should be 0 for named constants.     */    int offset;    enum AVOptionType type;     /**     * Native access only, except when documented otherwise.     * the default value for scalar options     */    union {        int64_t i64;        double dbl;        const char *str;        /* TODO those are unused now */        AVRational q;         /**         * Used for AV_OPT_TYPE_FLAG_ARRAY options. May be NULL.         *         * Foreign access to some members allowed, as noted in AVOptionArrayDef         * documentation.         */        const AVOptionArrayDef *arr;    } default_val;    double min;                 ///< minimum valid value for the option    double max;                 ///< maximum valid value for the option     /**     * A combination of AV_OPT_FLAG_*.     */    int flags;     /**     * The logical unit to which the option belongs. Non-constant     * options and corresponding named constants share the same     * unit. May be NULL.     */    const char *unit;} AVOption; /** * A single allowed range of values, or a single allowed value. */typedef struct AVOptionRange {    const char *str;    /**     * Value range.     * For string ranges this represents the min/max length.     * For dimensions this represents the min/max pixel count or width/height in multi-component case.     */    double value_min, value_max;    /**     * Value's component range.     * For string this represents the unicode range for chars, 0-127 limits to ASCII.     */    double component_min, component_max;    /**     * Range flag.     * If set to 1 the struct encodes a range, if set to 0 a single value.

Lines 1–500 of 1194. Load more