Custom Effects & Generators

labs-icon.pngLightform Labs Feature

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.

  1. File Structure
  2. Importing Effects into Creator
  3. Effect Errors
  4. Modifying Existing Effects
  5. Looping Effects
  6. Importing Effects from Shadertoy
  7. Generators vs. Effects

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 (optional) - 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 files.

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

  • On Windows this is typically:
    C:/Program Files/Lightform/Lightform Creator
  • On Mac OSX this is typically:
    Applications/Lightform.app/Contents/Resources

This will make a copy of the effects, and you can import them into your project as described above. The original version will not be modified.


Looping Effects

For visually coherent effects when on a that is being looped, 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 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?
2 out of 2 found this helpful

Sign in to make a suggestion to improve this article