[FFmpeg-user] A systematic effort for documentation? [was: Re: Why is format=rgb24 required after maskedmerge?]

[Mark Filipak]

On 08/21/2020 11:20 PM, Jim DeLaHunt wrote:
-snip-
> There is a great need for a glossary. It should be structured so that each term has an anchor, 
> allowing references from anywhere in the documentation to the glossary. My nomination for entries: 
> "fps", "GOP", "PTS", "time base".
-snip-

I have been working on a glossary for a very long time that includes all those and much more, and in 
which each and every element of a program stream has a clear, unambiguous structure definition sans 
implied relations (e.g. 'this' implies 'that') and sans vague references to metadata (e.g. a frame 
is a thing that metadata defines as a frame). I've worked my way deeply into the streams and am 
currently resolving macroblock internals [1]. The problem I'm encountering is that in order to 
create clear, unambiguous definitions, I have had to create names for differing things that 
currently have the same names that differ based on 'context' (which sucks), and that I suspect will 
raise much controversy. For example, the word "frame" is applied to a great number of things that 
are not frames -- I have created several unique 'sample-sets' that cover the variant frames, fields, 
and scans. For example, the word "picture" is applied to so-called 'progressive' sample-sets, to 
hard telecined, concurrent "field pictures" (which I call "half-pictures"), and even to successive 
fields (which I call "scans"). In my effort, I've tried very hard to not change too much of the 
current nomenclature.

[1] I've discovered that "interlace" applies not to lines on a display, but to samples within blocks 
within macroblocks. There are several interlace schemes and I'm defining each of them via easy to 
understand diagrams that simultaneously show how they are stored and traversed in-buffer versus 
where they wind up in slices on the display. While attempting to understand what ffmpeg developers 
mean when they refer to "interlace", I now appreciate that looking at top-level metadata in stream 
headers is futile -- they are not directly related. Without a "look" into how blocks and macroblocks 
are structured, one will never understand what ffmpeg developers say regarding "interlace".

Mark.