General

-> Note: For executables see Pyaket's FAQ

Q: Crashes on exporting videos¶

-> Using scene main --no-turbo (...) or scene.main(turbo=False) might fix it.

ShaderFlow uses an auxiliary library called TurboPipe (from the same author) to speed up data transfers to FFmpeg (video encoder) by offloading it to a fast, multithreaded C++ code.

While no known pattern has been found on why it happens, it is believed to be related with hybrid systems or the lack of driver support for the CPU to directly read from a mapped buffer; perhaps even a bug in TurboPipe itself with lifetimes and garbage collection. Please ensure the package is using the right primary gpu, as muxing/ownership can cause issues too.

However, the vast majority of systems have no issues with it, so it's currently opt-out.

Note: Disabling turbopipe can make exporting up to 50% slower if you've got the cpu headroom for it.

Q: Only pixel shaders?¶

ShaderFlow does not aim to support vertex data or complex OpenGL features, only but one thing and doing it well: Rendering a fullscreen rectangle with a pixel shader, similar to shadertoy.

This is not a limitation, nor implies 3D scenes aren't possible - in fact, they tend to look much better and interesting than traditional rasterization by using Ray Marching techniques.

-> For a practical example, check out the ⭐️ DepthFlow project!

Note: For such work, you're better off using Blender or Godot, which are Open Source and awesome!

Q: Extension GL_* is required¶

Not all drivers and hardware are made equal - depending on your functions and features used, particular combinations of software and hardware might not support the shader altogether.

A practical example is a function that returns a sampler2D:

// Metaprogrammed to get the nth layer from uniforms
sampler2D iScreenGet(int layer) {
    if (layer == 0) return iScreen0;
    if (layer == 1) return iScreen1;
    if (layer == 2) return iScreen2;
    if (layer == 3) return iScreen3;
    return iScreen0; // Fallback
}

This function fails for Windows AMD GPU with GL_ARB_bindless_texture is required and macOS; adding a request for it fixes for Windows but is completely unsupported in macOS.

A workaround for this example case is to rethink the function:

vec4 iScreenGet(int layer, vec2 uv) {
    if (layer == 0) return texture(iScreen0, uv);
    if (layer == 1) return texture(iScreen1, uv);
    if (layer == 2) return texture(iScreen2, uv);
    if (layer == 3) return texture(iScreen3, uv);
    return texture(iScreen0, uv);
}