VapourSynth 1.0 documentation
previous | next | index

# VapourSynth.h

## Table of contents

Introduction

Macros

  VS_CC

  VS_EXTERNAL_API

  VAPOURSYNTH_API_VERSION

Enums

  VSColorFamily

  VSSampleType

  VSPresetFormat

  VSFilterMode

  VSNodeFlags

  VSPropTypes

  VSGetPropErrors

  VSPropAppendMode

  VSActivationReason

  VSMessageType

Structs

  VSFrameRef

  VSNodeRef

  VSCore

  VSPlugin

  VSNode

  VSFuncRef

  VSMap

  VSFrameContext

  VSFormat

  VSCoreInfo

  VSVideoInfo

  VSAPI

  createCore freeCore getCoreInfo cloneFrameRef cloneNodeRef cloneFuncRef freeFrame freeNode freeFunc newVideoFrame copyFrame copyFrameProps registerFunction getPluginById getPluginByNs getPlugins getFunctions | createFilter setError getError setFilterError invoke getFormatPreset registerFormat getFrame getFrameAsync getFrameFilter requestFrameFilter queryCompletedFrame releaseFrameEarly getStride getReadPtr getWritePtr createFunc | callFunc createMap freeMap clearMap getVideoInfo setVideoInfo getFrameFormat getFrameWidth getFrameHeight getFramePropsRO getFramePropsRW propNumKeys propGetKey propNumElements propGetType propGetInt propGetFloat | propGetData propGetDataSize propGetNode propGetFrame propGetFunc propDeleteKey propSetInt propSetFloat propSetData propSetNode propSetFrame propSetFunc setMaxCacheSize getOutputIndex newVideoFrame2 setMessageHandler

Functions
  getVapourSynthAPI
Writing plugins

  VSInitPlugin

  VSFilterInit

  VSFilterGetFrame

  VSFilterFree

## Introduction

This is VapourSynth’s main header file. Plugins and applications that use the library must include it.

VapourSynth’s public API is all C.

## Macros

VapourSynth.h defines some preprocessor macros that make the programmer’s life easier. The relevant ones are described below.

### VS_CC

The `VS_CC` macro expands to the calling convention used by VapourSynth. All functions meant to be called by VapourSynth must use this macro (a filter’s “init”, “getframe”, “free” functions, etc).

Example:

    static void VS_CC fooInit(...) { ... }

### VS_EXTERNAL_API

The `VS_EXTERNAL_API` macro expands to the platform-specific magic required for functions exported by shared libraries. It also takes care of adding `extern "C"` when needed, and `VS_CC`.

This macro must be used for a plugin’s entry point, like so:

    VS_EXTERNAL_API(void) VapourSynthPluginInit(...) { ... }

### VAPOURSYNTH_API_VERSION

Self-explanatory. Expands to an integer.

## Enums

### enum VSColorFamily

> - cmGray
> - cmRGB
> - cmYUV
> - cmYCoCg
> - cmCompat

### enum VSSampleType

> - stInteger
> - stFloat

### enum VSPresetFormat

> The presets suffixed with H and S have floating point sample type. The H and S suffixes stand for half precision and single precision, respectively.

> The compat formats are the only packed formats in VapourSynth. Everything else is planar. They exist for compatibility with Avisynth plugins. They are not to be implemented in native VapourSynth plugins.

> - pfNone
> - pfGray8
> - pfGray16
> - pfGrayH
> - pfGrayS
> - pfYUV420P8
> - pfYUV422P8
> - pfYUV444P8
> - pfYUV410P8
> - pfYUV411P8
> - pfYUV440P8
> - pfYUV420P9
> - pfYUV422P9
> - pfYUV444P9
> - pfYUV420P10
> - pfYUV422P10
> - pfYUV444P10
> - pfYUV420P16
> - pfYUV422P16
> - pfYUV444P16
> - pfYUV444PH
> - pfYUV444PS
> - pfRGB24
> - pfRGB27
> - pfRGB30
> - pfRGB48
> - pfRGBH
> - pfRGBS
> - pfCompatBGR32
> - pfCompatYUY2

### enum VSFilterMode

> Controls how a filter will be multithreaded, if at all.

> - fmParallel

>   Completely parallel execution. Multiple threads will call a filter’s “getframe” function, to fetch several frames in parallel.

> - fmParallelRequests

>   For filters that are serial in nature but can request in advance one or more frames they need. A filter’s “getframe” function will be called from multiple threads at a time with activation reason arInitial, but only one thread will call it with activation reason arAllFramesReady.

> - fmUnordered

>   For filters that modify their internal state every request.

> - fmSerial

>   For source filters and compatibility with other filtering architectures. The filter’s “getframe” function only ever gets called from one thread at a time.

### enum VSNodeFlags

> - nfNoCache

### enum VSPropTypes

> Types of properties that can be stored in a VSMap.

> - ptUnset
> - ptInt
> - ptFloat
> - ptData
> - ptNode
> - ptFrame
> - ptFunction

### enum VSGetPropErrors

> - peUnset
> - peType
> - peIndex

### enum VSPropAppendMode

> Controls the behaviour of propSetInt() and friends.

> - paReplace

>   All existing values associated with the key will be replaced with the new value.

> - paAppend

>   The new value will be appended to the list of existing values associated with the key.

> - paTouch

>   If the key exists in the map, nothing happens. Otherwise, the key is added to the map, with no values associated.

### enum VSActivationReason

> See VSFilterGetFrame.

> - arInitial
> - arFrameReady
> - arAllFramesReady
> - arError

### enum VSMessageType

> See setMessageHandler().

> - mtDebug
> - mtWarning
> - mtCritical
> - mtFatal

## Structs

Most of the structs are implemented in C++, therefore constructing instances of them directly is not possible.

### struct VSFrameRef

> A frame.

> The contents of a frame (pixels) are guaranteed to have an alignment of 32 bytes.

> Two frames with the same width are guaranteed to have the same stride.

> Any data can be attached to a frame, using a VSMap.

### struct VSNodeRef

> TODO

### struct VSCore

> TODO

### struct VSPlugin

> A VapourSynth plugin. There are a few of these built into the core, and therefore available at all times: the basic filters (identifier `com.vapoursynth.std`, namespace `std`), the resizers (identifier `com.vapoursynth.resize`, namespace `resize`), and the Avisynth compatibility module, if running in Windows (identifier `com.vapoursynth.avisynth`, namespace `avs`).

> The Function Reference describes how to load VapourSynth and Avisynth plugins.

> A VSPlugin instance is constructed by the core when loading a plugin (.so / .dylib / .dll), and the pointer is passed to the plugin’s VapourSynthPluginInit() function.

> A VapourSynth plugin can export any number of filters.

> Plugins have a few attributes:

> > - An identifier, which must be unique among all VapourSynth plugins in existence, because this is what the core uses to make sure a plugin only gets loaded once.
> > - A namespace, also unique. The filters exported by a plugin end up in the plugin’s namespace.
> > - A full name, which is used by the core in a few error messages.
> > - The VapourSynth API version the plugin requires.

> Things you can do with a VSPlugin:

> > - Get a list of all the filters it exports, using getFunctions().
> > - Invoke one of its filters, using invoke().

> A list of all loaded plugins (including built-in) can be obtained with getPlugins().

> Once loaded, a plugin only gets unloaded when the VapourSynth core is freed.

### struct VSNode

> TODO

### struct VSFuncRef

> TODO

### struct VSMap

> VSMap is a container that stores (key,value) pairs. The keys are strings and the values can be (arrays of) integers, floating point numbers, arrays of bytes, VSNodeRef, VSFrameRef, or VSFuncRef.

> The pairs in a VSMap are sorted by key.

> In VapourSynth, VSMaps have several uses:
>   - storing filters’ arguments and return values
>   - storing user-defined functions’ arguments and return values
>   - storing the properties attached to frames

> VSMap itself allows any non-zero bytes to be used in keys, but VapourSynth places certain restrictions on the characters allowed in filters’ arguments. See registerFunc in VSInitPlugin.

> Creating and destroying a map are done with createMap() and freeMap(), respectively.

> A map’s contents can be retrieved and modified using a number of functions, all prefixed with “prop”.

> A map’s contents can be erased with clearMap().

### struct VSFrameContext

> TODO

### struct VSFormat

> Describes the format of a clip.

> Don’t create an instance of this struct manually (`struct VSFormat moo;`), but only through registerFormat(). Registered VSFormat instances will be valid as long as the VapourSynth core object lives. They can be retrieved with getFormatPreset().

> `char name[32]`

>   A nice, printable name, like “YUV444P10”, or “runtime registered”, for custom formats.

> int `id`

>   A number that uniquely identifies the VSFormat instance. One of VSPresetFormat, if it’s a built-in format.

> int `colorFamily`

>   See VSColorFamily.

> int `sampleType`

>   See VSSampleType.

> int `bitsPerSample`

>   Number of significant bits.

> int `bytesPerSample`

>   Number of bytes needed for a sample. This is always a power of 2 and the smallest possible that can fit the number of bits used per sample.

> int `subSamplingW`
> int `subSamplingH`

>   log2 subsampling factor, applied to second and third plane. Convenient numbers that can be used like so:

>       uv_width = y_width >> subSamplingW;

> int `numPlanes`

>   Number of planes.

### struct VSCoreInfo

> Contains information about a VSCore instance.

> const char* `versionString`

>   Printable string containing the name of the library, copyright notice, core and API versions.

> int `core`

>   Version of the core.

> int `api`

>   Version of the API.

> int64_t `maxFramebufferSize`

>   The framebuffer cache will be allowed to grow up to this size (bytes).

> int64_t `usedFramebufferSize`

>   Current size of the framebuffer cache, in bytes.

### struct VSVideoInfo

> Contains information about a clip.

> const VSFormat* `format`

>   Format of the clip. It will be NULL if the clip’s format can vary.

> int64_t `fpsNum`

>   Numerator part of the clip’s frame rate.

> int64_t `fpsDen`

>   Denominator part of the clip’s frame rate.

> int `width`

>   Width of the clip. It will be 0 if the clip’s dimensions can vary.

> int `height`

>   Height of the clip. It will be 0 if the clip’s dimensions can vary.

> int `numFrames`

>   Length of the clip. It will be 0 if the clip’s length is unknown.

> int `flags`

>   What is this?

### struct VSAPI

> This giant struct is the way to access VapourSynth’s public API.

> VSCreateCore `createCore`

>   typedef VSCore *(VS_CC *VSCreateCore)(int threads)

>   Creates the Vapoursynth processing core and returns a pointer to it. It is legal to create multiple cores.

>   If plugin autoloading is enabled, plugins found in certain folders are automatically loaded.

>   threads
>     Number of desired worker threads. If 0, a suitable value is automatically chosen, based on the number of logical CPUs.

> VSFreeCore `freeCore`

>   typedef void (VS_CC *VSFreeCore)(VSCore *core)

>   Frees a core.

>   ??? Conditions on the object state, threading ???

> VSGetCoreInfo `getCoreInfo`

>   typedef const VSCoreInfo *(VS_CC *VSGetCoreInfo)(VSCore *core)

>   Returns information about the VapourSynth core.

> VSCloneFrameRef `cloneFrameRef`

>   typedef const VSFrameRef *(VS_CC *VSCloneFrameRef)(const VSFrameRef *f)

>   Duplicates a frame reference. This new reference has to be deleted with freeFrame() when it is no longer needed.

> VSCloneNodeRef `cloneNodeRef`

>   typedef VSNodeRef *(VS_CC *VSCloneNodeRef)(VSNodeRef *node)

>   Duplicates a node reference. This new reference has to be deleted with freeNode() when it is no longer needed.

> VSCloneFuncRef `cloneFuncRef`

>   typedef VSFuncRef *(VS_CC *VSCloneFuncRef)(VSFuncRef *f)

>   TODO

> VSFreeFrame `freeFrame`

>   typedef void (VS_CC *VSFreeFrame)(const VSFrameRef *f)

>   Deletes a frame reference, releasing the caller’s ownership of the frame.

>   Don’t try to use the frame once the reference has been deleted.

> VSFreeNode `freeNode`

>   typedef void (VS_CC *VSFreeNode)(VSNodeRef *node)

>   Deletes a node reference, releasing the caller’s ownership of the node.

>   Don’t try to use the node once the reference has been deleted.

> VSFreeFunc `freeFunc`

>   typedef void (VS_CC *VSFreeFunc)(VSFuncRef *f)

>   TODO

> VSNewVideoFrame `newVideoFrame`

>   typedef VSFrameRef *(VS_CC *VSNewVideoFrame)(const VSFormat *format, int width, int height, const VSFrameRef *propSrc, VSCore *core)

>   Creates a new frame, optionally copying the properties attached to another frame.

>   The new frame contains uninitialised memory.

>   format
>     The desired colorspace format. Must not be NULL.

>   width

>   height
>     The desired dimensions of the frame, in pixels. Must be greater than 0.
>   propSrc
>     A frame from which properties will be copied. Can be NULL.

>   Returns a pointer to the created frame. Ownership of the new frame is transferred to the caller.

>   See also newVideoFrame2().

> VSCopyFrame `copyFrame`

>   typedef VSFrameRef *(VS_CC *VSCopyFrame)(const VSFrameRef *f, VSCore *core)

>   Duplicates the frame (not just the reference). As the frame buffer is shared in a copy-on-write fashion, the frame content is not really duplicated until a write operation occurs. This is transparent for the user.

>   Returns a pointer to the new frame. Ownership is transferred to the caller.

> VSCopyFrameProps `copyFrameProps`

>   typedef void (VS_CC *VSCopyFrameProps)(const VSFrameRef *src, VSFrameRef *dst, VSCore *core)

>   Copies the property map of a frame to another frame, owerwriting all existing properties.

> VSRegisterFunction `registerFunction`

>   typedef void (VS_CC *VSRegisterFunction)(const char *name, const char *args, VSPublicFunction argsFunc, void *functionData, VSPlugin *plugin)

>   See VSInitPlugin.

> VSGetPluginById `getPluginById`

>   typedef VSPlugin *(VS_CC *VSGetPluginById)(const char *identifier, VSCore *core)

>   Returns a pointer to the plugin with the given identifier, or NULL if not found.

>   identifier
>     Reverse URL that uniquely identifies the plugin.

> VSGetPluginByNs `getPluginByNs`

>   typedef VSPlugin *(VS_CC *VSGetPluginByNs)(const char *ns, VSCore *core)

>   Returns a pointer to the plugin with the given namespace, or NULL if not found.

>   ns
>     Namespace.

> VSGetPlugins `getPlugins`

>   typedef VSMap *(VS_CC *VSGetPlugins)(VSCore *core)

>   Returns a map containing a list of all loaded plugins.

>   Keys:
>     The plugins’ unique identifiers.
>   Values:
>     Namespace, identifier, and full name, separated by semicolons.

> VSGetFunctions `getFunctions`

>   typedef VSMap *(VS_CC *VSGetFunctions)(VSPlugin *plugin)

>   Returns a map containing a list of the filters exported by a plugin.

>   Keys:
>     The filter names.
>   Values:
>     The filter name followed by its argument string, separated by a semicolon.

> VSCreateFilter `createFilter`

>   typedef void (VS_CC *VSCreateFilter)(const VSMap *in, VSMap *out, const char *name, VSFilterInit init, VSFilterGetFrame getFrame, VSFilterFree free, int filterMode, int flags, void *instanceData, VSCore *core)

>   Creates a new filter node.

>   in
>     List of the filter’s arguments.
>   out
>     List of the filter’s return values (clip(s) or an error).
>   name
>     Instance name. Please make it the same as the filter’s name.
>   init
>     The filter’s “init” function. Must not be NULL.
>   getFrame
>     The filter’s “getframe” function. Must not be NULL.
>   free
>     The filter’s “free” function. Can be NULL.
>   filterMode
>     One of VSFilterMode. Indicates the level of parallelism supported by the filter.
>   flags
>     Set to nfNoCache (VSNodeFlags) if the frames generated by the filter should not be cached. It is useful for filters that only shuffle frames around without modifying them (e.g. std.Interleave). For most filters this should be 0.
>   instanceData
>     A pointer to the private filter data, usually allocated in the filter’s argsFunc function.

>   After this function returns, out will contain the new node(s) in the “clip” property, or an error, if something went wrong.

>   Warning

>   Never use inside a filter’s “getframe” function.

> VSSetError `setError`

>   typedef void (VS_CC *VSSetError)(VSMap *map, const char *errorMessage)

>   Adds an error message to a map. The map is cleared first.

>   Never call from a filter’s “getframe” function. See setFilterError.

>   errorMessage
>     Pass NULL to get a useless default error message.

> VSGetError `getError`

>   typedef const char *(VS_CC *VSGetError)(const VSMap *map)

>   Returns a pointer to the error message contained in the map, or NULL if there is no error message. The pointer is valid as long as the map lives.

> VSSetFilterError `setFilterError`

>   typedef void (VS_CC *VSSetFilterError)(const char *errorMessage, VSFrameContext *frameCtx)

>   Adds an error message to a frame context, replacing the existing message, if any.

>   This is the way to report errors in a filter’s “getframe” function. Such errors are not fatal, i.e. the caller can try to request the same frame again.

> VSInvoke `invoke`

>   typedef VSMap *(VS_CC *VSInvoke)(VSPlugin *plugin, const char *name, const VSMap *args)

>   Invokes a filter.

>   invoke() makes sure the filter has no compat input nodes, checks that the args passed to the filter are consistent with the argument list registered by the plugin, calls the filter’s “create” function, and checks that the filter doesn’t return any compat nodes. If everything goes smoothly, the filter will be ready to generate frames after invoke() returns.

>   ??? Concurrent call with other functions ???

>   plugin

>     A pointer to the plugin where the filter is located. Must not be NULL.

>     See getPluginById() and getPluginByNs().

>   name
>     Name of the filter to invoke.
>   args
>     Arguments for the filter.

>   Returns a map containing the filter’s return value(s). The caller gets ownership of the map. Use getError() to check if the filter was invoked successfully.

>   Most filters will either add an error to the map, or one or more clips with the key “clip”. One exception is the special LoadPlugin “filter”, which doesn’t return any clips for obvious reasons.

>   Warning

>   Never use inside a filter’s “getframe” function.

> VSGetFormatPreset `getFormatPreset`

>   typedef const VSFormat *(VS_CC *VSGetFormatPreset)(int id, VSCore *core)

>   Returns a VSFormat structure from a video format identifier.

>   Concurrent access allowed with other video format functions.

>   id
>     The format identifier: one of VSPresetFormat or a custom registered format.

>   Returns NULL if the identifier is not known.

> VSRegisterFormat `registerFormat`

>   typedef const VSFormat *(VS_CC *VSRegisterFormat)(int colorFamily, int sampleType, int bitsPerSample, int subSamplingW, int subSamplingH, VSCore *core)

>   Registers a custom video format.

>   Concurrent access allowed with other video format functions.

>   colorFamily

>     One of VSColorFamily.

>     Note

>     Registering compat formats is not allowed.

>   sampleType
>     One of VSSampleType.
>   bitsPerSample

>     Number of meaningful bits for a single component. The valid range is 8-32.

>     For floating point formats, only 16 or 32 bits are allowed.

>   subSamplingW
>     log2 of the horizontal chroma subsampling. 0 == no subsampling.
>   subSamplingH

>     log2 of the vertical chroma subsampling. The valid range is 0-4.

>     Note

>     RGB formats are not allowed to be subsampled in VapourSynth.

>   Returns a pointer to the created VSFormat object. Its id member contains the attributed format identifier. The pointer is valid as long as the VSCore instance lives.

>   If the parameters specify a format that is already registered (including preset formats), then no new format is created and the existing one is returned.

> VSGetFrame `getFrame`

>   typedef const VSFrameRef *(VS_CC *VSGetFrame)(int n, VSNodeRef *node, char *errorMsg, int bufSize)

>   Generates a frame directly. The frame is available when the function returns.

>   This function is meant for external applications using the core as a library, or if frame requests are necessary during a filter’s initialization.

>   n
>     The frame number. Negative values will cause an error.
>   node
>     The node from which the frame is requested.
>   bufSize
>     Maximum length for the error message, in bytes (including the trailing ‘0’). Can be 0 if no error message is wanted.
>   errorMsg
>     Pointer to a buffer of bufSize bytes to store a possible error message. Can be NULL if no error message is wanted.

>   Returns a reference to the generated frame, or NULL in case of failure. The ownership of the frame is transferred to the caller.

>   Warning

>   Never use inside a filter’s “getframe” function.

> VSGetFrameAsync `getFrameAsync`

>   typedef void (VS_CC *VSGetFrameAsync)(int n, VSNodeRef *node, VSFrameDoneCallback callback, void *userData)

>   Requests the generation of a frame. When the frame is ready, a user-provided function is called.

>   This function is meant for applications using VapourSynth as a library.

>   ??? Could be called concurrently ???

>   n
>     Frame number. Negative values will cause an error.
>   node
>     The node from which the frame is requested.
>   callback

>     typedef void (VS_CC *VSFrameDoneCallback)(void *userData, const VSFrameRef *f, int n, VSNodeRef *node, const char *errorMsg)

>     Function of the client application called by the core when a requested frame is ready, after a call to getFrameAsync().

>     If multiple frames were requested, they can be returned in any order. Client applications must take care of reordering them.

>     This function is only ever called from one thread at a time.

>     getFrameAsync() may be called from this function to request more frames.

>     userData
>       Pointer to private data from the client application, as passed previously to getFrameAsync().
>     f

>       The finished frame.

>       The ownership of the frame is kept by the core, hence a new reference must be created if the frame has to be stored for later use (after the function returns).

>       It will be NULL in case of error.

>     n
>       The frame number.
>     node
>       Node the frame belongs to.
>     errorMsg
>       String that usually contains an error message if the frame generation failed. NULL if there is no error.
>   userData
>     Pointer passed to the callback.

>   Warning

>   Never use inside a filter’s “getframe” function.

> VSGetFrameFilter `getFrameFilter`

>   typedef const VSFrameRef *(VS_CC *VSGetFrameFilter)(int n, VSNodeRef *node, VSFrameContext *frameCtx)

>   Retrieves a frame that was previously requested with requestFrameFilter().

>   Only use inside a filter’s “getframe” function.

>   A filter usually calls this function when its activation reason is arAllFramesReady or arFrameReady.

>   n
>     The frame number.
>   node
>     The node from which the frame is retrieved.
>   frameCtx
>     The context passed to the filter’s “getframe” function.

>   Returns a pointer to the requested frame, or NULL if the requested frame is not available for any reason. The ownership of the frame is transferred to the caller.

> VSRequestFrameFilter `requestFrameFilter`

>   typedef void (VS_CC *VSRequestFrameFilter)(int n, VSNodeRef *node, VSFrameContext *frameCtx)

>   Requests a frame from a node and returns immediately.

>   Only use inside a filter’s “getframe” function.

>   A filter usually calls this function when its activation reason is arInitial. The requested frame can then be retrieved using getFrameFilter(), when the filter’s activation reason is arAllFramesReady or arFrameReady.

>   n
>     The frame number. Negative values will cause an error.
>   node
>     The node from which the frame is requested.
>   frameCtx
>     The context passed to the filter’s “getframe” function.

> VSQueryCompletedFrame `queryCompletedFrame`

>   typedef void (VS_CC *VSQueryCompletedFrame)(VSNodeRef **node, int *n, VSFrameContext *frameCtx)

>   Finds out which requested frame is ready. To be used in a filter’s “getframe” function, when it is called with activationReason arFrameReady.

>   The node and the frame number will be available in node and n.

> VSReleaseFrameEarly `releaseFrameEarly`

>   typedef void (VS_CC *VSReleaseFrameEarly)(VSNodeRef *node, int n, VSFrameContext *frameCtx)

>   TODO

>   Only use inside a filter’s “getframe” function.

> VSGetStride `getStride`

>   typedef int (VS_CC *VSGetStride)(const VSFrameRef *f, int plane)

>   Returns the distance in bytes between two consecutive lines of a plane of a frame.

>   Passing an invalid plane number will cause a fatal error.

> VSGetReadPtr `getReadPtr`

>   typedef const uint8_t *(VS_CC *VSGetReadPtr)(const VSFrameRef *f, int plane)

>   Returns a read-only pointer to a plane of a frame.

>   Passing an invalid plane number will cause a fatal error.

>   Note

>   Don’t assume all three planes of a frame are allocated in one contiguous chunk (they’re not).

> VSGetWritePtr `getWritePtr`

>   typedef uint8_t *(VS_CC *VSGetWritePtr)(VSFrameRef *f, int plane)

>   Returns a read/write pointer to a plane of a frame.

>   Passing an invalid plane number will cause a fatal error.

> VSCreateFunc `createFunc`

>   typedef VSFuncRef *(VS_CC *VSCreateFunc)(VSPublicFunction func, void *userData, VSFreeFuncData free)

>   func

>     typedef void (VS_CC *VSPublicFunction)(const VSMap *in, VSMap *out, void *userData, VSCore *core, const VSAPI *vsapi)

>     User-defined function that does stuff. ???

>   userData
>     Pointer passed to func
>   free

>     typedef void (VS_CC *VSFreeFuncData)(void *userData)

>     Callback tasked with freeing userData.

> VSCallFunc `callFunc`

>   typedef void (VS_CC *VSCallFunc)(VSFuncRef *func, const VSMap *in, VSMap *out, VSCore *core, const VSAPI *vsapi)

>   TODO

> VSCreateMap `createMap`

>   typedef VSMap *(VS_CC *VSCreateMap)(void)

>   Creates a new property map. It must be deallocated later with freeMap().

> VSFreeMap `freeMap`

>   typedef void (VS_CC *VSFreeMap)(VSMap *map)

>   Frees a map and all the objects it contains.

> VSClearMap `clearMap`

>   typedef void (VS_CC *VSClearMap)(VSMap *map)

>   Deletes all the keys and their associated values from the map, leaving it empty.

> VSGetVideoInfo `getVideoInfo`

>   typedef const VSVideoInfo *(VS_CC *VSGetVideoInfo)(VSNodeRef *node)

>   Returns a pointer to the video info associated with a node. The pointer is valid as long as the node lives.

> VSSetVideoInfo `setVideoInfo`

>   typedef void (VS_CC *VSSetVideoInfo)(const VSVideoInfo *vi, int numOutputs, VSNode *node)

>   Sets the node’s video info.

>   vi
>     Pointer to numOutputs VSVideoInfo instances. The structures are copied by the core.
>   numOutputs
>     Number of clips the filter wants to return. Must be greater than 0.
>   node
>     Pointer to the node whose video info is to be set.

> VSGetFrameFormat `getFrameFormat`

>   typedef const VSFormat *(VS_CC *VSGetFrameFormat)(const VSFrameRef *f)

>   Retrieves the format of a frame.

> VSGetFrameWidth `getFrameWidth`

>   typedef int (VS_CC *VSGetFrameWidth)(const VSFrameRef *f, int plane)

>   Returns the width of a plane of a given frame, in pixels. The width depends on the plane number because of the possible chroma subsampling.

> VSGetFrameHeight `getFrameHeight`

>   typedef int (VS_CC *VSGetFrameHeight)(const VSFrameRef *f, int plane)

>   Returns the height of a plane of a given frame, in pixels. The height depends on the plane number because of the possible chroma subsampling.

> VSGetFramePropsRO `getFramePropsRO`

>   typedef const VSMap *(VS_CC *VSGetFramePropsRO)(const VSFrameRef *f)

>   Returns a read-only pointer to a frame’s properties. The pointer is valid as long as the frame lives.

> VSGetFramePropsRW `getFramePropsRW`

>   typedef VSMap *(VS_CC *VSGetFramePropsRW)(VSFrameRef *f)

>   Returns a read/write pointer to a frame’s properties. The pointer is valid as long as the frame lives.

> VSPropNumKeys `propNumKeys`

>   typedef int (VS_CC *VSPropNumKeys)(const VSMap *map)

>   Returns the number of keys contained in a property map.

> VSPropGetKey `propGetKey`

>   typedef const char *(VS_CC *VSPropGetKey)(const VSMap *map, int index)

>   Returns a key from a property map.

>   Passing an invalid index will cause a fatal error.

>   The pointer is valid as long as the key exists in the map.

> VSPropNumElements `propNumElements`

>   typedef int (VS_CC *VSPropNumElements)(const VSMap *map, const char *key)

>   Returns the number of elements associated with a key in a property map. Returns -1 if there is no such key in the map.

> VSPropGetType `propGetType`

>   typedef char (VS_CC *VSPropGetType)(const VSMap *map, const char *key)

>   Returns the type of the elements associated with the given key in a property map.

>   The returned value is one of VSPropTypes. If there is no such key in the map, the returned value is ptUnset.

> VSPropGetInt `propGetInt`

>   typedef int64_t (VS_CC *VSPropGetInt)(const VSMap *map, const char *key, int index, int *error)

>   Retrieves an integer from a map.

>   Returns the number on success, or 0 in case of error.

>   If the map has an error set (i.e. if getError() returns non-NULL) VapourSynth will die with a fatal error.

>   index

>     Zero-based index of the element.

>     Use propNumElements() to know the total number of elements associated with a key.

>   error

>     A bitwise OR of VSGetPropErrors, or 0 on success.

>     You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

> VSPropGetFloat `propGetFloat`

>   typedef double (VS_CC *VSPropGetFloat)(const VSMap *map, const char *key, int index, int *error)

>   Retrieves a floating point number from a map.

>   Returns the number on success, or 0 in case of error.

>   If the map has an error set (i.e. if getError() returns non-NULL) VapourSynth will die with a fatal error.

>   index

>     Zero-based index of the element.

>     Use propNumElements() to know the total number of elements associated with a key.

>   error

>     A bitwise OR of VSGetPropErrors, or 0 on success.

>     You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

> VSPropGetData `propGetData`

>   typedef const char *(VS_CC *VSPropGetData)(const VSMap *map, const char *key, int index, int *error)

>   Retrieves arbitrary binary data from a map.

>   Returns a pointer to the data on success, or NULL in case of error.

>   The pointer is valid until the map is destroyed, or until the corresponding key is removed from the map or altered.

>   If the map has an error set (i.e. if getError() returns non-NULL) VapourSynth will die with a fatal error.

>   index

>     Zero-based index of the element.

>     Use propNumElements() to know the total number of elements associated with a key.

>   error

>     A bitwise OR of VSGetPropErrors, or 0 on success.

>     You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

> VSPropGetDataSize `propGetDataSize`

>   typedef int (VS_CC *VSPropGetDataSize)(const VSMap *map, const char *key, int index, int *error)

>   Returns the size in bytes of a property of type ptData. See VSPropTypes.

> VSPropGetNode `propGetNode`

>   typedef VSNodeRef *(VS_CC *VSPropGetNode)(const VSMap *map, const char *key, int index, int *error)

>   Retrieves a node from a map.

>   Returns a pointer to the node on success, or NULL in case of error.

>   This function increases the node’s reference count, so freeNode() must be used when the node is no longer needed.

>   If the map has an error set (i.e. if getError() returns non-NULL) VapourSynth will die with a fatal error.

>   index

>     Zero-based index of the element.

>     Use propNumElements() to know the total number of elements associated with a key.

>   error

>     A bitwise OR of VSGetPropErrors, or 0 on success.

>     You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

> VSPropGetFrame `propGetFrame`

>   typedef const VSFrameRef *(VS_CC *VSPropGetFrame)(const VSMap *map, const char *key, int index, int *error)

>   Retrieves a frame from a map.

>   Returns a pointer to the frame on success, or NULL in case of error.

>   This function increases the frame’s reference count, so freeFrame() must be used when the frame is no longer needed.

>   If the map has an error set (i.e. if getError() returns non-NULL) VapourSynth will die with a fatal error.

>   index

>     Zero-based index of the element.

>     Use propNumElements() to know the total number of elements associated with a key.

>   error

>     A bitwise OR of VSGetPropErrors, or 0 on success.

>     You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

> VSPropGetFunc `propGetFunc`

>   typedef VSFuncRef *(VS_CC *VSPropGetFunc)(const VSMap *map, const char *key, int index, int *error)

>   Retrieves a function from a map.

>   Returns a pointer to the function on success, or NULL in case of error.

>   This function increases the function’s reference count, so freeFunc() must be used when the function is no longer needed.

>   If the map has an error set (i.e. if getError() returns non-NULL) VapourSynth will die with a fatal error.

>   index

>     Zero-based index of the element.

>     Use propNumElements() to know the total number of elements associated with a key.

>   error

>     A bitwise OR of VSGetPropErrors, or 0 on success.

>     You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

> VSPropDeleteKey `propDeleteKey`

>   typedef int (VS_CC *VSPropDeleteKey)(VSMap *map, const char *key)

>   Removes the property with the given key. All values associated with the key are lost.

>   Returns 0 if the key isn’t in the map. Otherwise it returns 1.

> VSPropSetInt `propSetInt`

>   typedef int (VS_CC *VSPropSetInt)(VSMap *map, const char *key, int64_t i, int append)

>   Adds a property to a map.

>   Multiple values can be associated with one key, but they must all be the same type.

>   key
>     Name of the property. Any characters may be used.
>   i
>     Value to store.
>   append
>     One of VSPropAppendMode.

>   Returns 0 on success, or 1 if trying to append to a property with the wrong type.

> VSPropSetFloat `propSetFloat`

>   typedef int (VS_CC *VSPropSetFloat)(VSMap *map, const char *key, double d, int append)

>   Adds a property to a map.

>   Multiple values can be associated with one key, but they must all be the same type.

>   key
>     Name of the property. Any characters may be used.
>   d
>     Value to store.
>   append
>     One of VSPropAppendMode.

>   Returns 0 on success, or 1 if trying to append to a property with the wrong type.

> VSPropSetData `propSetData`

>   typedef int (VS_CC *VSPropSetData)(VSMap *map, const char *key, const char *data, int size, int append)

>   Adds a property to a map.

>   Multiple values can be associated with one key, but they must all be the same type.

>   key
>     Name of the property. Any characters may be used.
>   data

>     Value to store.

>     This function copies the data, so the pointer should be freed when no longer needed.

>   size
>     The number of bytes to copy.
>   append
>     One of VSPropAppendMode.

>   Returns 0 on success, or 1 if trying to append to a property with the wrong type.

> VSPropSetNode `propSetNode`

>   typedef int (VS_CC *VSPropSetNode)(VSMap *map, const char *key, VSNodeRef *node, int append)

>   Adds a property to a map.

>   Multiple values can be associated with one key, but they must all be the same type.

>   key
>     Name of the property. Any characters may be used.
>   node

>     Value to store.

>     This function will increase the node’s reference count, so the pointer should be freed when no longer needed.

>   append
>     One of VSPropAppendMode.

>   Returns 0 on success, or 1 if trying to append to a property with the wrong type.

> VSPropSetFrame `propSetFrame`

>   typedef int (VS_CC *VSPropSetFrame)(VSMap *map, const char *key, const VSFrameRef *f, int append)

>   Adds a property to a map.

>   Multiple values can be associated with one key, but they must all be the same type.

>   key
>     Name of the property. Any characters may be used.
>   f

>     Value to store.

>     This function will increase the frame’s reference count, so the pointer should be freed when no longer needed.

>   append
>     One of VSPropAppendMode.

>   Returns 0 on success, or 1 if trying to append to a property with the wrong type.

> VSPropSetFunc `propSetFunc`

>   typedef int (VS_CC *VSPropSetFunc)(VSMap *map, const char *key, VSFuncRef *func, int append)

>   Adds a property to a map.

>   Multiple values can be associated with one key, but they must all be the same type.

>   key
>     Name of the property. Any characters may be used.
>   func

>     Value to store.

>     This function will increase the function’s reference count, so the pointer should be freed when no longer needed.

>   append
>     One of VSPropAppendMode.

>   Returns 0 on success, or 1 if trying to append to a property with the wrong type.

> VSSetMaxCacheSize `setMaxCacheSize`

>   typedef int64_t (VS_CC *VSSetMaxCacheSize)(int64_t bytes, VSCore *core)

>   Sets the maximum size of the framebuffer cache. Returns the new maximum size.

> VSGetOutputIndex `getOutputIndex`

>   typedef int (VS_CC *VSGetOutputIndex)(VSFrameContext *frameCtx)

>   Returns the index of the node from which the frame is being requested.

>   Only needed in the “getframe” function of filters that return more than one clip.

> VSNewVideoFrame2 `newVideoFrame2`

>   typedef VSFrameRef *(VS_CC *VSNewVideoFrame2)(const VSFormat *format, int width, int height, const VSFrameRef **planeSrc, const int *planes, const VSFrameRef *propSrc, VSCore *core)

>   Creates a new frame from the planes of existing frames, optionally copying the properties attached to another frame.

>   format
>     The desired colorspace format. Must not be NULL.

>   width

>   height
>     The desired dimensions of the frame, in pixels. Must be greater than 0.
>   planeSrc
>     Array of frames from which planes will be copied. If any elements of the array are NULL, the corresponding planes in the new frame will contain uninitialised memory.
>   planes
>     Array of plane numbers indicating which plane to copy from the corresponding source frame.
>   propSrc
>     A frame from which properties will be copied. Can be NULL.

>   Returns a pointer to the created frame. Ownership of the new frame is transferred to the caller.

>   Example:

>       // Assume frameA, frameB, frameC are existing frames.
>       const VSFrameRef * frames[3] = { frameA, frameB, frameC };
>       const int planes[3] = { 1, 0, 2 };

>       VSFrameRef * newFrame = vsapi->newVideoFrame2(f, w, h, frames, planes, NULL, core);
>       // newFrame's first plane is now a copy of frameA's second plane,
>       // the second plane is a copy of frameB's first plane,
>       // the third plane is a copy of frameC's third plane.

> VSSetMessageHandler `setMessageHandler`

>   typedef void (VS_CC *VSSetMessageHandler)(VSMessageHandler handler, void *userData)

>   Installs a custom handler for the various error messages VapourSynth emits. The message handler is currently global, i.e. per process, not per VSCore instance.

>   This function wraps qInstallMsgHandler.

>   handler

>     typedef void (VS_CC *VSMessageHandler)(int msgType, const char *msg, void *userdata)

>     Custom message handler.

>     msgType

>       The type of message. One of VSMessageType.

>       If msgType is mtFatal, VapourSynth will call abort() after the message handler returns.

>     msg
>       The message.
>   userData
>     Pointer that gets passed to the message handler.

## Functions

const VSAPI* getVapourSynthAPI(int version)

> Returns a pointer to the global VSAPI instance.

> Returns NULL if the requested API version is not supported or if the system does not meet the minimum requirements to run VapourSynth.

## Writing plugins

A simple VapourSynth plugin which exports one filter will contain five functions: an entry point (called `VapourSynthPluginInit`), a function tasked with creating a filter instance (often called `fooCreate`), an “init” function (often called `fooInit`), a “getframe” function (often called `fooGetframe`), and a “free” function (often called `fooFree`). These functions are described below.

Another thing a filter requires is an object for storing a filter instance’s private data. This object will usually contain the filter’s input nodes (if it has any) and a VSVideoInfo struct describing the video the filter wants to return.

The sdk folder in the VapourSynth source contains some examples.

typedef void (VS_CC *VSInitPlugin)(VSConfigPlugin configFunc, VSRegisterFunction registerFunc, VSPlugin *plugin)

> A plugin’s entry point. It must be called `VapourSynthPluginInit`. This function is called after the core loads the shared library. Its purpose is to configure the plugin and to register the filters the plugin wants to export.

> configFunc

>   typedef void (VS_CC *VSConfigPlugin)(const char *identifier, const char *defaultNamespace, const char *name, int apiVersion, int readonly, VSPlugin *plugin)

>   Configures the plugin. Call once, before calling registerFunc.

>   identifier

>     Reverse URL that must uniquely identify the plugin.

>     If you don’t own a domain then make one up that’s related to the plugin name.

>     Example: “com.vapoursynth.std”

>   defaultNamespace

>     Namespace where the plugin’s filters will go. This, too, must be unique.

>     Only lowercase letters and the underscore should be used, and it shouldn’t be too long.

>     Example: “resize”

>   name
>     Plugin name in readable form.
>   apiVersion

>     The VapourSynth API version the plugin uses.

>     Use the VAPOURSYNTH_API_VERSION macro.

>   readonly
>     If set to 0, the plugin can export new filters after initialisation. The built-in Avisynth compat plugin uses this feature to add filters at runtime, as they are loaded. Most plugins should set this to 1.
>   plugin
>     Pointer to the plugin object in the core, as passed to VapourSynthPluginInit().
> registerFunc

>   typedef void (VS_CC *VSRegisterFunction)(const char *name, const char *args, VSPublicFunction argsFunc, void *functionData, VSPlugin *plugin)

>   Function that registers a filter exported by the plugin. A plugin can export any number of filters.

>   name

>     Filter name. The characters allowed are letters, numbers, and the underscore. The first character must be a letter. In other words: `^[a-zA-Z][a-zA-Z0-9_]*$`

>     Filter names should be PascalCase.

>   args

>     String containing the filter’s list of arguments.

>     Arguments are separated by a semicolon. Each argument is made of several fields separated by a colon. Don’t insert additional whitespace characters, or VapourSynth will die.

>     Fields:
>       The argument name.
>         The same characters are allowed as for the filter’s name. Argument names should be all lowercase and use only letters and the underscore.
>       The type.

>         “int”: int64_t

>         “float”: double

>         “data”: const char*

>         “clip”: const VSNodeRef*

>         “frame”: const VSFrameRef*

>         “func”: const VSFuncRef*

>         It is possible to declare an array by appending “[]” to the type.

>       “opt”
>         If the parameter is optional.
>       “empty”
>         For arrays that are allowed to be empty.

>     The following example declares the arguments “blah”, “moo”, and “asdf”:

>         blah:clip;moo:int[]:opt;asdf:float:opt;

>   argsFunc

>     typedef void (VS_CC *VSPublicFunction)(const VSMap *in, VSMap *out, void *userData, VSCore *core, const VSAPI *vsapi)

>     User-defined function called by the core to create an instance of the filter. This function is often named `fooCreate`.

>     In this function, the filter’s input parameters should be retrieved and validated, the filter’s private instance data should be initialised, and createFilter() should be called.

>     If for some reason you cannot create the filter, you have to free any created node references using freeNode(), call setError() on out, and return.

>     in

>       Input parameter list.

>       Use propGetInt() and friends to retrieve a parameter value.

>       The map is guaranteed to exist only until the filter’s “init” function returns. In other words, pointers returned by propGetData() will not be usable in the filter’s “getframe” and “free” functions.

>     out
>       Output parameter list. createFilter() will add the output node(s) with the key named “clip”, or an error, if something went wrong.
>     userData
>       Pointer that was passed to registerFunction().
>   functionData
>     Pointer to user data that gets passed to argsFunc when creating a filter. Useful to register multiple filters using a single argsFunc function.
>   plugin
>     Pointer to the plugin object in the core, as passed to VapourSynthPluginInit().
> plugin
>   The plugin object in the core. Pass to configFunc and registerFunc.

typedef void (VS_CC *VSFilterInit)(VSMap *in, VSMap *out, void **instanceData, VSNode *node, VSCore *core, const VSAPI *vsapi)

> A filter’s “init” function.

> This function is called by createFilter() (indirectly).

> This is where the filter should perform whatever initialisation it requires. This is the only place where the video properties may be set (see setVideoInfo()).

> If an error occurs during initialisation:
>   - free the input nodes, if any
>   - free the instance data
>   - free whatever else got allocated so far (obviously)
>   - call setError() on the out map
>   - return
> instanceData
>   Pointer to a pointer to the filter’s private instance data.

typedef const VSFrameRef *(VS_CC *VSFilterGetFrame)(int n, int activationReason, void **instanceData, void **frameData, VSFrameContext *frameCtx, VSCore *core, const VSAPI *vsapi)

> A filter’s “getframe” function. It is called by the core when it needs the filter to generate a frame.

> It is possible to allocate local data, persistent during the multiple calls requesting the output frame.

> In case of error, call setFilterError(), free *frameData if required, and return NULL.

> Depending on the VSFilterMode set for the filter, multiple output frames could be requested concurrently.

> ??? Could there be concurrent calls for the same output frame with arFrameReady and arAllFramesReady ???

> n
>   Requested frame number.
> activationReason

>   One of VSActivationReason.

>   This function is first called with activationReason arInitial. At this point the function should request the input frames and return. When one or all of the requested frames are ready, this function is called again with activationReason arFrameReady or arAllFramesReady. The function should only return a frame when called with activationReason arAllFramesReady.

>   In the case of arFrameReady, use queryCompletedFrame() to find out which of the requested frames is ready.

>   Most filters will only need to handle arInitial and arAllFramesReady.

> instanceData
>   The filter’s private instance data.
> frameData
>   Optional private data associated with output frame number n. It must be deallocated before the last call for the given frame (arAllFramesReady or error).

> Return a reference to the output frame number n when it is ready, or NULL. The ownership of the frame is transferred to the caller.

typedef void (VS_CC *VSFilterFree)(void *instanceData, VSCore *core, const VSAPI *vsapi)

> A filter’s “free” function.

> This is where the filter should free everything it allocated, including its instance data.

> instanceData
>   The filter’s private instance data.