Help, Usage & FAQ

Exporting to Three.js

1. Save your shader

You cannot export a shader until it is saved to the server. You must also be logged in.

2. Download your shader

Click on the "Export to Three.js button" to download the compiled shader file. This is what you will load in your application using the below runtime.

3. Add the ShaderFrog runtime library to your application

See the instructions on the ShaderFrog Runtime Github Repository. You need to include the script in your Three.js scene HTML file:

<script src="shaderfrog-runtime.min.js"></script>

4. Load, assign and configure your shader

See the instructions on the ShaderFrog Runtime Github Repository, and check out the example to see the code in action.

"Shader Error" on composed shaders

Unfortunately, ShaderFrog has some edge cases where certain combinations of shaders result in invalid source code. If you see this error, one of the shaders you added to the composition list is incompatible with another one. Unfortunately, the only way to fix it is to remove the offending shader by trial and error. These errors are tracked, so eventually it will get fixed or get a more descriptive error message. You can also file an issue about which combinations errored.

My shader disappears!

For basic (non-composed) shaders, you should see an error in the gutter of the editor explaining your syntax error, as in the below example:

For composed shaders, there is a known issue where certain combinations of mulitplier values for input shaders will cause the object to disappear. This is because the additions of the two gl_FragCoords produces an invalid position, often when using negative multiplier values. You can fix it by experimenting with the multiplier sliders until your object reappears.

If your object has disappeared while editing shader code and it doesn't fit either case above, please file an issue.

Questions Answered

How does ShaderFrog compose shaders?

At its core, ShaderFrog uses an open source GLSL parser / compiler written by Cimaron Shanahan. When composing shaders, ShaderFrog uses the parser to analyze the source code of input shaders. It parses two or more input shaders to find things like conflicting variable names, then compiles the shaders together into a third shader and sends the new source code to WebGL for rendering.

Is there a graph editor?

At this time, ShaderFrog works by taking multiple input shaders and adding their outputs together. In this sense, the heirarchy of shaders is flat, and the output is addative. Order doesn't matter. Since ShaderFrog parses entire shaders, there is no immediate need for graph nodes.

That isn't to say ShaderFrog will never have a graph editor. There are (at least) two important cases which may eventually warrant a graph editor. The first is a normal map. To achieve this effect correctly, it must be multiplied by the rest of the output, not added. One potential way to solve this is to let users specify that their basic shader, when combined, should be multiplied. Another way could be a graph editor

The other important case is making one shader the input to another. For example, a ripple shader works by reading UV coordinates of an image offset by the calculated ripple. If you combine this outright with another shader, it won't have the desired effect. The desired effect would be achived by making the ripple shader modify the UVs that the other shader reads from. This could be accomplished with a shader graph where you replace an image input with another shader, essentially making one shader an "input" to another.

How are lights handled?

Currently if you want your object to be lit, you have to compose in a light shader (such as Phong Light) and manually manage the light position uniforms in your application. This isn't ideal, and there's a discussion on how to make lights a seamless process with Three.js and potentially other publishing targets (like Unity). Your feedback is welcomed.

How does ShaderFrog differ from showcases many shaders that don't apply to 3d objects in the same way as ShaderFrog. A Shadertoy shader would be the equivalent of taking a ShaderFrog shader, putting it on a plane, and making the plane full screen. The Shadertoy shaders use a technique called "ray marching" so the shader knows how to draw an entire 3d scene on the plane, much like a movie projector showing a 3d scene on a 2d canvas.

ShaderFrog shaders are designed to be mapped to 3d objects to create reusable effects in a 3d scene with multiple objects, not just a full-screen plane. Shadertoy shaders can be likened to paintings: They are beautiful and complex, but not always practical. ShaderFrog shaders are more like building blocks: reusable and componentized.

Does ShaderFrog only support Three.js?

For the moment, the ShaderFrog workflow only supports Three.js scenes using the ShaderFrog Runtime library. However, ShaderFrog exports raw GLSL code, so there is nothing theoretically preventing the shaders from being used in any WebGL application. You can view an example JSON export to see the format. Warning: this format is volatile and likely to change.

Additionally, ShaderFrog uses an internal parser/compiler combination, which theoretically could cross-compile GLSL shaders to multiple platforms (iOS, DirectX, etc). This is not currently supported.

Is ShaderFrog open source?

No. ShaderFrog may one day include the ability to buy and sell shaders through a store model, and deal with monetary transactions. For security and business purposes, the source code for is not open source. The ShaderFrog Runtime that you include in your Three.js scenes is open source, and you should file issues there.

Where can I file ideas, suggestions, bugs?

Please use the open source ShaderFrog Runtime Github repository issue tracker for any ShaderFrog discussions.

Where can I get more help?

The creator of the project is active in the #three.js IRC channel. It's a good place to start. You can also use any of the Contact options.