User defined script functions

From Avisynth

[edit] Definition and Structure

You can define and call your own functions in AviSynth scripts as shown below. The function can return any clip or variable type. An user defined script function is an independent block of script code that is executed each time a call to the function is made in the script. An example of a simple user defined script function (here a custom filter) immediately follows:

function MuteRange(clip c, int fstart, int fend)
{
    before = c.Trim(0, -fstart)
    current = c.Trim(fstart, fend) 
    after = c.Trim(fend + 1, 0)
    audio = Dissolve(Dissolve(before, current.BlankClip, 3), after, 3)
    return AudioDub(c, audio)
}

User defined script functions start with the keyword function followed by the function name. The name of a script function follows the same naming rules as script variables.

Immediately after the name, the function's argument list follows. The list (which can be empty) consists of (expected argument's type - argument's name) pairs. Each argument must be a text string, an integer, a floating-point number, a boolean value or a video clip (that is, an expression).

function MuteRange(clip c, int fstart, int fend)

Then comes the function body, ie the code that is executed each time the function is called. The arguments are accessed within the function body by their names. The function body is contained within an opening and closing brace pair { ... }.

{
    before = c.Trim(0, -fstart)
    current = c.Trim(fstart, fend) 
    after = c.Trim(fend + 1, 0)
    audio = Dissolve(Dissolve(before, current.BlankClip, 3), after, 3)
    return AudioDub(c, audio)
}

At the end of the function body a return statement which returns the final value calculated from the arguments and the function's body code must be placed.

    return AudioDub(c, audio)

It should be noted that unlike other languages where multiple return statements are allowed inside the function body, in AviSynth functions contain a single return statement. This is because the language does not support branching (ie compound block statements).

[edit] Facts about user defined script functions

• Functions can take up to sixty arguments and the return value can be of any type supported by the scripting language (clip, int, float, bool, string).

• If the function expects a video clip as its first argument, and that argument is not supplied, then the clip in the special last variable will be used.

• Functions support named arguments. Simply enclose an argument's name inside double quotes to make it a named argument. Note that after doing so the following apply:
  1. All subsequent arguments in the argument list must be made named also.
  2. You must be prepared (ie use the Defined or Default Internal functions) inside the function body for the case that the argument is not supplied by the caller; that is a named argument is an optional argument.

• Functions always produce a new value and never modify an existing one. What that means is that all arguments to a function are passed "by value" and not "by reference"; in order to alter a variable's value in AviSynth script language you must assign to it a new value.

• Functions can call other functions, including theirselves. The later is known as recursion and is a very useful technique for creating functions that can accomplish complex tasks.

• Local function variables mask global ones with the same name inside the function body. For example, if you define in a function a local variable myvar by assigning to it a value, then you cannot read the global myvar anymore inside this function.

• The above is also true for arguments, since from the perspective of a function arguments are initialized local variables.

[edit] Related Links

• Shared functions. An ever growing collection of shared script functions created by the members of the AviSynth community.

{TEMP: http://www.avisynth.org/ShareFunctions}

• Conditional filters and script functions. A collection of highly useful conditional filters implemented as user defined script functions.

{TEMP: http://www.avisynth.org/ExportingSingleImage, http://www.avisynth.org/HowToApplyFilterToManySingleFrames :: Perhaps make decent functions from the last two?}

---

Back to AviSynth Syntax.