From e6212219ed29fecdc0640bc91fa438290ae8ae93 Mon Sep 17 00:00:00 2001 From: Edward Hervey Date: Mon, 19 Sep 2011 13:41:44 +0200 Subject: [PATCH] codecparsinglibs: Doc and indentation fixes --- gst-libs/gst/codecparsers/gsth264parser.c | 18 +-- gst-libs/gst/codecparsers/gsth264parser.h | 35 +++--- .../gst/codecparsers/gstmpegvideoparser.c | 48 ++++---- .../gst/codecparsers/gstmpegvideoparser.h | 111 ++++++++++-------- 4 files changed, 114 insertions(+), 98 deletions(-) diff --git a/gst-libs/gst/codecparsers/gsth264parser.c b/gst-libs/gst/codecparsers/gsth264parser.c index 237190c16e..b496c0fef1 100644 --- a/gst-libs/gst/codecparsers/gsth264parser.c +++ b/gst-libs/gst/codecparsers/gsth264parser.c @@ -1136,7 +1136,7 @@ gst_h264_nal_parser_new (void) /** * gst_h264_nal_parser_free: - * @nalparser the #GstH264NalParser to free + * @nalparser: the #GstH264NalParser to free * * Frees @nalparser and sets it to %NULL */ @@ -1270,7 +1270,7 @@ gst_h264_parser_identify_nalu_avc (GstH264NalParser * nalparser, * @nalparser: a #GstH264NalParser * @nalu: The #GstH264NalUnit to parse * - * This function should be called in the case you don't need to + * This function should be called in the case one doesn't need to * parse a specific structure. It is necessary to do so to make * sure @nalparser is up to date. * @@ -1296,8 +1296,8 @@ gst_h264_parser_parse_nal (GstH264NalParser * nalparser, GstH264NalUnit * nalu) /** * gst_h264_parser_parse_sps: * @nalparser: a #GstH264NalParser - * @nalu: The #GST_H264_NAL_SPS #GstH264NalUnit you want to parse - * @slice: The #GstH264SPS to fill. + * @nalu: The #GST_H264_NAL_SPS #GstH264NalUnit to parse + * @sps: The #GstH264SPS to fill. * @parse_vui_params: Whether to parse the vui_params or not * * Parses @data, and fills the @sps structure. @@ -1324,7 +1324,7 @@ gst_h264_parser_parse_sps (GstH264NalParser * nalparser, GstH264NalUnit * nalu, /** * gst_h264_parse_sps: - * @nalu: The #GST_H264_NAL_SPS #GstH264NalUnit you want to parse + * @nalu: The #GST_H264_NAL_SPS #GstH264NalUnit to parse * @sps: The #GstH264SPS to fill. * @parse_vui_params: Whether to parse the vui_params or not * @@ -1502,7 +1502,7 @@ error: /** * gst_h264_parse_pps: * @nalparser: a #GstH264NalParser - * @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit you want to parse + * @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit to parse * @pps: The #GstH264PPS to fill. * * Parses @data, and fills the @pps structure. @@ -1631,7 +1631,7 @@ error: /** * gst_h264_parser_parse_pps: * @nalparser: a #GstH264NalParser - * @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit you want to parse + * @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit to parse * @pps: The #GstH264PPS to fill. * * Parses @data, and fills the @pps structure. @@ -1657,7 +1657,7 @@ gst_h264_parser_parse_pps (GstH264NalParser * nalparser, /** * gst_h264_parser_parse_slice_hdr: * @nalparser: a #GstH264NalParser - * @nalu: The #GST_H264_NAL_SLICE #GstH264NalUnit you want to parse + * @nalu: The #GST_H264_NAL_SLICE #GstH264NalUnit to parse * @slice: The #GstH264SliceHdr to fill. * @parse_pred_weight_table: Whether to parse the pred_weight_table or not * @parse_dec_ref_pic_marking: Whether to parse the dec_ref_pic_marking or not @@ -1834,7 +1834,7 @@ error: /** * gst_h264_parser_parse_sei: * @nalparser: a #GstH264NalParser - * @nalu: The #GST_H264_NAL_SEI #GstH264NalUnit you want to parse + * @nalu: The #GST_H264_NAL_SEI #GstH264NalUnit to parse * @sei: The #GstH264SEIMessage to fill. * * Parses @data, and fills the @sei structures. diff --git a/gst-libs/gst/codecparsers/gsth264parser.h b/gst-libs/gst/codecparsers/gsth264parser.h index 84577f686b..ea808a6770 100644 --- a/gst-libs/gst/codecparsers/gsth264parser.h +++ b/gst-libs/gst/codecparsers/gsth264parser.h @@ -45,19 +45,19 @@ G_BEGIN_DECLS /** * GstH264NalUnitType: - * @GST_H264_NAL_UNKNOWN: Unkonw nal type + * @GST_H264_NAL_UNKNOWN: Unknown nal type * @GST_H264_NAL_SLICE: Slice nal * @GST_H264_NAL_SLICE_DPA: DPA slice nal * @GST_H264_NAL_SLICE_DPB: DPB slice nal * @GST_H264_NAL_SLICE_DPC: DPC slice nal * @GST_H264_NAL_SLICE_IDR: DPR slice nal - * @GST_H264_NAL_SEI: Supplemental enhancement information nal unit - * @GST_H264_NAL_SPS: Sequence parameter set nal unit - * @GST_H264_NAL_PPS: Picture parameter set nal unit - * @GST_H264_NAL_AU_DELIMITER: Access unit delimiter nal unit + * @GST_H264_NAL_SEI: Supplemental enhancement information (SEI) nal unit + * @GST_H264_NAL_SPS: Sequence parameter set (SPS) nal unit + * @GST_H264_NAL_PPS: Picture parameter set (PPS) nal unit + * @GST_H264_NAL_AU_DELIMITER: Access unit (AU) delimiter nal unit * @GST_H264_NAL_SEQ_END: End of sequence nal unit * @GST_H264_NAL_STREAM_END: End of stream nal unit - * @GST_H264_NAL_FILLER_DATA: Filler data na lunit + * @GST_H264_NAL_FILLER_DATA: Filler data nal lunit * * Indicates the type of H264 Nal Units */ @@ -81,13 +81,13 @@ typedef enum /** * GstH264ParserResult: * @GST_H264_PARSER_OK: The parsing succeded - * @GST_H264_PARSER_BROKEN_DATA: The data we parsed where broken - * @GST_H264_PARSER_BROKEN_LINK: The link to a needed struct for the parsing couldn't be found + * @GST_H264_PARSER_BROKEN_DATA: The data to parse is broken + * @GST_H264_PARSER_BROKEN_LINK: The link to structure needed for the parsing couldn't be found * @GST_H264_PARSER_ERROR: An error accured when parsing * @GST_H264_PARSER_NO_NAL: No nal found during the parsing - * @GST_H264_PARSER_NO_NAL_END: Start of the nal found, not the end. + * @GST_H264_PARSER_NO_NAL_END: Start of the nal found, but not the end. * - * Information about how the parsing of a H264 elements went. + * The result of parsing H264 data. */ typedef enum { @@ -101,11 +101,11 @@ typedef enum /** * GstH264SEIPayloadType: - * @GST_H264_SEI_BUF_PERIOD: The Sei Message contains a buffering period message - * @GST_H264_SEI_PIC_TIMING: The Sei Message contains a picture timing message + * @GST_H264_SEI_BUF_PERIOD: Buffering Period SEI Message + * @GST_H264_SEI_PIC_TIMING: Picture Timing SEI Message * ... * - * The type of the SEI message information + * The type of SEI message. */ typedef enum { @@ -294,7 +294,7 @@ struct _GstH264HRDParams * samples outside picture boundaries may be used in inter prediction * @max_bytes_per_pic_denom: indicates a number of bytes not exceeded by the sum of the sizes of * the VCL NAL units associated with any coded picture in the coded video sequence. - * @max_bits_per_mb_denom: indicates the maximum number of coded bits of macroblock_layer() + * @max_bits_per_mb_denom: indicates the maximum number of coded bits of macroblock_layer * @log2_max_mv_length_horizontal: indicate the maximum absolute value of a decoded horizontal * motion vector component * @log2_max_mv_length_vertical: indicate the maximum absolute value of a decoded vertical @@ -363,7 +363,7 @@ struct _GstH264VUIParams * @id: The ID of the sequence parameter set * @profile_idc: indicate the profile to which the coded video sequence conforms * - * + * H264 Sequence Parameter Set (SPS) */ struct _GstH264SPS { @@ -429,6 +429,11 @@ struct _GstH264SPS gboolean valid; }; +/** + * GstH264PPS: + * + * H264 Picture Parameter Set + */ struct _GstH264PPS { gint id; diff --git a/gst-libs/gst/codecparsers/gstmpegvideoparser.c b/gst-libs/gst/codecparsers/gstmpegvideoparser.c index c8a300e30c..1a2ddcc262 100644 --- a/gst-libs/gst/codecparsers/gstmpegvideoparser.c +++ b/gst-libs/gst/codecparsers/gstmpegvideoparser.c @@ -309,12 +309,12 @@ scan_for_start_codes (const GstByteReader * reader, guint offset, guint size) /** * gst_mpeg_video_parse: - * @data: The datas from which to parse + * @data: The data to parse * @size: The size of @data - * @offset: The offset from which to start the parsing + * @offset: The offset from which to start parsing * - * Parses @data, and detects the different packets types, offset, - * and size, starting from @offset + * Parses the MPEG 1/2 video bitstream contained in @data , and returns the + * detect packets as a list of #GstMpegVideoTypeOffsetSize. * * Returns: a #GList of #GstMpegVideoTypeOffsetSize */ @@ -373,12 +373,12 @@ gst_mpeg_video_parse (guint8 * data, gsize size, guint offset) /** * gst_mpeg_video_parse_sequence_header: - * @seqhdr: The #GstMpegVideoSequenceHdr to set - * @data: The datas from which to parse the seqhdr + * @seqhdr: (out): The #GstMpegVideoSequenceHdr structure to fill + * @data: The data from which to parse the sequence header * @size: The size of @data * @offset: The offset in byte from which to start parsing @data * - * Sets the @seqhdr Mpeg Video Sequence Header structure members from @data + * Parses the @seqhdr Mpeg Video Sequence Header structure members from @data * * Returns: %TRUE if the seqhdr could be parsed correctly, %FALSE otherwize. */ @@ -400,12 +400,12 @@ gst_mpeg_video_parse_sequence_header (GstMpegVideoSequenceHdr * seqhdr, /** * gst_mpeg_video_parse_sequence_extension: - * @seqhdr: The #GstMpegVideoSequenceExt to set - * @data: The datas from which to parse the seqext + * @seqext: (out): The #GstMpegVideoSequenceExt structure to fill + * @data: The data from which to parse the sequence extension * @size: The size of @data * @offset: The offset in byte from which to start parsing @data * - * Sets the @seqext Mpeg Video Sequence Extension structure members from @data + * Parses the @seqext Mpeg Video Sequence Extension structure members from @data * * Returns: %TRUE if the seqext could be parsed correctly, %FALSE otherwize. */ @@ -464,12 +464,12 @@ gst_mpeg_video_parse_sequence_extension (GstMpegVideoSequenceExt * seqext, /** * gst_mpeg_video_parse_quant_matrix_extension: - * @ext: The #GstMpegVideoQuantMatrixExt to set - * @data: The datas from which to parse @quant + * @quant: (out): The #GstMpegVideoQuantMatrixExt structure to fill + * @data: The data from which to parse the Quantization Matrix extension * @size: The size of @data * @offset: The offset in byte from which to start the parsing * - * Sets the @quant Mpeg Video Quant Matrix Extension structure members from + * Parses the @quant Mpeg Video Quant Matrix Extension structure members from * @data * * Returns: %TRUE if the quant matrix extension could be parsed correctly, @@ -537,12 +537,12 @@ failed: /** * gst_mpeg_video_parse_picture_extension: - * @ext: The #GstMpegVideoPictureExt to set - * @data: The datas from which to parse the ext + * @ext: (out): The #GstMpegVideoPictureExt structure to fill + * @data: The data from which to parse the picture extension * @size: The size of @data * @offset: The offset in byte from which to start the parsing * - * Sets the @ext Mpeg Video Picture Extension structure members from @data + * Parse the @ext Mpeg Video Picture Extension structure members from @data * * Returns: %TRUE if the picture extension could be parsed correctly, * %FALSE otherwize. @@ -636,14 +636,15 @@ failed: /** * gst_mpeg_video_parse_picture_header: - * @hdr: The #GstMpegVideoPictureHdr to set - * @data: The datas from which to parse the hdr + * @hdr: (out): The #GstMpegVideoPictureHdr structure to fill + * @data: The data from which to parse the picture header * @size: The size of @data * @offset: The offset in byte from which to start the parsing * - * Sets the @hdr Mpeg Video Picture Header structure members from @data + * Parsers the @hdr Mpeg Video Picture Header structure members from @data * - * Returns: %TRUE if the picture sequence could be parsed correctly, %FALSE otherwize. + * Returns: %TRUE if the picture sequence could be parsed correctly, %FALSE + * otherwize. */ gboolean gst_mpeg_video_parse_picture_header (GstMpegVideoPictureHdr * hdr, @@ -708,13 +709,12 @@ failed: /** * gst_mpeg_video_parse_gop: - * @gop: The #GstMpegVideoGop to set - * @data: The datas from which to parse the gop + * @gop: (out): The #GstMpegVideoGop structure to fill + * @data: The data from which to parse the gop * @size: The size of @data * @offset: The offset in byte from which to start the parsing * - * - * Sets the @gop Mpeg Video Group of Picture structure members from @data + * Parses the @gop Mpeg Video Group of Picture structure members from @data * * Returns: %TRUE if the gop could be parsed correctly, %FALSE otherwize. */ diff --git a/gst-libs/gst/codecparsers/gstmpegvideoparser.h b/gst-libs/gst/codecparsers/gstmpegvideoparser.h index 13653e5df1..8bdf684770 100644 --- a/gst-libs/gst/codecparsers/gstmpegvideoparser.h +++ b/gst-libs/gst/codecparsers/gstmpegvideoparser.h @@ -56,33 +56,44 @@ typedef enum { GST_MPEG_VIDEO_PACKET_NONE = 0xff } GstMpegVideoPacketTypeCode; +/** + * GST_MPEG_VIDEO_PACKET_IS_SLICE: + * @typecode: The MPEG video packet type code + * + * Checks whether a packet type code is a slice. + * + * Returns: %TRUE if the packet type code corresponds to a slice, + * else %FALSE. + */ +#define GST_MPEG_VIDEO_PACKET_IS_SLICE(typecode) ((typecode) >= GST_MPEG_VIDEO_PACKET_SLICE_MIN && \ + (typecode) <= GST_MPEG_VIDEO_PACKET_SLICE_MAX) + /** * GstMpegVideoPacketExtensionCode: * @GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE: Sequence extension code - * @GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE_DISPLAY: Display extension code - * @GST_MPEG_VIDEO_PACKET_EXT_QUANT_MATRIX: Quantizer extension code - * @GST_MPEG_VIDEO_PACKET_EXT_GOP: Group Of Picture extension code + * @GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE_DISPLAY: Sequence Display extension code + * @GST_MPEG_VIDEO_PACKET_EXT_QUANT_MATRIX: Quantization Matrix extension code + * @GST_MPEG_VIDEO_PACKET_EXT_PICTURE: Picture coding extension * - * Indicates what type of packets are in this - * block, some are mutually * exclusive though - ie, sequence packs are - * accumulated separately. GOP & Picture may occur together or separately + * Indicates what type of packets are in this block, some are mutually + * exclusive though - ie, sequence packs are accumulated separately. GOP & + * Picture may occur together or separately. */ typedef enum { GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE = 0x01, GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE_DISPLAY = 0x02, GST_MPEG_VIDEO_PACKET_EXT_QUANT_MATRIX = 0x03, - GST_MPEG_VIDEO_PACKET_EXT_GOP = 0x04, GST_MPEG_VIDEO_PACKET_EXT_PICTURE = 0x08 } GstMpegVideoPacketExtensionCode; /** * GstMpegVideoLevel: - * @GST_MPEG_VIDEO_LEVEL_LOW: Level Low - * @GST_MPEG_VIDEO_LEVEL_MAIN: Level Main - * @GST_MPEG_VIDEO_LEVEL_HIGH_1440: Level High 1440 - * @GST_MPEG_VIDEO_LEVEL_HIGH: Level High + * @GST_MPEG_VIDEO_LEVEL_LOW: Low level (LL) + * @GST_MPEG_VIDEO_LEVEL_MAIN: Main level (ML) + * @GST_MPEG_VIDEO_LEVEL_HIGH_1440: High 1440 level (H-14) + * @GST_MPEG_VIDEO_LEVEL_HIGH: High level (HL) * - * Indicates the level in use + * Mpeg-2 Levels. **/ typedef enum { GST_MPEG_VIDEO_LEVEL_HIGH = 0x04, @@ -93,14 +104,14 @@ typedef enum { /** * GstMpegVideoProfile: - * @GST_MPEG_VIDEO_PROFILE_422, - * @GST_MPEG_VIDEO_PROFILE_HIGH, - * @GST_MPEG_VIDEO_PROFILE_SPATIALLY_SCALABLE, - * @GST_MPEG_VIDEO_PROFILE_SNR_SCALABLE, - * @GST_MPEG_VIDEO_PROFILE_MAIN, - * @GST_MPEG_VIDEO_PROFILE_SIMPLE, + * @GST_MPEG_VIDEO_PROFILE_422: 4:2:2 profile (422) + * @GST_MPEG_VIDEO_PROFILE_HIGH: High profile (HP) + * @GST_MPEG_VIDEO_PROFILE_SPATIALLY_SCALABLE: Spatially Scalable profile (Spatial) + * @GST_MPEG_VIDEO_PROFILE_SNR_SCALABLE: SNR Scalable profile (SNR) + * @GST_MPEG_VIDEO_PROFILE_MAIN: Main profile (MP) + * @GST_MPEG_VIDEO_PROFILE_SIMPLE: Simple profile (SP) * - * Indicates the profile type in use + * Mpeg-2 Profiles. **/ typedef enum { GST_MPEG_VIDEO_PROFILE_422 = 0x00, @@ -113,12 +124,12 @@ typedef enum { /** * GstMpegVideoChromaFormat: - * @GST_MPEG_VIDEO_CHROMA_RES, - * @GST_MPEG_VIDEO_CHROMA_420, - * @GST_MPEG_VIDEO_CHROMA_422, - * @GST_MPEG_VIDEO_CHROMA_444, + * @GST_MPEG_VIDEO_CHROMA_RES: Invalid (reserved for future use) + * @GST_MPEG_VIDEO_CHROMA_420: 4:2:0 subsampling + * @GST_MPEG_VIDEO_CHROMA_422: 4:2:2 subsampling + * @GST_MPEG_VIDEO_CHROMA_444: 4:4:4 (non-subsampled) * - * Indicates the chroma type + * Chroma subsampling type. */ typedef enum { GST_MPEG_VIDEO_CHROMA_RES = 0x00, @@ -129,12 +140,12 @@ typedef enum { /** * GstMpegVideoPictureType: - * @GST_MPEG_VIDEO_PICTURE_TYPE_I: Type I - * @GST_MPEG_VIDEO_PICTURE_TYPE_P: Type P - * @GST_MPEG_VIDEO_PICTURE_TYPE_B: Type B - * @GST_MPEG_VIDEO_PICTURE_TYPE_D: Type D + * @GST_MPEG_VIDEO_PICTURE_TYPE_I: Intra-coded (I) frame + * @GST_MPEG_VIDEO_PICTURE_TYPE_P: Predictive-codec (P) frame + * @GST_MPEG_VIDEO_PICTURE_TYPE_B: Bidirectionally predictive-coded (B) frame + * @GST_MPEG_VIDEO_PICTURE_TYPE_D: D frame * - * Indicates the type of picture + * Picture type. */ typedef enum { GST_MPEG_VIDEO_PICTURE_TYPE_I = 0x01, @@ -147,9 +158,9 @@ typedef enum { * GstMpegVideoPictureStructure: * @GST_MPEG_VIDEO_PICTURE_STRUCTURE_TOP_FIELD: Top field * @GST_MPEG_VIDEO_PICTURE_STRUCTURE_BOTTOM_FIELD: Bottom field - * @GST_MPEG_VIDEO_PICTURE_STRUCTURE_FRAME: Frame + * @GST_MPEG_VIDEO_PICTURE_STRUCTURE_FRAME: Frame picture * - * Indicates the structure of picture + * Picture structure type. */ typedef enum { GST_MPEG_VIDEO_PICTURE_STRUCTURE_TOP_FIELD = 0x01, @@ -184,20 +195,20 @@ typedef struct _GstMpegVideoTypeOffsetSize GstMpegVideoTypeOffsetSize; struct _GstMpegVideoSequenceHdr { guint16 width, height; - guint8 aspect_ratio_info; - guint8 frame_rate_code; + guint8 aspect_ratio_info; + guint8 frame_rate_code; guint32 bitrate_value; guint16 vbv_buffer_size_value; - guint8 constrained_parameters_flag; + guint8 constrained_parameters_flag; - guint8 intra_quantizer_matrix[64]; - guint8 non_intra_quantizer_matrix[64]; + guint8 intra_quantizer_matrix[64]; + guint8 non_intra_quantizer_matrix[64]; /* Calculated values */ - guint par_w, par_h; - guint fps_n, fps_d; - guint bitrate; + guint par_w, par_h; + guint fps_n, fps_d; + guint bitrate; }; /** @@ -210,7 +221,7 @@ struct _GstMpegVideoSequenceHdr * @vert_size_ext: Vertical size * @bitrate_ext: The bitrate * @vbv_buffer_size_extension: Vbv vuffer size - * @low_delay: %TRUE if the sequence doesn't contain any B-pitcture, %FALSE + * @low_delay: %TRUE if the sequence doesn't contain any B-pictures, %FALSE * otherwize * @fps_n_ext: Framerate nominator code * @fps_d_ext: Framerate denominator code @@ -238,14 +249,14 @@ struct _GstMpegVideoSequenceExt /** * GstMpegVideoQuantMatrixExt: - * @load_intra_quantiser_matrix - * @intra_quantiser_matrix - * @load_non_intra_quantiser_matrix + * @load_intra_quantiser_matrix: + * @intra_quantiser_matrix: + * @load_non_intra_quantiser_matrix: * @non_intra_quantiser_matrix: - * @load_chroma_intra_quantiser_matrix - * @chroma_intra_quantiser_matrix - * @load_chroma_non_intra_quantiser_matrix - * @chroma_non_intra_quantiser_matrix + * @load_chroma_intra_quantiser_matrix: + * @chroma_intra_quantiser_matrix: + * @load_chroma_non_intra_quantiser_matrix: + * @chroma_non_intra_quantiser_matrix: * * The Quant Matrix Extension structure */ @@ -355,11 +366,11 @@ struct _GstMpegVideoGop struct _GstMpegVideoTypeOffsetSize { guint8 type; - guint offset; - gint size; + guint offset; + gint size; }; -GList * gst_mpeg_video_parse (guint8 * data, gsize size, guint offset); +GList *gst_mpeg_video_parse (guint8 * data, gsize size, guint offset); gboolean gst_mpeg_video_parse_sequence_header (GstMpegVideoSequenceHdr * params, guint8 * data, gsize size, guint offset);