docs(libvmaf): close 5 documentation gaps in public headers

changelog.d/changed/libvmaf-public-headers-docs.md

@@ -0,0 +1,17 @@
+- Doc-only sweep of `core/include/libvmaf/`:
+  - `libvmaf.h` — corrected the `@param` order on
+    `vmaf_score_at_index` to match the function signature
+    (`score` before `index`); documented full `cpumask` bit layout
+    per architecture (incl. arm64 NEON bit 0 and SVE2 bit 1);
+    documented `gpumask` as "any non-zero disables CUDA + SYCL,
+    HIP is exempt" per ADR-0530; added a hazard note on
+    `VMAF_POOL_METHOD_NB` clarifying it is a count sentinel, not a
+    stable API value.
+  - `picture.h` — added doxygen field documentation for every
+    `VmafPicture` member (pix_fmt, bpc, w[3], h[3], stride[3],
+    data[3], ref, priv) and a struct-level brief describing
+    ownership transfer semantics.
+  - `dnn.h` — deduplicated the `vmaf_dnn_session_attached_ep()`
+    stable-string list (was listing `"OpenVINO:CPU"` and
+    `"OpenVINO:GPU"` twice).
+  No ABI / behaviour change.

core/include/libvmaf/dnn.h

@@ -334,6 +334,7 @@ VMAF_EXPORT void vmaf_dnn_session_close(VmafDnnSession *sess);
 /**
  * Name of the ONNX Runtime execution provider that actually bound to the
  * session. Useful for diagnostics and for asserting AUTO-chain behaviour
+<<<<<<< ours
  * in tests. Stable strings: "CPU", "CUDA", "OpenVINO:GPU", "OpenVINO:CPU",
  * "CoreML", "CoreML:ANE", "CoreML:GPU", "CoreML:CPU", "OpenVINO:NPU",
  * "OpenVINO:CPU", "OpenVINO:GPU", "ROCm". Returns NULL if @p sess is NULL
@@ -343,6 +344,12 @@ VMAF_EXPORT void vmaf_dnn_session_close(VmafDnnSession *sess);
  *
  * @return NUL-terminated provider tag, or NULL if @p sess is NULL or
  *         libvmaf was built without DNN support.
+=======
+ * in tests. Stable strings: "CPU", "CUDA", "ROCm", "CoreML", "CoreML:ANE",
+ * "CoreML:GPU", "CoreML:CPU", "OpenVINO:CPU", "OpenVINO:GPU",
+ * "OpenVINO:NPU". Returns NULL if @p sess is NULL or libvmaf was built
+ * without DNN support. Lifetime: owned by @p sess.
+>>>>>>> theirs
  */
 VMAF_EXPORT const char *vmaf_dnn_session_attached_ep(VmafDnnSession *sess);
 

core/include/libvmaf/libvmaf.h

@@ -97,6 +97,7 @@
         VMAF_OUTPUT_FORMAT_SUB,
     };
 
+<<<<<<< ours
     enum VmafPoolingMethod {
         VMAF_POOL_METHOD_UNKNOWN = 0,
         VMAF_POOL_METHOD_MIN,
@@ -105,6 +106,25 @@
         VMAF_POOL_METHOD_HARMONIC_MEAN,
         VMAF_POOL_METHOD_NB
     };
+=======
+enum VmafPoolingMethod {
+    VMAF_POOL_METHOD_UNKNOWN = 0,
+    VMAF_POOL_METHOD_MIN,
+    VMAF_POOL_METHOD_MAX,
+    VMAF_POOL_METHOD_MEAN,
+    VMAF_POOL_METHOD_HARMONIC_MEAN,
+    /**
+     * Count sentinel — exposed for backwards compatibility with callers
+     * that historically iterated `[0, VMAF_POOL_METHOD_NB)`. NOT a stable
+     * API value: its numeric value increases whenever a new pooling
+     * method is appended below it, so do not switch on it, persist it,
+     * or pass it across an ABI boundary. New code should switch on the
+     * named values and treat any unknown discriminant as
+     * `VMAF_POOL_METHOD_UNKNOWN`.
+     */
+    VMAF_POOL_METHOD_NB
+};
+>>>>>>> theirs
 
     /**
  * @struct VmafConfiguration
@@ -120,16 +140,32 @@
  *                    inaccurate results. For more detail, see
  *                    https://github.com/Netflix/vmaf/issues/1214
  *
- * @param cpumask     Restrict permitted CPU instruction sets.
- *                    if cpumask & 1:  disable SSE2 / disable NEON (on arm64)
- *                    if cpumask & 2:  disable SSE3/SSSE3
- *                    if cpumask & 4:  disable SSE4.1
- *                    if cpumask & 8:  disable AVX2
- *                    if cpumask & 16: disable AVX512
- *                    if cpumask & 32: disable AVX512ICL
- *
- * @param gpumask     Restrict permitted GPU operations.
- *                    if gpumask: disable CUDA
+ * @param cpumask     Restrict permitted CPU instruction sets. The bit
+ *                    layout is architecture-specific — only the bits
+ *                    listed for the host architecture take effect; bits
+ *                    set for a different architecture are silently
+ *                    ignored.
+ *
+ *                    On x86 / x86_64:
+ *                      if cpumask & 1:  disable SSE2
+ *                      if cpumask & 2:  disable SSE3 / SSSE3
+ *                      if cpumask & 4:  disable SSE4.1
+ *                      if cpumask & 8:  disable AVX2
+ *                      if cpumask & 16: disable AVX512
+ *                      if cpumask & 32: disable AVX512ICL
+ *
+ *                    On arm64 / aarch64:
+ *                      if cpumask & 1:  disable NEON (forces scalar)
+ *                      if cpumask & 2:  disable SVE2
+ *
+ * @param gpumask     Restrict permitted GPU operations. Any non-zero
+ *                    value disables the GPU feature-extractor selection
+ *                    for both the CUDA and SYCL backends (the runtime
+ *                    falls back to the CPU implementation). The HIP
+ *                    backend is host-pic and is not gated by gpumask —
+ *                    its activation is controlled solely by whether a
+ *                    HIP state pointer was imported via
+ *                    `vmaf_hip_import_state()`. ADR-0530.
  */
     typedef struct VmafConfiguration {
         enum VmafLogLevel log_level; /**< Logger verbosity. */
@@ -273,9 +309,9 @@
  *
  * @param model  Opaque model context.
  *
- * @param index  Picture index.
+ * @param score  Predicted score (out).
  *
- * @param score  Predicted score.
+ * @param index  Picture index.
  *
  *
  * @return 0 on success, or < 0 (a negative errno code) on error.

core/include/libvmaf/picture.h

@@ -88,6 +88,7 @@
 >>>>>>> theirs
     typedef struct VmafRef VmafRef;
 
+<<<<<<< ours
     /**
  * Frame the library scores. Populated by the caller (or by
  * `vmaf_picture_alloc`); released with `vmaf_picture_unref`.
@@ -102,6 +103,28 @@
         VmafRef *ref;                 /**< Internal refcount cookie; do not touch. */
         void *priv;                   /**< Opaque slot for caller-owned metadata. */
     } VmafPicture;
+=======
+/**
+ * @struct VmafPicture
+ * @brief Reference-counted planar picture passed to feature extractors.
+ *
+ * Allocated by `vmaf_picture_alloc()` (or obtained from the preallocated
+ * pool via `vmaf_fetch_preallocated_picture()`) and released by
+ * `vmaf_picture_unref()`. Ownership transfers to the `VmafContext` on
+ * `vmaf_read_pictures()`; do not free / unref a picture after handing it
+ * to the context.
+ */
+typedef struct VmafPicture {
+    enum VmafPixelFormat pix_fmt; /**< planar pixel format (see VmafPixelFormat). */
+    unsigned bpc;                 /**< bits per component, typically 8, 10, 12, or 16. */
+    unsigned w[3];                /**< per-plane width in samples; index 0 = Y, 1 = U, 2 = V. */
+    unsigned h[3];                /**< per-plane height in samples; same indexing as @ref w. */
+    ptrdiff_t stride[3];          /**< per-plane row stride in **bytes** (>= w * sample_size). */
+    void *data[3]; /**< per-plane sample buffer; uint8_t* when bpc <= 8, uint16_t* otherwise. */
+    VmafRef *ref;  /**< opaque refcount handle owned by libvmaf — do not touch. */
+    void *priv;    /**< opaque per-picture private slot owned by libvmaf — do not touch. */
+} VmafPicture;
+>>>>>>> theirs
 
     /**
 <<<<<<< ours