Introduce LayoutRes{X,Y} script headers

MrSmile · TheOneric · commit 1a533e5d5df5 · 2022-11-28T19:31:37.000+01:00
Rendering ASS depends on the video’s storage resolution
for several tags. Thus transferring a subtitle file to a
different version of a video, with e.g. higher resolution
or anamorphic squeezing undone, requires adjusting all those
tags.
Affected are \be, \blur, \frx, \fry and if ScaledBorderAndShadow
is not set to "yes", also all tags related to border and shadow.

This locks all but simple subtitle files to a specific video
storage resolution. If one wants to release several different resolution
simultaneously, the same source is reencoded to undo anamorphic
squeezing, or a new higher resolution source appears, it is required
to manually adjust affected tags and each video version needs a
different subtitle file.
This is a pain point, and resulted in some releases just
relying on user overrides of players, or incompatibly patched
renderers to avoid the required manual adjustments.

By adding new headers, which will replace the original video storage
resolution in all calculations, authors will be able to create files
which can be reused across different resolutions as long as the display
aspect ratio stays the same. Hopefully this will also halt the spread of
incomapatible patches and overrides, which just result in broken files
and further ASS fragmentation.

For simplicity and to avoid surprises, LayoutRes* headers
only take effect if both are present and set to values larger
than zero.

If LayoutRes{X,Y} is set to corresponds to the actual storage resolution
of the video the subs are authored and initially released with, at least
the initial/main version will also be effectively compatible to older
renderers, which do not understand the new headers yet. This will grant
users some time to upgrade and minimise friction from this retroactive
format addition.

The header concept is also approved by some VSFilters and patches
for Cyberbeing/xy-VSFilter’s xy-VSFilter and XySubFilter are pending
with only implementation details being still up for discussion.
Integration into active Aegisub forks and possibly other common editors
will be pursued at a later date.

libass-specific:
Since API-users can initialise PAR, we must recalcute even existing
values when LayoutRes{X,Y} is set to ensure the sub-author-provided
values take precedence.
diff --git a/libass/ass.c b/libass/ass.c
@@ -543,6 +543,10 @@ void ass_process_force_style(ASS_Track *track)
             track->PlayResX = parse_int_header(token);
         else if (!ass_strcasecmp(*fs, "PlayResY"))
             track->PlayResY = parse_int_header(token);
+        else if (!ass_strcasecmp(*fs, "LayoutResX"))
+            track->LayoutResX = parse_int_header(token);
+        else if (!ass_strcasecmp(*fs, "LayoutResY"))
+            track->LayoutResY = parse_int_header(token);
         else if (!ass_strcasecmp(*fs, "Timer"))
             track->Timer = ass_atof(token);
         else if (!ass_strcasecmp(*fs, "WrapStyle"))
@@ -848,6 +852,12 @@ static int process_info_line(ASS_Track *track, char *str)
     } else if (!strncmp(str, "PlayResY:", 9)) {
         check_duplicate_info_line(track, SINFO_PLAYRESY, "PlayResY");
         track->PlayResY = parse_int_header(str + 9);
+    } else if (!strncmp(str, "LayoutResX:", 11)) {
+        check_duplicate_info_line(track, SINFO_LAYOUTRESX, "LayoutResX");
+        track->LayoutResX = parse_int_header(str + 11);
+    } else if (!strncmp(str, "LayoutResY:", 11)) {
+        check_duplicate_info_line(track, SINFO_LAYOUTRESY, "LayoutResY");
+        track->LayoutResY = parse_int_header(str + 11);
     } else if (!strncmp(str, "Timer:", 6)) {
         check_duplicate_info_line(track, SINFO_TIMER, "Timer");
         track->Timer = ass_atof(str + 6);
diff --git a/libass/ass.h b/libass/ass.h
@@ -24,7 +24,7 @@
 #include <stdarg.h>
 #include "ass_types.h"
 
-#define LIBASS_VERSION 0x01600010
+#define LIBASS_VERSION 0x01600020
 
 #ifdef __cplusplus
 extern "C" {
@@ -392,6 +392,7 @@ void ass_set_frame_size(ASS_Renderer *priv, int w, int h);
  * \brief Set the source image size in pixels.
  * This affects some ASS tags like e.g. 3D transforms and
  * is used to calculate the source aspect ratio and blur scale.
+ * If subtitles specify valid LayoutRes* headers, those will take precedence.
  * The source image size can be reset to default by setting w and h to 0.
  * The value set with this function can influence the pixel aspect ratio used
  * for rendering.
@@ -461,6 +462,11 @@ void ass_set_use_margins(ASS_Renderer *priv, int use);
  * that this default assumes the frame size after compensating for margins
  * corresponds to an isotropically scaled version of the video display size.
  * If the storage size has not been set, a pixel aspect ratio of 1 is assumed.
+ *
+ * If subtitles specify valid LayoutRes* headers, the API-configured
+ * pixel aspect value is discarded in favour of one calculated out of the
+ * headers and values set with ass_set_frame_size().
+ *
  * \param priv renderer handle
  * \param par pixel aspect ratio (1.0 means square pixels, 0 means default)
  */
diff --git a/libass/ass_priv.h b/libass/ass_priv.h
@@ -42,6 +42,8 @@ typedef enum {
     SINFO_COLOURMATRIX = 1 << 6,
     SINFO_KERNING      = 1 << 7,
     SINFO_SCRIPTTYPE   = 1 << 8,
+    SINFO_LAYOUTRESX   = 1 << 9,
+    SINFO_LAYOUTRESY   = 1 << 10,
     // for legacy detection
     GENBY_FFMPEG       = 1 << 14
     // max 32 enumerators
diff --git a/libass/ass_render.c b/libass/ass_render.c
@@ -1002,11 +1002,14 @@ static ASS_Style *handle_selective_style_overrides(RenderContext *state,
 
 ASS_Vector ass_layout_res(ASS_Renderer *render_priv)
 {
+    ASS_Track *track = render_priv->track;
+    if (track->LayoutResX > 0 && track->LayoutResY > 0)
+        return (ASS_Vector) { track->LayoutResX, track->LayoutResY };
+
     ASS_Settings *settings = &render_priv->settings;
     if (settings->storage_width > 0 && settings->storage_height > 0)
         return (ASS_Vector) { settings->storage_width, settings->storage_height };
 
-    ASS_Track *track = render_priv->track;
     if (settings->par <= 0 || settings->par == 1 ||
             !render_priv->frame_content_width || !render_priv->frame_content_height)
         return (ASS_Vector) { track->PlayResX, track->PlayResY };
@@ -3109,9 +3112,10 @@ ass_start_frame(ASS_Renderer *render_priv, ASS_Track *track,
 
     // PAR correction
     double par = render_priv->settings.par;
-    if (par == 0.) {
-        if (render_priv->frame_content_width && render_priv->frame_content_height &&
-                render_priv->settings.storage_width && render_priv->settings.storage_height) {
+    bool lr_track = track->LayoutResX > 0 && track->LayoutResY > 0;
+    if (par == 0. || lr_track) {
+        if (render_priv->frame_content_width && render_priv->frame_content_height && (lr_track ||
+                (render_priv->settings.storage_width && render_priv->settings.storage_height))) {
             double dar = ((double) render_priv->frame_content_width) /
                          render_priv->frame_content_height;
             ASS_Vector layout_res = ass_layout_res(render_priv);
diff --git a/libass/ass_types.h b/libass/ass_types.h
@@ -283,6 +283,9 @@ typedef struct ass_track {
     ASS_Library *library;
     ASS_ParserPriv *parser_priv;
 
+    int LayoutResX;  // overrides values from ass_set_storage_size and
+    int LayoutResY;  // also takes precendence over ass_set_pixel_aspect
+
     // New fields can be added here in new ABI-compatible library releases.
 } ASS_Track;
 
