avutil/channel_layout: add a helper function to get the ambisonic order of a layout

Signed-off-by: James Almer <jamrial@gmail.com>

doc/APIchanges

@@ -2,6 +2,9 @@ The last version increases of all libraries were on 2024-03-07
 
 API changes, most recent first:
 
+2024-05-23 - xxxxxxxxxx - lavu 59.20.100 - channel_layout.h
+  Add av_channel_layout_ambisonic_order().
+
 2024-05-xx - xxxxxxxxxx - lavu 59.19.100 - hwcontext_qsv.h
   Add AVQSVFramesContext.info
 

libavutil/channel_layout.c

@@ -473,15 +473,14 @@ static int has_channel_names(const AVChannelLayout *channel_layout)
     return 0;
 }
 
-/**
- * If the layout is n-th order standard-order ambisonic, with optional
- * extra non-diegetic channels at the end, return the order.
- * Return a negative error code otherwise.
- */
-static int ambisonic_order(const AVChannelLayout *channel_layout)
+int av_channel_layout_ambisonic_order(const AVChannelLayout *channel_layout)
 {
     int i, highest_ambi, order;
 
+    if (channel_layout->order != AV_CHANNEL_ORDER_AMBISONIC &&
+        channel_layout->order != AV_CHANNEL_ORDER_CUSTOM)
+        return AVERROR(EINVAL);
+
     highest_ambi = -1;
     if (channel_layout->order == AV_CHANNEL_ORDER_AMBISONIC)
         highest_ambi = channel_layout->nb_channels - av_popcount64(channel_layout->u.mask) - 1;
@@ -536,7 +535,7 @@ static enum AVChannelOrder canonical_order(AVChannelLayout *channel_layout)
     if (masked_description(channel_layout, 0) > 0)
         return AV_CHANNEL_ORDER_NATIVE;
 
-    order = ambisonic_order(channel_layout);
+    order = av_channel_layout_ambisonic_order(channel_layout);
     if (order >= 0 && masked_description(channel_layout, (order + 1) * (order + 1)) >= 0)
         return AV_CHANNEL_ORDER_AMBISONIC;
 
@@ -551,7 +550,7 @@ static enum AVChannelOrder canonical_order(AVChannelLayout *channel_layout)
 static int try_describe_ambisonic(AVBPrint *bp, const AVChannelLayout *channel_layout)
 {
     int nb_ambi_channels;
-    int order = ambisonic_order(channel_layout);
+    int order = av_channel_layout_ambisonic_order(channel_layout);
     if (order < 0)
         return order;
 
@@ -945,7 +944,7 @@ int av_channel_layout_retype(AVChannelLayout *channel_layout, enum AVChannelOrde
         if (channel_layout->order == AV_CHANNEL_ORDER_CUSTOM) {
             int64_t mask;
             int nb_channels = channel_layout->nb_channels;
-            int order = ambisonic_order(channel_layout);
+            int order = av_channel_layout_ambisonic_order(channel_layout);
             if (order < 0)
                 return AVERROR(ENOSYS);
             mask = masked_description(channel_layout, (order + 1) * (order + 1));

libavutil/channel_layout.h

@@ -679,6 +679,16 @@ int av_channel_layout_check(const AVChannelLayout *channel_layout);
  */
 int av_channel_layout_compare(const AVChannelLayout *chl, const AVChannelLayout *chl1);
 
+/**
+ * Return the order if the layout is n-th order standard-order ambisonic.
+ * The presence of optional extra non-diegetic channels at the end is not taken
+ * into account.
+ *
+ * @param channel_layout input channel layout
+ * @return the order of the layout, a negative error code otherwise.
+ */
+int av_channel_layout_ambisonic_order(const AVChannelLayout *channel_layout);
+
 /**
  * The conversion must be lossless.
  */

libavutil/version.h

@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  59
-#define LIBAVUTIL_VERSION_MINOR  19
+#define LIBAVUTIL_VERSION_MINOR  20
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \