Opened 5 months ago
Last modified 4 months ago
#10767 new defect
Bad documentation on chroma-derived-nc and friends
Reported by: | Mingye Wang | Owned by: | |
---|---|---|---|
Priority: | normal | Component: | documentation |
Version: | git-master | Keywords: | colorspace |
Cc: | Blocked By: | ||
Blocking: | Reproduced by developer: | no | |
Analyzed by developer: | no |
Description (last modified by )
Summary of the bug:
The texinfo documentation on chroma-derived-{nc,c} is bad. In fact, it's worse than what we have in pixfmt.h. We should replace these all with pixfmt.h documentation.
How to reproduce:
Navigate to:
- https://ffmpeg.org/ffmpeg-codecs.html#Codec-Options, which has one instance of these options. Here we see
chroma-derived-nc
explained as "Chroma-derived NCL", which is very unhelpful compared to what pixfmt says. In general, the descriptions forcolor_primaries
,color_trc
,colorspace
are of lower quality than their pixfmt.h version, so I recommend that they all be replaced.- While we are at it, the texinfo description for
color_range
is straight up wrong. pixfmt again has it right.
- While we are at it, the texinfo description for
- https://ffmpeg.org/ffmpeg-filters.html#setparams-1, which has another instance. This one is just blank.
Change History (6)
comment:1 by , 5 months ago
Description: | modified (diff) |
---|
comment:2 by , 5 months ago
Description: | modified (diff) |
---|
comment:3 by , 5 months ago
Description: | modified (diff) |
---|
comment:4 by , 5 months ago
comment:5 by , 4 months ago
Yes, I get that. But the thing is, the user-facing documentation in the texinfo pages is worse than the programmer-facing document in pixfmt.h. (Have you clicked the link "what pixfmt says"? Because that goes right to the line for AVCOL_SPC_CHROMA_DERIVED_NCL
in pixfmt.h.)
For chroma-derived-nc
, texinfo says "Chroma-derived NCL", while pixfmt says "Chromaticity-derived non-constant luminance system". That's much better.
For color_range
mpeg
, texinfo says MPEG (219*2^(n-8))
, while pixfmt very carefully tells you (219 * E + 16) * 2^(n-8)
for luma and (224 * E + 128) * 2^(n-8)
for chroma. That's not only better, but also more correct.
comment:6 by , 4 months ago
is worse than the programmer-facing document in pixfmt.h.
That is because I fixed the text in header file.
chroma-derived-nc is just a matrix that depends on primaries and white point. Every combination of primaries and white point leads to special matrix, like how CIE D65 + BT.709 is BT.709 matrix or Illuminant C + BT.470 primaries make BT.601 matrix.
Nc means it is using NC, non constant transfer function. There is also CL, where transfer works differently, like in BT.2020CL.