# Shader graphs (pyzed.shading)

> API reference for pyzed.shading: load .pzshad shader graphs, change their variables, and build node graphs in code that compile to the WGSL of pz.shader.

Source: https://albakore.github.io/pyzed/reference/shading/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

`pyzed.shading` is the node-based shader system behind the designer's
[Shader view](https://albakore.github.io/pyzed/shading/shader-designer/): `.pzshad` graphs of nodes that compile to the WGSL of
[`pz.shader`](https://albakore.github.io/pyzed/reference/widgets/). See [Shader graphs](https://albakore.github.io/pyzed/shading/shader-graphs/) for a tour.

```python
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`

```python
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`

```python
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`

```python
widget(source, **options)
```

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

## Building graphs

### `Graph`

```python
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`

```python
new(name='shader')
```

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

### `load_graph`

```python
load_graph(path)
```

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

### `Variable`

```python
@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`

```python
@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`

```python
class NodeRef
```

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

### `GraphError`

```python
class GraphError
```

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

## Compiling

### `compile`

```python
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`

```python
@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`

```python
register(node_type, *, preset=True)
```

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

### `NodeType`

```python
@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`

```python
@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).