[VDPAU] [PATCH] Use member groups to simplify documentation
Aaron Plattner
aplattner at nvidia.com
Thu Jan 29 13:11:25 PST 2015
For lists of fields that are copied or derived from the video bitstreams, use
Doxygen member groups to document them once as a block, rather than copying the
text "Copy of the <whatever> bitstream field." all over the place. This groups
the fields together in the HTML.
Signed-off-by: Aaron Plattner <aplattner at nvidia.com>
---
include/vdpau/vdpau.h | 170 +++++++++++++++++++++-----------------------------
1 file changed, 70 insertions(+), 100 deletions(-)
diff --git a/include/vdpau/vdpau.h b/include/vdpau/vdpau.h
index b386825da4f5..71a053bc8299 100644
--- a/include/vdpau/vdpau.h
+++ b/include/vdpau/vdpau.h
@@ -2679,9 +2679,9 @@ typedef void VdpPictureInfo;
* \brief Picture parameter information for an MPEG 1 or MPEG 2
* picture.
*
- * Note: References to "copy of bitstream field" in the field descriptions
- * may refer to data literally parsed from the bitstream, or derived from
- * the bitstream using a mechanism described in the specification.
+ * Note: References to bitstream fields below may refer to data literally parsed
+ * from the bitstream, or derived from the bitstream using a mechanism described
+ * in the specification.
*/
typedef struct {
/**
@@ -2697,45 +2697,38 @@ typedef struct {
/** Number of slices in the bitstream provided. */
uint32_t slice_count;
- /** Copy of the MPEG bitstream field. */
+ /** \name MPEG bitstream
+ *
+ * Copies of the MPEG bitstream fields.
+ * @{ */
uint8_t picture_structure;
- /** Copy of the MPEG bitstream field. */
uint8_t picture_coding_type;
- /** Copy of the MPEG bitstream field. */
uint8_t intra_dc_precision;
- /** Copy of the MPEG bitstream field. */
uint8_t frame_pred_frame_dct;
- /** Copy of the MPEG bitstream field. */
uint8_t concealment_motion_vectors;
- /** Copy of the MPEG bitstream field. */
uint8_t intra_vlc_format;
- /** Copy of the MPEG bitstream field. */
uint8_t alternate_scan;
- /** Copy of the MPEG bitstream field. */
uint8_t q_scale_type;
- /** Copy of the MPEG bitstream field. */
uint8_t top_field_first;
- /** Copy of the MPEG-1 bitstream field. For MPEG-2, set to 0. */
+ /** MPEG-1 only. For MPEG-2, set to 0. */
uint8_t full_pel_forward_vector;
- /** Copy of the MPEG-1 bitstream field. For MPEG-2, set to 0. */
+ /** MPEG-1 only. For MPEG-2, set to 0. */
uint8_t full_pel_backward_vector;
- /**
- * Copy of the MPEG bitstream field.
- * For MPEG-1, fill both horizontal and vertical entries.
- */
+ /** For MPEG-1, fill both horizontal and vertical entries. */
uint8_t f_code[2][2];
- /** Copy of the MPEG bitstream field, converted to raster order. */
+ /** Convert to raster order. */
uint8_t intra_quantizer_matrix[64];
- /** Copy of the MPEG bitstream field, converted to raster order. */
+ /** Convert to raster order. */
uint8_t non_intra_quantizer_matrix[64];
+ /** @} */
} VdpPictureInfoMPEG1Or2;
/**
* \brief Information about an H.264 reference frame
*
- * Note: References to "copy of bitstream field" in the field descriptions
- * may refer to data literally parsed from the bitstream, or derived from
- * the bitstream using a mechanism described in the specification.
+ * Note: References to bitstream fields below may refer to data literally parsed
+ * from the bitstream, or derived from the bitstream using a mechanism described
+ * in the specification.
*/
typedef struct {
/**
@@ -2779,9 +2772,9 @@ typedef struct {
* VdpDecoderRender may be used as reference frames. In particular,
* surfaces filled using any "put bits" API will not work.
*
- * Note: References to "copy of bitstream field" in the field descriptions
- * may refer to data literally parsed from the bitstream, or derived from
- * the bitstream using a mechanism described in the specification.
+ * Note: References to bitstream fields below may refer to data literally parsed
+ * from the bitstream, or derived from the bitstream using a mechanism described
+ * in the specification.
*
* Note: VDPAU clients must use VdpPictureInfoH264Predictive to describe the
* attributes of a frame being decoded with
@@ -2795,59 +2788,39 @@ typedef struct {
/** Will the decoded frame be used as a reference later. */
VdpBool is_reference;
- /** Copy of the H.264 bitstream field. */
+ /** \name H.264 bitstream
+ *
+ * Copies of the H.264 bitstream fields.
+ * @{ */
uint16_t frame_num;
- /** Copy of the H.264 bitstream field. */
uint8_t field_pic_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t bottom_field_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t num_ref_frames;
- /** Copy of the H.264 bitstream field. */
uint8_t mb_adaptive_frame_field_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t constrained_intra_pred_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t weighted_pred_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t weighted_bipred_idc;
- /** Copy of the H.264 bitstream field. */
uint8_t frame_mbs_only_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t transform_8x8_mode_flag;
- /** Copy of the H.264 bitstream field. */
int8_t chroma_qp_index_offset;
- /** Copy of the H.264 bitstream field. */
int8_t second_chroma_qp_index_offset;
- /** Copy of the H.264 bitstream field. */
int8_t pic_init_qp_minus26;
- /** Copy of the H.264 bitstream field. */
uint8_t num_ref_idx_l0_active_minus1;
- /** Copy of the H.264 bitstream field. */
uint8_t num_ref_idx_l1_active_minus1;
- /** Copy of the H.264 bitstream field. */
uint8_t log2_max_frame_num_minus4;
- /** Copy of the H.264 bitstream field. */
uint8_t pic_order_cnt_type;
- /** Copy of the H.264 bitstream field. */
uint8_t log2_max_pic_order_cnt_lsb_minus4;
- /** Copy of the H.264 bitstream field. */
uint8_t delta_pic_order_always_zero_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t direct_8x8_inference_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t entropy_coding_mode_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t pic_order_present_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t deblocking_filter_control_present_flag;
- /** Copy of the H.264 bitstream field. */
uint8_t redundant_pic_cnt_present_flag;
-
- /** Copy of the H.264 bitstream field, converted to raster order. */
+ /** Convert to raster order. */
uint8_t scaling_lists_4x4[6][16];
- /** Copy of the H.264 bitstream field, converted to raster order. */
+ /** Convert to raster order. */
uint8_t scaling_lists_8x8[2][64];
+ /** @} */
/** See \ref VdpPictureInfoH264 for instructions regarding this field. */
VdpReferenceFrameH264 referenceFrames[16];
@@ -2866,26 +2839,30 @@ typedef struct {
typedef struct {
/** \ref VdpPictureInfoH264 struct. */
VdpPictureInfoH264 pictureInfo;
- /** Copy of the H.264 bitstream field.
+
+ /** \name H.264 bitstream
*
+ * Copies of the H.264 bitstream fields.
+ * @{ */
+ /**
* 0 - lossless disabled
* 1 - lossless enabled
*/
uint8_t qpprime_y_zero_transform_bypass_flag;
- /** Copy of the H.264 bitstream field.
+ /**
* 0 - disabled
* 1 - enabled
*/
uint8_t separate_colour_plane_flag;
-
+ /** @} */
} VdpPictureInfoH264Predictive;
/**
* \brief Picture parameter information for a VC1 picture.
*
- * Note: References to "copy of bitstream field" in the field descriptions
- * may refer to data literally parsed from the bitstream, or derived from
- * the bitstream using a mechanism described in the specification.
+ * Note: References to bitstream fields below may refer to data literally parsed
+ * from the bitstream, or derived from the bitstream using a mechanism described
+ * in the specification.
*/
typedef struct {
/**
@@ -2906,54 +2883,56 @@ typedef struct {
/** Progressive=0, Frame-interlace=2, Field-interlace=3; see VC-1 7.1.1.15. */
uint8_t frame_coding_mode;
- /** Copy of the VC-1 bitstream field. See VC-1 6.1.5. */
+ /** \name VC-1 bitstream
+ *
+ * Copies of the VC-1 bitstream fields.
+ * @{ */
+ /** See VC-1 6.1.5. */
uint8_t postprocflag;
- /** Copy of the VC-1 bitstream field. See VC-1 6.1.8. */
+ /** See VC-1 6.1.8. */
uint8_t pulldown;
- /** Copy of the VC-1 bitstream field. See VC-1 6.1.9. */
+ /** See VC-1 6.1.9. */
uint8_t interlace;
- /** Copy of the VC-1 bitstream field. See VC-1 6.1.10. */
+ /** See VC-1 6.1.10. */
uint8_t tfcntrflag;
- /** Copy of the VC-1 bitstream field. See VC-1 6.1.11. */
+ /** See VC-1 6.1.11. */
uint8_t finterpflag;
- /** Copy of the VC-1 bitstream field. See VC-1 6.1.3. */
+ /** See VC-1 6.1.3. */
uint8_t psf;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.8. */
+ /** See VC-1 6.2.8. */
uint8_t dquant;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.3. */
+ /** See VC-1 6.2.3. */
uint8_t panscan_flag;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.4. */
+ /** See VC-1 6.2.4. */
uint8_t refdist_flag;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.11. */
+ /** See VC-1 6.2.11. */
uint8_t quantizer;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.7. */
+ /** See VC-1 6.2.7. */
uint8_t extended_mv;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.14. */
+ /** See VC-1 6.2.14. */
uint8_t extended_dmv;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.10. */
+ /** See VC-1 6.2.10. */
uint8_t overlap;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.9. */
+ /** See VC-1 6.2.9. */
uint8_t vstransform;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.5. */
+ /** See VC-1 6.2.5. */
uint8_t loopfilter;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.6. */
+ /** See VC-1 6.2.6. */
uint8_t fastuvmc;
- /** Copy of the VC-1 bitstream field. See VC-1 6.12.15. */
+ /** See VC-1 6.12.15. */
uint8_t range_mapy_flag;
- /** Copy of the VC-1 bitstream field. */
uint8_t range_mapy;
- /** Copy of the VC-1 bitstream field. See VC-1 6.2.16. */
+ /** See VC-1 6.2.16. */
uint8_t range_mapuv_flag;
- /** Copy of the VC-1 bitstream field. */
uint8_t range_mapuv;
/**
- * Copy of the VC-1 bitstream field. See VC-1 J.1.10.
+ * See VC-1 J.1.10.
* Only used by simple and main profiles.
*/
uint8_t multires;
/**
- * Copy of the VC-1 bitstream field. See VC-1 J.1.16.
+ * See VC-1 J.1.16.
* Only used by simple and main profiles.
*/
uint8_t syncmarker;
@@ -2965,10 +2944,11 @@ typedef struct {
*/
uint8_t rangered;
/**
- * Copy of the VC-1 bitstream field. See VC-1 J.1.17.
+ * See VC-1 J.1.17.
* Only used by simple and main profiles.
*/
uint8_t maxbframes;
+ /** @} */
/**
* Out-of-loop deblocking enable.
@@ -2987,9 +2967,9 @@ typedef struct {
/**
* \brief Picture parameter information for an MPEG-4 Part 2 picture.
*
- * Note: References to "copy of bitstream field" in the field descriptions
- * may refer to data literally parsed from the bitstream, or derived from
- * the bitstream using a mechanism described in the specification.
+ * Note: References to bitstream fields below may refer to data literally parsed
+ * from the bitstream, or derived from the bitstream using a mechanism described
+ * in the specification.
*/
typedef struct {
/**
@@ -3003,38 +2983,28 @@ typedef struct {
*/
VdpVideoSurface backward_reference;
- /** Copy of the bitstream field. */
+ /** \name MPEG 4 part 2 bitstream
+ *
+ * Copies of the MPEG 4 part 2 bitstream fields.
+ * @{ */
int32_t trd[2];
- /** Copy of the bitstream field. */
int32_t trb[2];
- /** Copy of the bitstream field. */
uint16_t vop_time_increment_resolution;
- /** Copy of the bitstream field. */
uint8_t vop_coding_type;
- /** Copy of the bitstream field. */
uint8_t vop_fcode_forward;
- /** Copy of the bitstream field. */
uint8_t vop_fcode_backward;
- /** Copy of the bitstream field. */
uint8_t resync_marker_disable;
- /** Copy of the bitstream field. */
uint8_t interlaced;
- /** Copy of the bitstream field. */
uint8_t quant_type;
- /** Copy of the bitstream field. */
uint8_t quarter_sample;
- /** Copy of the bitstream field. */
uint8_t short_video_header;
/** Derived from vop_rounding_type bitstream field. */
uint8_t rounding_control;
- /** Copy of the bitstream field. */
uint8_t alternate_vertical_scan_flag;
- /** Copy of the bitstream field. */
uint8_t top_field_first;
- /** Copy of the bitstream field. */
uint8_t intra_quantizer_matrix[64];
- /** Copy of the bitstream field. */
uint8_t non_intra_quantizer_matrix[64];
+ /** @} */
} VdpPictureInfoMPEG4Part2;
/**
--
2.2.2
More information about the VDPAU
mailing list