Runtime environment - Revision history

Pinterf: /* How to script inside the runtime environment */ Add avs+ function_objects

2021-02-11T07:43:07Z

‎How to script inside the runtime environment: Add avs+ function_objects

Raffriff42: max-width, heading levels

2016-03-12T19:42:53Z

max-width, heading levels

Raffriff42: /* Special runtime variables and functions */ list some runtime functions for example

2015-12-30T23:26:57Z

‎Special runtime variables and functions: list some runtime functions for example

Admin: 1 revision

2013-05-09T21:33:34Z

1 revision

Gavino: /* Runtime filters */ fix a couple of inaccuracies

2009-09-22T23:43:53Z

‎Runtime filters: fix a couple of inaccuracies

New page

== Definition ==

The runtime environment is an extension to the normal AviSynth script execution environment that is available to scripts executed by [[#Runtime filters|runtime filters]]. Its basic characteristic is that the runtime filters' scripts are evaluated (executed) '''at every frame'''. This allows for complex video processing that it would be difficult or impossible to perform in a normal AviSynth script.

Let's now look at the above definition in more detail. The runtime environment is:

# An environment, that is a set of available local and global variables and filters / functions to be used by the script.
# An extension to the normal AviSynth script execution environment; that is there are additional variables and functions available to runtime scripts.
# Available to scripts executed by runtime filters '''only''', that is scripts inside it are executed only during the AviSynth "runtime" (the frame serving phase).

The last is the biggest difference. Normal script code is parsed and evaluated (executed) at the start of the script's [[The_script_execution_model/Sequence_of_events|execution]] (the parsing phase) in a linear fashion, from top to bottom; the result is the creation of a [[The_script_execution_model/The_filter_graph|filter graph]] that is used by AviSynth to serve frames to the host video application. Runtime script code is executed ''after'' the parsing phase, when frames are served. Moreover it is executed on every frame requested and only for that specific frame, in an event-driven fashion.

'''Note:''' Audio is ''not'' handled by the runtime environment; it is passed through untouched. This also means that you cannot modify clip audio with runtime filters.

== Runtime filters ==

The following [[Internal_filters|filters]] are the basic set of the so-called "runtime filters":

* [[ConditionalFilter]]: Selects, on every frame, from one of two (provided) clips based on the evaluation of a condition.
* [[ScriptClip]]: Executes arbitrary script code on every frame and returns a clip.
* [[FrameEvaluate]]: Executes arbitrary script code on every frame but the script's output is ignored.
* [[ConditionalReader]]: Loads input from an external file to a selectable [[Script_variables|variable]] on every frame.

In addition, the [[WriteFile]] filter can also be considered a runtime filter, because it sets the special variables set by all runtime filters before evaluating the expressions passed to it, which can use the special runtime [[Internal_functions/Runtime_functions|functions]].

== Special runtime variables and functions ==

All runtime filters set and make available to runtime scripts the following special variables.

* {{Term|last}}: The clip passed as argument to the filter
* {{Term|current_frame}}: The frame number (ranging from zero to input clip's [[Clip_properties|Framecount]] minus one) of the requested frame.

All the above variables are defined at the [[The_script_execution_model/Scope_and_lifetime_of_variables|top-level script local scope]]. That is you read and write to them in a runtime script as if they where variables that you declare at the script level.

Runtime scripts can also call a rich set of [[Internal_functions/Runtime_functions|special functions]] that provide various pieces of information for the current frame of their input clip.

== How to script inside the runtime environment ==

Using the runtime environment is simple: you use one of the [[#Runtime_filters|runtime filters]] and supply it with the needed arguments. Among them, two are the most important:

* The input clip
* The runtime script

The latter is supplied as a string argument which contains the AviSynth script commands. Scripts can contain many statements (you can use a multiline string), local and global variables and function calls, as well as special runtime [[Internal_functions/Runtime_functions|functions]] and [[#Special_runtime_variables_and_functions|variables]]. In general all statements of the AviSynth [[AviSynth_Syntax|syntax]] are permitted, but attention must be paid to avoid overly complex scripts because this has a penalty on speed that is paid at '''every frame'''. See the runtime section of [[Scripting_reference|scripting reference]]'s [[The_script_execution_model/Performance_considerations|performance considerations]] for details.

Lets see a few examples:

TODO...EXAMPLES

----

Other points:

* [[Internal_functions/Runtime_functions|Runtime functions]] and variables, such as current_frame, AverageLuma(), etc., are available only at the runtime script's scope. To use them in a function you must pass them as arguments.
* You can include an explicit <tt>return</tt> statement in your runtime script to return a clip that is not contained in the special <tt>last</tt> variable.

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

← Older revision		Revision as of 07:43, 11 February 2021
Line 46:		Line 46:

	The latter is supplied as a string argument which contains the AviSynth script commands. Scripts can contain many statements (you can use a multiline string), local and global variables and function calls, as well as special runtime [[Internal_functions/Runtime_functions\|functions]] and [[#Special_runtime_variables_and_functions\|variables]]. In general all statements of the AviSynth [[AviSynth_Syntax\|syntax]] are permitted, but attention must be paid to avoid overly complex scripts because this has a penalty on speed that is paid at '''every frame'''. See the runtime section of [[Scripting_reference\|scripting reference]]'s [[The_script_execution_model/Performance_considerations\|performance considerations]] for details.		The latter is supplied as a string argument which contains the AviSynth script commands. Scripts can contain many statements (you can use a multiline string), local and global variables and function calls, as well as special runtime [[Internal_functions/Runtime_functions\|functions]] and [[#Special_runtime_variables_and_functions\|variables]]. In general all statements of the AviSynth [[AviSynth_Syntax\|syntax]] are permitted, but attention must be paid to avoid overly complex scripts because this has a penalty on speed that is paid at '''every frame'''. See the runtime section of [[Scripting_reference\|scripting reference]]'s [[The_script_execution_model/Performance_considerations\|performance considerations]] for details.
		+
		+	{{AvsPluscon}}In Avisynth+ runtime filters can accept function objects as well, where in the classic syntax a stringified script would appear.
		+	* The input clip
		+	* The function object. See [[Function_objects]]
		+	* Capture variables (part of function object syntax).
		+	In this or Script is not an assembled string but a prewritten function, either inline or separately written.
		+
	</div>		</div>

@@ Line 1: / Line 1: @@
-== Definition ==
+==== Definition ====
+<div style="max-width:62em" >
 The runtime environment is an extension to the normal AviSynth script execution environment that is available to scripts executed by [[#Runtime filters|runtime filters]]. Its basic characteristic is that the runtime filters' scripts are evaluated (executed) '''at every frame'''. This allows for complex video processing that it would be difficult or impossible to perform in a normal AviSynth script.
@@ Line 12: / Line 12: @@
 '''Note:''' Audio is ''not'' handled by the runtime environment; it is passed through untouched. This also means that you cannot modify clip audio with runtime filters.
-== Runtime filters ==
+==== Runtime filters ====
+<div style="max-width:62em" >
 The following [[Internal_filters|filters]] are the basic set of the so-called "runtime filters":
@@ Line 23: / Line 24: @@
 In addition, the [[WriteFile]] filter can also be considered a runtime filter, because it sets the special variables set by all runtime filters before evaluating the expressions passed to it, which can use the special runtime [[Internal_functions/Runtime_functions|functions]].
-== Special runtime variables and functions ==
+==== Special runtime variables and functions ====
+<div style="max-width:62em" >
 All runtime filters set and make available to runtime scripts the following special variables.
@@ Line 34: / Line 36: @@
 Runtime scripts can also call a rich set of [[Internal_functions/Runtime_functions|runtime functions]] that provide various pieces of information for the current frame of their input clip - for example, <tt>AverageLuma</tt>, <tt>YDifferenceFromPrevious</tt>, <tt>YPlaneMin</tt> and <tt>YPlaneMinMaxDifference</tt>.
-== How to script inside the runtime environment ==
+==== How to script inside the runtime environment ====
+<div style="max-width:62em" >
 Using the runtime environment is simple: you use one of the [[#Runtime_filters|runtime filters]] and supply it with the needed arguments. Among them, two are the most important:
@@ Line 43: / Line 46: @@
 The latter is supplied as a string argument which contains the AviSynth script commands. Scripts can contain many statements (you can use a multiline string), local and global variables and function calls, as well as special runtime [[Internal_functions/Runtime_functions|functions]] and [[#Special_runtime_variables_and_functions|variables]]. In general all statements of the AviSynth [[AviSynth_Syntax|syntax]] are permitted, but attention must be paid to avoid overly complex scripts because this has a penalty on speed that is paid at '''every frame'''. See the runtime section of [[Scripting_reference|scripting reference]]'s [[The_script_execution_model/Performance_considerations|performance considerations]] for details.
-Lets see a few examples:
+==== Examples ====
+<div style="max-width:62em" >
- TODO...EXAMPLES
+[[TODO]]
+</div>
-----
-−
-Other points:
 * [[Internal_functions/Runtime_functions|Runtime functions]] and variables, such as current_frame, AverageLuma(), etc., are available only at the runtime script's scope. To use them in a function you must pass them as arguments.
 * You can include an explicit <tt>return</tt> statement in your runtime script to return a clip that is  not contained in the special <tt>last</tt> variable.
 [[Category:AviSynth_Syntax]]
 [[Category:Scripting_Basics]]

@@ Line 33: / Line 33: @@
 All the above variables are defined at the [[The_script_execution_model/Scope_and_lifetime_of_variables|top-level script local scope]]. That is you read and write to them in a runtime script as if they where variables that you declare at the script level.
-Runtime scripts can also call a rich set of [[Internal_functions/Runtime_functions|special functions]] that provide various pieces of information for the current frame of their input clip.
+Runtime scripts can also call a rich set of [[Internal_functions/Runtime_functions|runtime functions]] that provide various pieces of information for the current frame of their input clip - for example, <tt>AverageLuma</tt>, <tt>YDifferenceFromPrevious</tt>, <tt>YPlaneMin</tt> and <tt>YPlaneMinMaxDifference</tt>.
 == How to script inside the runtime environment ==