The Map Script component lets you specify a custom program in a computer language (a 'script') that generates an image based on user-defined inputs which are queried by the script. Essentially, it allows you to program your own image generation and image processing components with custom inputs and internal logic. Map Script is a map component, it can be located in the Advanced category on the Components Bar. You can also write curve scripts – for details, see Curve Script.
Scripts in Filter Forge are written in Lua. Filter Forge help does not include information on the Lua language itself – please refer to the Lua online manual at http://www.lua.org/manual/5.3/.
For beginner-level tutorials on scripting, see Getting Started with Scripting. For information on what functions and variables are available to scripts, see Scripting API.
Inputs Tab
The Inputs tab shows the inputs of the currently selected Map Script component and allows you to configure them – you can add new inputs, rename or delete existing ones, change their sorting order and other properties using the Input Editor. Values of these user-added inputs can be queried by the script – for details, see Referencing Inputs from Scripts.
Script Tab
The Script tab contains the following elements:
- Script editor – Lets you enter and modify the Lua script for the currently selected Map Script component.
- Settings button – Opens the Script Settings dialog allowing you to change script settings for the currently selected Map Script component.
- Apply Changes button – Lets you 'commit' the changes you made when editing the script in the script editor. Filter Forge doesn't execute scripts every time you change them – you need to manually notify Filter Forge that you have changed the script. When you click the Apply Changes button (or press Ctrl⌘+Enter) Filter Forge executes the script and re-renders all previews in the Filter Editor.
Script errors are shown in the Message Log panel that pops up when a script error occurs. You can quickly locate the component and the script line it occurred at by double-clicking the error message. To help you locate errors, the line and column under the cursor are displayed in the Line/Column Indicator at the bottom.
Writing Map Scripts
In order to execute successfully, a Map Script component must implement the following functions:
prepare()
This function is called once per rendering session, immediately before the rendering session begins. It allows you to perform precalculations that would be too expensive to perform within get_sample(), which is called at least once per pixel. The function accepts no arguments and returns no values. While this function is required by Filter Forge, you may leave its implementation empty so it does nothing.
When doing precalculations or querying inputs within the prepare() function, make sure you store the results in variables and tables that aren't declared as local, otherwise you won't be able to access their values from script's get_sample() function described below.
Some of the inputs, such as Checkboxes or Integer Sliders, must be queried the prepare() function only, they can't be queried from get_sample(). For a full list of inputs that must be queried from prepare(), see Referencing Inputs from Scripts.
r, g, b, a, aazone = get_sample(x, y)
The get_sample() function of the script provides the image generation code. It is called by Filter Forge whenever an 'upstream' component (i.e. the component the current Map Script component is connected to) or a renderer requests a sample. Filter Forge uses a sample-based approach to image generation. Scripts don't produce images by painting their pixels directly. Instead, Filter Forge 'asks' them "What color does your image have at coordinates x and y?" by calling their get_sample() function, which 'replies' by returning an RGBA color. For more information, see Filter Forge's Sample-Based Architecture.
- r, g, b and a(return values) – The RGBA channels of the color at the sample coordinates x and y in the image generated by the script, represented as floating-point numbers. The base range for RGBA values in Filter Forge is 0…1, but HDR colors can exceed that range both in positive and negative directions. If you want to return HDR colors from the script, make sure you have a corresponding flag turned on in Script Settings.
- aazone (return value, optional) – The anti-aliasing zone (or AA Zone) value, represented as an integer number. AA Zones are used in Filter Forge's smart anti-aliasing algorithm – they identify solid-colored or smooth areas in script's output that don't need anti-aliasing in their interior but need anti-aliasing on their edges. For detailed information about AA Zones, see Implementing Smart Anti-Aliasing.
- x and y – The sample coordinates, represented as floating-point numbers. In Filter Forge, a point with the coordinates of 0, 0 corresponds to the top-left corner of the image, and a point with the coordinates of 1, 1 corresponds to the bottom-right corner of the square Size x Size pixels wide, where Size is the current value of the global Size slider. For more information on Filter Forge's coordinate system and sampling in general, see Filter Forge's Sample-Based Architecture.
Referencing Inputs from the Script
Filter Forge scripts can query inputs added by the user via the Input Editor dialog. Non-mapped inputs such as Checkboxes or Integer Sliders must be queried from script's prepare() function, while mappable inputs such as Color Map, Grayscale Map and Curve must be sampled from script's get_sample() function. For details, see Referencing Inputs from Scripts.
Script Settings
The Script Settings dialog (accessible via the Settings button below the script editing area on the Script tab) lets you modify flags and other settings for the currently selected script component. Script settings are stored per component, not globally for all script components – a filter can have two components, one of which is unsafe and the other safe.
You will need these settings when you're making an unsafe script, i.e. a non-sandboxed script that can access all Lua functions, or a script that makes use of Filter Forge's global variables such as VARIATION, SIZE, or SEAMLESS (see Scripting API for details.) Some of the variables are not available to the script unless a corresponding flag is turned on. For details, see Script Settings.
