User defined script functions - Revision history

Pinterf: /* Array examples {{AvsPluscon}} */ move avs+ icon

2021-01-20T08:41:49Z

Array examples {{AvsPluscon}}: move avs+ icon

← Older revision		Revision as of 10:41, 20 January 2021
Line 76:		Line 76:
	* Each function has its own local version of the special variable ''Last''. On entry to a function, ''Last'' is set to a void ('undefined') value.		* Each function has its own local version of the special variable ''Last''. On entry to a function, ''Last'' is set to a void ('undefined') value.

	==== Array examples {{AvsPluscon}} ~~====~~		==== Array examples ====
			{{AvsPluscon}}

	Parameters that are "arrays" in the function definition, can be be given with the usual comma separated way.		Parameters that are "arrays" in the function definition, can be be given with the usual comma separated way.

Pinterf: /* Array examples {{AvsPluscon}} */ Fill with content

2021-01-20T08:37:17Z

Array examples {{AvsPluscon}}: Fill with content

← Older revision		Revision as of 10:37, 20 January 2021
Line 77:		Line 77:

	==== Array examples {{AvsPluscon}} ====		==== Array examples {{AvsPluscon}} ====

			Parameters that are "arrays" in the function definition, can be be given with the usual comma separated way.

			"zero or more of anything" parameters can only occur at the very end or the parameter list because the parameters can begiven in a flattened way (like in classic Avisynth where there had been no [] array syntax).

			Avisynth parser engine is not able to distinguish between not-given or zero-sized arrays parameters. Avisynth was always working with simple 1D arrays which are used for example in Apply, Format, Animate, etc. If the parameters at the given place were not provided, the array size was 0. But the variable was always existing.

			Note 1:
			int_array and the other fixed-type arrays are type checked. They are only 1D arrays.

			Note 2:
			"val_array" (array of anything) type is special. The parser has not even any clue what type of parameters should it expect.
			So when you pass a direct array for that (like in the "Dedicated val_array" example) it will take as a distinct value and will put it as a subarray of the given "n" variable. In r_val(20, "Dedicated val_array", [1,2,3]) n will be an array of size 1, containing the [1,2,3] array in its 0th element

			This is because arrays can contain anything, even different type of subarrays or other types in an infinite depth.

			<div {{BoxWidthIndent\|100\|1}} >
			BlankClip(width=1024,pixel_type="yv12")

			r(0, "Dedicated int_array", [1,2,3])
			r_val(20, "Dedicated val_array", [1,2,3])
			r_val(40, "Dedicated val_array", [1,2,3],["hello","leo",2])
			r(60, "Classic int_array", 1,2,3)
			r_val(80, "Classic val_array", 1,2,3)
			r(100, "Nothing =classic int_array (zero sized)")
			r(120, "Nothing =classic val_array (zero sized)")

			function r(clip c, int y, string s, int_array "n")
			{
			x=0
			if(ArraySize(n) == 3) {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={},[0]={},[1]={},[2]={}",s, ArraySize(n),n[0],n[1],n[2]))
			} else {
			if(ArraySize(n) == 1) {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={}, n[0] length={},[0,0]={},[0,1]={},[0,2]={}", s, ArraySize(n),ArraySize(n[0]),n[0,0],n[0,1],n[0,2]))
			} else if(ArraySize(n) == 2) {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={}, n[0] length={},n[1] length={},[0,0]={},[0,1]={},[0,2]={},[1,0]={},[1,1]={},[1,2]={}", \
			s, ArraySize(n),ArraySize(n[0]),ArraySize(n[1]),n[0,0],n[0,1],n[0,2],n[1,0],n[1,1],n[1,2]))
			} else {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={}",s, ArraySize(n)))
			}
			}
			}

			function r_val(clip c, int y, string s, val_array "n")
			{
			x=0
			if(ArraySize(n) == 3) {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={},[0]={},[1]={},[2]={}",s, ArraySize(n),n[0],n[1],n[2]))
			} else {
			if(ArraySize(n) == 1) {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={}, n[0] length={},[0,0]={},[0,1]={},[0,2]={}", s, ArraySize(n),ArraySize(n[0]),n[0,0],n[0,1],n[0,2]))
			} else if(ArraySize(n) == 2) {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={}, n[0] length={},n[1] length={},[0,0]={},[0,1]={},[0,2]={},[1,0]={},[1,1]={},[1,2]={}", \
			s, ArraySize(n),ArraySize(n[0]),ArraySize(n[1]),n[0,0],n[0,1],n[0,2],n[1,0],n[1,1],n[1,2]))
			} else {
			return Subtitle(c, x=x, y=y, Format("{}: Array length={}",s, ArraySize(n)))
			}
			}
			}
			</div>

	==== Related Links ====		==== Related Links ====

Pinterf: User defined script functions: Add Array examples section

2021-01-20T08:32:39Z

User defined script functions: Add Array examples section

← Older revision		Revision as of 10:32, 20 January 2021
Line 75:		Line 75:

	* Each function has its own local version of the special variable ''Last''. On entry to a function, ''Last'' is set to a void ('undefined') value.		* Each function has its own local version of the special variable ''Last''. On entry to a function, ''Last'' is set to a void ('undefined') value.

			==== Array examples {{AvsPluscon}} ====

	==== Related Links ====		==== Related Links ====

Pinterf: /* Facts about user defined script functions */

2021-01-20T08:28:59Z

Facts about user defined script functions

← Older revision		Revision as of 10:28, 20 January 2021
Line 43:		Line 43:
	==== Facts about user defined script functions ====		==== 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).		* 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, {{AvsPluscon}}array).

	* Although not recommended practice, an argument type may be omitted, and will default to <tt>val</tt>, the generic type.		* Although not recommended practice, an argument type may be omitted, and will default to <tt>val</tt>, the generic type.
Line 53:		Line 53:
	*# '''A named argument is an optional argument''', that is, it need not be supplied by the caller.		*# '''A named argument is an optional argument''', that is, it need not be supplied by the caller.
	*# When a function is called, any optional argument which has ''not'' been provided is set to a value which has the void ('undefined') type. This does not mean that its value is random garbage - simply that its type is neither clip, int, float, bool or string and so it has ''no'' usable value.		*# When a function is called, any optional argument which has ''not'' been provided is set to a value which has the void ('undefined') type. This does not mean that its value is random garbage - simply that its type is neither clip, int, float, bool or string and so it has ''no'' usable value.
	*# Normally, you should use the [[Internal_functions/Boolean_functions\|Defined]] function to test if an optional argument has an explicit value, or the [[Internal_functions/Control_functions\|Default]] function, which combines the Defined test with the setting of a default value if appropriate.		*# {{AvsPluscon}} Except: calling with missing parameters a parameter 'val_array' yields a zero sized array. The array parameter will always be defined but the size will be zero.
			*# {{AvsPluscon}} Array type parameters can be be given with the usual comma separated way. Arrays other than val_array are allowed to pass with the bracket syntax. E.g. [1.0, 3.0, 3.14] for a float_array.
			*# Normally, you should use the [[Internal_functions/Boolean_functions\|Defined]] function to test if an optional argument has an explicit value, or the [[Internal_functions/Control_functions\|Default]] function, which combines the Defined test with the setting of a default value if appropriate. {{AvsPluscon}} a val_array (array of anything) is always defined and has the size of zero.
	*# A void ('undefined') value can be passed on to another function as one of its optional arguments. This is useful when you want to write a wrapper function that calls another function, preserving the same defaults.		*# A void ('undefined') value can be passed on to another function as one of its optional arguments. This is useful when you want to write a wrapper function that calls another function, preserving the same defaults.

			* {{AvsPluscon}} As mentioned, Avisynth traditionally was always using arrays for internal and plugin function definitions. Array (zero or more of anything) is marked as type specifier ".". Integer array is marked "i", array of string is "s*" in the function definition. Arrays are used for example in "Select" or "GeneralConvolution" or "StackHorizontal". Avisynth+ (since v3.6) was just extended their use on script level.

			* {{AvsPluscon}} Rules for arrays.
			** val_array: array of anything; zero or more element. Can occur at the last position of the parameter list. Being an untyped array element can be another array. Untyped arrays can contain variables or any type (int, string, etc.., arrays) in arbitrary depth. The reason, why val_array is allowed only at the very last parameter is because parameters at this place can be simply given as a comma separated syntax. (This syntax is used internally in classic Avisynth as well when getting a parameter list into an array.) Because of this simple syntax, when not providing any parameters in the function call for val_array, Avisynth thinks that a zero-sized array is passed. One would argue that by providing a [] (empty array) would help, but no, it creates an array which has a single empty array element.
			** bool_array, int_array, string_array, float_array, clip_array, func_array: simple 1D arrays of the specified type. When called from script, typed array values must be passed with the bracketed syntax e.g. [1, 2, 3] when provided directly, or passing an existing array type variable. Exception: Avisynth recognizes a fixed-type array when providing it in a comma separated way instead of the [] style in two cases. Case #1: parameter is the very last one. Case #2: the parameters values are followed by a differently typed value. Avisynth can recognize the end of the comma separatedly given array only by encountering a different type.

	* If a function body has no (explicit or implicit) return, a void value (ie a value of the 'undefined' type) is returned.		* If a function body has no (explicit or implicit) return, a void value (ie a value of the 'undefined' type) is returned.

Raffriff42: formatting, links, phrasing TODO Related Links

2016-03-12T15:59:13Z

formatting, links, phrasing ***TODO Related Links***

← Older revision		Revision as of 17:59, 12 March 2016
Line 1:		Line 1:
			<div style="max-width:62em" >
	==== Definition and Structure ====		==== 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:		You can define and call your own (''user defined'') functions in AviSynth scripts. These are independent blocks of script code that are [[wikipedia:Subroutine\|executed each time a call to the function is made]] in the script. They can return any [[Script_variables\|clip or variable type]]. An example of a simple user defined script function (here a custom ''filter'', ''ie'' a function returning a clip) immediately follows:

	function MuteRange(clip c, int fstart, int fend)		function MuteRange(clip c, int fstart, int fend)
Line 12:		Line 13:
	}		}

	User defined script functions start with the keyword <tt>function</tt> followed by the function name. The name of a script function follows the same naming rules as [[Script_variables\|script variables]].		User defined script functions start with the keyword <tt>function</tt>, followed by the function ''name''. The name of a script function follows the same naming rules as [[Script_variables\|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's~~ [[Script_variables\|type]] may be any of those supported by the scripting language.		Immediately after the name, the function's [[Grammar#Functions.2C_Filters_and_Arguments\|''argument list'']] follows. The list (which can be empty) consists of (expected argument's type - argument's name) pairs. Argument [[Script_variables\|type]] may be any of those supported by the scripting language.

	function MuteRange(clip c, int fstart, int fend)		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 <tt>{ ... }</tt>.		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 <tt>{ ... }</tt>.

	{		{
Line 28:		Line 29:
	}		}

	(For simplicity, this code assumes the function will only be called with fstart > 0 and fend < c.Framecount-1. A more complete version would also handle the special cases fstart=0 and fend=c.Framecount-1.)		For simplicity, this code assumes the function will only be called with fstart>0 and fend<c.Framecount-1. A more complete version would also handle the special cases fstart=0 and fend=c.Framecount-1.

	At the end of the function body a <tt>return</tt> statement which ~~returns~~ the ~~final~~ value ~~calculated from the arguments and the function's body code is placed~~.		At the end of the function body, a <tt>return</tt> statement is placed, which sets the return value.

	return [[AudioDub]](c, audio)		return [[AudioDub]](c, audio)
Line 38:		Line 39:
	[[AudioDub]](c, audio)		[[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)~~.		It should be noted that unlike other languages, where multiple return statements are allowed inside the function body, AviSynth functions contain a ''single'' return statement. This is because the language does not support loops or branching in the normal sense, although there are ways around this – see [[Control_structures\|Control structures]] for more.

	==== Facts about user defined script functions ====		==== Facts about user defined script functions ====
Line 46:		Line 47:
	* Although not recommended practice, an argument type may be omitted, and will default to <tt>val</tt>, the generic type.		* Although not recommended practice, an argument type may be omitted, and will default to <tt>val</tt>, the generic type.

	* If the function expects a video clip as its first argument, and that argument is not supplied, then the clip in the special <tt>~~last~~</tt> variable will be used.		* If the function expects a video clip as its first argument, and that argument is not supplied, then the clip in the special <tt>Last</tt> 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:		* 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:
	*# All subsequent arguments in the argument list must be ~~made~~ named also.		*# All subsequent arguments in the argument list must be named also.
	*# '''A named argument is an optional argument''', that is, it need not be supplied by the caller.		*# '''A named argument is an optional argument''', that is, it need not be supplied by the caller.
	*# When a function is called, any optional argument which has ''not'' been provided is set to a value which has the void ('undefined') type. This does not mean that its value is random garbage - simply that its type is neither clip, int, float, bool or string and so it has ''no'' usable value.		*# When a function is called, any optional argument which has ''not'' been provided is set to a value which has the void ('undefined') type. This does not mean that its value is random garbage - simply that its type is neither clip, int, float, bool or string and so it has ''no'' usable value.
	*# Normally, you should use the [[Internal_functions/Boolean_functions\|Defined]] function to test if an optional argument has an explicit value, or the [[Internal_functions/Control_functions\|Default]] function, which combines the Defined test with the ~~delivery~~ of a default value if appropriate.		*# Normally, you should use the [[Internal_functions/Boolean_functions\|Defined]] function to test if an optional argument has an explicit value, or the [[Internal_functions/Control_functions\|Default]] function, which combines the Defined test with the setting of a default value if appropriate.
	*# A void ('undefined') value can be passed on to another function as one of its optional arguments. This is useful when you want to write a wrapper function that calls another function, preserving the same defaults.		*# A void ('undefined') value can be passed on to another function as one of its optional arguments. This is useful when you want to write a wrapper function that calls another function, preserving the same defaults.

Line 59:		Line 60:
	* 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 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 themselves''. The latter is known as recursion and is a very useful technique for creating functions that can accomplish complex tasks.		* Functions can call other functions, ''including themselves''. The latter is known as ''recursion'' and is a very useful technique for creating functions that can accomplish complex tasks. See [[Control_structures\|Control structures]] for more.

	* 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 <tt>myvar</tt> by assigning to it a value, then you cannot read the global <tt>myvar</tt> anymore inside this function.		* Local function variables mask [[Script_variables\|global]] ones with the same name inside the function body. For example, if you define in a function a local variable <tt>myvar</tt> by assigning to it a value, then you cannot read the [[Script_variables\|global]] <tt>myvar</tt> anymore inside this function.

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

	* Each function has its own local version of the special variable ''~~last~~''. On entry to a function, ''~~last~~'' is set to a void ('undefined') value.		* Each function has its own local version of the special variable ''Last''. On entry to a function, ''Last'' is set to a void ('undefined') value.

	==== Related Links ====		==== Related Links ====

	* [[Shared_functions\|Shared functions]]~~. An~~ ever growing collection of shared script functions created by the members of the AviSynth community.		* [[Shared_functions\|Shared functions]] – an ever growing collection of shared script functions created by the members of the AviSynth community.
	:~~<nowiki>{TEMP~~: ~~http://www~~.~~avisynth.org/ShareFunctions}</nowiki>~~		* [[:Category:Scripts]] – even more scripts.
	* [[~~Shared_functions/Conditional\|Conditional filters and script functions~~]]~~. A collection of highly useful conditional filters implemented as user defined script functions.~~
	: <nowiki>~~{TEMP:~~ http://www.avisynth.org/ExportingSingleImage, http://www.avisynth.org/HowToApplyFilterToManySingleFrames :: Perhaps make decent functions from the last two?}</~~nowiki~~>		[[TODO]]
			:<nowiki>http://www.avisynth.org/ExportingSingleImage</nowiki>
			:<nowiki>http://www.avisynth.org/HowToApplyFilterToManySingleFrames</nowiki>
			:''Perhaps make decent functions from the last two?''

			</div>

	----		----

Admin: 1 revision

2013-05-09T21:33:33Z

1 revision

New page

==== 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]](before, current.[[BlankClip]], after, 3)
return [[AudioDub]](c, audio)
}

User defined script functions start with the keyword <tt>function</tt> followed by the function name. The name of a script function follows the same naming rules as [[Script_variables|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's [[Script_variables|type]] may be any of those supported by the scripting language.

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 <tt>{ ... }</tt>.

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

(For simplicity, this code assumes the function will only be called with fstart > 0 and fend < c.Framecount-1. A more complete version would also handle the special cases fstart=0 and fend=c.Framecount-1.)

At the end of the function body a <tt>return</tt> statement which returns the final value calculated from the arguments and the function's body code is placed.

return [[AudioDub]](c, audio)

As a shorthand, a bare expression as the final statement is treated as if the keyword '''return''' was present. Thus, we could also have written simply

[[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).

==== 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).

* Although not recommended practice, an argument type may be omitted, and will default to <tt>val</tt>, the generic type.

* If the function expects a video clip as its first argument, and that argument is not supplied, then the clip in the special <tt>last</tt> 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:
*# All subsequent arguments in the argument list must be made named also.
*# '''A named argument is an optional argument''', that is, it need not be supplied by the caller.
*# When a function is called, any optional argument which has ''not'' been provided is set to a value which has the void ('undefined') type. This does not mean that its value is random garbage - simply that its type is neither clip, int, float, bool or string and so it has ''no'' usable value.
*# Normally, you should use the [[Internal_functions/Boolean_functions|Defined]] function to test if an optional argument has an explicit value, or the [[Internal_functions/Control_functions|Default]] function, which combines the Defined test with the delivery of a default value if appropriate.
*# A void ('undefined') value can be passed on to another function as one of its optional arguments. This is useful when you want to write a wrapper function that calls another function, preserving the same defaults.

* If a function body has no (explicit or implicit) return, a void value (ie a value of the 'undefined' type) is returned.

* 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 themselves''. The latter 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 <tt>myvar</tt> by assigning to it a value, then you cannot read the global <tt>myvar</tt> anymore inside this function.

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

* Each function has its own local version of the special variable ''last''. On entry to a function, ''last'' is set to a void ('undefined') value.

==== Related Links ====

* [[Shared_functions|Shared functions]]. An ever growing collection of shared script functions created by the members of the AviSynth community.
:<nowiki>{TEMP: http://www.avisynth.org/ShareFunctions}</nowiki>
* [[Shared_functions/Conditional|Conditional filters and script functions]]. A collection of highly useful conditional filters implemented as user defined script functions.
: <nowiki>{TEMP: http://www.avisynth.org/ExportingSingleImage, http://www.avisynth.org/HowToApplyFilterToManySingleFrames :: Perhaps make decent functions from the last two?}</nowiki>

----
Back to [[AviSynth Syntax]].

[[Category:AviSynth_Syntax]]
[[Category:Scripting_Basics]]