[VDPAU] [PATCH] Use member groups to simplify documentation
Christian König
christian.koenig at amd.com
Fri Jan 30 01:09:56 PST 2015
Am 29.01.2015 um 22:11 schrieb Aaron Plattner:
> 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>
Haven't looked at the resulting Doxygen output, but in general it looks
sane to me.
Patch is Reviewed-by: Christian König <christian.koenig at amd.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;
>
> /**
More information about the VDPAU
mailing list