ConvertBits

ConvertBits

Changes bit depth while keeping color format the same, if possible.
If the conversion is not possible – for example, converting RGB32 to 16bit – an error is raised.

ConvertBits(clip, int bits [, bool truerange, int dither, float scale, int dither_bits, bool fulls, bool fulld ] )

(older bit-depth conversion filters – deprecated)

ConvertToFloat(clip, int bits [, bool truerange, int dither, float scale, int dither_bits, bool fulls, bool fulld ] )
ConvertTo16bit(clip, int bits [, bool truerange, int dither, float scale, int dither_bits, bool fulls, bool fulld ] )
ConvertTo8bit(clip, int bits [, bool truerange, int dither, float scale, int dither_bits, bool fulls, bool fulld ] )

clip   = (required)

Source clip.

bits   = (required)

Bit depth of output clip. Valid values: 8, 10, 12, 14, 16 (integer) or 32 (floating point).

bool  truerange = true

Use the default value unless you know what you are doing.

(TODO if false, seems to either do nothing or corrupt output)

Only allowed with Planar color formats.

If true (default), convert 10-16 bit formats without re-scaling underlying pixel data. For example,

  clip10bit.ConvertBits(16, truerange=false)

will leave pixel data in the 0..1023 range, but will change the color format from YUVxxxP10 to YUVxxxP16.

int  dither = -1

If 0, add ordered dither; if -1 (default), do not add dither.

Dithering is allowed only for scaling down (bit depth reduction), not up.

Dithering is allowed only for 10-16bit (not 32bit float) sources.

float  scale = 1.0

Use the default value unless you know what you are doing.

(TODO no apparent change in output)

Only allowed for 32bit → 32bit.

int  dither_bits = bits

Exaggerated dither effect: dither to a lower color depth than required by bits argument.

Has no effect if dither=-1 (off).

• Must be an even number from 2 to bits, inclusive.
• In addition, must be >= (clip.BitsPerComponent-8).

Examples

Conversion	Allowed Values
16 → 12bit	8, 10, 12
16 → 10bit	8, 10
16 →   8bit	8
14 → 10bit	6, 8, 10
14 →   8bit	6, 8
12 → 10bit	4, 6, 8, 10
12 →   8bit	4, 6, 8
10 →   8bit	2, 4, 6, 8

bool  fulls = (auto)

Use the default value unless you know what you are doing.

If true (RGB default), scale by multiplication: 0-255 → 0-65535;

if false (YUV default), scale by bit-shifting.

Use case: override greyscale conversion to fullscale instead of bit-shifts.

Conversion from and to float is always full-scale.

Alpha plane is always treated as full scale.

bool  fulld = fulls

Use the default value unless you know what you are doing.

At the moment, must match fulls.

Changes