Autoscale parameter

Autoscale is the term being used to describe filter and function arguments that adjust themselves to the current bit depth – the BitsPerComponent of the main source clip. A related concept is 'd' notation: 16_d-235_d refers to normal TV-range levels at any bit depth.

bit depth equivalent color values
8	0	16	128	235	255
10	0	64	512	940	1020
12	0	256	2048	3670	4080
14	0	1024	8192	15040	16320
16	0	4096	32768	60160	65280
32	0.0	16/256	128/256	235/256	255/256

[edit] Examples

To see a filter with non-autoscaling arguments, consider Levels:

Levels(clip C, 
\     int input_low, float gamma, int input_high,
\     int output_low, int output_high [, 
\     bool coring, bool dither])

All the arguments in blue expect user inputs in the normal 0-255 range – assuming 8-bit video. For 10-bit, the input range is 0-1023, and for 16-bit, it's 0-65535. Scripts that specify 8-bit Levels arguments need to be altered for use with other bit depths. For those used to "thinking in 8-bit," writing scripts for multiple bit depths can be cumbersome.

That's not to say Levels is wrong or buggy – what it does makes sense: it is the humans that need to adjust. There are utility functions to help with this, which will be discussed below.

Another example is RGBAdjust with its bias arguments: rb=16 always lifts the Red channel by 16 units, whether on the 0-255 or the 0-65535 scale. It does what you say, not necessarily what you mean.

To see a filter with autoscaling arguments, consider ColorYUV:

ColorYUV(clip [,
\    float gain_y, float off_y, float gamma_y, float cont_y,
\    float gain_u, float off_u, float gamma_u, float cont_u,
\    float gain_v, float off_v, float gamma_v, float cont_v,
\    string levels, string opt, bool showyuv, bool analyze,
\    bool autowhite, bool autogain, bool conditional ] ))

The off_x arguments (in blue) add or subtract a given amount from all pixels in the given color channel, and the amount is always on the 0-255 scale – that is, off_y=255 will always turn black to white, at any bit depth.

In 8-bit video, setting off_y=16 will raise all luminance values by 16 units on the 0-255 scale – but in 10-bit video, off_y=16 will raise all luminance values by 64 units on the 0-1023 scale.

The argument value has been adjusted by the filter to give the same visual effect. That's autoscaling.

[edit] User-Defined Autoscaling functions

For filters and function that don't autoscale, there are some helper functions you can call upon, which are included in raffriff42's Utils-r41.avsi script. These three are the ones most important for autoscaling:

sc8f(clip T, float f, [bool cx])

Scale an 8-bit value for target clip T

sc8x(clip T, float f)

Scale an 8-bit value for target clip T; clamp output

sc8s(clip T, float f, [int decimals])

Scale an 8-bit value for target clip T; string result

You can use them to make Levels autoscale, so that the old 8-bit arguments give the same visual result in any bit depth:

function LevelsPlus(clip C, 
\               int input_low, float gamma, int input_high,
\               int output_low, int output_high,
\               bool "coring", bool "dither")
{
    return C.Levels(
    \           C.sc8x(input_low), 
    \           gamma, 
    \           C.sc8x(input_high),
    \           C.sc8x(output_low), 
    \           C.sc8x(output_high), 
    \           coring, dither)
}

LevelsPlus is included in the script previously mentioned.

You don't have to write wrapper scripts like the one above; you can insert them only where needed:

RGBAdjust(rb=sc8f(8), gb=sc8f(-8), bb=sc8f(12)) 

Limiter(min_chroma=sc8x(128-64), max_chroma=sc8x(128+64))

These statements will have the same visual effect at all bit depths.