Filter SDK

From Avisynth wiki
Revision as of 01:09, 25 December 2014 by Admin (Talk | contribs)

Jump to: navigation, search

AviSynth external Filter SDK is a package for developers to create your own filters (plugins and console applications) for AviSynth.

The package consists of:

  • this documentation text files (in HTML or Wiki format);
  • the header files 'avisynth.h' (for the use of the C++ API) and 'avisynth_c.h' (for the use of the C API) with all declarations to include in plugin source code;
  • several plugin and console application source codes;
  • some extra files in 'Extra' folder.

Contents

Necessary software

You must have some necessary software.

Writing a plugin

We will start by writing some simple plugins to show you the basics.

Processing video

  • InvertNeg produces a photo-negative of the input clip.
  • SimpleSample has some very simple examples covering development of a filter that draws a variable sized square, in the middle of the screen. It does so for all color formats.

One thing not covered in the examples, is how to change frame size in a filter.

Processing audio

  • xxx

Also have a look at Getting started with Audio.

Runtime functions

See Non-clip sample how to create runtime AviSynth functions.

Source filters

  • RandomSource - Simple source filter example by StainlessS.

Speeding up your plugin using assembler

You can also browse various topics on Assembler Optimizing.

Making dual plugins

One of the features of AviSynth 2.6 is that 2.5 plugins (plugins compiled with plugin api v3) can still be used in AviSynth 2.6, although you need to make sure you use it properly since it doesn't know about the new features in AviSynth 2.6. So when processing a clip (with say color format YV16) with a 2.5 plugin you will get a messed up clip at best, and a crash at worst, since YV16 is not supported in the v3 api.

There are several ways to make 2.6 plugins (plugins compiled with plugin api v5 or higher) also work with AviSynth 2.5. They are described here.

Writing utilities that access AviSynth

When writing console applications (commandline programs) it is possible to access AviSynth in two ways.

The first one is to use the VfW api (using the AVIFile library) like is done in avs2avi (see [1] or [2]), avs2yuv (using the C api, or using the C++ api), or avs2wav for example. See also here to get you going.

The second one is to call AviSynth directly like is done in avs2pipe for example (it uses the C api). It's a tool to output y4m video or wav audio to stdout. The way to do this is importing avisynth.dll via loadlibrary() and getprocaddress(). Then creating a scriptenvironment and importing a script using invoke(). At that point you will have a clip from which you can call getframe() to access the video and getaudio() to access the audio.

Below are some examples that have a script as input and raw video or audio as output:

  • avs2yuv reads a script and outputs raw video.
  • avs2pcm reads a script and outputs raw audio.

AviSynth and its plugin api's

AviSynth exists as an instance of the ScriptEnvironment class, that implements the IScriptEnvironment interface. The IScriptEnvironment interface is defined in avisynth.h (and avisynth_c.h) and it is the only way for plugins and external applications to communicate with AviSynth. A pointer to ScriptEnvironment object is passed along to all plugins, so that they can use AviSynth facilities. Plugins are forbidden from storing this pointer. AviSynth creates one ScriptEnvironment object when Windows attempts to use AviSynth to open a script via AVIFile API.

When ScriptEnvironment is created, it checks for CPU extensions (to provide this information to filters that are able to use CPU extensions), sets up memory limits for itself and performs pre-scanning of all plugins.

AviSynth has the capability to load third-party libraries that include their own video and audio filters. It comes with two language interfaces (or plugin api's):

  • C++ API (through avisynth.h) - The classes and miscellaneous constants are described in here.
  • C API (through avisynth_c.h) - The classes and miscellaneous constants are described in here.

The built-in filters use the C++ API. This Filter SDK (or Source Development Kit) describes how to create plugins using both interfaces.

Although not included in AviSynth itself, several people wrote other language interfaces in Delphi, Purebasic, NET and Java. They can be found here.

...

There are several different Colorspaces in AviSynth. See more information about Color spaces and Working with Images.

Read more about the Internal Functions in AviSynth.

...

What's new in the 2.6 api

  • C++ API (AVISYNTH_INTERFACE_VERSION = 6):
    • Plugin api v3 and older contains baked code which is code that is included inline. The result is all that code is "baked" into all and every plugin instead being called from avisynth.dll. This issue is solved in 2.6. Starting from 2.6 the version 2.5 plugins are supported directly (with current baked code; meaning that plugins compiled for 2.5 can be loaded when using 2.6) and all the baked code from 2.6+ plugins is removed and the plugins are still source compatible. Note that the baked code is moved to interface.cpp, where also the structure AVS_Linkage is defined.
    • GetVarDef can be used to access AviSynth variables. It will not throw an error if the variable doesn't exist.
    • DeleteScriptEnvironment provides a method to delete the ScriptEnvironment which is created with CreateScriptEnvironment.
    • ApplyMessage writes text on a frame.
    • GetAVSLinkage returns the AVSLinkage.
    • It uses size_t for things that are memory sizes, ready for 64 bit port.
    • It support the new colorformats Y8, YV411, YV16 and YV24.
    • todo: See v5 constants and functions in: VideoInfo. See also the cache and cpu constants in Cplusplus_API.
  • C API (AVISYNTH_INTERFACE_VERSION = 5):
    • The following functions are added to the interface: avs_is_yv24, avs_is_yv16, avs_is_yv12, avs_is_yv411, avs_is_y8, avs_is_color_space, avs_get_plane_width_subsampling, avs_get_plane_height_subsampling, avs_bits_per_pixel, avs_bytes_from_pixels, avs_row_size, avs_bmp_size, avs_get_row_size_p and avs_get_height_p.

Some history

Ben's AviSynth Docs is the documentation written for AviSynth 1.0 by Ben Rudiak-Gould, in its original form.

See more about the modifications for AviSynth 2.5 in the AviSynth Two-Five SDK.

Please read AviSynth SDK History. ---

Other sources ???

Once you've got the basics down on AVS development (Ben's text is quite good), the SDK for VirtualDub is also a good read. Good news is you won't have to worry about writing function pointers and raw Win32; meanwhile, Avery knows his stuff when it comes to video & CPU optimization techniques, so you better pay attention.

Some video related ebooks (PDF) can be downloaded freely from Snell & Wilcox. edit - http://www.snellgroup.com/support/documentation/engineering-guides this???


License terms

Note: Avisynth Filter SDK parts are under specific SDK license terms.

Personal tools