diff options
| -rw-r--r-- | libass/ass_types.h | 83 |
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 |