Shader graphs (pyzed.shading)

pyzed.shading is the node-based shader system behind the designer’s Shader view: .pzshad graphs of nodes that compile to the WGSL of pz.shader. See Shader graphs for a tour.

from pyzed import shading

fire = shading.load("shaders/fire.pzshad")
fire["speed"] = 2.0                       # a mutable variable: no recompiling
pz.shader(fire, width=320, height=200)    # or pz.shader("shaders/fire.pzshad")

Using shaders

load

load(path, *, fresh=False)

The Shader of a .pzshad file, cached by path (fresh=True reads it again). It reloads by itself when the file changes.

Shader

class Shader

A shader graph ready to draw, with its own values for the variables: shader["speed"] = 2, shader.set(...), shader.variables, shader.wgsl and shader.widget(...). pz.shader takes one directly.

widget

widget(source, **options)

A pz.shader widget for a .pzshad path, a Graph or a Shader.

Building graphs

Graph

class Graph

A shader graph: variables, nodes and the links between them. Call a node type on it to add one (g.noise(scale=4), g.sin(x)), pick outputs with node["name"] and combine them with arithmetic. save, compile, arrange, connect and the variable methods edit it.

new

new(name='shader')

A new graph with UV feeding a gradient into the Output node: the designer’s Blank template.

load_graph

load_graph(path)

The Graph of a .pzshad file, to edit it.

Variable

@dataclass
class Variable(name, type='float', value=None, mutable=True, min=None, max=None, step=None, description='')

A variable of a shader: name, type (float, int, bool, vec2, vec3, vec4, color, texture), value, mutable (a uniform) or constant, min, max, step and description.

Node

@dataclass
class Node(id, type, x=0.0, y=0.0, inputs={}, params={}, title='', preview=True)

A node of a graph: its type, position, inputs (fixed values of unconnected inputs), params (settings), title and whether its preview shows.

NodeRef

class NodeRef

What Graph.add returns: ref["port"] is an output to wire elsewhere; arithmetic uses its first output.

GraphError

class GraphError

Raised for wires that can’t connect (types, cycles), unknown node types and bad variable names.

Compiling

compile

compile(graph, target=None, *, values=None)

Compiles a graph (or one node’s output, for its preview) to WGSL: the Compiled code, uniforms, textures and problems by node.

Compiled

@dataclass
class Compiled(code, uniforms={}, textures={}, names={}, errors={}, lines={}, uses_time=False)

The result of compile: code, uniforms, textures, names (the uniform of each variable), errors by node id, uses_time, and check(), which runs the GPU compiler and puts its messages on the node that wrote the line.

The node catalog

register

register(node_type, *, preset=True)

Adds a node type of your own to the catalog (and the designer’s Shading sidebar).

NodeType

@dataclass
class NodeType(id, title, category, description, inputs=(), outputs=(), params=(), exprs={}, functions=(), min_type='bool', build=None, ports=None, resolve=None, label=None, icon='', keywords='')

A node type: id, title, category, inputs, outputs, settings and how it writes its WGSL.

Preset

@dataclass
class Preset(type, title, category, description, params={}, keywords='')

An entry of the Shading sidebar: a node type with some settings (func:sin is the Function node set to sin).