diff --git a/doc/APIchanges b/doc/APIchanges index b8d8b8599d..8b946e2dd2 100644 --- a/doc/APIchanges +++ b/doc/APIchanges @@ -15,6 +15,10 @@ libavutil: 2012-10-22 API changes, most recent first: +2014-04-xx - xxxxxxx - lavu 52.72.100 - opt.h + Add AV_OPT_MULTI_COMPONENT_RANGE define to allow return + multi-component option ranges. + 2014-03-xx - xxxxxxx - lavu 52.70.100 - mem.h Add av_dynarray_add_nofree() function. diff --git a/libavutil/opt.c b/libavutil/opt.c index 428c4e5839..cffa5a6a24 100644 --- a/libavutil/opt.c +++ b/libavutil/opt.c @@ -1514,6 +1514,7 @@ void *av_opt_ptr(const AVClass *class, void *obj, const char *name) int av_opt_query_ranges(AVOptionRanges **ranges_arg, void *obj, const char *key, int flags) { + int ret; const AVClass *c = *(AVClass**)obj; int (*callback)(AVOptionRanges **, void *obj, const char *key, int flags) = NULL; @@ -1523,7 +1524,13 @@ int av_opt_query_ranges(AVOptionRanges **ranges_arg, void *obj, const char *key, if (!callback) callback = av_opt_query_ranges_default; - return callback(ranges_arg, obj, key, flags); + ret = callback(ranges_arg, obj, key, flags); + if (ret >= 0) { + if (!(flags & AV_OPT_MULTI_COMPONENT_RANGE)) + ret = 1; + (*ranges_arg)->nb_components = ret; + } + return ret; } int av_opt_query_ranges_default(AVOptionRanges **ranges_arg, void *obj, const char *key, int flags) @@ -1544,6 +1551,7 @@ int av_opt_query_ranges_default(AVOptionRanges **ranges_arg, void *obj, const ch ranges->range = range_array; ranges->range[0] = range; ranges->nb_ranges = 1; + ranges->nb_components = 1; range->is_range = 1; range->value_min = field->min; range->value_max = field->max; @@ -1587,7 +1595,7 @@ int av_opt_query_ranges_default(AVOptionRanges **ranges_arg, void *obj, const ch } *ranges_arg = ranges; - return 0; + return 1; fail: av_free(ranges); av_free(range); @@ -1600,7 +1608,7 @@ void av_opt_freep_ranges(AVOptionRanges **rangesp) int i; AVOptionRanges *ranges = *rangesp; - for (i = 0; i < ranges->nb_ranges; i++) { + for (i = 0; i < ranges->nb_ranges * ranges->nb_components; i++) { AVOptionRange *range = ranges->range[i]; av_freep(&range->str); av_freep(&ranges->range[i]); diff --git a/libavutil/opt.h b/libavutil/opt.h index cd1b18e4c0..6a1ae4354a 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -313,17 +313,67 @@ typedef struct AVOption { */ typedef struct AVOptionRange { const char *str; - double value_min, value_max; ///< For string ranges this represents the min/max length, for dimensions this represents the min/max pixel count - double component_min, component_max; ///< For string this represents the unicode range for chars, 0-127 limits to ASCII - int is_range; ///< if set to 1 the struct encodes a range, if set to 0 a single value + /** + * 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. + */ + int is_range; } AVOptionRange; /** - * List of AVOptionRange structs + * List of AVOptionRange structs. */ typedef struct AVOptionRanges { + /** + * Array of option ranges. + * + * Most of option types use just one component. + * Following describes multi-component option types: + * + * AV_OPT_TYPE_IMAGE_SIZE: + * component index 0: range of pixel count (width * height). + * component index 1: range of width. + * component index 2: range of height. + * + * @note To obtain multi-component version of this structure, user must + * provide AV_OPT_MULTI_COMPONENT_RANGE to av_opt_query_ranges or + * av_opt_query_ranges_default function. + * + * Multi-component range can be read as in following example: + * + * @code + * int range_index, component_index; + * AVOptionRanges *ranges; + * AVOptionRange *range[3]; //may require more than 3 in the future. + * av_opt_query_ranges(&ranges, obj, key, AV_OPT_MULTI_COMPONENT_RANGE); + * for (range_index = 0; range_index < ranges->nb_ranges; range_index++) { + * for (component_index = 0; component_index < ranges->nb_components; component_index++) + * range[component_index] = ranges->range[ranges->nb_ranges * component_index + range_index]; + * //do something with range here. + * } + * av_opt_freep_ranges(&ranges); + * @endcode + */ AVOptionRange **range; + /** + * Number of ranges per component. + */ int nb_ranges; + /** + * Number of componentes. + */ + int nb_components; } AVOptionRanges; @@ -558,6 +608,13 @@ int av_opt_eval_q (void *obj, const AVOption *o, const char *val, AVRational */ #define AV_OPT_SEARCH_FAKE_OBJ 0x0002 +/** + * Allows av_opt_query_ranges and av_opt_query_ranges_default to return more than + * one component for certain option types. + * @see AVOptionRanges for details. + */ +#define AV_OPT_MULTI_COMPONENT_RANGE 0x1000 + /** * Look for an option in an object. Consider only options which * have all the specified flags set. @@ -739,10 +796,11 @@ void av_opt_freep_ranges(AVOptionRanges **ranges); * * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance + * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges * * The result must be freed with av_opt_freep_ranges. * - * @return >= 0 on success, a negative errro code otherwise + * @return number of compontents returned on success, a negative errro code otherwise */ int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags); @@ -754,10 +812,11 @@ int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags * * @param flags is a bitmask of flags, undefined flags should not be set and should be ignored * AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance + * AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component, @see AVOptionRanges * * The result must be freed with av_opt_free_ranges. * - * @return >= 0 on success, a negative errro code otherwise + * @return number of compontents returned on success, a negative errro code otherwise */ int av_opt_query_ranges_default(AVOptionRanges **, void *obj, const char *key, int flags); diff --git a/libavutil/version.h b/libavutil/version.h index 73bdfabd4b..9bf499416e 100644 --- a/libavutil/version.h +++ b/libavutil/version.h @@ -56,7 +56,7 @@ */ #define LIBAVUTIL_VERSION_MAJOR 52 -#define LIBAVUTIL_VERSION_MINOR 71 +#define LIBAVUTIL_VERSION_MINOR 72 #define LIBAVUTIL_VERSION_MICRO 100 #define LIBAVUTIL_VERSION_INT AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \