Commit 8b268bd4 authored by Thibault Saunier's avatar Thibault Saunier

codecparsers: h264: Update the documentation

Fix a few error.
Document missing parts.
Add links to the specifications
parent 24517ba7
......@@ -32,25 +32,52 @@
* @short_description: Convenience library for h264 video
* bitstream parsing.
*
* It offers you basic parsing in AVC mode or not. Tp identify Nals in a bitstream and
* parse its basic headers, you should call:
* It offers you bitstream parsing in AVC mode or not. To identify Nals in a bitstream and
* parse its headers, you should call:
* <itemizedlist>
* <listitem>
* gst_h264_parser_identify_nalu to identify the following nalu in not AVC bitstreams
* #gst_h264_parser_identify_nalu to identify the following nalu in not AVC bitstreams
* </listitem>
* <listitem>
* gst_h264_parser_identify_nalu_avc to identify the following nalu in AVC bitstreams
* #gst_h264_parser_identify_nalu_avc to identify the nalu in AVC bitstreams
* </listitem>
* </itemizedlist>
*
* Then, depending on the #GstH264NalUnitType of the newly parsed #GstH264NalUnit, you should
* call the differents functions to parse the struct.
* call the differents functions to parse the structure:
* <itemizedlist>
* <listitem>
* From #GST_H264_NAL_SLICE to #GST_H264_NAL_SLICE_IDR: #gst_h264_parser_parse_slice_hdr
* </listitem>
* <listitem>
* #GST_H264_NAL_SEI: #gst_h264_parser_parse_sei
* </listitem>
* <listitem>
* #GST_H264_NAL_SPS: #gst_h264_parser_parse_sps
* </listitem>
* <listitem>
* #GST_H264_NAL_PPS: #gst_h264_parser_parse_pps
* </listitem>
* <listitem>
* Any other: #gst_h264_parser_parse_nal
* </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. This, to guarantee that the
* #GstH264NalUnitType to be parsed for your personnal use, in order to guarantee that the
* #GstH264NalParser is always up to date.
*
* For more details about the structures, look at the ISO specifications.
* 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:
*
* <itemizedlist>
* <listitem>
* ITU-T H.264: http://www.itu.int/rec/T-REC-H.264
* </listitem>
* <listitem>
* ISO/IEC 14496-10: http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=56538
* </listitem>
* </itemizedlist>
*/
#ifdef HAVE_CONFIG_H
......@@ -1090,7 +1117,8 @@ error:
/**
* gst_h264_nal_parser_new:
*
* Creates a nez #GstH264NalParser
* Creates a new #GstH264NalParser. It should be freed with
* gst_h264_nal_parser_free after use.
*
* Returns: a new #GstH264NalParser
*/
......@@ -1110,11 +1138,11 @@ gst_h264_nal_parser_new (void)
* gst_h264_parser_identify_nalu:
* @nalparser: a #GstH264NalParser
* @data: The data to parse
* @offset: the offset from which to parse @data
* @offset: the offset from which to parse @data
* @size: the size of @data
* @nalu: The #GstH264NalUnit where to store parsed nal headers
*
* Parses the buffer and set @nalu from the next nalu data from @data
* Parses @data and fills @nalu from the next nalu data from @data
*
* Returns: a #GstH264ParserResult
*/
......@@ -1180,12 +1208,14 @@ gst_h264_parser_identify_nalu (GstH264NalParser * nalparser,
/**
* 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
* @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
*
* Parses the data and sets @nalu from @data.
* Parses @data and sets @nalu.
*
* Returns: a #GstH264ParserResult
*/
......@@ -1221,6 +1251,17 @@ gst_h264_parser_identify_nalu_avc (GstH264NalParser * nalparser,
return GST_H264_PARSER_OK;
}
/**
* gst_h264_parser_parse_nal:
* @nalparser: a #GstH264NalParser
* @nalu: The #GstH264NalUnit to parse
*
* This function should be called in the case you don't need to
* parse a specific structure. It is necessary to do so to make
* sure @nalparser is up to date.
*
* Returns: a #GstH264ParserResult
*/
GstH264ParserResult
gst_h264_parser_parse_nal (GstH264NalParser * nalparser, GstH264NalUnit * nalu)
{
......@@ -1242,10 +1283,10 @@ 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 set.
* @slice: The #GstH264SPS to fill.
* @parse_vui_params: Whether to parse the vui_params or not
*
* Parses the @data, and sets the @sps.
* Parses @data, and fills the @sps structure.
*
* Returns: a #GstH264ParserResult
*/
......@@ -1270,10 +1311,10 @@ gst_h264_parser_parse_sps (GstH264NalParser * nalparser, GstH264NalUnit * nalu,
/**
* gst_h264_parse_sps:
* @nalu: The #GST_H264_NAL_SPS #GstH264NalUnit you want to parse
* @slice: The #GstH264SPS to set.
* @sps: The #GstH264SPS to fill.
* @parse_vui_params: Whether to parse the vui_params or not
*
* Parses the @data, and sets the @sps.
* Parses @data, and fills the @sps structure.
*
* Returns: a #GstH264ParserResult
*/
......@@ -1441,12 +1482,10 @@ error:
/**
* gst_h264_parse_pps:
* @nalparser: a #GstH264NalParser
* @data: the data to parse
* @size: the size of @data
* @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit you want to parse
* @slice: The #GstH264PPS to set.
* @pps: The #GstH264PPS to fill.
*
* Parses the @data, and sets the @pps.
* Parses @data, and fills the @pps structure.
*
* Returns: a #GstH264ParserResult
*/
......@@ -1572,12 +1611,10 @@ error:
/**
* gst_h264_parser_parse_pps:
* @nalparser: a #GstH264NalParser
* @data: the data to parse
* @size: the size of @data
* @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit you want to parse
* @slice: The #GstH264PPS to set.
* @pps: The #GstH264PPS to fill.
*
* Parses the @data, and sets the @pps.
* Parses @data, and fills the @pps structure.
*
* Returns: a #GstH264ParserResult
*/
......@@ -1599,12 +1636,13 @@ 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
* @slice: The #GstH264SliceHdr to set.
* @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 the @data, and sets the @slice.
* Parses @data, and fills the @slice structure.
*
* Returns: a #GstH264ParserResult
*/
......@@ -1777,9 +1815,9 @@ error:
* gst_h264_parser_parse_sei:
* @nalparser: a #GstH264NalParser
* @nalu: The #GST_H264_NAL_SEI #GstH264NalUnit you want to parse
* @slice: The #GstH264SEIMessage to set.
* @sei: The #GstH264SEIMessage to fill.
*
* Parses the @data, and sets the @pps.
* Parses @data, and fills the @sei structures.
*
* Returns: a #GstH264ParserResult
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment