[FFmpeg-devel] [PATCH v3 22/34] avutil/opt: document AVOptionRange min_value > max_value

[Diederick Niehorster]

AVOptionRange needs a way to encode that an option is not set. Here i
provide a documentation solution. When a range is invalid (value_min >
value_max), it should be considered unset/value not available.

When querying a range of formats of an avdevice, sometimes for a given
format the queried option is not available. This is not an error as the
user is asking for a valid capability, it just doesn't always apply to
all the matching formats of the device. This cannot be communicated
through a single special value (like 0 or -1) as that has the same
problem asany special value solution. Documenting that an invalid range
means value not available allows communicating this situation without
adding a field to the AVOptionRange struct.

This further documents that an AVOptionRange denotes a single value when
value_min == value_max, and a range only when value_max > value_min.
This makes the is_range field superfluous.

Signed-off-by: Diederick Niehorster <dcnieho at gmail.com>
---
 libavutil/opt.c | 2 +-
 libavutil/opt.h | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/libavutil/opt.c b/libavutil/opt.c
index 41284d4ecd..edb2c2ca41 100644
--- a/libavutil/opt.c
+++ b/libavutil/opt.c
@@ -1865,9 +1865,9 @@ int av_opt_query_ranges_default(AVOptionRanges **ranges_arg, void *obj, const ch
     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;
+    range->is_range = field->max > field->min;
 
     switch (field->type) {
     case AV_OPT_TYPE_BOOL:
diff --git a/libavutil/opt.h b/libavutil/opt.h
index c2329e5589..3c64e8d3a5 100644
--- a/libavutil/opt.h
+++ b/libavutil/opt.h
@@ -313,6 +313,11 @@ typedef struct AVOptionRange {
      * 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.
+     * If value_min  < value_max, the struct encodes a range.
+     * If value_min == value_max, the struct encodes a single value.
+     * If value_min  > value_max, the range is empty (a value is not available).
+     *                            Good sentinel values to use when a range is empty
+     *                            are value_min=0, value_max=-1, but this is not required.
      */
     double value_min, value_max;
     /**
-- 
2.28.0.windows.1