Login - Create Account

Lua Scripting

This is possibly the biggest improvement Filter Forge 2.0 has to offer – now you can execute your own code right in Filter Forge!

Lua Scipt in Filter Forge

Scripts in Filter Forge 2.0 are written in Lua, a blazing-fast scripting language held by numerous developers as a number one choice for embedded scripting. When you battle orcs in World of Warcraft or blast aliens in Crysis, you are executing Lua code – Blizzard Entertainment and Crytek have chosen Lua as the scripting language for their best-selling games. Lua is no stranger to the graphics world as well – it is used as a scripting language in the leading photography workflow application, Adobe Lightroom, and in GIMP, a free open-source competitor to Photoshop.

Scripting is available via two dedicated components, Map Script and Curve Script  which basically allow you to implement your own components with custom inputs and internal logic. A filter can contain any number of script components which can have different scripts and can be freely mixed with 'normal' Filter Forge components:

Filter Editor with script components mixed with normal components

Example #1: Wolfenst… er… Bearestroika!

Bearestroika.ffxml

Looks familiar? No wonder – this filter is based on a raycasting game engine pioneered by Wolfenstein 3D, the game that gave birth to the genre of first-person shooters. We even contacted John Carmack, the tech guru behind Wolfenstein, Doom and Quake, for permission to use the brown-shirted Nazi soldier texture in our example. We knew that unlike the game source code the textures are still copyrighted, but the idea was just too cool to pass up. John replied that he would give us the permission, but now that id Software is a part of Zenimax, he is not the final authority on this anymore. The issue wasn't worth pestering Zenimax lawyers, so we dropped the Nazis and went with Stalin's Elite Zombie Bears:

Bearestroika!

When we were working on scripting, it occurred to us that scripts provide a crude way of embedding basically any binary data into Filter Forge filters – you just create an array, initialize it with constants and provide a way to access this array via Filter Forge's sampling functions! We can't say that we like this particular way of implementing embedding, but the genie is out of the bottle anyway, and to contain it we would have to remove scripting altogether. If you can't beat it, embrace it – the Bearestroika example uses this approach for storing bear and lamp textures inside the filter:

Bear script

Example #2: Raytracing

Raytracing.ffxml

This filter implements a simple but functional raytracing-based renderer. In fact, Filter Forge's sampling architecture is very close to raytracers – we also shoot 'rays' into the 'scene', but unlike raytracers where rays extend from a single origin point representing viewer's eye, Filter Forge's 'rays' (called samples) are parallel, and Filter Forge's 'scene' is simply an infinite procedurally textured view-aligned plane while a raytracer can use polygons and procedural geometry. Despite these differences, it was very easy to adapt Filter Forge's sampling approach to raytracing:

Raytracer Room

Another highlight of this script is the way it implements smart anti-aliasing – object edges are anti-aliased, while their interior is not, except when it is textured using 'normal' Filter Forge components which may add their own anti-aliasing edges. Note that even reflections and refractions handle anti-aliasing correctly. Here's what you see when you turn on AA Edges display in the new Filter > Anti-Aliasing > Show Diagnostics menu – white lines represent anti-aliased pixels:

Raytracer's AA Edges

Example #3: Mandelbrot Fractal

MandelbrotFractal.ffxml

Bad news: we didn't implement fractals in Filter Forge 2.0. Good news? You will do this! Here's proof of concept – this filter implements a Mandelbrot fractal in about 20 lines of Lua code. Technically, it implements a Julia set and configures it to produce a Mandelbrot fractal:

Mandelbrot Fractal

Example #4: Droste Spiral

DrosteSpiral.ffxml

This filter implements Droste effect, or, more specifically, its more complex spiral variant:

Droste Effect

Example #5: Clock Showing Real-World Time

RealWorldClock.ffxml

This filter isn't much of a beauty, but that's not its point. The point is that the time it shows is the actual real-world time – the filter queries the system clock!

Clock Showing Real-World Time

This is achieved via Unsafe Scripts, a dark art that lets filters access all Lua functions at the expense of not being accepted to our online Filter Library. Normally, Filter Forge scripts are 'sandboxed', that is, they are executed in a restricted environment that doesn't allow them to call potentially dangerous Lua functions such as access to files or OS functions. However, turning the Unsafe Script option on for a script component bypasses this restriction – such scripts can read, write, rename and delete files, execute OS shell commands, access process environment variables, query system date and time and more.

You should be very careful when using filters with unsafe scripts from sources you don't trust. By default, Filter Forge is configured not to run unsafe scripts. Even if you open a filter that contains an unsafe script, Filter Forge won't execute it unless you explicitly enable unsafe script execution in Tools > Options > Scripts. This setting acts as a global safety override – no filter can execute unsafe scripts unless it's enabled:

Script Options

As an additional safety measure, we don't accept filters with unsafe scripts to our Filter Library. When you try to submit such filters via the Submit Wizard, you will get the following error message:

Filters with unsafe scripts cannot be submitted

Why did we add unsafe scripts? Why take all this risk, you might ask? The answer is, because we want to see where you take Filter Forge, what you will do with it. It is always amazing to see what people can come up with if you don't restrict their creative freedom!

Filter Forge's amazing node based editor has been invaluable in giving us the power to create textures that make the most of today's real-time pixel shaders.

Karl Wickens
Visual Effects Lead Artist
Electronic Arts
www.ea.com

See All Testimonials

Get a 75% discount on any edition!
Expires soon!
Buy today – save up to $300!

“I really like Filter Forge, I seem to find new uses for it constantly. The 2.0 upgrade looks great, HDR will be really welcome.”

Jared Martin
3D and Visual Effects Artist
jozvex.cgsociety.org/gallery

“Incredibly powerful texture engine.”

Albert Kiefer
www.kiefer.nl

Follow filterforge on Twitter