[FFmpeg-user] "documented implicitly" [was: Re: Why is format=rgb24 required after maskedmerge?]

[Paul B Mahol]

On 8/19/20, Jim DeLaHunt <list+ffmpeg-user at jdlh.com> wrote:
> On 2020-08-19 10:53, Paul B Mahol wrote:
>> On 8/19/20, Jim DeLaHunt <list+ffmpeg-user at jdlh.com> wrote:
>>> On 2020-08-19 07:34, Paul B Mahol wrote:
>>>> You are deeply confused about our filters.
>>>> Any filter can change pixel formats to one that they accepts thus gbrp
>>>> is picked instead of packed rgb, this is already documented
>>>> implicitly.
>>> Wow, "documented implicitly". This is such a classic FFmpeg project
>>> statement. The role of documentation is to explain, explicitly, at a
>>> suitable level of detail. What does "documented implicitly" even mean?
>>>
>>> I think this thread points out is that FFmpeg documentation is
>>> inadequate. It is hard to prove a negative, but I suspect that the term
>>> "pixel format" is not actually defined in the FFmpeg documentation. I
>>> suspect that the statement, "Any filter can change pixel formats" is not
>>> stated either. Certainly the maskedmerge filter documentation[1] doesn't
>>> mention pixel formats at all, much less say what pixel formats the
>>> filter sets for its output.
>>>
>>> …And yet "You are deeply confused about our filters". In other words, the
>>> documentation has failed to explain to you what FFmpeg does, the project
>>> has failed to write or welcome improved documentation, you do not
>>> understand how FFmpeg works — and somehow this is your fault.
>> http://ffmpeg.org/ffmpeg-filters.html#toc-Filtergraph-syntax-1
>>
>> mention it explicitly:
>>
>> Libavfilter will automatically insert scale filters where format
>> conversion is required. It is possible to specify swscale flags for
>> those automatically inserted scalers by prepending sws_flags=flags; to
>> the filtergraph description.
>
>
> This continues to be a great example of the FFmpeg project's approach to
> documentation.
>
> 1. A sentence about a library adding functional processing steps ("scale
> filters") in buried in a section entitled "syntax", amid paragraphs
> about syntax.
>
> 2. the "scale filters" name alludes to changing pixel counts, and the
> linked-to filter documentation[2] talks about "(resize) the input video"
> and about "the input image format" (without defining that term); it does
> not have a parameter for pixel formats or document the pixel formats it
> uses or sets or changes.
>
> 3. this reference to "scale filters" is supposed to be responsive to a
> thread about pixel formats.
>
> 4. no acknowledgement that the documentation might actually be less than
> perfect. Is it so hard to concede, "you have a point, the docs could be
> better here"?
>
> [1] http://ffmpeg.org/ffmpeg-all.html#maskedmerge
> [2] http://ffmpeg.org/ffmpeg-filters.html#scale


Well than sentence needs to be completely rewritten since we have
audio support too.

>
>
> _______________________________________________
> ffmpeg-user mailing list
> ffmpeg-user at ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-user
>
> To unsubscribe, visit link above, or email
> ffmpeg-user-request at ffmpeg.org with subject "unsubscribe".