On Thu, Oct 06, 2011 at 10:10:29PM +0200, Anton Khirnov wrote:
>
> --- a/libavutil/opt.h
> +++ b/libavutil/opt.h
> @@ -32,6 +32,188 @@
>
> +/**
> + * @defgroup avoptions AVOptions
> + * @{
> + * AVOptions provide a generic system for arbitrary structs ("objects") to
> + * declare options on them.
That sounds weird - is
AVOptions provide a generic system to declare options on arbitrary
structs ("objects").
still what you are trying to say?
> An option can have a help text associated with it, a
> + * type and a range of possible values.
The latter two are not associated with the option?
> + * @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 must be a pointer to an AVClass describing
> it.
Which struct was that again? And what is described - the struct, the
AVClass, the AVOptions?
> + * Its option field must be set to a NULL-terminated static array of
> + * AVOptions.
Again what does "its" refer to?
> + * The following example illustrates an AVOptions-enabled struct:
> + * @code
> + * typedef struct test_struct {
> + * AVClass *class;
> + * int int_opt;
> + * char *str_opt;
> + * uint8_t *bin_opt;
> + * int bin_len;
> + * } test_struct;
Maybe this could be more readable with the member names aligned - your
call.
> + * Next, when allocating your struct, you must ensure that the AVClass
> pointer
> + * is set to the correct value. Then, av_opt_set_defaults() must be called to
> + * initialize defaults. After that the struct is ready to be used with
> AVOptions
> + * API.
with the AVOptions API
> + * Continuing with the above example:
> + * @code
> + * test_struct *alloc_test_struct(void)
> + * {
> + * }
> + * void free_test_struct(test_struct **foo)
> + * {
nit: add an empty line
> + * @subsection avoptions_implement_nesting Nesting
> + * It may happen that an AVOptions-enabled struct contains another
> + * AVOptions-enabled struct as its member (e.g. AVCodecContext in
s/its/a/
> + * lavc exports generic options, while its priv_data field exports
s/lavc/libavcodec/
Not everybody will be immediately familiar with our internal shorthands.
> + * codec-specific options). In such a case, it is possible to setup the
set up
> + * parent struct to export child's options. To do that, simply
a child's
> + * implement AVClass.child_next() and AVClass.child_class_next() in
> parent
in the parent
> + * Assuming that test_struct from above now also contains a child_struct
that the
> + * @code
> + * typedef struct child_struct {
> + * } child_struct;
> + * static const AVOption child_opts[] = {
> + * };
> + * static const AVClass child_class = {
> + * };
> + *
> + * void *child_next(void *obj, void *prev)
> + * {
> + * }
> + * const AVClass child_class_next(const AVClass *prev)
> + * {
> + * }
> + * @endcode
Again, I think some blank lines would not hurt.
> + * Putting child_next() and child_class_next() defined above into
nit: stray double space
as defined above
> + * test_class will now make child_struct's options accessible through
s/now//
> + * From the above example it might not be clear why are both
> child_next()
> + * and child_class_next() needed. The distinction is that child_next()
why both foo and bar are needed
> + * { "flag1", "This is flag with value 16", 0, AV_OPT_TYPE_CONST, { 16
> }, 0, 0, "test_unit" },
a flag?
> + * @section avoptions_use Using AVOptions
> + * This section deals with accessing options in an AVOptions-enabled struct.
> + * Such structs in Libav are e.g. AVCodecContext in lavc or AVFormatContext
> in
> + * lavf.
libavcodec/libavformat
> + * Situation is more complicated with nesting. An AVOptions-enabled struct
> may
The situation
> + * have AVOptions-enabled children. Passing AV_OPT_SEARCH_CHILDREN flag to
Passing the
> + * av_opt_find() will make it search recursively in children too.
will make the function search children recursively.
> + * For enumerating there are basically two cases. First is when you want to
> get
The first
> + * @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
is enough. For
> + * non-string type options it will parse the string according to the option
it?
> + * Similarly av_opt_get() will read any option type and convert it to a
> string
> + * which will be returned. Don't forget that the string is allocated, so you
Avoid short forms with apostrophes in written English.
> + * 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 allows to set some options
> + * that can't be set otherwise, since e.g. the input file format isn't known
> + * before the file is actually opened.
same
Diego
_______________________________________________
libav-devel mailing list
libav-devel@libav.org
https://lists.libav.org/mailman/listinfo/libav-devel
