VapourSynth.h ============= Table of contents ################# Introduction_ Macros_ VS_CC_ VS_EXTERNAL_API_ VAPOURSYNTH_API_MAJOR_ VAPOURSYNTH_API_MINOR_ 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_ * Functions that deal with the core: * createCore_ * freeCore_ * getCoreInfo_ * getCoreInfo2_ * setMaxCacheSize_ * setMessageHandler_ * addMessageHandler_ * removeMessageHandler_ * logMessage_ * setThreadCount_ * Functions that deal with frames: * newVideoFrame_ * newVideoFrame2_ * copyFrame_ * cloneFrameRef_ * freeFrame_ * getStride_ * getReadPtr_ * getWritePtr_ * getFrameFormat_ * getFrameWidth_ * getFrameHeight_ * copyFrameProps_ * getFramePropsRO_ * getFramePropsRW_ * Functions that deal with nodes: * cloneNodeRef_ * freeNode_ * getFrame_ * getFrameAsync_ * getFrameFilter_ * requestFrameFilter_ * getVideoInfo_ * setVideoInfo_ * Functions that deal with formats: * getFormatPreset_ * registerFormat_ * Functions that deal with maps: * createMap_ * freeMap_ * clearMap_ * setError_ * getError_ * propNumKeys_ * propGetKey_ * propDeleteKey_ * propGetType_ * propNumElements_ * propGetInt_ * propGetIntArray_ * propGetFloat_ * propGetFloatArray_ * propGetData_ * propGetDataSize_ * propGetNode_ * propGetFrame_ * propGetFunc_ * propSetInt_ * propSetIntArray_ * propSetFloat_ * propSetFloatArray_ * propSetData_ * propSetNode_ * propSetFrame_ * propSetFunc_ * Functions that deal with plugins: * getPluginById_ * getPluginByNs_ * getPlugins_ * getFunctions_ * getPluginPath_ * Functions that deal with functions: * createFunc_ * cloneFuncRef_ * callFunc_ * freeFunc_ * Functions that are mostly used in plugins: * createFilter_ * registerFunction_ * Functions that resist classification: * invoke_ * Functions that are useful only in a filter's getframe function, but otherwise still resist classification: * setFilterError_ * getOutputIndex_ * queryCompletedFrame_ * releaseFrameEarly_ 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: .. code-block:: c 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: .. code-block:: c VS_EXTERNAL_API(void) VapourSynthPluginInit(...) { ... } VAPOURSYNTH_API_MAJOR --------------------- Major API version. This macro was added in VapourSynth R26 (API R3). VAPOURSYNTH_API_MINOR --------------------- Minor API version. It is bumped when new functions are added to VSAPI_. This macro was added in VapourSynth R26 (API R3). VAPOURSYNTH_API_VERSION ----------------------- API version. The high 16 bits are VAPOURSYNTH_API_MAJOR_, the low 16 bits are VAPOURSYNTH_API_MINOR_. Prior to VapourSynth R26, the API version consisted of only the major component. Enums ##### .. _VSColorFamily: enum VSColorFamily ------------------ * cmGray * cmRGB * cmYUV * cmYCoCg * cmCompat .. _VSSampleType: enum VSSampleType ----------------- * stInteger * stFloat .. _VSPresetFormat: 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 * pfYUV420P12 * pfYUV422P12 * pfYUV444P12 * pfYUV420P14 * pfYUV422P14 * pfYUV444P14 * pfYUV420P16 * pfYUV422P16 * pfYUV444P16 * pfYUV444PH * pfYUV444PS * pfRGB24 * pfRGB27 * pfRGB30 * pfRGB48 * pfRGBH * pfRGBS * pfCompatBGR32 * pfCompatYUY2 .. _VSFilterMode: 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 at a time. * fmUnordered Only one thread can call the filter's "getframe" function at a time. Useful for filters that modify or examine their internal state to determine which frames to request. While the "getframe" function will only run in one thread at a time, the calls can happen in any order. For example, it can be called with reason arInitial for frame 0, then again with reason arInitial for frame 1, then with reason arAllFramesReady for frame 0. * fmSerial For compatibility with other filtering architectures. The filter's "getframe" function only ever gets called from one thread at a time. Unlike fmUnordered, only one frame is processed at a time. .. _VSNodeFlags: enum VSNodeFlags ---------------- * nfNoCache This flag indicates that the frames returned by the filter should not be cached. "Fast" filters should set this to reduce cache bloat. * nfIsCache This flag must not be used in third-party filters. It is used to mark instances of the built-in Cache filter. Strange things may happen to your filter if you use this flag. This flag was introduced in VapourSynth R24 without bumping the API version (R3). * nfMakeLinear This flag should be used by filters which prefer linear access, like source filters, where seeking around can cause significant slowdowns. This flag only has any effect if the filter using it is immediately followed by an instance of the built-in Cache filter. This flag was introduced in API R3.3 (VapourSynth R30). .. _VSPropTypes: enum VSPropTypes ---------------- Types of properties that can be stored in a VSMap. * ptUnset * ptInt * ptFloat * ptData * ptNode * ptFrame * ptFunction .. _VSGetPropErrors: enum VSGetPropErrors -------------------- When a propGet* function fails, it returns one of these in the *err* parameter. They are all non-zero. * peUnset The requested key was not found in the map. * peType The wrong function was used to retrieve the property. E.g. propGetInt_\ () was used on a property of type ptFloat. * peIndex The requested index was out of bounds. .. _VSPropAppendMode: 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. .. _VSActivationReason: enum VSActivationReason ----------------------- See VSFilterGetFrame_. * arInitial * arFrameReady * arAllFramesReady * arError .. _VSMessageType: enum VSMessageType ------------------ See setMessageHandler_\ (). * mtDebug * mtWarning * mtCritical * mtFatal Structs ####### Most structs are opaque and their contents can only be accessed using functions in the API. .. _VSFrameRef: struct VSFrameRef ----------------- A frame. Each row of pixels in a frame is 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_. .. _VSNodeRef: struct VSNodeRef ---------------- A reference to a node in the constructed filter graph. Its primary use is as an argument to other filter or to request frames from. .. _VSCore: struct VSCore ------------- The core represents one instance of VapourSynth. Every core individually loads plugins and keeps track of memory. .. _VSPlugin: 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. - A file name. 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_\ (). - Get its location in the file system, using getPluginPath_\ (). 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. .. _VSNode: struct VSNode ------------- Not really interesting. .. _VSFuncRef: struct VSFuncRef ---------------- Holds a reference to a function that may be called. This type primarily exists so functions can be shared between the scripting layer and plugins in the core. .. _VSMap: 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 Only alphanumeric characters and the underscore may be used in keys. Creating and destroying a map can be 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_\ (). .. _VSFrameContext: struct VSFrameContext --------------------- Not really interesting. .. _VSFormat: 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_\ () or registerFormat_\ (). .. c:member:: char name[32] A nice, printable name, like "YUV444P10". .. c:member:: int id A number that uniquely identifies the VSFormat instance. One of VSPresetFormat_, if it's a built-in format. .. c:member:: int colorFamily See VSColorFamily_. .. c:member:: int sampleType See VSSampleType_. .. c:member:: int bitsPerSample Number of significant bits. .. c:member:: 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. .. c:member:: int subSamplingW .. c:member:: int subSamplingH log2 subsampling factor, applied to second and third plane. Convenient numbers that can be used like so: .. code-block:: c uv_width = y_width >> subSamplingW; .. c:member:: int numPlanes Number of planes. .. _VSCoreInfo: struct VSCoreInfo ----------------- Contains information about a VSCore_ instance. .. c:member:: const char* versionString Printable string containing the name of the library, copyright notice, core and API versions. .. c:member:: int core Version of the core. .. c:member:: int api Version of the API. .. c:member:: int numThreads Number of worker threads. .. c:member:: int64_t maxFramebufferSize The framebuffer cache will be allowed to grow up to this size (bytes) before memory is aggressively reclaimed. .. c:member:: int64_t usedFramebufferSize Current size of the framebuffer cache, in bytes. .. _VSVideoInfo: struct VSVideoInfo ------------------ Contains information about a clip. .. c:member:: const VSFormat* format Format of the clip. It will be NULL if the clip's format can vary. .. c:member:: int64_t fpsNum Numerator part of the clip's frame rate. It will be 0 if the frame rate can vary. Should always be a reduced fraction. .. c:member:: int64_t fpsDen Denominator part of the clip's frame rate. It will be 0 if the frame rate can vary. Should always be a reduced fraction. .. c:member:: int width Width of the clip. Both width and height will be 0 if the clip's dimensions can vary. .. c:member:: int height Height of the clip. Both width and height will be 0 if the clip's dimensions can vary. .. c:member:: int numFrames Length of the clip. Since API R3.2 (VapourSynth R27) this is no longer allowed to be 0, i.e. clips with unknown length are not supported. .. c:member:: int flags The flags passed to createFilter_ (either 0, or one or more of VSNodeFlags_). .. _VSAPI: struct VSAPI ------------ This giant struct is the way to access VapourSynth's public API. ---------- .. _createCore: VSCore_ \*createCore(int threads) Creates the VapourSynth processing core and returns a pointer to it. It is legal to create multiple cores but in most cases it shouldn't be needed. *threads* Number of desired worker threads. If 0 or lower, a suitable value is automatically chosen, based on the number of logical CPUs. ---------- .. _freeCore: void freeCore(VSCore_ \*core) Frees a core. Should only be done after all frame requests have completed and all objects belonging to the core have been released. ---------- .. _getCoreInfo: const VSCoreInfo_ \*getCoreInfo(VSCore_ \*core) Deprecated as of API 3.6 (VapourSynth R47) Returns information about the VapourSynth core. VapourSynth retains ownership of the returned pointer. ---------- .. _getCoreInfo2: void getCoreInfo2(VSCore_ \*core, VSCoreInfo_ \*info) Returns information about the VapourSynth core. This function is thread-safe. ---------- .. _setMaxCacheSize: int64_t setMaxCacheSize(int64_t bytes, VSCore_ \*core) Sets the maximum size of the framebuffer cache. Returns the new maximum size. ---------- .. _setMessageHandler: void setMessageHandler(VSMessageHandler handler, void \*userData) Deprecated as of API 3.6 (VapourSynth R47) 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. The default message handler simply sends the messages to the standard error stream. This function is thread-safe. *handler* typedef void (VS_CC \*VSMessageHandler)(int msgType, const char \*msg, void \*userdata) Custom message handler. If this is NULL, the default message handler will be restored. *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. ---------- .. _addMessageHandler: int addMessageHandler(VSMessageHandler handler, VSMessageHandlerFree free, 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. Returns a unique id for the handler. If no error handler is installed the messages are sent to the standard error stream. This function is thread-safe. *handler* typedef void (VS_CC \*VSMessageHandler)(int msgType, const char \*msg, void \*userdata) Custom message handler. If this is NULL, the default message handler will be restored. *msgType* The type of message. One of VSMessageType_. If *msgType* is mtFatal, VapourSynth will call abort() after the message handler returns. *msg* The message. *free* typedef void (VS_CC \*VSMessageHandlerFree)(void \*userData) Called when a handler is removed. *userData* Pointer that gets passed to the message handler. This function was introduced in API R3.6 (VapourSynth R47). ---------- .. _removeMessageHandler: int removeMessageHandler(int id) Removes a custom handler. Return non-zero on success and zero if the handler id is invalid. This function is thread-safe. *id* Message handler id obtained from addMessageHandler_\ (). This function was introduced in API R3.6 (VapourSynth R47). ---------- .. _logMessage: void logMessage(int msgType, const char \*msg) Send a message through VapourSynth's logging framework. See setMessageHandler_. This function is thread-safe. *msgType* The type of message. One of VSMessageType_. If *msgType* is mtFatal, VapourSynth will call abort() after delivering the message. *msg* The message. This function was introduced in API R3.4 (VapourSynth R30). ---------- .. _setThreadCount: int setThreadCount(int threads, VSCore_ \*core) Sets the number of worker threads for the given core. If the requested number of threads is zero or lower, the number of hardware threads will be detected and used. Returns the new thread count. This function was introduced in VapourSynth R24 without bumping the API version (R3). ---------- .. _newVideoFrame: VSFrameRef_ \*newVideoFrame(const VSFormat_ \*format, int width, int height, const VSFrameRef_ \*propSrc, VSCore_ \*core) Creates a new frame, optionally copying the properties attached to another frame. It is a fatal error to pass invalid arguments to this function. 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 and have a suitable multiple for the subsampling in format. *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_\ (). ---------- .. _newVideoFrame2: VSFrameRef_ \*newVideoFrame2(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. It is a fatal error to pass invalid arguments to this function. *format* The desired colorspace format. Must not be NULL. *width* *height* The desired dimensions of the frame, in pixels. Must be greater than 0 and have a suitable multiple for the subsampling in format. *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): .. code-block:: c const VSFrameRef * frames[3] = { frameA, frameB, frameC }; const int planes[3] = { 1, 0, 2 }; VSFrameRef * newFrame = vsapi->newVideoFrame2(f, w, h, frames, planes, frameB, core); The 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 and the properties have been copied from *frameB*. ---------- .. _copyFrame: VSFrameRef_ \*copyFrame(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. ---------- .. _cloneFrameRef: const VSFrameRef_ \*cloneFrameRef(const VSFrameRef_ \*f) Duplicates a frame reference. This new reference has to be deleted with freeFrame_\ () when it is no longer needed. ---------- .. _freeFrame: void freeFrame(const VSFrameRef_ \*f) Deletes a frame reference, releasing the caller's ownership of the frame. It is safe to pass NULL. Don't try to use the frame once the reference has been deleted. ---------- .. _getStride: int getStride(const VSFrameRef_ \*f, int plane) Returns the distance in bytes between two consecutive lines of a plane of a frame. The stride is always positive. Passing an invalid plane number will cause a fatal error. ---------- .. _getReadPtr: const uint8_t \*getReadPtr(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). ---------- .. _getWritePtr: uint8_t \*getWritePtr(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. .. note:: Don't assume all three planes of a frame are allocated in one contiguous chunk (they're not). ---------- .. _getFrameFormat: const VSFormat_ \*getFrameFormat(const VSFrameRef_ \*f) Retrieves the format of a frame. ---------- .. _getFrameWidth: int getFrameWidth(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. ---------- .. _getFrameHeight: int getFrameHeight(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. ---------- .. _copyFrameProps: void copyFrameProps(const VSFrameRef_ \*src, VSFrameRef_ \*dst, VSCore_ \*core) Copies the property map of a frame to another frame, overwriting all existing properties. ---------- .. _getFramePropsRO: const VSMap_ \*getFramePropsRO(const VSFrameRef_ \*f) Returns a read-only pointer to a frame's properties. The pointer is valid as long as the frame lives. ---------- .. _getFramePropsRW: VSMap_ \*getFramePropsRW(VSFrameRef_ \*f) Returns a read/write pointer to a frame's properties. The pointer is valid as long as the frame lives. ---------- .. _cloneNodeRef: VSNodeRef_ \*cloneNodeRef(VSNodeRef_ \*node) Duplicates a node reference. This new reference has to be deleted with freeNode_\ () when it is no longer needed. ---------- .. _freeNode: void freeNode(VSNodeRef_ \*node) Deletes a node reference, releasing the caller's ownership of the node. It is safe to pass NULL. Don't try to use the node once the reference has been deleted. ---------- .. _getFrame: const VSFrameRef_ \*getFrame(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. Thread-safe. *n* The frame number. Negative values will cause an error. *node* The node from which the frame is requested. *errorMsg* Pointer to a buffer of *bufSize* bytes to store a possible error message. Can be NULL if no error message is wanted. *bufSize* Maximum length for the error message, in bytes (including the trailing '\0'). Can be 0 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. ---------- .. _getFrameAsync: void getFrameAsync(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. Thread-safe. *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* Contains a reference to the generated frame, or NULL in case of failure. The ownership of the frame is transferred to the caller. *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. ---------- .. _getFrameFilter: const VSFrameRef_ \*getFrameFilter(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. See VSActivationReason_. It is safe to retrieve a frame more than once, but each reference needs to be freed. *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. ---------- .. _requestFrameFilter: void requestFrameFilter(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. See VSActivationReason_. It is safe to request a frame more than once. An unimportant consequence of requesting a frame more than once is that the getframe function may be called more than once for the same frame with reason arFrameReady. It is best to request frames in ascending order, i.e. n, n+1, n+2, etc. *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. ---------- .. _getVideoInfo: const VSVideoInfo_ \*getVideoInfo(VSNodeRef_ \*node) Returns a pointer to the video info associated with a node. The pointer is valid as long as the node lives. ---------- .. _setVideoInfo: void setVideoInfo(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. The flags are however ignored and replaced by the flags passed to _createFilter. *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. ---------- .. _getFormatPreset: const VSFormat_ \*getFormatPreset(int id, VSCore_ \*core) Returns a VSFormat structure from a video format identifier. Thread-safe. *id* The format identifier: one of VSPresetFormat_ or a custom registered format. Returns NULL if the identifier is not known. ---------- .. _registerFormat: const VSFormat_ \*registerFormat(int colorFamily, int sampleType, int bitsPerSample, int subSamplingW, int subSamplingH, VSCore_ \*core) Registers a custom video format. Thread-safe. *colorFamily* One of VSColorFamily_. .. note:: Registering compat formats is not allowed. Only certain privileged built-in filters are allowed to handle compat formats. *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. Returns NULL in case an invalid format is described. 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. ---------- .. _createMap: VSMap_ \*createMap(void) Creates a new property map. It must be deallocated later with freeMap_\ (). ---------- .. _freeMap: void freeMap(VSMap_ \*map) Frees a map and all the objects it contains. ---------- .. _clearMap: void clearMap(VSMap_ \*map) Deletes all the keys and their associated values from the map, leaving it empty. ---------- .. _setError: void setError(VSMap_ \*map, const char \*errorMessage) Adds an error message to a map. The map is cleared first. The error message is copied. In this state the map may only be freed, cleared or queried for the error message. For errors encountered in a filter's "getframe" function, use setFilterError_. ---------- .. _getError: const char \*getError(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. ---------- .. _propNumKeys: int propNumKeys(const VSMap_ \*map) Returns the number of keys contained in a property map. ---------- .. _propGetKey: const char \*propGetKey(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. ---------- .. _propDeleteKey: int propDeleteKey(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. ---------- .. _propGetType: char propGetType(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. ---------- .. _propNumElements: int propNumElements(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. ---------- .. _propGetInt: int64_t propGetInt(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* One 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. ---------- .. _propGetIntArray: const int64_t \*propGetIntArray(const VSMap_ \*map, const char \*key, int \*error) Retrieves an array of integers from a map. Use this function if there are a lot of numbers associated with a key, because it is faster than calling propGetInt_\ () in a loop. Returns a pointer to the first element of the array on success, or NULL 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. Use propNumElements_\ () to know the total number of elements associated with a key. *error* One 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. This function was introduced in API R3.1 (VapourSynth R26). ---------- .. _propGetFloat: double propGetFloat(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* One 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. ---------- .. _propGetFloatArray: const double \*propGetFloatArray(const VSMap_ \*map, const char \*key, int \*error) Retrieves an array of floating point numbers from a map. Use this function if there are a lot of numbers associated with a key, because it is faster than calling propGetFloat_\ () in a loop. Returns a pointer to the first element of the array on success, or NULL 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. Use propNumElements_\ () to know the total number of elements associated with a key. *error* One 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. This function was introduced in API R3.1 (VapourSynth R26). ---------- .. _propGetData: const char \*propGetData(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 array returned is guaranteed to be NULL-terminated. The NULL byte is not considered to be part of the array (propGetDataSize_ doesn't count it). 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* One 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. ---------- .. _propGetDataSize: int propGetDataSize(const VSMap_ \*map, const char \*key, int index, int \*error) Returns the size in bytes of a property of type ptData (see VSPropTypes_), or 0 in case of error. The terminating NULL byte added by propSetData_\ () is not counted. ---------- .. _propGetNode: VSNodeRef_ \*propGetNode(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* One 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. ---------- .. _propGetFrame: const VSFrameRef_ \*propGetFrame(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* One 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. ---------- .. _propGetFunc: VSFuncRef_ \*propGetFunc(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* One 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. ---------- .. _propSetInt: int propSetInt(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. Alphanumeric characters and the underscore 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. ---------- .. _propSetIntArray: int propSetIntArray(VSMap_ \*map, const char \*key, const int64_t \*i, int size) Adds an array of integers to a map. Use this function if there are a lot of numbers to add, because it is faster than calling propSetInt_\ () in a loop. If *map* already contains a property with this *key*, that property will be overwritten and all old values will be lost. *key* Name of the property. Alphanumeric characters and the underscore may be used. *i* Pointer to the first element of the array to store. *size* Number of integers to read from the array. It can be 0, in which case no integers are read from the array, and the property will be created empty. Returns 0 on success, or 1 if *size* is negative. This function was introduced in API R3.1 (VapourSynth R26). ---------- .. _propSetFloat: int propSetFloat(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. Alphanumeric characters and the underscore 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. ---------- .. _propSetFloatArray: int propSetFloatArray(VSMap_ \*map, const char \*key, const double \*d, int size) Adds an array of floating point numbers to a map. Use this function if there are a lot of numbers to add, because it is faster than calling propSetFloat_\ () in a loop. If *map* already contains a property with this *key*, that property will be overwritten and all old values will be lost. *key* Name of the property. Alphanumeric characters and the underscore may be used. *d* Pointer to the first element of the array to store. *size* Number of floating point numbers to read from the array. It can be 0, in which case no numbers are read from the array, and the property will be created empty. Returns 0 on success, or 1 if *size* is negative. This function was introduced in API R3.1 (VapourSynth R26). ---------- .. _propSetData: int propSetData(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. Alphanumeric characters and the underscore 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. If this is negative, everything up to the first NULL byte will be copied. This function will always add a NULL byte at the end of the data. *append* One of VSPropAppendMode_. Returns 0 on success, or 1 if trying to append to a property with the wrong type. ---------- .. _propSetNode: int propSetNode(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. Alphanumeric characters and the underscore 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. ---------- .. _propSetFrame: int propSetFrame(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. Alphanumeric characters and the underscore 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. ---------- .. _propSetFunc: int propSetFunc(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. Alphanumeric characters and the underscore 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. ---------- .. _getPluginById: VSPlugin_ \*getPluginById(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. ---------- .. _getPluginByNs: VSPlugin_ \*getPluginByNs(const char \*ns, VSCore_ \*core) Returns a pointer to the plugin with the given namespace, or NULL if not found. getPluginById_ should be used instead. *ns* Namespace. ---------- .. _getPlugins: VSMap_ \*getPlugins(VSCore_ \*core) Returns a map containing a list of all loaded plugins. The map must be freed when no longer needed. Keys: Meaningless unique strings. Values: Namespace, identifier, and full name, separated by semicolons. ---------- .. _getFunctions: VSMap_ \*getFunctions(VSPlugin_ \*plugin) Returns a map containing a list of the filters exported by a plugin. The map must be freed when no longer needed. Keys: The filter names. Values: The filter name followed by its argument string, separated by a semicolon. ---------- .. _getPluginPath: const char \*getPluginPath(const VSPlugin_ \*plugin) Returns the absolute path to the plugin, including the plugin's file name. This is the real location of the plugin, i.e. there are no symbolic links in the path. Path elements are always delimited with forward slashes. VapourSynth retains ownership of the returned pointer. This function was introduced in VapourSynth R25 without bumping the API version (R3). ---------- .. _createFunc: VSFuncRef_ \*createFunc(VSPublicFunction func, void \*userData, VSFreeFuncData free, VSCore \*core, const VSAPI \*vsapi) *func* typedef void (VS_CC \*VSPublicFunction)(const VSMap_ \*in, VSMap_ \*out, void \*userData, VSCore_ \*core, const VSAPI_ \*vsapi) User-defined function that may be called in any context. *userData* Pointer passed to *func*. *free* typedef void (VS_CC \*VSFreeFuncData)(void \*userData) Callback tasked with freeing *userData*. ---------- .. _cloneFuncRef: VSFuncRef_ \*cloneFuncRef(VSFuncRef_ \*f) Duplicates a func reference. This new reference has to be deleted with freeFunc_\ () when it is no longer needed. ---------- .. _callFunc: void callFunc(VSFuncRef_ \*func, const VSMap_ \*in, VSMap_ \*out, VSCore_ \*core, const VSAPI_ \*vsapi) Calls a function. If the call fails *out* will have an error set. *func* Function to be called. *in* Arguments passed to *func*. *out* Returned values from *func*. *core* Must be NULL. *vsapi* Must be NULL. ---------- .. _freeFunc: void freeFunc(VSFuncRef_ \*f) Deletes a function reference, releasing the caller's ownership of the function. It is safe to pass NULL. Don't try to use the function once the reference has been deleted. ---------- .. _createFilter: void createFilter(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. This pointer will be passed to the *init*, *getFrame*, and *free* functions. It should be freed by the *free* function. After this function returns, *out* will contain the new node(s) in the "clip" property, or an error, if something went wrong. ---------- .. _registerFunction: void registerFunction(const char \*name, const char \*args, VSPublicFunction argsFunc, void \*functionData, VSPlugin_ \*plugin) See VSInitPlugin_. ---------- .. _invoke: VSMap_ \*invoke(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 that contains the filter, 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. Thread-safe. *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". The exception to this are functions, for example LoadPlugin, which doesn't return any clips for obvious reasons. ---------- .. _setFilterError: void setFilterError(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 necessarily fatal, i.e. the caller can try to request the same frame again. ---------- .. _getOutputIndex: int getOutputIndex(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. ---------- .. _queryCompletedFrame: void queryCompletedFrame(VSNodeRef_ \**node, int \*n, VSFrameContext_ \*frameCtx) .. warning:: This function has several issues and may or may not return the actual node or frame number. Finds out which requested frame is ready. To be used in a filter's "getframe" function, when it is called with *activationReason* arFrameReady. ---------- .. _releaseFrameEarly: void releaseFrameEarly(VSNodeRef_ \*node, int n, VSFrameContext_ \*frameCtx) Normally a reference is kept to all requested frames until the current frame is complete. If a filter scans a large number of frames this can consume all memory, instead the filter should release the internal frame references as well immediately by calling this function. Only use inside a filter's "getframe" function. Functions ######### .. _getVapourSynthAPI: 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. ---------- .. _VSInitPlugin: 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. Additionally, words that are special to Python, e.g. "del", should be avoided. 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. This is where the filter should perform any other initialisation it requires. 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*. ---------- .. _VSFilterInit: 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 the only place where setVideoInfo_\ () can be called. There is no reason to do anything else here. If an error occurs in this function: - 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. ---------- .. _VSFilterGetFrame: 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. It is never called concurrently for the same frame number. *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 it needs and return NULL. 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). By default, *frameData* is a pointer to NULL. 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. ---------- .. _VSFilterFree: 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.