[FFmpeg-devel] Inconsistent usage of AVFieldOrder values

[Marton Balint]

On Mon, 22 Apr 2024, Devin Heitmueller wrote:

> Hello,
>
> I suspect this topic has been visited a number of times over the
> years, but I figured I should re-raise it.
>
> In the compressed domain, field ordering is represented by the
> AVFieldOrder enumeration.  Among the interlaced possibilities, you've
> got four combinations:  AV_FIELD_TT, AV_FIELD_BB, AV_FIELD_TB,
> AV_FIELD_BT.  The last two characters indicate the coding and display
> order respectively.

That is how it is documented, but likely it is not how it actually works. 
The whole mess is originated from the QuickTime specification which 
contradicts with an Apple technical note. See this discussion: 
https://sourceforge.net/p/mediainfo/bugs/841/

Long story short, AV_FIELD_TB means top field first in practice, 
AV_FIELD_BT means bottom field first in practice. I think most of the code 
follows this interpretation, and not the actual documentation. 
AV_FIELD_BB and AV_FIELD_TT tries to signal field order for separate 
field encodings, but quite possibly sometimes (mis)used for ordinary field 
order signalling as well...

>
> Only a subset of these possible values are able to be represented in
> ffmpeg's AVFrame facility (specifically AV_FIELD_TT and AV_FIELD_TB).
> This is because interlaced AVFrames are always represented as
> interleaved with top field coded first, and the
> AV_FRAME_FLAG_TOP_FIELD_FIRST flag (previously the top_field_first
> member) is used to dictate the display order.  I'm not proposing we
> make any change to this behavior at this time.
>
> I'm seeing use cases (including within the ffmpeg tree) where I
> suspect the developer is misunderstanding the meaning of these values,
> and I want to solicit feedback on whether patches would be accepted to
> correct such usage, even if it results in breaking applications that
> expect the incorrect values.
>
> For example, the decklink input module (libavdevice/decklink_dec.cpp)
> sets the values on the v210 packets to either AV_FIELD_TT or
> AV_FIELD_BB depending on whether the display order is top field first
> or bottom field first.  While the AV_FIELD_TT values is correct, the
> use of AV_FIELD_BB is incorrect since all frames delivered by the
> driver are always coded as top-field-first (i.e. interlaced frames
> with a display order of bottom first should be AV_FIELD_TB).

I guess the reason for using TT/BB was that it is not contriversal... But 
TB is BFF according to docs, but it is interpreted as TFF in reality...

>
> I'm seeing numerous cases such as the above, in decoders and encoders,
> libavformat/libavdevice modules, as well as in third party
> applications.
>
> I guess my question is:  if I submit patches which fix such cases
> where I find them, will they be rejected because they are a change in
> behavior and might very well break existing applications that expect
> the incorrect values?  I would like the libraries to report the
> correct values in a consistent manner, but I recognize this may cause
> some breakage in existing applications.

Making changes out of the blue likely won't be acceptable. If a
justified plan is presented to untangle this, then maybe *some* breakage 
is acceptable, but I don't honestly know.

Some random ideas:

- Consider fixing the documentation (and the textual description of the
   field orders) instead of changing behaviour.
- Try to collect commercial samples and see what they contain for TFF/BFF
   content, separete fields or interleaved, compressed or
   uncompressed.
- Go over the codebase and see which component is using which
   interpretation in practice, make a list, see if there is a significant
   majority...

Regards,
Marton