doc: improve colour matrix description

Better explained what and why and remove confusing comment about
"None" supposedly being for "exact colour doesn't matter" as
there's no evidence of anyone actually using it like this.

1 files changed, 54 insertions, 29 deletions

diff --git a/libass/ass_types.h b/libass/ass_types.h
index 9148e7f..f235990 100644
--- a/libass/ass_types.h
+++ b/libass/ass_types.h
@@ -150,56 +150,81 @@ typedef struct ass_event {
 } ASS_Event;
 
 /**
- * Support for (xy-)vsfilter mangled colors
+ * Support for (xy-)VSFilter mangled colors
  *
- * Generally, xy-vsfilter emulates the classic vsfilter behavior of
- * rendering directly into the (usually YCbCr) video. vsfilter is
- * hardcoded to use BT.601(TV) as target colorspace when converting
- * the subtitle RGB color to the video colorspace. This led to major
- * breakage when HDTV video was introduced: HDTV typically uses
- * BT.709(TV), but vsfilter still used BT.601(TV) for conversion.
+ * Generally, xy-VSFilter emulates the classic VSFilter behavior of
+ * rendering directly into the (usually YCbCr) video. Classic
+ * guliverkli(2)-VSFilter is hardcoded to use BT.601(TV) as target colorspace
+ * when converting the subtitle RGB color to the video colorspace.
+ * This led to odd results when other colorspaces were used, particular
+ * once those became more common with the rise of HDTV video:
+ * HDTV typically uses BT.709(TV), but VSFilter continued assuming
+ * BT.601(TV) for conversion.
  *
  * This means classic vsfilter will mangle colors as follows:
  *
- *    screen_rgb = bt_709tv_to_rgb(rgb_to_bt601tv(ass_rgb))
- *
- * Or in general:
- *
  *    screen_rgb = video_csp_to_rgb(rgb_to_bt601tv(ass_rgb))
  *
  * where video_csp is the colorspace of the video with which the
  * subtitle was muxed.
  *
- * xy-vsfilter did not fix this, but instead introduced explicit
- * rules how colors were mangled by adding a "YCbCr Matrix" header.
- * If this header specifies a real colorspace (like BT.601(TV) etc.),
- * xy-vsfilter behaves exactly like vsfilter, but using the specified
- * colorspace for conversion of ASS input RGB to screen RGB:
+ * Subtitle authors worked around this issue by adjusting the color
+ * to look as intended *after* going through the mangling process. Still,
+ * this behaviour isn't great and also limits the color range. Yet,
+ * for backwards compatibility with existing files, the classic mangling
+ * must be preserved for existing files to not break the display of
+ * color-matched typesets created with older VSFilter versions. Thus,
+ * on iniative of xy-VSFilter/XYSubFilter a new explicit "YCbCr Matrix"
+ * header was introduced to allow new files to avoid this color mangling.
+ * However due to a limitation of VSFilter API, VSFilters don't actually
+ * know the real colorspace of the video they're rendering to, so the
+ * header wasn't created as a simple "Use ColourMangling: yes/no", but instead
+ * specifies exactly which colorspace to use for the initial conversion
+ * from the subtitle's RGB values. So we now got
  *
  *    screen_rgb = video_csp_to_rgb(rgb_to_ycbcr_header_csp(ass_rgb))
  *
- * Further, xy-vsfilter behaves like vsfilter with no changes if the header
- * is missing.
+ * with rgb_to_ycbcr_header_csp defaulting to TV-range BT.601.
+ *
+ * XySubFilter, whose API was planned during introduction of this header,
+ * is not affected by this VSFilter-API limitation, so for it and other
+ * renderers like libass an additional special value "None" was also added.
+ * "None" tells the renderer to directly use untouched RGB values without
+ * any conversion.
+ * The above mangling process with special value "None" to opt out
+ * of any colour mangling is the recommended default behaviour.
  *
- * The special value "None" means untouched RGB values. Keep in mind that
- * some version of xy-vsfilter are buggy and don't interpret this correctly.
- * It appears some people are advocating that this header value is
- * intended for situations where exact colors do not matter.
+ * Keep in mind though, that xy-VSFilter cannot accurately implement this and
+ * will instead resort to a guessing the video colorspace based on resolution
+ * and then convert RGB to the guessed space.
+ * Also some versions of MPC-HC's Internal Subtitle Renderer don't (explicitly)
+ * implement "None", but use xy-VSFilter-like resolution-based guessing for
+ * unknown values or no header at all (which ofc also breaks old subtitles).
  *
- * Note that newer Aegisub versions (the main application to produce ASS
- * subtitle scripts) have an option that tries not to mangle the colors. It
- * is said that if the header is not set to BT.601(TV), the colors are
- * supposed not to be mangled, even if the "YCbCr Matrix" header is not
- * set to "None". In other words, the video colorspace as detected by
- * Aegisub is the same as identified in the file header.
+ * Aegisub's (the main application to produce ASS subtitle scripts) behaviour
+ * regarding colorspaces is unfortunately a bit confusing.
+ * As of time of writing there still is a config option to force BT.601(TV)
+ * in some active forks (which should not be used to author subs and serves
+ * at most as a tool to check how now ancient VSFilters would have rendered the
+ * subs), the automatically chosen colorspace may depend on the fork and the
+ * videoprovider used and furthermore Aegisub likes to override
+ * "YCbCr Matrix: None" with the autodetected space of a loaded video.
+ * Supposedly some Aegisub versions had an option that "tries not to mangle the
+ * colors". It was said that if the header is not set to BT.601(TV), the colors
+ * were supposed not to be mangled, even if the header was not set to "None".
  *
  * In general, misinterpreting this header or not using it will lead to
  * slightly different subtitle colors, which can matter if the subtitle
  * attempts to match solid colored areas in the video.
+ * It is recommended to stick to XySubFilter-like behaviour described above.
+ * A highly motivated application may also expose options to users to  emulate
+ * xy-VSFilter's resolution-depended guess or other (historic) mangling modes.
+ * Completly ignoring the color mangling is likely to give bad results.
  *
  * Note that libass doesn't change colors based on this header. It
  * absolutely can't do that, because the video colorspace is required
- * in order to handle this as intended by xy-vsfilter.
+ * in order to handle this as intended. API users must use the exposed
+ * information to perform color mangling as described above.
  */
 typedef enum ASS_YCbCrMatrix {
     YCBCR_DEFAULT = 0,  // Header missing