Documentation function gst_video_encoder_finish_frame and structure GstVideoCodecFrame not enough?

[Arun Raghavan]

n Thu, 25 May 2017, at 08:17 PM, Martin Maurer wrote:
> Hello,
> 
> when looking at the documentation of gst_video_encoder_finish_frame
> 
> ( 
> https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gst-plugins-base-libs-GstVideoEncoder.html#gst-video-encoder-finish-frame 
> )
> 
> I am missing which information must be filled in which field, what it 
> does with this information and which are not needed at all (ignored).
> E.g. PTS/DTS/Duration can be filled into frame (GstVideoCodecFrame has 
> PTS/DTS/Duration fields),
> but also in fields of GstBuffer included in this frame. Seems to be the 
> case, that they must be filled into frame and are ignored in buffer.

It probably does make sense to document the fact that the values from
the field are used in preference to those from the GstBuffer.

> According to source code there is e.g. a check/handling for 
> presentation_frame_number == 0, which seems to be a special case.
> Could there be added some description inside the documentation of the 
> function what it does?
> 
> The function does a lot on timestamps, but what exactly? Why so lot 
> cases and very less documentation for the caller?

It isn't always desirable for all these details to be exposed in API
documentation. If there are things you think would make sense to have,
however, suggestions (or better still, patches) are welcome.

> When looking into documentation of GstVideoCodecFrame
> 
> ( 
> https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gst-plugins-base-libs-gstvideoutils.html#GstVideoCodecFrame 
> )
> 
> there is no description of /|decode_frame_number nor of 
> |//|/|presentation_frame_number.

I don't know what these are, but you can see examples of usage in
schrodec/schroenc/theoraenc. 
 
> What does "ED" and "D" mean in comments after structure elements? 
> Something like "encoded data" and "data"?
> What does it mean? Do you have an example?

Seems to be whether that field makes sense in the encode or decode
context. We should expand that too.

-- Arun