pyvvisf Documentation

Welcome to the documentation for pyvvisf!

About

pyvvisf is a Python library for working with ISF shaders and rendering.

Getting Started

Install pyvvisf with pip:

pip install pyvvisf

For development installation:

git clone https://github.com/jimcortez/pyvvisf.git
cd pyvvisf
pip install -e .

Quick Start

Here’s a minimal example using a well-formed ISF shader:

from pyvvisf import ISFRenderer

# A simple ISF shader (every pixel is the selected color)
test_shader = """
/*{
    \"DESCRIPTION\": \"Every pixel is the selected color.\",
    \"CREDIT\": \"pyvvisf example\",
    \"ISFVSN\": \"2.0\",
    \"CATEGORIES\": [\"Generator\"],
    \"INPUTS\": [
        {\"NAME\": \"color\", \"TYPE\": \"color\", \"DEFAULT\": [1.0, 0.0, 0.0, 1.0]}
    ]
}*/
void main() {
    gl_FragColor = color;
}
"""

with ISFRenderer(test_shader) as renderer:
    # Render with the default color (red)
    buffer = renderer.render(512, 512)
    image = buffer.to_pil_image()
    image.save("output_red.png")

    # Render with a custom color (green)
    renderer.set_input("color", (0.0, 1.0, 0.0, 1.0))
    buffer = renderer.render(512, 512)
    image = buffer.to_pil_image()
    image.save("output_green.png")

GLSL Version Support

pyvvisf supports multiple GLSL versions and can automatically detect which versions are supported on your system:

from pyvvisf import get_supported_glsl_versions, ISFRenderer

# Check which GLSL versions are supported
supported_versions = get_supported_glsl_versions()
print(f"Supported GLSL versions: {supported_versions}")

# Create renderer with specific GLSL version
renderer = ISFRenderer(shader_content, glsl_version='330')

The default GLSL version is ‘330’, but you can specify any supported version. The library will automatically test shader compilation to ensure compatibility.

Examples

See the examples/ directory for complete examples:

isf_renderer_demo.py: Render ISF shaders to images, set inputs, and save output.
isf_window_demo.py: Render ISF shaders in a window (interactive display).
time_offset_demo.py: Render shaders at different time offsets (for animation or frame capture).

Shader examples are in examples/shaders/:

simple_color_change.fs: Single color input, fills the screen with the selected color.
simple_color_animation.fs: Fades between two user-selected colors over time.
shapes.fs: Animated shapes (moving circle, rotating rectangle, pulsating ring).
simple.fs: Minimal shader, fills the screen with blue.

Setting Shader Inputs

You can set shader inputs using plain Python primitives:

int, float, bool
list or tuple (for colors and points)

You can set a single input with set_input(), or set multiple inputs at once with set_inputs():

Examples:

renderer.set_input("scale", 1.0)  # float
renderer.set_input("color", [1.0, 0.0, 0.0, 1.0])  # RGBA color as list
renderer.set_input("point", (0.5, 0.5))  # point2D as tuple
renderer.set_input("flag", False)  # boolean

# Set multiple inputs at once
renderer.set_inputs({
    "color": [0.0, 1.0, 0.0, 1.0],
    "scale": 0.5,
    "flag": True
})

The set_inputs() method is a convenience function that takes a dictionary of input names and values, and calls set_input() for each one. This is useful for updating several shader parameters in a single call.

You do not need to use ISFColor, ISFPoint2D, or other ISF value classes directly.

ISF Features

pyvvisf supports the full ISF 2.0 specification including:

Multi-pass rendering: Shaders with multiple render passes
ISF imports: Support for imported textures and shaders
ISF special functions: IMG_THIS_PIXEL, IMG_PIXEL, IMG_SIZE, etc.
ISF sampling functions: VVSAMPLER_2DBYPIXEL, VVSAMPLER_2DBYNORM
Modern GLSL: Support for GLSL 330+ with proper ISF 2.0 compatibility

Value Types

These types help you specify shader inputs in a structured way (optional, primitives are preferred):

ISFColor: RGBA color value
ISFPoint2D: 2D point value
ISFFloat: Floating-point value
ISFInt: Integer value
ISFBool: Boolean value

Error Handling

All rendering errors raise exceptions derived from pyvvisf.errors.ISFError. For example:

from pyvvisf import ISFRenderer, errors

try:
    with ISFRenderer("") as renderer:  # Empty shader will fail
        renderer.render()
except errors.ISFError as e:
    print(f"Rendering failed: {e}")

Development

To install development dependencies and run tests:

pip install -e ".[dev]"
pytest