include/VapourSynth.h

   1 /*
   2 * Copyright (c) 2012 Fredrik Mellbin
   3 *
   4 * This file is part of VapourSynth.
   5 *
   6 * VapourSynth is free software; you can redistribute it and/or
   7 * modify it under the terms of the GNU Lesser General Public
   8 * License as published by the Free Software Foundation; either
   9 * version 2.1 of the License, or (at your option) any later version.
  10 *
  11 * VapourSynth is distributed in the hope that it will be useful,
  12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 * Lesser General Public License for more details.
  15 *
  16 * You should have received a copy of the GNU Lesser General Public
  17 * License along with VapourSynth; if not, write to the Free Software
  18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19 */
  20
  21 #ifndef VAPOURSYNTH_H
  22 #define VAPOURSYNTH_H
  23
  24 #include <stdint.h>
  25
  26 #define VAPOURSYNTH_API_VERSION 3
  27
  28 // Convenience for C++ users.
  29 #ifdef __cplusplus
  30 #       define VS_EXTERN_C extern "C"
  31 #else
  32 #       define VS_EXTERN_C
  33 #endif
  34
  35 #ifdef _WIN32
  36 #       define VS_CC __stdcall
  37 #else
  38 #       define VS_CC
  39 #endif
  40
  41 // And now for some symbol hide-and-seek...
  42 #if defined(_WIN32) // Windows being special
  43 #       define VS_EXTERNAL_API(ret) VS_EXTERN_C __declspec(dllexport) ret VS_CC
  44 #elif defined(__GNUC__) && __GNUC__ >= 4
  45 #       define VS_EXTERNAL_API(ret) VS_EXTERN_C __attribute__((visibility("default"))) ret VS_CC
  46 #else
  47 #       define VS_EXTERNAL_API(ret) VS_EXTERN_C ret VS_CC
  48 #endif
  49
  50 #if !defined(VSCORE_EXPORTS) && defined(_WIN32)
  51 #       define VS_API(ret) VS_EXTERN_C __declspec(dllimport) ret VS_CC
  52 #else
  53 #       define VS_API(ret) VS_EXTERNAL_API(ret)
  54 #endif
  55
  56 typedef struct VSFrameRef VSFrameRef;
  57 typedef struct VSNodeRef VSNodeRef;
  58 typedef struct VSCore VSCore;
  59 typedef struct VSPlugin VSPlugin;
  60 typedef struct VSNode VSNode;
  61 typedef struct VSFuncRef VSFuncRef;
  62 typedef struct VSMap VSMap;
  63 typedef struct VSAPI VSAPI;
  64 typedef struct VSFrameContext VSFrameContext;
  65
  66 typedef enum VSColorFamily {
  67     // all planar formats
  68     cmGray   = 1000000,
  69     cmRGB    = 2000000,
  70     cmYUV    = 3000000,
  71     cmYCoCg  = 4000000,
  72     // special for compatibility
  73     cmCompat = 9000000
  74 } VSColorFamily;
  75
  76 typedef enum VSSampleType {
  77     stInteger = 0,
  78     stFloat = 1
  79 } VSSampleType;
  80
  81 // The +10 is so people won't be using the constants interchangably "by accident"
  82 typedef enum VSPresetFormat {
  83     pfNone = 0,
  84
  85     pfGray8 = cmGray + 10,
  86     pfGray16,
  87
  88     pfGrayH,
  89     pfGrayS,
  90
  91     pfYUV420P8 = cmYUV + 10,
  92     pfYUV422P8,
  93     pfYUV444P8,
  94     pfYUV410P8,
  95     pfYUV411P8,
  96     pfYUV440P8,
  97
  98     pfYUV420P9,
  99     pfYUV422P9,
 100     pfYUV444P9,
 101
 102     pfYUV420P10,
 103     pfYUV422P10,
 104     pfYUV444P10,
 105
 106     pfYUV420P16,
 107     pfYUV422P16,
 108     pfYUV444P16,
 109
 110     pfYUV444PH,
 111     pfYUV444PS,
 112
 113     pfRGB24 = cmRGB + 10,
 114     pfRGB27,
 115     pfRGB30,
 116     pfRGB48,
 117
 118     pfRGBH,
 119     pfRGBS,
 120
 121     // special for compatibility, if you implement these in any filter I'll personally kill you
 122     // I'll also change their ids around to break your stuff regularly
 123     pfCompatBGR32 = cmCompat + 10,
 124     pfCompatYUY2
 125 } VSPresetFormat;
 126
 127 typedef enum VSFilterMode {
 128     fmParallel = 100, // completely parallel execution
 129     fmParallelRequests = 200, // for filters that are serial in nature but can request one or more frames they need in advance
 130     fmUnordered = 300, // for filters that modify their internal state every request
 131     fmSerial = 400 // for source filters and compatibility with other filtering architectures
 132 } VSFilterMode;
 133
 134 typedef struct VSFormat {
 135     char name[32];
 136     int id;
 137     int colorFamily; // see VSColorFamily
 138     int sampleType; // see VSSampleType
 139     int bitsPerSample; // number of significant bits
 140     int bytesPerSample; // actual storage is always in a power of 2 and the smallest possible that can fit the number of bits used per sample
 141
 142     int subSamplingW; // log2 subsampling factor, applied to second and third plane
 143     int subSamplingH;
 144
 145     int numPlanes; // implicit from colorFamily
 146 } VSFormat;
 147
 148 typedef enum NodeFlags {
 149     nfNoCache = 1,
 150 } NodeFlags;
 151
 152 typedef enum GetPropErrors {
 153     peUnset = 1,
 154     peType  = 2,
 155     peIndex = 4
 156 } GetPropErrors;
 157
 158 typedef enum PropAppendMode {
 159     paReplace = 0,
 160     paAppend  = 1,
 161     paTouch   = 2
 162 } PropAppendMode;
 163
 164 typedef struct VSCoreInfo {
 165     const char *versionString;
 166     int core;
 167     int api;
 168     int numThreads;
 169     int64_t maxFramebufferSize;
 170     int64_t usedFramebufferSize;
 171 } VSCoreInfo;
 172
 173 typedef struct VSVideoInfo {
 174     const VSFormat *format;
 175     int64_t fpsNum;
 176     int64_t fpsDen;
 177     int width;
 178     int height;
 179     int numFrames;
 180     int flags;
 181 } VSVideoInfo;
 182
 183 typedef enum ActivationReason {
 184     arInitial = 0,
 185     arFrameReady = 1,
 186     arAllFramesReady = 2,
 187     arError = -1
 188 } ActivationReason;
 189
 190 // core function typedefs
 191 typedef VSCore *(VS_CC *VSCreateCore)(int threads);
 192 typedef void (VS_CC *VSFreeCore)(VSCore *core);
 193 typedef const VSCoreInfo *(VS_CC *VSGetCoreInfo)(VSCore *core);
 194
 195 // function/filter typedefs
 196 typedef void (VS_CC *VSPublicFunction)(const VSMap *in, VSMap *out, void *userData, VSCore *core, const VSAPI *vsapi);
 197 typedef void (VS_CC *VSFreeFuncData)(void *userData);
 198 typedef void (VS_CC *VSFilterInit)(VSMap *in, VSMap *out, void **instanceData, VSNode *node, VSCore *core, const VSAPI *vsapi);
 199 typedef const VSFrameRef *(VS_CC *VSFilterGetFrame)(int n, int activationReason, void **instanceData, void **frameData, VSFrameContext *frameCtx, VSCore *core, const VSAPI *vsapi);
 200 typedef int (VS_CC *VSGetOutputIndex)(VSFrameContext *frameCtx);
 201 typedef void (VS_CC *VSFilterFree)(void *instanceData, VSCore *core, const VSAPI *vsapi);
 202 typedef void (VS_CC *VSRegisterFunction)(const char *name, const char *args, VSPublicFunction argsFunc, void *functionData, VSPlugin *plugin);
 203 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);
 204 typedef VSMap *(VS_CC *VSInvoke)(VSPlugin *plugin, const char *name, const VSMap *args);
 205 typedef void (VS_CC *VSSetError)(VSMap *map, const char *errorMessage);
 206 typedef const char *(VS_CC *VSGetError)(const VSMap *map);
 207 typedef void (VS_CC *VSSetFilterError)(const char *errorMessage, VSFrameContext *frameCtx);
 208
 209 typedef const VSFormat *(VS_CC *VSGetFormatPreset)(int id, VSCore *core);
 210 typedef const VSFormat *(VS_CC *VSRegisterFormat)(int colorFamily, int sampleType, int bitsPerSample, int subSamplingW, int subSamplingH, VSCore *core);
 211
 212 // frame and clip handling
 213 typedef void (VS_CC *VSFrameDoneCallback)(void *userData, const VSFrameRef *f, int n, VSNodeRef *, const char *errorMsg);
 214 typedef void (VS_CC *VSGetFrameAsync)(int n, VSNodeRef *node, VSFrameDoneCallback callback, void *userData);
 215 typedef const VSFrameRef *(VS_CC *VSGetFrame)(int n, VSNodeRef *node, char *errorMsg, int bufSize);
 216 typedef void (VS_CC *VSRequestFrameFilter)(int n, VSNodeRef *node, VSFrameContext *frameCtx);
 217 typedef const VSFrameRef *(VS_CC *VSGetFrameFilter)(int n, VSNodeRef *node, VSFrameContext *frameCtx);
 218 typedef const VSFrameRef *(VS_CC *VSCloneFrameRef)(const VSFrameRef *f);
 219 typedef VSNodeRef *(VS_CC *VSCloneNodeRef)(VSNodeRef *node);
 220 typedef VSFuncRef *(VS_CC *VSCloneFuncRef)(VSFuncRef *f);
 221 typedef void (VS_CC *VSFreeFrame)(const VSFrameRef *f);
 222 typedef void (VS_CC *VSFreeNode)(VSNodeRef *node);
 223 typedef void (VS_CC *VSFreeFunc)(VSFuncRef *f);
 224 typedef VSFrameRef *(VS_CC *VSNewVideoFrame)(const VSFormat *format, int width, int height, const VSFrameRef *propSrc, VSCore *core);
 225 typedef VSFrameRef *(VS_CC *VSNewVideoFrame2)(const VSFormat *format, int width, int height, const VSFrameRef **planeSrc, const int *planes, const VSFrameRef *propSrc, VSCore *core);
 226 typedef VSFrameRef *(VS_CC *VSCopyFrame)(const VSFrameRef *f, VSCore *core);
 227 typedef void (VS_CC *VSCopyFrameProps)(const VSFrameRef *src, VSFrameRef *dst, VSCore *core);
 228 typedef int (VS_CC *VSGetStride)(const VSFrameRef *f, int plane);
 229 typedef const uint8_t *(VS_CC *VSGetReadPtr)(const VSFrameRef *f, int plane);
 230 typedef uint8_t *(VS_CC *VSGetWritePtr)(VSFrameRef *f, int plane);
 231
 232 // property access
 233 typedef const VSVideoInfo *(VS_CC *VSGetVideoInfo)(VSNodeRef *node);
 234 typedef void (VS_CC *VSSetVideoInfo)(const VSVideoInfo *vi, int numOutputs, VSNode *node);
 235 typedef const VSFormat *(VS_CC *VSGetFrameFormat)(const VSFrameRef *f);
 236 typedef int (VS_CC *VSGetFrameWidth)(const VSFrameRef *f, int plane);
 237 typedef int (VS_CC *VSGetFrameHeight)(const VSFrameRef *f, int plane);
 238 typedef const VSMap *(VS_CC *VSGetFramePropsRO)(const VSFrameRef *f);
 239 typedef VSMap *(VS_CC *VSGetFramePropsRW)(VSFrameRef *f);
 240 typedef int (VS_CC *VSPropNumKeys)(const VSMap *map);
 241 typedef const char *(VS_CC *VSPropGetKey)(const VSMap *map, int index);
 242 typedef int (VS_CC *VSPropNumElements)(const VSMap *map, const char *key);
 243 typedef char(VS_CC *VSPropGetType)(const VSMap *map, const char *key);
 244
 245 typedef VSMap *(VS_CC *VSNewMap)(void);
 246 typedef void (VS_CC *VSFreeMap)(VSMap *map);
 247 typedef void (VS_CC *VSClearMap)(VSMap *map);
 248
 249 typedef int64_t (VS_CC *VSPropGetInt)(const VSMap *map, const char *key, int index, int *error);
 250 typedef double(VS_CC *VSPropGetFloat)(const VSMap *map, const char *key, int index, int *error);
 251 typedef const char *(VS_CC *VSPropGetData)(const VSMap *map, const char *key, int index, int *error);
 252 typedef int (VS_CC *VSPropGetDataSize)(const VSMap *map, const char *key, int index, int *error);
 253 typedef VSNodeRef *(VS_CC *VSPropGetNode)(const VSMap *map, const char *key, int index, int *error);
 254 typedef const VSFrameRef *(VS_CC *VSPropGetFrame)(const VSMap *map, const char *key, int index, int *error);
 255 typedef VSFuncRef *(VS_CC *VSPropGetFunc)(const VSMap *map, const char *key, int index, int *error);
 256
 257 typedef int (VS_CC *VSPropDeleteKey)(VSMap *map, const char *key);
 258 typedef int (VS_CC *VSPropSetInt)(VSMap *map, const char *key, int64_t i, int append);
 259 typedef int (VS_CC *VSPropSetFloat)(VSMap *map, const char *key, double d, int append);
 260 typedef int (VS_CC *VSPropSetData)(VSMap *map, const char *key, const char *data, int size, int append);
 261 typedef int (VS_CC *VSPropSetNode)(VSMap *map, const char *key, VSNodeRef *node, int append);
 262 typedef int (VS_CC *VSPropSetFrame)(VSMap *map, const char *key, const VSFrameRef *f, int append);
 263 typedef int (VS_CC *VSPropSetFunc)(VSMap *map, const char *key, VSFuncRef *func, int append);
 264
 265 // mixed
 266
 267 typedef void (VS_CC *VSConfigPlugin)(const char *identifier, const char *defaultNamespace, const char *name, int apiVersion, int readonly, VSPlugin *plugin);
 268 typedef void (VS_CC *VSInitPlugin)(VSConfigPlugin configFunc, VSRegisterFunction registerFunc, VSPlugin *plugin);
 269
 270 typedef VSPlugin *(VS_CC *VSGetPluginId)(const char *identifier, VSCore *core);
 271 typedef VSPlugin *(VS_CC *VSGetPluginNs)(const char *ns, VSCore *core);
 272
 273 typedef VSMap *(VS_CC *VSGetPlugins)(VSCore *core);
 274 typedef VSMap *(VS_CC *VSGetFunctions)(VSPlugin *plugin);
 275
 276 typedef void (VS_CC *VSCallFunc)(VSFuncRef *func, const VSMap *in, VSMap *out, VSCore *core, const VSAPI *vsapi);
 277 typedef VSFuncRef *(VS_CC *VSCreateFunc)(VSPublicFunction func, void *userData, VSFreeFuncData free);
 278
 279 typedef void (VS_CC *VSQueryCompletedFrame)(VSNodeRef **node, int *n, VSFrameContext *frameCtx);
 280 typedef void (VS_CC *VSReleaseFrameEarly)(VSNodeRef *node, int n, VSFrameContext *frameCtx);
 281
 282 typedef int64_t (VS_CC *VSSetMaxCacheSize)(int64_t bytes, VSCore *core);
 283
 284
 285 struct VSAPI {
 286     VSCreateCore createCore;
 287     VSFreeCore freeCore;
 288     VSGetCoreInfo getCoreInfo;
 289
 290     VSCloneFrameRef cloneFrameRef;
 291     VSCloneNodeRef cloneNodeRef;
 292     VSCloneFuncRef cloneFuncRef;
 293
 294     VSFreeFrame freeFrame;
 295     VSFreeNode freeNode;
 296     VSFreeFunc freeFunc;
 297
 298     VSNewVideoFrame newVideoFrame;
 299     VSCopyFrame copyFrame;
 300     VSCopyFrameProps copyFrameProps;
 301
 302     VSRegisterFunction registerFunction;
 303     VSGetPluginId getPluginId;
 304     VSGetPluginNs getPluginNs;
 305     VSGetPlugins getPlugins;
 306     VSGetFunctions getFunctions;
 307     VSCreateFilter createFilter; // do never use inside a filter's getframe function
 308     VSSetError setError; // use to signal errors outside filter getframe functions
 309     VSGetError getError; // use to query errors, returns 0 if no error
 310     VSSetFilterError setFilterError; // use to signal errors in the filter getframe function
 311     VSInvoke invoke; // may not be used inside a filter's getframe method
 312
 313     VSGetFormatPreset getFormatPreset; //threadsafe
 314     VSRegisterFormat registerFormat; // threadsafe
 315
 316     VSGetFrame getFrame; // do never use inside a filter's getframe function, for external applications using the core as a library or for requesting frames in a filter constructor
 317     VSGetFrameAsync getFrameAsync; // do never use inside a filter's getframe function, for external applications using the core as a library or for requesting frames in a filter constructor
 318     VSGetFrameFilter getFrameFilter; // only use inside a filter's getframe function
 319     VSRequestFrameFilter requestFrameFilter; // only use inside a filter's getframe function
 320     VSQueryCompletedFrame queryCompletedFrame; // only use inside a filter's getframe function
 321     VSReleaseFrameEarly releaseFrameEarly; // only use inside a filter's getframe function
 322
 323     VSGetStride getStride;
 324     VSGetReadPtr getReadPtr;
 325     VSGetWritePtr getWritePtr;
 326
 327     VSCreateFunc createFunc;
 328     VSCallFunc callFunc;
 329
 330     //property access functions
 331     VSNewMap newMap;
 332     VSFreeMap freeMap;
 333     VSClearMap clearMap;
 334
 335     VSGetVideoInfo getVideoInfo;
 336     VSSetVideoInfo setVideoInfo;
 337     VSGetFrameFormat getFrameFormat;
 338     VSGetFrameWidth getFrameWidth;
 339     VSGetFrameHeight getFrameHeight;
 340     VSGetFramePropsRO getFramePropsRO;
 341     VSGetFramePropsRW getFramePropsRW;
 342
 343     VSPropNumKeys propNumKeys;
 344     VSPropGetKey propGetKey;
 345     VSPropNumElements propNumElements;
 346     VSPropGetType propGetType;
 347     VSPropGetInt propGetInt;
 348     VSPropGetFloat propGetFloat;
 349     VSPropGetData propGetData;
 350     VSPropGetDataSize propGetDataSize;
 351     VSPropGetNode propGetNode;
 352     VSPropGetFrame propGetFrame;
 353     VSPropGetFunc propGetFunc;
 354
 355     VSPropDeleteKey propDeleteKey;
 356     VSPropSetInt propSetInt;
 357     VSPropSetFloat propSetFloat;
 358     VSPropSetData propSetData;
 359     VSPropSetNode propSetNode;
 360     VSPropSetFrame propSetFrame;
 361     VSPropSetFunc propSetFunc;
 362
 363     VSSetMaxCacheSize setMaxCacheSize;
 364     VSGetOutputIndex getOutputIndex;
 365     VSNewVideoFrame2 newVideoFrame2;
 366 };
 367
 368 VS_API(const VSAPI *) getVapourSynthAPI(int version);
 369
 370 #endif // VAPOURSYNTH_H