How to Manually Convert from Shadertoy.com to SSF - Syn Tutorial

Summary

This tutorial walks through the process of manually porting a shader from ShaderToy to Synesthesia, focusing on replacing ShaderToy-specific uniforms with Synesthesia equivalents. Key steps include adjusting time, resolution, and pixel coordinates, as well as handling audio reactivity and texture imports. The tutorial also covers troubleshooting common errors, such as undefined variables, and provides insights on working with Synesthesia's control system and limitations. It concludes with a reminder about respecting the licensing of ShaderToy shaders, especially for commercial use, and highlights potential challenges like replacing cube maps and handling mouse/keyboard controls.

Takeaways

• 😀 Always check the license of ShaderToy shaders before using them in commercial work, as many are non-commercial by default.
• 😀 The main task when porting shaders from ShaderToy to Synesthesia is replacing ShaderToy-specific inputs like `iTime` and `iResolution` with Synesthesia equivalents.
• 😀 Synesthesia uses `renderSize` for `iResolution` and `rTime` (uppercase) for `iTime`. Always refer to Synesthesia's shader documentation for uniform equivalents.
• 😀 The main function in ShaderToy is called `mainImage`, whereas in Synesthesia, it's `renderMain`. This requires function renaming when porting.
• 😀 Synesthesia uses `fragColor` as the output color, which must be returned in the `renderMain` function, unlike ShaderToy's `mainImage` that sets `fragColor`.
• 😀 Compilation errors are normal during porting. Pay close attention to undefined variables and replace them systematically (e.g., replacing `iTime` with `time`).
• 😀 Synesthesia does not support integer types (`int`) or `ivex` types. If a ShaderToy shader uses `iframe` (an integer), it should be replaced with `frameCount` (a float) in Synesthesia.
• 😀 Textures in ShaderToy are often accessed via `iChannels`, but in Synesthesia, you can import images manually. The automatic importer can handle some cases.
• 😀 Synesthesia does not support cube maps, commonly used in ShaderToy for 3D reflections. You must replace them with 2D textures and simulate 3D behavior mathematically.
• 😀 ShaderToy's audio-reactive shaders rely on texture-based methods, but Synesthesia has its own audio-reactive uniforms like `sinTime` that should replace ShaderToy's approach.
• 😀 Synesthesia does not support mouse or keyboard input in the same way as ShaderToy. Replace input handling with Synesthesia’s XY pads, toggles, or bangs for interactivity.

Q & A

What is the primary purpose of this tutorial?

The primary purpose of the tutorial is to guide users through the process of manually porting a shader from ShaderToy to Synesthesia, highlighting key differences in syntax and uniform variables between the two platforms.

Why might someone need to manually port a shader from ShaderToy to Synesthesia?

Manual porting may be necessary if the automatic importer doesn’t work for a particular shader, or if the shader isn't listed in Synesthesia's database. Additionally, some shaders may require customization beyond what the automatic importer can handle.

What are the common ShaderToy uniforms that need to be replaced when porting a shader to Synesthesia?

Common ShaderToy uniforms like `iTime` and `iResolution` need to be replaced with Synesthesia's equivalents, such as `time` and `render_size`. These variables control time-based effects and the resolution of the rendering canvas.

What should you do if you encounter compilation errors after pasting the shader code into Synesthesia?

After pasting the shader code, if you encounter compilation errors, you should identify and fix issues like undefined variables (e.g., `fragColor`, `iTime`) and mismatched uniforms. Pay attention to error messages, and make necessary replacements (e.g., `iTime` to `time`).

What is the role of `fragColor` in a shader, and why must it be defined in Synesthesia?

`fragColor` represents the final color output of each pixel in a shader. In Synesthesia, you must explicitly define `fragColor` (e.g., setting it to black initially) because Synesthesia does not automatically define this like ShaderToy does in its shaders.

How does Synesthesia handle audio reactivity differently than ShaderToy?

ShaderToy uses texture lookups (e.g., `iChannel0` with audio data) for audio reactivity, whereas Synesthesia uses specific audio-reactive uniforms like `sinTime` and `synHiHits`. This requires replacing ShaderToy's audio texture lookups with Synesthesia's audio-reactive variables.

What happens if you try to use `iframe` (integer frame count) directly in Synesthesia?

Synesthesia does not support integer types like `iframe`. If you use `iframe` directly, Synesthesia will likely throw an error due to type mismatches. To resolve this, you should wrap the `frame_count` in an `int` type if an integer is required for certain operations.

How does Synesthesia handle textures, and what challenges arise when porting textures from ShaderToy?

Synesthesia allows users to import 2D images manually, but it doesn't support built-in ShaderToy texture channels like `iChannel0` or cube maps. When porting, you may need to manually import the images or rely on Synesthesia's automatic importer to fetch the textures if available.

What should you do if a ShaderToy shader uses a cube map?

Synesthesia doesn't support cube maps, so you must replace them with 2D textures. You'll need to adjust the shader code by replacing the 3D texture lookup with a 2D texture lookup and perform additional calculations to simulate the 3D effect.

What are the recommended controls to use for mouse and keyboard interactions when porting from ShaderToy to Synesthesia?

Since Synesthesia doesn’t support mouse or keyboard inputs in the same way as ShaderToy, you should replace these with Synesthesia’s `xyPad` for mouse input and use toggles or bangs for click actions and other interactive elements.

Why is it important to check the license of a ShaderToy shader before using it in commercial projects?

It’s important to check the shader's license because many ShaderToy shaders are released under non-commercial licenses by default. Using them in commercial projects without permission from the artist or an appropriate license could result in legal issues.

Can you automatically import ShaderToy shaders into Synesthesia without needing to make manual adjustments?

In some cases, Synesthesia’s automatic importer can successfully convert a ShaderToy shader, including texture imports. However, if the automatic importer doesn't work or if advanced features (like cube maps or audio reactivity) are involved, manual adjustments may still be required.