video: replace vf_format outputlevels option with global option

The vf_format suboption is replaced with --video-output-levels (a global
option and property). In particular, the parameter is removed from
mp_image_params. The mechanism is moved to the "video equalizer", which
also handles common video output customization like brightness and
contrast controls.

The new code is slightly cleaner, and the top-level option is slightly
more user-friendly than as vf_format sub-option.

DOCS/interface-changes.rst

@@ -20,6 +20,8 @@ Interface changes
 ::
 
  --- mpv 0.12.0 ---
+    - replace vf_format outputlevels suboption with "video-output-levels" global
+      property/option; also remove "colormatrix-output-range" property
     - vo_opengl: remove sharpen3/sharpen5 scale filters, add sharpen sub-option
  --- mpv 0.11.0 ---
     - add "af-metadata" property

DOCS/man/input.rst

@@ -1260,8 +1260,8 @@ Property list
 ``colormatrix-input-range`` (R)
     See ``colormatrix``.
 
-``colormatrix-output-range`` (R)
-    See ``colormatrix``.
+``video-output-levels`` (RW)
+    See ``--video-output-levels``,
 
 ``colormatrix-primaries`` (R)
     See ``colormatrix``.

DOCS/man/options.rst

@@ -774,6 +774,26 @@ Video
     For audio-only playback, any value greater than 0 will quit playback
     immediately after initialization. The value 0 works as with video.
 
+``--video-output-levels=<outputlevels>``
+    RGB color levels used with YUV to RGB conversion. Normally, output devices
+    such as PC monitors use full range color levels. However, some TVs and
+    video monitors expect studio RGB levels. Providing full range output to a
+    device expecting studio level input results in crushed blacks and whites,
+    the reverse in dim gray blacks and dim whites.
+
+    Not all VOs support this option. Some will silently ignore it.
+
+    Available color ranges are:
+
+    :auto:      automatic selection (equals to full range) (default)
+    :limited:   limited range (16-235 per component), studio levels
+    :full:      full range (0-255 per component), PC levels
+
+    .. note::
+
+        It is advisable to use your graphics driver's color range option
+        instead, if available.
+
 ``--hwdec-codecs=<codec1,codec2,...|all>``
     Allow hardware decoding for a given list of codecs only. The special value
     ``all`` always allows all codecs.

DOCS/man/vf.rst

@@ -259,26 +259,6 @@ Available filters are:
         :limited:   limited range (16-235 for luma, 16-240 for chroma)
         :full:      full range (0-255 for both luma and chroma)
 
-    ``<outputlevels>``
-        RGB color levels used with YUV to RGB conversion. Normally, output devices
-        such as PC monitors use full range color levels. However, some TVs and
-        video monitors expect studio RGB levels. Providing full range output to a
-        device expecting studio level input results in crushed blacks and whites,
-        the reverse in dim gray blacks and dim whites.
-
-        The same limitations as with ``<colormatrix>`` apply.
-
-        Available color ranges are:
-
-        :auto:      automatic selection (equals to full range) (default)
-        :limited:   limited range (16-235 per component), studio levels
-        :full:      full range (0-255 per component), PC levels
-
-        .. note::
-
-            It is advisable to use your graphics driver's color range option
-            instead, if available.
-
     ``<primaries>``
         RGB primaries the source file was encoded with. Normally this should be set
         in the file header, but when playing broken or mistagged files this can be

options/options.c

@@ -463,6 +463,8 @@ const m_option_t mp_opts[] = {
     OPT_INTRANGE("contrast", gamma_contrast, 0, -100, 100),
     OPT_INTRANGE("hue", gamma_hue, 0, -100, 100),
     OPT_INTRANGE("gamma", gamma_gamma, 0, -100, 100),
+    OPT_CHOICE_C("video-output-levels", video_output_levels, 0,
+                 mp_csp_levels_names),
     OPT_FLAG("keepaspect", vo.keepaspect, 0),
     OPT_FLAG("keepaspect-window", vo.keepaspect_window, 0),
 

options/options.h

@@ -103,6 +103,7 @@ typedef struct MPOpts {
     int gamma_contrast;
     int gamma_saturation;
     int gamma_hue;
+    int video_output_levels;
 
     int stop_screensaver;
     int cursor_autohide_delay;

player/command.c

@@ -2370,18 +2370,19 @@ static int mp_property_framedrop(void *ctx, struct m_property *prop,
 static int mp_property_video_color(void *ctx, struct m_property *prop,
                                    int action, void *arg)
 {
+    const char *name = prop->priv ? prop->priv : prop->name;
     MPContext *mpctx = ctx;
     if (!mpctx->d_video)
         return M_PROPERTY_UNAVAILABLE;
 
     switch (action) {
     case M_PROPERTY_SET: {
-        if (video_set_colors(mpctx->d_video, prop->name, *(int *) arg) <= 0)
+        if (video_set_colors(mpctx->d_video, name, *(int *) arg) <= 0)
             return M_PROPERTY_UNAVAILABLE;
         break;
     }
     case M_PROPERTY_GET:
-        if (video_get_colors(mpctx->d_video, prop->name, (int *)arg) <= 0)
+        if (video_get_colors(mpctx->d_video, name, (int *)arg) <= 0)
             return M_PROPERTY_UNAVAILABLE;
         // Write new value to option variable
         mp_property_generic_option(mpctx, prop, M_PROPERTY_SET, arg);
@@ -2440,8 +2441,6 @@ static int property_imgparams(struct mp_image_params p, int action, void *arg)
             SUB_PROP_STR(m_opt_choice_str(mp_csp_names, p.colorspace))},
         {"colorlevels",
             SUB_PROP_STR(m_opt_choice_str(mp_csp_levels_names, p.colorlevels))},
-        {"outputlevels",
-            SUB_PROP_STR(m_opt_choice_str(mp_csp_levels_names, p.outputlevels))},
         {"primaries",
             SUB_PROP_STR(m_opt_choice_str(mp_csp_prim_names, p.primaries))},
         {"gamma",
@@ -3453,6 +3452,8 @@ static const struct m_property mp_properties[] = {
     {"contrast", mp_property_video_color},
     {"saturation", mp_property_video_color},
     {"hue", mp_property_video_color},
+    {"video-output-levels", mp_property_video_color,
+     .priv = (void *)"output-levels"},
     {"panscan", panscan_property_helper},
     {"video-zoom", panscan_property_helper},
     {"video-align-x", panscan_property_helper},
@@ -3563,7 +3564,6 @@ static const struct m_property mp_properties[] = {
     M_PROPERTY_ALIAS("sub", "sid"),
     M_PROPERTY_ALIAS("colormatrix", "video-params/colormatrix"),
     M_PROPERTY_ALIAS("colormatrix-input-range", "video-params/colorlevels"),
-    M_PROPERTY_ALIAS("colormatrix-output-range", "video-params/outputlevels"),
     M_PROPERTY_ALIAS("colormatrix-primaries", "video-params/primaries"),
     M_PROPERTY_ALIAS("colormatrix-gamma", "video-params/gamma"),
 

player/video.c

@@ -787,6 +787,7 @@ static void init_vo(struct MPContext *mpctx)
         video_set_colors(d_video, "saturation", opts->gamma_saturation);
     if (opts->gamma_hue != 1000)
         video_set_colors(d_video, "hue", opts->gamma_hue);
+    video_set_colors(d_video, "output-levels", opts->video_output_levels);
 
     mp_notify(mpctx, MPV_EVENT_VIDEO_RECONFIG, NULL);
 }

video/csputils.c

@@ -90,6 +90,7 @@ const char *const mp_csp_equalizer_names[MP_CSP_EQ_COUNT] = {
     "hue",
     "saturation",
     "gamma",
+    "output-levels",
 };
 
 const struct m_opt_choice_alternatives mp_chroma_names[] = {
@@ -709,7 +710,6 @@ void mp_csp_set_image_params(struct mp_csp_params *params,
     mp_image_params_guess_csp(&p); // ensure consistency
     params->colorspace = p.colorspace;
     params->levels_in = p.colorlevels;
-    params->levels_out = p.outputlevels;
 }
 
 // Copy settings from eq into params.
@@ -721,6 +721,7 @@ void mp_csp_copy_equalizer_values(struct mp_csp_params *params,
     params->hue = eq->values[MP_CSP_EQ_HUE] / 100.0 * M_PI;
     params->saturation = (eq->values[MP_CSP_EQ_SATURATION] + 100) / 100.0;
     params->gamma = exp(log(8.0) * eq->values[MP_CSP_EQ_GAMMA] / 100.0);
+    params->levels_out = eq->values[MP_CSP_EQ_OUTPUT_LEVELS];
 }
 
 static int find_eq(int capabilities, const char *name)

video/csputils.h

@@ -161,6 +161,7 @@ enum mp_csp_equalizer_param {
     MP_CSP_EQ_HUE,
     MP_CSP_EQ_SATURATION,
     MP_CSP_EQ_GAMMA,
+    MP_CSP_EQ_OUTPUT_LEVELS,
     MP_CSP_EQ_COUNT,
 };
 
@@ -168,7 +169,8 @@ enum mp_csp_equalizer_param {
     ( (1 << MP_CSP_EQ_BRIGHTNESS) \
     | (1 << MP_CSP_EQ_CONTRAST) \
     | (1 << MP_CSP_EQ_HUE) \
-    | (1 << MP_CSP_EQ_SATURATION) )
+    | (1 << MP_CSP_EQ_SATURATION) \
+    | (1 << MP_CSP_EQ_OUTPUT_LEVELS) )
 
 #define MP_CSP_EQ_CAPS_GAMMA (1 << MP_CSP_EQ_GAMMA)
 #define MP_CSP_EQ_CAPS_BRIGHTNESS (1 << MP_CSP_EQ_BRIGHTNESS)

video/filter/vf_format.c

@@ -34,7 +34,6 @@ struct vf_priv_s {
     int outfmt;
     int colormatrix;
     int colorlevels;
-    int outputlevels;
     int primaries;
     int gamma;
     int chroma_location;
@@ -89,8 +88,6 @@ static int reconfig(struct vf_instance *vf, struct mp_image_params *in,
         out->colorspace = p->colormatrix;
     if (p->colorlevels)
         out->colorlevels = p->colorlevels;
-    if (p->outputlevels)
-        out->outputlevels = p->outputlevels;
     if (p->primaries)
         out->primaries = p->primaries;
     if (p->gamma)
@@ -137,7 +134,6 @@ static const m_option_t vf_opts_fields[] = {
     OPT_IMAGEFORMAT("outfmt", outfmt, 0),
     OPT_CHOICE_C("colormatrix", colormatrix, 0, mp_csp_names),
     OPT_CHOICE_C("colorlevels", colorlevels, 0, mp_csp_levels_names),
-    OPT_CHOICE_C("outputlevels", outputlevels, 0, mp_csp_levels_names),
     OPT_CHOICE_C("primaries", primaries, 0, mp_csp_prim_names),
     OPT_CHOICE_C("gamma", gamma, 0, mp_csp_trc_names),
     OPT_CHOICE_C("chroma-location", chroma_location, 0, mp_chroma_names),
@@ -147,6 +143,7 @@ static const m_option_t vf_opts_fields[] = {
     OPT_INT("dw", dw, 0),
     OPT_INT("dh", dh, 0),
     OPT_DOUBLE("dar", dar, 0),
+    OPT_REMOVED("outputlevels", "use the --video-output-levels global option"),
     {0}
 };
 

video/mp_image.c

@@ -394,7 +394,6 @@ void mp_image_copy_attributes(struct mp_image *dst, struct mp_image *src)
         dst->params.colorspace = src->params.colorspace;
         dst->params.colorlevels = src->params.colorlevels;
         dst->params.chroma_location = src->params.chroma_location;
-        dst->params.outputlevels = src->params.outputlevels;
     }
     mp_image_params_guess_csp(&dst->params); // ensure colorspace consistency
     if ((dst->fmt.flags & MP_IMGFLAG_PAL) && (src->fmt.flags & MP_IMGFLAG_PAL)) {
@@ -491,10 +490,6 @@ char *mp_image_params_to_str_buf(char *b, size_t bs,
                         m_opt_choice_str(mp_csp_levels_names, p->colorlevels));
         mp_snprintf_cat(b, bs, " CL=%s",
                         m_opt_choice_str(mp_chroma_names, p->chroma_location));
-        if (p->outputlevels) {
-            mp_snprintf_cat(b, bs, " out=%s",
-                    m_opt_choice_str(mp_csp_levels_names, p->outputlevels));
-        }
         if (p->rotate)
             mp_snprintf_cat(b, bs, " rot=%d", p->rotate);
         if (p->stereo_in > 0 || p->stereo_out > 0) {
@@ -541,7 +536,6 @@ bool mp_image_params_equal(const struct mp_image_params *p1,
            p1->d_w == p2->d_w && p1->d_h == p2->d_h &&
            p1->colorspace == p2->colorspace &&
            p1->colorlevels == p2->colorlevels &&
-           p1->outputlevels == p2->outputlevels &&
            p1->primaries == p2->primaries &&
            p1->gamma == p2->gamma &&
            p1->chroma_location == p2->chroma_location &&

video/mp_image.h

@@ -46,10 +46,6 @@ struct mp_image_params {
     enum mp_csp_prim primaries;
     enum mp_csp_trc gamma;
     enum mp_chroma_location chroma_location;
-    // The image should be converted to these levels. Unlike colorlevels, it
-    // does not describe the current state of the image. (Somewhat similar to
-    // d_w/d_h vs. w/h.)
-    enum mp_csp_levels outputlevels;
     // The image should be rotated clockwise (0-359 degrees).
     int rotate;
     enum mp_stereo3d_mode stereo_in;    // image is encoded with this mode

video/out/vo_vdpau.c

@@ -948,10 +948,6 @@ static struct mp_image *read_output_surface(struct vo *vo,
     if (!image)
         return NULL;
 
-    image->params.colorspace = MP_CSP_RGB;
-    // hardcoded with conv. matrix
-    image->params.colorlevels = vo->params->outputlevels;
-
     void *dst_planes[] = { image->planes[0] };
     uint32_t dst_pitches[] = { image->stride[0] };
     vdp_st = vdp->output_surface_get_bits_native(surface, NULL, dst_planes,

video/sws_utils.c

@@ -161,7 +161,6 @@ int mp_sws_reinit(struct mp_sws_context *ctx)
     // Neutralize unsupported or ignored parameters.
     src->d_w = dst->d_w = 0;
     src->d_h = dst->d_h = 0;
-    src->outputlevels = dst->outputlevels = MP_CSP_LEVELS_AUTO;
 
     if (cache_valid(ctx))
         return 0;