We do not recommend using Labs for installations or productions where dependability is required. These features are experimental and unsupported.
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.
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.
- Create an effect package by placing the three required files into a folder
- Import your effects into your project, by dragging the effects .liteffect file into Creator
- The Project Assets panel will open and direct you to where the file needs to be dropped
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.
- Community Resources - You can find a growing number of converted effects and generators in a shared folder here, which is maintained by a member of the Lightform User Group. These effects were originally created by members of the Shadertoy and ISF shader community websites, and are subject to either a free-use licensing, or in some cases fall under an Attribution-NonCommercial-ShareAlike agreement.
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.
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.
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-Built_In-4_0_0.zip
- On Mac OSX this is typically:
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".
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
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:
// 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);
// 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:
|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
RENDERSIZE that might be important:
|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:
vec2 uv = gl_FragCoord.xy / RENDERSIZE.xy;