Custom Effects & Generators

Labs features are experimental and unsupported, but we welcome bug reports and feedback to continue improving Lightform Creator.

Generative content is a vital part of the Lightform experience.

Your Lightform device and Lightform Creator software run this content as shaders - little pieces of code that run directly on a GPU and are optimized for parallel execution.

Shaders in Lightform Creator come in two flavors - effects and generators. Effects utilize the Lightform device's scan data (colors, disparity, normals, edges, and distance to edges) to create context-aware graphics. On the other hand, generators don't use any of the scan data and are purely procedurally generated. They'll be projected in the same way regardless of what the user is projecting onto. For simplicity in this documentation, we will refer to both as effects, as the development differs by minor details.

Lightform effects are based on a modified version of the Interactive Shader Format (ISF) specification, with extra features for accessing Lightform specific features.

File Structure

An effect package contains three files that are loaded by Lightform Creator:

  • [effect name].liteffect - Contains a metadata description of the effect inputs and controls.
  • [effect name].fs - Shader code executed to generate the effect.
  • [effect name].liteffect.gif - Effect preview image, shown in the Lightform Creator asset preview panel.

Details about these files can be found in the Lightform Effect Specification.

Importing Effects into Creator

Custom effects require Lightform Labs to be enabled. Click Help > Enable Labs.

  1. Create an effect package by placing the three required files into a folder
  2. Import your effects into your project, by dragging the effects .liteffect file into Creator
  3. The Project Assets panel will open and direct you to where the file needs to be dropped

    drag_custom_effect.gif

Now the effect will be available to insert into Surfaces and publish to your device like any other effect. Creator will automatically reload effects if they change on disk, which will refresh any existing surfaces with the effects and update the properties panel with any changes. This allows for quick iteration and visual feedback of your changes as you construct the effect.

Please Note: Importing an effect only makes it available in the current project. If you would like to share a custom effect between multiple projects, you will need to drag and drop it into each project.

Effect Errors

If you have a syntax error in either your .liteffect or .fs file, an error panel will pop up on the left side of Lightform Creator.

customEffects_error_1x.png

Please Note: The errors produced are hardware-dependent and could be confusing or have the wrong line numbers. Sometimes effects will successfully compile on a Windows PC but fail on a Mac, or fail when run Live on your Lightform device. At this time, we do not display the errors produced when you publish a Live effect. One standard error is missing decimal points on floating-point errors (i.e., using 1 instead of 1. or 1.0)

Modifying existing effects

If you wish to modify or hack the effects that come with Creator, you can extract them from the included asset library zip file:

<Asset Library Location>/Lightform-Built_In-3_0_0.zip/effects

  • On Windows this is typically:
    C:/Program Files/Lightform/Lightform Creator/Lightform-Build_In-3_0_0.zip
  • On Mac OSX this is typically:
    Applications/Lightform.app/Contents/Resources/Lightform-Build_In-3_0_0.zip
    Go to your Applications in Finder and right-click Lightform > Show Package Contents. You should then see the Contents folder.

Open this zip file and extract the effects folder to your workspace. This will make a copy of the effects that are included with Lightform, and from here you can make your own modifications to them without modifying the originals. If you drag these effects into Lightform, your local copy of the effects will show up under "Project Assets" in the Asset Browser, with the unmodified originals in "Built-In Assets".

Looping Effects

For visually coherent effects looping slides, you need to ensure that the math in your shader loops properly. You can use the include ISF variables TIME and SLIDE_LENGTH along with various math tricks to accomplish this. Your shader should produce the exact same image when TIME == 0.0 and TIME == SLIDE_LENGTH, here are a few examples:

Ping Pong

// Creates a value that goes back and forth between -1 and 1 
float var1 = sin(TWO_PI*(TIME/SLIDE_LENGTH));

// Modifying the phase and frequency
float Freq; // Integer value
float Phase; // Constant value
float var2 = sin(Freq*TWO_PI*(TIME/SLIDE_LENGTH) + Phase);

Wrapping

// Percentage of slide completed, equal to 0.0
float var3 = fract(time/SLIDE_LENGTH);

Importing Effects from Shadertoy

Shadertoy is a website designed to help people build and share fragment shaders. Their shader spec is very similar to ISF and Lightform, although there are a few differences to be aware of, which will be covered below.

There are a few key syntax differences between shaders written on Shadertoy and shaders written with the ISF/Lightform spec. Here's a list of the most important ones:

ShaderToy Conversions

Variable/Function

Shadertoy

Lightform/ISF

pixel coordinates

fragCoord gl_FragCoord
color output fragColor gl_FragColor
window size iResolution RENDERSIZE
time iTime TIME
sampling image/texture texture() IMG_NORM_PIXEL()
shader main function void mainImage(out vec4 fragColor, in vec2 fragCoord) void main() 

 You can also use this website by Magic Music Visuals to convert a Shadertoy into ISF.

Shadertoy Licensing - Unless a Shadertoy specifies the license explicitly, it falls under the default Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License, which restricts the usage of derivative works and how they must attribute the original.

Generators vs. Effects

The difference between generators and effects can be mostly ignored, but there are a few small differences in the values of gl_FragCoord and RENDERSIZE that might be important:

Name

Generator

Effect

 gl_FragCoord.xy  Pixel coordinate in surface Pixel coordinate in artboard
 RENDERSIZE.xy  Dimensions of surface  Dimensions of artboard

In general, converting to uv this way works for both effects and generators:

void main()
{
vec2 uv = gl_FragCoord.xy / RENDERSIZE.xy;
...
}
Was this article helpful?
3 out of 5 found this helpful

Sign in to make a suggestion to improve this article

  • Comment actions Permalink
    Avatar
    Gerngross Glowinski

    Is this source from an old Version? How can i access the effects in 1.12.7?

    <Asset Library Location>/Lightform-Built_In-3_0_0.zip/effects

    • On Mac OSX this is typically:
      Applications/Lightform.app/Contents/Resources
  • Comment actions Permalink
    Avatar
    Anum

    Hi Gerngross Glowinski, if you are on a Mac, go to your Applications in Finder and right-click Lightform > Show Package Contents. You should then see the Contents folder.

  • Comment actions Permalink
    Avatar
    Gerngross Glowinski

    I didn't know that was a thing. It worked, thanks a lot!