Scripting API

This article describes what functions and variables are available to scripts in the Map Script and Curve Script components. All Filter Forge API functions (but not variables) are syntax-highlighted with orange in the script editor.

Availability of Standard Lua Libraries

Safe scripts (that is, scripts that have the Unsafe Script setting turned off in their Script Settings) are allowed to call Lua functions from the following standard Lua libraries:

• String library.
• Table library.
• Math library. Note that math.random() and math.randomseed() functions cannot be called from script's get_sample() function, they can be called from prepare() only. This restriction applies to both safe and unsafe scripts.
• Basic library, excluding the Coroutine library and dofile(), getfenv(), getmetatable(), load(), loadfile(), loadstring(), pcall(), rawequal(), rawget(), rawset(), setfenv(), setmetatable() and xpcall() functions.

Unsafe scripts are allowed to call all Lua functions from all standard Lua libraries.

API Variables

The scripts in Filter Forge can employ several global variables that let you query the value of the global Size and Variation sliders, the width and height of the working image and more. When referencing these variables from scripts, remember that Lua is case-sensitive, so the variable names must be written in uppercase, as shown in the list:

• SIZE – the value of the global Size slider. Available only to scripts that have the Makes use of the global Size setting flag turned on in their Script Settings. Measured in pixels, but can assume non-integer values.
• VARIATION – the value of the global Variation slider. Available only to scripts that have the Makes use of the global Variation setting flag turned on in their Script Settings.
• OUTPUT_WIDTH and OUTPUT_HEIGHT – width and height of the image currently loaded into Filter Forge. Measured in pixels.
• SEAMLESS_REGION_WIDTH and SEAMLESS_REGION_HEIGHT – width and height of the seamless region, i.e. the region in which the script must provide seamlessly-tiled output. Available only to scripts that have the Produces seamlessly-tiled results flag turned on in their Script Settings. Both variables are measured as a ratio to SIZE. For example, if SIZE is 300 pixels and the seamless region width is 450 pixels, the SEAMLESS_REGION_WIDTH variable will assume the value of 1.5.
• SEAMLESS – the state of the global Seamless Tiling checkbox, either true or false. Available only to scripts that have the "Produces seamlessly-tiled results" flag turned on in their Script Settings.

API Functions for Referencing Custom Inputs

Filter Forge provides functions allowing you to query values of custom inputs added to a Map Script or Curve Script component via the Input Editor. Each input type (e.g. Slider, Checkbox etc.) has a corresponding query function. For information on input types and their corresponding functions, see Referencing Inputs from Scripts.

API Functions for Smart Anti-Aliasing

Filter Forge provides a combine_aa_zones() function that simplifies the process of combining anti-aliasing zones. For more information on this function and on handling anti-aliasing in scripts in general, see Implementing Smart Anti-Aliasing.

API Functions for Noises

Filter Forge provides a get_noise() and a set_noise_seed() functions that help implement any graphic algorithm that requires randomness. For more information on these functions and on using noise generation in scripts in general, see Noise API.

API Functions for Blending Modes

Filter Forge provides several blending functions like blend_normal(), blend_multiply() etc that help implement blending scripts. For more information on these functions and on using blending modes in scripts, see Blending Modes API.

Writing to the Message Log

You can use the standard Lua error() function to write error messages to the Message Log. Note that calling this function terminates the script. Currently, there are no other ways to send messages to the Message Log without interrupting the script.