ConvertBits

From Avisynth wiki
(Difference between revisions)
Jump to: navigation, search
(TODO - placeholder)
 
(→‎ConvertBits)
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
[[TODO]]
+
<div style="max-width:82em; min-width:42em;" >
 +
{{AvsPlusFilter}}
 +
</div>
 +
__NOTOC__
 +
 
 +
<div style="max-width:62em; min-width:42em;" >
 +
<!-- ==== Syntax and Parameters ==== -->
 +
==== ConvertBits ====
 +
Changes bit depth while keeping [[Avisynthplus_color_formats|color format]] the same, if possible. <br>
 +
If the conversion is not possible &ndash; for example, converting [[RGB32]] to 14bit &ndash; an error is raised.
 +
 
 +
 
 +
{{FuncDef
 +
|ConvertBits(clip, int bits [, bool ''truerange'', int ''dither'', int ''dither_bits'', bool ''fulls'', bool ''fulld'' ] )}}
 +
 
 +
 
 +
''(older bit-depth conversion filters &ndash; deprecated)''
 +
 
 +
{{Func3Def
 +
|ConvertToFloat(clip, int bits [, bool ''truerange'', int ''dither'', int ''dither_bits'', bool ''fulls'', bool ''fulld'' ] )
 +
|ConvertTo16bit(clip, int bits [, bool ''truerange'', int ''dither'', int ''dither_bits'', bool ''fulls'', bool ''fulld'' ] )
 +
|ConvertTo8bit(clip, int bits [, bool ''truerange'', int ''dither'', int ''dither_bits'', bool ''fulls'', bool ''fulld'' ] )}}
 +
 
 +
 
 +
:{{Par2||clip|(required)}}
 +
::Source clip.
 +
 
 +
:{{Par2|bits|int|(actual bit depth)}}
 +
::Bit depth of output clip. If provided valid values are: ''8'', ''10'', ''12'', ''14'', ''16'' (integer) or ''32'' (floating point).
 +
::From 3.7.1 parameter is optional since no bitdepth change is needed when doing only range conversion (fulls-fulld) or artistic dithering (dither_bits<bit depth)
 +
::<3.7.1: required
 +
 
 +
:{{Par2|truerange|bool|true}}
 +
::Hint: forget it. Deprecated, do not use. Maybe once removed.
 +
::When converting from true 10-16 bit formats, {{FuncArg|truerange}}=false indicates bitdepth of 16 bits regardless of the 10-12-14 bit format. Not applicable for non planar formats.
 +
 
 +
{{HiddenAnchor|dither}}
 +
:{{Par2|dither|int|-1}}
 +
::*If ''-1'' (default), do not add dither;
 +
::*If ''0'', add [[Ordered_dithering|ordered]] dither;
 +
::*If ''1'', add [[wikipedia:Floyd–Steinberg_dithering|error diffusion (Floyd-Steinberg)]] dither <sup>[http://forum.doom9.org/showthread.php?p=1838145#post1838145 doom9]</sup>
 +
::Dithering is allowed only for scaling down (bit depth reduction), not up. Bit depth can be kept though if a smaller dither_bits is given.
 +
::From 3.7.1: no limit. Note: (behind the scenes) 32 bit float clips are first converted down to 16 (or less if needed) bits, then are further dithered down from this intermediate clip.
 +
::<3.7.1: Dithering is allowed only for 10-16bit (not 32bit float) sources.
 +
 
 +
:{{Par2|dither_bits|int|{{Template:FuncArg|bits}}}}
 +
::Exaggerated dither effect: dither to a lower color depth than required by {{FuncArg|bits}} argument.
 +
::Has no effect if {{FuncArg|dither}}=''-1'' (off).
 +
::* from 3.7.1 Arbitrary number from 1 to {{FuncArg|bits}}, inclusive.
 +
::* <3.7.1: Must be an even number from ''2'' to {{FuncArg|bits}}, inclusive.
 +
::* <3.7.1: In addition, must be >= ({{FuncArg|clip}}.[[Clip_properties#Color_Format|BitsPerComponent]]-8).
 +
:{{Par2|fulls|bool|(auto)}}
 +
::''Use the default value unless you know what you are doing.''
 +
::Default value can come from <code>_ChromaRange</code> frame property
 +
::If ''true'' (RGB default), scale by multiplication: 0-255 &rarr; 0-65535; <p>Note: full scale U and V chroma is specially handled</p>
 +
::if ''false'' (YUV default), scale by [[wikipedia:Arithmetic_shift|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.
 +
 
 +
:{{Par2|fulld|bool|{{Template:FuncArg|fulls}}}}
 +
::''Use the default value unless you know what you are doing.''
 +
::From 3.7.1: can be any combination with {{FuncArg|fulls}}.
 +
::<3.7.1: ''must'' match {{FuncArg|fulls}}.
 +
 
 +
 
 +
:ConvertBits writes <code>_ChromaRange</code> frame property (0-full or 1-limited)
 +
 
 +
<!--
 +
==== Examples ====
 +
<div style="max-width:62em; min-width:42em;" >
 +
<div {{BoxWidthIndent|54|2}} >
 +
#combine greyscale clips into YUVA clip
 +
U8 = source.UToY8()
 +
V8 = source.VToY8()
 +
Y8 = source.ConvertToY()
 +
A8 = source.AddAlphaPlane(128).AToY8()
 +
CombinePlanes(Y8, U8, V8, A8, planes="YUVA", source_planes="YYYY",
 +
\              sample_clip=source) #pixel_type="YUV444P8"
 +
</div>
 +
 
 +
<div {{BoxWidthIndent|54|2}} >
 +
# Copy planes between planar RGB(A) and YUV(A) without any conversion
 +
# yuv 4:4:4 <-> planar rgb
 +
source = last.ConvertBits(32) # 4:4:4
 +
cast_to_planarrgb = CombinePlanes(source, planes="RGB", source_planes="YUV",
 +
\              pixel_type="RGBPS")
 +
# get back a clip identical with "source"
 +
cast_to_yuv = CombinePlanes(cast_to_planarrgb, planes="YUV", source_planes="RGB",
 +
\              pixel_type="YUV444PS")
 +
</div>
 +
 
 +
<div {{BoxWidthIndent|54|2}} >
 +
#create a black and white planar RGB clip using Y channel
 +
#source is a YUV clip
 +
grey = CombinePlanes(source, planes="RGB", source_planes="YYY",
 +
\              pixel_type="RGBP8")
 +
</div>
 +
 
 +
<div {{BoxWidthIndent|54|2}} >
 +
#copy luma from one clip, U and V from another
 +
#source is the template
 +
#sourceY is a Y or YUV clip
 +
#sourceUV is a YUV clip
 +
grey = CombinePlanes(sourceY, sourceUV, planes="YUV",
 +
\              source_planes="YUV", sample_clip = source)
 +
</div>
 +
-->
 +
 
 +
==== Changes ====
 +
{|border=1 cellspacing=1 cellpadding=4
 +
|-
 +
| 3.7.1
 +
|parameter ''bits'' optional
 +
<p>_ChromaRange frame property handling</p>
 +
<p>Free fulls-fulld combination</p>
 +
<p>Free target dither_bits down to 1</p>
 +
<p>Allow dithering from 32 bit float</p>
 +
<p>Allow dithering while keeping actual bit depth (but with a smaller dither_bits)</p>
 +
<p>Specially handled full scale chroma</p>
 +
|-
 +
| 20170310 r2440
 +
| parameter ''dither_bits''
 +
|-
 +
| 20170202 r2420
 +
| parameters ''fulls'', ''fulld''
 +
|}
 +
</div>
 +
 
 +
[[Category:Internal_filters]]
 +
[[Category:Colourspace_Conversion]]
 +
[[Category:Deep_color_tools]]
 
[[Category:Avisynthplus]]
 
[[Category:Avisynthplus]]

Latest revision as of 03:02, 3 December 2023

AVS+
This feature is specific to AviSynthPlus.

It is not supported in other AviSynth versions.


[edit] ConvertBits

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


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


(older bit-depth conversion filters – deprecated)

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


clip   = (required)
Source clip.
int  bits = (actual bit depth)
Bit depth of output clip. If provided valid values are: 8, 10, 12, 14, 16 (integer) or 32 (floating point).
From 3.7.1 parameter is optional since no bitdepth change is needed when doing only range conversion (fulls-fulld) or artistic dithering (dither_bits<bit depth)
<3.7.1: required
bool  truerange = true
Hint: forget it. Deprecated, do not use. Maybe once removed.
When converting from true 10-16 bit formats, truerange=false indicates bitdepth of 16 bits regardless of the 10-12-14 bit format. Not applicable for non planar formats.
int  dither = -1
Dithering is allowed only for scaling down (bit depth reduction), not up. Bit depth can be kept though if a smaller dither_bits is given.
From 3.7.1: no limit. Note: (behind the scenes) 32 bit float clips are first converted down to 16 (or less if needed) bits, then are further dithered down from this intermediate clip.
<3.7.1: Dithering is allowed only for 10-16bit (not 32bit float) sources.
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).
  • from 3.7.1 Arbitrary number from 1 to bits, inclusive.
  • <3.7.1: Must be an even number from 2 to bits, inclusive.
  • <3.7.1: In addition, must be >= (clip.BitsPerComponent-8).
bool  fulls = (auto)
Use the default value unless you know what you are doing.
Default value can come from _ChromaRange frame property
If true (RGB default), scale by multiplication: 0-255 → 0-65535;

Note: full scale U and V chroma is specially handled

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.
From 3.7.1: can be any combination with fulls.
<3.7.1: must match fulls.


ConvertBits writes _ChromaRange frame property (0-full or 1-limited)


[edit] Changes

3.7.1 parameter bits optional

_ChromaRange frame property handling

Free fulls-fulld combination

Free target dither_bits down to 1

Allow dithering from 32 bit float

Allow dithering while keeping actual bit depth (but with a smaller dither_bits)

Specially handled full scale chroma

20170310 r2440 parameter dither_bits
20170202 r2420 parameters fulls, fulld
Retrieved from "http://avisynth.nl/index.php?title=ConvertBits&oldid=13301"
Personal tools