Avisynth wiki - User contributions [en]

Filter SDK/SimpleSample

2016-06-11T12:25:50Z

Jmac698:

Note: An updated version of this example with source code, documentation, and Avisynth test scripts in available at http://forum.doom9.org/showthread.php?p=1656962#post1656962

I have rewritten SimpleSample for AviSynth 2.6. I changed it into an in place filter (so the source is overwritten). It draws a white square in the center of the clip and it supports all colorformats.

Here's simplesample.cpp:

#include <windows.h>
#include "avisynth.h"

class SimpleSample : public GenericVideoFilter {
int SquareSize;
public:
SimpleSample(PClip _child, int _SquareSize, IScriptEnvironment* env);
~SimpleSample();
PVideoFrame __stdcall GetFrame(int n, IScriptEnvironment* env);
};

SimpleSample::SimpleSample(PClip _child, int _SquareSize, IScriptEnvironment* env) :
GenericVideoFilter(_child), SquareSize(_SquareSize) {
if (vi.width<SquareSize || vi.height<SquareSize) {
env->ThrowError("SimpleSample: square doesn't fit into the clip!");
}
}

SimpleSample::~SimpleSample() {}

PVideoFrame __stdcall SimpleSample::GetFrame(int n, IScriptEnvironment* env) {

PVideoFrame src = child->GetFrame(n, env);
env->MakeWritable(&src);

unsigned char* srcp = src->GetWritePtr();
int src_pitch = src->GetPitch();
int src_width = src->GetRowSize();
int src_height = src->GetHeight();

int w, h, woffset;

if (vi.IsRGB24()) {
srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

woffset = src_width/2 - 3*SquareSize/2;

for (h=0; h<SquareSize; h++) {
for (w=0; w<3*SquareSize; w+=3) {
*(srcp + woffset + w) = 255;
*(srcp + woffset + w + 1) = 255;
*(srcp + woffset + w + 2) = 255;
}
srcp += src_pitch;
}
}
if (vi.IsRGB32()) {
srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

woffset = src_width/2 - 4*SquareSize/2;

for (h=0; h<SquareSize; h++) {
for (w=0; w<4*SquareSize; w+=4) {
*(srcp + woffset + w) = 255;
*(srcp + woffset + w + 1) = 255;
*(srcp + woffset + w + 2) = 255;
}
srcp += src_pitch;
}
}
/*
if (vi.IsRGB32()) { // variant 1 - processing a pixel at once
srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

woffset = src_width/8 - SquareSize/2;

for (h=0; h<SquareSize; h++) {
for (w=0; w<SquareSize; w++) {
*((unsigned int *)srcp + woffset + w) = 0x00FFFFFF;
}
srcp += src_pitch;
}
}
*/
/*
if (vi.IsRGB32()) { // variant 2 - processing a pixel at once
unsigned int* srcp = (unsigned int*)src->GetWritePtr();

srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch/4;

woffset = src_width/8 - SquareSize/2;

for (h=0; h<SquareSize; h++) {
for (w=0; w<SquareSize; w++) {
srcp[woffset + w] = 0x00FFFFFF;
}
srcp += src_pitch/4;
}
}
*/
if (vi.IsYUY2()) {
srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

woffset = src_width/8 - SquareSize/4;

for (h=0; h<SquareSize; h++) {
for (w=0; w<SquareSize/2; w++) {
*((unsigned int *)srcp + woffset + w) = 0x80EB80EB;
}
srcp += src_pitch;
}
}
if (vi.IsPlanar() && vi.IsYUV()) {

int planes[] = {PLANAR_Y, PLANAR_U, PLANAR_V};
int square_value[] = {235, 128, 128};
int p;
int width_sub, height_sub;

for (p=0; p<3; p++) {
srcp = src->GetWritePtr(planes[p]);
src_pitch = src->GetPitch(planes[p]);
src_width = src->GetRowSize(planes[p]);
src_height = src->GetHeight(planes[p]);
width_sub = vi.GetPlaneWidthSubsampling(planes[p]);
height_sub = vi.GetPlaneHeightSubsampling(planes[p]);

srcp = srcp + (src_height/2 - (SquareSize>>height_sub)/2) * src_pitch;

woffset = src_width/2 - (SquareSize>>width_sub)/2;

for (h=0; h<(SquareSize>>height_sub); h++) {
for (w=0; w<(SquareSize>>width_sub); w++) {
srcp[woffset + w] = square_value[p];
}
srcp += src_pitch;
}
}
}

return src;
}

AVSValue __cdecl Create_SimpleSample(AVSValue args, void* user_data, IScriptEnvironment* env) {
return new SimpleSample(args[0].AsClip(),
args[1].AsInt(100),
env);
}

const AVS_Linkage *AVS_linkage = 0;

extern "C" __declspec(dllexport) const char* __stdcall AvisynthPluginInit3(IScriptEnvironment* env, const AVS_Linkage* const vectors) {
AVS_linkage = vectors;
env->AddFunction("SimpleSample", "c[size]i", Create_SimpleSample, 0);
return "SimpleSample plugin";
}

Compile this file into a DLL named InvertNeg.dll. See [[Filter_SDK/Compiling_instructions|compiling instructions]]. Now create an Avisynth script which looks something like this:

LoadPlugin("d:\path\simplesample.dll")
Colorbars().Trim(0,1)
ConvertTORGB32()
# ConvertTOYV411()
SimpleSample(100)

=== Line by line breakdown ===

Here's a line-by-line breakdown of simplesample.cpp. I won't repeat the comments in the previous example InvertNeg.cpp, so read that first if needed. The declaration of the class is as follows

class SimpleSample : public GenericVideoFilter {
int SquareSize;
public:
SimpleSample(PClip _child, int _SquareSize, IScriptEnvironment* env);
~SimpleSample();
PVideoFrame __stdcall GetFrame(int n, IScriptEnvironment* env);
};

With respect to our previous example there are two differences. It contains a private data member 'SquareSize' (members are private by default). Note that this is our parameter variable. These have to be declared here.

The member function ~SimpleSample() is the declaration of the destructor. It fulfills the opposite functionality as the constructor. It is automatically called when the filter is destroyed. It is used to release allocated memory when the filter is destroyed. This is needed when there is memory allocated in the constructor. This is not the case in our filter, so we didn't need to declare it.

SimpleSample::~SimpleSample() {}

This is the actual destructor. You can release allocated memory here using the operator delete.

SimpleSample::SimpleSample(PClip _child, int _SquareSize, IScriptEnvironment* env) :
GenericVideoFilter(_child), SquareSize(_SquareSize) {
if (vi.width<SquareSize || vi.height<SquareSize) {
env->ThrowError("SimpleSample: square doesn't fit into the clip!");
}
}

This is the constructor. It initializes the value of SquareSize with the parameter that is passed to it (which is called _SquareSize here). It also checks whether the square which will be drawn fits in the frame, otherwise it will return an error.

unsigned char* srcp = src->GetWritePtr();
int src_pitch = src->GetPitch();
int src_width = src->GetRowSize();
int src_height = src->GetHeight();

The default value of plane is PLANAR_Y (= 0) for the functions GetReadPtr, GetWritePtr, GetPitch, GetRowSize and GetHeight. For planar formats this is the luma plane and for interleaved formats this is the whole frame.

if (vi.IsRGB24()) {

When the clip has color format RGB24 the code path is taken. For RGB24 each pixel is represented by three bytes, blue, green and red (in that order). RGB is up side down, so srcp[0] will be the bottom-left pixel.

srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

The pointer is moved to the lower line of the square that will be drawn. Remember that src_height is the height in pixels.

woffset = src_width/2 - 3*SquareSize/2;

The offset is calculated of the left most byte of the square that will be drawn. Remember that src_width is the width in bytes. Since SquareSize is specified in pixels, the corresponding number of bytes is 3*SquareSize.

for (h=0; h<SquareSize; h++) { // Loop from bottom line to top line.
for (w=0; w<3*SquareSize; w+=3) { // Loop from left side of the image to the right side 1 pixel (3 bytes) at a time
*(srcp + woffset + w) = 255; // this is the same as srcp[woffset+w]=255;
*(srcp + woffset + w + 1) = 255; // this is the same as srcp[woffset+w+1]=255;
*(srcp + woffset + w + 2) = 255; // this is the same as srcp[woffset+w+2]=255;
}
srcp += src_pitch;
}
}

Here the white square is drawn. Each color component is set to 255.

For RGB32 the following code path is taken

if (vi.IsRGB32()) {
srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

woffset = src_width/2 - 4*SquareSize/2;

for (h=0; h<SquareSize; h++) {
for (w=0; w<4*SquareSize; w+=4) {
*(srcp + woffset + w) = 255;
*(srcp + woffset + w + 1) = 255;
*(srcp + woffset + w + 2) = 255;
}
srcp += src_pitch;
}
}

It's the same as for RGB24, except a pixel is represented by four bytes, blue, green, red and alpha (in that order). Since SquareSize is specified in pixels, the corresponding number of bytes is 4*SquareSize. The fourth color component, the alpha channel, *(srcp + woffset + w + 3) is left untouched.

It is possible to speed the code above up a bit since you can deal with whole 32bit variables at a time. This can be done in several ways:

if (vi.IsRGB32()) { // variant 1 - processing a pixel at once
srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

woffset = src_width/8 - SquareSize/2; // src_width/2 bytes equals src_width/8 pixels

for (h=0; h<SquareSize; h++) {
for (w=0; w<SquareSize; w++) {
*((unsigned int *)srcp + woffset + w) = 0x00FFFFFF;
}
srcp += src_pitch;
}
}

You need to cast srcp as unsigned int (instead of unsigned char). unsigned int is 4 bytes or 32 bits (it runs from 0 to 2^32-1), which is exactly what we need for one pixel. The casting is done in this line

*((unsigned int *)srcp + woffset + w) = 0x00FFFFFF;

The value of a white pixel is 0x00FFFFFF (where the alpha pixel is set to black). When writing several bytes at once, you need to write the right one first and the left one last.

It is also possible to declare srcp as unsigned int when defining it, but you have to take it into account in the rest of the code:

if (vi.IsRGB32()) { // variant 2 - processing a pixel at once
unsigned int* srcp = (unsigned int*)src->GetWritePtr();

srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch/4;

woffset = src_width/8 - SquareSize/2;

for (h=0; h<SquareSize; h++) {
for (w=0; w<SquareSize; w++) {
srcp[woffset + w] = 0x00FFFFFF;
}
srcp += src_pitch/4;
}
}

Remember that src_pitch is given in bytes and it is equal to src_pitch/4 pixels.

For YUY2, each 4 byte sequence represents 2 pixels, (Y1, U, Y2 and then V). So we can write two pixels at once by recasting again.

if (vi.IsYUY2()) {
srcp = srcp + (src_height/2 - SquareSize/2) * src_pitch;

woffset = src_width/8 - SquareSize/4;

for (h=0; h<SquareSize; h++) {
for (w=0; w<SquareSize/2; w++) { // we are writing two pixels at once
*((unsigned int *)srcp + woffset + w) = 0x80EB80EB; // VY2UY1; Y1=Y2=0xEB=235, U=V=0x80=128
}
srcp += src_pitch;
}
}

At last we move on to the YUV planar formats. Since we are processing the color components independently we can loop over the planes.

if (vi.IsPlanar() && vi.IsYUV()) {

All planar YUV formats in the 2.6 api are: YV24, YV16, YV12, YV411 and Y8.

int planes[] = {PLANAR_Y, PLANAR_U, PLANAR_V};
int square_value[] = {235, 128, 128};
int p;
int width_sub, height_sub;

for (p=0; p<3; p++) {
srcp = src->GetWritePtr(planes[p]);
src_pitch = src->GetPitch(planes[p]);
src_width = src->GetRowSize(planes[p]);
src_height = src->GetHeight(planes[p]);
width_sub = vi.GetPlaneWidthSubsampling(planes[p]);
height_sub = vi.GetPlaneHeightSubsampling(planes[p]);

Since the planes have unequal width (measured in bytes; same for height) we will need their subsampling. The functions [[Filter_SDK/Cplusplus_API/VideoInfo|GetPlaneWidthSubsampling]] and [[Filter_SDK/Cplusplus_API/VideoInfo|GetPlaneHeightSubsampling]] are new in the 2.6 api. They return the horizontal and vertical subsampling of the plane compared to the luma plane. The subsampling of the formats is:

{| border="1"
|-
| color format
| GetPlaneWidthSubsampling(PLANAR_U)
| GetPlaneHeightSubsampling(PLANAR_U)
|-
| YV24
| 0
| 0
|-
| YV16
| 1
| 0
|-
| YV12
| 1
| 1
|-
| YV411
| 2
| 1
|-
| Y8
| 0 ?
| 0 ?
|}

The chroma planes PLANAR_U and PLANAR_V have the same subsampling. Also GetPlaneWidthSubsampling(PLANAR_Y) = GetPlaneHeightSubsampling(PLANAR_Y) = 0 since PLANAR_Y is not subsampled.

srcp = srcp + (src_height/2 - (SquareSize>>height_sub)/2) * src_pitch;

Note SquareSize is specified in pixels and src_height the height of the samples of plane p. Let's look at YV12 for example. For the luma plane we have SquareSize>>0 = SquareSize since there is no subsampling and for the chroma planes we have SquareSize>>1 = SquareSize/2 since there are twice as many luma samples as chroma samples horizontally.

woffset = src_width/2 - (SquareSize>>width_sub)/2;

The vertical subsampling is taken into account again.

for (h=0; h<(SquareSize>>height_sub); h++) {
for (w=0; w<(SquareSize>>width_sub); w++) {
srcp[woffset + w] = square_value[p];
}
srcp += src_pitch;
}
}
}

Here the white square is drawn. The luma pixels will get the value square_value[PLANAR_Y] = 235, and the chroma pixels will get the value square_value[PLANAR_U] = 128 (idem for PLANAR_V).

AVSValue __cdecl Create_SimpleSample(AVSValue args, void* user_data, IScriptEnvironment* env) {
return new SimpleSample(args[0].AsClip(),
args[1].AsInt(100),
env);
}

args[0], args[1], ... are the arguments of the filter. Here there are two arguments. The first one is of type clip and the second one of type int (with default value 100). You can pre-process or post-process your variables (and clips) here too. See DirectShowSource for some examples.

extern "C" __declspec(dllexport) const char* __stdcall AvisynthPluginInit3(IScriptEnvironment* env, const AVS_Linkage* const vectors) {
AVS_linkage = vectors;
env->AddFunction("SimpleSample", "c[size]i", Create_SimpleSample, 0);
return "SimpleSample plugin";
}

The [[Filter_SDK/Cplusplus_API#AddFunction|AddFunction]] has the following parameters:

AddFunction(Filtername, Arguments, Function to call, 0);

''Arguments'' is a string that defines the types and optional names of the arguments for your filter. The possible types are:

# Argument type specifier strings
c - clip
i - integer
f - float
s - string
b - boolean
. - Any type (dot)
# Array Specifiers (have a look at StackVertical and SelectEvery for example as to how access such arrays)
i* - Integer Array, zero or more
i+ - Integer Array, one or more
.* - Any type Array, zero or more
.+ - Any type Array, one or more

The text inside the [ ] lets you used named parameters in your script. Thus

clip = ...
SimpleSample(clip, size=100)

but

clip = ...
SimpleSample(clip, 100)

works as well. See [[Filter_SDK/InvertNeg|InvertNeg]] for more information.

=== Old versions ===

[[Filter_SDK/Simple_sample|Simple sample]] <need to move the old examples>

[[Category:FilterSDK]]

Avisynth Plugin Development in C

2016-06-11T11:57:47Z

Jmac698:

Note: This guide is in development. Currently, only the section [[Avisynth_Plugin_Development_in_C#Compiling_Your_First_Plugin|Compiling Your First Plugin]] has been tested. The rest contains some errors, so use at your own risk!

Note: for new development, it is recommended to develop in C++ using the Avisynth 2.6 API. Please refer to the guide, [[Avisynth Plugin Development in CPP]]

Original written by jmac698 with corrections by the Avisynth community.

==Introduction==
This tutorial takes you step-by-step through the process of creating a new C plugin for AviSynth by modifying an existing example. By the end of this tutorial, you should be able a plugin which returns a normal value or which works on a single frame. The target audience is the beginning level C programmer.

==Why Develop a Plugin in C?==
Some reasons to use C based plugin development are that,

*Free compilers can be used, such as MingW and online code editors such as https://codeanywhere.com/features/editor; only Microsoft Visual C++ or the free Community Edition may be used to create AviSynth C++ plugins
*You are only familiar with C
*It may be simpler to learn for a beginner
*There is no download (with online code editor) or small download (with mingw)
*You want to use any .NET language, PureBasic, or Delphi

==Choosing a License==
Before starting development, be aware of these license requirements:

*The 2.6 C API requires that your plugin uses the GPL license. The GPL license requires that you release the source code.
*The 2.5 C API can use your own license, but the complete source of AviSynth 2.5 and the C API header must be made available along with your plugin binary

==Plugin Compatibility==
Plugins programmed in the 2.5 C API can also be used with higher versions of AviSynth, however they can't access any newer features.

==Setting up your Development Environment==
This tutorial was developed with Code::Blocks, a free development environment. Please follow these steps:

*Download <tt>codeblocks-13.12mingw-setup.exe</tt> from the [http://www.codeblocks.org/downloads/binaries CodeBlocks homepage] and run it
*The first screen reads "Welcome to the CodeBlocks Setup Wizard". Click Next.
*The GPL license is displayed. Click I Agree.
*Choose any extra components to install if desired, but the default is sufficient. Click Next.
*Choose a destination folder. Click Install. Complete the wizard.

==Compiling Your First Plugin==
Before making our own plugin, first we will learn how to compile an existing plugin. Please follow these steps:

*Ensure that you included the option "Install FilterSDK" when installing AviSynth; otherwise reinstall AviSynth with that option.
*Create a C Projects folder under My Documents.
*Obtain the sample plugin Demosaic from [http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip]. Unzip the files to C Projects. There should now be demosaic, avisynth_c and avisynth_c_2_5 folders.
*Delete the avisynth_c and avisynth_c_2_5 folders.
*Delete this file from demosaic: makefile
*Make a new folder, lib under Demosaic.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\Extras\avisynth.lib to demosaic\lib.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\FilterSDK\include\avisynth_c.h to demosaic.
*Start Code::Blocks. Click Create a new project.
*Click Projects, then click Dynamic Link Library, then click Go.
*The wizard page "Dynamic Link Library" appears. Click Next.
*For Project title, use Demosaic. Choose the My Documents\C Projects folder you created in a previous step. Click Next.
*Under compiler, choose GNU GCC Compiler. Accept the defaults and click Finish.
*Right click "Demosaic", and choose Remove files. A list showing main.cpp and main.h appear. Click OK. Click Yes.
*Delete these files from demosaic: main.cpp, main.h
*Right click "Demosaic" and choose Add Files. Add the demosaic.cpp file found in demosaic.
*A window asks you to choose which targets the file belongs to. Click OK.
*Right click Demosaic and choose Add Files. Add the avisynth_c.h file found in 'demosaic. Click OK.
*Select the menu Project->Build Options.... Select Demosaic in the tree.
*Select the tab Linker settings. Click Add. Browse for the file Demosaic\lib\avisynth.lib.
*You are asked "Keep this as a relative path?". Click Yes. Click OK. Click OK.
*Select the menu Build->Select target->Release.
*Select the menu Build->Build.
*Verify that the file demosaic\bin\Release\Demosaic.dll was made. Copy this file to your (C:\Program Files\ or other installation directory then:) AviSynth 2.5 folder.
*Test the plugin by writing an AviSynth script:

Load_Stdcall_Plugin("Demosaic.dll")
colorbars(pixel_type="YV12")
Demosaic()

This should display a grey test pattern with some colour fringes.

*Save the project with File->Save project.

Troubleshooting:

*Note that I found problems using full paths with spaces. The .lib file can only be found when placed in a folder lib and using relative paths.
*If you have a script error, try using the original demosaic.dll in the Demosaic folder. Note that this file starts with a lower case d, so adjust your script accordingly.
*The test.avs which comes with the plugin uses <code>LoadCPlugin</code>. It is better to use <code>Load_Stdcall_Plugin</code> because the <code>avisynth_c.dll</code> plugin may be auto-loaded. This is a plugin which overrides the functionality of <code>LoadCPlugin</code>, such that it won't load <tt>demosaic.dll</tt> anymore.

==Passing Parameters to your Plugin==
For this example, again we will start with the C source of Demosaic ([http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip])

The example source defines a function, in AviSynth script terms, as:

Demosaic(clip clip1, string "mosaic")

However, for our purposes we want to define a plugin like this:

Merge(clip clip1, clip clip2, int weight)

Step 1: Define a place to store the parameters

In this step, we will change the existing code:

<pre>enum Mosaic {
BAYER
};
struct Demosaic {
Mosaic mosaic;
};

Into a new version:
struct Params
{
AVS_Clip* clip2;
int Weight;
};</pre>

Step 2: Tell Avisynth to parse the new parameters 
In this step, we will use a special code to inform the Avisynth parser to look for, and save our parameters. We will change the existing code:

<pre>const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Demosaic", "c[mosaic]s", create_filter, 0);
return "Demosaic plugin";
}</pre>

To the new version:
const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Merge", "cc[weight]i", create_filter, 0);
return "Merge plugin";
}

The:
return "Merge plugin";

statement returns a value to the LoadCPlugin() command (in AviSynth script) upon loading our plugin. In practice, almost no one checks this return value. The code
avs_add_function(env, "Merge", "c[weight]i", create_filter, 0);

does a few things; first "Merge" will be the name of our AviSynth script function (i.e., in the same sense that "[[Tweak]]" is a built-in function). Next, we use a special code to define the expected parameters. In this case, "c" refers to a clip while "i" refers to an int. If we had used "ci", the function would simply expect a clip and an int, like this: <code>Merge(clip1,2)</code> However, we wanted to use a named parameter, which is an optional parameter in functions which can also be named and placed in any order. For example, we could use this script:

Merge(clip1,weight=2)

or simply leave it out:

Merge(clip1)
To specify the name, we include it in square brackets before the parameter type, which in this example, is "[weight]i".

Reference

The special codes for defining your parameters: 'c' for clip, 'i' for integer, 's' for string, 'b' for boolean, and 'f' for float There are a few more features which are explained at: [http://www.kevina.org/avisynth_c/example.html AviSynth C Interface Illustrated Example] by Kevin Atkinson.

Step 3: Fetching and checking your parameters In this final step, we will actually read the parameters which the AviSynth parser has saved for us. We will change the original code:

int pnum = 0;
++pnum; mosaic_str = avs_defined(avs_array_elt(args, pnum)) ? avs_as_string(avs_array_elt(args, pnum)) : "Bayer";

To the following:
int pnum = 0;
++pnum; params->clip2 = avs_defined(avs_array_elt(args, pnum)) ? avs_take_clip(avs_array_elt(args, pnum), env) : 0;
++pnum; params->weight = avs_defined(avs_array_elt(args, pnum)) ?
avs_as_int(avs_array_elt(args, pnum)) : 1; // Default value for weight here

It turns out that avs_array_elt contains our list of arguments in the order they were supplied in the script. We are going to expect the first parameter to be a clip, and the second to be an int. The first element, numbered 0, in the array is the value of last, which is also our first clip. pnum will be a counter to fetch each parameter, starting with number 1 (int pnum=0; ++pnum leaves pnum=1). avs_defined() is a function which checks to see if the parameter exists. So we are seeing if parameter #1 exists, and if so, assign it to params->clip2 which is the structure we've defined to hold our parameters. If it doesn't exists, we'll just put a 0 there. The function avs_take_clip actually takes our clip.

In the second parameter fetch, we use avs_as_int to fetch our weight. This function doesn't need an "env" argument. Instead of return 0 if the parameter isn't there, we will take the opportunity to also set a default value for weight here.

Next comes checking the parameters. Even though it seems like we've saved the values, we actually don't know what they really are - they're just data at this point, that we've assumed were a clip and an int. Next we have to actually double-check this. Original code:
// Check params
retval = avs_void;
if (stricmp(mosaic_str, "bayer") == 0)
params->mosaic = BAYER;
else
retval = avs_new_value_error("Mosaic mode can be: \"Bayer\"");
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi) && !avs_is_yv12(&fi->vi) && !avs_is_y8(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2, YV12, Y8");
}

New code:
// Check params
retval = avs_void;
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2");
}
if (!avs_defined(retval) && !avs_is_int(params->weight) {
retval = avs_new_value_error("weight must be an int");
}

There's a few things to go over here. First of all, in the larger context we are defining what our plugin returns here, and that is what retval is. If you return void, it's the same as returning nothing - you'd see "Not a clip" if you tried to play it. We will cover returning a new clip shortly. !avs_defined(retval) is basically saying, "if retval hasn't been defined yet...", and this is logic to continue checking parameters. In other words, if one of these checks fails, we will set an error message clip as a retval, then the next check will be skipped because a retval has been set. It's just a way to check each parameter just once and skip all other checks as soon as a problem is found. Now for the actual checking: !avs_is_yuy2(&fi->vi) checks the colour format of our first clip; there are predefined functions for checking every format. Likewise, !avs_is_int(params->weight) checks if our weight is really an int. avs_new_value_error() is a function that creates a new video clip with a message in it, similar to messageclip() in script. We use this to inform the user of the error. If all parameters are found to be correct, we finally return the output clip. Original code (unchanged):
// If no errors, all is fine, return clip value
if (!avs_defined(retval)) {
retval = avs_new_value_clip(new_clip);
}

Reference There are numerous checks for video type:
int avs_is_rgb(const AVS_VideoInfo * p)
int avs_is_rgb24(const AVS_VideoInfo * p)
int avs_is_rgb32(const AVS_VideoInfo * p)
int avs_is_yuy(const AVS_VideoInfo * p)
int avs_is_yuy2(const AVS_VideoInfo * p)
int avs_is_yv12(const AVS_VideoInfo * p)

There are various checks for other parameters:
int avs_defined(AVS_Value v)
int avs_is_clip(AVS_Value v)
int avs_is_bool(AVS_Value v)
int avs_is_int(AVS_Value v)
int avs_is_float(AVS_Value v)
int avs_is_string(AVS_Value v)
int avs_is_array(AVS_Value v)
int avs_is_error(AVS_Value v)

And as mentioned, we can return an error clip or a new clip; we can also return int, float, and string values which can be read by the runtime environment:
AVS_Value avs_new_value_bool(int v0)
AVS_Value avs_new_value_int(int v0)
AVS_Value avs_new_value_string(const char * v0)
AVS_Value avs_new_value_float(float v0)
AVS_Value avs_new_value_error(const char * v0)
AVS_Value avs_new_value_clip(AVS_Clip * v0)
AVS_Value avs_new_value_array(AVS_Value * v0, int size)

For more information, please review [http://www.kevina.org/avisynth_c/api.html AviSynth C Interface API Reference].

==Writing the actual function==
After all that work, finally we can write a few simple lines of code to actually merge our videos! However, there's *still* a few more things you need to know. The various video formats are stored in memory in different ways; although we've got a pointer to an area of memory which holds our video, it can be *interpreted* in different ways, even though it's the same size! This is where handling of YUY2 vs YV12 and RGB comes in. We'll start with YUY2 in our example. YUY2 is where every two luma pixels share a color. A color is stored as two values, U and V. We won't go into what U and V means, except to say that if you average two pixels together, everything works out. YUY2 is stored in this format in memory, from the initial pointer to increasing values in memory, a byte at a time: Y1 U Y2 V. If you access the memory 4 bytes at a time (that is, as a 32 bit unsigned int), due to the Intel assembly stored values as Least Significant Byte order, the int would look like this: 0xVVYYUUYY, where each doubled letter represents one HEX value. For example, if our pixels were Y1=35, Y2=40, U=V=128 (which I'll tell you represents no color or grey), we'd have a hex value of 0x80288023. I mention that only as a reminder for the optimizing section. For now we'll simply deal with them as bytes for clarity. New code:
aY1=src_data[x];
bY1=clip2_data[x];
aU=src_data[x+1];
bU=clip2_data[x+1];
aY2=src_data[x+2];
bY2=clip2_data[x+2];
aV=src_data[x+3];
bV=clip2_data[x+3];

Will give us a pair of pixels each from the two input clips in easy to use byte values. Finally, *finally*, we can simply write these 4 lines of code to finish our function:
dest_data[x+1] = (aU/weight+bU*weight);
dest_data[x+3] = (aV/weight+bV*weight);
dest_data[x+0] = (aY1/weight+bY1*weight);
dest_data[x+2] = (aY2/weight+bY2*weight);

Just remember, again, that [x] is Y1, [x+1] is U, [x+2] is Y2, and [x+3] is V.

==Putting it all together==
Download and compile the final sample code from .... Install, then open the Merge.cbp file, the project for Code::Blocks. Simply Build->Build. You now have a fresh merge.dll in your project directory. In order to test it, I've include some simple windows batch files. Double click the install.bat icon. This will copy the merge.dll to your AviSynth directory. Note: ensure that you have no scripts open using the plugin, or the file will fail to overwrite any existing plugin version in your AviSynth directory. Next, open merge.avs in for example AvsP, then press F5. You should see a semitransparent message overlaid on the background. The weight value will change the degree of transparency, where a higher value makes the message stronger.

==Conclusion==
In this manual, we've covered the basic steps necessary to convert an existing example to a new filter, with pointers on how to extend the concepts to include any set of parameters, to return a clip or runtime variable, and to access pixels pairs as stored in YUY2 colour format. In the next set of tutorials, it is planned to cover other colour formats, and some notes on optimizing your code for better execution speed. I hope you have found this tutorial useful. If you have any comments or corrections, please see the ongoing discussion at: http://forum.doom9.org/forumdisplay.php?f=69

==External Links==
*[http://forum.doom9.org/showthread.php?p=1465008#post1465008 Doom9 Forum] - Includes corrections and additional information.
*[http://forum.doom9.org/showthread.php?p=1688939#post1688939 Doom9 Forum] - Continued discussion.

[[Category:AviSynth_Development]]
[[Category:FilterSDK]]

Avisynth Plugin Development in C

2016-06-11T11:48:12Z

Jmac698:

Note: This guide is in development. Currently, only the section [[Avisynth_Plugin_Development_in_C#Compiling_Your_First_Plugin|Compiling Your First Plugin]] has been tested. The rest contains some errors, so use at your own risk!

Original written by jmac698 with corrections by the Avisynth community.

==Introduction==
This tutorial takes you step-by-step through the process of creating a new C plugin for AviSynth by modifying an existing example. By the end of this tutorial, you should be able a plugin which returns a normal value or which works on a single frame. The target audience is the beginning level C programmer.

==Why Develop a Plugin in C?==
Some reasons to use C based plugin development are that,

*Free compilers can be used, such as MingW and online code editors such as https://codeanywhere.com/features/editor; only Microsoft Visual C++ or the free Community Edition may be used to create AviSynth C++ plugins
*You are only familiar with C
*It may be simpler to learn for a beginner
*There is no download (with online code editor) or small download (with mingw)

==Choosing a License==
Before starting development, be aware of these license requirements:

*The 2.6 C API requires that your plugin uses the GPL license. The GPL license requires that you release the source code.
*The 2.5 C API can use your own license, but the complete source of AviSynth 2.5 and the C API header must be made available along with your plugin binary

==Plugin Compatibility==
Plugins programmed in the 2.5 C API can also be used with higher versions of AviSynth, however they can't access any newer features.

==Setting up your Development Environment==
This tutorial was developed with Code::Blocks, a free development environment. Please follow these steps:

*Download <tt>codeblocks-13.12mingw-setup.exe</tt> from the [http://www.codeblocks.org/downloads/binaries CodeBlocks homepage] and run it
*The first screen reads "Welcome to the CodeBlocks Setup Wizard". Click Next.
*The GPL license is displayed. Click I Agree.
*Choose any extra components to install if desired, but the default is sufficient. Click Next.
*Choose a destination folder. Click Install. Complete the wizard.

==Compiling Your First Plugin==
Before making our own plugin, first we will learn how to compile an existing plugin. Please follow these steps:

*Ensure that you included the option "Install FilterSDK" when installing AviSynth; otherwise reinstall AviSynth with that option.
*Create a C Projects folder under My Documents.
*Obtain the sample plugin Demosaic from [http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip]. Unzip the files to C Projects. There should now be demosaic, avisynth_c and avisynth_c_2_5 folders.
*Delete the avisynth_c and avisynth_c_2_5 folders.
*Delete this file from demosaic: makefile
*Make a new folder, lib under Demosaic.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\Extras\avisynth.lib to demosaic\lib.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\FilterSDK\include\avisynth_c.h to demosaic.
*Start Code::Blocks. Click Create a new project.
*Click Projects, then click Dynamic Link Library, then click Go.
*The wizard page "Dynamic Link Library" appears. Click Next.
*For Project title, use Demosaic. Choose the My Documents\C Projects folder you created in a previous step. Click Next.
*Under compiler, choose GNU GCC Compiler. Accept the defaults and click Finish.
*Right click "Demosaic", and choose Remove files. A list showing main.cpp and main.h appear. Click OK. Click Yes.
*Delete these files from demosaic: main.cpp, main.h
*Right click "Demosaic" and choose Add Files. Add the demosaic.cpp file found in demosaic.
*A window asks you to choose which targets the file belongs to. Click OK.
*Right click Demosaic and choose Add Files. Add the avisynth_c.h file found in 'demosaic. Click OK.
*Select the menu Project->Build Options.... Select Demosaic in the tree.
*Select the tab Linker settings. Click Add. Browse for the file Demosaic\lib\avisynth.lib.
*You are asked "Keep this as a relative path?". Click Yes. Click OK. Click OK.
*Select the menu Build->Select target->Release.
*Select the menu Build->Build.
*Verify that the file demosaic\bin\Release\Demosaic.dll was made. Copy this file to your (C:\Program Files\ or other installation directory then:) AviSynth 2.5 folder.
*Test the plugin by writing an AviSynth script:

Load_Stdcall_Plugin("Demosaic.dll")
colorbars(pixel_type="YV12")
Demosaic()

This should display a grey test pattern with some colour fringes.

*Save the project with File->Save project.

Troubleshooting:

*Note that I found problems using full paths with spaces. The .lib file can only be found when placed in a folder lib and using relative paths.
*If you have a script error, try using the original demosaic.dll in the Demosaic folder. Note that this file starts with a lower case d, so adjust your script accordingly.
*The test.avs which comes with the plugin uses <code>LoadCPlugin</code>. It is better to use <code>Load_Stdcall_Plugin</code> because the <code>avisynth_c.dll</code> plugin may be auto-loaded. This is a plugin which overrides the functionality of <code>LoadCPlugin</code>, such that it won't load <tt>demosaic.dll</tt> anymore.

==Passing Parameters to your Plugin==
For this example, again we will start with the C source of Demosaic ([http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip])

The example source defines a function, in AviSynth script terms, as:

Demosaic(clip clip1, string "mosaic")

However, for our purposes we want to define a plugin like this:

Merge(clip clip1, clip clip2, int weight)

Step 1: Define a place to store the parameters

In this step, we will change the existing code:

<pre>enum Mosaic {
BAYER
};
struct Demosaic {
Mosaic mosaic;
};

Into a new version:
struct Params
{
AVS_Clip* clip2;
int Weight;
};</pre>

Step 2: Tell Avisynth to parse the new parameters 
In this step, we will use a special code to inform the Avisynth parser to look for, and save our parameters. We will change the existing code:

<pre>const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Demosaic", "c[mosaic]s", create_filter, 0);
return "Demosaic plugin";
}</pre>

To the new version:
const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Merge", "cc[weight]i", create_filter, 0);
return "Merge plugin";
}

The:
return "Merge plugin";

statement returns a value to the LoadCPlugin() command (in AviSynth script) upon loading our plugin. In practice, almost no one checks this return value. The code
avs_add_function(env, "Merge", "c[weight]i", create_filter, 0);

does a few things; first "Merge" will be the name of our AviSynth script function (i.e., in the same sense that "[[Tweak]]" is a built-in function). Next, we use a special code to define the expected parameters. In this case, "c" refers to a clip while "i" refers to an int. If we had used "ci", the function would simply expect a clip and an int, like this: <code>Merge(clip1,2)</code> However, we wanted to use a named parameter, which is an optional parameter in functions which can also be named and placed in any order. For example, we could use this script:

Merge(clip1,weight=2)

or simply leave it out:

Merge(clip1)
To specify the name, we include it in square brackets before the parameter type, which in this example, is "[weight]i".

Reference

The special codes for defining your parameters: 'c' for clip, 'i' for integer, 's' for string, 'b' for boolean, and 'f' for float There are a few more features which are explained at: [http://www.kevina.org/avisynth_c/example.html AviSynth C Interface Illustrated Example] by Kevin Atkinson.

Step 3: Fetching and checking your parameters In this final step, we will actually read the parameters which the AviSynth parser has saved for us. We will change the original code:

int pnum = 0;
++pnum; mosaic_str = avs_defined(avs_array_elt(args, pnum)) ? avs_as_string(avs_array_elt(args, pnum)) : "Bayer";

To the following:
int pnum = 0;
++pnum; params->clip2 = avs_defined(avs_array_elt(args, pnum)) ? avs_take_clip(avs_array_elt(args, pnum), env) : 0;
++pnum; params->weight = avs_defined(avs_array_elt(args, pnum)) ?
avs_as_int(avs_array_elt(args, pnum)) : 1; // Default value for weight here

It turns out that avs_array_elt contains our list of arguments in the order they were supplied in the script. We are going to expect the first parameter to be a clip, and the second to be an int. The first element, numbered 0, in the array is the value of last, which is also our first clip. pnum will be a counter to fetch each parameter, starting with number 1 (int pnum=0; ++pnum leaves pnum=1). avs_defined() is a function which checks to see if the parameter exists. So we are seeing if parameter #1 exists, and if so, assign it to params->clip2 which is the structure we've defined to hold our parameters. If it doesn't exists, we'll just put a 0 there. The function avs_take_clip actually takes our clip.

In the second parameter fetch, we use avs_as_int to fetch our weight. This function doesn't need an "env" argument. Instead of return 0 if the parameter isn't there, we will take the opportunity to also set a default value for weight here.

Next comes checking the parameters. Even though it seems like we've saved the values, we actually don't know what they really are - they're just data at this point, that we've assumed were a clip and an int. Next we have to actually double-check this. Original code:
// Check params
retval = avs_void;
if (stricmp(mosaic_str, "bayer") == 0)
params->mosaic = BAYER;
else
retval = avs_new_value_error("Mosaic mode can be: \"Bayer\"");
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi) && !avs_is_yv12(&fi->vi) && !avs_is_y8(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2, YV12, Y8");
}

New code:
// Check params
retval = avs_void;
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2");
}
if (!avs_defined(retval) && !avs_is_int(params->weight) {
retval = avs_new_value_error("weight must be an int");
}

There's a few things to go over here. First of all, in the larger context we are defining what our plugin returns here, and that is what retval is. If you return void, it's the same as returning nothing - you'd see "Not a clip" if you tried to play it. We will cover returning a new clip shortly. !avs_defined(retval) is basically saying, "if retval hasn't been defined yet...", and this is logic to continue checking parameters. In other words, if one of these checks fails, we will set an error message clip as a retval, then the next check will be skipped because a retval has been set. It's just a way to check each parameter just once and skip all other checks as soon as a problem is found. Now for the actual checking: !avs_is_yuy2(&fi->vi) checks the colour format of our first clip; there are predefined functions for checking every format. Likewise, !avs_is_int(params->weight) checks if our weight is really an int. avs_new_value_error() is a function that creates a new video clip with a message in it, similar to messageclip() in script. We use this to inform the user of the error. If all parameters are found to be correct, we finally return the output clip. Original code (unchanged):
// If no errors, all is fine, return clip value
if (!avs_defined(retval)) {
retval = avs_new_value_clip(new_clip);
}

Reference There are numerous checks for video type:
int avs_is_rgb(const AVS_VideoInfo * p)
int avs_is_rgb24(const AVS_VideoInfo * p)
int avs_is_rgb32(const AVS_VideoInfo * p)
int avs_is_yuy(const AVS_VideoInfo * p)
int avs_is_yuy2(const AVS_VideoInfo * p)
int avs_is_yv12(const AVS_VideoInfo * p)

There are various checks for other parameters:
int avs_defined(AVS_Value v)
int avs_is_clip(AVS_Value v)
int avs_is_bool(AVS_Value v)
int avs_is_int(AVS_Value v)
int avs_is_float(AVS_Value v)
int avs_is_string(AVS_Value v)
int avs_is_array(AVS_Value v)
int avs_is_error(AVS_Value v)

And as mentioned, we can return an error clip or a new clip; we can also return int, float, and string values which can be read by the runtime environment:
AVS_Value avs_new_value_bool(int v0)
AVS_Value avs_new_value_int(int v0)
AVS_Value avs_new_value_string(const char * v0)
AVS_Value avs_new_value_float(float v0)
AVS_Value avs_new_value_error(const char * v0)
AVS_Value avs_new_value_clip(AVS_Clip * v0)
AVS_Value avs_new_value_array(AVS_Value * v0, int size)

For more information, please review [http://www.kevina.org/avisynth_c/api.html AviSynth C Interface API Reference].

==Writing the actual function==
After all that work, finally we can write a few simple lines of code to actually merge our videos! However, there's *still* a few more things you need to know. The various video formats are stored in memory in different ways; although we've got a pointer to an area of memory which holds our video, it can be *interpreted* in different ways, even though it's the same size! This is where handling of YUY2 vs YV12 and RGB comes in. We'll start with YUY2 in our example. YUY2 is where every two luma pixels share a color. A color is stored as two values, U and V. We won't go into what U and V means, except to say that if you average two pixels together, everything works out. YUY2 is stored in this format in memory, from the initial pointer to increasing values in memory, a byte at a time: Y1 U Y2 V. If you access the memory 4 bytes at a time (that is, as a 32 bit unsigned int), due to the Intel assembly stored values as Least Significant Byte order, the int would look like this: 0xVVYYUUYY, where each doubled letter represents one HEX value. For example, if our pixels were Y1=35, Y2=40, U=V=128 (which I'll tell you represents no color or grey), we'd have a hex value of 0x80288023. I mention that only as a reminder for the optimizing section. For now we'll simply deal with them as bytes for clarity. New code:
aY1=src_data[x];
bY1=clip2_data[x];
aU=src_data[x+1];
bU=clip2_data[x+1];
aY2=src_data[x+2];
bY2=clip2_data[x+2];
aV=src_data[x+3];
bV=clip2_data[x+3];

Will give us a pair of pixels each from the two input clips in easy to use byte values. Finally, *finally*, we can simply write these 4 lines of code to finish our function:
dest_data[x+1] = (aU/weight+bU*weight);
dest_data[x+3] = (aV/weight+bV*weight);
dest_data[x+0] = (aY1/weight+bY1*weight);
dest_data[x+2] = (aY2/weight+bY2*weight);

Just remember, again, that [x] is Y1, [x+1] is U, [x+2] is Y2, and [x+3] is V.

==Putting it all together==
Download and compile the final sample code from .... Install, then open the Merge.cbp file, the project for Code::Blocks. Simply Build->Build. You now have a fresh merge.dll in your project directory. In order to test it, I've include some simple windows batch files. Double click the install.bat icon. This will copy the merge.dll to your AviSynth directory. Note: ensure that you have no scripts open using the plugin, or the file will fail to overwrite any existing plugin version in your AviSynth directory. Next, open merge.avs in for example AvsP, then press F5. You should see a semitransparent message overlaid on the background. The weight value will change the degree of transparency, where a higher value makes the message stronger.

==Conclusion==
In this manual, we've covered the basic steps necessary to convert an existing example to a new filter, with pointers on how to extend the concepts to include any set of parameters, to return a clip or runtime variable, and to access pixels pairs as stored in YUY2 colour format. In the next set of tutorials, it is planned to cover other colour formats, and some notes on optimizing your code for better execution speed. I hope you have found this tutorial useful. If you have any comments or corrections, please see the ongoing discussion at: http://forum.doom9.org/forumdisplay.php?f=69

==External Links==
*[http://forum.doom9.org/showthread.php?p=1465008#post1465008 Doom9 Forum] - Includes corrections and additional information.
*[http://forum.doom9.org/showthread.php?p=1688939#post1688939 Doom9 Forum] - Continued discussion.

[[Category:AviSynth_Development]]
[[Category:FilterSDK]]

Avisynth Plugin Development in C

2016-06-11T11:43:54Z

Jmac698: /* Choosing a License */

Note: This guide is in development. Currently, only the section [[Avisynth_Plugin_Development_in_C#Compiling_Your_First_Plugin|Compiling Your First Plugin]] has been tested. The rest contains some errors, so use at your own risk!

==Introduction==
This tutorial takes you step-by-step through the process of creating a new C plugin for AviSynth by modifying an existing example. By the end of this tutorial, you should be able a plugin which returns a normal value or which works on a single frame. The target audience is the beginning level C programmer.

==Why Develop a Plugin in C?==
Some reasons to use C based plugin development are that,

*Free compilers can be used, such as MingW and online code editors such as https://codeanywhere.com/features/editor; only Microsoft Visual C++ or the free Community Edition may be used to create AviSynth C++ plugins
*You are only familiar with C
*It may be simpler to learn for a beginner
*There is no download (with online code editor) or small download (with mingw)

==Choosing a License==
Before starting development, be aware of these license requirements:

*The 2.6 C API requires that your plugin uses the GPL license. The GPL license requires that you release the source code.
*The 2.5 C API can use your own license, but the complete source of AviSynth 2.5 and the C API header must be made available along with your plugin binary

==Plugin Compatibility==
Plugins programmed in the 2.5 C API can also be used with higher versions of AviSynth, however they can't access any newer features.

==Setting up your Development Environment==
This tutorial was developed with Code::Blocks, a free development environment. Please follow these steps:

*Download <tt>codeblocks-13.12mingw-setup.exe</tt> from the [http://www.codeblocks.org/downloads/binaries CodeBlocks homepage] and run it
*The first screen reads "Welcome to the CodeBlocks Setup Wizard". Click Next.
*The GPL license is displayed. Click I Agree.
*Choose any extra components to install if desired, but the default is sufficient. Click Next.
*Choose a destination folder. Click Install. Complete the wizard.

==Compiling Your First Plugin==
Before making our own plugin, first we will learn how to compile an existing plugin. Please follow these steps:

*Ensure that you included the option "Install FilterSDK" when installing AviSynth; otherwise reinstall AviSynth with that option.
*Create a C Projects folder under My Documents.
*Obtain the sample plugin Demosaic from [http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip]. Unzip the files to C Projects. There should now be demosaic, avisynth_c and avisynth_c_2_5 folders.
*Delete the avisynth_c and avisynth_c_2_5 folders.
*Delete this file from demosaic: makefile
*Make a new folder, lib under Demosaic.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\Extras\avisynth.lib to demosaic\lib.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\FilterSDK\include\avisynth_c.h to demosaic.
*Start Code::Blocks. Click Create a new project.
*Click Projects, then click Dynamic Link Library, then click Go.
*The wizard page "Dynamic Link Library" appears. Click Next.
*For Project title, use Demosaic. Choose the My Documents\C Projects folder you created in a previous step. Click Next.
*Under compiler, choose GNU GCC Compiler. Accept the defaults and click Finish.
*Right click "Demosaic", and choose Remove files. A list showing main.cpp and main.h appear. Click OK. Click Yes.
*Delete these files from demosaic: main.cpp, main.h
*Right click "Demosaic" and choose Add Files. Add the demosaic.cpp file found in demosaic.
*A window asks you to choose which targets the file belongs to. Click OK.
*Right click Demosaic and choose Add Files. Add the avisynth_c.h file found in 'demosaic. Click OK.
*Select the menu Project->Build Options.... Select Demosaic in the tree.
*Select the tab Linker settings. Click Add. Browse for the file Demosaic\lib\avisynth.lib.
*You are asked "Keep this as a relative path?". Click Yes. Click OK. Click OK.
*Select the menu Build->Select target->Release.
*Select the menu Build->Build.
*Verify that the file demosaic\bin\Release\Demosaic.dll was made. Copy this file to your (C:\Program Files\ or other installation directory then:) AviSynth 2.5 folder.
*Test the plugin by writing an AviSynth script:

Load_Stdcall_Plugin("Demosaic.dll")
colorbars(pixel_type="YV12")
Demosaic()

This should display a grey test pattern with some colour fringes.

*Save the project with File->Save project.

Troubleshooting:

*Note that I found problems using full paths with spaces. The .lib file can only be found when placed in a folder lib and using relative paths.
*If you have a script error, try using the original demosaic.dll in the Demosaic folder. Note that this file starts with a lower case d, so adjust your script accordingly.
*The test.avs which comes with the plugin uses <code>LoadCPlugin</code>. It is better to use <code>Load_Stdcall_Plugin</code> because the <code>avisynth_c.dll</code> plugin may be auto-loaded. This is a plugin which overrides the functionality of <code>LoadCPlugin</code>, such that it won't load <tt>demosaic.dll</tt> anymore.

==Passing Parameters to your Plugin==
For this example, again we will start with the C source of Demosaic ([http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip])

The example source defines a function, in AviSynth script terms, as:

Demosaic(clip clip1, string "mosaic")

However, for our purposes we want to define a plugin like this:

Merge(clip clip1, clip clip2, int weight)

Step 1: Define a place to store the parameters

In this step, we will change the existing code:

<pre>enum Mosaic {
BAYER
};
struct Demosaic {
Mosaic mosaic;
};

Into a new version:
struct Params
{
AVS_Clip* clip2;
int Weight;
};</pre>

Step 2: Tell Avisynth to parse the new parameters 
In this step, we will use a special code to inform the Avisynth parser to look for, and save our parameters. We will change the existing code:

<pre>const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Demosaic", "c[mosaic]s", create_filter, 0);
return "Demosaic plugin";
}</pre>

To the new version:
const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Merge", "cc[weight]i", create_filter, 0);
return "Merge plugin";
}

The:
return "Merge plugin";

statement returns a value to the LoadCPlugin() command (in AviSynth script) upon loading our plugin. In practice, almost no one checks this return value. The code
avs_add_function(env, "Merge", "c[weight]i", create_filter, 0);

does a few things; first "Merge" will be the name of our AviSynth script function (i.e., in the same sense that "[[Tweak]]" is a built-in function). Next, we use a special code to define the expected parameters. In this case, "c" refers to a clip while "i" refers to an int. If we had used "ci", the function would simply expect a clip and an int, like this: <code>Merge(clip1,2)</code> However, we wanted to use a named parameter, which is an optional parameter in functions which can also be named and placed in any order. For example, we could use this script:

Merge(clip1,weight=2)

or simply leave it out:

Merge(clip1)
To specify the name, we include it in square brackets before the parameter type, which in this example, is "[weight]i".

Reference

The special codes for defining your parameters: 'c' for clip, 'i' for integer, 's' for string, 'b' for boolean, and 'f' for float There are a few more features which are explained at: [http://www.kevina.org/avisynth_c/example.html AviSynth C Interface Illustrated Example] by Kevin Atkinson.

Step 3: Fetching and checking your parameters In this final step, we will actually read the parameters which the AviSynth parser has saved for us. We will change the original code:

int pnum = 0;
++pnum; mosaic_str = avs_defined(avs_array_elt(args, pnum)) ? avs_as_string(avs_array_elt(args, pnum)) : "Bayer";

To the following:
int pnum = 0;
++pnum; params->clip2 = avs_defined(avs_array_elt(args, pnum)) ? avs_take_clip(avs_array_elt(args, pnum), env) : 0;
++pnum; params->weight = avs_defined(avs_array_elt(args, pnum)) ?
avs_as_int(avs_array_elt(args, pnum)) : 1; // Default value for weight here

It turns out that avs_array_elt contains our list of arguments in the order they were supplied in the script. We are going to expect the first parameter to be a clip, and the second to be an int. The first element, numbered 0, in the array is the value of last, which is also our first clip. pnum will be a counter to fetch each parameter, starting with number 1 (int pnum=0; ++pnum leaves pnum=1). avs_defined() is a function which checks to see if the parameter exists. So we are seeing if parameter #1 exists, and if so, assign it to params->clip2 which is the structure we've defined to hold our parameters. If it doesn't exists, we'll just put a 0 there. The function avs_take_clip actually takes our clip.

In the second parameter fetch, we use avs_as_int to fetch our weight. This function doesn't need an "env" argument. Instead of return 0 if the parameter isn't there, we will take the opportunity to also set a default value for weight here.

Next comes checking the parameters. Even though it seems like we've saved the values, we actually don't know what they really are - they're just data at this point, that we've assumed were a clip and an int. Next we have to actually double-check this. Original code:
// Check params
retval = avs_void;
if (stricmp(mosaic_str, "bayer") == 0)
params->mosaic = BAYER;
else
retval = avs_new_value_error("Mosaic mode can be: \"Bayer\"");
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi) && !avs_is_yv12(&fi->vi) && !avs_is_y8(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2, YV12, Y8");
}

New code:
// Check params
retval = avs_void;
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2");
}
if (!avs_defined(retval) && !avs_is_int(params->weight) {
retval = avs_new_value_error("weight must be an int");
}

There's a few things to go over here. First of all, in the larger context we are defining what our plugin returns here, and that is what retval is. If you return void, it's the same as returning nothing - you'd see "Not a clip" if you tried to play it. We will cover returning a new clip shortly. !avs_defined(retval) is basically saying, "if retval hasn't been defined yet...", and this is logic to continue checking parameters. In other words, if one of these checks fails, we will set an error message clip as a retval, then the next check will be skipped because a retval has been set. It's just a way to check each parameter just once and skip all other checks as soon as a problem is found. Now for the actual checking: !avs_is_yuy2(&fi->vi) checks the colour format of our first clip; there are predefined functions for checking every format. Likewise, !avs_is_int(params->weight) checks if our weight is really an int. avs_new_value_error() is a function that creates a new video clip with a message in it, similar to messageclip() in script. We use this to inform the user of the error. If all parameters are found to be correct, we finally return the output clip. Original code (unchanged):
// If no errors, all is fine, return clip value
if (!avs_defined(retval)) {
retval = avs_new_value_clip(new_clip);
}

Reference There are numerous checks for video type:
int avs_is_rgb(const AVS_VideoInfo * p)
int avs_is_rgb24(const AVS_VideoInfo * p)
int avs_is_rgb32(const AVS_VideoInfo * p)
int avs_is_yuy(const AVS_VideoInfo * p)
int avs_is_yuy2(const AVS_VideoInfo * p)
int avs_is_yv12(const AVS_VideoInfo * p)

There are various checks for other parameters:
int avs_defined(AVS_Value v)
int avs_is_clip(AVS_Value v)
int avs_is_bool(AVS_Value v)
int avs_is_int(AVS_Value v)
int avs_is_float(AVS_Value v)
int avs_is_string(AVS_Value v)
int avs_is_array(AVS_Value v)
int avs_is_error(AVS_Value v)

And as mentioned, we can return an error clip or a new clip; we can also return int, float, and string values which can be read by the runtime environment:
AVS_Value avs_new_value_bool(int v0)
AVS_Value avs_new_value_int(int v0)
AVS_Value avs_new_value_string(const char * v0)
AVS_Value avs_new_value_float(float v0)
AVS_Value avs_new_value_error(const char * v0)
AVS_Value avs_new_value_clip(AVS_Clip * v0)
AVS_Value avs_new_value_array(AVS_Value * v0, int size)

For more information, please review [http://www.kevina.org/avisynth_c/api.html AviSynth C Interface API Reference].

==Writing the actual function==
After all that work, finally we can write a few simple lines of code to actually merge our videos! However, there's *still* a few more things you need to know. The various video formats are stored in memory in different ways; although we've got a pointer to an area of memory which holds our video, it can be *interpreted* in different ways, even though it's the same size! This is where handling of YUY2 vs YV12 and RGB comes in. We'll start with YUY2 in our example. YUY2 is where every two luma pixels share a color. A color is stored as two values, U and V. We won't go into what U and V means, except to say that if you average two pixels together, everything works out. YUY2 is stored in this format in memory, from the initial pointer to increasing values in memory, a byte at a time: Y1 U Y2 V. If you access the memory 4 bytes at a time (that is, as a 32 bit unsigned int), due to the Intel assembly stored values as Least Significant Byte order, the int would look like this: 0xVVYYUUYY, where each doubled letter represents one HEX value. For example, if our pixels were Y1=35, Y2=40, U=V=128 (which I'll tell you represents no color or grey), we'd have a hex value of 0x80288023. I mention that only as a reminder for the optimizing section. For now we'll simply deal with them as bytes for clarity. New code:
aY1=src_data[x];
bY1=clip2_data[x];
aU=src_data[x+1];
bU=clip2_data[x+1];
aY2=src_data[x+2];
bY2=clip2_data[x+2];
aV=src_data[x+3];
bV=clip2_data[x+3];

Will give us a pair of pixels each from the two input clips in easy to use byte values. Finally, *finally*, we can simply write these 4 lines of code to finish our function:
dest_data[x+1] = (aU/weight+bU*weight);
dest_data[x+3] = (aV/weight+bV*weight);
dest_data[x+0] = (aY1/weight+bY1*weight);
dest_data[x+2] = (aY2/weight+bY2*weight);

Just remember, again, that [x] is Y1, [x+1] is U, [x+2] is Y2, and [x+3] is V.

==Putting it all together==
Download and compile the final sample code from .... Install, then open the Merge.cbp file, the project for Code::Blocks. Simply Build->Build. You now have a fresh merge.dll in your project directory. In order to test it, I've include some simple windows batch files. Double click the install.bat icon. This will copy the merge.dll to your AviSynth directory. Note: ensure that you have no scripts open using the plugin, or the file will fail to overwrite any existing plugin version in your AviSynth directory. Next, open merge.avs in for example AvsP, then press F5. You should see a semitransparent message overlaid on the background. The weight value will change the degree of transparency, where a higher value makes the message stronger.

==Conclusion==
In this manual, we've covered the basic steps necessary to convert an existing example to a new filter, with pointers on how to extend the concepts to include any set of parameters, to return a clip or runtime variable, and to access pixels pairs as stored in YUY2 colour format. In the next set of tutorials, it is planned to cover other colour formats, and some notes on optimizing your code for better execution speed. I hope you have found this tutorial useful. If you have any comments or corrections, please see the ongoing discussion at: http://forum.doom9.org/forumdisplay.php?f=69

==External Links==
*[http://forum.doom9.org/showthread.php?p=1465008#post1465008 Doom9 Forum] - Includes corrections and additional information.
*[http://forum.doom9.org/showthread.php?p=1688939#post1688939 Doom9 Forum] - Continued discussion.

[[Category:AviSynth_Development]]
[[Category:FilterSDK]]

Avisynth Plugin Development in C

2016-06-11T11:42:49Z

Jmac698: /* Why Develop a Plugin in C? */

Note: This guide is in development. Currently, only the section [[Avisynth_Plugin_Development_in_C#Compiling_Your_First_Plugin|Compiling Your First Plugin]] has been tested. The rest contains some errors, so use at your own risk!

==Introduction==
This tutorial takes you step-by-step through the process of creating a new C plugin for AviSynth by modifying an existing example. By the end of this tutorial, you should be able a plugin which returns a normal value or which works on a single frame. The target audience is the beginning level C programmer.

==Why Develop a Plugin in C?==
Some reasons to use C based plugin development are that,

*Free compilers can be used, such as MingW and online code editors such as https://codeanywhere.com/features/editor; only Microsoft Visual C++ or the free Community Edition may be used to create AviSynth C++ plugins
*You are only familiar with C
*It may be simpler to learn for a beginner
*There is no download (with online code editor) or small download (with mingw)

==Choosing a License==
Before starting development, be aware of these license requirements:

*The 2.6a5 C API requires that your plugin uses the GPL license. The GPL license requires that you release the source code.
*The 2.5 C API can use your own license, but the complete source of AviSynth 2.5 and the C API header must be made available along with your plugin binary

==Plugin Compatibility==
Plugins programmed in the 2.5 C API can also be used with higher versions of AviSynth, however they can't access any newer features.

==Setting up your Development Environment==
This tutorial was developed with Code::Blocks, a free development environment. Please follow these steps:

*Download <tt>codeblocks-13.12mingw-setup.exe</tt> from the [http://www.codeblocks.org/downloads/binaries CodeBlocks homepage] and run it
*The first screen reads "Welcome to the CodeBlocks Setup Wizard". Click Next.
*The GPL license is displayed. Click I Agree.
*Choose any extra components to install if desired, but the default is sufficient. Click Next.
*Choose a destination folder. Click Install. Complete the wizard.

==Compiling Your First Plugin==
Before making our own plugin, first we will learn how to compile an existing plugin. Please follow these steps:

*Ensure that you included the option "Install FilterSDK" when installing AviSynth; otherwise reinstall AviSynth with that option.
*Create a C Projects folder under My Documents.
*Obtain the sample plugin Demosaic from [http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip]. Unzip the files to C Projects. There should now be demosaic, avisynth_c and avisynth_c_2_5 folders.
*Delete the avisynth_c and avisynth_c_2_5 folders.
*Delete this file from demosaic: makefile
*Make a new folder, lib under Demosaic.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\Extras\avisynth.lib to demosaic\lib.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\FilterSDK\include\avisynth_c.h to demosaic.
*Start Code::Blocks. Click Create a new project.
*Click Projects, then click Dynamic Link Library, then click Go.
*The wizard page "Dynamic Link Library" appears. Click Next.
*For Project title, use Demosaic. Choose the My Documents\C Projects folder you created in a previous step. Click Next.
*Under compiler, choose GNU GCC Compiler. Accept the defaults and click Finish.
*Right click "Demosaic", and choose Remove files. A list showing main.cpp and main.h appear. Click OK. Click Yes.
*Delete these files from demosaic: main.cpp, main.h
*Right click "Demosaic" and choose Add Files. Add the demosaic.cpp file found in demosaic.
*A window asks you to choose which targets the file belongs to. Click OK.
*Right click Demosaic and choose Add Files. Add the avisynth_c.h file found in 'demosaic. Click OK.
*Select the menu Project->Build Options.... Select Demosaic in the tree.
*Select the tab Linker settings. Click Add. Browse for the file Demosaic\lib\avisynth.lib.
*You are asked "Keep this as a relative path?". Click Yes. Click OK. Click OK.
*Select the menu Build->Select target->Release.
*Select the menu Build->Build.
*Verify that the file demosaic\bin\Release\Demosaic.dll was made. Copy this file to your (C:\Program Files\ or other installation directory then:) AviSynth 2.5 folder.
*Test the plugin by writing an AviSynth script:

Load_Stdcall_Plugin("Demosaic.dll")
colorbars(pixel_type="YV12")
Demosaic()

This should display a grey test pattern with some colour fringes.

*Save the project with File->Save project.

Troubleshooting:

*Note that I found problems using full paths with spaces. The .lib file can only be found when placed in a folder lib and using relative paths.
*If you have a script error, try using the original demosaic.dll in the Demosaic folder. Note that this file starts with a lower case d, so adjust your script accordingly.
*The test.avs which comes with the plugin uses <code>LoadCPlugin</code>. It is better to use <code>Load_Stdcall_Plugin</code> because the <code>avisynth_c.dll</code> plugin may be auto-loaded. This is a plugin which overrides the functionality of <code>LoadCPlugin</code>, such that it won't load <tt>demosaic.dll</tt> anymore.

==Passing Parameters to your Plugin==
For this example, again we will start with the C source of Demosaic ([http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip])

The example source defines a function, in AviSynth script terms, as:

Demosaic(clip clip1, string "mosaic")

However, for our purposes we want to define a plugin like this:

Merge(clip clip1, clip clip2, int weight)

Step 1: Define a place to store the parameters

In this step, we will change the existing code:

<pre>enum Mosaic {
BAYER
};
struct Demosaic {
Mosaic mosaic;
};

Into a new version:
struct Params
{
AVS_Clip* clip2;
int Weight;
};</pre>

Step 2: Tell Avisynth to parse the new parameters 
In this step, we will use a special code to inform the Avisynth parser to look for, and save our parameters. We will change the existing code:

<pre>const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Demosaic", "c[mosaic]s", create_filter, 0);
return "Demosaic plugin";
}</pre>

To the new version:
const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Merge", "cc[weight]i", create_filter, 0);
return "Merge plugin";
}

The:
return "Merge plugin";

statement returns a value to the LoadCPlugin() command (in AviSynth script) upon loading our plugin. In practice, almost no one checks this return value. The code
avs_add_function(env, "Merge", "c[weight]i", create_filter, 0);

does a few things; first "Merge" will be the name of our AviSynth script function (i.e., in the same sense that "[[Tweak]]" is a built-in function). Next, we use a special code to define the expected parameters. In this case, "c" refers to a clip while "i" refers to an int. If we had used "ci", the function would simply expect a clip and an int, like this: <code>Merge(clip1,2)</code> However, we wanted to use a named parameter, which is an optional parameter in functions which can also be named and placed in any order. For example, we could use this script:

Merge(clip1,weight=2)

or simply leave it out:

Merge(clip1)
To specify the name, we include it in square brackets before the parameter type, which in this example, is "[weight]i".

Reference

The special codes for defining your parameters: 'c' for clip, 'i' for integer, 's' for string, 'b' for boolean, and 'f' for float There are a few more features which are explained at: [http://www.kevina.org/avisynth_c/example.html AviSynth C Interface Illustrated Example] by Kevin Atkinson.

Step 3: Fetching and checking your parameters In this final step, we will actually read the parameters which the AviSynth parser has saved for us. We will change the original code:

int pnum = 0;
++pnum; mosaic_str = avs_defined(avs_array_elt(args, pnum)) ? avs_as_string(avs_array_elt(args, pnum)) : "Bayer";

To the following:
int pnum = 0;
++pnum; params->clip2 = avs_defined(avs_array_elt(args, pnum)) ? avs_take_clip(avs_array_elt(args, pnum), env) : 0;
++pnum; params->weight = avs_defined(avs_array_elt(args, pnum)) ?
avs_as_int(avs_array_elt(args, pnum)) : 1; // Default value for weight here

It turns out that avs_array_elt contains our list of arguments in the order they were supplied in the script. We are going to expect the first parameter to be a clip, and the second to be an int. The first element, numbered 0, in the array is the value of last, which is also our first clip. pnum will be a counter to fetch each parameter, starting with number 1 (int pnum=0; ++pnum leaves pnum=1). avs_defined() is a function which checks to see if the parameter exists. So we are seeing if parameter #1 exists, and if so, assign it to params->clip2 which is the structure we've defined to hold our parameters. If it doesn't exists, we'll just put a 0 there. The function avs_take_clip actually takes our clip.

In the second parameter fetch, we use avs_as_int to fetch our weight. This function doesn't need an "env" argument. Instead of return 0 if the parameter isn't there, we will take the opportunity to also set a default value for weight here.

Next comes checking the parameters. Even though it seems like we've saved the values, we actually don't know what they really are - they're just data at this point, that we've assumed were a clip and an int. Next we have to actually double-check this. Original code:
// Check params
retval = avs_void;
if (stricmp(mosaic_str, "bayer") == 0)
params->mosaic = BAYER;
else
retval = avs_new_value_error("Mosaic mode can be: \"Bayer\"");
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi) && !avs_is_yv12(&fi->vi) && !avs_is_y8(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2, YV12, Y8");
}

New code:
// Check params
retval = avs_void;
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2");
}
if (!avs_defined(retval) && !avs_is_int(params->weight) {
retval = avs_new_value_error("weight must be an int");
}

There's a few things to go over here. First of all, in the larger context we are defining what our plugin returns here, and that is what retval is. If you return void, it's the same as returning nothing - you'd see "Not a clip" if you tried to play it. We will cover returning a new clip shortly. !avs_defined(retval) is basically saying, "if retval hasn't been defined yet...", and this is logic to continue checking parameters. In other words, if one of these checks fails, we will set an error message clip as a retval, then the next check will be skipped because a retval has been set. It's just a way to check each parameter just once and skip all other checks as soon as a problem is found. Now for the actual checking: !avs_is_yuy2(&fi->vi) checks the colour format of our first clip; there are predefined functions for checking every format. Likewise, !avs_is_int(params->weight) checks if our weight is really an int. avs_new_value_error() is a function that creates a new video clip with a message in it, similar to messageclip() in script. We use this to inform the user of the error. If all parameters are found to be correct, we finally return the output clip. Original code (unchanged):
// If no errors, all is fine, return clip value
if (!avs_defined(retval)) {
retval = avs_new_value_clip(new_clip);
}

Reference There are numerous checks for video type:
int avs_is_rgb(const AVS_VideoInfo * p)
int avs_is_rgb24(const AVS_VideoInfo * p)
int avs_is_rgb32(const AVS_VideoInfo * p)
int avs_is_yuy(const AVS_VideoInfo * p)
int avs_is_yuy2(const AVS_VideoInfo * p)
int avs_is_yv12(const AVS_VideoInfo * p)

There are various checks for other parameters:
int avs_defined(AVS_Value v)
int avs_is_clip(AVS_Value v)
int avs_is_bool(AVS_Value v)
int avs_is_int(AVS_Value v)
int avs_is_float(AVS_Value v)
int avs_is_string(AVS_Value v)
int avs_is_array(AVS_Value v)
int avs_is_error(AVS_Value v)

And as mentioned, we can return an error clip or a new clip; we can also return int, float, and string values which can be read by the runtime environment:
AVS_Value avs_new_value_bool(int v0)
AVS_Value avs_new_value_int(int v0)
AVS_Value avs_new_value_string(const char * v0)
AVS_Value avs_new_value_float(float v0)
AVS_Value avs_new_value_error(const char * v0)
AVS_Value avs_new_value_clip(AVS_Clip * v0)
AVS_Value avs_new_value_array(AVS_Value * v0, int size)

For more information, please review [http://www.kevina.org/avisynth_c/api.html AviSynth C Interface API Reference].

==Writing the actual function==
After all that work, finally we can write a few simple lines of code to actually merge our videos! However, there's *still* a few more things you need to know. The various video formats are stored in memory in different ways; although we've got a pointer to an area of memory which holds our video, it can be *interpreted* in different ways, even though it's the same size! This is where handling of YUY2 vs YV12 and RGB comes in. We'll start with YUY2 in our example. YUY2 is where every two luma pixels share a color. A color is stored as two values, U and V. We won't go into what U and V means, except to say that if you average two pixels together, everything works out. YUY2 is stored in this format in memory, from the initial pointer to increasing values in memory, a byte at a time: Y1 U Y2 V. If you access the memory 4 bytes at a time (that is, as a 32 bit unsigned int), due to the Intel assembly stored values as Least Significant Byte order, the int would look like this: 0xVVYYUUYY, where each doubled letter represents one HEX value. For example, if our pixels were Y1=35, Y2=40, U=V=128 (which I'll tell you represents no color or grey), we'd have a hex value of 0x80288023. I mention that only as a reminder for the optimizing section. For now we'll simply deal with them as bytes for clarity. New code:
aY1=src_data[x];
bY1=clip2_data[x];
aU=src_data[x+1];
bU=clip2_data[x+1];
aY2=src_data[x+2];
bY2=clip2_data[x+2];
aV=src_data[x+3];
bV=clip2_data[x+3];

Will give us a pair of pixels each from the two input clips in easy to use byte values. Finally, *finally*, we can simply write these 4 lines of code to finish our function:
dest_data[x+1] = (aU/weight+bU*weight);
dest_data[x+3] = (aV/weight+bV*weight);
dest_data[x+0] = (aY1/weight+bY1*weight);
dest_data[x+2] = (aY2/weight+bY2*weight);

Just remember, again, that [x] is Y1, [x+1] is U, [x+2] is Y2, and [x+3] is V.

==Putting it all together==
Download and compile the final sample code from .... Install, then open the Merge.cbp file, the project for Code::Blocks. Simply Build->Build. You now have a fresh merge.dll in your project directory. In order to test it, I've include some simple windows batch files. Double click the install.bat icon. This will copy the merge.dll to your AviSynth directory. Note: ensure that you have no scripts open using the plugin, or the file will fail to overwrite any existing plugin version in your AviSynth directory. Next, open merge.avs in for example AvsP, then press F5. You should see a semitransparent message overlaid on the background. The weight value will change the degree of transparency, where a higher value makes the message stronger.

==Conclusion==
In this manual, we've covered the basic steps necessary to convert an existing example to a new filter, with pointers on how to extend the concepts to include any set of parameters, to return a clip or runtime variable, and to access pixels pairs as stored in YUY2 colour format. In the next set of tutorials, it is planned to cover other colour formats, and some notes on optimizing your code for better execution speed. I hope you have found this tutorial useful. If you have any comments or corrections, please see the ongoing discussion at: http://forum.doom9.org/forumdisplay.php?f=69

==External Links==
*[http://forum.doom9.org/showthread.php?p=1465008#post1465008 Doom9 Forum] - Includes corrections and additional information.
*[http://forum.doom9.org/showthread.php?p=1688939#post1688939 Doom9 Forum] - Continued discussion.

[[Category:AviSynth_Development]]
[[Category:FilterSDK]]

Avisynth Plugin Development in C

2016-06-11T11:39:42Z

Jmac698: /* Writing the actual function */

Note: This guide is in development. Currently, only the section [[Avisynth_Plugin_Development_in_C#Compiling_Your_First_Plugin|Compiling Your First Plugin]] has been tested. The rest contains some errors, so use at your own risk!

==Introduction==
This tutorial takes you step-by-step through the process of creating a new C plugin for AviSynth by modifying an existing example. By the end of this tutorial, you should be able a plugin which returns a normal value or which works on a single frame. The target audience is the beginning level C programmer.

==Why Develop a Plugin in C?==
Some reasons to use C based plugin development are that,

*Free compilers can be used, such as MingW; only Microsoft Visual C++ may be used to create AviSynth C++ plugins
*You are only familiar with C
*It may be simpler to learn for a beginner

==Choosing a License==
Before starting development, be aware of these license requirements:

*The 2.6a5 C API requires that your plugin uses the GPL license. The GPL license requires that you release the source code.
*The 2.5 C API can use your own license, but the complete source of AviSynth 2.5 and the C API header must be made available along with your plugin binary

==Plugin Compatibility==
Plugins programmed in the 2.5 C API can also be used with higher versions of AviSynth, however they can't access any newer features.

==Setting up your Development Environment==
This tutorial was developed with Code::Blocks, a free development environment. Please follow these steps:

*Download <tt>codeblocks-13.12mingw-setup.exe</tt> from the [http://www.codeblocks.org/downloads/binaries CodeBlocks homepage] and run it
*The first screen reads "Welcome to the CodeBlocks Setup Wizard". Click Next.
*The GPL license is displayed. Click I Agree.
*Choose any extra components to install if desired, but the default is sufficient. Click Next.
*Choose a destination folder. Click Install. Complete the wizard.

==Compiling Your First Plugin==
Before making our own plugin, first we will learn how to compile an existing plugin. Please follow these steps:

*Ensure that you included the option "Install FilterSDK" when installing AviSynth; otherwise reinstall AviSynth with that option.
*Create a C Projects folder under My Documents.
*Obtain the sample plugin Demosaic from [http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip]. Unzip the files to C Projects. There should now be demosaic, avisynth_c and avisynth_c_2_5 folders.
*Delete the avisynth_c and avisynth_c_2_5 folders.
*Delete this file from demosaic: makefile
*Make a new folder, lib under Demosaic.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\Extras\avisynth.lib to demosaic\lib.
*Copy (C:\Program Files\ or other installation directory then:) AviSynth 2.5\FilterSDK\include\avisynth_c.h to demosaic.
*Start Code::Blocks. Click Create a new project.
*Click Projects, then click Dynamic Link Library, then click Go.
*The wizard page "Dynamic Link Library" appears. Click Next.
*For Project title, use Demosaic. Choose the My Documents\C Projects folder you created in a previous step. Click Next.
*Under compiler, choose GNU GCC Compiler. Accept the defaults and click Finish.
*Right click "Demosaic", and choose Remove files. A list showing main.cpp and main.h appear. Click OK. Click Yes.
*Delete these files from demosaic: main.cpp, main.h
*Right click "Demosaic" and choose Add Files. Add the demosaic.cpp file found in demosaic.
*A window asks you to choose which targets the file belongs to. Click OK.
*Right click Demosaic and choose Add Files. Add the avisynth_c.h file found in 'demosaic. Click OK.
*Select the menu Project->Build Options.... Select Demosaic in the tree.
*Select the tab Linker settings. Click Add. Browse for the file Demosaic\lib\avisynth.lib.
*You are asked "Keep this as a relative path?". Click Yes. Click OK. Click OK.
*Select the menu Build->Select target->Release.
*Select the menu Build->Build.
*Verify that the file demosaic\bin\Release\Demosaic.dll was made. Copy this file to your (C:\Program Files\ or other installation directory then:) AviSynth 2.5 folder.
*Test the plugin by writing an AviSynth script:

Load_Stdcall_Plugin("Demosaic.dll")
colorbars(pixel_type="YV12")
Demosaic()

This should display a grey test pattern with some colour fringes.

*Save the project with File->Save project.

Troubleshooting:

*Note that I found problems using full paths with spaces. The .lib file can only be found when placed in a folder lib and using relative paths.
*If you have a script error, try using the original demosaic.dll in the Demosaic folder. Note that this file starts with a lower case d, so adjust your script accordingly.
*The test.avs which comes with the plugin uses <code>LoadCPlugin</code>. It is better to use <code>Load_Stdcall_Plugin</code> because the <code>avisynth_c.dll</code> plugin may be auto-loaded. This is a plugin which overrides the functionality of <code>LoadCPlugin</code>, such that it won't load <tt>demosaic.dll</tt> anymore.

==Passing Parameters to your Plugin==
For this example, again we will start with the C source of Demosaic ([http://www.avisynth.nl/users/warpenterprises/files/demosaic_20071206.zip demosaic_20071206.zip])

The example source defines a function, in AviSynth script terms, as:

Demosaic(clip clip1, string "mosaic")

However, for our purposes we want to define a plugin like this:

Merge(clip clip1, clip clip2, int weight)

Step 1: Define a place to store the parameters

In this step, we will change the existing code:

<pre>enum Mosaic {
BAYER
};
struct Demosaic {
Mosaic mosaic;
};

Into a new version:
struct Params
{
AVS_Clip* clip2;
int Weight;
};</pre>

Step 2: Tell Avisynth to parse the new parameters 
In this step, we will use a special code to inform the Avisynth parser to look for, and save our parameters. We will change the existing code:

<pre>const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Demosaic", "c[mosaic]s", create_filter, 0);
return "Demosaic plugin";
}</pre>

To the new version:
const char* AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)
{
avs_add_function(env, "Merge", "cc[weight]i", create_filter, 0);
return "Merge plugin";
}

The:
return "Merge plugin";

statement returns a value to the LoadCPlugin() command (in AviSynth script) upon loading our plugin. In practice, almost no one checks this return value. The code
avs_add_function(env, "Merge", "c[weight]i", create_filter, 0);

does a few things; first "Merge" will be the name of our AviSynth script function (i.e., in the same sense that "[[Tweak]]" is a built-in function). Next, we use a special code to define the expected parameters. In this case, "c" refers to a clip while "i" refers to an int. If we had used "ci", the function would simply expect a clip and an int, like this: <code>Merge(clip1,2)</code> However, we wanted to use a named parameter, which is an optional parameter in functions which can also be named and placed in any order. For example, we could use this script:

Merge(clip1,weight=2)

or simply leave it out:

Merge(clip1)
To specify the name, we include it in square brackets before the parameter type, which in this example, is "[weight]i".

Reference

The special codes for defining your parameters: 'c' for clip, 'i' for integer, 's' for string, 'b' for boolean, and 'f' for float There are a few more features which are explained at: [http://www.kevina.org/avisynth_c/example.html AviSynth C Interface Illustrated Example] by Kevin Atkinson.

Step 3: Fetching and checking your parameters In this final step, we will actually read the parameters which the AviSynth parser has saved for us. We will change the original code:

int pnum = 0;
++pnum; mosaic_str = avs_defined(avs_array_elt(args, pnum)) ? avs_as_string(avs_array_elt(args, pnum)) : "Bayer";

To the following:
int pnum = 0;
++pnum; params->clip2 = avs_defined(avs_array_elt(args, pnum)) ? avs_take_clip(avs_array_elt(args, pnum), env) : 0;
++pnum; params->weight = avs_defined(avs_array_elt(args, pnum)) ?
avs_as_int(avs_array_elt(args, pnum)) : 1; // Default value for weight here

It turns out that avs_array_elt contains our list of arguments in the order they were supplied in the script. We are going to expect the first parameter to be a clip, and the second to be an int. The first element, numbered 0, in the array is the value of last, which is also our first clip. pnum will be a counter to fetch each parameter, starting with number 1 (int pnum=0; ++pnum leaves pnum=1). avs_defined() is a function which checks to see if the parameter exists. So we are seeing if parameter #1 exists, and if so, assign it to params->clip2 which is the structure we've defined to hold our parameters. If it doesn't exists, we'll just put a 0 there. The function avs_take_clip actually takes our clip.

In the second parameter fetch, we use avs_as_int to fetch our weight. This function doesn't need an "env" argument. Instead of return 0 if the parameter isn't there, we will take the opportunity to also set a default value for weight here.

Next comes checking the parameters. Even though it seems like we've saved the values, we actually don't know what they really are - they're just data at this point, that we've assumed were a clip and an int. Next we have to actually double-check this. Original code:
// Check params
retval = avs_void;
if (stricmp(mosaic_str, "bayer") == 0)
params->mosaic = BAYER;
else
retval = avs_new_value_error("Mosaic mode can be: \"Bayer\"");
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi) && !avs_is_yv12(&fi->vi) && !avs_is_y8(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2, YV12, Y8");
}

New code:
// Check params
retval = avs_void;
if (!avs_defined(retval) && !avs_is_yuy2(&fi->vi)) {
retval = avs_new_value_error("Input video format can be: YUY2");
}
if (!avs_defined(retval) && !avs_is_int(params->weight) {
retval = avs_new_value_error("weight must be an int");
}

There's a few things to go over here. First of all, in the larger context we are defining what our plugin returns here, and that is what retval is. If you return void, it's the same as returning nothing - you'd see "Not a clip" if you tried to play it. We will cover returning a new clip shortly. !avs_defined(retval) is basically saying, "if retval hasn't been defined yet...", and this is logic to continue checking parameters. In other words, if one of these checks fails, we will set an error message clip as a retval, then the next check will be skipped because a retval has been set. It's just a way to check each parameter just once and skip all other checks as soon as a problem is found. Now for the actual checking: !avs_is_yuy2(&fi->vi) checks the colour format of our first clip; there are predefined functions for checking every format. Likewise, !avs_is_int(params->weight) checks if our weight is really an int. avs_new_value_error() is a function that creates a new video clip with a message in it, similar to messageclip() in script. We use this to inform the user of the error. If all parameters are found to be correct, we finally return the output clip. Original code (unchanged):
// If no errors, all is fine, return clip value
if (!avs_defined(retval)) {
retval = avs_new_value_clip(new_clip);
}

Reference There are numerous checks for video type:
int avs_is_rgb(const AVS_VideoInfo * p)
int avs_is_rgb24(const AVS_VideoInfo * p)
int avs_is_rgb32(const AVS_VideoInfo * p)
int avs_is_yuy(const AVS_VideoInfo * p)
int avs_is_yuy2(const AVS_VideoInfo * p)
int avs_is_yv12(const AVS_VideoInfo * p)

There are various checks for other parameters:
int avs_defined(AVS_Value v)
int avs_is_clip(AVS_Value v)
int avs_is_bool(AVS_Value v)
int avs_is_int(AVS_Value v)
int avs_is_float(AVS_Value v)
int avs_is_string(AVS_Value v)
int avs_is_array(AVS_Value v)
int avs_is_error(AVS_Value v)

And as mentioned, we can return an error clip or a new clip; we can also return int, float, and string values which can be read by the runtime environment:
AVS_Value avs_new_value_bool(int v0)
AVS_Value avs_new_value_int(int v0)
AVS_Value avs_new_value_string(const char * v0)
AVS_Value avs_new_value_float(float v0)
AVS_Value avs_new_value_error(const char * v0)
AVS_Value avs_new_value_clip(AVS_Clip * v0)
AVS_Value avs_new_value_array(AVS_Value * v0, int size)

For more information, please review [http://www.kevina.org/avisynth_c/api.html AviSynth C Interface API Reference].

==Writing the actual function==
After all that work, finally we can write a few simple lines of code to actually merge our videos! However, there's *still* a few more things you need to know. The various video formats are stored in memory in different ways; although we've got a pointer to an area of memory which holds our video, it can be *interpreted* in different ways, even though it's the same size! This is where handling of YUY2 vs YV12 and RGB comes in. We'll start with YUY2 in our example. YUY2 is where every two luma pixels share a color. A color is stored as two values, U and V. We won't go into what U and V means, except to say that if you average two pixels together, everything works out. YUY2 is stored in this format in memory, from the initial pointer to increasing values in memory, a byte at a time: Y1 U Y2 V. If you access the memory 4 bytes at a time (that is, as a 32 bit unsigned int), due to the Intel assembly stored values as Least Significant Byte order, the int would look like this: 0xVVYYUUYY, where each doubled letter represents one HEX value. For example, if our pixels were Y1=35, Y2=40, U=V=128 (which I'll tell you represents no color or grey), we'd have a hex value of 0x80288023. I mention that only as a reminder for the optimizing section. For now we'll simply deal with them as bytes for clarity. New code:
aY1=src_data[x];
bY1=clip2_data[x];
aU=src_data[x+1];
bU=clip2_data[x+1];
aY2=src_data[x+2];
bY2=clip2_data[x+2];
aV=src_data[x+3];
bV=clip2_data[x+3];

Will give us a pair of pixels each from the two input clips in easy to use byte values. Finally, *finally*, we can simply write these 4 lines of code to finish our function:
dest_data[x+1] = (aU/weight+bU*weight);
dest_data[x+3] = (aV/weight+bV*weight);
dest_data[x+0] = (aY1/weight+bY1*weight);
dest_data[x+2] = (aY2/weight+bY2*weight);

Just remember, again, that [x] is Y1, [x+1] is U, [x+2] is Y2, and [x+3] is V.

==Putting it all together==
Download and compile the final sample code from .... Install, then open the Merge.cbp file, the project for Code::Blocks. Simply Build->Build. You now have a fresh merge.dll in your project directory. In order to test it, I've include some simple windows batch files. Double click the install.bat icon. This will copy the merge.dll to your AviSynth directory. Note: ensure that you have no scripts open using the plugin, or the file will fail to overwrite any existing plugin version in your AviSynth directory. Next, open merge.avs in for example AvsP, then press F5. You should see a semitransparent message overlaid on the background. The weight value will change the degree of transparency, where a higher value makes the message stronger.

==Conclusion==
In this manual, we've covered the basic steps necessary to convert an existing example to a new filter, with pointers on how to extend the concepts to include any set of parameters, to return a clip or runtime variable, and to access pixels pairs as stored in YUY2 colour format. In the next set of tutorials, it is planned to cover other colour formats, and some notes on optimizing your code for better execution speed. I hope you have found this tutorial useful. If you have any comments or corrections, please see the ongoing discussion at: http://forum.doom9.org/forumdisplay.php?f=69

==External Links==
*[http://forum.doom9.org/showthread.php?p=1465008#post1465008 Doom9 Forum] - Includes corrections and additional information.
*[http://forum.doom9.org/showthread.php?p=1688939#post1688939 Doom9 Forum] - Continued discussion.

[[Category:AviSynth_Development]]
[[Category:FilterSDK]]

High bit-depth Support with Avisynth

2015-11-10T02:34:55Z

Jmac698: /* Image Magick */

== Introduction ==
Currently, Avisynth only supports 8-bit video. Nevertheless, through various utilities, plugins, and scripts, Avisynth can be used to import, process, and export high bit-depth video. There has been some effort to update Avisynth itself to support high bit-depth, but there has been no progress as of 2012 (http://forum.doom9.org/showthread.php?t=162436).
 
 
== What is Deep Color? ==

Deepcolor refers to using more than 8 bits of data to represent each color channel. It is also referred to as high bit-depth color. Basically, deepcolor/high bit-depth allows finer graduations of color, allowing smoother gradients and more detail. Please refer to this short, easy to understand article: [http://www.pcworld.com/article/171223/what_is_10bit_color.html PCWorld: What is 10-bit Color?]
 
 

== Why Use Deep Color? ==

*Higher internal precision, using high-bit depth color, when processing an image in a filter, gives a higher quality (8-bit) output.
*If a video filter uses linear gamma internally, there can be noticeable differences in the image. A linear gamma representation is best supported with a high bit-depth. See the illustration for [http://int64.org/projects/resamplehq/ ResampleHQ].
*If you encode high-bit depth video, you can get better compression (reportedly up to 30%) and less banding.
*Banding is one of the most serious liabilities of 8-bit depth. Refer to the following references for an explanation of why 10-bit encodes compress better:
**[http://x264.nl/x264/10bit_02-ateme-why_does_10bit_save_bandwidth.pdf Why does 10-bit save bandwidth (even when content is 8-bit)?.pdf]
**[http://x264.nl/x264/10bit_01-ateme_pierre_larbier_422_10-bit.pdf Using 10-bit AVC/H.264 Encoding with 4:2:2 for Broadcast Contribution.pdf]
**[http://x264.nl/x264/10bit_03-422_10_bit_pristine_video_quality.pdf Keeping Video Quality Pristine throughout the Production Process: 4:2:2 10-bit AVC/H.264 encoding.pdf]

 

== Importing High Bit-depth Video into AviSynth ==
For importing high bit depth video [http://sourceforge.net/projects/avisynth2/ AviSynth 2.6.0] or greater is strongly recommended. AviSynth 2.6 adds the additional [[planar]] color spaces ([[Y8]],[[YV16]],[[YV24]], [[YV411]]) which makes it that much more compatible with all of the existing formats.
 
 
=== [[FFmpegSource|FFMS2]] ===
'''Patched FFMS2''' - import DNxHD, ProRes, and other 10-bit videos in their native format (4:2:2 and 4:4:4 are also supported), output greater than 8-bits will always be in the [[Stack16]] format.

*Source code: [http://github.com/SAPikachu/ffms2_hacks GitHub repository]
*Discussion: [http://forum.doom9.org/showthread.php?t=164841 Doom9 thread] - Importing DNxHD to Avisynth (some of the links may be outdated; see downloads below or [http://forum.doom9.org/member.php?u=135430 SAPikachu's signature] for latest versions)

==== Download ====
Updated binaries: March 15, 2015 | [http://www.mediafire.com/folder/2izh9abzep52o/Video_works older versions]
* <code>[http://www.nmm-hd.org/upload/get~t6gq8DWihBs/ffms2-6e0d654+a9fe004-ffmbc-FFmbc-0.7.1.7z ffms2-6e0d654+a9fe004-ffmbc-FFmbc-0.7.1.7z]</code> | [http://web.archive.org/web/20150321005059/https://www.nmm-hd.org/upload/get~t6gq8DWihBs/ffms2-6e0d654+a9fe004-ffmbc-FFmbc-0.7.1.7z mirror] - This version uses [http://code.google.com/p/ffmbc/ FFmbc] as a decoder; may have better support for professional video formats like ProRes, DNxHD, etc.
* <code>[http://www.nmm-hd.org/upload/get~BLsLZwgj5ps/ffms2-6e0d654+a9fe004-ffmpeg-1e4d049.7z ffms2-6e0d654+a9fe004-ffmpeg-1e4d049.7z]</code> | [http://web.archive.org/web/20150321005255/https://www.nmm-hd.org/upload/get~BLsLZwgj5ps/ffms2-6e0d654+a9fe004-ffmpeg-1e4d049.7z mirror] - This version uses [http://en.wikipedia.org/wiki/FFmpeg FFmpeg] as a decoder; may be better for general (more common) formats.
* <code>[http://www.nmm-hd.org/upload/get~Q4mZfV9y0Og/ffms2-6e0d654+a9fe004-libav-9a60b1f.7z ffms2-6e0d654+a9fe004-libav-9a60b1f.7z]</code> | [http://web.archive.org/web/20150321005339/https://www.nmm-hd.org/upload/get~Q4mZfV9y0Og/ffms2-6e0d654+a9fe004-libav-9a60b1f.7z mirror] - This version uses [http://en.wikipedia.org/wiki/Libav Libav] as a decoder; may be better for general (more common) formats.
These versions work just like the official [[FFmpegSource|FFMS2]], but includes the additional {{FuncDef3|enable10bithack}} parameter and support for the additional [[planar]] colorspaces available is AviSynth 2.6. By default {{FuncDef3|enable10bithack}} is set to false so it will work just like the official FFMS2; to import high bit depth video set {{FuncDef3|enable10bithack}}<tt>=true</tt>, output will be in the [[Stack16]] format. 
See [http://github.com/mpv-player/mpv/wiki/FFmpeg-versus-Libav FFmpeg versus Libav] for information on pros and cons and differences between the FFmpeg and Libav. 

 

=== [[LSMASHSource]] ===
Another source filter to import regular 8-bit and high bit depth video. LSMASHSource includes these 2 fuctions to import video:
*[[LSMASHSource/LSMASHVideoSource|LSMASHVideoSource]] - This function uses [http://en.wikipedia.org/wiki/Libavcodec#Implemented_video_codecs libavcodec] as a video decoder and [http://github.com/l-smash/l-smash L-SMASH] as a demuxer. Recommended for MP4, MOV, [http://en.wikipedia.org/wiki/ISO_base_media_file_format ISO Base Media] and its derived file formats. 
*[[LSMASHSource/LWLibavVideoSource|LWLibavVideoSource]] - This function uses [http://en.wikipedia.org/wiki/Libavcodec#Implemented_video_codecs libavcodec] as a video decoder and [http://www.ffmpeg.org/libavformat.html libavformat] as a demuxer. 
 
=== [[VapourSource]] ===
Can be used to import [http://www.vapoursynth.com/ VapourSynth] scripts into AviSynth. Video can be 8-bit or greater. 
 

=== [[Image Magick]] ===
You can also import video or still via 16-bit PNG format pictures with the following Image Magick command lines (examples shown for Windows, requires the 16-bit version of Image Magick found at http://www.imagemagick.org/script/bi...es.php#windows, the file ImageMagick-x.y.z-a-Q16-x64)

Convert 16-bit to stacked (high/low or stack16 format):
<pre>
convert 16bit.png -depth 16 ( +clone -evaluate and 255 -evaluate multiply 256 ) -append stacked.png
</pre>

convert stacked (high/low) to 16bit:
<pre>
convert stacked.png -depth 16 -crop 100%x50% ( +clone -evaluate divide 256 ) -delete 1 -compose Add -composite -define png:bit-depth=16 16bit1.png
</pre>

For further explanation of these command lines, please see the thread http://forum.doom9.org/showthread.php?t=172846

=== Obsolete ===
'''The following methods are obsolete! If you must, only use as a verification or as workaround:''' 

*[http://forum.doom9.org/showthread.php?p=1526131#post1526131 Readv210mod] - Can read uncompressed v210 in .mov container as color. Needs a manual setting skip the file header.

*[http://sites.google.com/site/ourenthusiasmsasham/soft Sashimi] - Sashimi 0.85 has different bit-depth support. Please see OtherFormats/Read_v210.avs included in the package.

*[http://forum.doom9.org/showthread.php?t=158985 ReadV210] - Can read uncompressed v210 in .mov container as greyscale.
 
Alternative builds and methods of importing '''(also obsolete)''':

*[http://forum.doom9.org/showthread.php?p=1528494 ffms2mod] - Can return most 10bit video in the Avisynth high bit-depth convention.

*[http://forum.doom9.org/showthread.php?t=162598&page=2 RawSource with ffmpeg] - shows an example of using ffmpeg to convert to a 16bit format which can be read by RawSource in Avisynth 2.6.
 

== Processing High Bit-depth Video with AviSynth ==

Some plugins support processing internally in a higher bit-depth for better quality and return an 8-bit video. Others support full high-bit processing and can retun a special format 16 bit video.

Most developers have adopted a vertically stacked format known as [[Stack16]], where the high bits (MSB) are stored in the upper half of a video, and the lower bits (LSB) in the lower half of the video. 
This special format must be processed only with high-bit aware scripts and plugins. 
* Multipurpose
**'''[[Dither_tools|Dither]]''' - A set of scripts, original and modified plugins to process 16-bit clips. Some of the functions include 16-bit color space conversion, debanding, denoising, resizing, and dithering 16-bit to lower bit depths.
**'''[http://github.com/tp7/CLExpr/releases CLExpr]''' - OpenCl plugin for runtime calculation of expressions on 8 and 16-bit depths clips. Makes mt_lutxy and mt_lutxyz possible on 16-bit. More information [http://forum.doom9.org/showpost.php?p=1672638 here].
**'''[http://forum.doom9.org/showthread.php?t=154971 SmoothAdjust]''' - High quality YUV color adjustment plugin. SmoothAdjust can input and output 16-bits; all calculations are internally done in 32-bit float to avoid rounding errors and artifacts.

* Antialiasing
**'''[[Xaa]]''' - anti-aliasing and resizing script.

* Debanding
**'''[http://forum.doom9.org/showthread.php?t=161411 flash3kyuu_deband]''' - Debanding filter with 8/16 bit input/output. In addition flash3kyuu_deband can be used to dither 16-bit to lower bit depths.

* Degraining
**'''[[SMDegrain]]''' - mvtools+mdegrain denoising with 16-bit input and output.

* Denoising
**'''[http://forum.doom9.org/showthread.php?t=162342 DenoiseMD]''' - 8/16-bit denoise.
**'''[[Dfttest]]''' - 8/16-bit 2D/3D frequency domain denoiser.
**'''[http://forum.doom9.org/showthread.php?t=171379 KNLMeansCL]''' - OpenCL based Non Local Means denoising with support for 16-bit input and output.
**'''[http://forum.doom9.org/showthread.php?t=163018 RedAverage]''' - 16-bit capable average with masking. Download latest version [http://chaosking.de/wp-content/uploads/avsfilters/Unclassified/RedAverage___(1.4.3_-_2011-12-02).7z here]
**'''[http://forum.videohelp.com/threads/369142-Simple-MDegrain-Mod-v2-2d-A-Quality-Denoising-Solution SMDegrainMod]''' - 8/16 bit denoising with additional features like sharpening. [http://web.archive.org/web/20131210170708/http://doom10.org/index.php?topic=2178.0 Original Doom10 archived page.]
**'''[http://forum.doom9.org/showthread.php?t=167032 TempLinearApproximate]''' - 8/16 bit filter for temporal linear approximation between pixels . Meant mainly for denoising aid in motion compensated clips.

* Deringing
**[[HQDering_mod|'''HQDeringMod''']] - Deringing script with 16-bit input and output.

* Effects
**'''[[f3kgrain]]''' - Luma adaptive grain generator with 8/16-bit input and output.

* Frame Averaging
**'''[http://forum.doom9.org/showpost.php?p=1579509 AvgAll_16]''' - Average all frames in a clip with 16-bit accuracy.
**'''[http://forum.doom9.org/showthread.php?t=168048 ClipBlend16]''' - Blend an specified amount of frames into a single frame with 16-bit accuracy.

* Resizing
**'''[[Debicubic]]''' - This filter is designed to reverse the effects of bicubic upsampling. 8/16-bit input and output.
**'''[[Debilinear]]''' - This filter is designed to reverse the effects of bilinear upsampling. 8/16-bit input and output.
**'''[[nnedi3_resize16]]''' - An advanced script for high quality image resizing and colorspace conversion. It supports 16-bit input and output.
**'''[http://svn.int64.org/viewvc/int64/resamplehq/doc/index.html ResampleHQ]''' - Provides gamma-aware resizing and color space conversion. Uses 32-bit linear color internally but input and output is limited to 8-bit.
**'''[http://forum.videohelp.com/threads/369143-ResizersPack-MasksPack-PlaygroundPack-SmoothContrast-Logo-mod-functions?p=2364056 Resizers Functions Pack]''' - Includes LinearResize(), a function to resize in linear space. 8/16-bit input/output. [http://web.archive.org/web/20141105135234/http://doom10.org/index.php?topic=2182.0 Original Doom10 archived page.]

* Deprecated
**'''[http://forum.doom9.org/showthread.php?p=1467907#post1467907 Deep Color Tools]''' - This Script provides basic functions to import 10bit video, do color adjustments, and export to 8bit. (NOT RECOMMENDED, THERE ARE BETTER ALTERNATIVES)

You can also check the [[External_filters#Deepcolor_Filters|External Filters: DeepColor]] section, and the [[:Category:Deep_color_tools|Deep Color Tools]] category for possibly more listings.
 
 

== Codecs which support high bit-depth ==

*[http://en.wikipedia.org/wiki/Animation_codec Apple Animation]

*[http://en.wikipedia.org/wiki/DNxHD DNxHD] also supported by [http://code.google.com/p/ffmbc/ ffmbc]

*[http://en.wikipedia.org/wiki/H.264 H.264] - 10-bit YUV 4:2:0/4:2:2/4:4:4 available via x264 (lossy/lossless compression supported).

*[http://en.wikipedia.org/wiki/High_Efficiency_Video_Coding HEVC] - 10-bit YUV 4:2:0/4:2:2/4:4:4 available via x265 (lossy/lossless compression supported).

*[http://en.wikipedia.org/wiki/ProRes ProRes 422]

*[http://www.videohelp.com/tools/Ut-Video-Codec-Suite Ut Video Codec Suite] - YUV 4:2:2 10bit (lossless compression).

*[http://en.wikipedia.org/wiki/VP9 VP9] - support for YUV 4:2:0/4:2:2/4:4:4 10-12bit encoding via [http://en.wikipedia.org/wiki/VP9#Profiles profiles 2 and 3.]

*[http://azfcpug.org/wp-content/uploads/2011/02/Digital%20Video%20Acquisition%20Codecs.pdf Digital Video Acquisition Codecs.pdf] [http://web.archive.org/web/20141021023458/http://azfcpug.org/wp-content/uploads/2011/02/Digital%20Video%20Acquisition%20Codecs.pdf mirror]
 
== Exporting High Bit-depth Video ==

You can encode out of AviSynth to 10bit x264 via

*[http://tmod.nmm-hd.org/x264/ x264-tMod] - A modification to the x264 encoder to enable various enhancements, especially for the use of high-bit depth input. Supports the AviSynth high bit-depth convention, quality enhancements, bit-depth conversion, filters such as denoising and deinterlacing. 10bit x264 command-line example: <pre>avs2yuv -raw "script.avs" -o - | x264-10bit --demuxer raw --input-depth 10 --input-res 1280x720 --fps 24 --output "out.mp4" -</pre>

*[[Avs2YUV]]

*[[avs2pipemod]]

*[[avs4x264mod]] - This command-line tool will directly convert from a high bit-depth convention Avisynth script to H.264 with x264, including the 10bit profile. Please check the [http://astrataro.wordpress.com/category/encode/x264/avs4x26x/ blog] for updated versions. Example: <pre>avs4x264mod.exe --x264-binary “C:\x264_64-abc.exe” -o out.264 in.avs</pre>
 
Some tutorials on exporting high bit depth image sequences:
*[http://web.archive.org/web/20130914191039/http://blendervse.wordpress.com/2011/09/16/8bit-video-to-16bit-scene-referred-linear-exrs/ 8-bit video to 16-bit Scene Referred Linear .EXR’s]
*[http://web.archive.org/web/20131112191047/http://blendervse.wordpress.com/2013/03/23/pipe-to-rgb-quick-how-to/ Pipe To RGB – Quick How To]
*[http://web.archive.org/web/20131009105710/http://blendervse.wordpress.com/2013/03/12/pipe-to-rgb-avspmod-to-imagemagick/ Pipe To RGB – AvsPmod To ImageMagick]
 
== Playback of High Bit-depth Videos ==
*Most of the time you will only get to see dithered 8-bit video, as equipment to truly display high bit-depths is not as common at the consumer level in 2014 ([http://4ktvblog.com/10-bit-monitor list of 10-bit monitors]).

*The Blu-ray standard does not support high bit-depth video nor [http://en.wikipedia.org/wiki/XvYCC xvYCC] color space (full-range 8 bit video). On September 2014 it was announced that the up-and-coming [http://en.wikipedia.org/wiki/Blu-ray_Disc#4K_Blu-ray_Disc 4k Blu-ray] standard will support 10-bit video and a greater color gamut by using the [http://en.wikipedia.org/wiki/Rec._2020 Rec. 2020] color space.

*Digital theaters project up to 12-bit video; for more information read the wiki article: [http://en.wikipedia.org/wiki/Digital_Cinema_Initiatives#Image_and_audio_capability_overview Digital Cinema Initiatives]

'''Playback Software'''

*[http://forum.doom9.org/showthread.php?t=146228 MadVR]

*[http://mpc-hc.org/ MPC-HC]

*[http://forum.doom9.org/showthread.php?t=171120 MPDN]

*[http://www.videolan.org VLC]

'''Other Software and Information'''

*[http://forum.doom9.org/showthread.php?t=161548 Further information on high-bit playback]

*[http://haruhichan.com/wpblog/?p=205 An excellent guide on 10-bit playback]

*[http://forum.doom9.org/showthread.php?t=161915 FFdshow builds with 10-bit support] (deprecated)
 

== Sample High Bit-Depth Videos ==

See this thread for links to examples. There are also deepcolor versions of standard test clips (used in image processing research). http://forum.doom9.org/showthread.php?t=158836&highlight=v210

todo add: piping RGB48 data from avs2yuv and export 16bit image sequences in either .tif or .exr preferably using ImageMagick: http://www.imagemagick.org/discourse-server/viewtopic.php?f=1&t=18943 or .jp2 image sequences http://www.imagemagick.org/discourse-server/viewtopic.php?f=3&t=24718

[[Category:Advanced topics]]

High bit-depth Support with Avisynth

2015-11-10T02:32:51Z

Jmac698: /* VapourSource */

== Introduction ==
Currently, Avisynth only supports 8-bit video. Nevertheless, through various utilities, plugins, and scripts, Avisynth can be used to import, process, and export high bit-depth video. There has been some effort to update Avisynth itself to support high bit-depth, but there has been no progress as of 2012 (http://forum.doom9.org/showthread.php?t=162436).
 
 
== What is Deep Color? ==

Deepcolor refers to using more than 8 bits of data to represent each color channel. It is also referred to as high bit-depth color. Basically, deepcolor/high bit-depth allows finer graduations of color, allowing smoother gradients and more detail. Please refer to this short, easy to understand article: [http://www.pcworld.com/article/171223/what_is_10bit_color.html PCWorld: What is 10-bit Color?]
 
 

== Why Use Deep Color? ==

*Higher internal precision, using high-bit depth color, when processing an image in a filter, gives a higher quality (8-bit) output.
*If a video filter uses linear gamma internally, there can be noticeable differences in the image. A linear gamma representation is best supported with a high bit-depth. See the illustration for [http://int64.org/projects/resamplehq/ ResampleHQ].
*If you encode high-bit depth video, you can get better compression (reportedly up to 30%) and less banding.
*Banding is one of the most serious liabilities of 8-bit depth. Refer to the following references for an explanation of why 10-bit encodes compress better:
**[http://x264.nl/x264/10bit_02-ateme-why_does_10bit_save_bandwidth.pdf Why does 10-bit save bandwidth (even when content is 8-bit)?.pdf]
**[http://x264.nl/x264/10bit_01-ateme_pierre_larbier_422_10-bit.pdf Using 10-bit AVC/H.264 Encoding with 4:2:2 for Broadcast Contribution.pdf]
**[http://x264.nl/x264/10bit_03-422_10_bit_pristine_video_quality.pdf Keeping Video Quality Pristine throughout the Production Process: 4:2:2 10-bit AVC/H.264 encoding.pdf]

 

== Importing High Bit-depth Video into AviSynth ==
For importing high bit depth video [http://sourceforge.net/projects/avisynth2/ AviSynth 2.6.0] or greater is strongly recommended. AviSynth 2.6 adds the additional [[planar]] color spaces ([[Y8]],[[YV16]],[[YV24]], [[YV411]]) which makes it that much more compatible with all of the existing formats.
 
 
=== [[FFmpegSource|FFMS2]] ===
'''Patched FFMS2''' - import DNxHD, ProRes, and other 10-bit videos in their native format (4:2:2 and 4:4:4 are also supported), output greater than 8-bits will always be in the [[Stack16]] format.

*Source code: [http://github.com/SAPikachu/ffms2_hacks GitHub repository]
*Discussion: [http://forum.doom9.org/showthread.php?t=164841 Doom9 thread] - Importing DNxHD to Avisynth (some of the links may be outdated; see downloads below or [http://forum.doom9.org/member.php?u=135430 SAPikachu's signature] for latest versions)

==== Download ====
Updated binaries: March 15, 2015 | [http://www.mediafire.com/folder/2izh9abzep52o/Video_works older versions]
* <code>[http://www.nmm-hd.org/upload/get~t6gq8DWihBs/ffms2-6e0d654+a9fe004-ffmbc-FFmbc-0.7.1.7z ffms2-6e0d654+a9fe004-ffmbc-FFmbc-0.7.1.7z]</code> | [http://web.archive.org/web/20150321005059/https://www.nmm-hd.org/upload/get~t6gq8DWihBs/ffms2-6e0d654+a9fe004-ffmbc-FFmbc-0.7.1.7z mirror] - This version uses [http://code.google.com/p/ffmbc/ FFmbc] as a decoder; may have better support for professional video formats like ProRes, DNxHD, etc.
* <code>[http://www.nmm-hd.org/upload/get~BLsLZwgj5ps/ffms2-6e0d654+a9fe004-ffmpeg-1e4d049.7z ffms2-6e0d654+a9fe004-ffmpeg-1e4d049.7z]</code> | [http://web.archive.org/web/20150321005255/https://www.nmm-hd.org/upload/get~BLsLZwgj5ps/ffms2-6e0d654+a9fe004-ffmpeg-1e4d049.7z mirror] - This version uses [http://en.wikipedia.org/wiki/FFmpeg FFmpeg] as a decoder; may be better for general (more common) formats.
* <code>[http://www.nmm-hd.org/upload/get~Q4mZfV9y0Og/ffms2-6e0d654+a9fe004-libav-9a60b1f.7z ffms2-6e0d654+a9fe004-libav-9a60b1f.7z]</code> | [http://web.archive.org/web/20150321005339/https://www.nmm-hd.org/upload/get~Q4mZfV9y0Og/ffms2-6e0d654+a9fe004-libav-9a60b1f.7z mirror] - This version uses [http://en.wikipedia.org/wiki/Libav Libav] as a decoder; may be better for general (more common) formats.
These versions work just like the official [[FFmpegSource|FFMS2]], but includes the additional {{FuncDef3|enable10bithack}} parameter and support for the additional [[planar]] colorspaces available is AviSynth 2.6. By default {{FuncDef3|enable10bithack}} is set to false so it will work just like the official FFMS2; to import high bit depth video set {{FuncDef3|enable10bithack}}<tt>=true</tt>, output will be in the [[Stack16]] format. 
See [http://github.com/mpv-player/mpv/wiki/FFmpeg-versus-Libav FFmpeg versus Libav] for information on pros and cons and differences between the FFmpeg and Libav. 

 

=== [[LSMASHSource]] ===
Another source filter to import regular 8-bit and high bit depth video. LSMASHSource includes these 2 fuctions to import video:
*[[LSMASHSource/LSMASHVideoSource|LSMASHVideoSource]] - This function uses [http://en.wikipedia.org/wiki/Libavcodec#Implemented_video_codecs libavcodec] as a video decoder and [http://github.com/l-smash/l-smash L-SMASH] as a demuxer. Recommended for MP4, MOV, [http://en.wikipedia.org/wiki/ISO_base_media_file_format ISO Base Media] and its derived file formats. 
*[[LSMASHSource/LWLibavVideoSource|LWLibavVideoSource]] - This function uses [http://en.wikipedia.org/wiki/Libavcodec#Implemented_video_codecs libavcodec] as a video decoder and [http://www.ffmpeg.org/libavformat.html libavformat] as a demuxer. 
 
=== [[VapourSource]] ===
Can be used to import [http://www.vapoursynth.com/ VapourSynth] scripts into AviSynth. Video can be 8-bit or greater. 
 

=== [[Image Magick]] ===
You can also import video or still via 16-bit PNG format pictures with the following Image Magick command lines (examples shown for Windows, requires the 16-bit version of Image Magick found at http://www.imagemagick.org/script/bi...es.php#windows, the file ImageMagick-x.y.z-a-Q16-x64)

Convert 16-bit to stacked (high/low or stack16 format):
[code]
convert 16bit.png -depth 16 ( +clone -evaluate and 255 -evaluate multiply 256 ) -append stacked.png
[/code]

convert stacked (high/low) to 16bit:
[code]
convert stacked.png -depth 16 -crop 100%x50% ( +clone -evaluate divide 256 ) -delete 1 -compose Add -composite -define png:bit-depth=16 16bit1.png
[/code]

For further explanation of these command lines, please see the thread http://forum.doom9.org/showthread.php?t=172846

=== Obsolete ===
'''The following methods are obsolete! If you must, only use as a verification or as workaround:''' 

*[http://forum.doom9.org/showthread.php?p=1526131#post1526131 Readv210mod] - Can read uncompressed v210 in .mov container as color. Needs a manual setting skip the file header.

*[http://sites.google.com/site/ourenthusiasmsasham/soft Sashimi] - Sashimi 0.85 has different bit-depth support. Please see OtherFormats/Read_v210.avs included in the package.

*[http://forum.doom9.org/showthread.php?t=158985 ReadV210] - Can read uncompressed v210 in .mov container as greyscale.
 
Alternative builds and methods of importing '''(also obsolete)''':

*[http://forum.doom9.org/showthread.php?p=1528494 ffms2mod] - Can return most 10bit video in the Avisynth high bit-depth convention.

*[http://forum.doom9.org/showthread.php?t=162598&page=2 RawSource with ffmpeg] - shows an example of using ffmpeg to convert to a 16bit format which can be read by RawSource in Avisynth 2.6.
 

== Processing High Bit-depth Video with AviSynth ==

Some plugins support processing internally in a higher bit-depth for better quality and return an 8-bit video. Others support full high-bit processing and can retun a special format 16 bit video.

Most developers have adopted a vertically stacked format known as [[Stack16]], where the high bits (MSB) are stored in the upper half of a video, and the lower bits (LSB) in the lower half of the video. 
This special format must be processed only with high-bit aware scripts and plugins. 
* Multipurpose
**'''[[Dither_tools|Dither]]''' - A set of scripts, original and modified plugins to process 16-bit clips. Some of the functions include 16-bit color space conversion, debanding, denoising, resizing, and dithering 16-bit to lower bit depths.
**'''[http://github.com/tp7/CLExpr/releases CLExpr]''' - OpenCl plugin for runtime calculation of expressions on 8 and 16-bit depths clips. Makes mt_lutxy and mt_lutxyz possible on 16-bit. More information [http://forum.doom9.org/showpost.php?p=1672638 here].
**'''[http://forum.doom9.org/showthread.php?t=154971 SmoothAdjust]''' - High quality YUV color adjustment plugin. SmoothAdjust can input and output 16-bits; all calculations are internally done in 32-bit float to avoid rounding errors and artifacts.

* Antialiasing
**'''[[Xaa]]''' - anti-aliasing and resizing script.

* Debanding
**'''[http://forum.doom9.org/showthread.php?t=161411 flash3kyuu_deband]''' - Debanding filter with 8/16 bit input/output. In addition flash3kyuu_deband can be used to dither 16-bit to lower bit depths.

* Degraining
**'''[[SMDegrain]]''' - mvtools+mdegrain denoising with 16-bit input and output.

* Denoising
**'''[http://forum.doom9.org/showthread.php?t=162342 DenoiseMD]''' - 8/16-bit denoise.
**'''[[Dfttest]]''' - 8/16-bit 2D/3D frequency domain denoiser.
**'''[http://forum.doom9.org/showthread.php?t=171379 KNLMeansCL]''' - OpenCL based Non Local Means denoising with support for 16-bit input and output.
**'''[http://forum.doom9.org/showthread.php?t=163018 RedAverage]''' - 16-bit capable average with masking. Download latest version [http://chaosking.de/wp-content/uploads/avsfilters/Unclassified/RedAverage___(1.4.3_-_2011-12-02).7z here]
**'''[http://forum.videohelp.com/threads/369142-Simple-MDegrain-Mod-v2-2d-A-Quality-Denoising-Solution SMDegrainMod]''' - 8/16 bit denoising with additional features like sharpening. [http://web.archive.org/web/20131210170708/http://doom10.org/index.php?topic=2178.0 Original Doom10 archived page.]
**'''[http://forum.doom9.org/showthread.php?t=167032 TempLinearApproximate]''' - 8/16 bit filter for temporal linear approximation between pixels . Meant mainly for denoising aid in motion compensated clips.

* Deringing
**[[HQDering_mod|'''HQDeringMod''']] - Deringing script with 16-bit input and output.

* Effects
**'''[[f3kgrain]]''' - Luma adaptive grain generator with 8/16-bit input and output.

* Frame Averaging
**'''[http://forum.doom9.org/showpost.php?p=1579509 AvgAll_16]''' - Average all frames in a clip with 16-bit accuracy.
**'''[http://forum.doom9.org/showthread.php?t=168048 ClipBlend16]''' - Blend an specified amount of frames into a single frame with 16-bit accuracy.

* Resizing
**'''[[Debicubic]]''' - This filter is designed to reverse the effects of bicubic upsampling. 8/16-bit input and output.
**'''[[Debilinear]]''' - This filter is designed to reverse the effects of bilinear upsampling. 8/16-bit input and output.
**'''[[nnedi3_resize16]]''' - An advanced script for high quality image resizing and colorspace conversion. It supports 16-bit input and output.
**'''[http://svn.int64.org/viewvc/int64/resamplehq/doc/index.html ResampleHQ]''' - Provides gamma-aware resizing and color space conversion. Uses 32-bit linear color internally but input and output is limited to 8-bit.
**'''[http://forum.videohelp.com/threads/369143-ResizersPack-MasksPack-PlaygroundPack-SmoothContrast-Logo-mod-functions?p=2364056 Resizers Functions Pack]''' - Includes LinearResize(), a function to resize in linear space. 8/16-bit input/output. [http://web.archive.org/web/20141105135234/http://doom10.org/index.php?topic=2182.0 Original Doom10 archived page.]

* Deprecated
**'''[http://forum.doom9.org/showthread.php?p=1467907#post1467907 Deep Color Tools]''' - This Script provides basic functions to import 10bit video, do color adjustments, and export to 8bit. (NOT RECOMMENDED, THERE ARE BETTER ALTERNATIVES)

You can also check the [[External_filters#Deepcolor_Filters|External Filters: DeepColor]] section, and the [[:Category:Deep_color_tools|Deep Color Tools]] category for possibly more listings.
 
 

== Codecs which support high bit-depth ==

*[http://en.wikipedia.org/wiki/Animation_codec Apple Animation]

*[http://en.wikipedia.org/wiki/DNxHD DNxHD] also supported by [http://code.google.com/p/ffmbc/ ffmbc]

*[http://en.wikipedia.org/wiki/H.264 H.264] - 10-bit YUV 4:2:0/4:2:2/4:4:4 available via x264 (lossy/lossless compression supported).

*[http://en.wikipedia.org/wiki/High_Efficiency_Video_Coding HEVC] - 10-bit YUV 4:2:0/4:2:2/4:4:4 available via x265 (lossy/lossless compression supported).

*[http://en.wikipedia.org/wiki/ProRes ProRes 422]

*[http://www.videohelp.com/tools/Ut-Video-Codec-Suite Ut Video Codec Suite] - YUV 4:2:2 10bit (lossless compression).

*[http://en.wikipedia.org/wiki/VP9 VP9] - support for YUV 4:2:0/4:2:2/4:4:4 10-12bit encoding via [http://en.wikipedia.org/wiki/VP9#Profiles profiles 2 and 3.]

*[http://azfcpug.org/wp-content/uploads/2011/02/Digital%20Video%20Acquisition%20Codecs.pdf Digital Video Acquisition Codecs.pdf] [http://web.archive.org/web/20141021023458/http://azfcpug.org/wp-content/uploads/2011/02/Digital%20Video%20Acquisition%20Codecs.pdf mirror]
 
== Exporting High Bit-depth Video ==

You can encode out of AviSynth to 10bit x264 via

*[http://tmod.nmm-hd.org/x264/ x264-tMod] - A modification to the x264 encoder to enable various enhancements, especially for the use of high-bit depth input. Supports the AviSynth high bit-depth convention, quality enhancements, bit-depth conversion, filters such as denoising and deinterlacing. 10bit x264 command-line example: <pre>avs2yuv -raw "script.avs" -o - | x264-10bit --demuxer raw --input-depth 10 --input-res 1280x720 --fps 24 --output "out.mp4" -</pre>

*[[Avs2YUV]]

*[[avs2pipemod]]

*[[avs4x264mod]] - This command-line tool will directly convert from a high bit-depth convention Avisynth script to H.264 with x264, including the 10bit profile. Please check the [http://astrataro.wordpress.com/category/encode/x264/avs4x26x/ blog] for updated versions. Example: <pre>avs4x264mod.exe --x264-binary “C:\x264_64-abc.exe” -o out.264 in.avs</pre>
 
Some tutorials on exporting high bit depth image sequences:
*[http://web.archive.org/web/20130914191039/http://blendervse.wordpress.com/2011/09/16/8bit-video-to-16bit-scene-referred-linear-exrs/ 8-bit video to 16-bit Scene Referred Linear .EXR’s]
*[http://web.archive.org/web/20131112191047/http://blendervse.wordpress.com/2013/03/23/pipe-to-rgb-quick-how-to/ Pipe To RGB – Quick How To]
*[http://web.archive.org/web/20131009105710/http://blendervse.wordpress.com/2013/03/12/pipe-to-rgb-avspmod-to-imagemagick/ Pipe To RGB – AvsPmod To ImageMagick]
 
== Playback of High Bit-depth Videos ==
*Most of the time you will only get to see dithered 8-bit video, as equipment to truly display high bit-depths is not as common at the consumer level in 2014 ([http://4ktvblog.com/10-bit-monitor list of 10-bit monitors]).

*The Blu-ray standard does not support high bit-depth video nor [http://en.wikipedia.org/wiki/XvYCC xvYCC] color space (full-range 8 bit video). On September 2014 it was announced that the up-and-coming [http://en.wikipedia.org/wiki/Blu-ray_Disc#4K_Blu-ray_Disc 4k Blu-ray] standard will support 10-bit video and a greater color gamut by using the [http://en.wikipedia.org/wiki/Rec._2020 Rec. 2020] color space.

*Digital theaters project up to 12-bit video; for more information read the wiki article: [http://en.wikipedia.org/wiki/Digital_Cinema_Initiatives#Image_and_audio_capability_overview Digital Cinema Initiatives]

'''Playback Software'''

*[http://forum.doom9.org/showthread.php?t=146228 MadVR]

*[http://mpc-hc.org/ MPC-HC]

*[http://forum.doom9.org/showthread.php?t=171120 MPDN]

*[http://www.videolan.org VLC]

'''Other Software and Information'''

*[http://forum.doom9.org/showthread.php?t=161548 Further information on high-bit playback]

*[http://haruhichan.com/wpblog/?p=205 An excellent guide on 10-bit playback]

*[http://forum.doom9.org/showthread.php?t=161915 FFdshow builds with 10-bit support] (deprecated)
 

== Sample High Bit-Depth Videos ==

See this thread for links to examples. There are also deepcolor versions of standard test clips (used in image processing research). http://forum.doom9.org/showthread.php?t=158836&highlight=v210

todo add: piping RGB48 data from avs2yuv and export 16bit image sequences in either .tif or .exr preferably using ImageMagick: http://www.imagemagick.org/discourse-server/viewtopic.php?f=1&t=18943 or .jp2 image sequences http://www.imagemagick.org/discourse-server/viewtopic.php?f=3&t=24718

[[Category:Advanced topics]]