headers: reorder and improve the doxy for some fields

include/dav1d/data.h

@@ -37,7 +37,7 @@ typedef struct Dav1dData {
     const uint8_t *data; ///< data pointer
     size_t sz; ///< data size
     struct Dav1dRef *ref; ///< allocation origin
-    Dav1dDataProps m;
+    Dav1dDataProps m; ///< user provided metadata passed to the output picture
 } Dav1dData;
 
 /**

include/dav1d/dav1d.h

@@ -61,11 +61,11 @@ typedef struct Dav1dLogger {
 typedef struct Dav1dSettings {
     int n_frame_threads;
     int n_tile_threads;
-    Dav1dPicAllocator allocator;
-    Dav1dLogger logger;
     int apply_grain;
     int operating_point; ///< select an operating point for scalable AV1 bitstreams (0 - 31)
     int all_layers; ///< output all spatial layers of a scalable AV1 biststream
+    Dav1dPicAllocator allocator;
+    Dav1dLogger logger;
 } Dav1dSettings;
 
 /**

include/dav1d/headers.h

@@ -194,6 +194,14 @@ typedef struct Dav1dSequenceHeader {
     enum Dav1dTransferCharacteristics trc; ///< transfer characteristics (av1)
     enum Dav1dMatrixCoefficients mtrx; ///< matrix coefficients (av1)
     enum Dav1dChromaSamplePosition chr; ///< chroma sample position (av1)
+    /**
+     * 0, 1 and 2 mean 8, 10 or 12 bits/component, respectively. This is not
+     * exactly the same as 'hbd' from the spec; the spec's hbd distinguishes
+     * between 8 (0) and 10-12 (1) bits/component, and another element
+     * (twelve_bit) to distinguish between 10 and 12 bits/component. To get
+     * the spec's hbd, use !!our_hbd, and to get twelve_bit, use hbd == 2.
+     */
+    int hbd;
     /**
      * Pixel data uses JPEG pixel range ([0,255] for 8bits) instead of
      * MPEG pixel range ([16,235] for 8bits luma, [16,240] for 8bits chroma).
@@ -246,14 +254,6 @@ typedef struct Dav1dSequenceHeader {
     int super_res;
     int cdef;
     int restoration;
-    /**
-     * 0, 1 and 2 mean 8, 10 or 12 bits/component, respectively. This is not
-     * exactly the same as 'hbd' from the spec; the spec's hbd distinguishes
-     * between 8 (0) and 10-12 (1) bits/component, and another element
-     * (twelve_bit) to distinguish between 10 and 12 bits/component. To get
-     * the spec's hbd, use !!our_hbd, and to get twelve_bit, use hbd == 2.
-     */
-    int hbd;
     int ss_hor, ss_ver, monochrome;
     int color_description_present;
     int separate_uv_delta_q;

include/dav1d/picture.h

@@ -61,13 +61,23 @@ typedef struct Dav1dPicture {
 
     Dav1dPictureParameters p;
     Dav1dDataProps m;
-    struct Dav1dRef *frame_hdr_ref, *seq_hdr_ref, *ref; ///< allocation origins
-
-    void *allocator_data; ///< pointer managed by the allocator
 
+    /**
+     * High Dynamic Range Content Light Level metadata applying to this picture,
+     * as defined in section 5.8.3 and 6.7.3
+     */
     Dav1dContentLightLevel *content_light;
+    /**
+     * High Dynamic Range Mastering Display Color Volume metadata applying to
+     * this picture, as defined in section 5.8.4 and 6.7.4
+     */
     Dav1dMasteringDisplay *mastering_display;
-    struct Dav1dRef *content_light_ref, *mastering_display_ref;
+
+    struct Dav1dRef *frame_hdr_ref, *seq_hdr_ref; ///< Frame parameter allocation origins
+    struct Dav1dRef *content_light_ref, *mastering_display_ref; ///< Metadata allocation origins
+    struct Dav1dRef *ref; ///< Frame data allocation origin
+
+    void *allocator_data; ///< pointer managed by the allocator
 } Dav1dPicture;
 
 typedef struct Dav1dPicAllocator {
@@ -89,8 +99,10 @@ typedef struct Dav1dPicAllocator {
      *             a custom pointer that will be passed to
      *             release_picture_callback().
      * @param cookie Custom pointer passed to all calls.
-    *
-    * @return 0 on success. A negative errno value on error.
+     *
+     * @note No fields other than data, stride and allocator_data must be filled
+     *       by this callback.
+     * @return 0 on success. A negative errno value on error.
      */
     int (*alloc_picture_callback)(Dav1dPicture *pic, void *cookie);
     /**