Filter SDK/Compiling instructions

Latest revision as of 00:41, 4 January 2019

[edit] Introduction

The Avisynth API is a C++ API, but that doesn't mean that you can use every C++ compiler to compile your plugin. Unfortunately compilers have different ideas about what the C++ ABI should look like. In practice, this means that if you want things to work 100% as expected, you must compile your plugin with the same compiler that was used to compile AviSynth. That's MSVC 6.0 for official builds. Later versions of MSVC will kinda sorta work, as will ICL (up to ICL10.1), but there are caveats (for example, you must never allow any C++ exceptions to escape your plugin ever - use ThrowError() instead - and you must always make sure memory allocated by AviSynth is freed by AviSynth itself and not by your plugin). So unfortunately it matters what C++ compiler will be used to compile a plugin.

An application binary interface (ABI) specifies how software components should interact with each other at the binary level (in this case AviSynth and a plugin). ABIs cover details such as the sizes, layout, and alignment of data types, the calling convention of functions' arguments that are passed and returned. It standardizes details such as the C++ name mangling and exception propagation. The problem is that there are different C++ ABIs.

Microsoft set their general C++ ABI with their first C++ compilers, and it has had some changes along the years and versions of their compiler suite. Intel and Borland, among others, support the Microsoft ABI, and thus things built with the other generally work, just like with Linux and the ABI used by GCC. Enter MinGW.

Instead of implementing the Microsoft ABI, the people at GCC and MinGW decided to just use the same C++ ABI on Windows as they use everywhere else. Thus we have two groups of compilers that use a different ABI. It will give issues if you try to load a mingw-built C++ API DLL from a MSVC-built Avisynth. The opposite will not work, either. The C interface was made exactly for this reason, as pretty much by chance the ABI for C is (more or less) set, and thus it is generally OK to mix binaries created by different C compilers.

This is why the Avisynth C API exists: if you want a portable API, you want a C API. C++ API's are more or less by definition unportable.

This section explains how to compile Avisynth plugins that are using the C++ API and that are using the C API. For the latter see the MSVC++ 2010 section.

[edit] Further reading

If you want extra reading regarding calling conventions and name mangling and such ABI-related things, you can read the following PDF that lists quite a few things of various implementations. Available here. Basically these things in general are not fixable by a mere header, you would have to patch a compiler for the other calling convention, as well as handle exceptions so that the other side would understand it as well. And so forth, and so forth. (source: Doom9 forum posts: [1], [2].)

[edit] Installing necessary software

For installing software and setting up environments have a look at necessary software and necessary software and setting up environments.

[edit] Compiling AviSynth plugins step by step instructions (for MS VC++ 6.0)

Open VC++. Select a new project: Go to the File tab -> New. Select a Win32 Dynamic-Link Library in the Projects tab:

Add the location of your project and the Project Name. The location is the project folder where the source of your project will be.

Select "An empty DLL project":

Copy existing source files (*.cpp), headers (*.h) and avisynth.h in your project folder. If you started from scratch, you only need to copy avisynth.h in your project folder.

Go to the Project tab -> Add To Project -> Files:

Add the existing source files (*.cpp), headers (*.h) and avisynth.h to your project. If you start from scratch, you need to a new files to your project:

Go to the Project tab -> Add To project -> New:

1) Select C++ source file, and give it a name. 2) Select C/C++ header file (if you are going to use one), and give it a name.

Go to the Build tab -> Set Active Configuration -> select the release build.

If you go to the Project tab again -> Settings. Then you should see something similar as this:

Save your workspace: File -> Save Workspace.

Finally, code your source/header files, and compile your plugin. Go to the Build tab -> Build (...)

[edit] Compiling AviSynth plugins step by step instructions (for MS VC++ 2005 Express Edition)

[edit] How to compile existent (old MS VC 6.0) plugin with MS VC++ 2005

• Start VC++ 2005, go to folder with old plugin (e.g. SimpleSample) unpacked zip file with full source codes and project files, and open plugin workspace file SimpleSample.dsw.

• Agree in dialog to convert and open this project.

• Go to menu Build -> Configuration Manager, Set active solution configuration to Release (or Debug if you want firsly debug it).

• Go to Build -> Build Solution (F7) to compile and create SimpleSample.dll

• If you get fatal error LNK1181: cannot open input file 'odbc32.lib', then go to menu Project -> SimpleSample Properties. Select Configuration Properties -> Linker -> Input -> Additional Dependencies, and remove extra unneeded libraries like odbc32.lib, odbccp32.lib.

• Also check Linker -> Output File option there and set approriate pathname (or Inherit From Process default).

• You can make some changes (edit) of source codes if you want.

• Repeat command Build -> Build Solution (F7) to compile and create SimpleSample.dll

[edit] How to create new plugin from scratch with MS VC++ 2005

• Start VC++2005.
• Menu: fiIe -> Create new project.
• Select Win32 console appication.
• Enter name of your new project and press OK.
• You will in Win32 Appcilation Wizard. Press Application Settings (left panel).
• Select Application Type as DLL (but it may be console too).
• At Additional options select "Empty project"
• Copy files to project folder with Explorer.
• Add header file avisynth.h to the project: Menu Project -> Add existent item. Also add existant (e.g. simplesample.cpp) or create new CPP files by Project -> Add new item.
• Go to menu Build -> Configuration Manager, Set active solution configuration to Release (or Debug if you want firsly debug it).
• Make some changes (edit) of source codes to implement your algorithm. See SimpleSample or some other open source plugin source code and Avisynth Filter SDK for details.
• Go to Build -> Build Solution (F7) to compile and create plugin SimpleSample.dll

[edit] Compiling AviSynth plugins step by step instructions (for MS VC++ 2008 Professional Edition)

• In this guide, we will compile the Example plugin from CPP for C programmers, from http://forum.doom9.org/showthread.php?p=1538557#post1538557 or directly from http://www.mediafire.com/download.php?tc61m9otustmy29
• Start Microsoft Visual Studio 2008
• Upon first start, you are asked to set up your environment. You may choose the typical Visual C++ option
• Choose File->New->Project or click the New Project icon
• On the left pane, under Project Types, expand Visual C++ and select Win32
• On the right pane, choose Win32 Console Application
• Enter a name for your project (in this example we will use Example), click OK
• You may get an error: An error has occurred in this dialog, Error: 54, Unspecified Error. This may be because you installed some windows updates but didn't reboot yet. Click OK.
• You are shown the current project settings. Click Next.
• Under Application Type, click the DLL option. Under Additional options, check the Empty project box.
• A new directory is created, My Documents\Visual Studio 2008\Projects\Example
• You need to extract the files from our example plugin into My Documents\Visual Studio 2008\Projects\Example\Example
• In the default layout, there is a Solution Explorer pane on the left side. Right click Header Files, and select Add->Existing Item, select avisynth.h and click Add
• Continue to add the other files, Info.h and InfoF.h
• Right click Source Files, select Add->Existing Item, and select Example.cpp
• Click Build->Build Solution (this will give errors!)
• There's a lot of errors about OutputDebugStringW. To fix this, select Project->Example Properties
• In the left pane, Expand Configuration Properties, select General
• In the right pane, click Character Set. Use the drop-down to select Use Multi-Byte Character Set. Click OK.
• Click Build->Build Solution (this may give errors!)
• In the version 0.3 of the plugin, there was an error, 'example.cpp(610) : error C4430: missing type specifier - int assumed'. To fix this, double-click that error line to highlight it's location in the example.cpp source file. Change 'const wstep = (vi.IsRGB24()) ? 3 : 4; // 3 bytes for RGB24, & 4 for RGB32.' to 'const int wstep = (vi.IsRGB24()) ? 3 : 4; // 3 bytes for RGB24, & 4 for RGB32.'
• Click Build->Build Solution
• If you get an error 'unresolved external symbol _main referenced in function ___tmainCRTStartup', then you're trying to build an .exe. Use Project->Example Properties, Configuration Properties, General, set Configuration Type to Dynamic Library (.dll)
• By default, a debug version is made. To change this, Build->Configuration Manager, select Release in the left drop-down
• You will have to re-apply the configuration changes: Project->Example Properties, Configuration Properties, General, Configuration Type=Dynamic Library (.dll) and Character Set=Use Multi-Byte Character Set
• The following file should appear: My Documents\Visual Studio 2008\Projects\Example\Release\Example.dll. Note that there is also a directory My Documents\Visual Studio 2008\Projects\Example\Example\Release which contains only tempory files, but not the dll. This is set under Project->Example Properties, General, Output Directory=$(SolutionDir)$(ConfigurationName), Intermediate Directory=$(ConfigurationName). In this case $(SolutionDir)=My Documents\Visual Studio 2008\Projects\Example, $(ConfigurationName)=Release.
• You need to copy Example.dll to your Avisynth plugins directory, and then test it with the Example.avs file.
• If everything worked, you can proceed to modify the example by following the comments, or also using the SimnpleSample included in the Avisynth distribution.

[edit] Compiling AviSynth plugins or console applications step by step instructions (for MS VC++ 2010 Express and Professional Edition)

These instructions are also valid for the 2008 editions. Be sure to start with the necessary software and necessary software and setting up environments.

[edit] Creating a new project

Open MSVC++ 2010. Select a new project:

Select a Win32 Console Application. Add the location of your project and the project name. The Location\Name will be the project folder (or Solution Directory as MSVC++ 2010 calls it) where the source of your project will be. If the folder "Name" already exists the 'Create directory for solution' box should be left unchecked, otherwise it will create as a subfolder regardless.

Select application settings. When creating a plugin check the application type 'DLL' and when creating a console application (such as avs2wav.exe for example) check the application type 'Console application'. Also check the additional option 'Empty project' boxes. Click on finish:

[edit] Adding files to the project

In the Solution Explorer window, the solution has the 'folders' External Dependencies, Header Files, Resource Files and Source Files:

• When creating a plugin using the C++ API, you need to copy the existing source files (*.cpp), headers (*.h) and avisynth.h in your project folder. If you started from scratch, you only need to copy avisynth.h in your project folder.

• When creating a plugin using the C API, you need to copy the existing source files (*.c), headers (*.h) and avisynth_c.h in your project folder. If you started from scratch, you only need to copy avisynth_c.h in your project folder. Note make sure your source files end with '.c' instead of '.cpp' (that's how for example MSVC++ knows it's C code).

You can add the source and header files to your project by right-clicking on a 'folder' (say Header Files as in the screenshot below), select Add and Existing Item (or New Item if you start from scratch):

When creating a plugin using the C API, you need to do two additional things:

• You need to link to avisynth.lib (create the folder InvertNeg/lib and copy the library to it). In the linker add lib\avisynth.lib under 'Additional Dependencies' (both for the release and debug configuration):

• When compiling with MSVC++ you also need to add a definition file to your project (otherwise LoadCPlugin can't load the library). Create a text file (here named InvertNeg.def), add it to your project (under source files) and add it to the 'Module Definition File' in the linker (both for the release and debug configuration):

Select the release build, since we are building the release build.

[edit] General settings

If it's your first time you use the compiler, you need to select the expert settings to make the build tab visible:

Tools > Settings > Expert Settings

In the property page you can see (and change) the location of the DLL that will be build:

Right click on the project name (InvertNeg in our case) > Properties > Configuration Properties > General

The default location is $(SolutionDir)$(Configuration)\. You have set the 'SolutionDir' when defining the project (D:\AviSynth\Plugins\InvertNeg in our case). 'Configuration' will be the Release or Debug folder depending on which configuration you have selected.

Next you need to be aware of the VC++ Directories and change them if necessary:

Right click on the project name (InvertNeg in our case) > Properties > Configuration Properties > VC++ Directories

Here you will find the location of the 'Include Directories' and others. $(VCInstallDir)include points to the include folder of MSVC++ 2010 and $(WindowsSdkDir)include to the include folder of the Microsoft Platform SDK. When including headers (such as windows.h) in your project they will be searched for in the include folders (unless you explicitly add its location when including them). So both of them should point to the correct folders.

Note that in general windows.h should be included in your project. It is the header file for accessing the Win32 API through C/C++ and it is located in the include folder of the Microsoft Platform SDK.

You can see the values of VCInstallDir and WindowsSdkDir when opening the VS command prompt:

Tools > Visual Studio > Command Prompt

The VS command prompt will be loaded. Type set and you will see the variables. They will be set when starting MSVC++ 2010 (by vsvars32.bat which is located in your <VisualStudioInstallDir>\Common7\Tools folder).

[edit] Building the plugin or console application

Now you are ready to build you DLL/EXE. Go to

Build > Build Solution

And you will find your compiled plugin in the Location\Name\Folder.