Documenting AviSynth api

[Wilbert]

As is well known the AviSynth api is poorly documented. The part which is documented is scattered among the wiki and this forum. Some of it can be found here http://avisynth.org/mediawiki/Filter_SDK .

A while ago I started to collect, rewrite and complete all the documentation and I can use some help. The idea is that the content in the above wiki link will be replaced by something which is well structured, complete and contains a lot of examples.

What I have done so far:

http://avisynth.org/mediawiki/User:Wilbert/Filter_SDK
http://avisynth.org/mediawiki/Cplusplus_API
http://avisynth.org/mediawiki/Cplusplus_API/VideoInfo
http://avisynth.org/mediawiki/C_API

As you can see a lot is still missing. I need people who are willing to correct and proof-read the stuff about the C++ api. I also need people who are willing to document the C api and create a c-version of the example plugins: Simple Sample 1.6 and Simple Sample 1.7. Any volunteers who are willing to help?

I also would like to hear your ideas about what I have done so far. Is it better than what existed, should it be organized in a different way, do other things need to be added, other relevant things which you can think off ???

[kemuri-_9]

I have a fair bit of experience in the C interface so I may be able to help there, granted I can find time to do so in my schedule.

If I were to write simple sample 1.6 and 1.7 in the C interface, how should it be provided to you?

[Wilbert]

I have a fair bit of experience in the C interface so I may be able to help there, granted I can find time to do so in my schedule.
That would be great!

If I were to write simple sample 1.6 and 1.7 in the C interface, how should it be provided to you?
If you provide it in html or doc format would be fine. Adding it to the wiki is fine too if you prefer that.

[Wilbert]

Some questions for those who know the internals better than i do:

1) SetCacheHints(CACHE_RANGE, frame_range)

Does frame_range denote the diameter or radius of frames to be cached? Is it the diameter prior to v2.56? The cache code is too complicated for me to follow.

2) PushContext / PopContext / PopContextGlobal

What's the difference between those and when is each used?

3) What's the difference between SetVar and SetGlobalVar?

4) What's the difference between CACHE_AUDIO_AUTO and CACHE_AUDIO?

[TheFluff]

3: the first one sets a local variable and the second sets a global. That is, the first one is equivalent to a simple "foo = bar", while the second is equivalent to "global foo = bar".

[StainlessS]

Some questions for those who know the internals better than i do:
3) What's the difference between SetVar and SetGlobalVar?

Not the question (already answered by TheFluff) BUT ,
The return value from SetVar/SetGlobalVar denotes whether the variable already exists (false) or newly created (true), not denoting error situation as in API docs Cplusplus_API (from my reading of source script.cpp a week or so ago).

Question:
When do you use env->SaveString() for SetVar/SetGlobalVar, only when the variable name does not already exist ?

When do you use env->SaveString() for SetVar/SetGlobalVar, with the value, always for strings ?

EDIT: Would be nice if Wilberts questions could be answered too.

EDIT: Nice work in the docs Wilbert.

[Gavino]

When do you use env->SaveString() for SetVar/SetGlobalVar, only when the variable name does not already exist ?

When do you use env->SaveString() for SetVar/SetGlobalVar, with the value, always for strings ?
The principles are the same as for other uses of SaveString.

Since Set[Global]Var does not copy the contents of the variable name (only a pointer to it), you need to use SaveString if the memory holding the name string will be deallocated before the current script environment (eg a local variable) [unless you know (in advance) that the name already exists].

Similarly, if the value is a string, use SaveString if the string contents are stored in memory that will not survive long enough.

[StainlessS]

I did read about 3 pages (search) of posts for SetVar and about 1 for SetGlobalVar (or other way around)
and was no wiser afterwards. Some people always used, some never and one fellow fixed a bug by using SaveString.
I implemented ShowChannels latest beta as you describe so thats OK, I'm always uncomfortable if I dont know the
specifics and dont like guessing.
Thank you maestro.

[IanB]

Sorry, I intended to answer this post, but I got distracted and subsequently forgot about it :o
Some questions for those who know the internals better than i do:

1) SetCacheHints(CACHE_RANGE, frame_range)

Does frame_range denote the diameter or radius of frames to be cached? Is it the diameter prior to v2.56? The cache code is too complicated for me to follow.
CACHE_RANGE currently provides a hard cache of up to frame_range buffers. When a new frame is buffered any buffers containing frames outside the radius frame_range are released. With normal sequential access only frame_range buffers are ever protected.
E.g. for frame_range=3 and frame 10 is the next frame being generated. Frames 8, 9, 10, 11 & 12 become eligible for protection, any frames <= 7 and >= 13 will be marked unprotected. From the previous iteration, frames 7, 8 & 9 will be cached and protected, 10, 11 & 12 have never been requested so will not exist. As frame 10 is being added frame 7 will become marked unprotected, frames 8 & 9 will remain protected and new frame 10 will become protected, frames 11 and 12 still do not exist.

Note! Subsequently accessing frame 8 will make frames 6, 7, 8, 9 & 10 eligible but will not cause them to become explicitly protected. So frames 6 & 7 will be left alone and will remain marked unprotected, if they even still exist, frame 8 will be explicitly marked as protected (a nop) and frames 9 & 10 will be left alone and remain marked as protected.

I believe that CACHE_RANGE has always worked fundamentally as described above, but there has been much confusion about the frame_range values to be used. Earlier cache.cpp versions maintained a table frame_range*2+1 in size but frames outside the radius frame_range were always evicted as new frames were added so the table was only ever half full.
E.g. With frames 7, 8 & 9 in the table, adding frame 11 would make frames 9, 10, 11, 12 & 13 eligible. This will evict frames 7 & 8. Frame 9 will remain, frame 11 will be added and frames 10, 12 & 13 will not exist yet.

CACHE_RANGE is being renamed to CACHE_WINDOW in 2.6 This will require plugin authors using CACHE_RANGE to re-evaluate the caching needs of their filters in consideration of a hopefully less ambiguous definition of the cache api.

2) PushContext / PopContext / PopContextGlobal

What's the difference between those and when is each used?
PushContext() and PopContext() are used to implement local script function name space contexts. A plugin could use these to create a new local name space before Invok'ing or Eval'ing script expressions in order to avoid clashes with similarly named variables in the calling script.

PushContext() and PopContext() should always be used in matched pairs, and the code region of interest be try/catch protected with a PopContext() in the catch case.

PopContextGlobal() will release the global script namespace. It is used as part of the ~IScriptEnvironment cleanup, calling this function outside of this function is usually pretty fatal. It is currently of no use in user plugins. My guess is BenRG had some thought about having a matching PushContextGlobal() but it was apparently not needed and was never implemented. Likewise PushContext(Level) always ignores the level argument, my guess is BenRG had some thought about having nestable local namespaces like in nested Pascal functions but it was apparently not needed and was never implemented.

3) What's the difference between SetVar and SetGlobalVar?
SetVar and SetGlobalVar implement script variables. Filters can use the IScriptEnvironment callbacks together with GetVar to interact with the calling scripts variables.

SetVar manipulates variables in the current local script function context. See PushContext.

SetGlobalVar manipulates global script variables declared with the GLOBAL qualifier.

The variable core only maintains the pointers to the name strings passed in, so the memory containing the names must remain constant and current for the duration of context maintaining the variables. Using env->SaveString is a convenient way to allocate pseudo static memory for the script duration. You could equally use strdup but then you need to eventually free the buffer when the context is no longer current to avoid a memory leak.

4) What's the difference between CACHE_AUDIO_AUTO and CACHE_AUDIO?
CACHE_AUDIO is to explicitly cache audio with an initial X byte cache. Auto mode can increase the size if required, but will never disable or decrease the cache.

CACHE_AUDIO_AUTO is used internally to turn the Audio cache on in auto mode.

CACHE_AUDIO_NONE is the default and starts with the Audio cache off but in auto mode.

Auto mode monitors the input request pattern for forwards and backwards accesses. When it detects sufficient backwards accesses it switches to CACHE_AUDIO_AUTO mode. When it detects only forwards accesses with no further backwards accesses it switches back to CACHE_AUDIO_NONE mode and waits for any further sufficient backwards accesses.

Auto mode also monitors the success and failure of the cache when enabled and will increase the cache size when required. A future edition could also decrease the cache size if indicated, the current version only reverts to CACHE_AUDIO_NONE mode.

CACHE_AUDIO_NOTHING is new in 2.6 and is to explicitly not cache audio and disables auto mode scanning.

[StainlessS]

Wilbert, links in opening post are broken.

EDIT: Perhaps these are correct.

http://www.avisynth.nl/index.php/Filter_SDK
http://www.avisynth.nl/index.php/Cplusplus_API
http://www.avisynth.nl/index.php/Cplusplus_API/VideoInfo
http://www.avisynth.nl/index.php/C_API

Not sure about the "User:Wilbert/Filter_SDK" link.

[martin53]

Wilbert,
highly appreciate your effort to improve documentation! :thanks:
There's also a Wiki page about how to set up a build environment - and currently there's a small discussion about that in the RT_Stats thread. I think me and others would also be very grateful if the mentioned page was updated and important hints were added - e.g. to avoid conflicting other compilers with a higher %PATH% priority, who needs Visual C++ Toolkit 2003 and who doesn't, etc etc.

I am about to set up a plugin IDE, but I'm really afraid about what I learn about all the things to observe - and I only notice it by chance as some off topic remarks here, there and there. :scared: I think I haven't got the time to go through all possible shallows of bad IDE configurations.
Maybe VS 2010, that seems to compile for XP ... W7 (W8?), x86+x64, I don't ask for more than one reasonable suggestion.

[Wilbert]

There's also a Wiki page about how to set up a build environment - and currently there's a small discussion about that in the RT_Stats thread. I think me and others would also be very grateful if the mentioned page was updated and important hints were added - e.g. to avoid conflicting other compilers with a higher %PATH% priority, who needs Visual C++ Toolkit 2003 and who doesn't, etc etc.

Could you give links to the relevants posts here? That thread is long ;) Then i will include when i have some time ...

Guess you mean http://forum.doom9.org/showthread.php?p=1654825#post1654825 + next couple of pages.

[martin53]

Guess you mean http://forum.doom9.org/showthread.php?p=1654825#post1654825 + next couple of pages.
Yep. Thank you for your time!

[Groucho2004]

There's also a Wiki page about how to set up a build environment - and currently there's a small discussion about that in the RT_Stats thread. I think me and others would also be very grateful if the mentioned page was updated and important hints were added - e.g. to avoid conflicting other compilers with a higher %PATH% priority, who needs Visual C++ Toolkit 2003 and who doesn't, etc etc.

I am about to set up a plugin IDE, but I'm really afraid about what I learn about all the things to observe - and I only notice it by chance as some off topic remarks here, there and there. :scared: I think I haven't got the time to go through all possible shallows of bad IDE configurations.
Maybe VS 2010, that seems to compile for XP ... W7 (W8?), x86+x64, I don't ask for more than one reasonable suggestion.
There is already a guide (http://www.avisynth.nl/index.php/Filter_SDK/Compiling_instructions) on Avisynth.nl that describes how to build plugins with various Visual Studio versions and as far as I can see, it's sufficient. The guide for VS2008 on that page should provide enough info make it also work with VS2010 and 2012.