avutil/stereo3d: Fill out stereo info provided by Vision Pro files

Based on what is in the files themselves, and what the API provides
to users.

URLs:
  * https://developer.apple.com/documentation/videotoolbox/kvtcompressionpropertykey_heroeye
  * https://developer.apple.com/documentation/videotoolbox/kvtcompressionpropertykey_stereocamerabaseline
  * https://developer.apple.com/documentation/videotoolbox/kvtcompressionpropertykey_horizontaldisparityadjustment
  * https://developer.apple.com/documentation/coremedia/kcmformatdescriptionextension_horizontalfieldofview

Signed-off-by: Derek Buitenhuis <derek.buitenhuis@gmail.com>

4 files changed, 140 insertions, 1 deletions

diff --git a/doc/APIchanges b/doc/APIchanges
index fcb20872a6..6a470702b6 100644
--- a/doc/APIchanges
+++ b/doc/APIchanges
@@ -2,6 +2,15 @@ The last version increases of all libraries were on 2024-03-07
 
 API changes, most recent first:
 
+2024-06-18 - xxxxxxxxxx - lavu 59.24.100 - stereo3d.h
+  Add primary_eye, baseline, horizontal_disparity_adjustment, and
+  horizontal_field_of_view fields to AVStereo3D.
+  Add AVStereo3DPrimaryEye.
+  Add av_stereo3d_view_name.
+  Add av_stereo3d_view_from_name.
+  Add av_stereo3d_primary_eye_name.
+  Add av_stereo3d_primary_eye_from_name.
+
 2024-06-18 - xxxxxxxxxx - lavu 59.23.100 - spherical.h
   Add AV_SPHERICAL_HALF_EQUIRECTANGULAR, AV_SPHERICAL_RECTILINEAR, and
   AV_SPHERICAL_FISHEYE values to AVSphericalProjection, and initialize
diff --git a/libavutil/stereo3d.c b/libavutil/stereo3d.c
index 9c29ab01b5..a40a9439bb 100644
--- a/libavutil/stereo3d.c
+++ b/libavutil/stereo3d.c
@@ -55,6 +55,18 @@ static const char * const stereo3d_type_names[] = {
     [AV_STEREO3D_COLUMNS]             = "interleaved columns",
 };
 
+static const char * const stereo3d_view_names[] = {
+    [AV_STEREO3D_VIEW_PACKED] = "packed",
+    [AV_STEREO3D_VIEW_LEFT]   = "left",
+    [AV_STEREO3D_VIEW_RIGHT]  = "right",
+};
+
+static const char * const stereo3d_primary_eye_names[] = {
+    [AV_PRIMARY_EYE_NONE]  = "none",
+    [AV_PRIMARY_EYE_LEFT]  = "left",
+    [AV_PRIMARY_EYE_RIGHT] = "right",
+};
+
 const char *av_stereo3d_type_name(unsigned int type)
 {
     if (type >= FF_ARRAY_ELEMS(stereo3d_type_names))
@@ -74,3 +86,43 @@ int av_stereo3d_from_name(const char *name)
 
     return -1;
 }
+
+const char *av_stereo3d_view_name(unsigned int view)
+{
+    if (view >= FF_ARRAY_ELEMS(stereo3d_view_names))
+        return "unknown";
+
+    return stereo3d_view_names[view];
+}
+
+int av_stereo3d_view_from_name(const char *name)
+{
+    int i;
+
+    for (i = 0; i < FF_ARRAY_ELEMS(stereo3d_view_names); i++) {
+        if (av_strstart(name, stereo3d_view_names[i], NULL))
+            return i;
+    }
+
+    return -1;
+}
+
+const char *av_stereo3d_primary_eye_name(unsigned int eye)
+{
+    if (eye >= FF_ARRAY_ELEMS(stereo3d_primary_eye_names))
+        return "unknown";
+
+    return stereo3d_primary_eye_names[eye];
+}
+
+int av_stereo3d_primary_eye_from_name(const char *name)
+{
+    int i;
+
+    for (i = 0; i < FF_ARRAY_ELEMS(stereo3d_primary_eye_names); i++) {
+        if (av_strstart(name, stereo3d_primary_eye_names[i], NULL))
+            return i;
+    }
+
+    return -1;
+}
diff --git a/libavutil/stereo3d.h b/libavutil/stereo3d.h
index 3aab959b79..00a5c3900e 100644
--- a/libavutil/stereo3d.h
+++ b/libavutil/stereo3d.h
@@ -159,6 +159,26 @@ enum AVStereo3DView {
 };
 
 /**
+ * List of possible primary eyes.
+ */
+enum AVStereo3DPrimaryEye {
+    /**
+     * Neither eye.
+     */
+    AV_PRIMARY_EYE_NONE,
+
+    /**
+     * Left eye.
+     */
+    AV_PRIMARY_EYE_LEFT,
+
+    /**
+     * Right eye
+     */
+    AV_PRIMARY_EYE_RIGHT,
+};
+
+/**
  * Inverted views, Right/Bottom represents the left view.
  */
 #define AV_STEREO3D_FLAG_INVERT     (1 << 0)
@@ -185,6 +205,28 @@ typedef struct AVStereo3D {
      * Determines which views are packed.
      */
     enum AVStereo3DView view;
+
+    /**
+     * Which eye is the primary eye when rendering in 2D.
+     */
+    enum AVStereo3DPrimaryEye primary_eye;
+
+    /**
+     * The distance between the centres of the lenses of the camera system,
+     * in micrometers. Zero if unset.
+     */
+    uint32_t baseline;
+
+    /**
+     * Relative shift of the left and right images, which changes the zero parallax plane.
+     * Range is -1.0 to 1.0. Zero if unset.
+     */
+    AVRational horizontal_disparity_adjustment;
+
+    /**
+     * Horizontal field of view in thousanths of a degree. Zero if unset.
+     */
+    uint32_t horizontal_field_of_view;
 } AVStereo3D;
 
 /**
@@ -223,6 +265,42 @@ const char *av_stereo3d_type_name(unsigned int type);
 int av_stereo3d_from_name(const char *name);
 
 /**
+ * Provide a human-readable name of a given stereo3d view.
+ *
+ * @param type The input stereo3d view value.
+ *
+ * @return The name of the stereo3d view value, or "unknown".
+ */
+const char *av_stereo3d_view_name(unsigned int view);
+
+/**
+ * Get the AVStereo3DView form a human-readable name.
+ *
+ * @param name The input string.
+ *
+ * @return The AVStereo3DView value, or -1 if not found.
+ */
+int av_stereo3d_view_from_name(const char *name);
+
+/**
+ * Provide a human-readable name of a given stereo3d primary eye.
+ *
+ * @param type The input stereo3d primary eye value.
+ *
+ * @return The name of the stereo3d primary eye value, or "unknown".
+ */
+const char *av_stereo3d_primary_eye_name(unsigned int eye);
+
+/**
+ * Get the AVStereo3DPrimaryEye form a human-readable name.
+ *
+ * @param name The input string.
+ *
+ * @return The AVStereo3DPrimaryEye value, or -1 if not found.
+ */
+int av_stereo3d_primary_eye_from_name(const char *name);
+
+/**
  * @}
  */
 
diff --git a/libavutil/version.h b/libavutil/version.h
index 7df546ee22..8044fd3935 100644
--- a/libavutil/version.h
+++ b/libavutil/version.h
@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  59
-#define LIBAVUTIL_VERSION_MINOR  23
+#define LIBAVUTIL_VERSION_MINOR  24
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \