FragmentColor for Python

FragmentColor is a universal GPU abstraction for Rust, JavaScript, Python, Swift, and Kotlin. This package is the Python binding, built with PyO3.

This README is specific to the PyPI package. For Rust usage, see the repository README.md. For JavaScript, see platforms/web/README.md in the repository.

• Documentation: https://fragmentcolor.org/welcome
• API Reference: https://fragmentcolor.org/api

Install

pip install fragmentcolor rendercanvas glfw

NumPy installs with the package as a required dependency. TextureTarget.get_image() returns its pixels as a NumPy array of shape (height, width, 4), and Renderer.create_texture accepts one as input.

Quick start

from fragmentcolor import Renderer, Shader, Pass
from rendercanvas.auto import RenderCanvas, loop

# Initializes a renderer and a target compatible with the given canvas
canvas = RenderCanvas(size=(800, 600))
renderer = Renderer()
target = renderer.create_target(canvas)

# You can pass the shader as a source string, a file path, a registry slug,
# or an https URL pointing at a .wgsl file.
circle = Shader("./path/to/circle.wgsl")
triangle = Shader("https://fragmentcolor.org/shaders/sdf2d/circle.wgsl")
shader = Shader("""
struct VertexOutput {
    @builtin(position) coords: vec4<f32>,
}

struct MyStruct {
    my_field: vec3<f32>,
}

@group(0) @binding(0)
var<uniform> my_struct: MyStruct;

@group(0) @binding(1)
var<uniform> my_vec2: vec2<f32>;

@vertex
fn vs_main(@builtin(vertex_index) in_vertex_index: u32) -> VertexOutput {
    const vertices = array(
        vec2( -1., -1.),
        vec2(  3., -1.),
        vec2( -1.,  3.)
    );
    return VertexOutput(vec4<f32>(vertices[in_vertex_index], 0.0, 1.0));
}

@fragment
fn fs_main() -> @location(0) vec4<f32> {
    return vec4<f32>(my_struct.my_field, 1.0);
}
""")

# The library binds and updates the uniforms automatically
shader.set("my_struct.my_field", [0.1, 0.8, 0.9])
shader.set("my_vec2", [1.0, 1.0])

# One shader is all you need to render
renderer.render(shader, target)

# But you can also combine multiple shaders in a render Pass
rpass = Pass("single pass")
rpass.add_shader(circle)
rpass.add_shader(triangle)
rpass.add_shader(shader)
renderer.render(rpass, target)

# Finally, you can render a list of passes in order. No extra type needed.
passes = [rpass, Pass("GUI pass")]
renderer.render(passes, target)

# To animate, simply update the uniforms in a loop
@canvas.request_draw
def animate():
    circle.set("position", [0.0, 0.0])
    renderer.render(passes, target)

loop.run()

Python binding (local dev)

# Quick run helper: build wheel into dist/, create venv, and run an example
./fc run_py main      # or: ./fc run_py multiobject | ./fc run_py headless

# Manual alternative
pipx install maturin
maturin develop
pip install glfw rendercanvas
python examples/python/main.py

Documentation & website

• Docs source of truth lives in docs/api and is referenced from code via #[lsp_doc].
• Examples on method pages are sliced from the healthcheck scripts; no filesystem reads in docs.
• Doc examples follow async + pollster patterns on the Rust side and are converted to Python automatically.

Platform support

Platform support is aligned with upstream wgpu:

✅ = First Class Support
🆗 = Downlevel/Best Effort Support
📐 = Requires the ANGLE translation layer (GL ES 3.0 only)
🌋 = Requires the MoltenVK translation layer

Limitations (planned features)

• See the ROADMAP and CHANGELOG on the repository for planned features and known limitations.

Note on generation: this README.md is generated from README.tpl.md (same directory) and the repository README.md examples by the build script. Do not edit the generated README.md directly.