mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-11-23 10:11:08 +00:00
Code Issues 1 Projects Releases Wiki Activity

codecparsers: h264parse: improve documentation commentary

Browse source 
https://bugzilla.gnome.org/show_bug.cgi?id=775306
This commit is contained in:
Anton Eliasson 2016-11-29 11:08:14 +01:00 committed by Tim-Philipp Müller
parent 0e8567a981
commit 03615a772a
1 changed files with 31 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
gst-libs/gst/codecparsers/gsth264parser.c
View file

@ -32,19 +32,20 @@
* @short_description: Convenience library for h264 video
* bitstream parsing.
*
* It offers you bitstream parsing in AVC mode or not. To identify Nals in a bitstream and
* parse its headers, you should call:
* It offers bitstream parsing in both AVC (length-prefixed) and Annex B
* (0x000001 start code prefix) format. To identify a NAL unit in a bitstream
* and parse its headers, first call:
* <itemizedlist>
* <listitem>
* #gst_h264_parser_identify_nalu to identify the following nalu in not AVC bitstreams
* #gst_h264_parser_identify_nalu to identify a NAL unit in an Annex B type bitstream
* </listitem>
* <listitem>
* #gst_h264_parser_identify_nalu_avc to identify the nalu in AVC bitstreams
* #gst_h264_parser_identify_nalu_avc to identify a NAL unit in an AVC type bitstream
* </listitem>
* </itemizedlist>
*
* Then, depending on the #GstH264NalUnitType of the newly parsed #GstH264NalUnit, you should
* call the differents functions to parse the structure:
* The following functions are then available for parsing the structure of the
* #GstH264NalUnit, depending on the #GstH264NalUnitType:
* <itemizedlist>
* <listitem>
* From #GST_H264_NAL_SLICE to #GST_H264_NAL_SLICE_IDR: #gst_h264_parser_parse_slice_hdr
@ -63,12 +64,14 @@
* </listitem>
* </itemizedlist>
*
* Note: You should always call gst_h264_parser_parse_nal if you don't actually need
* #GstH264NalUnitType to be parsed for your personnal use, in order to guarantee that the
* #GstH264NalParser is always up to date.
* One of these functions *must* be called on every NAL unit in the bitstream,
* in order to keep the internal structures of the #GstH264NalParser up to
* date. It is legal to call #gst_h264_parser_parse_nal on NAL units of any
* type, if no special parsing of the current NAL unit is required by the
* application.
*
* For more details about the structures, look at the ITU-T H.264 and ISO/IEC 14496-10 – MPEG-4
* Part 10 specifications, you can download them from:
* Part 10 specifications, available at:
*
* <itemizedlist>
* <listitem>
@ -1333,12 +1336,13 @@ gst_h264_parser_identify_nalu_unchecked (GstH264NalParser * nalparser,
/**
* gst_h264_parser_identify_nalu:
* @nalparser: a #GstH264NalParser
* @data: The data to parse
* @offset: the offset from which to parse @data
* @data: The data to parse, containing an Annex B coded NAL unit
* @offset: the offset in @data from which to parse the NAL unit
* @size: the size of @data
* @nalu: The #GstH264NalUnit where to store parsed nal headers
* @nalu: The #GstH264NalUnit to store the identified NAL unit in
*
* Parses @data and fills @nalu from the next nalu data from @data
* Parses the headers of an Annex B coded NAL unit from @data and puts the
* result into @nalu.
*
* Returns: a #GstH264ParserResult
*/
@ -1383,13 +1387,14 @@ beach:
/**
* gst_h264_parser_identify_nalu_avc:
* @nalparser: a #GstH264NalParser
* @data: The data to parse, must be the beging of the Nal unit
* @offset: the offset from which to parse @data
* @data: The data to parse, containing an AVC coded NAL unit
* @offset: the offset in @data from which to parse the NAL unit
* @size: the size of @data
* @nal_length_size: the size in bytes of the AVC nal length prefix.
* @nalu: The #GstH264NalUnit where to store parsed nal headers
* @nalu: The #GstH264NalUnit to store the identified NAL unit in
*
* Parses @data and sets @nalu.
* Parses the headers of an AVC coded NAL unit from @data and puts the result
* into @nalu.
*
* Returns: a #GstH264ParserResult
*/
@ -1470,7 +1475,7 @@ gst_h264_parser_parse_nal (GstH264NalParser * nalparser, GstH264NalUnit * nalu)
* @sps: The #GstH264SPS to fill.
* @parse_vui_params: Whether to parse the vui_params or not
*
* Parses @data, and fills the @sps structure.
* Parses @nalu containing a Sequence Parameter Set, and fills @sps.
*
* Returns: a #GstH264ParserResult
*/
@ -2009,11 +2014,10 @@ error:
* @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit to parse
* @pps: The #GstH264PPS to fill.
*
* Parses @data, and fills the @pps structure.
* Parses @nalu containing a Picture Parameter Set, and fills @pps.
*
* The resulting @pps data structure shall be deallocated with the
* gst_h264_pps_clear() function when it is no longer needed, or prior
* to parsing a new PPS NAL unit.
* The resulting @pps data structure must be deallocated by the caller using
* gst_h264_pps_clear().
*
* Returns: a #GstH264ParserResult
*/
@ -2054,12 +2058,12 @@ gst_h264_pps_clear (GstH264PPS * pps)
/**
* gst_h264_parser_parse_slice_hdr:
* @nalparser: a #GstH264NalParser
* @nalu: The #GST_H264_NAL_SLICE #GstH264NalUnit to parse
* @nalu: The #GST_H264_NAL_SLICE to #GST_H264_NAL_SLICE_IDR #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
*
* Parses @data, and fills the @slice structure.
* Parses @nalu containing a coded slice, and fills @slice.
*
* Returns: a #GstH264ParserResult
*/
@ -2286,7 +2290,8 @@ gst_h264_sps_clear (GstH264SPS * sps)
* @nalu: The #GST_H264_NAL_SEI #GstH264NalUnit to parse
* @messages: The GArray of #GstH264SEIMessage to fill. The caller must free it when done.
*
* Parses @data, create and fills the @messages array.
* Parses @nalu containing one or more Supplementary Enhancement Information messages,
* and allocates and fills the @messages array.
*
* Returns: a #GstH264ParserResult
*/